Ntlm ActiveX Reference Documentation
Ntlm
Current Version: 10.1.2
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.
Object Creation
Note: For versions of Chilkat < 10.0.0, use "Chilkat_9_5_0.Ntlm" instead of "Chilkat.Ntlm" For a specific major version, use "Chilkat.Ntlm.<major_version>", such as "Chilkat.Ntlm.10" for Chilkat v10.*.* See Chilkat ActiveX Object Creation (ASP) set obj = Server.CreateObject("Chilkat.Ntlm") (AutoIt) $obj = ObjCreate("Chilkat.Ntlm") (Visual Basic 6.0) Dim obj As New ChilkatNtlm (VBScript) set obj = CreateObject("Chilkat.Ntlm") (Delphi) obj := TChilkatNtlm.Create(Self); (FoxPro) loObject = CreateObject('Chilkat.Ntlm') (PowerBuilder) lole_object = create oleobject li_rc = lole_object.ConnectToNewObject("Chilkat.Ntlm") (SQL Server) EXEC @hr = sp_OACreate 'Chilkat.Ntlm', @obj OUT (Javascript) var obj = new ActiveXObject("Chilkat.Ntlm");
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, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing 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
This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. It is only accessible if Chilkat.Global.KeepBinaryResult is set to 1. This feature allows for the retrieval of large varbinary results in an SQL Server environment, which has restrictions on returning large data via method calls, though temp tables can handle binary properties.
topLastErrorHtml
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages.
topLastStringResult
In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. It is accessible only when Chilkat.Global.KeepStringResult is set to TRUE. SQL Server has limitations on string lengths returned from methods and properties, but temp tables can be used to access large strings.
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
Version of the component/library, such as "10.1.0"
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 Nothing 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 Nothing 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 Nothing 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 Nothing 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 Nothing 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 Nothing 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