ntlm.h File Reference

NT LAN Manager (NTLM) authentication. More...

#include <stdint.h>
#include <ipxe/crypto.h>
#include <ipxe/md5.h>

Go to the source code of this file.

Data Structures
struct	ntlm_header
	A message header. More...
struct	ntlm_version
	A version descriptor. More...
struct	ntlm_nonce
	A nonce. More...
struct	ntlm_data
	A variable-length data descriptor. More...
struct	ntlm_negotiate
	A Negotiate message. More...
struct	ntlm_challenge
	A Challenge message. More...
struct	ntlm_authenticate
	An Authenticate message. More...
struct	ntlm_lm_response
	A LAN Manager response. More...
struct	ntlm_nt_response
	An NT response. More...
struct	ntlm_challenge_info
	NTLM challenge information. More...
struct	ntlm_key
	An NTLM verification key. More...

Macros
#define	NTLM_MAGIC   { 'N', 'T', 'L', 'M', 'S', 'S', 'P', '\0' }
	Magic signature.
#define	NTLM_VERSION_NTLMV2   0x01
	NTLM version.

Enumerations
enum	ntlm_type { NTLM_NEGOTIATE = 0x00000001UL , NTLM_CHALLENGE = 0x00000002UL , NTLM_AUTHENTICATE = 0x00000003UL }
	Message types. More...
enum	ntlm_flags {   NTLM_NEGOTIATE_KEY_EXCH = 0x20000000UL , NTLM_NEGOTIATE_EXTENDED_SESSIONSECURITY = 0x00080000UL , NTLM_NEGOTIATE_ALWAYS_SIGN = 0x00008000UL , NTLM_NEGOTIATE_NTLM = 0x00000200UL ,   NTLM_REQUEST_TARGET = 0x00000004UL , NTLM_NEGOTIATE_UNICODE = 0x00000001UL }
	Negotiation flags. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
	FILE_SECBOOT (PERMITTED)
int	ntlm_challenge (struct ntlm_challenge *challenge, size_t len, struct ntlm_challenge_info *info)
	Parse NTLM Challenge.
void	ntlm_key (const char *domain, const char *username, const char *password, struct ntlm_key *key)
	Calculate NTLM verification key.
void	ntlm_response (struct ntlm_challenge_info *info, struct ntlm_key *key, struct ntlm_nonce *nonce, struct ntlm_lm_response *lm, struct ntlm_nt_response *nt)
	Construct NTLM responses.
size_t	ntlm_authenticate (struct ntlm_challenge_info *info, const char *domain, const char *username, const char *workstation, struct ntlm_lm_response *lm, struct ntlm_nt_response *nt, struct ntlm_authenticate *auth)
	Construct NTLM Authenticate message.
size_t	ntlm_authenticate_len (struct ntlm_challenge_info *info, const char *domain, const char *username, const char *workstation)
	Calculate NTLM Authenticate message length.

Variables
const struct ntlm_negotiate	ntlm_negotiate
	Negotiate message.

Detailed Description

NT LAN Manager (NTLM) authentication.

Definition in file ntlm.h.

Macro Definition Documentation

NTLM_MAGIC

#define NTLM_MAGIC   { 'N', 'T', 'L', 'M', 'S', 'S', 'P', '\0' }

Magic signature.

Definition at line 26 of file ntlm.h.

NTLM_VERSION_NTLMV2

#define NTLM_VERSION_NTLMV2   0x01

NTLM version.

Definition at line 163 of file ntlm.h.

Referenced by ntlm_response().

Enumeration Type Documentation

ntlm_type

enum ntlm_type

Message types.

Enumerator
NTLM_NEGOTIATE	Negotiate message type.
NTLM_CHALLENGE	Challenge message type.
NTLM_AUTHENTICATE	Authenticate message.

Definition at line 29 of file ntlm.h.

               {
        /** Negotiate message type */
        NTLM_NEGOTIATE = 0x00000001UL,
        /** Challenge message type */
        NTLM_CHALLENGE = 0x00000002UL,
        /** Authenticate message */
        NTLM_AUTHENTICATE = 0x00000003UL,
};

ntlm_flags

enum ntlm_flags

Negotiation flags.

Enumerator
NTLM_NEGOTIATE_KEY_EXCH	Negotiate key exchange.
NTLM_NEGOTIATE_EXTENDED_SESSIONSECURITY	Negotiate extended security.
NTLM_NEGOTIATE_ALWAYS_SIGN	Negotiate always sign.
NTLM_NEGOTIATE_NTLM	Negotiate NTLM key.
NTLM_REQUEST_TARGET	Request target name and information.
NTLM_NEGOTIATE_UNICODE	Negotiate Unicode character encoding.

Definition at line 39 of file ntlm.h.

                {
        /** Negotiate key exchange */
        NTLM_NEGOTIATE_KEY_EXCH = 0x20000000UL,
        /** Negotiate extended security */
        NTLM_NEGOTIATE_EXTENDED_SESSIONSECURITY = 0x00080000UL,
        /** Negotiate always sign */
        NTLM_NEGOTIATE_ALWAYS_SIGN = 0x00008000UL,
        /** Negotiate NTLM key */
        NTLM_NEGOTIATE_NTLM = 0x00000200UL,
        /** Request target name and information */
        NTLM_REQUEST_TARGET = 0x00000004UL,
        /** Negotiate Unicode character encoding */
        NTLM_NEGOTIATE_UNICODE = 0x00000001UL,
};

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

ntlm_challenge()

int ntlm_challenge ( struct ntlm_challenge * challenge, size_t len, struct ntlm_challenge_info * info )

extern

Parse NTLM Challenge.

Parameters

challenge	Challenge message
len	Length of Challenge message
info	Challenge information to fill in

Return values

rc	Return status code

Definition at line 69 of file ntlm.c.

                                                        {
        size_t offset;
 
        DBGC ( challenge, "NTLM challenge message:\n" );
        DBGC_HDA ( challenge, 0, challenge, len );
 
        /* Sanity checks */
        if ( len < sizeof ( *challenge ) ) {
                DBGC ( challenge, "NTLM underlength challenge (%zd bytes)\n",
                       len );
                return -EINVAL;
        }
 
        /* Extract nonce */
        info->nonce = &challenge->nonce;
        DBGC ( challenge, "NTLM challenge nonce:\n" );
        DBGC_HDA ( challenge, 0, info->nonce, sizeof ( *info->nonce ) );
 
        /* Extract target information */
        info->len = le16_to_cpu ( challenge->info.len );
        offset = le32_to_cpu ( challenge->info.offset );
        if ( ( offset > len ) ||
             ( info->len > ( len - offset ) ) ) {
                DBGC ( challenge, "NTLM target information outside "
                       "challenge\n" );
                DBGC_HDA ( challenge, 0, challenge, len );
                return -EINVAL;
        }
        info->target = ( ( ( void * ) challenge ) + offset );
        DBGC ( challenge, "NTLM challenge target information:\n" );
        DBGC_HDA ( challenge, 0, info->target, info->len );
 
        return 0;
}

References DBGC, DBGC_HDA, EINVAL, info, ntlm_challenge::info, le16_to_cpu, le32_to_cpu, len, ntlm_data::len, ntlm_challenge::nonce, ntlm_data::offset, and offset.

ntlm_key()

void ntlm_key ( const char * domain, const char * username, const char * password, struct ntlm_key * key )

extern

Calculate NTLM verification key.

Parameters

domain	Domain name (or NULL)
username	User name (or NULL)
password	Password (or NULL)
key	Key to fill in

This is the NTOWFv2() function as defined in MS-NLMP.

Definition at line 115 of file ntlm.c.

                                                             {
        struct digest_algorithm *md4 = &md4_algorithm;
        struct digest_algorithm *md5 = &md5_algorithm;
        union {
                uint8_t md4[MD4_CTX_SIZE];
                uint8_t md5[ MD5_CTX_SIZE + MD5_BLOCK_SIZE ];
        } ctx;
        uint8_t digest[MD4_DIGEST_SIZE];
        uint8_t c;
        uint16_t wc;
 
        /* Use empty usernames/passwords if not specified */
        if ( ! domain )
                domain = "";
        if ( ! username )
                username = "";
        if ( ! password )
                password = "";
 
        /* Construct MD4 digest of (Unicode) password */
        digest_init ( md4, ctx.md4 );
        while ( ( c = *(password++) ) ) {
                wc = cpu_to_le16 ( c );
                digest_update ( md4, ctx.md4, &wc, sizeof ( wc ) );
        }
        digest_final ( md4, ctx.md4, digest );
 
        /* Construct HMAC-MD5 of (Unicode) upper-case username */
        hmac_init ( md5, ctx.md5, digest, sizeof ( digest ) );
        while ( ( c = *(username++) ) ) {
                wc = cpu_to_le16 ( toupper ( c ) );
                hmac_update ( md5, ctx.md5, &wc, sizeof ( wc ) );
        }
        while ( ( c = *(domain++) ) ) {
                wc = cpu_to_le16 ( c );
                hmac_update ( md5, ctx.md5, &wc, sizeof ( wc ) );
        }
        hmac_final ( md5, ctx.md5, key->raw );
        DBGC ( key, "NTLM key:\n" );
        DBGC_HDA ( key, 0, key, sizeof ( *key ) );
}

References cpu_to_le16, ctx, DBGC, DBGC_HDA, digest_final(), digest_init(), digest_update(), hmac_final(), hmac_init(), hmac_update(), key, md4_algorithm, MD4_CTX_SIZE, MD4_DIGEST_SIZE, md5_algorithm, MD5_BLOCK_SIZE, MD5_CTX_SIZE, password, toupper(), username, and wc.

Referenced by http_ntlm_authenticate(), ntlm_authenticate_okx(), and ntlm_key_okx().

ntlm_response()

void ntlm_response ( struct ntlm_challenge_info * info, struct ntlm_key * key, struct ntlm_nonce * nonce, struct ntlm_lm_response * lm, struct ntlm_nt_response * nt )

extern

Construct NTLM responses.

Parameters

info	Challenge information
key	Verification key
nonce	Nonce, or NULL to use a random nonce
lm	LAN Manager response to fill in
nt	NT response to fill in

Definition at line 167 of file ntlm.c.

                                                   {
        struct digest_algorithm *md5 = &md5_algorithm;
        struct ntlm_nonce tmp_nonce;
        uint8_t ctx[ MD5_CTX_SIZE + MD5_BLOCK_SIZE ];
        unsigned int i;
 
        /* Generate random nonce, if needed */
        if ( ! nonce ) {
                for ( i = 0 ; i < sizeof ( tmp_nonce ) ; i++ )
                        tmp_nonce.raw[i] = random();
                nonce = &tmp_nonce;
        }
 
        /* Construct LAN Manager response */
        memcpy ( &lm->nonce, nonce, sizeof ( lm->nonce ) );
        hmac_init ( md5, ctx, key->raw, sizeof ( *key ) );
        hmac_update ( md5, ctx, info->nonce, sizeof ( *info->nonce ) );
        hmac_update ( md5, ctx, &lm->nonce, sizeof ( lm->nonce ) );
        hmac_final ( md5, ctx, lm->digest );
        DBGC ( key, "NTLM LAN Manager response:\n" );
        DBGC_HDA ( key, 0, lm, sizeof ( *lm ) );
 
        /* Construct NT response */
        memset ( nt, 0, sizeof ( *nt ) );
        nt->version = NTLM_VERSION_NTLMV2;
        nt->high = NTLM_VERSION_NTLMV2;
        memcpy ( &nt->nonce, nonce, sizeof ( nt->nonce ) );
        hmac_init ( md5, ctx, key->raw, sizeof ( *key ) );
        hmac_update ( md5, ctx, info->nonce, sizeof ( *info->nonce ) );
        hmac_update ( md5, ctx, &nt->version,
                      ( sizeof ( *nt ) -
                        offsetof ( typeof ( *nt ), version ) ) );
        hmac_update ( md5, ctx, info->target, info->len );
        hmac_update ( md5, ctx, &nt->zero, sizeof ( nt->zero ) );
        hmac_final ( md5, ctx, nt->digest );
        DBGC ( key, "NTLM NT response prefix:\n" );
        DBGC_HDA ( key, 0, nt, sizeof ( *nt ) );
}

References ctx, DBGC, DBGC_HDA, ntlm_lm_response::digest, hmac_final(), hmac_init(), hmac_update(), info, key, md5_algorithm, MD5_BLOCK_SIZE, MD5_CTX_SIZE, memcpy(), memset(), nonce, ntlm_lm_response::nonce, nt, NTLM_VERSION_NTLMV2, offsetof, random(), ntlm_nonce::raw, typeof(), and version.

Referenced by http_ntlm_authenticate(), and ntlm_authenticate_okx().

ntlm_authenticate()

size_t ntlm_authenticate ( struct ntlm_challenge_info * info, const char * domain, const char * username, const char * workstation, struct ntlm_lm_response * lm, struct ntlm_nt_response * nt, struct ntlm_authenticate * auth )

extern

Construct NTLM Authenticate message.

Parameters

info	Challenge information
domain	Domain name, or NULL
username	User name, or NULL
workstation	Workstation name, or NULL
lm	LAN Manager response
nt	NT response
auth	Message to fill in, or NULL to only calculate length

Return values

len	Length of message

Definition at line 267 of file ntlm.c.

                                                            {
        void *tmp;
        size_t nt_len;
        size_t len;
 
        /* Construct response header */
        if ( auth ) {
                memset ( auth, 0, sizeof ( *auth ) );
                memcpy ( auth->header.magic, ntlm_negotiate.header.magic,
                         sizeof ( auth->header.magic ) );
                auth->header.type = cpu_to_le32 ( NTLM_AUTHENTICATE );
                auth->flags = ntlm_negotiate.flags;
        }
        tmp = ( ( ( void * ) auth ) + sizeof ( *auth ) );
 
        /* Construct LAN Manager response */
        if ( auth )
                memcpy ( tmp, lm, sizeof ( *lm ) );
        tmp = ntlm_append ( &auth->header, &auth->lm, tmp, sizeof ( *lm ) );
 
        /* Construct NT response */
        nt_len = ( sizeof ( *nt ) + info->len + sizeof ( nt->zero ) );
        if ( auth ) {
                memcpy ( tmp, nt, sizeof ( *nt ) );
                memcpy ( ( tmp + sizeof ( *nt ) ), info->target, info->len );
                memset ( ( tmp + sizeof ( *nt ) + info->len ), 0,
                         sizeof ( nt->zero ) );
        }
        tmp = ntlm_append ( &auth->header, &auth->nt, tmp, nt_len );
 
        /* Populate domain, user, and workstation names */
        tmp = ntlm_append_string ( &auth->header, &auth->domain, tmp, domain );
        tmp = ntlm_append_string ( &auth->header, &auth->user, tmp, username );
        tmp = ntlm_append_string ( &auth->header, &auth->workstation, tmp,
                                   workstation );
 
        /* Calculate length */
        len = ( tmp - ( ( void * ) auth ) );
        if ( auth ) {
                DBGC ( auth, "NTLM authenticate message:\n" );
                DBGC_HDA ( auth, 0, auth, len );
        }
 
        return len;
}

References cpu_to_le32, DBGC, DBGC_HDA, ntlm_authenticate::domain, ntlm_authenticate::flags, ntlm_negotiate::flags, ntlm_authenticate::header, ntlm_negotiate::header, info, len, ntlm_authenticate::lm, ntlm_header::magic, memcpy(), memset(), nt, ntlm_authenticate::nt, ntlm_append(), ntlm_append_string(), NTLM_AUTHENTICATE, tmp, ntlm_header::type, ntlm_authenticate::user, username, and ntlm_authenticate::workstation.

Referenced by http_format_ntlm_auth(), and ntlm_authenticate_len().

ntlm_authenticate_len()

size_t ntlm_authenticate_len ( struct ntlm_challenge_info * info, const char * domain, const char * username, const char * workstation )

extern

Calculate NTLM Authenticate message length.

Parameters

info	Challenge information
domain	Domain name, or NULL
username	User name, or NULL
workstation	Workstation name, or NULL

Return values

len	Length of Authenticate message

Definition at line 326 of file ntlm.c.

                                                         {
 
        return ntlm_authenticate ( info, domain, username, workstation,
                                   NULL, NULL, NULL );
}

References info, ntlm_authenticate(), NULL, and username.

Referenced by http_ntlm_authenticate(), and ntlm_authenticate_okx().

Variable Documentation

ntlm_negotiate

const struct ntlm_negotiate ntlm_negotiate

extern

Negotiate message.

This message content is fixed since there is no need to specify the calling workstation name or domain name, and the set of flags is mandated by the MS-NLMP specification.

Definition at line 49 of file ntlm.c.

                                             {
        .header = {
                .magic = NTLM_MAGIC,
                .type = cpu_to_le32 ( NTLM_NEGOTIATE ),
        },
        .flags = cpu_to_le32 ( NTLM_NEGOTIATE_EXTENDED_SESSIONSECURITY |
                               NTLM_NEGOTIATE_ALWAYS_SIGN |
                               NTLM_NEGOTIATE_NTLM |
                               NTLM_REQUEST_TARGET |
                               NTLM_NEGOTIATE_UNICODE ),
};