Package com.chilkatsoft.chilkat2

Class Ntlm

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Ntlm
All Implemented Interfaces:
AutoCloseable
public class Ntlm extends ChilkatObject
<section class="ntlm-summary">

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.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Ntlm

      public Ntlm()
      Creates a new Ntlm object.

  • Method Details

    • getClientChallenge

      public String getClientChallenge()
      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.

      Returns:
      the value of the ClientChallenge property

    • setClientChallenge

      public void setClientChallenge​(String value)
      Sets the ClientChallenge property; see getClientChallenge().
      Parameters:
      value - the new value (not null)

    • getDnsComputerName

      public String getDnsComputerName()
      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.

      Returns:
      the value of the DnsComputerName property

    • setDnsComputerName

      public void setDnsComputerName​(String value)
      Sets the DnsComputerName property; see getDnsComputerName().
      Parameters:
      value - the new value (not null)

    • getDnsDomainName

      public String getDnsDomainName()
      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.

      Returns:
      the value of the DnsDomainName property

    • setDnsDomainName

      public void setDnsDomainName​(String value)
      Sets the DnsDomainName property; see getDnsDomainName().
      Parameters:
      value - the new value (not null)

    • getDomain

      public String getDomain()
      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.

      Returns:
      the value of the Domain property

    • setDomain

      public void setDomain​(String value)
      Sets the Domain property; see getDomain().
      Parameters:
      value - the new value (not null)

    • getEncodingMode

      public String getEncodingMode()
      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.

      Returns:
      the value of the EncodingMode property

    • setEncodingMode

      public void setEncodingMode​(String value)
      Sets the EncodingMode property; see getEncodingMode().
      Parameters:
      value - the new value (not null)

    • getFlags

      public String getFlags()
      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.

      Letter Bit value Microsoft flag name

      A 0x00000001 NTLMSSP_NEGOTIATE_UNICODE

      B 0x00000002 NTLM_NEGOTIATE_OEM

      C 0x00000004 NTLMSSP_REQUEST_TARGET

      D 0x00000010 NTLMSSP_NEGOTIATE_SIGN

      E 0x00000020 NTLMSSP_NEGOTIATE_SEAL

      F 0x00000040 NTLMSSP_NEGOTIATE_DATAGRAM

      G 0x00000080 NTLMSSP_NEGOTIATE_LM_KEY

      H 0x00000200 NTLMSSP_NEGOTIATE_NTLM

      I 0x00000400 Reserved / unused

      J 0x00000800 NTLMSSP_NEGOTIATE_ANONYMOUS

      K 0x00001000 NTLMSSP_NEGOTIATE_OEM_DOMAIN_SUPPLIED

      L 0x00002000 NTLMSSP_NEGOTIATE_OEM_WORKSTATION_SUPPLIED

      M 0x00008000 NTLMSSP_NEGOTIATE_ALWAYS_SIGN

      N 0x00010000 NTLMSSP_TARGET_TYPE_DOMAIN

      O 0x00020000 NTLMSSP_TARGET_TYPE_SERVER

      P 0x00040000 Reserved / unused

      Q 0x00080000 NTLMSSP_NEGOTIATE_EXTENDED_SESSIONSECURITY

      R 0x00100000 NTLMSSP_NEGOTIATE_IDENTIFY

      S 0x00400000 NTLMSSP_REQUEST_NON_NT_SESSION_KEY

      T 0x00800000 NTLMSSP_NEGOTIATE_TARGET_INFO

      U 0x02000000 NTLMSSP_NEGOTIATE_VERSION

      V 0x20000000 NTLMSSP_NEGOTIATE_128

      W 0x40000000 NTLMSSP_NEGOTIATE_KEY_EXCH

      X 0x80000000 NTLMSSP_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.

      Returns:
      the value of the Flags property

    • setFlags

      public void setFlags​(String value)
      Sets the Flags property; see getFlags().
      Parameters:
      value - the new value (not null)

    • getNetBiosComputerName

      public String getNetBiosComputerName()
      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.

      Returns:
      the value of the NetBiosComputerName property

    • setNetBiosComputerName

      public void setNetBiosComputerName​(String value)
      Sets the NetBiosComputerName property; see getNetBiosComputerName().
      Parameters:
      value - the new value (not null)

    • getNetBiosDomainName

      public String getNetBiosDomainName()
      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.

      Returns:
      the value of the NetBiosDomainName property

    • setNetBiosDomainName

      public void setNetBiosDomainName​(String value)
      Sets the NetBiosDomainName property; see getNetBiosDomainName().
      Parameters:
      value - the new value (not null)

    • getNtlmVersion

      public int getNtlmVersion()
      Selects the challenge-response algorithm used to generate and verify the authentication response.

      Value Behavior

      1 Use NTLMv1. This is the default for backward compatibility.

      2 Use 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.

      Returns:
      the value of the NtlmVersion property

    • setNtlmVersion

      public void setNtlmVersion​(int value)
      Sets the NtlmVersion property; see getNtlmVersion().
      Parameters:
      value - the new value

    • getOemCodePage

      public int getOemCodePage()
      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.

      Returns:
      the value of the OemCodePage property

    • setOemCodePage

      public void setOemCodePage​(int value)
      Sets the OemCodePage property; see getOemCodePage().
      Parameters:
      value - the new value

    • getPassword

      public String getPassword()
      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.

      Returns:
      the value of the Password property

    • setPassword

      public void setPassword​(String value)
      Sets the Password property; see getPassword().
      Parameters:
      value - the new value (not null)

    • getServerChallenge

      public String getServerChallenge()
      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.

      Returns:
      the value of the ServerChallenge property

    • setServerChallenge

      public void setServerChallenge​(String value)
      Sets the ServerChallenge property; see getServerChallenge().
      Parameters:
      value - the new value (not null)

    • getTargetName

      public String getTargetName()
      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.

      Returns:
      the value of the TargetName property

    • setTargetName

      public void setTargetName​(String value)
      Sets the TargetName property; see getTargetName().
      Parameters:
      value - the new value (not null)

    • getUserName

      public String getUserName()
      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.

      Returns:
      the value of the UserName property

    • setUserName

      public void setUserName​(String value)
      Sets the UserName property; see getUserName().
      Parameters:
      value - the new value (not null)

    • getWorkstation

      public String getWorkstation()
      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.
      Returns:
      the value of the Workstation property

    • setWorkstation

      public void setWorkstation​(String value)
      Sets the Workstation property; see getWorkstation().
      Parameters:
      value - the new value (not null)

    • compareType3

      public boolean 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.

      Parameters:
      msg1 - the msg1 argument (not null)
      msg2 - the msg2 argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • genType1

      public 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:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • genType2

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

      Parameters:
      type1Msg - the type1Msg argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • genType3

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

      Parameters:
      type2Msg - the type2Msg argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadType3

      public void 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.

      Parameters:
      type3Msg - the type3Msg argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • parseType1

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

      Parameters:
      type1Msg - the type1Msg argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • parseType2

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

      Parameters:
      type2Msg - the type2Msg argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • parseType3

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

      Parameters:
      type3Msg - the type3Msg argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setFlag

      public void setFlag​(String flagLetter, boolean 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.

      Parameters:
      flagLetter - the flagLetter argument (not null)
      onOrOff - the onOrOff argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why