TChilkatNtlm Delphi ActiveX Reference Documentation
TChilkatNtlm
Current Version: 10.0.0
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.
Importing the Chilkat ActiveX into Delphi
Important: When upgrading to a new version of Chilkat, make sure to re-imported ActiveX DLL into Delphi to regenerate the files described below.
Chilkat v9.5.*: If using Chilkat v9.5.*, then use "Chilkat_v9_5_0_TLB" instead of "Chilkat_TLB", and the DLLs are named ChilkatAx-9.5.0-win32.dll (or ChilkatAx-9.5.0-x64.dll).
Two things are required to use an ActiveX in Delphi:
- The ActiveX DLL needs to be registered via regsvr32 on the system where the Delphi application runs. See How To Register ActiveX DLLs for detailed information.
- See also: ActiveX Registration Tutorial
- The ActiveX component needs to be "imported". Use the Delphi Import Component Wizard to import the Chilkat type library. This creates the following files: Chilkat_TLB.pas and Chilkat_TLB.dcr. The Chilkat_TLB.pas should be added to your project.
To import the Chilkat type library, do the following:
- In the Delphi RAD Studio, select the menu item "Component" --> "Import a Type Library".
- Find "Chilkat ActiveX" in the list and select it. This will only appear in the list if the ChilkatAx-win32.dll (or ChilkatAx-x64.dll) has been registered w/ regsvr32.
- Check the "Generate Component Wrappers" checkbox.
- Select a directory where the unit files (.pas and .dcr) should be generated.
- Select "Create Unit" and then "Finish".
- Add the .pas to your Delphi project.
To use a Chilkat ActiveX object in your Delphi code, add "Chilkat_TLB" to the "uses" statement. For example:
uses Winapi.Windows, Winapi.Messages, System.SysUtils, System.Variants, System.Classes, Vcl.Graphics, Vcl.Controls, Vcl.Forms, Vcl.Dialogs, Vcl.StdCtrls, Chilkat_TLB;
Object Creation
var obj: TChilkatNtlm; ... begin obj := TChilkatNtlm.Create(Self); ... // When finished, free the object instance. obj.Free();
Properties
ClientChallenge
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.
topDebugLogFilePath
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.
DnsComputerName
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.
topDnsDomainName
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.
topDomain
Optional. May be set by the client for inclusion in the Type 1 message.
topEncodingMode
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".
topFlags
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 0x80000000The 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". top
LastBinaryResult
The binary data returned by the last (binary data returning) method called. Only available if Chilkat.Global.KeepBinaryResult is set to 1. This provides a means for obtaining large varbinary results in the SQL Server environment (where limitations exist in getting large amounts of data returned by method calls, but where temp tables can be used for binary properties).
topLastErrorHtml
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.
topLastErrorText
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.
LastErrorXml
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.
topLastMethodSuccess
Indicate whether the last method call succeeded or failed. A value of 1 indicates success, a value of 0 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 = 1 and failure = 0.
- 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 1. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.
topLastStringResult
The string return value of the last (string returning) method called. Only available if Chilkat.Global.KeepStringResult is set to 1. This provides a means for obtaining large string results in the SQL Server environment (where limitations exist in getting long strings returned by method calls, but where temp tables can be used for string properties).
LastStringResultLen
The length, in characters, of the string contained in the LastStringResult property.
topNetBiosComputerName
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.
topNetBiosDomainName
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.
topNtlmVersion
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.
topOemCodePage
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.
topPassword
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.
topServerChallenge
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.
topTargetName
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.
topUserName
The username of the account to be authenticated. This must be set by the client prior to generating and sending the Type 3 message.
topVerboseLogging
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
topVersion
Workstation
The value to be used in the optional workstation field in Type 1 message.
topMethods
CompareType3
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 1 if the responses match, and 0 if they do not.
topGenType1
Generates the Type 1 message. The Type 1 message is sent from Client to Server and initiates the NTLM authentication exchange.
Returns a zero-length WideString on failure
GenType2
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 a zero-length WideString on failure
GenType3
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 a zero-length WideString on failure
LoadType3
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 1 for success, 0 for failure.
ParseType1
For informational purposes only. Allows for the server-side to parse a Type 1 message to get human-readable information about the contents.
Returns a zero-length WideString on failure
ParseType2
For informational purposes only. Allows for the client-side to parse a Type 2 message to get human-readable information about the contents.
Returns a zero-length WideString on failure
ParseType3
For informational purposes only. Allows for the server-side to parse a Type 3 message to get human-readable information about the contents.
Returns a zero-length WideString on failure
SetFlag
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 1 for success, 0 for failure.
top