Ntlm Delphi DLL Reference Documentation

Ntlm

Current Version: 10.1.0

Requires Chilkat Bundle License

API for implemeting both client and server sides of the NTLM protocol/algorithm. The Chilkat NTLM API is included as part of the "Chilkat Crypt" license.

Create/Dispose

var
myObject: HCkNtlm;

begin
myObject := CkNtlm_Create();

// ...

CkNtlm_Dispose(myObject);
end;

function CkNtlm_Create: HCkNtlm; stdcall;

Creates an instance of the HCkNtlm object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

procedure CkNtlm_Dispose(handle: HCkNtlm); stdcall;

Objects created by calling CkNtlm_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

Properties

ClientChallenge

procedure CkNtlm_getClientChallenge(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putClientChallenge(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__clientChallenge(objHandle: HCkNtlm): PWideChar; stdcall;

The ClientChallenge is passed in the Type 3 message from the client to the server. It must contain exactly 8 bytes. Because this is a string property, the bytes are get/set in encoded form (such as hex or base64) based on the value of the EncodingMode property. For example, if the EncodingMode property = "hex", then a hex representation of 8 bytes should be used to set the ClientChallenge.

Note: Setting the ClientChallenge is optional. If the ClientChallenge remains unset, it will be automatically set to 8 random bytes when the GenType3 method is called.

See the notes about PWideChar memory ownership and validity.

DebugLogFilePath

procedure CkNtlm_getDebugLogFilePath(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putDebugLogFilePath(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__debugLogFilePath(objHandle: HCkNtlm): PWideChar; stdcall;

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
there is an internal problem (bug) in the Chilkat code that causes the hang.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

Example showing how to use DebugLogFilePath.

DnsComputerName

procedure CkNtlm_getDnsComputerName(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putDnsComputerName(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__dnsComputerName(objHandle: HCkNtlm): PWideChar; stdcall;

Optional. This is information that would be set by the server for inclusion in the "Target Info" internal portion of the Type 2 message. Note: If any optional "Target Info" fields are provided, then both NetBiosComputerName and NetBiosDomainName must be provided.

See the notes about PWideChar memory ownership and validity.

DnsDomainName

procedure CkNtlm_getDnsDomainName(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putDnsDomainName(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__dnsDomainName(objHandle: HCkNtlm): PWideChar; stdcall;

Optional. This is information that would be set by the server for inclusion in the "Target Info" internal portion of the Type 2 message. Note: If any optional "Target Info" fields are provided, then both NetBiosComputerName and NetBiosDomainName must be provided.

See the notes about PWideChar memory ownership and validity.

Domain

procedure CkNtlm_getDomain(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putDomain(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__domain(objHandle: HCkNtlm): PWideChar; stdcall;

Optional. May be set by the client for inclusion in the Type 1 message.

See the notes about PWideChar memory ownership and validity.

EncodingMode

procedure CkNtlm_getEncodingMode(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putEncodingMode(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__encodingMode(objHandle: HCkNtlm): PWideChar; stdcall;

Determines the encoding mode used for getting/setting various properties, such as ClientChallenge. The valid case-insensitive modes are "Base64", "modBase64", "Base32", "UU", "QP" (for quoted-printable), "URL" (for url-encoding), "Hex", "Q", "B", "url_oath", "url_rfc1738", "url_rfc2396", and "url_rfc3986".

See the notes about PWideChar memory ownership and validity.

Flags

procedure CkNtlm_getFlags(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putFlags(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__flags(objHandle: HCkNtlm): PWideChar; stdcall;

The negotiate flags that are set in the Type 1 message generated by the client and sent to the server. These flags have a default value and should ONLY be set by a programmer that is an expert in the NTLM protocol and knows what they mean. In general, this property should be left at it's default value.

The flags are represented as a string of letters, where each letter represents a bit. The full set of possible flags (bit values) are shown below:

NegotiateUnicode               0x00000001
NegotiateOEM                   0x00000002
RequestTarget                  0x00000004
NegotiateSign                  0x00000010
NegotiateSeal                  0x00000020
NegotiateDatagramStyle         0x00000040
NegotiateLanManagerKey         0x00000080
NegotiateNetware               0x00000100
NegotiateNTLMKey               0x00000200
NegotiateDomainSupplied        0x00001000
NegotiateWorkstationSupplied   0x00002000
NegotiateLocalCall             0x00004000
NegotiateAlwaysSign            0x00008000
TargetTypeDomain               0x00010000
TargetTypeServer               0x00020000
TargetTypeShare                0x00040000
NegotiateNTLM2Key              0x00080000
RequestInitResponse            0x00100000
RequestAcceptResponse          0x00200000
RequestNonNTSessionKey         0x00400000
NegotiateTargetInfo            0x00800000
Negotiate128                   0x20000000
NegotiateKeyExchange           0x40000000
Negotiate56                    0x80000000

The mapping of letters to bit values are as follows:

0x01 - "A"
0x02 - "B"
0x04 - "C"
0x10 - "D"
0x20 - "E"
0x40 - "F"
0x80 - "G"
0x200 - "H"
0x400 - "I"
0x800 - "J"
0x1000 - "K"
0x2000 - "L"
0x8000 - "M"
0x10000 - "N"
0x20000 - "O"
0x40000 - "P"
0x80000 - "Q"
0x100000 - "R"
0x400000 - "S"
0x800000 - "T"
0x2000000 - "U"
0x20000000 - "V"
0x40000000 - "W"
0x80000000 - "X"

The default Flags value has the following flags set: NegotiateUnicode, NegotiateOEM, RequestTarget, NegotiateNTLMKey, NegotiateAlwaysSign, NegotiateNTLM2Key. The corresponds to the string "ABCHMQ".

See the notes about PWideChar memory ownership and validity.

LastErrorHtml

procedure CkNtlm_getLastErrorHtml(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
function CkNtlm__lastErrorHtml(objHandle: HCkNtlm): PWideChar; stdcall;

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

See the notes about PWideChar memory ownership and validity.

LastErrorText

procedure CkNtlm_getLastErrorText(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
function CkNtlm__lastErrorText(objHandle: HCkNtlm): PWideChar; stdcall;

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

Concept of LastErrorText LastErrorText Standard Information

LastErrorXml

procedure CkNtlm_getLastErrorXml(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
function CkNtlm__lastErrorXml(objHandle: HCkNtlm): PWideChar; stdcall;

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

See the notes about PWideChar memory ownership and validity.

LastMethodSuccess

function CkNtlm_getLastMethodSuccess(objHandle: HCkNtlm): wordbool; stdcall;
procedure CkNtlm_putLastMethodSuccess(objHandle: HCkNtlm; newPropVal: wordbool); stdcall;

Indicate whether the last method call succeeded or failed. A value of True indicates success, a value of False indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

Any method that returns a string.
Any method returning a Chilkat object, binary bytes, or a date/time.
Any method returning a standard boolean status value where success = True and failure = False.
Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to True. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

NetBiosComputerName

procedure CkNtlm_getNetBiosComputerName(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putNetBiosComputerName(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__netBiosComputerName(objHandle: HCkNtlm): PWideChar; stdcall;

Optional. This is information that would be set by the server for inclusion in the "Target Info" internal portion of the Type 2 message. Note: If any optional "Target Info" fields are provided, then both NetBiosComputerName and NetBiosDomainName must be provided.

See the notes about PWideChar memory ownership and validity.

NetBiosDomainName

procedure CkNtlm_getNetBiosDomainName(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putNetBiosDomainName(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__netBiosDomainName(objHandle: HCkNtlm): PWideChar; stdcall;

Optional. This is information that would be set by the server for inclusion in the "Target Info" internal portion of the Type 2 message. Note: If any optional "Target Info" fields are provided, then both NetBiosComputerName and NetBiosDomainName must be provided.

See the notes about PWideChar memory ownership and validity.

NtlmVersion

function CkNtlm_getNtlmVersion(objHandle: HCkNtlm): Integer; stdcall;
procedure CkNtlm_putNtlmVersion(objHandle: HCkNtlm; newPropVal: Integer); stdcall;

The version of the NTLM protocol to be used. Must be set to either 1 or 2. The default value is 1 (for NTLMv1). Setting this property equal to 2 selects NTLMv2.

OemCodePage

function CkNtlm_getOemCodePage(objHandle: HCkNtlm): Integer; stdcall;
procedure CkNtlm_putOemCodePage(objHandle: HCkNtlm; newPropVal: Integer); stdcall;

If the "A" flag is unset, then Unicode strings are not used internally in the NTLM messages. Strings are instead represented using the OEM code page (i.e. charset, or character encoding) as specified here. In general, given that the Flags property should rarely be modified, and given that the "A" flag is set by default (meaning that Unicode is used), the OemCodePage property will not apply. The default value is the default OEM code page of the local computer.

Password

procedure CkNtlm_getPassword(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putPassword(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__password(objHandle: HCkNtlm): PWideChar; stdcall;

The password corresponding to the username of the account to be authenticated. This must be set by the client prior to generating and sending the Type 3 message.

See the notes about PWideChar memory ownership and validity.

ServerChallenge

procedure CkNtlm_getServerChallenge(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putServerChallenge(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__serverChallenge(objHandle: HCkNtlm): PWideChar; stdcall;

This is similar to the ClientChallenge in that it must contain 8 bytes.

The ServerChallenge is passed in the Type 2 message from the server to the client. Because this is a string property, the bytes are get/set in encoded form (such as hex or base64) based on the value of the EncodingMode property. For example, if the EncodingMode property = "hex", then a hex representation of 8 bytes should be used to set the ServerChallenge.

Note: Setting the ServerChallenge is optional. If the ServerChallenge remains unset, it will be automatically set to 8 random bytes when the GenType2 method is called.

See the notes about PWideChar memory ownership and validity.

TargetName

procedure CkNtlm_getTargetName(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putTargetName(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__targetName(objHandle: HCkNtlm): PWideChar; stdcall;

The authentication realm in which the authenticating account has membership, such as a domain for domain accounts, or a server name for local machine accounts. The TargetName is used in the Type2 message sent from the server to the client.

See the notes about PWideChar memory ownership and validity.

UserName

procedure CkNtlm_getUserName(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putUserName(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__userName(objHandle: HCkNtlm): PWideChar; stdcall;

The username of the account to be authenticated. This must be set by the client prior to generating and sending the Type 3 message.

See the notes about PWideChar memory ownership and validity.

VerboseLogging

function CkNtlm_getVerboseLogging(objHandle: HCkNtlm): wordbool; stdcall;
procedure CkNtlm_putVerboseLogging(objHandle: HCkNtlm; newPropVal: wordbool); stdcall;

If set to True, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is False. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

Version

procedure CkNtlm_getVersion(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
function CkNtlm__version(objHandle: HCkNtlm): PWideChar; stdcall;

Version of the component/library, such as "9.5.0.94"

See the notes about PWideChar memory ownership and validity.

More Information and Examples

How to get the Chilkat version at runtime.

Workstation

procedure CkNtlm_getWorkstation(objHandle: HCkNtlm; outPropVal: HCkString); stdcall;
procedure CkNtlm_putWorkstation(objHandle: HCkNtlm; newPropVal: PWideChar); stdcall;
function CkNtlm__workstation(objHandle: HCkNtlm): PWideChar; stdcall;

The value to be used in the optional workstation field in Type 1 message.

See the notes about PWideChar memory ownership and validity.

Methods

CompareType3

function CkNtlm_CompareType3(objHandle: HCkNtlm;
msg1: PWideChar;
msg2: PWideChar): wordbool; stdcall;

Compares the internal contents of two Type3 messages to verify that the LM and NTLM response parts match. A server would typically compute the Type3 message by calling GenType3, and then compare it with the Type3 message received from the client. The method returns True if the responses match, and False if they do not.

GenType1

function CkNtlm_GenType1(objHandle: HCkNtlm;
outStr: HCkString): wordbool; stdcall;
function CkNtlm__genType1(objHandle: HCkNtlm): PWideChar; stdcall;

Generates the Type 1 message. The Type 1 message is sent from Client to Server and initiates the NTLM authentication exchange.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

NTLM Client and Server Example

GenType2

function CkNtlm_GenType2(objHandle: HCkNtlm;
    type1Msg: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkNtlm__genType2(objHandle: HCkNtlm;
    type1Msg: PWideChar): PWideChar; stdcall;

Generates a Type2 message from a received Type1 message. The server-side generates the Type2 message and sends it to the client. This is the 2nd step in the NTLM protocol. The 1st step is the client generating the initial Type1 message which is sent to the server.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

NTLM Client and Server Example

GenType3

function CkNtlm_GenType3(objHandle: HCkNtlm;
    type2Msg: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkNtlm__genType3(objHandle: HCkNtlm;
    type2Msg: PWideChar): PWideChar; stdcall;

Generates the final message in the NTLM authentication exchange. This message is sent from the client to the server. The Type 2 message received from the server is passed to GenType3. The Username and Password properties are finally used here in the generation of the Type 3 message. Note, the Password is never actually sent. It is used to compute a binary response that the server can then check, using the password it has on file, to verify that indeed the client must've used the correct password.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

NTLM Client and Server Example

LoadType3

function CkNtlm_LoadType3(objHandle: HCkNtlm;
type3Msg: PWideChar): wordbool; stdcall;

The server-side should call this method with the Type 3 message received from the client. The LoadType3 method sets the following properties: Username, Domain, Workstation, and ClientChallenge, all of which are embedded within the Type 3 message.

The server-side code may then use the Username to lookup the associated password and then it will itself call the GenType3 method to do the same computation as done by the client. The server then compares it's computed Type 3 message with the Type 3 message received from the client. If the Type 3 messages are exactly the same, then it must be that the client used the correct password, and therefore the client authentication is successful.

Returns True for success, False for failure.

More Information and Examples

NTLM Client and Server Example

ParseType1

function CkNtlm_ParseType1(objHandle: HCkNtlm;
    type1Msg: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkNtlm__parseType1(objHandle: HCkNtlm;
    type1Msg: PWideChar): PWideChar; stdcall;

For informational purposes only. Allows for the server-side to parse a Type 1 message to get human-readable information about the contents.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

NTLM Client and Server Example

ParseType2

function CkNtlm_ParseType2(objHandle: HCkNtlm;
    type2Msg: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkNtlm__parseType2(objHandle: HCkNtlm;
    type2Msg: PWideChar): PWideChar; stdcall;

For informational purposes only. Allows for the client-side to parse a Type 2 message to get human-readable information about the contents.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

NTLM Client and Server Example

ParseType3

function CkNtlm_ParseType3(objHandle: HCkNtlm;
    type3Msg: PWideChar;
    outStr: HCkString): wordbool; stdcall;
function CkNtlm__parseType3(objHandle: HCkNtlm;
    type3Msg: PWideChar): PWideChar; stdcall;

For informational purposes only. Allows for the server-side to parse a Type 3 message to get human-readable information about the contents.

Returns True for success, False for failure.

See the notes about PWideChar memory ownership and validity.

More Information and Examples

NTLM Client and Server Example

SetFlag

function CkNtlm_SetFlag(objHandle: HCkNtlm;
flagLetter: PWideChar;
onOrOff: wordbool): wordbool; stdcall;

Sets one of the negotiate flags to be used in the Type 1 message sent by the client. It should normally be unnecessary to modify the default flag settings. For more information about flags, see the description for the Flags property above.

Returns True for success, False for failure.