DCAuth Component

Properties   Methods   Events   Config Settings   Errors  

The DCAuth component represents the private key side of the SecureBlackbox distributed cryptography protocol.

Syntax

nsoftware.SecureBlackbox.Dcauth

Remarks

The purpose of DCAuth is to sign async requests produced by SignAsyncBegin calls. For each incoming async request containing a document hash, DCAuth produces the corresponding async response containing a signature over that hash.

Protocol Overview

The distributed cryptography protocol involves two principal parties. The signing party, represented by components such as PDFSigner, XAdESSigner, or OfficeSigner, pre-signs documents (such as PDF files), and encapsulates their hashes into what is called an async request. It then communicates the async request to the private key side, where the DCAuth component extracts the hash and signs it with a local private key. DCAuth then encapsulates the signature into an async response, which is sent back to the signing party. The signing party completes the signing operation by extracting the signature from the async response and embedding it into the pre-signed document.

The protocol supports a variety of uses. The scheme above describes the most typical of them, where the signing party is represented by a web application, and the private key side is represented by a workstation. In that particular scenario DC provides a mechanism for the web app to sign documents residing on the web server with private keys residing on the users workstations, perhaps in non-exportable form (e.g. a USB dongle). Other uses include creation of a signing server for a team of driver developers, or an automated signing gateway for outgoing official documents.

In the webapp-to-browser setting the DCAuth control would normally be used within a web server running on the users workstation. That web server would accept async requests from the web page running in the browser, use DCAuth to generate the matching async response, and feed that response back to the web page. The web page will then submit it back to the web server.

Configuring and Using DCAuth

To process an async request, you need to set up a DCAuth object first, and then call its ProcessRequest method:

• Set the KeyId and KeySecret properties so they match the credentials used by the signing party - e.g. those of PDFSigner object: DCAuth.KeyId = "mykeyid"; DCAuth.KeySecret = "mykeysecret123";

  These two properties are used to verify the integrity of the incoming async requests. Keep them safe.

• Provide the signing certificate: DCAuth.SigningCertificate = "C:\Certs\SigningCert.pfx"; DCAuth.CertPassword = "password789";

  Alternatively, use StorageId to provide a certificate residing elsewhere, such as a PKCS#11 device.

• Assign the async request to the Input property: DCAuth.Input = Request;

  Make sure to provide the request in its original XML format. Some technologies and SecureBlackbox code samples may apply additional encoding when conveying async requests from their origin to the DCAuth endpoint. Please double check that you assign the request without any encodings applied. An async request is a properly formed XML document with the root element of SecureBlackboxAsyncState.

• Call the ProcessRequest method: DCAuth.ProcessRequest;

  This method performs the actual signing of the hash. Make sure your code is prepared for potential signing errors.

• If the ProcessRequest call has succeeded, grab the async response from the Output property: Result = DCAuth.Output;

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.

ClaimedSigningTime Property (DCAuth Component)

The signing time from the signer's computer.

Syntax

• C#
• VB.NET

public string ClaimedSigningTime { get; set; }

Public Property ClaimedSigningTime As String

Default Value

""

Remarks

Use this property to provide the signature production time. The claimed time is not supported by a trusted source; it may be inaccurate, forfeited, or wrong, and as such is usually taken for informational purposes only by verifiers. Use timestamp servers to embed verifiable trusted timestamps. The time is in UTC.

ExternalCrypto Property (DCAuth 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 (DCAuth 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.

Input Property (DCAuth Component)

Contains the signing request to process

Syntax

• C#
• VB.NET

public string Input { get; set; }

Public Property Input As String

Default Value

""

Remarks

Assign the request you received from the counterparty to this property before calling the ProcessRequest method. Use Output to read the resulting signature response after ProcessRequest completes.

InputEncoding Property (DCAuth Component)

Specifies request encoding.

Syntax

• C#
• VB.NET

public DcauthInputEncodings InputEncoding { get; set; }

enum DcauthInputEncodings {
  encNone,
  encAuto,
  encBase64
}

Public Property InputEncoding As DcauthInputEncodings

Enum DcauthInputEncodings
  encNone
  encAuto
  encBase64
End Enum

Default Value

0

Remarks

Use this property to specify the encoding to expect the requests to be in.

KeyId Property (DCAuth Component)

Specifies the KeyID of the pre-shared authentication key.

Syntax

• C#
• VB.NET

public string KeyId { get; set; }

Public Property KeyId As String

Default Value

""

Remarks

If processing requests from a single known party, assign the Id of the key you pre-shared with them to this property, and the key itself to the KeySecret property. If you expect to receive requests from many parties with different authentication keys, use KeySecretNeeded event instead.

KeySecret Property (DCAuth Component)

The pre-shared authentication key.

Syntax

• C#
• VB.NET

public string KeySecret { get; set; }

Public Property KeySecret As String

Default Value

""

Remarks

If processing requests from a single known party, assign the key you pre-shared with them to this property. Use KeyId property to assign the ID of that key. If you expect to receive requests from many parties with different authentication keys, use KeySecretNeeded event instead.

Output Property (DCAuth Component)

Contains the output of the request processing.

Syntax

• C#
• VB.NET

public string Output { get; }

Public ReadOnly Property Output As String

Default Value

""

Remarks

When ProcessRequest method completes it saves the processing output to this property. The output typically contains the response to be sent back to the requestor.

This property is read-only.

OutputEncoding Property (DCAuth Component)

Specifies response encoding.

Syntax

• C#
• VB.NET

public DcauthOutputEncodings OutputEncoding { get; set; }

enum DcauthOutputEncodings {
  encNone,
  encAuto,
  encBase64
}

Public Property OutputEncoding As DcauthOutputEncodings

Enum DcauthOutputEncodings
  encNone
  encAuto
  encBase64
End Enum

Default Value

0

Remarks

Use this property to specify the encoding you want the response to be produced in.

Policies Property (DCAuth Component)

Specifies the policies to use when processing requests.

Syntax

• C#
• VB.NET

public int Policies { get; set; }

Public Property Policies As Integer

Default Value

0

Remarks

This property lets you specify policies to apply blanketly to the requests. If this property does not give you enough flexibility - for example, if you need to cherry-pick requests basing on their content - please consider using the SignRequest (allows you to track individual requests) and/or ExternalSign (lets you perform the signing manually) events. This setting is a bit mask of the following flags:

This property is not available at design time.

Profile Property (DCAuth Component)

Specifies a pre-defined profile to apply when creating the signature.

Syntax

• C#
• VB.NET

public string Profile { get; set; }

Public Property Profile As String

Default Value

""

Remarks

Advanced signatures come in many variants, which are often defined by parties that needs to process them or by local standards. SecureBlackbox profiles are sets of pre-defined configurations which correspond to particular signature variants. By specifying a profile, you are pre-configuring the component to make it produce the signature that matches the configuration corresponding to that profile.

Proxy Property (DCAuth 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.

SigningCertificate Property (DCAuth 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.

SigningChain Property (DCAuth Component)

The signing certificate chain.

Syntax

• C#
• VB.NET

public CertificateList SigningChain { get; }

Public Property SigningChain As CertificateList

Remarks

Use this property to provide the chain for the signing certificate. Use the SigningCertificate property, if it is available, to provide the signing certificate itself.

This property is not available at design time.

SocketSettings Property (DCAuth 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.

StorageId Property (DCAuth Component)

Specifies the signing certificate residing in an alternative location

Syntax

• C#
• VB.NET

public string StorageId { get; set; }

Public Property StorageId As String

Default Value

""

Remarks

Use this property to specify the signing certificate contained on alternative media, such as a hardware device or in a system certificate store.

Example 1: The certificate resides on a PKCS#11 device

pkcs11://user:pin@/c:/windows/system32/pkcsdriver.dll?slot=0&readonly=1

Example 2: The certificate resides in a system store

system://localmachine@/?store=MY

You can use the following URI modifiers to provide more accurate specifiers for the needed certificate:

• cn: the common name of the certificate subject.
• keyid: the unique identifier included in subject key identifier extension of the certificate.
• keyusage: a comma-separated list of enabled (+) or disabled (-) key usages. The following usages are supported: signature, nonrepudiation, keyencipherment, dataencipherment, keyagreement, keycertsign, crlsign, encipheronly, decipheronly, serverauth, clientauth, codesigning, emailprotection, timestamping, ocspsigning, smartcardlogon, keypurposeclientauth, keypurposekdc.
• fingerprint: the fingerprint of the certificate.

Example 3: selecting the certificate with a given fingerprint:

pkcs11://user:pin@/c:/windows/system32/pkcsdriver.dll?slot=0&readonly=1&fingerprint=001122334455667788aabbccddeeff0011223344

TimestampServer Property (DCAuth Component)

The address of the timestamping server.

Syntax

• C#
• VB.NET

public string TimestampServer { get; set; }

Public Property TimestampServer As String

Default Value

""

Remarks

Use this property to provide the address of the Time Stamping Authority (TSA) server to be used for timestamping the signature.

SecureBlackbox supports RFC3161-compliant timestamping servers, available via HTTP or HTTPS.

If your timestamping service enforces credential-based user authentication (basic or digest), you can provide the credentials in the same URL:

http://user:password@timestamp.server.com/TsaService

For TSAs using certificate-based TLS authentication, provide the client certificate via the TLSClientChain property.

If this property is left empty, no timestamp will be added to the signature.

Starting from summer 2021 update (Vol. 2), the virtual timestamping service is supported, which allows you to intervene in the timestamping routine and provide your own handling for the TSA exchange. This may be handy if the service that you are requesting timestamps from uses a non-standard TSP protocol or requires special authentication option.

To employ the virtual service, assign an URI of the following format to this property:

virtual://localhost?hashonly=true&includecerts=true&reqpolicy=1.2.3.4.5&halg=SHA256

Subscribe to Notification event to get notified about the virtualized timestamping event. The EventID of the timestamping event is TimestampRequest. Inside the event handler, read the base16-encoded request from the EventParam parameter and forward it to the timestamping authority. Upon receiving the response, pass it back to the component, encoded in base16, via the TimestampResponse config property:

component.Config("TimestampResponse=308208ab...");

Note that all the exchange with your custom TSA should take place within the same invocation of the Notification event.

The hashonly parameter of the virtual URI tells the component to only return the timestamp message imprint via the EventParam parameter. If set to false, EventParam will contain the complete RFC3161 timestamping request.

The includecerts parameter specifies that the requestCertificates parameter of the timestamping request should be set to true.

The reqpolicy parameter lets you specify the request policy, and the halg parameter specifies the hash algorithm to use for timestamping.

All the parameters are optional.

TLSClientChain Property (DCAuth Component)

The TLS client certificate chain.

Syntax

• C#
• VB.NET

public CertificateList TLSClientChain { get; }

Public Property TLSClientChain As CertificateList

Remarks

Assign a certificate chain to this property to enable TLS client authentication in the component. Note that the client's end-entity certificate should have a private key associated with it.

Use the CertificateStorage or CertificateManager components to import the certificate from a file, system store, or PKCS11 device.

This property is not available at design time.

TLSServerChain Property (DCAuth Component)

The TLS server's certificate chain.

Syntax

• C#
• VB.NET

public CertificateList TLSServerChain { get; }

Public ReadOnly Property TLSServerChain As CertificateList

Remarks

Use this property to access the certificate chain sent by the TLS server. This property is ready to read when the TLSCertValidate event is fired by the client component.

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

TLSSettings Property (DCAuth 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.

Config Method (DCAuth 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.

DoAction Method (DCAuth 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;....

ProcessRequest Method (DCAuth Component)

Processes the request

Syntax

• C#
• VB.NET

public void ProcessRequest();

Public Sub ProcessRequest()

Remarks

Use this method to process the request, sign the hashes, and produce the response. This is the main method of the class. Note that a single request received from the counterparty may contain more than one signature request. This method processes them all, reporting each atomic signature request with SignRequest and SignRequestCompleted events. Before calling this method, make sure you assign the request content to Input. Upon completion, read the response (containing all the signatures) from Output property.

CustomParametersReceived Event (DCAuth Component)

Passes custom request parameters to the application.

Syntax

• C#
• VB.NET

public event OnCustomParametersReceivedHandler OnCustomParametersReceived;

public delegate void OnCustomParametersReceivedHandler(object sender, DcauthCustomParametersReceivedEventArgs e);

public class DcauthCustomParametersReceivedEventArgs : EventArgs {
  public string Value { get; }
}

Public Event OnCustomParametersReceived As OnCustomParametersReceivedHandler

Public Delegate Sub OnCustomParametersReceivedHandler(sender As Object, e As DcauthCustomParametersReceivedEventArgs)

Public Class DcauthCustomParametersReceivedEventArgs Inherits EventArgs
  Public ReadOnly Property Value As String
End Class

Remarks

This event is only provided for backward compatibility and is not currently used.

Error Event (DCAuth Component)

Reports information about errors during request processing or signing.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

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

Remarks

The event is fired if an error occurs during the request processing. Use the ErrorCode and Description parameters to get the details.

ExternalSign Event (DCAuth Component)

Handles remote or external signing initiated by the SignExternal method or other source.

Syntax

• C#
• VB.NET

public event OnExternalSignHandler OnExternalSign;

public delegate void OnExternalSignHandler(object sender, DcauthExternalSignEventArgs e);

public class DcauthExternalSignEventArgs : EventArgs {
  public string OperationId { get; }
  public string HashAlgorithm { get; }
  public string Pars { get; }
  public string MethodPars { get; }
  public string Data { get; }
  public string SignedData { get; set; }
}

Public Event OnExternalSign As OnExternalSignHandler

Public Delegate Sub OnExternalSignHandler(sender As Object, e As DcauthExternalSignEventArgs)

Public Class DcauthExternalSignEventArgs Inherits EventArgs
  Public ReadOnly Property OperationId As String
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property MethodPars As String
  Public ReadOnly Property Data As String
  Public Property SignedData As String
End Class

Remarks

Assign a handler to this event if you need to delegate a low-level signing operation to an external, remote, or custom signing engine. Depending on the settings, the handler will receive a hashed or unhashed value to be signed.

The event handler must pass the value of Data to the signer, obtain the signature, and pass it back to the component via the SignedData parameter.

OperationId provides a comment about the operation and its origin. It depends on the exact component being used, and may be empty. HashAlgorithm specifies the hash algorithm being used for the operation, and Pars contains algorithm-dependent parameters.

The component uses base16 (hex) encoding for the Data, SignedData, and Pars parameters. If your signing engine uses a different input and output encoding, you may need to decode and/or encode the data before and/or after the signing.

A sample MD5 hash encoded in base16: a0dee2a0382afbb09120ffa7ccd8a152 - lower case base16 A0DEE2A0382AFBB09120FFA7CCD8A152 - upper case base16

A sample event handler that uses the .NET RSACryptoServiceProvider class may look like the following: signer.OnExternalSign += (s, e) => { var cert = new X509Certificate2("cert.pfx", "", X509KeyStorageFlags.Exportable); var key = (RSACryptoServiceProvider)cert.PrivateKey; var dataToSign = e.Data.FromBase16String(); var signedData = key.SignHash(dataToSign, "2.16.840.1.101.3.4.2.1"); e.SignedData = signedData.ToBase16String(); };

The MethodPars parameter contains the method-specific parameters. For example, for PKCS7 requests it contains the requested parameters of the PKCS7 blob.

KeySecretNeeded Event (DCAuth Component)

Requests the key secret from the application.

Syntax

• C#
• VB.NET

public event OnKeySecretNeededHandler OnKeySecretNeeded;

public delegate void OnKeySecretNeededHandler(object sender, DcauthKeySecretNeededEventArgs e);

public class DcauthKeySecretNeededEventArgs : EventArgs {
  public string KeyId { get; }
  public string KeySecret { get; set; }
}

Public Event OnKeySecretNeeded As OnKeySecretNeededHandler

Public Delegate Sub OnKeySecretNeededHandler(sender As Object, e As DcauthKeySecretNeededEventArgs)

Public Class DcauthKeySecretNeededEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public Property KeySecret As String
End Class

Remarks

Subscribe to this event to pass the key secret (a pre-shared request authentication code) to the signing component when it is needed. The authentication combination consists of the KeyId, a non-secret unique key identifier, and the KeySecret, shared by the parties, which should be kept private. This event is an alternative for KeySecret property. Use it when you expect to process requests from requestors with different KeyIds and secrets. If you only expect to receive requests from a single requestor with a known KeyId, providing the key secret via KeyId and KeySecret properties would be an easier route.

Notification Event (DCAuth 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, DcauthNotificationEventArgs e);

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

Public Event OnNotification As OnNotificationHandler

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

Public Class DcauthNotificationEventArgs 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.

ParameterReceived Event (DCAuth Component)

Passes a standard request parameter to the user code.

Syntax

• C#
• VB.NET

public event OnParameterReceivedHandler OnParameterReceived;

public delegate void OnParameterReceivedHandler(object sender, DcauthParameterReceivedEventArgs e);

public class DcauthParameterReceivedEventArgs : EventArgs {
  public string Name { get; }
  public string Value { get; }
}

Public Event OnParameterReceived As OnParameterReceivedHandler

Public Delegate Sub OnParameterReceivedHandler(sender As Object, e As DcauthParameterReceivedEventArgs)

Public Class DcauthParameterReceivedEventArgs Inherits EventArgs
  Public ReadOnly Property Name As String
  Public ReadOnly Property Value As String
End Class

Remarks

This event is only provided for backward compatibility and is not currently used.

SignRequest Event (DCAuth Component)

This event signifies the processing of an atomic signing request.

Syntax

• C#
• VB.NET

public event OnSignRequestHandler OnSignRequest;

public delegate void OnSignRequestHandler(object sender, DcauthSignRequestEventArgs e);

public class DcauthSignRequestEventArgs : EventArgs {
  public int Method { get; }
  public string HashAlgorithm { get; }
  public byte[] Hash { get; }
  public string KeyID { get; }
  public string Pars { get; }
  public string MethodPars { get; }
  public bool Allow { get; set; }
}

Public Event OnSignRequest As OnSignRequestHandler

Public Delegate Sub OnSignRequestHandler(sender As Object, e As DcauthSignRequestEventArgs)

Public Class DcauthSignRequestEventArgs Inherits EventArgs
  Public ReadOnly Property Method As Integer
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property Hash As Byte()
  Public ReadOnly Property KeyID As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property MethodPars As String
  Public Property Allow As Boolean
End Class

Remarks

Subscribe to this event to be notified of every signature request processed by the DC server. Note that any one request coming from the requestor may contain multiple individual signature requests (so-called 'batching'). This event is a good mechanism to track signature requests for accountability purposes, and provide basic access control over the signing operations. The Method parameter specifies the async signing method requested by the client:

The Hash parameter contains the hash, made using HashAlgorithm, that needs to be signed. KeyID contains the key identifier of the requestor.

The Pars string contains a semicolon-separated string of the principal signature parameters. This has the same format and content that is passed to ExternalSign, if it is used. The MethodPars contains a similar parameter string, but for the specific async signing method used. For the PKCS1 method there are no defined method parameters, while the PKCS7 method supports a selection of settings that tune up the CMS blob.

Set Allow to false to stop the request from being served. Use the SignRequestCompleted event to track completion of the initiated operation.

SignRequestCompleted Event (DCAuth Component)

This event signifies completion of the processing of an atomic signing request.

Syntax

• C#
• VB.NET

public event OnSignRequestCompletedHandler OnSignRequestCompleted;

public delegate void OnSignRequestCompletedHandler(object sender, DcauthSignRequestCompletedEventArgs e);

public class DcauthSignRequestCompletedEventArgs : EventArgs {
  public int Method { get; }
  public string HashAlgorithm { get; }
  public byte[] Hash { get; }
  public string KeyID { get; }
  public string Pars { get; }
  public string MethodPars { get; }
  public byte[] Signature { get; }
}

Public Event OnSignRequestCompleted As OnSignRequestCompletedHandler

Public Delegate Sub OnSignRequestCompletedHandler(sender As Object, e As DcauthSignRequestCompletedEventArgs)

Public Class DcauthSignRequestCompletedEventArgs Inherits EventArgs
  Public ReadOnly Property Method As Integer
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property Hash As Byte()
  Public ReadOnly Property KeyID As String
  Public ReadOnly Property Pars As String
  Public ReadOnly Property MethodPars As String
  Public ReadOnly Property Signature As Byte()
End Class

Remarks

Use this event to track completion of signing request processing. The Hash parameter contains the hash that is signed, as supplied by the requestor, and the Signature parameter contains the resulting cryptographic signature. The KeyID parameter matches the parameter in SignRequest event.

TimestampRequest Event (DCAuth Component)

Fires when the component is ready to request a timestamp from an external TSA.

Syntax

• C#
• VB.NET

public event OnTimestampRequestHandler OnTimestampRequest;

public delegate void OnTimestampRequestHandler(object sender, DcauthTimestampRequestEventArgs e);

public class DcauthTimestampRequestEventArgs : EventArgs {
  public string TSA { get; }
  public string TimestampRequest { get; }
  public string TimestampResponse { get; set; }
  public bool SuppressDefault { get; set; }
}

Public Event OnTimestampRequest As OnTimestampRequestHandler

Public Delegate Sub OnTimestampRequestHandler(sender As Object, e As DcauthTimestampRequestEventArgs)

Public Class DcauthTimestampRequestEventArgs Inherits EventArgs
  Public ReadOnly Property TSA As String
  Public ReadOnly Property TimestampRequest As String
  Public Property TimestampResponse As String
  Public Property SuppressDefault As Boolean
End Class

Remarks

Subscribe to this event to intercept timestamp requests. You can use it to override timestamping requests and perform them in your code.

The TSA parameter indicates the timestamping service being used. It matches the value passed to the TimestampServer property. Set the SuppressDefault parameter to false if you would like to stop the built-in TSA request from going ahead. The built-in TSA request is also not performed if the returned TimestampResponse parameter is not empty.

TLSCertNeeded Event (DCAuth Component)

Fires when a remote TLS party requests a client certificate.

Syntax

• C#
• VB.NET

public event OnTLSCertNeededHandler OnTLSCertNeeded;

public delegate void OnTLSCertNeededHandler(object sender, DcauthTLSCertNeededEventArgs e);

public class DcauthTLSCertNeededEventArgs : EventArgs {
  public string Host { get; }
  public string CANames { get; }
}

Public Event OnTLSCertNeeded As OnTLSCertNeededHandler

Public Delegate Sub OnTLSCertNeededHandler(sender As Object, e As DcauthTLSCertNeededEventArgs)

Public Class DcauthTLSCertNeededEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property CANames As String
End Class

Remarks

This event fires to notify the implementation that a remote TLS server has requested a client certificate. The Host parameter identifies the host that makes a request, and the CANames parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

Use the TLSClientChain property in response to this event to provide the requested certificate. Please make sure the client certificate includes the associated private key. Note that you may set the certificates before the connection without waiting for this event to fire.

This event is preceded by the TLSHandshake event for the given host and, if the certificate was accepted, succeeded by the TLSEstablished event.

TLSCertValidate Event (DCAuth Component)

This event is fired upon receipt of the TLS server's certificate, allowing the user to control its acceptance.

Syntax

• C#
• VB.NET

public event OnTLSCertValidateHandler OnTLSCertValidate;

public delegate void OnTLSCertValidateHandler(object sender, DcauthTLSCertValidateEventArgs e);

public class DcauthTLSCertValidateEventArgs : EventArgs {
  public string ServerHost { get; }
  public string ServerIP { get; }
  public bool Accept { get; set; }
}

Public Event OnTLSCertValidate As OnTLSCertValidateHandler

Public Delegate Sub OnTLSCertValidateHandler(sender As Object, e As DcauthTLSCertValidateEventArgs)

Public Class DcauthTLSCertValidateEventArgs Inherits EventArgs
  Public ReadOnly Property ServerHost As String
  Public ReadOnly Property ServerIP As String
  Public Property Accept As Boolean
End Class

Remarks

This event is fired during a TLS handshake. Use the TLSServerChain property to access the certificate chain. In general, components may contact a number of TLS endpoints during their work, depending on their configuration.

Accept is assigned in accordance with the outcome of the internal validation check performed by the component, and can be adjusted if needed.

TLSEstablished Event (DCAuth Component)

Fires when a TLS handshake with Host successfully completes.

Syntax

• C#
• VB.NET

public event OnTLSEstablishedHandler OnTLSEstablished;

public delegate void OnTLSEstablishedHandler(object sender, DcauthTLSEstablishedEventArgs e);

public class DcauthTLSEstablishedEventArgs : EventArgs {
  public string Host { get; }
  public string Version { get; }
  public string Ciphersuite { get; }
  public byte[] ConnectionId { get; }
  public bool Abort { get; set; }
}

Public Event OnTLSEstablished As OnTLSEstablishedHandler

Public Delegate Sub OnTLSEstablishedHandler(sender As Object, e As DcauthTLSEstablishedEventArgs)

Public Class DcauthTLSEstablishedEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public ReadOnly Property Version As String
  Public ReadOnly Property Ciphersuite As String
  Public ReadOnly Property ConnectionId As Byte()
  Public Property Abort As Boolean
End Class

Remarks

The component uses this event to notify the application about a successful completion of a TLS handshake.

The Version, Ciphersuite, and ConnectionId parameters indicate the security parameters of the new connection. Use the Abort parameter if you need to terminate the connection at this stage.

TLSHandshake Event (DCAuth Component)

Fires when a new TLS handshake is initiated, before the handshake commences.

Syntax

• C#
• VB.NET

public event OnTLSHandshakeHandler OnTLSHandshake;

public delegate void OnTLSHandshakeHandler(object sender, DcauthTLSHandshakeEventArgs e);

public class DcauthTLSHandshakeEventArgs : EventArgs {
  public string Host { get; }
  public bool Abort { get; set; }
}

Public Event OnTLSHandshake As OnTLSHandshakeHandler

Public Delegate Sub OnTLSHandshakeHandler(sender As Object, e As DcauthTLSHandshakeEventArgs)

Public Class DcauthTLSHandshakeEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
  Public Property Abort As Boolean
End Class

Remarks

The component uses this event to notify the application about the start of a new TLS handshake to Host. If the handshake is successful, this event will be followed by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSShutdown Event (DCAuth Component)

Reports the graceful closure of a TLS connection.

Syntax

• C#
• VB.NET

public event OnTLSShutdownHandler OnTLSShutdown;

public delegate void OnTLSShutdownHandler(object sender, DcauthTLSShutdownEventArgs e);

public class DcauthTLSShutdownEventArgs : EventArgs {
  public string Host { get; }
}

Public Event OnTLSShutdown As OnTLSShutdownHandler

Public Delegate Sub OnTLSShutdownHandler(sender As Object, e As DcauthTLSShutdownEventArgs)

Public Class DcauthTLSShutdownEventArgs Inherits EventArgs
  Public ReadOnly Property Host As String
End Class

Remarks

This event notifies the application about the closure of an earlier established TLS connection. Note that only graceful connection closures are reported.

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.

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.

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.

Config Settings (DCAuth Component)

DCAuth Config Settings

Base Config Settings

Trappable Errors (DCAuth Component)