--- product: Chilkat product_version: 11.7.0 language: vbnet language_label: VB.NET class: Ntlm license: bundle deprecated: false reference_html: https://www.chilkatsoft.com/refdoc/vbnetNtlmRef.html --- # Chilkat Ntlm — VB.NET — v11.7.0 > Chilkat 11.7.0 · language=vbnet · class=Ntlm > Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0//classes/Ntlm.md`. > Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/vbnet/guide.md`. ## Purpose **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, unlocking and error handling **Object Creation** ```vbnet Dim obj As New Chilkat.Ntlm() ``` Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in VB.NET. How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called. ## Members common to every Chilkat class Documented once per language in `common-members.md`; listed here so this page is self-contained. | Property | Signature | Access | Meaning | |---|---|---|---| | `DebugLogFilePath` | `DebugLogFilePath As String` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. | | `LastErrorHtml` | `LastErrorHtml As String (ReadOnly)` | read-only | Provides HTML-formatted information about the last called method or property. | | `LastErrorText` | `LastErrorText As String (ReadOnly)` | read-only | Provides plain text information about the last called method or property. | | `LastErrorXml` | `LastErrorXml As String (ReadOnly)` | read-only | Provides XML-formatted information about the last called method or property. | | `LastMethodSuccess` | `LastMethodSuccess As Boolean` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. | | `VerboseLogging` | `VerboseLogging As Boolean` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. | | `Version` | `Version As String (ReadOnly)` | read-only | Version of the component/library, such as "10.1.0" | ## Member index | Member | Kind | Signature | |---|---|---| | `ClientChallenge` | property, read/write | `ClientChallenge As String` | | `DnsComputerName` | property, read/write | `DnsComputerName As String` | | `DnsDomainName` | property, read/write | `DnsDomainName As String` | | `Domain` | property, read/write | `Domain As String` | | `EncodingMode` | property, read/write | `EncodingMode As String` | | `Flags` | property, read/write | `Flags As String` | | `NetBiosComputerName` | property, read/write | `NetBiosComputerName As String` | | `NetBiosDomainName` | property, read/write | `NetBiosDomainName As String` | | `NtlmVersion` | property, read/write | `NtlmVersion As Integer` | | `OemCodePage` | property, read/write | `OemCodePage As Integer` | | `Password` | property, read/write | `Password As String` | | `ServerChallenge` | property, read/write | `ServerChallenge As String` | | `TargetName` | property, read/write | `TargetName As String` | | `UserName` | property, read/write | `UserName As String` | | `Workstation` | property, read/write | `Workstation As String` | | `CompareType3` | method | `Function CompareType3(ByVal msg1 As String, ByVal msg2 As String) As Boolean` | | `GenType1` | method | `Function GenType1() As String` | | `GenType2` | method | `Function GenType2(ByVal type1Msg As String) As String` | | `GenType3` | method | `Function GenType3(ByVal type2Msg As String) As String` | | `LoadType3` | method | `Function LoadType3(ByVal type3Msg As String) As Boolean` | | `ParseType1` | method | `Function ParseType1(ByVal type1Msg As String) As String` | | `ParseType2` | method | `Function ParseType2(ByVal type2Msg As String) As String` | | `ParseType3` | method | `Function ParseType3(ByVal type3Msg As String) As String` | | `SetFlag` | method | `Function SetFlag(ByVal flagLetter As String, ByVal onOrOff As Boolean) As Boolean` | ## Properties ### Ntlm.ClientChallenge `Chilkat 11.7.0 · vbnet · Ntlm · ClientChallenge · property · read/write` ```vbnet ClientChallenge As String ``` 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. ### Ntlm.DnsComputerName `Chilkat 11.7.0 · vbnet · Ntlm · DnsComputerName · property · read/write` ```vbnet DnsComputerName As String ``` 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. ### Ntlm.DnsDomainName `Chilkat 11.7.0 · vbnet · Ntlm · DnsDomainName · property · read/write` ```vbnet DnsDomainName As String ``` 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. ### Ntlm.Domain `Chilkat 11.7.0 · vbnet · Ntlm · Domain · property · read/write` ```vbnet Domain As String ``` 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. ### Ntlm.EncodingMode `Chilkat 11.7.0 · vbnet · Ntlm · EncodingMode · property · read/write` ```vbnet EncodingMode As String ``` 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. ### Ntlm.Flags `Chilkat 11.7.0 · vbnet · Ntlm · Flags · property · read/write` ```vbnet Flags As String ``` 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. ### Ntlm.NetBiosComputerName `Chilkat 11.7.0 · vbnet · Ntlm · NetBiosComputerName · property · read/write` ```vbnet NetBiosComputerName As String ``` 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. ### Ntlm.NetBiosDomainName `Chilkat 11.7.0 · vbnet · Ntlm · NetBiosDomainName · property · read/write` ```vbnet NetBiosDomainName As String ``` 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. ### Ntlm.NtlmVersion `Chilkat 11.7.0 · vbnet · Ntlm · NtlmVersion · property · read/write` ```vbnet NtlmVersion As Integer ``` 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. ### Ntlm.OemCodePage `Chilkat 11.7.0 · vbnet · Ntlm · OemCodePage · property · read/write` ```vbnet OemCodePage As Integer ``` 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. ### Ntlm.Password `Chilkat 11.7.0 · vbnet · Ntlm · Password · property · read/write` ```vbnet Password As String ``` 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. ### Ntlm.ServerChallenge `Chilkat 11.7.0 · vbnet · Ntlm · ServerChallenge · property · read/write` ```vbnet ServerChallenge As String ``` 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. ### Ntlm.TargetName `Chilkat 11.7.0 · vbnet · Ntlm · TargetName · property · read/write` ```vbnet TargetName As String ``` 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. ### Ntlm.UserName `Chilkat 11.7.0 · vbnet · Ntlm · UserName · property · read/write` ```vbnet UserName As String ``` 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. ### Ntlm.Workstation `Chilkat 11.7.0 · vbnet · Ntlm · Workstation · property · read/write` ```vbnet Workstation As String ``` 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. ## Methods ### Ntlm.CompareType3 `Chilkat 11.7.0 · vbnet · Ntlm · CompareType3 · method` ```vbnet Function CompareType3(ByVal msg1 As String, ByVal msg2 As String) As Boolean ``` 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. ### Ntlm.GenType1 `Chilkat 11.7.0 · vbnet · Ntlm · GenType1 · method` ```vbnet Function GenType1() As String ``` 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 `Nothing` on failure ### Ntlm.GenType2 `Chilkat 11.7.0 · vbnet · Ntlm · GenType2 · method` ```vbnet Function GenType2(ByVal type1Msg As String) As String ``` 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 `Nothing` on failure ### Ntlm.GenType3 `Chilkat 11.7.0 · vbnet · Ntlm · GenType3 · method` ```vbnet Function GenType3(ByVal type2Msg As String) As String ``` 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 `Nothing` on failure ### Ntlm.LoadType3 `Chilkat 11.7.0 · vbnet · Ntlm · LoadType3 · method` ```vbnet Function LoadType3(ByVal type3Msg As String) As Boolean ``` 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. ### Ntlm.ParseType1 `Chilkat 11.7.0 · vbnet · Ntlm · ParseType1 · method` ```vbnet Function ParseType1(ByVal type1Msg As String) As String ``` 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 `Nothing` on failure ### Ntlm.ParseType2 `Chilkat 11.7.0 · vbnet · Ntlm · ParseType2 · method` ```vbnet Function ParseType2(ByVal type2Msg As String) As String ``` 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 `Nothing` on failure ### Ntlm.ParseType3 `Chilkat 11.7.0 · vbnet · Ntlm · ParseType3 · method` ```vbnet Function ParseType3(ByVal type3Msg As String) As String ``` 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 `Nothing` on failure ### Ntlm.SetFlag `Chilkat 11.7.0 · vbnet · Ntlm · SetFlag · method` ```vbnet Function SetFlag(ByVal flagLetter As String, ByVal onOrOff As Boolean) As Boolean ``` 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.