NTLM Component

Properties   Methods   Events   Config Settings   Errors  

The NTLM component provides a simple API to create the required tokens for NTLM authentication.

Syntax

nsoftware.IPWorksAuth.Ntlm

Remarks

This component provides a simple API to create the required tokens for NTLM authentication.

The NTLM authentication process is a challenge-response scheme which consists of three messages. These three messages are the negotiation, challenge, and authentication. This component implements only the client side of NTLM and will create the negotiation and authentication tokens. The component does not transmit any data, it simply prepares the tokens for use in other transport protocols such as HTTP. The following steps describe how the component is used.

Create the Negotiate Token

To begin first set User and Password. The user value may contain domain information in the format "DOMAIN\User" or "user@domain". Next call CreateNegotiateToken to populate NegotiateToken. This token may then be transmitted separately. For instance in HTTP this would be sent in a request within the Authorization header: HTTPHeader = "Authorization: NTLM " + NegotiateToken

Create the Auth Token

After sending the negotiate token over the chosen transport protocol, the server will respond with a challenge token. Set ChallengeToken to the token received from the server. For instance, in HTTP the server will respond with the challenge token in the WWW-Authenticate header:

WWW-Authenticate: NTLM <ChallengeToken>

Note: If the server requires EPA (Extended Protection for Authentication), then SSLServerCert must be set to the server's public certificate before calling CreateAuthToken.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

AuthToken Property (NTLM Component)

The authentication token.

Syntax

• C#
• VB.NET

public string AuthToken { get; }
public byte[] AuthTokenB { get; }

Public ReadOnly Property AuthToken As String
Public ReadOnly Property AuthTokenB As Byte()

Default Value

""

Remarks

This property holds the created authentication token. This property is populated after calling CreateAuthToken.

Note: By default this value is Base64 encoded. Set EncodeToken to False before calling CreateAuthToken to obtain the raw value.

This property is read-only.

ChallengeToken Property (NTLM Component)

The challenge token.

Syntax

• C#
• VB.NET

public string ChallengeToken { get; set; }
public byte[] ChallengeTokenB { get; set; }

Public Property ChallengeToken As String
Public Property ChallengeTokenB As Byte()

Default Value

""

Remarks

This property specifies the challenge token. This must be set to the challenge token received from the server before calling CreateAuthToken.

Note: By default the component expects the token to be Base64 encoded. To provide a raw value to this property first set DecodeToken to False.

NegotiateToken Property (NTLM Component)

The negotiate token.

Syntax

• C#
• VB.NET

public string NegotiateToken { get; }
public byte[] NegotiateTokenB { get; }

Public ReadOnly Property NegotiateToken As String
Public ReadOnly Property NegotiateTokenB As Byte()

Default Value

""

Remarks

This property is populated after calling CreateNegotiateToken. By default the value is Base64 encoded. To obtain the raw value set EncodeToken to False before calling CreateNegotiateToken.

This property is read-only.

NTLMVersion Property (NTLM Component)

The NTLM version.

Syntax

• C#
• VB.NET

public NtlmNTLMVersions NTLMVersion { get; set; }

enum NtlmNTLMVersions {
  ntNTLMv1,
  ntNTLMv2
}

Public Property NTLMVersion As NtlmNTLMVersions

Enum NtlmNTLMVersions
  ntNTLMv1
  ntNTLMv2
End Enum

Default Value

1

Remarks

This property specifies the NTLM version to use. Possible values are:

• 1 (ntNTLMv1 - default)
• 2 (ntNTLMv2)

Note: If the server requires EPA (Extended Protection for Authentication) this property must be set to 2 (ntNTLMv2).

Password Property (NTLM Component)

The user's password.

Syntax

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

Default Value

""

Remarks

This property specifies the user's password.

SSLServerCert Property (NTLM Component)

The server's public certificate.

Syntax

• C#
• VB.NET

public Certificate SSLServerCert { get; set; }

Public Property SSLServerCert As Certificate

Remarks

This property specifies the server's public certificate. This must be set if the server requires EPA (Extended Protection for Authentication).

User Property (NTLM Component)

The user.

Syntax

• C#
• VB.NET

public string User { get; set; }

Public Property User As String

Default Value

""

Remarks

This property specifies the name and realm/domain of the user. The value specified must be in one of the following formats:

• user
• domain/user

Config Method (NTLM Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateAuthToken Method (NTLM Component)

Creates the authentication token.

Syntax

• C#
• VB.NET

public void CreateAuthToken();

Async Version
public async Task CreateAuthToken();
public async Task CreateAuthToken(CancellationToken cancellationToken);

Public Sub CreateAuthToken()

Async Version
Public Sub CreateAuthToken() As Task
Public Sub CreateAuthToken(cancellationToken As CancellationToken) As Task

Remarks

This method creates the authentication token. After calling this method the AuthToken property will be populated. The following properties are applicable when calling this method:

• User (required)
• Password (required)
• ChallengeToken (required)
• SSLServerCert
• NTLMVersion

Note: SSLServerCert must be set to the server's public certificate if the server requires EPA (Extended Protection for Authentication).

CreateNegotiateToken Method (NTLM Component)

Creates the negotiate token.

Syntax

• C#
• VB.NET

public void CreateNegotiateToken();

Async Version
public async Task CreateNegotiateToken();
public async Task CreateNegotiateToken(CancellationToken cancellationToken);

Public Sub CreateNegotiateToken()

Async Version
Public Sub CreateNegotiateToken() As Task
Public Sub CreateNegotiateToken(cancellationToken As CancellationToken) As Task

Remarks

This method creates the negotiate token. After calling this method the NegotiateToken property is populated. The following properties are applicable when calling this method:

• User (required)
• Password (required)
• NTLMVersion

Reset Method (NTLM Component)

Resets the component

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

When called, the component will reset all of its properties to their default values.

Error Event (NTLM Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, NtlmErrorEventArgs e);

public class NtlmErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As NtlmErrorEventArgs)

Public Class NtlmErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X509 public key.

• C#
• VB.NET

public Certificate(byte[] certificateData);

Public Certificate(ByVal CertificateData As Byte())

Parses CertificateData as an X509 public key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CyrptoAPI option. The default value is True (the key is persisted). "Thumbprint" - a MD5, SHA1, or SHA256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

Config Settings (NTLM Component)

NTLM Config Settings

Base Config Settings

Trappable Errors (NTLM Component)

NTLM Errors