ntlm_core(3)

💖 ntlm_core(3) — the Heimdal NTLM library, bestie edition 💖

okay so you found your way into the Heimdal ntlm library manual page and honestly? iconic. this is ntlm_core(3), which means section 3, which means it's a library page, which means we're talking about functions you call, not some command you type into a shell. buckle up. 🎀

---

✨ NAME ✨

ntlm_core — the Heimdal NTLM library 🦋

---

🌸 SYNOPSIS 🌸

🫶 Functions

here's the whole friend group. every single one of them, exactly as they show up in the header, no cap:

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])

the way that there are eighteen of them and they all start with heim_ntlm_... yes. that's the naming convention. it's giving consistency. we love that for us. 💅

---

💜 Detailed Description 💜

so what do all these functions actually do, you ask? here's the vibe:

the NTLM core functions implement:

• the string2key generation function 🔑
• the message encode and decode function ✉️
• and the hash function functions 🧮

that's it. that's the whole scope. keys get made, messages get encoded and decoded, hashes get hashed. main character energy across the board ✨

ngl this page is long — we're splitting it up, so this is part 1. more is coming, don't go anywhere bestie 🫶

💖 Function Documentation 💖

okay bestie, deep breath, this is the big one 🌈 — every single function in this library, one by one, no skipping. Grab a snack 🍓, we're going through all of them.

---

🦋 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 together with its associated session master key. They come as a matching set, like you and your emotional support playlist 🎀.

Parameters

• key — the ntlm v1 key
• len — length of key
• session — the generated session nonce. Free it with heim_ntlm_free_buf() when you're done, bestie, don't just leave it lying around 💀
• master — the calculated session master key. Also freed with heim_ntlm_free_buf().

Returns

0 on success, periodt 🎉. Otherwise you get an error, and it hands you an errno telling you 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)

Same energy as the one above, but NTLMv2 ✨. Generates an NTLMv2 session random with its associated session master key.

Parameters

• key — the NTLMv2 key
• len — length of key
• blob — the NTLMv2 'blob'
• session — the generated session nonce, freed with heim_ntlm_free_buf().
• master — the calculated session master key, freed with heim_ntlm_free_buf().

Returns

0 = success 💅. Not 0 = an error, with an errno for 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)

Calculates the LMv2 response. That's literally it, that's the whole job 🫶.

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

0 on success ✨. Otherwise, an error, and an errno explaining 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)

Calculates the NTLMv1 response hash. Iconic, vintage, we love her 🎀.

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

0 if it slayed ✅. Otherwise an error, with an errno for 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)

Calculates the NTLMv2 response — the glow-up version 🌈.

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

0 on success 🫶. Otherwise an error, plus an errno telling you what happened.

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. Turns that blob back into something you can actually read, no cap.

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

0 on success ✨. Otherwise an error and an errno.

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. The other direction, bestie 🦋.

Parameters

• ti — the ntlm_targetinfo message to encode.
• ucs2 — ignored 🙈 (yes, literally just ignored, don't ask)
• data — is the return buffer with the encoded message, should be freed with heim_ntlm_free_buf().

Returns

0 on success 🎉. Otherwise an error and an errno.

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. Type1 is the little opening line of the convo, main character energy 💅.

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

0 on success ✨. Otherwise an error and an errno.

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. That's the server's reply, the "okay bet" of the exchange 🌸.

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

0 on success 🫶. Otherwise an error and an errno.

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. Type3 is the grand finale, the closing argument 🎀.

Parameters

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

Returns

0 on success ✨. Otherwise an error and an errno.

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. That's it. That's the function. Cleaning up after yourself is self-care, periodt 💖.

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. Bye bestie 👋.

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 an encrypted session, unwrap the session key. It's giving ✨gift-wrapping in reverse✨.

Parameters

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

Returns

0 on success 💅. Otherwise an error, with an errno for what went wrong.

---

🍓 heim_ntlm_nt_key

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

Calculates 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

0 on success 🎉. Otherwise an error and an errno.

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 an NTLMv2 response. It checks three times, like a bestie who needs to hear it three different ways before she believes it 💀.

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

0 on success 🫶. Otherwise an error, with an errno for what went wrong.

Then it does the three checks, in this exact order:

1. First check with the domain as the client passed it to the function.
2. Second check with domain uppercased.
3. Third check with empty domain.

Examples

test_ntlm.c.

---

🎀 Author

Generated automatically by Doxygen for Heimdal ntlm library from the source code.

---

and that's the whole page, bestie 💖 you made it all the way through, I'm so proud of you. This was Heimdal ntlm library version 7.8.0, dated Tue Nov 15 2022 — from me and ntlm_core(3), mwah, go hydrate 🌸💅✨