Struct secureblackbox::DCAuth

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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 structs 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 struct 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 process_request 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 storage_id 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 process_request method: DCAuth.ProcessRequest;

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

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

Please see the demo folder for more in-depth code examples of this struct.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by SecureBlackbox. Due to this, the DCAuth struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of DCAuth when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

claimed_signing_time property (DCAuth Struct)

The signing time from the signer's computer.

Syntax

fn claimed_signing_time(&self ) -> Result<String, SecureBlackboxError> 
fn set_claimed_signing_time(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_claimed_signing_time_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

external_crypto_async_document_id property (DCAuth Struct)

Specifies an optional document ID for SignAsyncBegin() and SignAsyncEnd() calls.

Syntax

fn external_crypto_async_document_id(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_async_document_id(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_async_document_id_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Specifies an optional document ID for SignAsyncBegin() and SignAsyncEnd() calls.

Use this property when working with multi-signature DCAuth requests and responses to uniquely identify documents signed within a larger batch. On the completion stage, this value helps the signing component identify the correct signature in the returned batch of responses.

If using batched requests, make sure to set this property to the same value on both the pre-signing (SignAsyncBegin) and completion (SignAsyncEnd) stages.

Data Type

String

external_crypto_custom_params property (DCAuth Struct)

Custom parameters to be passed to the signing service (uninterpreted).

Syntax

fn external_crypto_custom_params(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_custom_params(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_custom_params_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Custom parameters to be passed to the signing service (uninterpreted).

Data Type

String

external_crypto_data property (DCAuth Struct)

Additional data to be included in the async state and mirrored back by the requestor.

Syntax

fn external_crypto_data(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_data(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_data_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Additional data to be included in the async state and mirrored back by the requestor.

Data Type

String

external_crypto_external_hash_calculation property (DCAuth Struct)

Specifies whether the message hash is to be calculated at the external endpoint.

Syntax

fn external_crypto_external_hash_calculation(&self ) -> Result<bool, SecureBlackboxError> 
fn set_external_crypto_external_hash_calculation(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

Specifies whether the message hash is to be calculated at the external endpoint. Please note that this mode is not supported by the DCAuth struct.

If set to true, the struct will pass a few kilobytes of to-be-signed data from the document to the OnExternalSign event. This only applies when SignExternal() is called.

Data Type

bool

external_crypto_hash_algorithm property (DCAuth Struct)

Specifies the request's signature hash algorithm.

Syntax

fn external_crypto_hash_algorithm(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_hash_algorithm(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_hash_algorithm_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

"SHA256"

Remarks

Specifies the request's signature hash algorithm.

Data Type

String

external_crypto_key_id property (DCAuth Struct)

The ID of the pre-shared key used for DC request authentication.

Syntax

fn external_crypto_key_id(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_key_id(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_key_id_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The ID of the pre-shared key used for DC request authentication.

Asynchronous DCAuth-driven communication requires that parties authenticate each other with a secret pre-shared cryptographic key. This provides an extra protection layer for the protocol and diminishes the risk of the private key becoming abused by foreign parties. Use this property to provide the pre-shared key identifier, and use external_crypto_key_secret to pass the key itself.

The same KeyID/KeySecret pair should be used on the DCAuth side for the signing requests to be accepted.

Note: The KeyID/KeySecret scheme is very similar to the AuthKey scheme used in various Cloud service providers to authenticate users.

Example: signer.ExternalCrypto.KeyID = "MainSigningKey"; signer.ExternalCrypto.KeySecret = "abcdef0123456789";

Data Type

String

external_crypto_key_secret property (DCAuth Struct)

The pre-shared key used for DC request authentication.

Syntax

fn external_crypto_key_secret(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_key_secret(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_key_secret_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The pre-shared key used for DC request authentication. This key must be set and match the key used by the DCAuth counterpart for the scheme to work.

Read more about configuring authentication in the external_crypto_key_id topic.

Data Type

String

external_crypto_method property (DCAuth Struct)

Specifies the asynchronous signing method.

Syntax

fn external_crypto_method(&self ) -> Result<i32, SecureBlackboxError> 
fn set_external_crypto_method(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // PKCS1
1   // PKCS7

Default Value

0

Remarks

Specifies the asynchronous signing method. This is typically defined by the DC server capabilities and setup.

Available options:

Data Type

i32

external_crypto_mode property (DCAuth Struct)

Specifies the external cryptography mode.

Syntax

fn external_crypto_mode(&self ) -> Result<i32, SecureBlackboxError> 
fn set_external_crypto_mode(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // Default
1   // Disabled
2   // Generic
3   // DCAuth
4   // DCAuthJSON

Default Value

0

Remarks

Specifies the external cryptography mode.

Available options:

Data Type

i32

external_crypto_public_key_algorithm property (DCAuth Struct)

Provide the public key algorithm here if the certificate is not available on the pre-signing stage.

Syntax

fn external_crypto_public_key_algorithm(&self ) -> Result<String, SecureBlackboxError> 
fn set_external_crypto_public_key_algorithm(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_external_crypto_public_key_algorithm_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Provide the public key algorithm here if the certificate is not available on the pre-signing stage.

Data Type

String

fips_mode property (DCAuth Struct)

Reserved.

Syntax

fn fips_mode(&self ) -> Result<bool, SecureBlackboxError> 
fn set_fips_mode(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

This property is reserved for future use.

Data Type

bool

input property (DCAuth Struct)

Contains the signing request to process.

Syntax

fn input(&self ) -> Result<String, SecureBlackboxError> 
fn set_input(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_input_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

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

Data Type

String

input_encoding property (DCAuth Struct)

Specifies request encoding.

Syntax

fn input_encoding(&self ) -> Result<i32, SecureBlackboxError> 
fn set_input_encoding(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // None
1   // Auto
2   // Base64

Default Value

0

Remarks

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

Data Type

i32

key_id property (DCAuth Struct)

Specifies the KeyID of the pre-shared authentication key.

Syntax

fn key_id(&self ) -> Result<String, SecureBlackboxError> 
fn set_key_id(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_key_id_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

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 key_secret property. If you expect to receive requests from many parties with different authentication keys, use on_key_secret_needed event instead.

Data Type

String

key_secret property (DCAuth Struct)

The pre-shared authentication key.

Syntax

fn key_secret(&self ) -> Result<String, SecureBlackboxError> 
fn set_key_secret(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_key_secret_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

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

Data Type

String

output property (DCAuth Struct)

Contains the output of the request processing.

Syntax

fn output(&self ) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

When process_request 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.

Data Type

String

output_encoding property (DCAuth Struct)

Specifies response encoding.

Syntax

fn output_encoding(&self ) -> Result<i32, SecureBlackboxError> 
fn set_output_encoding(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // None
1   // Auto
2   // Base64

Default Value

0

Remarks

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

Data Type

i32

policies property (DCAuth Struct)

Specifies the policies to use when processing requests.

Syntax

fn policies(&self ) -> Result<i32, SecureBlackboxError> 
fn set_policies(&self, value : i32) ->  Option<SecureBlackboxError> 

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 on_sign_request (allows you to track individual requests) and/or on_external_sign (lets you perform the signing manually) events. This setting is a bit mask of the following flags:

Data Type

i32

profile property (DCAuth Struct)

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

Syntax

fn profile(&self ) -> Result<String, SecureBlackboxError> 
fn set_profile(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_profile_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

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.

Data Type

String

proxy_address property (DCAuth Struct)

The IP address of the proxy server.

Syntax

fn proxy_address(&self ) -> Result<String, SecureBlackboxError> 
fn set_proxy_address(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_proxy_address_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The IP address of the proxy server.

Data Type

String

proxy_authentication property (DCAuth Struct)

The authentication type used by the proxy server.

Syntax

fn proxy_authentication(&self ) -> Result<i32, SecureBlackboxError> 
fn set_proxy_authentication(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // NoAuthentication
1   // Basic
2   // Digest
3   // NTLM

Default Value

0

Remarks

The authentication type used by the proxy server.

Data Type

i32

proxy_password property (DCAuth Struct)

The password to authenticate to the proxy server.

Syntax

fn proxy_password(&self ) -> Result<String, SecureBlackboxError> 
fn set_proxy_password(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_proxy_password_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The password to authenticate to the proxy server.

Data Type

String

proxy_port property (DCAuth Struct)

The port on the proxy server to connect to.

Syntax

fn proxy_port(&self ) -> Result<i32, SecureBlackboxError> 
fn set_proxy_port(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

The port on the proxy server to connect to.

Data Type

i32

proxy_type property (DCAuth Struct)

The type of the proxy server.

Syntax

fn proxy_type(&self ) -> Result<i32, SecureBlackboxError> 
fn set_proxy_type(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // None
1   // Socks4
2   // Socks5
3   // WebTunnel
4   // HTTP

Default Value

0

Remarks

The type of the proxy server.

Data Type

i32

proxy_request_headers property (DCAuth Struct)

Contains HTTP request headers for WebTunnel and HTTP proxy.

Syntax

fn proxy_request_headers(&self ) -> Result<String, SecureBlackboxError> 
fn set_proxy_request_headers(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_proxy_request_headers_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Contains HTTP request headers for WebTunnel and HTTP proxy.

Data Type

String

proxy_response_body property (DCAuth Struct)

Contains the HTTP or HTTPS (WebTunnel) proxy response body.

Syntax

fn proxy_response_body(&self ) -> Result<String, SecureBlackboxError> 
fn set_proxy_response_body(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_proxy_response_body_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Contains the HTTP or HTTPS (WebTunnel) proxy response body.

Data Type

String

proxy_response_headers property (DCAuth Struct)

Contains response headers received from an HTTP or HTTPS (WebTunnel) proxy server.

Syntax

fn proxy_response_headers(&self ) -> Result<String, SecureBlackboxError> 
fn set_proxy_response_headers(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_proxy_response_headers_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Contains response headers received from an HTTP or HTTPS (WebTunnel) proxy server.

Data Type

String

proxy_use_ipv6 property (DCAuth Struct)

Specifies whether IPv6 should be used when connecting through the proxy.

Syntax

fn proxy_use_ipv6(&self ) -> Result<bool, SecureBlackboxError> 
fn set_proxy_use_ipv6(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

Specifies whether IPv6 should be used when connecting through the proxy.

Data Type

bool

proxy_username property (DCAuth Struct)

Specifies the username credential for proxy authentication.

Syntax

fn proxy_username(&self ) -> Result<String, SecureBlackboxError> 
fn set_proxy_username(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_proxy_username_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Specifies the username credential for proxy authentication.

Data Type

String

signing_cert_bytes property (DCAuth Struct)

Returns the raw certificate data in DER format.

Syntax

fn signing_cert_bytes(&self ) -> Result<Vec<u8>, SecureBlackboxError> 

Remarks

Returns the raw certificate data in DER format.

This property is read-only.

Data Type

Vec

signing_cert_handle property (DCAuth Struct)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

fn signing_cert_handle(&self ) -> Result<i64, SecureBlackboxError> 
fn set_signing_cert_handle(&self, value : i64) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

Data Type

i64

signing_chain_count property (DCAuth Struct)

The number of records in the SigningChain arrays.

Syntax

fn signing_chain_count(&self ) -> Result<i32, SecureBlackboxError> 
fn set_signing_chain_count(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• signing_chain_bytes
• signing_chain_handle

The array indices start at 0 and end at signing_chain_count - 1.

Data Type

i32

signing_chain_bytes property (DCAuth Struct)

Returns the raw certificate data in DER format.

Syntax

fn signing_chain_bytes(&self , SigningChainIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 

Remarks

Returns the raw certificate data in DER format.

The SigningChainIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SigningChainCount property.

This property is read-only.

Data Type

Vec

signing_chain_handle property (DCAuth Struct)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

fn signing_chain_handle(&self , SigningChainIndex : i32) -> Result<i64, SecureBlackboxError> 
fn set_signing_chain_handle(&self, SigningChainIndex : i32, value : i64) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The SigningChainIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SigningChainCount property.

Data Type

i64

socket_dns_mode property (DCAuth Struct)

Selects the DNS resolver to use: the struct's (secure) built-in one, or the one provided by the system.

Syntax

fn socket_dns_mode(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_dns_mode(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // Auto
1   // Platform
2   // Own
3   // OwnSecure

Default Value

0

Remarks

Selects the DNS resolver to use: the component's (secure) built-in one, or the one provided by the system.

Data Type

i32

socket_dns_port property (DCAuth Struct)

Specifies the port number to be used for sending queries to the DNS server.

Syntax

fn socket_dns_port(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_dns_port(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

Specifies the port number to be used for sending queries to the DNS server.

Data Type

i32

socket_dns_query_timeout property (DCAuth Struct)

The timeout (in milliseconds) for each DNS query.

Syntax

fn socket_dns_query_timeout(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_dns_query_timeout(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

The timeout (in milliseconds) for each DNS query. The value of 0 indicates an infinite timeout.

Data Type

i32

socket_dns_servers property (DCAuth Struct)

The addresses of DNS servers to use for address resolution, separated by commas or semicolons.

Syntax

fn socket_dns_servers(&self ) -> Result<String, SecureBlackboxError> 
fn set_socket_dns_servers(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_socket_dns_servers_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The addresses of DNS servers to use for address resolution, separated by commas or semicolons.

Data Type

String

socket_dns_total_timeout property (DCAuth Struct)

The timeout (in milliseconds) for the whole resolution process.

Syntax

fn socket_dns_total_timeout(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_dns_total_timeout(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

The timeout (in milliseconds) for the whole resolution process. The value of 0 indicates an infinite timeout.

Data Type

i32

socket_incoming_speed_limit property (DCAuth Struct)

The maximum number of bytes to read from the socket, per second.

Syntax

fn socket_incoming_speed_limit(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_incoming_speed_limit(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

The maximum number of bytes to read from the socket, per second.

Data Type

i32

socket_local_address property (DCAuth Struct)

The local network interface to bind the socket to.

Syntax

fn socket_local_address(&self ) -> Result<String, SecureBlackboxError> 
fn set_socket_local_address(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_socket_local_address_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

The local network interface to bind the socket to.

Data Type

String

socket_local_port property (DCAuth Struct)

The local port number to bind the socket to.

Syntax

fn socket_local_port(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_local_port(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

The local port number to bind the socket to.

Data Type

i32

socket_outgoing_speed_limit property (DCAuth Struct)

The maximum number of bytes to write to the socket, per second.

Syntax

fn socket_outgoing_speed_limit(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_outgoing_speed_limit(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

The maximum number of bytes to write to the socket, per second.

Data Type

i32

socket_timeout property (DCAuth Struct)

The maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.

Syntax

fn socket_timeout(&self ) -> Result<i32, SecureBlackboxError> 
fn set_socket_timeout(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

60000

Remarks

The maximum period of waiting, in milliseconds, after which the socket operation is considered unsuccessful.

If Timeout is set to 0, a socket operation will expire after the system-default timeout (2 hrs 8 min for TCP stack).

Data Type

i32

socket_use_ipv6 property (DCAuth Struct)

Enables or disables IP protocol version 6.

Syntax

fn socket_use_ipv6(&self ) -> Result<bool, SecureBlackboxError> 
fn set_socket_use_ipv6(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

Enables or disables IP protocol version 6.

Data Type

bool

storage_id property (DCAuth Struct)

Specifies the signing certificate residing in an alternative location.

Syntax

fn storage_id(&self ) -> Result<String, SecureBlackboxError> 
fn set_storage_id(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_storage_id_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

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

Data Type

String

timestamp_server property (DCAuth Struct)

The address of the timestamping server.

Syntax

fn timestamp_server(&self ) -> Result<String, SecureBlackboxError> 
fn set_timestamp_server(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_timestamp_server_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

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 tls_client_chain 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&ignorenonce=true

Subscribe to on_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.

The ignorenonce parameter allows you to switch off client nonce verification to enable compatibility with TSA services that do not support nonce mirroring.

All the parameters are optional.

Data Type

String

tls_client_cert_count property (DCAuth Struct)

The number of records in the TLSClientCert arrays.

Syntax

fn tls_client_cert_count(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_client_cert_count(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• tls_client_cert_bytes
• tls_client_cert_handle

The array indices start at 0 and end at tls_client_cert_count - 1.

Data Type

i32

tls_client_cert_bytes property (DCAuth Struct)

Returns the raw certificate data in DER format.

Syntax

fn tls_client_cert_bytes(&self , TLSClientCertIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 

Remarks

Returns the raw certificate data in DER format.

The TLSClientCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSClientCertCount property.

This property is read-only.

Data Type

Vec

tls_client_cert_handle property (DCAuth Struct)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

fn tls_client_cert_handle(&self , TLSClientCertIndex : i32) -> Result<i64, SecureBlackboxError> 
fn set_tls_client_cert_handle(&self, TLSClientCertIndex : i32, value : i64) ->  Option<SecureBlackboxError> 

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The TLSClientCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSClientCertCount property.

Data Type

i64

tls_server_cert_count property (DCAuth Struct)

The number of records in the TLSServerCert arrays.

Syntax

fn tls_server_cert_count(&self ) -> Result<i32, SecureBlackboxError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• tls_server_cert_bytes
• tls_server_cert_fingerprint
• tls_server_cert_handle
• tls_server_cert_issuer
• tls_server_cert_issuer_rdn
• tls_server_cert_key_algorithm
• tls_server_cert_key_bits
• tls_server_cert_key_usage
• tls_server_cert_self_signed
• tls_server_cert_serial_number
• tls_server_cert_sig_algorithm
• tls_server_cert_subject
• tls_server_cert_subject_rdn
• tls_server_cert_valid_from
• tls_server_cert_valid_to

The array indices start at 0 and end at tls_server_cert_count - 1.

This property is read-only.

Data Type

i32

tls_server_cert_bytes property (DCAuth Struct)

Returns the raw certificate data in DER format.

Syntax

fn tls_server_cert_bytes(&self , TLSServerCertIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 

Remarks

Returns the raw certificate data in DER format.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

Vec

tls_server_cert_fingerprint property (DCAuth Struct)

Contains the fingerprint (a hash imprint) of this certificate.

Syntax

fn tls_server_cert_fingerprint(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

Contains the fingerprint (a hash imprint) of this certificate.

While there is no formal standard defining what a fingerprint is, a SHA1 hash of the certificate's DER-encoded body is typically used.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_handle property (DCAuth Struct)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

fn tls_server_cert_handle(&self , TLSServerCertIndex : i32) -> Result<i64, SecureBlackboxError> 

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

i64

tls_server_cert_issuer property (DCAuth Struct)

The common name of the certificate issuer (CA), typically a company name.

Syntax

fn tls_server_cert_issuer(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

The common name of the certificate issuer (CA), typically a company name. This is part of a larger set of credentials available via tls_issuer_rdn.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_issuer_rdn property (DCAuth Struct)

A list of Property=Value pairs that uniquely identify the certificate issuer.

Syntax

fn tls_server_cert_issuer_rdn(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

A list of Property=Value pairs that uniquely identify the certificate issuer.

Example: /C=US/O=Nationwide CA/CN=Web Certification Authority

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_key_algorithm property (DCAuth Struct)

Specifies the public key algorithm of this certificate.

Syntax

fn tls_server_cert_key_algorithm(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

"0"

Remarks

Specifies the public key algorithm of this certificate.

Use the tls_key_bits, tls_curve, and tls_public_key_bytes properties to get more details about the key the certificate contains.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_key_bits property (DCAuth Struct)

Returns the length of the public key in bits.

Syntax

fn tls_server_cert_key_bits(&self , TLSServerCertIndex : i32) -> Result<i32, SecureBlackboxError> 

Default Value

0

Remarks

Returns the length of the public key in bits.

This value indicates the length of the principal cryptographic parameter of the key, such as the length of the RSA modulus or ECDSA field. The key data returned by the tls_public_key_bytes or tls_private_key_bytes property would typically contain auxiliary values, and therefore be longer.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

i32

tls_server_cert_key_usage property (DCAuth Struct)

Indicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.

Syntax

fn tls_server_cert_key_usage(&self , TLSServerCertIndex : i32) -> Result<i32, SecureBlackboxError> 

Default Value

0

Remarks

Indicates the purposes of the key contained in the certificate, in the form of an OR'ed flag set.

This value is a bit mask of the following values:

Set this property before generating the certificate to propagate the key usage flags to the new certificate.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

i32

tls_server_cert_self_signed property (DCAuth Struct)

Indicates whether the certificate is self-signed (root) or signed by an external CA.

Syntax

fn tls_server_cert_self_signed(&self , TLSServerCertIndex : i32) -> Result<bool, SecureBlackboxError> 

Default Value

false

Remarks

Indicates whether the certificate is self-signed (root) or signed by an external CA.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

bool

tls_server_cert_serial_number property (DCAuth Struct)

Returns the certificate's serial number.

Syntax

fn tls_server_cert_serial_number(&self , TLSServerCertIndex : i32) -> Result<Vec<u8>, SecureBlackboxError> 

Remarks

Returns the certificate's serial number.

The serial number is a binary string that uniquely identifies a certificate among others issued by the same CA. According to the X.509 standard, the (issuer, serial number) pair should be globally unique to facilitate chain building.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

Vec

tls_server_cert_sig_algorithm property (DCAuth Struct)

Indicates the algorithm that was used by the CA to sign this certificate.

Syntax

fn tls_server_cert_sig_algorithm(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

Indicates the algorithm that was used by the CA to sign this certificate.

A signature algorithm typically combines hash and public key algorithms together, such as sha256WithRSAEncryption or ecdsa-with-SHA256.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_subject property (DCAuth Struct)

The common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name.

Syntax

fn tls_server_cert_subject(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

The common name of the certificate holder, typically an individual's name, a URL, an e-mail address, or a company name. This is part of a larger set of credentials available via tls_subject_rdn.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_subject_rdn property (DCAuth Struct)

A list of Property=Value pairs that uniquely identify the certificate holder (subject).

Syntax

fn tls_server_cert_subject_rdn(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

A list of Property=Value pairs that uniquely identify the certificate holder (subject).

Depending on the purpose of the certificate and the policies of the CA that issued it, the values included in the subject record may differ drastically and contain business or personal names, web URLs, email addresses, and other data.

Example: /C=US/O=Oranges and Apples, Inc./OU=Accounts Receivable/1.2.3.4.5=Value with unknown OID/CN=Margaret Watkins.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_valid_from property (DCAuth Struct)

The time point at which the certificate becomes valid, in UTC.

Syntax

fn tls_server_cert_valid_from(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

The time point at which the certificate becomes valid, in UTC.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_server_cert_valid_to property (DCAuth Struct)

The time point at which the certificate expires, in UTC.

Syntax

fn tls_server_cert_valid_to(&self , TLSServerCertIndex : i32) -> Result<String, SecureBlackboxError> 

Default Value

""

Remarks

The time point at which the certificate expires, in UTC.

The TLSServerCertIndex parameter specifies the index of the item in the array. The size of the array is controlled by the TLSServerCertCount property.

This property is read-only.

Data Type

String

tls_auto_validate_certificates property (DCAuth Struct)

Specifies whether server-side TLS certificates should be validated automatically using internal validation rules.

Syntax

fn tls_auto_validate_certificates(&self ) -> Result<bool, SecureBlackboxError> 
fn set_tls_auto_validate_certificates(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

true

Remarks

Specifies whether server-side TLS certificates should be validated automatically using internal validation rules.

Data Type

bool

tls_base_configuration property (DCAuth Struct)

Selects the base configuration for the TLS settings.

Syntax

fn tls_base_configuration(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_base_configuration(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // Default
1   // Compatible
2   // ComprehensiveInsecure
3   // HighlySecure

Default Value

0

Remarks

Selects the base configuration for the TLS settings. Several profiles are offered and tuned up for different purposes, such as high security or higher compatibility.

Data Type

i32

tls_ciphersuites property (DCAuth Struct)

A list of ciphersuites separated with commas or semicolons.

Syntax

fn tls_ciphersuites(&self ) -> Result<String, SecureBlackboxError> 
fn set_tls_ciphersuites(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_tls_ciphersuites_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

A list of ciphersuites separated with commas or semicolons. Each ciphersuite in the list may be prefixed with a minus sign (-) to indicate that the ciphersuite should be disabled rather than enabled. Besides the specific ciphersuite modifiers, this property supports the all (and -all) aliases, allowing all ciphersuites to be blanketly enabled or disabled at once.

Note: the list of ciphersuites provided to this property alters the baseline list of ciphersuites as defined by tls_base_configuration. Remember to start your ciphersuite string with -all; if you need to only enable a specific fixed set of ciphersuites. The list of supported ciphersuites is provided below:

• NULL_NULL_NULL
• RSA_NULL_MD5
• RSA_NULL_SHA
• RSA_RC4_MD5
• RSA_RC4_SHA
• RSA_RC2_MD5
• RSA_IDEA_MD5
• RSA_IDEA_SHA
• RSA_DES_MD5
• RSA_DES_SHA
• RSA_3DES_MD5
• RSA_3DES_SHA
• RSA_AES128_SHA
• RSA_AES256_SHA
• DH_DSS_DES_SHA
• DH_DSS_3DES_SHA
• DH_DSS_AES128_SHA
• DH_DSS_AES256_SHA
• DH_RSA_DES_SHA
• DH_RSA_3DES_SHA
• DH_RSA_AES128_SHA
• DH_RSA_AES256_SHA
• DHE_DSS_DES_SHA
• DHE_DSS_3DES_SHA
• DHE_DSS_AES128_SHA
• DHE_DSS_AES256_SHA
• DHE_RSA_DES_SHA
• DHE_RSA_3DES_SHA
• DHE_RSA_AES128_SHA
• DHE_RSA_AES256_SHA
• DH_ANON_RC4_MD5
• DH_ANON_DES_SHA
• DH_ANON_3DES_SHA
• DH_ANON_AES128_SHA
• DH_ANON_AES256_SHA
• RSA_RC2_MD5_EXPORT
• RSA_RC4_MD5_EXPORT
• RSA_DES_SHA_EXPORT
• DH_DSS_DES_SHA_EXPORT
• DH_RSA_DES_SHA_EXPORT
• DHE_DSS_DES_SHA_EXPORT
• DHE_RSA_DES_SHA_EXPORT
• DH_ANON_RC4_MD5_EXPORT
• DH_ANON_DES_SHA_EXPORT
• RSA_CAMELLIA128_SHA
• DH_DSS_CAMELLIA128_SHA
• DH_RSA_CAMELLIA128_SHA
• DHE_DSS_CAMELLIA128_SHA
• DHE_RSA_CAMELLIA128_SHA
• DH_ANON_CAMELLIA128_SHA
• RSA_CAMELLIA256_SHA
• DH_DSS_CAMELLIA256_SHA
• DH_RSA_CAMELLIA256_SHA
• DHE_DSS_CAMELLIA256_SHA
• DHE_RSA_CAMELLIA256_SHA
• DH_ANON_CAMELLIA256_SHA
• PSK_RC4_SHA
• PSK_3DES_SHA
• PSK_AES128_SHA
• PSK_AES256_SHA
• DHE_PSK_RC4_SHA
• DHE_PSK_3DES_SHA
• DHE_PSK_AES128_SHA
• DHE_PSK_AES256_SHA
• RSA_PSK_RC4_SHA
• RSA_PSK_3DES_SHA
• RSA_PSK_AES128_SHA
• RSA_PSK_AES256_SHA
• RSA_SEED_SHA
• DH_DSS_SEED_SHA
• DH_RSA_SEED_SHA
• DHE_DSS_SEED_SHA
• DHE_RSA_SEED_SHA
• DH_ANON_SEED_SHA
• SRP_SHA_3DES_SHA
• SRP_SHA_RSA_3DES_SHA
• SRP_SHA_DSS_3DES_SHA
• SRP_SHA_AES128_SHA
• SRP_SHA_RSA_AES128_SHA
• SRP_SHA_DSS_AES128_SHA
• SRP_SHA_AES256_SHA
• SRP_SHA_RSA_AES256_SHA
• SRP_SHA_DSS_AES256_SHA
• ECDH_ECDSA_NULL_SHA
• ECDH_ECDSA_RC4_SHA
• ECDH_ECDSA_3DES_SHA
• ECDH_ECDSA_AES128_SHA
• ECDH_ECDSA_AES256_SHA
• ECDHE_ECDSA_NULL_SHA
• ECDHE_ECDSA_RC4_SHA
• ECDHE_ECDSA_3DES_SHA
• ECDHE_ECDSA_AES128_SHA
• ECDHE_ECDSA_AES256_SHA
• ECDH_RSA_NULL_SHA
• ECDH_RSA_RC4_SHA
• ECDH_RSA_3DES_SHA
• ECDH_RSA_AES128_SHA
• ECDH_RSA_AES256_SHA
• ECDHE_RSA_NULL_SHA
• ECDHE_RSA_RC4_SHA
• ECDHE_RSA_3DES_SHA
• ECDHE_RSA_AES128_SHA
• ECDHE_RSA_AES256_SHA
• ECDH_ANON_NULL_SHA
• ECDH_ANON_RC4_SHA
• ECDH_ANON_3DES_SHA
• ECDH_ANON_AES128_SHA
• ECDH_ANON_AES256_SHA
• RSA_NULL_SHA256
• RSA_AES128_SHA256
• RSA_AES256_SHA256
• DH_DSS_AES128_SHA256
• DH_RSA_AES128_SHA256
• DHE_DSS_AES128_SHA256
• DHE_RSA_AES128_SHA256
• DH_DSS_AES256_SHA256
• DH_RSA_AES256_SHA256
• DHE_DSS_AES256_SHA256
• DHE_RSA_AES256_SHA256
• DH_ANON_AES128_SHA256
• DH_ANON_AES256_SHA256
• RSA_AES128_GCM_SHA256
• RSA_AES256_GCM_SHA384
• DHE_RSA_AES128_GCM_SHA256
• DHE_RSA_AES256_GCM_SHA384
• DH_RSA_AES128_GCM_SHA256
• DH_RSA_AES256_GCM_SHA384
• DHE_DSS_AES128_GCM_SHA256
• DHE_DSS_AES256_GCM_SHA384
• DH_DSS_AES128_GCM_SHA256
• DH_DSS_AES256_GCM_SHA384
• DH_ANON_AES128_GCM_SHA256
• DH_ANON_AES256_GCM_SHA384
• ECDHE_ECDSA_AES128_SHA256
• ECDHE_ECDSA_AES256_SHA384
• ECDH_ECDSA_AES128_SHA256
• ECDH_ECDSA_AES256_SHA384
• ECDHE_RSA_AES128_SHA256
• ECDHE_RSA_AES256_SHA384
• ECDH_RSA_AES128_SHA256
• ECDH_RSA_AES256_SHA384
• ECDHE_ECDSA_AES128_GCM_SHA256
• ECDHE_ECDSA_AES256_GCM_SHA384
• ECDH_ECDSA_AES128_GCM_SHA256
• ECDH_ECDSA_AES256_GCM_SHA384
• ECDHE_RSA_AES128_GCM_SHA256
• ECDHE_RSA_AES256_GCM_SHA384
• ECDH_RSA_AES128_GCM_SHA256
• ECDH_RSA_AES256_GCM_SHA384
• PSK_AES128_GCM_SHA256
• PSK_AES256_GCM_SHA384
• DHE_PSK_AES128_GCM_SHA256
• DHE_PSK_AES256_GCM_SHA384
• RSA_PSK_AES128_GCM_SHA256
• RSA_PSK_AES256_GCM_SHA384
• PSK_AES128_SHA256
• PSK_AES256_SHA384
• PSK_NULL_SHA256
• PSK_NULL_SHA384
• DHE_PSK_AES128_SHA256
• DHE_PSK_AES256_SHA384
• DHE_PSK_NULL_SHA256
• DHE_PSK_NULL_SHA384
• RSA_PSK_AES128_SHA256
• RSA_PSK_AES256_SHA384
• RSA_PSK_NULL_SHA256
• RSA_PSK_NULL_SHA384
• RSA_CAMELLIA128_SHA256
• DH_DSS_CAMELLIA128_SHA256
• DH_RSA_CAMELLIA128_SHA256
• DHE_DSS_CAMELLIA128_SHA256
• DHE_RSA_CAMELLIA128_SHA256
• DH_ANON_CAMELLIA128_SHA256
• RSA_CAMELLIA256_SHA256
• DH_DSS_CAMELLIA256_SHA256
• DH_RSA_CAMELLIA256_SHA256
• DHE_DSS_CAMELLIA256_SHA256
• DHE_RSA_CAMELLIA256_SHA256
• DH_ANON_CAMELLIA256_SHA256
• ECDHE_ECDSA_CAMELLIA128_SHA256
• ECDHE_ECDSA_CAMELLIA256_SHA384
• ECDH_ECDSA_CAMELLIA128_SHA256
• ECDH_ECDSA_CAMELLIA256_SHA384
• ECDHE_RSA_CAMELLIA128_SHA256
• ECDHE_RSA_CAMELLIA256_SHA384
• ECDH_RSA_CAMELLIA128_SHA256
• ECDH_RSA_CAMELLIA256_SHA384
• RSA_CAMELLIA128_GCM_SHA256
• RSA_CAMELLIA256_GCM_SHA384
• DHE_RSA_CAMELLIA128_GCM_SHA256
• DHE_RSA_CAMELLIA256_GCM_SHA384
• DH_RSA_CAMELLIA128_GCM_SHA256
• DH_RSA_CAMELLIA256_GCM_SHA384
• DHE_DSS_CAMELLIA128_GCM_SHA256
• DHE_DSS_CAMELLIA256_GCM_SHA384
• DH_DSS_CAMELLIA128_GCM_SHA256
• DH_DSS_CAMELLIA256_GCM_SHA384
• DH_anon_CAMELLIA128_GCM_SHA256
• DH_anon_CAMELLIA256_GCM_SHA384
• ECDHE_ECDSA_CAMELLIA128_GCM_SHA256
• ECDHE_ECDSA_CAMELLIA256_GCM_SHA384
• ECDH_ECDSA_CAMELLIA128_GCM_SHA256
• ECDH_ECDSA_CAMELLIA256_GCM_SHA384
• ECDHE_RSA_CAMELLIA128_GCM_SHA256
• ECDHE_RSA_CAMELLIA256_GCM_SHA384
• ECDH_RSA_CAMELLIA128_GCM_SHA256
• ECDH_RSA_CAMELLIA256_GCM_SHA384
• PSK_CAMELLIA128_GCM_SHA256
• PSK_CAMELLIA256_GCM_SHA384
• DHE_PSK_CAMELLIA128_GCM_SHA256
• DHE_PSK_CAMELLIA256_GCM_SHA384
• RSA_PSK_CAMELLIA128_GCM_SHA256
• RSA_PSK_CAMELLIA256_GCM_SHA384
• PSK_CAMELLIA128_SHA256
• PSK_CAMELLIA256_SHA384
• DHE_PSK_CAMELLIA128_SHA256
• DHE_PSK_CAMELLIA256_SHA384
• RSA_PSK_CAMELLIA128_SHA256
• RSA_PSK_CAMELLIA256_SHA384
• ECDHE_PSK_CAMELLIA128_SHA256
• ECDHE_PSK_CAMELLIA256_SHA384
• ECDHE_PSK_RC4_SHA
• ECDHE_PSK_3DES_SHA
• ECDHE_PSK_AES128_SHA
• ECDHE_PSK_AES256_SHA
• ECDHE_PSK_AES128_SHA256
• ECDHE_PSK_AES256_SHA384
• ECDHE_PSK_NULL_SHA
• ECDHE_PSK_NULL_SHA256
• ECDHE_PSK_NULL_SHA384
• ECDHE_RSA_CHACHA20_POLY1305_SHA256
• ECDHE_ECDSA_CHACHA20_POLY1305_SHA256
• DHE_RSA_CHACHA20_POLY1305_SHA256
• PSK_CHACHA20_POLY1305_SHA256
• ECDHE_PSK_CHACHA20_POLY1305_SHA256
• DHE_PSK_CHACHA20_POLY1305_SHA256
• RSA_PSK_CHACHA20_POLY1305_SHA256
• AES128_GCM_SHA256
• AES256_GCM_SHA384
• CHACHA20_POLY1305_SHA256
• AES128_CCM_SHA256
• AES128_CCM8_SHA256

Data Type

String

tls_client_auth property (DCAuth Struct)

Enables or disables certificate-based client authentication.

Syntax

fn tls_client_auth(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_client_auth(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // NoAuth
1   // RequestCert
2   // RequireCert

Default Value

0

Remarks

Enables or disables certificate-based client authentication.

Set this property to true to tune up the client authentication type:

Data Type

i32

tls_extensions property (DCAuth Struct)

Provides access to TLS extensions.

Syntax

fn tls_extensions(&self ) -> Result<String, SecureBlackboxError> 
fn set_tls_extensions(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_tls_extensions_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Provides access to TLS extensions.

Data Type

String

tls_force_resume_if_destination_changes property (DCAuth Struct)

Whether to force TLS session resumption when the destination address changes.

Syntax

fn tls_force_resume_if_destination_changes(&self ) -> Result<bool, SecureBlackboxError> 
fn set_tls_force_resume_if_destination_changes(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

Whether to force TLS session resumption when the destination address changes.

Data Type

bool

tls_groups property (DCAuth Struct)

Specifies a list of key exchange groups to attempt during the TLS key exchange.

Syntax

fn tls_groups(&self ) -> Result<String, SecureBlackboxError> 
fn set_tls_groups(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_tls_groups_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Specifies a list of key exchange groups to attempt during the TLS key exchange.

Keep this setting at its default value (empty string) to stick with the default list of key exchange groups. You can tweak the list by using '+' and '-' modifiers that are immediately followed by a group name or the all placeholder:

// Ensure the two x25519-based groups are enabled and the finite field DHE2048 is disabled client.TLSSettings.Groups = "+x25519mlkem768;+x25519;-ffdhe2048"; // Only enable the hybrid X25519/ML-KEM768 group client.TLSSettings.Groups = "-all;+x25519mlkem768";

The list of groups supported by the component is provided below. All the names are case-insensitive:

Elliptic curve-based groups:

• SECT163K1
• SECT163R1
• SECT163R2
• SECT193R1
• SECT193R2
• SECT233K1
• SECT233R1
• SECT239K1
• SECT283K1
• SECT283R1
• SECT409K1
• SECT409R1
• SECT571K1
• SECT571R1
• SECP160K1
• SECP160R1
• SECP160R2
• SECP192K1
• SECP192R1
• SECP224K1
• SECP224R1
• SECP256K1
• SECP256R1
• SECP384R1
• SECP521R1
• BRAINPOOLP256R1
• BRAINPOOLP384R1
• BRAINPOOLP512R1
• X25519
• X448

Finite field-based groups:

• FFDHE2048
• FFDHE3072
• FFDHE4096
• FFDHE6144
• FFDHE8192

Post-Quantum and Hybrid groups:

• MLKEM512
• MLKEM768
• MLKEM1024
• SECP256R1MLKEM768
• X25519MLKEM768
• SECP384R1MLKEM1024

Note: this property was called ECCurves in SecureBlackbox 2024 and older.

Data Type

String

tls_pre_shared_identity property (DCAuth Struct)

Defines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated.

Syntax

fn tls_pre_shared_identity(&self ) -> Result<String, SecureBlackboxError> 
fn set_tls_pre_shared_identity(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_tls_pre_shared_identity_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Defines the identity used when the PSK (Pre-Shared Key) key-exchange mechanism is negotiated.

Data Type

String

tls_pre_shared_key property (DCAuth Struct)

Contains the pre-shared key for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16.

Syntax

fn tls_pre_shared_key(&self ) -> Result<String, SecureBlackboxError> 
fn set_tls_pre_shared_key(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_tls_pre_shared_key_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Contains the pre-shared key for the PSK (Pre-Shared Key) key-exchange mechanism, encoded with base16.

Data Type

String

tls_pre_shared_key_ciphersuite property (DCAuth Struct)

Defines the ciphersuite used for PSK (Pre-Shared Key) negotiation.

Syntax

fn tls_pre_shared_key_ciphersuite(&self ) -> Result<String, SecureBlackboxError> 
fn set_tls_pre_shared_key_ciphersuite(&self, value : &str) ->  Option<SecureBlackboxError> 
fn set_tls_pre_shared_key_ciphersuite_ref(&self, value : &String) ->  Option<SecureBlackboxError> 

Default Value

""

Remarks

Defines the ciphersuite used for PSK (Pre-Shared Key) negotiation.

Data Type

String

tls_renegotiation_attack_prevention_mode property (DCAuth Struct)

Selects the renegotiation attack prevention mechanism.

Syntax

fn tls_renegotiation_attack_prevention_mode(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_renegotiation_attack_prevention_mode(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // Compatible
1   // Strict
2   // Auto

Default Value

2

Remarks

Selects the renegotiation attack prevention mechanism.

The following options are available:

Data Type

i32

tls_revocation_check property (DCAuth Struct)

Specifies the kind(s) of revocation check to perform.

Syntax

fn tls_revocation_check(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_revocation_check(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // None
1   // Auto
2   // AllCRL
3   // AllOCSP
4   // AllCRLAndOCSP
5   // AnyCRL
6   // AnyOCSP
7   // AnyCRLOrOCSP
8   // AnyOCSPOrCRL

Default Value

1

Remarks

Specifies the kind(s) of revocation check to perform.

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

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.

Data Type

i32

tls_ssl_options property (DCAuth Struct)

Various SSL (TLS) protocol options, set of cssloExpectShutdownMessage 0x001 Wait for the close-notify message when shutting down the connection cssloOpenSSLDTLSWorkaround 0x002 (DEPRECATED) Use a DTLS version workaround when talking to very old OpenSSL versions cssloDisableKexLengthAlignment 0x004 Do not align the client-side PMS by the RSA modulus size.

Syntax

fn tls_ssl_options(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_ssl_options(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

16

Remarks

Various SSL (TLS) protocol options, set of

Data Type

i32

tls_mode property (DCAuth Struct)

Specifies the TLS mode to use.

Syntax

fn tls_mode(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_mode(&self, value : i32) ->  Option<SecureBlackboxError> 

Possible Values

0   // Default
1   // NoTLS
2   // ExplicitTLS
3   // ImplicitTLS
4   // MixedTLS

Default Value

0

Remarks

Specifies the TLS mode to use.

Data Type

i32

tls_use_extended_master_secret property (DCAuth Struct)

Enables the Extended Master Secret Extension, as defined in RFC 7627.

Syntax

fn tls_use_extended_master_secret(&self ) -> Result<bool, SecureBlackboxError> 
fn set_tls_use_extended_master_secret(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

true

Remarks

Enables the Extended Master Secret Extension, as defined in RFC 7627.

Data Type

bool

tls_use_session_resumption property (DCAuth Struct)

Enables or disables the TLS session resumption capability.

Syntax

fn tls_use_session_resumption(&self ) -> Result<bool, SecureBlackboxError> 
fn set_tls_use_session_resumption(&self, value : bool) ->  Option<SecureBlackboxError> 

Default Value

false

Remarks

Enables or disables the TLS session resumption capability.

Data Type

bool

tls_versions property (DCAuth Struct)

The SSL/TLS versions to enable by default.

Syntax

fn tls_versions(&self ) -> Result<i32, SecureBlackboxError> 
fn set_tls_versions(&self, value : i32) ->  Option<SecureBlackboxError> 

Default Value

48

Remarks

The SSL/TLS versions to enable by default.

Data Type

i32

config method (DCAuth Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, SecureBlackboxError>

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, 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.

do_action method (DCAuth Struct)

Performs an additional action.

Syntax

fn do_action(&self, action_id : &str, action_params : &str) ->  Result<String, SecureBlackboxError>

Remarks

do_action is a generic method available in every struct. 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;....

Common ActionIDs:

process_request method (DCAuth Struct)

Processes the request.

Syntax

fn process_request(&self) -> Result<(), SecureBlackboxError>

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 on_sign_request and on_sign_request_completed 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.

reset method (DCAuth Struct)

Resets the struct settings.

Syntax

fn reset(&self) -> Result<(), SecureBlackboxError>

Remarks

reset is a generic method available in every struct.

on_custom_parameters_received event (DCAuth Struct)

Passes custom request parameters to the application.

Syntax

// DCAuthCustomParametersReceivedEventArgs carries the DCAuth CustomParametersReceived event's parameters.
pub struct DCAuthCustomParametersReceivedEventArgs {
  fn value(&self) -> &String
}

// DCAuthCustomParametersReceivedEvent defines the signature of the DCAuth CustomParametersReceived event's handler function.
pub trait DCAuthCustomParametersReceivedEvent {
  fn on_custom_parameters_received(&self, sender : DCAuth, e : &mut DCAuthCustomParametersReceivedEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_custom_parameters_received(&self) -> &'a dyn DCAuthCustomParametersReceivedEvent;
  pub fn set_on_custom_parameters_received(&mut self, value : &'a dyn DCAuthCustomParametersReceivedEvent);
  ...
}

Remarks

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

on_error event (DCAuth Struct)

Reports information about errors during request processing or signing.

Syntax

// DCAuthErrorEventArgs carries the DCAuth Error event's parameters.
pub struct DCAuthErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// DCAuthErrorEvent defines the signature of the DCAuth Error event's handler function.
pub trait DCAuthErrorEvent {
  fn on_error(&self, sender : DCAuth, e : &mut DCAuthErrorEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_error(&self) -> &'a dyn DCAuthErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn DCAuthErrorEvent);
  ...
}

Remarks

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

on_external_sign event (DCAuth Struct)

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

Syntax

// DCAuthExternalSignEventArgs carries the DCAuth ExternalSign event's parameters.
pub struct DCAuthExternalSignEventArgs {
  fn operation_id(&self) -> &String
  fn hash_algorithm(&self) -> &String
  fn pars(&self) -> &String
  fn method_pars(&self) -> &String
  fn data(&self) -> &String
  fn signed_data(&self) -> &String
  fn set_signed_data(&self, value : &str)
  fn set_signed_data_ref(&self, value : &String)
}

// DCAuthExternalSignEvent defines the signature of the DCAuth ExternalSign event's handler function.
pub trait DCAuthExternalSignEvent {
  fn on_external_sign(&self, sender : DCAuth, e : &mut DCAuthExternalSignEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_external_sign(&self) -> &'a dyn DCAuthExternalSignEvent;
  pub fn set_on_external_sign(&mut self, value : &'a dyn DCAuthExternalSignEvent);
  ...
}

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 struct via the SignedData parameter.

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

The struct 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.

on_key_secret_needed event (DCAuth Struct)

Requests the key secret from the application.

Syntax

// DCAuthKeySecretNeededEventArgs carries the DCAuth KeySecretNeeded event's parameters.
pub struct DCAuthKeySecretNeededEventArgs {
  fn key_id(&self) -> &String
  fn key_secret(&self) -> &String
  fn set_key_secret(&self, value : &str)
  fn set_key_secret_ref(&self, value : &String)
}

// DCAuthKeySecretNeededEvent defines the signature of the DCAuth KeySecretNeeded event's handler function.
pub trait DCAuthKeySecretNeededEvent {
  fn on_key_secret_needed(&self, sender : DCAuth, e : &mut DCAuthKeySecretNeededEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_key_secret_needed(&self) -> &'a dyn DCAuthKeySecretNeededEvent;
  pub fn set_on_key_secret_needed(&mut self, value : &'a dyn DCAuthKeySecretNeededEvent);
  ...
}

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 key_secret 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 key_id and key_secret properties would be an easier route.

on_notification event (DCAuth Struct)

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

Syntax

// DCAuthNotificationEventArgs carries the DCAuth Notification event's parameters.
pub struct DCAuthNotificationEventArgs {
  fn event_id(&self) -> &String
  fn event_param(&self) -> &String
}

// DCAuthNotificationEvent defines the signature of the DCAuth Notification event's handler function.
pub trait DCAuthNotificationEvent {
  fn on_notification(&self, sender : DCAuth, e : &mut DCAuthNotificationEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_notification(&self) -> &'a dyn DCAuthNotificationEvent;
  pub fn set_on_notification(&mut self, value : &'a dyn DCAuthNotificationEvent);
  ...
}

Remarks

The struct fires this event to let the application know about some event, occurrence, or milestone in the struct. 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 struct, the exact action it is performing, or the document being processed, one or both may be omitted.

This struct can fire this event with the following EventID values:

on_parameter_received event (DCAuth Struct)

Passes a standard request parameter to the user code.

Syntax

// DCAuthParameterReceivedEventArgs carries the DCAuth ParameterReceived event's parameters.
pub struct DCAuthParameterReceivedEventArgs {
  fn name(&self) -> &String
  fn value(&self) -> &String
}

// DCAuthParameterReceivedEvent defines the signature of the DCAuth ParameterReceived event's handler function.
pub trait DCAuthParameterReceivedEvent {
  fn on_parameter_received(&self, sender : DCAuth, e : &mut DCAuthParameterReceivedEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_parameter_received(&self) -> &'a dyn DCAuthParameterReceivedEvent;
  pub fn set_on_parameter_received(&mut self, value : &'a dyn DCAuthParameterReceivedEvent);
  ...
}

Remarks

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

on_sign_request event (DCAuth Struct)

This event signifies the processing of an atomic signing request.

Syntax

// DCAuthSignRequestEventArgs carries the DCAuth SignRequest event's parameters.
pub struct DCAuthSignRequestEventArgs {
  fn method(&self) -> i32
  fn hash_algorithm(&self) -> &String
  fn hash(&self) -> &[u8]
  fn key_id(&self) -> &String
  fn pars(&self) -> &String
  fn method_pars(&self) -> &String
  fn allow(&self) -> bool
  fn set_allow(&self, value : bool)
}

// DCAuthSignRequestEvent defines the signature of the DCAuth SignRequest event's handler function.
pub trait DCAuthSignRequestEvent {
  fn on_sign_request(&self, sender : DCAuth, e : &mut DCAuthSignRequestEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_sign_request(&self) -> &'a dyn DCAuthSignRequestEvent;
  pub fn set_on_sign_request(&mut self, value : &'a dyn DCAuthSignRequestEvent);
  ...
}

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 on_external_sign, 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 on_sign_request_completed event to track completion of the initiated operation.

on_sign_request_completed event (DCAuth Struct)

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

Syntax

// DCAuthSignRequestCompletedEventArgs carries the DCAuth SignRequestCompleted event's parameters.
pub struct DCAuthSignRequestCompletedEventArgs {
  fn method(&self) -> i32
  fn hash_algorithm(&self) -> &String
  fn hash(&self) -> &[u8]
  fn key_id(&self) -> &String
  fn pars(&self) -> &String
  fn method_pars(&self) -> &String
  fn signature(&self) -> &[u8]
}

// DCAuthSignRequestCompletedEvent defines the signature of the DCAuth SignRequestCompleted event's handler function.
pub trait DCAuthSignRequestCompletedEvent {
  fn on_sign_request_completed(&self, sender : DCAuth, e : &mut DCAuthSignRequestCompletedEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_sign_request_completed(&self) -> &'a dyn DCAuthSignRequestCompletedEvent;
  pub fn set_on_sign_request_completed(&mut self, value : &'a dyn DCAuthSignRequestCompletedEvent);
  ...
}

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 on_sign_request event.

on_timestamp_request event (DCAuth Struct)

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

Syntax

// DCAuthTimestampRequestEventArgs carries the DCAuth TimestampRequest event's parameters.
pub struct DCAuthTimestampRequestEventArgs {
  fn tsa(&self) -> &String
  fn timestamp_request(&self) -> &String
  fn timestamp_response(&self) -> &String
  fn set_timestamp_response(&self, value : &str)
  fn set_timestamp_response_ref(&self, value : &String)
  fn suppress_default(&self) -> bool
  fn set_suppress_default(&self, value : bool)
}

// DCAuthTimestampRequestEvent defines the signature of the DCAuth TimestampRequest event's handler function.
pub trait DCAuthTimestampRequestEvent {
  fn on_timestamp_request(&self, sender : DCAuth, e : &mut DCAuthTimestampRequestEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_timestamp_request(&self) -> &'a dyn DCAuthTimestampRequestEvent;
  pub fn set_on_timestamp_request(&mut self, value : &'a dyn DCAuthTimestampRequestEvent);
  ...
}

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 timestamp_server property. Set the SuppressDefault parameter to true 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.

on_tls_cert_needed event (DCAuth Struct)

Fires when a remote TLS party requests a client certificate.

Syntax

// DCAuthTLSCertNeededEventArgs carries the DCAuth TLSCertNeeded event's parameters.
pub struct DCAuthTLSCertNeededEventArgs {
  fn host(&self) -> &String
  fn ca_names(&self) -> &String
}

// DCAuthTLSCertNeededEvent defines the signature of the DCAuth TLSCertNeeded event's handler function.
pub trait DCAuthTLSCertNeededEvent {
  fn on_tls_cert_needed(&self, sender : DCAuth, e : &mut DCAuthTLSCertNeededEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_tls_cert_needed(&self) -> &'a dyn DCAuthTLSCertNeededEvent;
  pub fn set_on_tls_cert_needed(&mut self, value : &'a dyn DCAuthTLSCertNeededEvent);
  ...
}

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 tls_client_chain 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 on_tls_handshake event for the given host and, if the certificate was accepted, succeeded by the on_tls_established event.

on_tls_cert_validate event (DCAuth Struct)

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

Syntax

// DCAuthTLSCertValidateEventArgs carries the DCAuth TLSCertValidate event's parameters.
pub struct DCAuthTLSCertValidateEventArgs {
  fn server_host(&self) -> &String
  fn server_ip(&self) -> &String
  fn accept(&self) -> bool
  fn set_accept(&self, value : bool)
}

// DCAuthTLSCertValidateEvent defines the signature of the DCAuth TLSCertValidate event's handler function.
pub trait DCAuthTLSCertValidateEvent {
  fn on_tls_cert_validate(&self, sender : DCAuth, e : &mut DCAuthTLSCertValidateEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_tls_cert_validate(&self) -> &'a dyn DCAuthTLSCertValidateEvent;
  pub fn set_on_tls_cert_validate(&mut self, value : &'a dyn DCAuthTLSCertValidateEvent);
  ...
}

Remarks

This event is fired during a TLS handshake. Use the tls_server_chain property to access the certificate chain. In general, structs 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 struct, and can be adjusted if needed.

on_tls_established event (DCAuth Struct)

Fires when a TLS handshake with Host successfully completes.

Syntax

// DCAuthTLSEstablishedEventArgs carries the DCAuth TLSEstablished event's parameters.
pub struct DCAuthTLSEstablishedEventArgs {
  fn host(&self) -> &String
  fn version(&self) -> &String
  fn ciphersuite(&self) -> &String
  fn connection_id(&self) -> &[u8]
  fn abort(&self) -> bool
  fn set_abort(&self, value : bool)
}

// DCAuthTLSEstablishedEvent defines the signature of the DCAuth TLSEstablished event's handler function.
pub trait DCAuthTLSEstablishedEvent {
  fn on_tls_established(&self, sender : DCAuth, e : &mut DCAuthTLSEstablishedEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_tls_established(&self) -> &'a dyn DCAuthTLSEstablishedEvent;
  pub fn set_on_tls_established(&mut self, value : &'a dyn DCAuthTLSEstablishedEvent);
  ...
}

Remarks

The struct 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.

on_tls_handshake event (DCAuth Struct)

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

Syntax

// DCAuthTLSHandshakeEventArgs carries the DCAuth TLSHandshake event's parameters.
pub struct DCAuthTLSHandshakeEventArgs {
  fn host(&self) -> &String
  fn abort(&self) -> bool
  fn set_abort(&self, value : bool)
}

// DCAuthTLSHandshakeEvent defines the signature of the DCAuth TLSHandshake event's handler function.
pub trait DCAuthTLSHandshakeEvent {
  fn on_tls_handshake(&self, sender : DCAuth, e : &mut DCAuthTLSHandshakeEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_tls_handshake(&self) -> &'a dyn DCAuthTLSHandshakeEvent;
  pub fn set_on_tls_handshake(&mut self, value : &'a dyn DCAuthTLSHandshakeEvent);
  ...
}

Remarks

The struct 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 on_tls_established event. If the server chooses to request a client certificate, the on_tls_cert_needed event will also be fired.

on_tls_shutdown event (DCAuth Struct)

Reports the graceful closure of a TLS connection.

Syntax

// DCAuthTLSShutdownEventArgs carries the DCAuth TLSShutdown event's parameters.
pub struct DCAuthTLSShutdownEventArgs {
  fn host(&self) -> &String
}

// DCAuthTLSShutdownEvent defines the signature of the DCAuth TLSShutdown event's handler function.
pub trait DCAuthTLSShutdownEvent {
  fn on_tls_shutdown(&self, sender : DCAuth, e : &mut DCAuthTLSShutdownEventArgs);
}

impl <'a> DCAuth<'a> {
  pub fn on_tls_shutdown(&self) -> &'a dyn DCAuthTLSShutdownEvent;
  pub fn set_on_tls_shutdown(&mut self, value : &'a dyn DCAuthTLSShutdownEvent);
  ...
}

Remarks

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

Config Settings (DCAuth Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

DCAuth Config Settings

Base Config Settings

Trappable Errors (DCAuth Struct)