Ntlm PHP ActiveX Reference Documentation

Ntlm

Current Version: 11.5.0
Requires Chilkat Bundle License

Chilkat.Ntlm

Generate, parse, and verify NTLM authentication messages.

Chilkat.Ntlm implements the NTLM challenge/response message workflow. It can generate Type 1, Type 2, and Type 3 NTLM messages, parse those messages for inspection, compare Type 3 responses on the server side, and control key authentication inputs such as username, password, domain, workstation, target name, client challenge, server challenge, NTLM version, encoding mode, and negotiate flags.

Type 1 negotiate message

Generate the client-to-server message that begins the NTLM exchange and advertises supported options.

Type 2 challenge message

Generate the server challenge response, including target name, server challenge, and optional target-info fields.

Type 3 authenticate message

Generate the final client response using the username and password without sending the password itself.

Server-side verification

Load a received Type 3 message, extract embedded fields, recompute the response, and compare the result with CompareType3.

Challenges and encoding

Set or inspect 8-byte client and server challenges using encodings such as hex, Base64, Base32, quoted-printable, URL encoding, and others.

Version, flags, and diagnostics

Select NTLMv1 or NTLMv2, adjust negotiate flags when required, parse messages for readable diagnostics, and check LastErrorText.

Common pattern: The client calls GenType1 and sends the Type 1 message to the server. The server calls GenType2 and sends the Type 2 challenge back. The client sets UserName and Password, calls GenType3, and sends the Type 3 message. The server calls LoadType3, looks up the user's password, recomputes the Type 3 response, and uses CompareType3 to verify authentication.
Flag guidance: The default Flags value is intended for normal use. Only modify negotiate flags with SetFlag or by setting Flags directly when the application has specific NTLM protocol requirements and the meaning of the affected flags is understood.

Object Creation

Chilkat v10.0.0 or greater:
$obj = new COM("Chilkat.Ntlm");
Chilkat v9.5.0.*:
$obj = new COM("Chilkat_9_5_0.Ntlm");

Properties

ClientChallenge
string ClientChallenge

Specifies the 8-byte client challenge used when generating the Type 3 authenticate message. Because this property is a string, the bytes are represented using EncodingMode. For example, when EncodingMode is hex, set this property to exactly 16 hexadecimal characters.

Setting this property is optional. If it is empty when GenType3 is called, Chilkat generates eight random bytes automatically.

Security note: A client challenge is a nonce, not a password or encryption key. Use a fresh unpredictable value for each authentication exchange; do not deliberately reuse a fixed challenge in production.

top
DebugLogFilePath
string DebugLogFilePath

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.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
DnsComputerName
string DnsComputerName

Specifies the server's DNS computer name for inclusion in the MsvAvDnsComputerName entry of the Type 2 message's TargetInfo block.

This property is optional and is used by server-side code when constructing the TargetInfo AV-pair sequence in a Type 2 challenge message.

If any of the optional target-information name properties are supplied, Chilkat requires both NetBiosComputerName and NetBiosDomainName to be set.

NTLMv2 background: Target information is sent by the server and incorporated into the NTLMv2 response. The values should describe the actual authentication target; they are not arbitrary client-supplied labels.

top
DnsDomainName
string DnsDomainName

Specifies the server's DNS domain name for inclusion in the MsvAvDnsDomainName entry of the Type 2 message's TargetInfo block.

This property is optional and is used by server-side code when constructing the TargetInfo AV-pair sequence in a Type 2 challenge message.

If any of the optional target-information name properties are supplied, Chilkat requires both NetBiosComputerName and NetBiosDomainName to be set.

NTLMv2 background: Target information is sent by the server and incorporated into the NTLMv2 response. The values should describe the actual authentication target; they are not arbitrary client-supplied labels.

top
Domain
string Domain

Specifies the client's domain or workgroup name. When provided, it can be included in the Type 1 negotiate message and is used as the domain component of the identity in the Type 3 authenticate message.

For a domain account, use the account's Windows domain name. For a local account, the expected value depends on the authenticating server and protocol.

Identity note: Domain is separate from TargetName. Domain identifies the account's domain in the client identity, whereas TargetName is supplied by the server in the Type 2 challenge.

top
EncodingMode
string EncodingMode

Controls the textual encoding used when Chilkat exposes binary NTLM values as strings or accepts them from strings. This includes generated and parsed NTLM message tokens and binary-valued properties such as ClientChallenge and ServerChallenge.

The mode name is case-insensitive. Supported values include base64, modBase64, base32, UU, QP, URL, hex, Q, B, url_oauth, url_rfc1738, url_rfc2396, and url_rfc3986.

Interoperability: NTLM tokens carried in HTTP Authorization or WWW-Authenticate headers are conventionally Base64 encoded. Use the same EncodingMode for both the producer and consumer of a token.

top
Flags
string Flags

Specifies the NTLM negotiate flags as a compact string in which each letter represents one bit. The flags advertise or select character encoding, target information, session security, and other protocol capabilities.

The default is ABCHMQ, which enables Unicode, OEM compatibility, target-name request, NTLM authentication, always-sign behavior, and extended session security.

LetterBit valueMicrosoft flag name
A0x00000001NTLMSSP_NEGOTIATE_UNICODE
B0x00000002NTLM_NEGOTIATE_OEM
C0x00000004NTLMSSP_REQUEST_TARGET
D0x00000010NTLMSSP_NEGOTIATE_SIGN
E0x00000020NTLMSSP_NEGOTIATE_SEAL
F0x00000040NTLMSSP_NEGOTIATE_DATAGRAM
G0x00000080NTLMSSP_NEGOTIATE_LM_KEY
H0x00000200NTLMSSP_NEGOTIATE_NTLM
I0x00000400Reserved / unused
J0x00000800NTLMSSP_NEGOTIATE_ANONYMOUS
K0x00001000NTLMSSP_NEGOTIATE_OEM_DOMAIN_SUPPLIED
L0x00002000NTLMSSP_NEGOTIATE_OEM_WORKSTATION_SUPPLIED
M0x00008000NTLMSSP_NEGOTIATE_ALWAYS_SIGN
N0x00010000NTLMSSP_TARGET_TYPE_DOMAIN
O0x00020000NTLMSSP_TARGET_TYPE_SERVER
P0x00040000Reserved / unused
Q0x00080000NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY
R0x00100000NTLMSSP_NEGOTIATE_IDENTIFY
S0x00400000NTLMSSP_REQUEST_NON_NT_SESSION_KEY
T0x00800000NTLMSSP_NEGOTIATE_TARGET_INFO
U0x02000000NTLMSSP_NEGOTIATE_VERSION
V0x20000000NTLMSSP_NEGOTIATE_128
W0x40000000NTLMSSP_NEGOTIATE_KEY_EXCH
X0x80000000NTLMSSP_NEGOTIATE_56
Compatibility warning: Leave this property at its default unless a specific protocol peer requires different flags and the consequences are understood. Some bits are mutually dependent, some are meaningful only in particular message types, and reserved bits should remain clear. Prefer SetFlag when changing a single option.

top
LastBinaryResult
VARIANT LastBinaryResult (read-only)

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 true. 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.

top
LastErrorHtml
string LastErrorHtml (read-only)

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.

top
LastErrorText
string LastErrorText (read-only)

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.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
string LastErrorXml (read-only)

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.

top
LastMethodSuccess
bool LastMethodSuccess

Indicates the success or failure of the most recent method call: true means success, false 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. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.

top
LastStringResult
string LastStringResult (read-only)

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.

More Information and Examples
Long Strings Returned by ActiveX Methods in SQL Server
top
LastStringResultLen
int LastStringResultLen (read-only)

The length, in characters, of the string contained in the LastStringResult property.

top
NetBiosComputerName
string NetBiosComputerName

Specifies the server's NetBIOS computer name for inclusion in the MsvAvNbComputerName entry of the Type 2 message's TargetInfo block.

This property is optional and is used by server-side code when constructing the TargetInfo AV-pair sequence in a Type 2 challenge message.

If any of the optional target-information name properties are supplied, Chilkat requires both NetBiosComputerName and NetBiosDomainName to be set.

NTLMv2 background: Target information is sent by the server and incorporated into the NTLMv2 response. The values should describe the actual authentication target; they are not arbitrary client-supplied labels.

top
NetBiosDomainName
string NetBiosDomainName

Specifies the server's NetBIOS domain name for inclusion in the MsvAvNbDomainName entry of the Type 2 message's TargetInfo block.

This property is optional and is used by server-side code when constructing the TargetInfo AV-pair sequence in a Type 2 challenge message.

If any of the optional target-information name properties are supplied, Chilkat requires both NetBiosComputerName and NetBiosDomainName to be set.

NTLMv2 background: Target information is sent by the server and incorporated into the NTLMv2 response. The values should describe the actual authentication target; they are not arbitrary client-supplied labels.

top
NtlmVersion
int NtlmVersion

Selects the challenge-response algorithm used to generate and verify the authentication response.

ValueBehavior
1Use NTLMv1. This is the default for backward compatibility.
2Use NTLMv2.

The client and server must use compatible response algorithms. This setting is not negotiated by the three NTLM messages.

Security recommendation: Set this property to 2 for modern deployments. NTLMv1 is obsolete and has been removed from Windows 11 version 24H2 and Windows Server 2025. Use NTLM only where compatibility requires it; Kerberos through Negotiate is preferred in Active Directory environments.

top
OemCodePage
int OemCodePage

Specifies the OEM code page used to encode NTLM text fields when Unicode negotiation is disabled. The default is the local computer's OEM code page.

This property applies only when flag A (NTLMSSP_NEGOTIATE_UNICODE) is clear and OEM encoding is selected. With the default flags, Unicode is used and this setting has no effect.

Interoperability: Both sides must interpret OEM-encoded fields using compatible code pages. Retaining Unicode negotiation avoids locale-dependent corruption of usernames, domains, and workstation names.

top
Password
string Password

Specifies the password for UserName. Client-side code must set it before calling GenType3. Server-side verification code sets it after LoadType3, typically after looking up the account identified by the loaded username and domain.

The password itself is not placed in the Type 3 message. It is used to derive the challenge-response proof.

Sensitive value: Treat this property as credential material. Do not log it, persist it in plain text, or retain it longer than necessary. NTLM challenge-response still depends on password-derived secrets and does not make weak passwords safe.

top
ServerChallenge
string ServerChallenge

Specifies the 8-byte server challenge carried in the Type 2 challenge message. Because this property is a string, the bytes are represented using EncodingMode. For example, with EncodingMode set to hex, provide exactly 16 hexadecimal characters.

Setting this property is optional. If it is empty when GenType2 is called, Chilkat generates eight random bytes automatically. Server-side verification must use the same challenge that was sent to the client.

Security note: Generate a fresh unpredictable server challenge for each authentication exchange. Reusing challenges increases exposure to replay and precomputation attacks.

top
TargetName
string TargetName

Specifies the server-provided authentication target placed in the Type 2 challenge message. Depending on the target-type flags, it commonly identifies a Windows domain or the server handling local-account authentication.

This is not the client account's domain; use Domain for that purpose.

Protocol note: The target name helps describe the authentication realm advertised by the server. It does not by itself authenticate the server or prevent NTLM relay attacks.

top
UserName
string UserName

Specifies the account name to authenticate. Client-side code must set it before calling GenType3. After server-side code calls LoadType3, this property contains the username extracted from the received Type 3 message.

Use Domain separately when the account belongs to a Windows domain or workgroup.

Server-side rule: Treat the username and domain from a received Type 3 message as untrusted input until the challenge response has been verified.

top
VerboseLogging
bool VerboseLogging

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.

top
Version
string Version (read-only)

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

More Information and Examples
How to get the Chilkat version at runtime.
top
Workstation
string Workstation

Specifies the optional client workstation name. When supplied, Chilkat can include it in the Type 1 negotiate message and the Type 3 authenticate message. After LoadType3, it contains the workstation value reported by the client.

Identity note: The workstation field is descriptive client-supplied metadata. It is not proof of the client's computer identity and should not be used as an authorization decision by itself.

top

Methods

CompareType3
bool CompareType3(string msg1, string msg2)

Compares two encoded Type 3 authenticate messages and returns true when their LM and NT challenge-response fields match. A server commonly passes the Type 3 message received from the client as one argument and the expected Type 3 message recomputed with GenType3 as the other.

The messages must use the encoding selected by EncodingMode. Other Type 3 metadata, such as username or workstation text, is not the basis of this comparison.

Authentication workflow: A matching response is meaningful only when the expected message was generated from the original Type 2 challenge, the correct account password, the same NTLM version, and the relevant loaded client fields. A false result means the response fields do not match; inspect LastMethodSuccess and LastErrorText if malformed input or another processing error is possible.

top
GenType1
string GenType1()

Generates the client-to-server Type 1 Negotiate message that starts an NTLM authentication exchange. The message advertises the capabilities in Flags and can include the optional Domain and Workstation values.

The returned token is encoded according to EncodingMode. Check LastMethodSuccess before using the returned string.

Message flow: Type 1 contains negotiation metadata; it does not contain the user's password or challenge response.

Returns null on failure

More Information and Examples
NTLM Client and Server Example
top
GenType2
string GenType2(string type1Msg)

Generates the server-to-client Type 2 Challenge message from the encoded Type 1 message in type1Msg. Before calling, server-side code normally sets TargetName and may set ServerChallenge and the target-information name properties.

If ServerChallenge is empty, Chilkat generates a random 8-byte challenge. The input and returned token use EncodingMode. Check LastMethodSuccess before sending the result.

State requirement: Preserve the Type 2 message—or at minimum all state needed to reproduce it—for the later server-side verification of Type 3. The expected response is bound to the challenge and target information sent in this message.

Returns null on failure

More Information and Examples
NTLM Client and Server Example
top
GenType3
string GenType3(string type2Msg)

Generates the client-to-server Type 3 Authenticate message from the encoded Type 2 message in type2Msg. Client-side code must set UserName and Password; set Domain and Workstation when required by the account and peer.

Chilkat computes the response using NtlmVersion, the server challenge and target information from Type 2, and the client challenge. If ClientChallenge is empty, Chilkat generates it automatically. The password itself is not transmitted.

The input and returned token use EncodingMode. Check LastMethodSuccess before using the returned string.

Security limitation: NTLM proves knowledge of password-derived material but does not by itself authenticate the server. Deploy it only inside a transport and protocol configuration that addresses relay, channel protection, and server identity.

Returns null on failure

More Information and Examples
NTLM Client and Server Example
top
LoadType3
bool LoadType3(string type3Msg)

Parses an encoded Type 3 authenticate message received by server-side code and loads its client-supplied fields into this object. On success, UserName, Domain, Workstation, and ClientChallenge are populated from the message.

This method parses the message; it does not authenticate the client. After loading, look up the account's password, set Password, recompute the expected Type 3 response with GenType3 using the original Type 2 message, and compare the response fields with CompareType3.

Do not trust parsed identity fields yet: Values extracted from Type 3 are controlled by the remote client. Use them only to locate the candidate account until the challenge response has been verified.

Returns true for success, false for failure.

More Information and Examples
NTLM Client and Server Example
top
ParseType1
string ParseType1(string type1Msg)

Parses an encoded Type 1 negotiate message and returns human-readable XML describing its fields, including negotiation flags and any supplied domain or workstation information.

The input token is decoded according to EncodingMode. The returned text is diagnostic XML intended for inspection and troubleshooting; parsing a message does not verify its authenticity. Check LastMethodSuccess before using the returned string.

Returns null on failure

More Information and Examples
NTLM Client and Server Example
top
ParseType2
string ParseType2(string type2Msg)

Parses an encoded Type 2 challenge message and returns human-readable XML describing its fields, including flags, target name, server challenge, and target-information AV pairs when present.

The input token is decoded according to EncodingMode. The returned text is diagnostic XML intended for inspection and troubleshooting; parsing a message does not verify its authenticity. Check LastMethodSuccess before using the returned string.

Diagnostic sensitivity: A Type 2 message contains a live server challenge and target metadata. Avoid exposing diagnostic output unnecessarily while an authentication exchange is active.

Returns null on failure

More Information and Examples
NTLM Client and Server Example
top
ParseType3
string ParseType3(string type3Msg)

Parses an encoded Type 3 authenticate message and returns human-readable XML describing its fields, including the reported username, domain, workstation, and challenge-response data.

The input token is decoded according to EncodingMode. The returned text is diagnostic XML intended for inspection and troubleshooting; parsing a message does not verify its authenticity. Check LastMethodSuccess before using the returned string.

Sensitive diagnostic data: The password is not present, but Type 3 contains account identifiers and password-derived response material that may be useful to an attacker. Do not place parsed output in public or long-lived logs.

Returns null on failure

More Information and Examples
NTLM Client and Server Example
top
SetFlag
bool SetFlag(string flagLetter, bool onOrOff)

Turns one Chilkat flag letter on or off in Flags. flagLetter is a single letter listed in the Flags table, and onOrOff is true to set the bit or false to clear it.

Returns true when the flag letter is accepted and the value is updated; otherwise returns false.

Use with care: NTLM flags have dependencies and message-specific meanings. Modify them only for a known interoperability requirement, and avoid enabling reserved letters.

Returns true for success, false for failure.

top