Heimdal NTLM library

Functions
Heimdal NTLM library

## Functions
void | heim_ntlm_free_buf (struct ntlm_buf *p)
void | heim_ntlm_free_targetinfo (struct ntlm_targetinfo *ti)
int | heim_ntlm_encode_targetinfo (const struct ntlm_targetinfo *ti, int ucs2, struct ntlm_buf *data)
int | heim_ntlm_decode_targetinfo (const struct ntlm_buf *data, int ucs2, struct ntlm_targetinfo *ti)
void | heim_ntlm_free_type1 (struct ntlm_type1 *data)
int | heim_ntlm_encode_type1 (const struct ntlm_type1 *type1, struct ntlm_buf *data)
void | heim_ntlm_free_type2 (struct ntlm_type2 *data)
int | heim_ntlm_encode_type2 (const struct ntlm_type2 *type2, struct ntlm_buf *data)
void | heim_ntlm_free_type3 (struct ntlm_type3 *data)
int | heim_ntlm_encode_type3 (const struct ntlm_type3 *type3, struct ntlm_buf *data, size_t *mic_offset)
int | heim_ntlm_nt_key (const char *password, struct ntlm_buf *key)
int | heim_ntlm_calculate_ntlm1 (void *key, size_t len, unsigned char challenge[8], struct ntlm_buf *answer)
int | heim_ntlm_build_ntlm1_master (void *key, size_t len, struct ntlm_buf *session, struct ntlm_buf *master)
int | heim_ntlm_build_ntlm2_master (void *key, size_t len, struct ntlm_buf *blob, struct ntlm_buf *session, struct ntlm_buf *master)
int | heim_ntlm_keyex_unwrap (struct ntlm_buf *baseKey, struct ntlm_buf *encryptedSession, struct ntlm_buf *session)
int | heim_ntlm_ntlmv2_key (const void *key, size_t len, const char *username, const char *target, int upper_case_target, unsigned char ntlmv2[16])
int | heim_ntlm_calculate_lm2 (const void *key, size_t len, const char *username, const char *target, const unsigned char serverchallenge[8], unsigned char ntlmv2[16], struct ntlm_buf *answer)
int | heim_ntlm_calculate_ntlm2 (const void *key, size_t len, const char *username, const char *target, const unsigned char serverchallenge[8], const struct ntlm_buf *infotarget, unsigned char ntlmv2[16], struct ntlm_buf *answer)
int | heim_ntlm_verify_ntlm2 (const void *key, size_t len, const char *username, const char *target, time_t now, const unsigned char serverchallenge[8], const struct ntlm_buf *answer, struct ntlm_buf *infotarget, unsigned char ntlmv2[16])

## Detailed Description

The NTLM core functions implement the string2key generation function, message encode and decode function, and the hash function functions.

## Function Documentation

## ◆ heim_ntlm_build_ntlm1_master()

int heim_ntlm_build_ntlm1_master | ( | void * | key,
|  | size_t | len,
|  | struct ntlm_buf * | session,
|  | struct ntlm_buf * | master
| ) |  |

Generates an NTLMv1 session random with assosited session master key.

Parameters

  key | the ntlm v1 key
  len | length of key
  session | generated session nonce, should be freed with heim_ntlm_free_buf().
  master | calculated session master key, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

## ◆ heim_ntlm_build_ntlm2_master()

int heim_ntlm_build_ntlm2_master | ( | void * | key,
|  | size_t | len,
|  | struct ntlm_buf * | blob,
|  | struct ntlm_buf * | session,
|  | struct ntlm_buf * | master
| ) |  |

Generates an NTLMv2 session random with associated session master key.

Parameters

  key | the NTLMv2 key
  len | length of key
  blob | the NTLMv2 "blob"
  session | generated session nonce, should be freed with heim_ntlm_free_buf().
  master | calculated session master key, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

## ◆ heim_ntlm_calculate_lm2()

int heim_ntlm_calculate_lm2 | ( | const void * | key,
|  | size_t | len,
|  | const char * | username,
|  | const char * | target,
|  | const unsigned char | serverchallenge[8],
|  | unsigned char | ntlmv2[16],
|  | struct ntlm_buf * | answer
| ) |  |

Calculate LMv2 response

Parameters

  key | the ntlm key
  len | length of key
  username | name of the user, as sent in the message, assumed to be in UTF8.
  target | the name of the target, assumed to be in UTF8.
  serverchallenge | challenge as sent by the server in the type2 message.
  ntlmv2 | calculated session key
  answer | ntlm response answer, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

## ◆ heim_ntlm_calculate_ntlm1()

int heim_ntlm_calculate_ntlm1 | ( | void * | key,
|  | size_t | len,
|  | unsigned char | challenge[8],
|  | struct ntlm_buf * | answer
| ) |  |

Calculate NTLMv1 response hash

Parameters

  key | the ntlm v1 key
  len | length of key
  challenge | sent by the server
  answer | calculated answer, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_calculate_ntlm2()

int heim_ntlm_calculate_ntlm2 | ( | const void * | key,
|  | size_t | len,
|  | const char * | username,
|  | const char * | target,
|  | const unsigned char | serverchallenge[8],
|  | const struct ntlm_buf * | infotarget,
|  | unsigned char | ntlmv2[16],
|  | struct ntlm_buf * | answer
| ) |  |

Calculate NTLMv2 response

Parameters

  key | the ntlm key
  len | length of key
  username | name of the user, as sent in the message, assumed to be in UTF8.
  target | the name of the target, assumed to be in UTF8.
  serverchallenge | challenge as sent by the server in the type2 message.
  infotarget | infotarget as sent by the server in the type2 message.
  ntlmv2 | calculated session key
  answer | ntlm response answer, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_decode_targetinfo()

int heim_ntlm_decode_targetinfo | ( | const struct ntlm_buf * | data,
|  | int | ucs2,
|  | struct ntlm_targetinfo * | ti
| ) |  |

Decodes an NTLM targetinfo message

Parameters

  data | input data buffer with the encode NTLM targetinfo message
  ucs2 | if the strings should be encoded with ucs2 (selected by flag in message).
  ti | the decoded target info, should be freed with heim_ntlm_free_targetinfo().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_encode_targetinfo()

int heim_ntlm_encode_targetinfo | ( | const struct ntlm_targetinfo * | ti,
|  | int | ucs2,
|  | struct ntlm_buf * | data
| ) |  |

Encodes a ntlm_targetinfo message.

Parameters

  ti | the ntlm_targetinfo message to encode.
  ucs2 | ignored
  data | is the return buffer with the encoded message, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_encode_type1()

int heim_ntlm_encode_type1 | ( | const struct ntlm_type1 * | type1,
|  | struct ntlm_buf * | data
| ) |  |

Encodes an ntlm_type1 message.

Parameters

  type1 | the ntlm_type1 message to encode.
  data | is the return buffer with the encoded message, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_encode_type2()

int heim_ntlm_encode_type2 | ( | const struct ntlm_type2 * | type2,
|  | struct ntlm_buf * | data
| ) |  |

Encodes an ntlm_type2 message.

Parameters

  type2 | the ntlm_type2 message to encode.
  data | is the return buffer with the encoded message, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_encode_type3()

int heim_ntlm_encode_type3 | ( | const struct ntlm_type3 * | type3,
|  | struct ntlm_buf * | data,
|  | size_t * | mic_offset
| ) |  |

Encodes an ntlm_type3 message.

Parameters

  | type3 | the ntlm_type3 message to encode.
  | data | is the return buffer with the encoded message, should be
  [out] | mic_offset | offset of message integrity code freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_free_buf()

void heim_ntlm_free_buf | ( | struct ntlm_buf * | p | ) |

heim_ntlm_free_buf frees the ntlm buffer

Parameters

  p | buffer to be freed

Examples
  test_ntlm.c.

## ◆ heim_ntlm_free_targetinfo()

void heim_ntlm_free_targetinfo | ( | struct ntlm_targetinfo * | ti | ) |

Frees the ntlm_targetinfo message

Parameters

  ti | targetinfo to be freed

Examples
  test_ntlm.c.

## ◆ heim_ntlm_free_type1()

void heim_ntlm_free_type1 | ( | struct ntlm_type1 * | data | ) |

Frees the ntlm_type1 message

Parameters

  data | message to be freed

Examples
  test_ntlm.c.

## ◆ heim_ntlm_free_type2()

void heim_ntlm_free_type2 | ( | struct ntlm_type2 * | data | ) |

Frees the ntlm_type2 message

Parameters

  data | message to be freed

Examples
  test_ntlm.c.

## ◆ heim_ntlm_free_type3()

void heim_ntlm_free_type3 | ( | struct ntlm_type3 * | data | ) |

Frees the ntlm_type3 message

Parameters

  data | message to be freed

Examples
  test_ntlm.c.

## ◆ heim_ntlm_keyex_unwrap()

int heim_ntlm_keyex_unwrap | ( | struct ntlm_buf * | baseKey,
|  | struct ntlm_buf * | encryptedSession,
|  | struct ntlm_buf * | session
| ) |  |

Given a key and encrypted session, unwrap the session key

Parameters

  baseKey | the sessionBaseKey
  encryptedSession | encrypted session, type3.session field.
  session | generated session nonce, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

## ◆ heim_ntlm_nt_key()

int heim_ntlm_nt_key | ( | const char * | password,
|  | struct ntlm_buf * | key
| ) |  |

Calculate the NTLM key, the password is assumed to be in UTF8.

Parameters

  password | password to calcute the key for.
  key | calcuted key, should be freed with heim_ntlm_free_buf().

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

Examples
  test_ntlm.c.

## ◆ heim_ntlm_ntlmv2_key()

int heim_ntlm_ntlmv2_key | ( | const void * | key,
|  | size_t | len,
|  | const char * | username,
|  | const char * | target,
|  | int | upper_case_target,
|  | unsigned char | ntlmv2[16]
| ) |  |

Generates an NTLMv2 session key.

Parameters

  key | the ntlm key
  len | length of key
  username | name of the user, as sent in the message, assumed to be in UTF8.
  target | the name of the target, assumed to be in UTF8.
  upper_case_target | upper case the target, should not be used only for legacy systems
  ntlmv2 | the ntlmv2 session key

Returns
  0 on success, or an error code on failure.

## ◆ heim_ntlm_verify_ntlm2()

int heim_ntlm_verify_ntlm2 | ( | const void * | key,
|  | size_t | len,
|  | const char * | username,
|  | const char * | target,
|  | time_t | now,
|  | const unsigned char | serverchallenge[8],
|  | const struct ntlm_buf * | answer,
|  | struct ntlm_buf * | infotarget,
|  | unsigned char | ntlmv2[16]
| ) |  |

Verify NTLMv2 response.

Parameters

  key | the ntlm key
  len | length of key
  username | name of the user, as sent in the message, assumed to be in UTF8.
  target | the name of the target, assumed to be in UTF8.
  now | the time now (0 if the library should pick it up itself)
  serverchallenge | challenge as sent by the server in the type2 message.
  answer | ntlm response answer, should be freed with heim_ntlm_free_buf().
  infotarget | infotarget as sent by the server in the type2 message.
  ntlmv2 | calculated session key

Returns
  In case of success 0 is return, an errors, a errno in what went wrong.

First check with the domain as the client passed it to the function.

Second check with domain uppercased.

Third check with empty domain.

Examples
  test_ntlm.c.