Authenticator Component

Properties   Methods   Events   Config Settings   Errors  

The Authenticator component specializes in user authentication.

Syntax

nsoftware.SecureBlackbox.Authenticator

Remarks

Authenticator provides capabilities for implementing the authenticating party (as opposed to the one being authenticated) of the authentication protocol.

Authenticator can be used in a variety of authentication scenarios, ranging from simple password checks to complicated multi-factor variants. It also supports authentication via a SBB-own DC protocol, which makes it a good pair for DCAuth control.

In default configuration the component uses the attached database of users to handle authentication requests. The authentication flow can be altered if needed to match specific authentication requirements.

In Authenticator's terms, the authentication process is divided into a sequence of atomic steps. Each step is characterized by a user providing an authentication token - such as a password or PIN - and the authenticator validating that token. Each validation step may result in one of the following outcomes:

• Authentication succeeded: the authentication has been completed with the positive outcome;
• Authentication failed: the authentication process has failed, the user didn't provide enough evidence to confirm they are who they claim they are;
• Further authentication is required: the authentication was partly successful, but the settings of the component or user details require further step(s) to be taken.

Use the following logic when integrating the Authenticator into your project:

• Whenever you receive an authentication request from a user, call the StartAuth method, passing the UserID as a parameter. This initiates the authentication procedure: the Authenticator control looks up the user in the Users database and picks the first authentication method. It then returns the Further authentication is required result and stores the details of the first authentication step in AuthInfo property. Apart from the information about the authentication method that is to be performed during this step, AuthInfo also contains a STATE> value, which accumulates parameters and progress of the user's authentication flow. You can save the state value on this stage, and restore it later when a response from the user is received. With that in mind, component is stateless; you can save the current authentication state in a database, and return to it from a different context.
• Now that you have obtained Further authentication needed from StartAuth, it's time to check the AUTHMETHOD> and request the corresponding token from the user. For example, if the method is 'password', you may present the user with a password dialog.
• Upon receiving a password (or other kind of authentication token) from the user, pass it to the ContinueAuth method, together with the state object that you saved on the preceding step. The component will process the token and come up with one of the three results given above, signifying the end of the first authentication step. If Further authentication is required result is returned, another authentication step needs to be performed (either because a multi-factor authentication is configured for this user, or because an alternative authentication method was chosen following failure of the previous attempt). If that is the case, follow the guidance for StartAuth-initiated step above.

  Depending on the settings, many authentication steps may need to be performed, so your code may ultimately end up calling ContinueAuth many times.

component can be customized to use external user information sources instead of a predefined user database. AuthStart, AuthVerify, and AuthAttemptResult events provide an opportunity for your code to intervene into the authentication process by defining your own authentication procedures and validating authentication tokens manually.

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.

AuthInfo Property (Authenticator Component)

Contains details of the current authentication step.

Syntax

• C#
• VB.NET

public AuthInfo AuthInfo { get; }

Public ReadOnly Property AuthInfo As AuthInfo

Remarks

Check this object to get details about the current authentication step, such as authentication method, its parameters, the overall authentication state, and information about completed and pending authentication methods.

This property is read-only and not available at design time.

BlockedCertificates Property (Authenticator Component)

The certificates that must be rejected as trust anchors.

Syntax

• C#
• VB.NET

public CertificateList BlockedCertificates { get; }

Public Property BlockedCertificates As CertificateList

Remarks

Use this property to provide a list of compromised or blocked certificates. Any chain containing a blocked certificate will fail validation.

This property is not available at design time.

Certificates Property (Authenticator Component)

A collection of certificates included in the electronic signature.

Syntax

• C#
• VB.NET

public CertificateList Certificates { get; }

Public ReadOnly Property Certificates As CertificateList

Remarks

Use this property to access all certificates included into the signature(s) by its creator.

This property is read-only and not available at design time.

ChainValidationDetails Property (Authenticator Component)

The details of a certificate chain validation outcome.

Syntax

• C#
• VB.NET

public int ChainValidationDetails { get; }

Public ReadOnly Property ChainValidationDetails As Integer

Default Value

0

Remarks

Use the value(s) returned by this property to identify the reasons that contributed to the overall validation result.

Returns a bit mask of the following options:

This property is read-only and not available at design time.

ChainValidationResult Property (Authenticator Component)

The general outcome of a certificate chain validation routine. Use ChainValidationDetails to get information about the reasons that contributed to the validation result.

Syntax

• C#
• VB.NET

public AuthenticatorChainValidationResults ChainValidationResult { get; }

enum AuthenticatorChainValidationResults {
  cvtValid,
  cvtValidButUntrusted,
  cvtInvalid,
  cvtCantBeEstablished
}

Public ReadOnly Property ChainValidationResult As AuthenticatorChainValidationResults

Enum AuthenticatorChainValidationResults
  cvtValid
  cvtValidButUntrusted
  cvtInvalid
  cvtCantBeEstablished
End Enum

Default Value

0

Remarks

Available options:

Use the ValidationLog property to access the detailed validation log.

This property is read-only and not available at design time.

DefaultAuthMethods Property (Authenticator Component)

Contains the list of default authentication methods.

Syntax

• C#
• VB.NET

public string DefaultAuthMethods { get; set; }

Public Property DefaultAuthMethods As String

Default Value

""

Remarks

Use this property to specify a list of default authentication methods to apply to users that are not included in the Users database. Assign this property with a comma-separated list of standard and custom authentication methods.

The following standard authentication methods are supported by the component:

• password
• otp-h
• otp-t
• dcauth

You can use any names not clashing with the standard methods to indicate your own custom authentication methods. Use CustomAuthStart and AuthVerify events to handle custom authentication methods.

ExternalCrypto Property (Authenticator Component)

Provides access to external signing and DC parameters.

Syntax

• C#
• VB.NET

public ExternalCrypto ExternalCrypto { get; }

Public ReadOnly Property ExternalCrypto As ExternalCrypto

Remarks

Use this property to tune-up remote cryptography settings. SecureBlackbox supports two independent types of external cryptography: synchronous (based on the ExternalSign event) and asynchronous (based on the DC protocol and the DCAuth signing component).

This property is read-only.

FIPSMode Property (Authenticator Component)

Reserved.

Syntax

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

Default Value

False

Remarks

This property is reserved for future use.

IgnoreChainValidationErrors Property (Authenticator Component)

Makes the component tolerant to chain validation errors.

Syntax

• C#
• VB.NET

public bool IgnoreChainValidationErrors { get; set; }

Public Property IgnoreChainValidationErrors As Boolean

Default Value

False

Remarks

If this property is set to True, any errors emerging during certificate chain validation will be ignored. This setting may be handy if the purpose of validation is the creation of an LTV signature, and the validation is performed in an environment that doesn't trust the signer's certificate chain.

KnownCertificates Property (Authenticator Component)

Additional certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList KnownCertificates { get; }

Public Property KnownCertificates As CertificateList

Remarks

Use this property to supply a list of additional certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of the certificates to be added to this collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Do not add trust anchors or root certificates to this collection: add them to TrustedCertificates instead.

This property is not available at design time.

KnownCRLs Property (Authenticator Component)

Additional CRLs for chain validation.

Syntax

• C#
• VB.NET

public CRLList KnownCRLs { get; }

Public Property KnownCRLs As CRLList

Remarks

Use this property to supply additional CRLs that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated CRLs are stored separately from the signed message or document.

This property is not available at design time.

KnownOCSPs Property (Authenticator Component)

Additional OCSP responses for chain validation.

Syntax

• C#
• VB.NET

public OCSPResponseList KnownOCSPs { get; }

Public Property KnownOCSPs As OCSPResponseList

Remarks

Use this property to supply additional OCSP responses that might be needed for chain validation. This property may be helpful when a chain is validated in offline mode, and the associated OCSP responses are stored separately from the signed message or document.

This property is not available at design time.

OfflineMode Property (Authenticator Component)

Switches the component to offline mode.

Syntax

• C#
• VB.NET

public bool OfflineMode { get; set; }

Public Property OfflineMode As Boolean

Default Value

False

Remarks

When working in offline mode, the component restricts itself from using any online revocation information sources, such as CRL or OCSP responders.

Offline mode may be useful if there is a need to verify the completeness of the validation information included within the signature or provided via KnownCertificates, KnownCRLs, and other related properties.

Proxy Property (Authenticator Component)

The proxy server settings.

Syntax

• C#
• VB.NET

public ProxySettings Proxy { get; }

Public ReadOnly Property Proxy As ProxySettings

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

RevocationCheck Property (Authenticator Component)

Specifies the kind(s) of revocation check to perform for all chain certificates.

Syntax

• C#
• VB.NET

public AuthenticatorRevocationChecks RevocationCheck { get; set; }

enum AuthenticatorRevocationChecks {
  crcNone,
  crcAuto,
  crcAllCRL,
  crcAllOCSP,
  crcAllCRLAndOCSP,
  crcAnyCRL,
  crcAnyOCSP,
  crcAnyCRLOrOCSP,
  crcAnyOCSPOrCRL
}

Public Property RevocationCheck As AuthenticatorRevocationChecks

Enum AuthenticatorRevocationChecks
  crcNone
  crcAuto
  crcAllCRL
  crcAllOCSP
  crcAllCRLAndOCSP
  crcAnyCRL
  crcAnyOCSP
  crcAnyCRLOrOCSP
  crcAnyOCSPOrCRL
End Enum

Default Value

1

Remarks

Revocation checking is necessary to ensure the integrity of the chain and obtain up-to-date certificate validity and trustworthiness information.

Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) responses serve the same purpose of ensuring that the certificate had not been revoked by the Certificate Authority (CA) at the time of use. Depending on your circumstances and security policy requirements, you may want to use either one or both of the revocation information source types.

This setting controls the way the revocation checks are performed for every certificate in the chain. Typically certificates come with two types of revocation information sources: CRL (certificate revocation lists) and OCSP responders. CRLs are static objects periodically published by the CA at some online location. OCSP responders are active online services maintained by the CA that can provide up-to-date information on certificate statuses in near real time.

There are some conceptual differences between the two. CRLs are normally larger in size. Their use involves some latency because there is normally some delay between the time when a certificate was revoked and the time the subsequent CRL mentioning that is published. The benefits of CRL is that the same object can provide statuses for all certificates issued by a particular CA, and that the whole technology is much simpler than OCSP (and thus is supported by more CAs).

This setting lets you adjust the validation course by including or excluding certain types of revocation sources from the validation process. The crcAnyOCSPOrCRL setting (give preference to the faster OCSP route and only demand one source to succeed) is a good choice for most typical validation environments. The "crcAll*" modes are much stricter, and may be used in scenarios where bulletproof validity information is essential.

Note: If no CRL or OCSP endpoints are provided by the CA, the revocation check will be considered successful. This is because the CA chose not to supply revocation information for its certificates, meaning they are considered irrevocable.

Note: Within each of the above settings, if any retrieved CRL or OCSP response indicates that the certificate has been revoked, the revocation check fails.

SigningCertificate Property (Authenticator Component)

The certificate to be used for signing.

Syntax

• C#
• VB.NET

public Certificate SigningCertificate { get; set; }

Public Property SigningCertificate As Certificate

Remarks

Use this property to specify the certificate that shall be used for signing the data. Note that this certificate should have a private key associated with it. Use SigningChain to supply the rest of the certificate chain for inclusion into the signature.

This property is not available at design time.

SocketSettings Property (Authenticator Component)

Manages network connection settings.

Syntax

• C#
• VB.NET

public SocketSettings SocketSettings { get; }

Public ReadOnly Property SocketSettings As SocketSettings

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

TLSSettings Property (Authenticator Component)

Manages TLS layer settings.

Syntax

• C#
• VB.NET

public TLSSettings TLSSettings { get; }

Public ReadOnly Property TLSSettings As TLSSettings

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

TrustedCertificates Property (Authenticator Component)

A list of trusted certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList TrustedCertificates { get; }

Public Property TrustedCertificates As CertificateList

Remarks

Use this property to supply a list of trusted certificates that might be needed for chain validation. An example of a scenario where you might want to do that is when root CA certificates are absent from the standard system locations (or when there are no standard system locations), and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the trusted list may result in bad chains being accepted, and forfeited signatures being recognized as genuine. Only add certificates that originate from the parties that you know and trust.

This property is not available at design time.

Users Property (Authenticator Component)

A collection of known users along with their authentication settings.

Syntax

• C#
• VB.NET

public UserAccountList Users { get; }

Public Property Users As UserAccountList

Remarks

Use this property to access the database of known users and their authentication details.

This property is not available at design time.

ValidationLog Property (Authenticator Component)

Contains the complete log of the certificate validation routine.

Syntax

• C#
• VB.NET

public string ValidationLog { get; }

Public ReadOnly Property ValidationLog As String

Default Value

""

Remarks

Use this property to access the chain validation log produced by the component. The log can be very useful when investigating issues with chain validation, as it contains a step-by-step trace of the entire validation procedure.

This property is read-only and not available at design time.

ValidationMoment Property (Authenticator Component)

The time point at which signature validity is to be established.

Syntax

• C#
• VB.NET

public string ValidationMoment { get; set; }

Public Property ValidationMoment As String

Default Value

""

Remarks

Use this property to specify the moment in time at which signature validity should be established. The time is in UTC. Leave the setting empty to stick to the default moment (either the signature creation time or the current time).

The validity of the same signature may differ depending on the time point chosen due to temporal changes in chain validities, revocation statuses, and timestamp times.

Config Method (Authenticator Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As 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.

ContinueAuth Method (Authenticator Component)

Call this method to process an authentication token and proceed to the next authentication step.

Syntax

• C#
• VB.NET

public int ContinueAuth(string state, string authToken);

Public Function ContinueAuth(ByVal State As String, ByVal AuthToken As String) As Integer

Remarks

Call this method upon receiving an authentication token from the user to validate it and proceed to the next authentication step (or complete the authentication).

Pass the authentication state blob that you obtained at the beginning of the authentication step to the State parameter, and the authentication credential received from the user to the AuthToken parameter. The method will validate the token and return one of the following results:

The further authentication needed result indicates that the user is expected to go through at least one more authentication step. Check AuthInfo property to find out which authentication method should be used on that step, and request the relevant authentication token from the user. Upon receiving that new token, call ContinueAuth again - and continue running this loop until authentication succeeded or authentication failed result is returned.

DoAction Method (Authenticator Component)

Performs an additional action.

Syntax

• C#
• VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As String

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

StartAuth Method (Authenticator Component)

Initiates an authentication process.

Syntax

• C#
• VB.NET

public int StartAuth(string userID);

Public Function StartAuth(ByVal UserID As String) As Integer

Remarks

Call this method to start an authentication process for UserID.

The authentication process may consist of multiple atomic steps. Each step represents a single authentication transaction, such as provision of a password, a PIN, or a one-time token. The exact authentication step sequence for the user is chosen according to the following rules:

• If the user is found in the Users database, all authentication methods specified for that user are activated;
• otherwise, the methods assigned to DefaultAuthMethods are activated;
• AuthStart event is thrown, allowing the application to tune up the selection of authentication methods if needed.
• the first method from the list is initiated.

This method may return one of the three results:

The authentication succeeded result is returned if the authentication method selection procedure completed with an empty method list. A typical result of this method though is further authentication required, which indicates that the next authentication method has kicked off. Use rpAuthInfo; property to find out which authentication method should be used on this step, and solicit the relevant authentication token from the user. Pass the received token to the ContinueAuth method for validation.

AuthAttemptResult Event (Authenticator Component)

Reports the outcome of an authentication attempt.

Syntax

• C#
• VB.NET

public event OnAuthAttemptResultHandler OnAuthAttemptResult;

public delegate void OnAuthAttemptResultHandler(object sender, AuthenticatorAuthAttemptResultEventArgs e);

public class AuthenticatorAuthAttemptResultEventArgs : EventArgs {
  public string UserID { get; }
  public string AuthMethod { get; }
  public int AuthRes { get; set; }
  public string RemainingAuthMethods { get; set; }
}

Public Event OnAuthAttemptResult As OnAuthAttemptResultHandler

Public Delegate Sub OnAuthAttemptResultHandler(sender As Object, e As AuthenticatorAuthAttemptResultEventArgs)

Public Class AuthenticatorAuthAttemptResultEventArgs Inherits EventArgs
  Public ReadOnly Property UserID As String
  Public ReadOnly Property AuthMethod As String
  Public Property AuthRes As Integer
  Public Property RemainingAuthMethods As String
End Class

Remarks

This event follows a call to ContinueAuth method and reports the user's updated authentication status following the token verification.

The updated status is reported via the AuthRes parameter, and can take one of the following values:

The RemainingAuthMethods parameter lists the authentication methods that the user is yet to go through. The application can change either of AuthRes and RemainingAuthMethods in the event handler to alter the authentication flow.

AuthAttemptStart Event (Authenticator Component)

Signifies the start of an authentication attempt.

Syntax

• C#
• VB.NET

public event OnAuthAttemptStartHandler OnAuthAttemptStart;

public delegate void OnAuthAttemptStartHandler(object sender, AuthenticatorAuthAttemptStartEventArgs e);

public class AuthenticatorAuthAttemptStartEventArgs : EventArgs {
  public string UserID { get; }
  public string AuthMethod { get; }
  public string RemainingAuthMethods { get; }
}

Public Event OnAuthAttemptStart As OnAuthAttemptStartHandler

Public Delegate Sub OnAuthAttemptStartHandler(sender As Object, e As AuthenticatorAuthAttemptStartEventArgs)

Public Class AuthenticatorAuthAttemptStartEventArgs Inherits EventArgs
  Public ReadOnly Property UserID As String
  Public ReadOnly Property AuthMethod As String
  Public ReadOnly Property RemainingAuthMethods As String
End Class

Remarks

This event reports the start of an atomic authentication step. The AuthMethod parameter contains the authentication method that has started. The following authentication methods are currently supported, but the application may define its own methods in AuthStart, and tune them up in CustomAuthStart:

• password
• otp-h
• otp-t
• dcauth

This event is thrown from StartAuth and ContinueAuth methods.

AuthStart Event (Authenticator Component)

Signifies the start of an authentication process.

Syntax

• C#
• VB.NET

public event OnAuthStartHandler OnAuthStart;

public delegate void OnAuthStartHandler(object sender, AuthenticatorAuthStartEventArgs e);

public class AuthenticatorAuthStartEventArgs : EventArgs {
  public string UserID { get; }
  public string AuthMethods { get; set; }
}

Public Event OnAuthStart As OnAuthStartHandler

Public Delegate Sub OnAuthStartHandler(sender As Object, e As AuthenticatorAuthStartEventArgs)

Public Class AuthenticatorAuthStartEventArgs Inherits EventArgs
  Public ReadOnly Property UserID As String
  Public Property AuthMethods As String
End Class

Remarks

This event is fired in response to a StartAuth call, and signifies the start of a (potentially, multi-step) authentication process for UserID. The AuthMethods parameter list the methods to be performed for the user. The application may customize them as needed.

The following default authentication methods are supported:

• password
• otp-h
• otp-t
• dcauth

The application can define its own authentication methods if needed.

This event is only fired once per user authentication process, at the very start of it. See AuthAttemptStart for per-step notification.

AuthVerify Event (Authenticator Component)

Requests the application to validate an authentication token.

Syntax

• C#
• VB.NET

public event OnAuthVerifyHandler OnAuthVerify;

public delegate void OnAuthVerifyHandler(object sender, AuthenticatorAuthVerifyEventArgs e);

public class AuthenticatorAuthVerifyEventArgs : EventArgs {
  public string UserID { get; }
  public string AuthMethod { get; }
  public string AuthToken { get; }
  public string AuthMethodData { get; }
  public bool Valid { get; set; }
}

Public Event OnAuthVerify As OnAuthVerifyHandler

Public Delegate Sub OnAuthVerifyHandler(sender As Object, e As AuthenticatorAuthVerifyEventArgs)

Public Class AuthenticatorAuthVerifyEventArgs Inherits EventArgs
  Public ReadOnly Property UserID As String
  Public ReadOnly Property AuthMethod As String
  Public ReadOnly Property AuthToken As String
  Public ReadOnly Property AuthMethodData As String
  Public Property Valid As Boolean
End Class

Remarks

Component fires this event to ask the application to validate an authentication token that it can't validate automatically. This can happen if UserID was not found in the user database or a custom authentication method is used.

AuthMethod and AuthToken specify the authentication method being used and the authentication token provided by the user. AuthMethodData contains an application-specific data provided by the application at the beginning of the authentication step.

An event handler subscribed to this event should validate the authentication token provided by the user and set the Valid parameter accordingly.

CustomAuthStart Event (Authenticator Component)

Reports the beginning of a custom authentication method.

Syntax

• C#
• VB.NET

public event OnCustomAuthStartHandler OnCustomAuthStart;

public delegate void OnCustomAuthStartHandler(object sender, AuthenticatorCustomAuthStartEventArgs e);

public class AuthenticatorCustomAuthStartEventArgs : EventArgs {
  public string UserID { get; }
  public string AuthMethod { get; }
  public string AuthMethodPars { get; set; }
  public string AuthMethodData { get; set; }
}

Public Event OnCustomAuthStart As OnCustomAuthStartHandler

Public Delegate Sub OnCustomAuthStartHandler(sender As Object, e As AuthenticatorCustomAuthStartEventArgs)

Public Class AuthenticatorCustomAuthStartEventArgs Inherits EventArgs
  Public ReadOnly Property UserID As String
  Public ReadOnly Property AuthMethod As String
  Public Property AuthMethodPars As String
  Public Property AuthMethodData As String
End Class

Remarks

This event marks the start of an authentication method not supported by component internally and requests authentication parameters from the application.

Component currently supports the following authentication methods:

• password
• otp-h
• otp-t
• dcauth

The application may also use any number of custom authentication method it wants. Each such method is identified by a unique string name (such as 'pin', 'fingerprint', or 'fingerprint-v2'). It may specify them in DefaultAuthMethods property, or provide on the fly via AuthStart event.

The event handler may return authentication parameters and application-specific data to be associated with the authentication attempt via AuthMethodPars and AuthMethodData parameters.

Error Event (Authenticator Component)

Reports information about errors during authentication.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

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

Remarks

The event is fired in case of exceptional conditions during user authentication.

ErrorCode contains an error code and Description contains a textual description of the error.

Notification Event (Authenticator Component)

This event notifies the application about an underlying control flow event.

Syntax

• C#
• VB.NET

public event OnNotificationHandler OnNotification;

public delegate void OnNotificationHandler(object sender, AuthenticatorNotificationEventArgs e);

public class AuthenticatorNotificationEventArgs : EventArgs {
  public string EventID { get; }
  public string EventParam { get; }
}

Public Event OnNotification As OnNotificationHandler

Public Delegate Sub OnNotificationHandler(sender As Object, e As AuthenticatorNotificationEventArgs)

Public Class AuthenticatorNotificationEventArgs Inherits EventArgs
  Public ReadOnly Property EventID As String
  Public ReadOnly Property EventParam As String
End Class

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

AuthInfo Type

A container for authentication step information.

Remarks

AuthInfo objects are used to store current authentication information, such as userid and state.

Fields

Constructors

• C#
• VB.NET

public AuthInfo();

Public AuthInfo()

Creates a new AuthInfo object.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

• C#
• VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a new object with default field values.

CRL Type

Represents a Certificate Revocation List.

Remarks

CRLs store information about revoked certificates, i.e., certificates that have been identified as invalid by their issuing certificate authority (CA) for any number of reasons.

Each CRL object lists certificates from a single CA and identifies them by their serial numbers. A CA may or may not publish a CRL, may publish several CRLs, or may publish the same CRL in multiple locations.

Unlike OCSP responses, CRLs only list certificates that have been revoked. They do not list certificates that are still valid.

Fields

Constructors

• C#
• VB.NET

public CRL(byte[] bytes, int startIndex, int count);

Public CRL(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Creates a CRL object from a memory buffer. Bytes is a buffer containing raw (DER) CRL data, StartIndex and Count specify the starting position and the length of the CRL data in the buffer, respectively.

• C#
• VB.NET

public CRL(string location);

Public CRL(ByVal Location As String)

Creates a CRL object by downloading it from a remote location.

• C#
• VB.NET

public CRL(System.IO.Stream stream);

Public CRL(ByVal Stream As System.IO.Stream)

Creates a CRL object from data contained in a stream.

• C#
• VB.NET

public CRL();

Public CRL()

Creates an empty CRL object.

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Remarks

External cryptocalls are used in a Distributed Cryptography (DC) subsystem, which allows the delegation of security operations to the remote agent. For instance, it can be used to compute the signature value on the server, while retaining the client's private key locally.

Fields

Constructors

• C#
• VB.NET

public ExternalCrypto();

Public ExternalCrypto()

Creates a new ExternalCrypto object with default field values.

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Remarks

OCSP is a protocol that allows verification of certificate status in real-time, and is an alternative to Certificate Revocation Lists (CRLs).

An OCSP response is a snapshot of the certificate status at a given time.

Fields

Constructors

• C#
• VB.NET

public OCSPResponse(byte[] bytes, int startIndex, int count);

Public OCSPResponse(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Initializes the response from a memory buffer. Bytes is a buffer containing raw OCSP response data, StartIndex and Count specify the starting position and the number of bytes to be read from this buffer.

• C#
• VB.NET

public OCSPResponse(string location);

Public OCSPResponse(ByVal Location As String)

Downloads an OCSP response from a remote location.

• C#
• VB.NET

public OCSPResponse(System.IO.Stream stream);

Public OCSPResponse(ByVal Stream As System.IO.Stream)

Initializes the response with the data from a stream.

• C#
• VB.NET

public OCSPResponse();

Public OCSPResponse()

Creates an empty OCSP response object.

ProxySettings Type

A container for proxy server settings.

Remarks

This type exposes a collection of properties for tuning up the proxy server configuration.

Fields

Constructors

• C#
• VB.NET

public ProxySettings();

Public ProxySettings()

Creates a new ProxySettings object.

SocketSettings Type

A container for the socket settings.

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

• C#
• VB.NET

public SocketSettings();

Public SocketSettings()

Creates a new SocketSettings object.

TLSSettings Type

A container for TLS connection settings.

Remarks

The TLS (Transport Layer Security) protocol provides security for information exchanged over insecure connections such as TCP/IP.

Fields

Constructors

• C#
• VB.NET

public TLSSettings();

Public TLSSettings()

Creates a new TLSSettings object.

UserAccount Type

A container for user account information.

Remarks

UserAccount objects are used to store user account information, such as logins and passwords.

Fields

Constructors

• C#
• VB.NET

public UserAccount();

Public UserAccount()

Creates a new UserAccount object.

Config Settings (Authenticator Component)

DCAuthenticator Config Settings

Base Config Settings

Trappable Errors (Authenticator Component)