DCAuth Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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 classes 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 class 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 class with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

ClaimedSigningTime Property (DCAuth Class)

The signing time from the signer's computer.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetClaimedSigningTime();
int SetClaimedSigningTime(const char* lpszClaimedSigningTime);

Unicode (Windows)
LPWSTR GetClaimedSigningTime();
INT SetClaimedSigningTime(LPCWSTR lpszClaimedSigningTime);

char* secureblackbox_dcauth_getclaimedsigningtime(void* lpObj);
int secureblackbox_dcauth_setclaimedsigningtime(void* lpObj, const char* lpszClaimedSigningTime);

QString GetClaimedSigningTime();
int SetClaimedSigningTime(QString qsClaimedSigningTime);

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

ExternalCryptoAsyncDocumentID Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoAsyncDocumentID();
int SetExternalCryptoAsyncDocumentID(const char* lpszExternalCryptoAsyncDocumentID);

Unicode (Windows)
LPWSTR GetExternalCryptoAsyncDocumentID();
INT SetExternalCryptoAsyncDocumentID(LPCWSTR lpszExternalCryptoAsyncDocumentID);

char* secureblackbox_dcauth_getexternalcryptoasyncdocumentid(void* lpObj);
int secureblackbox_dcauth_setexternalcryptoasyncdocumentid(void* lpObj, const char* lpszExternalCryptoAsyncDocumentID);

QString GetExternalCryptoAsyncDocumentID();
int SetExternalCryptoAsyncDocumentID(QString qsExternalCryptoAsyncDocumentID);

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 pre-signing (SignAsyncBegin) and completion (SignAsyncEnd) stages.

Data Type

String

ExternalCryptoCustomParams Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoCustomParams();
int SetExternalCryptoCustomParams(const char* lpszExternalCryptoCustomParams);

Unicode (Windows)
LPWSTR GetExternalCryptoCustomParams();
INT SetExternalCryptoCustomParams(LPCWSTR lpszExternalCryptoCustomParams);

char* secureblackbox_dcauth_getexternalcryptocustomparams(void* lpObj);
int secureblackbox_dcauth_setexternalcryptocustomparams(void* lpObj, const char* lpszExternalCryptoCustomParams);

QString GetExternalCryptoCustomParams();
int SetExternalCryptoCustomParams(QString qsExternalCryptoCustomParams);

Default Value

""

Remarks

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

This property is not available at design time.

Data Type

String

ExternalCryptoData Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoData();
int SetExternalCryptoData(const char* lpszExternalCryptoData);

Unicode (Windows)
LPWSTR GetExternalCryptoData();
INT SetExternalCryptoData(LPCWSTR lpszExternalCryptoData);

char* secureblackbox_dcauth_getexternalcryptodata(void* lpObj);
int secureblackbox_dcauth_setexternalcryptodata(void* lpObj, const char* lpszExternalCryptoData);

QString GetExternalCryptoData();
int SetExternalCryptoData(QString qsExternalCryptoData);

Default Value

""

Remarks

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

This property is not available at design time.

Data Type

String

ExternalCryptoExternalHashCalculation Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetExternalCryptoExternalHashCalculation();
int SetExternalCryptoExternalHashCalculation(int bExternalCryptoExternalHashCalculation);

Unicode (Windows)
BOOL GetExternalCryptoExternalHashCalculation();
INT SetExternalCryptoExternalHashCalculation(BOOL bExternalCryptoExternalHashCalculation);

int secureblackbox_dcauth_getexternalcryptoexternalhashcalculation(void* lpObj);
int secureblackbox_dcauth_setexternalcryptoexternalhashcalculation(void* lpObj, int bExternalCryptoExternalHashCalculation);

bool GetExternalCryptoExternalHashCalculation();
int SetExternalCryptoExternalHashCalculation(bool bExternalCryptoExternalHashCalculation);

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 all components. In particular, components operating with larger objects (PDFSigner, CAdESSigner, XAdESSigner) do not support it.

Data Type

Boolean

ExternalCryptoHashAlgorithm Property (DCAuth Class)

Specifies the request's signature hash algorithm.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoHashAlgorithm();
int SetExternalCryptoHashAlgorithm(const char* lpszExternalCryptoHashAlgorithm);

Unicode (Windows)
LPWSTR GetExternalCryptoHashAlgorithm();
INT SetExternalCryptoHashAlgorithm(LPCWSTR lpszExternalCryptoHashAlgorithm);

char* secureblackbox_dcauth_getexternalcryptohashalgorithm(void* lpObj);
int secureblackbox_dcauth_setexternalcryptohashalgorithm(void* lpObj, const char* lpszExternalCryptoHashAlgorithm);

QString GetExternalCryptoHashAlgorithm();
int SetExternalCryptoHashAlgorithm(QString qsExternalCryptoHashAlgorithm);

Default Value

"SHA256"

Remarks

Specifies the request's signature hash algorithm.

Data Type

String

ExternalCryptoKeyID Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoKeyID();
int SetExternalCryptoKeyID(const char* lpszExternalCryptoKeyID);

Unicode (Windows)
LPWSTR GetExternalCryptoKeyID();
INT SetExternalCryptoKeyID(LPCWSTR lpszExternalCryptoKeyID);

char* secureblackbox_dcauth_getexternalcryptokeyid(void* lpObj);
int secureblackbox_dcauth_setexternalcryptokeyid(void* lpObj, const char* lpszExternalCryptoKeyID);

QString GetExternalCryptoKeyID();
int SetExternalCryptoKeyID(QString qsExternalCryptoKeyID);

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 extra protection layer for the protocol and diminishes the risk of private key becoming abused by foreign parties. Use this property to provide the pre-shared key identifier, and use ExternalCryptoKeySecret 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

ExternalCryptoKeySecret Property (DCAuth Class)

The pre-shared key used for DC request authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoKeySecret();
int SetExternalCryptoKeySecret(const char* lpszExternalCryptoKeySecret);

Unicode (Windows)
LPWSTR GetExternalCryptoKeySecret();
INT SetExternalCryptoKeySecret(LPCWSTR lpszExternalCryptoKeySecret);

char* secureblackbox_dcauth_getexternalcryptokeysecret(void* lpObj);
int secureblackbox_dcauth_setexternalcryptokeysecret(void* lpObj, const char* lpszExternalCryptoKeySecret);

QString GetExternalCryptoKeySecret();
int SetExternalCryptoKeySecret(QString qsExternalCryptoKeySecret);

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 ExternalCryptoKeyID topic.

Data Type

String

ExternalCryptoMethod Property (DCAuth Class)

Specifies the asynchronous signing method.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetExternalCryptoMethod();
int SetExternalCryptoMethod(int iExternalCryptoMethod);

Unicode (Windows)
INT GetExternalCryptoMethod();
INT SetExternalCryptoMethod(INT iExternalCryptoMethod);

ASMD_PKCS1(0), 
ASMD_PKCS7(1)

int secureblackbox_dcauth_getexternalcryptomethod(void* lpObj);
int secureblackbox_dcauth_setexternalcryptomethod(void* lpObj, int iExternalCryptoMethod);

int GetExternalCryptoMethod();
int SetExternalCryptoMethod(int iExternalCryptoMethod);

Default Value

0

Remarks

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

Available options:

Data Type

Integer

ExternalCryptoMode Property (DCAuth Class)

Specifies the external cryptography mode.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetExternalCryptoMode();
int SetExternalCryptoMode(int iExternalCryptoMode);

Unicode (Windows)
INT GetExternalCryptoMode();
INT SetExternalCryptoMode(INT iExternalCryptoMode);

ECM_DEFAULT(0), 
ECM_DISABLED(1), 
ECM_GENERIC(2), 
ECM_DCAUTH(3), 
ECM_DCAUTH_JSON(4)

int secureblackbox_dcauth_getexternalcryptomode(void* lpObj);
int secureblackbox_dcauth_setexternalcryptomode(void* lpObj, int iExternalCryptoMode);

int GetExternalCryptoMode();
int SetExternalCryptoMode(int iExternalCryptoMode);

Default Value

0

Remarks

Specifies the external cryptography mode.

Available options:

This property is not available at design time.

Data Type

Integer

ExternalCryptoPublicKeyAlgorithm Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExternalCryptoPublicKeyAlgorithm();
int SetExternalCryptoPublicKeyAlgorithm(const char* lpszExternalCryptoPublicKeyAlgorithm);

Unicode (Windows)
LPWSTR GetExternalCryptoPublicKeyAlgorithm();
INT SetExternalCryptoPublicKeyAlgorithm(LPCWSTR lpszExternalCryptoPublicKeyAlgorithm);

char* secureblackbox_dcauth_getexternalcryptopublickeyalgorithm(void* lpObj);
int secureblackbox_dcauth_setexternalcryptopublickeyalgorithm(void* lpObj, const char* lpszExternalCryptoPublicKeyAlgorithm);

QString GetExternalCryptoPublicKeyAlgorithm();
int SetExternalCryptoPublicKeyAlgorithm(QString qsExternalCryptoPublicKeyAlgorithm);

Default Value

""

Remarks

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

Data Type

String

FIPSMode Property (DCAuth Class)

Reserved.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFIPSMode();
int SetFIPSMode(int bFIPSMode);

Unicode (Windows)
BOOL GetFIPSMode();
INT SetFIPSMode(BOOL bFIPSMode);

int secureblackbox_dcauth_getfipsmode(void* lpObj);
int secureblackbox_dcauth_setfipsmode(void* lpObj, int bFIPSMode);

bool GetFIPSMode();
int SetFIPSMode(bool bFIPSMode);

Default Value

FALSE

Remarks

This property is reserved for future use.

Data Type

Boolean

Input Property (DCAuth Class)

Contains the signing request to process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetInput();
int SetInput(const char* lpszInput);

Unicode (Windows)
LPWSTR GetInput();
INT SetInput(LPCWSTR lpszInput);

char* secureblackbox_dcauth_getinput(void* lpObj);
int secureblackbox_dcauth_setinput(void* lpObj, const char* lpszInput);

QString GetInput();
int SetInput(QString qsInput);

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.

Data Type

String

InputEncoding Property (DCAuth Class)

Specifies request encoding.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetInputEncoding();
int SetInputEncoding(int iInputEncoding);

Unicode (Windows)
INT GetInputEncoding();
INT SetInputEncoding(INT iInputEncoding);

ENC_NONE(0), 
ENC_AUTO(1), 
ENC_BASE_64(2)

int secureblackbox_dcauth_getinputencoding(void* lpObj);
int secureblackbox_dcauth_setinputencoding(void* lpObj, int iInputEncoding);

int GetInputEncoding();
int SetInputEncoding(int iInputEncoding);

Default Value

0

Remarks

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

Data Type

Integer

KeyId Property (DCAuth Class)

Specifies the KeyID of the pre-shared authentication key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetKeyId();
int SetKeyId(const char* lpszKeyId);

Unicode (Windows)
LPWSTR GetKeyId();
INT SetKeyId(LPCWSTR lpszKeyId);

char* secureblackbox_dcauth_getkeyid(void* lpObj);
int secureblackbox_dcauth_setkeyid(void* lpObj, const char* lpszKeyId);

QString GetKeyId();
int SetKeyId(QString qsKeyId);

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.

Data Type

String

KeySecret Property (DCAuth Class)

The pre-shared authentication key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetKeySecret();
int SetKeySecret(const char* lpszKeySecret);

Unicode (Windows)
LPWSTR GetKeySecret();
INT SetKeySecret(LPCWSTR lpszKeySecret);

char* secureblackbox_dcauth_getkeysecret(void* lpObj);
int secureblackbox_dcauth_setkeysecret(void* lpObj, const char* lpszKeySecret);

QString GetKeySecret();
int SetKeySecret(QString qsKeySecret);

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.

Data Type

String

Output Property (DCAuth Class)

Contains the output of the request processing.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutput();

Unicode (Windows)
LPWSTR GetOutput();

char* secureblackbox_dcauth_getoutput(void* lpObj);

QString GetOutput();

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.

Data Type

String

OutputEncoding Property (DCAuth Class)

Specifies response encoding.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutputEncoding();
int SetOutputEncoding(int iOutputEncoding);

Unicode (Windows)
INT GetOutputEncoding();
INT SetOutputEncoding(INT iOutputEncoding);

ENC_NONE(0), 
ENC_AUTO(1), 
ENC_BASE_64(2)

int secureblackbox_dcauth_getoutputencoding(void* lpObj);
int secureblackbox_dcauth_setoutputencoding(void* lpObj, int iOutputEncoding);

int GetOutputEncoding();
int SetOutputEncoding(int iOutputEncoding);

Default Value

0

Remarks

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

Data Type

Integer

Policies Property (DCAuth Class)

Specifies the policies to use when processing requests.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPolicies();
int SetPolicies(int iPolicies);

Unicode (Windows)
INT GetPolicies();
INT SetPolicies(INT iPolicies);

int secureblackbox_dcauth_getpolicies(void* lpObj);
int secureblackbox_dcauth_setpolicies(void* lpObj, int iPolicies);

int GetPolicies();
int SetPolicies(int iPolicies);

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.

Data Type

Integer

Profile Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProfile();
int SetProfile(const char* lpszProfile);

Unicode (Windows)
LPWSTR GetProfile();
INT SetProfile(LPCWSTR lpszProfile);

char* secureblackbox_dcauth_getprofile(void* lpObj);
int secureblackbox_dcauth_setprofile(void* lpObj, const char* lpszProfile);

QString GetProfile();
int SetProfile(QString qsProfile);

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

ProxyAddress Property (DCAuth Class)

The IP address of the proxy server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyAddress();
int SetProxyAddress(const char* lpszProxyAddress);

Unicode (Windows)
LPWSTR GetProxyAddress();
INT SetProxyAddress(LPCWSTR lpszProxyAddress);

char* secureblackbox_dcauth_getproxyaddress(void* lpObj);
int secureblackbox_dcauth_setproxyaddress(void* lpObj, const char* lpszProxyAddress);

QString GetProxyAddress();
int SetProxyAddress(QString qsProxyAddress);

Default Value

""

Remarks

The IP address of the proxy server.

Data Type

String

ProxyAuthentication Property (DCAuth Class)

The authentication type used by the proxy server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyAuthentication();
int SetProxyAuthentication(int iProxyAuthentication);

Unicode (Windows)
INT GetProxyAuthentication();
INT SetProxyAuthentication(INT iProxyAuthentication);

PAT_NO_AUTHENTICATION(0), 
PAT_BASIC(1), 
PAT_DIGEST(2), 
PAT_NTLM(3)

int secureblackbox_dcauth_getproxyauthentication(void* lpObj);
int secureblackbox_dcauth_setproxyauthentication(void* lpObj, int iProxyAuthentication);

int GetProxyAuthentication();
int SetProxyAuthentication(int iProxyAuthentication);

Default Value

0

Remarks

The authentication type used by the proxy server.

Data Type

Integer

ProxyPassword Property (DCAuth Class)

The password to authenticate to the proxy server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyPassword();
int SetProxyPassword(const char* lpszProxyPassword);

Unicode (Windows)
LPWSTR GetProxyPassword();
INT SetProxyPassword(LPCWSTR lpszProxyPassword);

char* secureblackbox_dcauth_getproxypassword(void* lpObj);
int secureblackbox_dcauth_setproxypassword(void* lpObj, const char* lpszProxyPassword);

QString GetProxyPassword();
int SetProxyPassword(QString qsProxyPassword);

Default Value

""

Remarks

The password to authenticate to the proxy server.

Data Type

String

ProxyPort Property (DCAuth Class)

The port on the proxy server to connect to.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyPort();
int SetProxyPort(int iProxyPort);

Unicode (Windows)
INT GetProxyPort();
INT SetProxyPort(INT iProxyPort);

int secureblackbox_dcauth_getproxyport(void* lpObj);
int secureblackbox_dcauth_setproxyport(void* lpObj, int iProxyPort);

int GetProxyPort();
int SetProxyPort(int iProxyPort);

Default Value

0

Remarks

The port on the proxy server to connect to.

Data Type

Integer

ProxyProxyType Property (DCAuth Class)

The type of the proxy server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyProxyType();
int SetProxyProxyType(int iProxyProxyType);

Unicode (Windows)
INT GetProxyProxyType();
INT SetProxyProxyType(INT iProxyProxyType);

CPT_NONE(0), 
CPT_SOCKS_4(1), 
CPT_SOCKS_5(2), 
CPT_WEB_TUNNEL(3), 
CPT_HTTP(4)

int secureblackbox_dcauth_getproxyproxytype(void* lpObj);
int secureblackbox_dcauth_setproxyproxytype(void* lpObj, int iProxyProxyType);

int GetProxyProxyType();
int SetProxyProxyType(int iProxyProxyType);

Default Value

0

Remarks

The type of the proxy server.

The WebTunnel proxy is also known as HTTPS proxy. Unlike HTTP proxy, HTTPS proxy (WebTunnel) provides end-to-end security.

Data Type

Integer

ProxyRequestHeaders Property (DCAuth Class)

Contains HTTP request headers for WebTunnel and HTTP proxy.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyRequestHeaders();
int SetProxyRequestHeaders(const char* lpszProxyRequestHeaders);

Unicode (Windows)
LPWSTR GetProxyRequestHeaders();
INT SetProxyRequestHeaders(LPCWSTR lpszProxyRequestHeaders);

char* secureblackbox_dcauth_getproxyrequestheaders(void* lpObj);
int secureblackbox_dcauth_setproxyrequestheaders(void* lpObj, const char* lpszProxyRequestHeaders);

QString GetProxyRequestHeaders();
int SetProxyRequestHeaders(QString qsProxyRequestHeaders);

Default Value

""

Remarks

Contains HTTP request headers for WebTunnel and HTTP proxy.

Data Type

String

ProxyResponseBody Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyResponseBody();
int SetProxyResponseBody(const char* lpszProxyResponseBody);

Unicode (Windows)
LPWSTR GetProxyResponseBody();
INT SetProxyResponseBody(LPCWSTR lpszProxyResponseBody);

char* secureblackbox_dcauth_getproxyresponsebody(void* lpObj);
int secureblackbox_dcauth_setproxyresponsebody(void* lpObj, const char* lpszProxyResponseBody);

QString GetProxyResponseBody();
int SetProxyResponseBody(QString qsProxyResponseBody);

Default Value

""

Remarks

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

Data Type

String

ProxyResponseHeaders Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyResponseHeaders();
int SetProxyResponseHeaders(const char* lpszProxyResponseHeaders);

Unicode (Windows)
LPWSTR GetProxyResponseHeaders();
INT SetProxyResponseHeaders(LPCWSTR lpszProxyResponseHeaders);

char* secureblackbox_dcauth_getproxyresponseheaders(void* lpObj);
int secureblackbox_dcauth_setproxyresponseheaders(void* lpObj, const char* lpszProxyResponseHeaders);

QString GetProxyResponseHeaders();
int SetProxyResponseHeaders(QString qsProxyResponseHeaders);

Default Value

""

Remarks

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

Data Type

String

ProxyUseIPv6 Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyUseIPv6();
int SetProxyUseIPv6(int bProxyUseIPv6);

Unicode (Windows)
BOOL GetProxyUseIPv6();
INT SetProxyUseIPv6(BOOL bProxyUseIPv6);

int secureblackbox_dcauth_getproxyuseipv6(void* lpObj);
int secureblackbox_dcauth_setproxyuseipv6(void* lpObj, int bProxyUseIPv6);

bool GetProxyUseIPv6();
int SetProxyUseIPv6(bool bProxyUseIPv6);

Default Value

FALSE

Remarks

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

Data Type

Boolean

ProxyUseProxy Property (DCAuth Class)

Enables or disables proxy-driven connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProxyUseProxy();
int SetProxyUseProxy(int bProxyUseProxy);

Unicode (Windows)
BOOL GetProxyUseProxy();
INT SetProxyUseProxy(BOOL bProxyUseProxy);

int secureblackbox_dcauth_getproxyuseproxy(void* lpObj);
int secureblackbox_dcauth_setproxyuseproxy(void* lpObj, int bProxyUseProxy);

bool GetProxyUseProxy();
int SetProxyUseProxy(bool bProxyUseProxy);

Default Value

FALSE

Remarks

Enables or disables proxy-driven connection.

Data Type

Boolean

ProxyUsername Property (DCAuth Class)

Specifies the username credential for proxy authentication.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetProxyUsername();
int SetProxyUsername(const char* lpszProxyUsername);

Unicode (Windows)
LPWSTR GetProxyUsername();
INT SetProxyUsername(LPCWSTR lpszProxyUsername);

char* secureblackbox_dcauth_getproxyusername(void* lpObj);
int secureblackbox_dcauth_setproxyusername(void* lpObj, const char* lpszProxyUsername);

QString GetProxyUsername();
int SetProxyUsername(QString qsProxyUsername);

Default Value

""

Remarks

Specifies the username credential for proxy authentication.

Data Type

String

SigningCertBytes Property (DCAuth Class)

Returns raw certificate data in DER format.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSigningCertBytes(char* &lpSigningCertBytes, int &lenSigningCertBytes);

Unicode (Windows)
INT GetSigningCertBytes(LPSTR &lpSigningCertBytes, INT &lenSigningCertBytes);

int secureblackbox_dcauth_getsigningcertbytes(void* lpObj, char** lpSigningCertBytes, int* lenSigningCertBytes);

QByteArray GetSigningCertBytes();

Remarks

Returns raw certificate data in DER format.

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

Data Type

Byte Array

SigningCertHandle Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSigningCertHandle();
int SetSigningCertHandle(int64 lSigningCertHandle);

Unicode (Windows)
LONG64 GetSigningCertHandle();
INT SetSigningCertHandle(LONG64 lSigningCertHandle);

int64 secureblackbox_dcauth_getsigningcerthandle(void* lpObj);
int secureblackbox_dcauth_setsigningcerthandle(void* lpObj, int64 lSigningCertHandle);

qint64 GetSigningCertHandle();
int SetSigningCertHandle(qint64 lSigningCertHandle);

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());

This property is not available at design time.

Data Type

Long64

SigningChainCount Property (DCAuth Class)

The number of records in the SigningChain arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSigningChainCount();
int SetSigningChainCount(int iSigningChainCount);

Unicode (Windows)
INT GetSigningChainCount();
INT SetSigningChainCount(INT iSigningChainCount);

int secureblackbox_dcauth_getsigningchaincount(void* lpObj);
int secureblackbox_dcauth_setsigningchaincount(void* lpObj, int iSigningChainCount);

int GetSigningChainCount();
int SetSigningChainCount(int iSigningChainCount);

Default Value

0

Remarks

This property controls the size of the following arrays:

• SigningChainBytes
• SigningChainHandle

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

This property is not available at design time.

Data Type

Integer

SigningChainBytes Property (DCAuth Class)

Returns raw certificate data in DER format.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSigningChainBytes(int iSigningChainIndex, char* &lpSigningChainBytes, int &lenSigningChainBytes);

Unicode (Windows)
INT GetSigningChainBytes(INT iSigningChainIndex, LPSTR &lpSigningChainBytes, INT &lenSigningChainBytes);

int secureblackbox_dcauth_getsigningchainbytes(void* lpObj, int signingchainindex, char** lpSigningChainBytes, int* lenSigningChainBytes);

QByteArray GetSigningChainBytes(int iSigningChainIndex);

Remarks

Returns 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 and not available at design time.

Data Type

Byte Array

SigningChainHandle Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSigningChainHandle(int iSigningChainIndex);
int SetSigningChainHandle(int iSigningChainIndex, int64 lSigningChainHandle);

Unicode (Windows)
LONG64 GetSigningChainHandle(INT iSigningChainIndex);
INT SetSigningChainHandle(INT iSigningChainIndex, LONG64 lSigningChainHandle);

int64 secureblackbox_dcauth_getsigningchainhandle(void* lpObj, int signingchainindex);
int secureblackbox_dcauth_setsigningchainhandle(void* lpObj, int signingchainindex, int64 lSigningChainHandle);

qint64 GetSigningChainHandle(int iSigningChainIndex);
int SetSigningChainHandle(int iSigningChainIndex, qint64 lSigningChainHandle);

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.

This property is not available at design time.

Data Type

Long64

SocketDNSMode Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketDNSMode();
int SetSocketDNSMode(int iSocketDNSMode);

Unicode (Windows)
INT GetSocketDNSMode();
INT SetSocketDNSMode(INT iSocketDNSMode);

DM_AUTO(0), 
DM_PLATFORM(1), 
DM_OWN(2), 
DM_OWN_SECURE(3)

int secureblackbox_dcauth_getsocketdnsmode(void* lpObj);
int secureblackbox_dcauth_setsocketdnsmode(void* lpObj, int iSocketDNSMode);

int GetSocketDNSMode();
int SetSocketDNSMode(int iSocketDNSMode);

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

Integer

SocketDNSPort Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketDNSPort();
int SetSocketDNSPort(int iSocketDNSPort);

Unicode (Windows)
INT GetSocketDNSPort();
INT SetSocketDNSPort(INT iSocketDNSPort);

int secureblackbox_dcauth_getsocketdnsport(void* lpObj);
int secureblackbox_dcauth_setsocketdnsport(void* lpObj, int iSocketDNSPort);

int GetSocketDNSPort();
int SetSocketDNSPort(int iSocketDNSPort);

Default Value

0

Remarks

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

Data Type

Integer

SocketDNSQueryTimeout Property (DCAuth Class)

The timeout (in milliseconds) for each DNS query.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketDNSQueryTimeout();
int SetSocketDNSQueryTimeout(int iSocketDNSQueryTimeout);

Unicode (Windows)
INT GetSocketDNSQueryTimeout();
INT SetSocketDNSQueryTimeout(INT iSocketDNSQueryTimeout);

int secureblackbox_dcauth_getsocketdnsquerytimeout(void* lpObj);
int secureblackbox_dcauth_setsocketdnsquerytimeout(void* lpObj, int iSocketDNSQueryTimeout);

int GetSocketDNSQueryTimeout();
int SetSocketDNSQueryTimeout(int iSocketDNSQueryTimeout);

Default Value

0

Remarks

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

Data Type

Integer

SocketDNSServers Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSocketDNSServers();
int SetSocketDNSServers(const char* lpszSocketDNSServers);

Unicode (Windows)
LPWSTR GetSocketDNSServers();
INT SetSocketDNSServers(LPCWSTR lpszSocketDNSServers);

char* secureblackbox_dcauth_getsocketdnsservers(void* lpObj);
int secureblackbox_dcauth_setsocketdnsservers(void* lpObj, const char* lpszSocketDNSServers);

QString GetSocketDNSServers();
int SetSocketDNSServers(QString qsSocketDNSServers);

Default Value

""

Remarks

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

Data Type

String

SocketDNSTotalTimeout Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketDNSTotalTimeout();
int SetSocketDNSTotalTimeout(int iSocketDNSTotalTimeout);

Unicode (Windows)
INT GetSocketDNSTotalTimeout();
INT SetSocketDNSTotalTimeout(INT iSocketDNSTotalTimeout);

int secureblackbox_dcauth_getsocketdnstotaltimeout(void* lpObj);
int secureblackbox_dcauth_setsocketdnstotaltimeout(void* lpObj, int iSocketDNSTotalTimeout);

int GetSocketDNSTotalTimeout();
int SetSocketDNSTotalTimeout(int iSocketDNSTotalTimeout);

Default Value

0

Remarks

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

Data Type

Integer

SocketIncomingSpeedLimit Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketIncomingSpeedLimit();
int SetSocketIncomingSpeedLimit(int iSocketIncomingSpeedLimit);

Unicode (Windows)
INT GetSocketIncomingSpeedLimit();
INT SetSocketIncomingSpeedLimit(INT iSocketIncomingSpeedLimit);

int secureblackbox_dcauth_getsocketincomingspeedlimit(void* lpObj);
int secureblackbox_dcauth_setsocketincomingspeedlimit(void* lpObj, int iSocketIncomingSpeedLimit);

int GetSocketIncomingSpeedLimit();
int SetSocketIncomingSpeedLimit(int iSocketIncomingSpeedLimit);

Default Value

0

Remarks

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

Data Type

Integer

SocketLocalAddress Property (DCAuth Class)

The local network interface to bind the socket to.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSocketLocalAddress();
int SetSocketLocalAddress(const char* lpszSocketLocalAddress);

Unicode (Windows)
LPWSTR GetSocketLocalAddress();
INT SetSocketLocalAddress(LPCWSTR lpszSocketLocalAddress);

char* secureblackbox_dcauth_getsocketlocaladdress(void* lpObj);
int secureblackbox_dcauth_setsocketlocaladdress(void* lpObj, const char* lpszSocketLocalAddress);

QString GetSocketLocalAddress();
int SetSocketLocalAddress(QString qsSocketLocalAddress);

Default Value

""

Remarks

The local network interface to bind the socket to.

Data Type

String

SocketLocalPort Property (DCAuth Class)

The local port number to bind the socket to.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketLocalPort();
int SetSocketLocalPort(int iSocketLocalPort);

Unicode (Windows)
INT GetSocketLocalPort();
INT SetSocketLocalPort(INT iSocketLocalPort);

int secureblackbox_dcauth_getsocketlocalport(void* lpObj);
int secureblackbox_dcauth_setsocketlocalport(void* lpObj, int iSocketLocalPort);

int GetSocketLocalPort();
int SetSocketLocalPort(int iSocketLocalPort);

Default Value

0

Remarks

The local port number to bind the socket to.

Data Type

Integer

SocketOutgoingSpeedLimit Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketOutgoingSpeedLimit();
int SetSocketOutgoingSpeedLimit(int iSocketOutgoingSpeedLimit);

Unicode (Windows)
INT GetSocketOutgoingSpeedLimit();
INT SetSocketOutgoingSpeedLimit(INT iSocketOutgoingSpeedLimit);

int secureblackbox_dcauth_getsocketoutgoingspeedlimit(void* lpObj);
int secureblackbox_dcauth_setsocketoutgoingspeedlimit(void* lpObj, int iSocketOutgoingSpeedLimit);

int GetSocketOutgoingSpeedLimit();
int SetSocketOutgoingSpeedLimit(int iSocketOutgoingSpeedLimit);

Default Value

0

Remarks

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

Data Type

Integer

SocketTimeout Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketTimeout();
int SetSocketTimeout(int iSocketTimeout);

Unicode (Windows)
INT GetSocketTimeout();
INT SetSocketTimeout(INT iSocketTimeout);

int secureblackbox_dcauth_getsockettimeout(void* lpObj);
int secureblackbox_dcauth_setsockettimeout(void* lpObj, int iSocketTimeout);

int GetSocketTimeout();
int SetSocketTimeout(int iSocketTimeout);

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

Integer

SocketUseIPv6 Property (DCAuth Class)

Enables or disables IP protocol version 6.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSocketUseIPv6();
int SetSocketUseIPv6(int bSocketUseIPv6);

Unicode (Windows)
BOOL GetSocketUseIPv6();
INT SetSocketUseIPv6(BOOL bSocketUseIPv6);

int secureblackbox_dcauth_getsocketuseipv6(void* lpObj);
int secureblackbox_dcauth_setsocketuseipv6(void* lpObj, int bSocketUseIPv6);

bool GetSocketUseIPv6();
int SetSocketUseIPv6(bool bSocketUseIPv6);

Default Value

FALSE

Remarks

Enables or disables IP protocol version 6.

Data Type

Boolean

StorageId Property (DCAuth Class)

Specifies the signing certificate residing in an alternative location.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetStorageId();
int SetStorageId(const char* lpszStorageId);

Unicode (Windows)
LPWSTR GetStorageId();
INT SetStorageId(LPCWSTR lpszStorageId);

char* secureblackbox_dcauth_getstorageid(void* lpObj);
int secureblackbox_dcauth_setstorageid(void* lpObj, const char* lpszStorageId);

QString GetStorageId();
int SetStorageId(QString qsStorageId);

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

TimestampServer Property (DCAuth Class)

The address of the timestamping server.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTimestampServer();
int SetTimestampServer(const char* lpszTimestampServer);

Unicode (Windows)
LPWSTR GetTimestampServer();
INT SetTimestampServer(LPCWSTR lpszTimestampServer);

char* secureblackbox_dcauth_gettimestampserver(void* lpObj);
int secureblackbox_dcauth_settimestampserver(void* lpObj, const char* lpszTimestampServer);

QString GetTimestampServer();
int SetTimestampServer(QString qsTimestampServer);

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.

Data Type

String

TLSClientCertCount Property (DCAuth Class)

The number of records in the TLSClientCert arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSClientCertCount();
int SetTLSClientCertCount(int iTLSClientCertCount);

Unicode (Windows)
INT GetTLSClientCertCount();
INT SetTLSClientCertCount(INT iTLSClientCertCount);

int secureblackbox_dcauth_gettlsclientcertcount(void* lpObj);
int secureblackbox_dcauth_settlsclientcertcount(void* lpObj, int iTLSClientCertCount);

int GetTLSClientCertCount();
int SetTLSClientCertCount(int iTLSClientCertCount);

Default Value

0

Remarks

This property controls the size of the following arrays:

• TLSClientCertBytes
• TLSClientCertHandle

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

This property is not available at design time.

Data Type

Integer

TLSClientCertBytes Property (DCAuth Class)

Returns raw certificate data in DER format.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSClientCertBytes(int iTLSClientCertIndex, char* &lpTLSClientCertBytes, int &lenTLSClientCertBytes);

Unicode (Windows)
INT GetTLSClientCertBytes(INT iTLSClientCertIndex, LPSTR &lpTLSClientCertBytes, INT &lenTLSClientCertBytes);

int secureblackbox_dcauth_gettlsclientcertbytes(void* lpObj, int tlsclientcertindex, char** lpTLSClientCertBytes, int* lenTLSClientCertBytes);

QByteArray GetTLSClientCertBytes(int iTLSClientCertIndex);

Remarks

Returns 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 and not available at design time.

Data Type

Byte Array

TLSClientCertHandle Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetTLSClientCertHandle(int iTLSClientCertIndex);
int SetTLSClientCertHandle(int iTLSClientCertIndex, int64 lTLSClientCertHandle);

Unicode (Windows)
LONG64 GetTLSClientCertHandle(INT iTLSClientCertIndex);
INT SetTLSClientCertHandle(INT iTLSClientCertIndex, LONG64 lTLSClientCertHandle);

int64 secureblackbox_dcauth_gettlsclientcerthandle(void* lpObj, int tlsclientcertindex);
int secureblackbox_dcauth_settlsclientcerthandle(void* lpObj, int tlsclientcertindex, int64 lTLSClientCertHandle);

qint64 GetTLSClientCertHandle(int iTLSClientCertIndex);
int SetTLSClientCertHandle(int iTLSClientCertIndex, qint64 lTLSClientCertHandle);

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.

This property is not available at design time.

Data Type

Long64

TLSServerCertCount Property (DCAuth Class)

The number of records in the TLSServerCert arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSServerCertCount();

Unicode (Windows)
INT GetTLSServerCertCount();

int secureblackbox_dcauth_gettlsservercertcount(void* lpObj);

int GetTLSServerCertCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• TLSServerCertBytes
• TLSServerCertHandle

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

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

Data Type

Integer

TLSServerCertBytes Property (DCAuth Class)

Returns raw certificate data in DER format.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSServerCertBytes(int iTLSServerCertIndex, char* &lpTLSServerCertBytes, int &lenTLSServerCertBytes);

Unicode (Windows)
INT GetTLSServerCertBytes(INT iTLSServerCertIndex, LPSTR &lpTLSServerCertBytes, INT &lenTLSServerCertBytes);

int secureblackbox_dcauth_gettlsservercertbytes(void* lpObj, int tlsservercertindex, char** lpTLSServerCertBytes, int* lenTLSServerCertBytes);

QByteArray GetTLSServerCertBytes(int iTLSServerCertIndex);

Remarks

Returns 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 and not available at design time.

Data Type

Byte Array

TLSServerCertHandle Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetTLSServerCertHandle(int iTLSServerCertIndex);

Unicode (Windows)
LONG64 GetTLSServerCertHandle(INT iTLSServerCertIndex);

int64 secureblackbox_dcauth_gettlsservercerthandle(void* lpObj, int tlsservercertindex);

qint64 GetTLSServerCertHandle(int iTLSServerCertIndex);

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 and not available at design time.

Data Type

Long64

TLSAutoValidateCertificates Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSAutoValidateCertificates();
int SetTLSAutoValidateCertificates(int bTLSAutoValidateCertificates);

Unicode (Windows)
BOOL GetTLSAutoValidateCertificates();
INT SetTLSAutoValidateCertificates(BOOL bTLSAutoValidateCertificates);

int secureblackbox_dcauth_gettlsautovalidatecertificates(void* lpObj);
int secureblackbox_dcauth_settlsautovalidatecertificates(void* lpObj, int bTLSAutoValidateCertificates);

bool GetTLSAutoValidateCertificates();
int SetTLSAutoValidateCertificates(bool bTLSAutoValidateCertificates);

Default Value

TRUE

Remarks

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

Data Type

Boolean

TLSBaseConfiguration Property (DCAuth Class)

Selects the base configuration for the TLS settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSBaseConfiguration();
int SetTLSBaseConfiguration(int iTLSBaseConfiguration);

Unicode (Windows)
INT GetTLSBaseConfiguration();
INT SetTLSBaseConfiguration(INT iTLSBaseConfiguration);

STPC_DEFAULT(0), 
STPC_COMPATIBLE(1), 
STPC_COMPREHENSIVE_INSECURE(2), 
STPC_HIGHLY_SECURE(3)

int secureblackbox_dcauth_gettlsbaseconfiguration(void* lpObj);
int secureblackbox_dcauth_settlsbaseconfiguration(void* lpObj, int iTLSBaseConfiguration);

int GetTLSBaseConfiguration();
int SetTLSBaseConfiguration(int iTLSBaseConfiguration);

Default Value

0

Remarks

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

Data Type

Integer

TLSCiphersuites Property (DCAuth Class)

A list of ciphersuites separated with commas or semicolons.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTLSCiphersuites();
int SetTLSCiphersuites(const char* lpszTLSCiphersuites);

Unicode (Windows)
LPWSTR GetTLSCiphersuites();
INT SetTLSCiphersuites(LPCWSTR lpszTLSCiphersuites);

char* secureblackbox_dcauth_gettlsciphersuites(void* lpObj);
int secureblackbox_dcauth_settlsciphersuites(void* lpObj, const char* lpszTLSCiphersuites);

QString GetTLSCiphersuites();
int SetTLSCiphersuites(QString qsTLSCiphersuites);

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 that allow to blanketly enable or disable all ciphersuites at once.

Note: the list of ciphersuites provided to this property alters the baseline list of ciphersuites as defined by BaseConfiguration. 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

TLSECCurves Property (DCAuth Class)

Defines the elliptic curves to enable.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTLSECCurves();
int SetTLSECCurves(const char* lpszTLSECCurves);

Unicode (Windows)
LPWSTR GetTLSECCurves();
INT SetTLSECCurves(LPCWSTR lpszTLSECCurves);

char* secureblackbox_dcauth_gettlseccurves(void* lpObj);
int secureblackbox_dcauth_settlseccurves(void* lpObj, const char* lpszTLSECCurves);

QString GetTLSECCurves();
int SetTLSECCurves(QString qsTLSECCurves);

Default Value

""

Remarks

Defines the elliptic curves to enable.

Data Type

String

TLSExtensions Property (DCAuth Class)

Provides access to TLS extensions.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTLSExtensions();
int SetTLSExtensions(const char* lpszTLSExtensions);

Unicode (Windows)
LPWSTR GetTLSExtensions();
INT SetTLSExtensions(LPCWSTR lpszTLSExtensions);

char* secureblackbox_dcauth_gettlsextensions(void* lpObj);
int secureblackbox_dcauth_settlsextensions(void* lpObj, const char* lpszTLSExtensions);

QString GetTLSExtensions();
int SetTLSExtensions(QString qsTLSExtensions);

Default Value

""

Remarks

Provides access to TLS extensions.

Data Type

String

TLSForceResumeIfDestinationChanges Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSForceResumeIfDestinationChanges();
int SetTLSForceResumeIfDestinationChanges(int bTLSForceResumeIfDestinationChanges);

Unicode (Windows)
BOOL GetTLSForceResumeIfDestinationChanges();
INT SetTLSForceResumeIfDestinationChanges(BOOL bTLSForceResumeIfDestinationChanges);

int secureblackbox_dcauth_gettlsforceresumeifdestinationchanges(void* lpObj);
int secureblackbox_dcauth_settlsforceresumeifdestinationchanges(void* lpObj, int bTLSForceResumeIfDestinationChanges);

bool GetTLSForceResumeIfDestinationChanges();
int SetTLSForceResumeIfDestinationChanges(bool bTLSForceResumeIfDestinationChanges);

Default Value

FALSE

Remarks

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

Data Type

Boolean

TLSPreSharedIdentity Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTLSPreSharedIdentity();
int SetTLSPreSharedIdentity(const char* lpszTLSPreSharedIdentity);

Unicode (Windows)
LPWSTR GetTLSPreSharedIdentity();
INT SetTLSPreSharedIdentity(LPCWSTR lpszTLSPreSharedIdentity);

char* secureblackbox_dcauth_gettlspresharedidentity(void* lpObj);
int secureblackbox_dcauth_settlspresharedidentity(void* lpObj, const char* lpszTLSPreSharedIdentity);

QString GetTLSPreSharedIdentity();
int SetTLSPreSharedIdentity(QString qsTLSPreSharedIdentity);

Default Value

""

Remarks

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

This property is not available at design time.

Data Type

String

TLSPreSharedKey Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTLSPreSharedKey();
int SetTLSPreSharedKey(const char* lpszTLSPreSharedKey);

Unicode (Windows)
LPWSTR GetTLSPreSharedKey();
INT SetTLSPreSharedKey(LPCWSTR lpszTLSPreSharedKey);

char* secureblackbox_dcauth_gettlspresharedkey(void* lpObj);
int secureblackbox_dcauth_settlspresharedkey(void* lpObj, const char* lpszTLSPreSharedKey);

QString GetTLSPreSharedKey();
int SetTLSPreSharedKey(QString qsTLSPreSharedKey);

Default Value

""

Remarks

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

This property is not available at design time.

Data Type

String

TLSPreSharedKeyCiphersuite Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetTLSPreSharedKeyCiphersuite();
int SetTLSPreSharedKeyCiphersuite(const char* lpszTLSPreSharedKeyCiphersuite);

Unicode (Windows)
LPWSTR GetTLSPreSharedKeyCiphersuite();
INT SetTLSPreSharedKeyCiphersuite(LPCWSTR lpszTLSPreSharedKeyCiphersuite);

char* secureblackbox_dcauth_gettlspresharedkeyciphersuite(void* lpObj);
int secureblackbox_dcauth_settlspresharedkeyciphersuite(void* lpObj, const char* lpszTLSPreSharedKeyCiphersuite);

QString GetTLSPreSharedKeyCiphersuite();
int SetTLSPreSharedKeyCiphersuite(QString qsTLSPreSharedKeyCiphersuite);

Default Value

""

Remarks

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

Data Type

String

TLSRenegotiationAttackPreventionMode Property (DCAuth Class)

Selects renegotiation attack prevention mechanism.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSRenegotiationAttackPreventionMode();
int SetTLSRenegotiationAttackPreventionMode(int iTLSRenegotiationAttackPreventionMode);

Unicode (Windows)
INT GetTLSRenegotiationAttackPreventionMode();
INT SetTLSRenegotiationAttackPreventionMode(INT iTLSRenegotiationAttackPreventionMode);

CRAPM_COMPATIBLE(0), 
CRAPM_STRICT(1), 
CRAPM_AUTO(2)

int secureblackbox_dcauth_gettlsrenegotiationattackpreventionmode(void* lpObj);
int secureblackbox_dcauth_settlsrenegotiationattackpreventionmode(void* lpObj, int iTLSRenegotiationAttackPreventionMode);

int GetTLSRenegotiationAttackPreventionMode();
int SetTLSRenegotiationAttackPreventionMode(int iTLSRenegotiationAttackPreventionMode);

Default Value

0

Remarks

Selects renegotiation attack prevention mechanism.

The following options are available:

Data Type

Integer

TLSRevocationCheck Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSRevocationCheck();
int SetTLSRevocationCheck(int iTLSRevocationCheck);

Unicode (Windows)
INT GetTLSRevocationCheck();
INT SetTLSRevocationCheck(INT iTLSRevocationCheck);

CRC_NONE(0), 
CRC_AUTO(1), 
CRC_ALL_CRL(2), 
CRC_ALL_OCSP(3), 
CRC_ALL_CRLAND_OCSP(4), 
CRC_ANY_CRL(5), 
CRC_ANY_OCSP(6), 
CRC_ANY_CRLOR_OCSP(7), 
CRC_ANY_OCSPOR_CRL(8)

int secureblackbox_dcauth_gettlsrevocationcheck(void* lpObj);
int secureblackbox_dcauth_settlsrevocationcheck(void* lpObj, int iTLSRevocationCheck);

int GetTLSRevocationCheck();
int SetTLSRevocationCheck(int iTLSRevocationCheck);

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. 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 faster OCSP route and only demand one source to succeed) is a good choice for most of typical validation environments. The "crcAll*" modes are much stricter, and may be used in scenarios where bulletproof validity information is essential.

This property is not available at design time.

Data Type

Integer

TLSSSLOptions Property (DCAuth Class)

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

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSSSLOptions();
int SetTLSSSLOptions(int iTLSSSLOptions);

Unicode (Windows)
INT GetTLSSSLOptions();
INT SetTLSSSLOptions(INT iTLSSSLOptions);

int secureblackbox_dcauth_gettlsssloptions(void* lpObj);
int secureblackbox_dcauth_settlsssloptions(void* lpObj, int iTLSSSLOptions);

int GetTLSSSLOptions();
int SetTLSSSLOptions(int iTLSSSLOptions);

Default Value

16

Remarks

Various SSL (TLS) protocol options, set of

Data Type

Integer

TLSTLSMode Property (DCAuth Class)

Specifies the TLS mode to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSTLSMode();
int SetTLSTLSMode(int iTLSTLSMode);

Unicode (Windows)
INT GetTLSTLSMode();
INT SetTLSTLSMode(INT iTLSTLSMode);

SM_DEFAULT(0), 
SM_NO_TLS(1), 
SM_EXPLICIT_TLS(2), 
SM_IMPLICIT_TLS(3), 
SM_MIXED_TLS(4)

int secureblackbox_dcauth_gettlstlsmode(void* lpObj);
int secureblackbox_dcauth_settlstlsmode(void* lpObj, int iTLSTLSMode);

int GetTLSTLSMode();
int SetTLSTLSMode(int iTLSTLSMode);

Default Value

0

Remarks

Specifies the TLS mode to use.

Data Type

Integer

TLSUseExtendedMasterSecret Property (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSUseExtendedMasterSecret();
int SetTLSUseExtendedMasterSecret(int bTLSUseExtendedMasterSecret);

Unicode (Windows)
BOOL GetTLSUseExtendedMasterSecret();
INT SetTLSUseExtendedMasterSecret(BOOL bTLSUseExtendedMasterSecret);

int secureblackbox_dcauth_gettlsuseextendedmastersecret(void* lpObj);
int secureblackbox_dcauth_settlsuseextendedmastersecret(void* lpObj, int bTLSUseExtendedMasterSecret);

bool GetTLSUseExtendedMasterSecret();
int SetTLSUseExtendedMasterSecret(bool bTLSUseExtendedMasterSecret);

Default Value

FALSE

Remarks

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

Data Type

Boolean

TLSUseSessionResumption Property (DCAuth Class)

Enables or disables TLS session resumption capability.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSUseSessionResumption();
int SetTLSUseSessionResumption(int bTLSUseSessionResumption);

Unicode (Windows)
BOOL GetTLSUseSessionResumption();
INT SetTLSUseSessionResumption(BOOL bTLSUseSessionResumption);

int secureblackbox_dcauth_gettlsusesessionresumption(void* lpObj);
int secureblackbox_dcauth_settlsusesessionresumption(void* lpObj, int bTLSUseSessionResumption);

bool GetTLSUseSessionResumption();
int SetTLSUseSessionResumption(bool bTLSUseSessionResumption);

Default Value

FALSE

Remarks

Enables or disables TLS session resumption capability.

Data Type

Boolean

TLSVersions Property (DCAuth Class)

The SSL/TLS versions to enable by default.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTLSVersions();
int SetTLSVersions(int iTLSVersions);

Unicode (Windows)
INT GetTLSVersions();
INT SetTLSVersions(INT iTLSVersions);

int secureblackbox_dcauth_gettlsversions(void* lpObj);
int secureblackbox_dcauth_settlsversions(void* lpObj, int iTLSVersions);

int GetTLSVersions();
int SetTLSVersions(int iTLSVersions);

Default Value

16

Remarks

The SSL/TLS versions to enable by default.

Data Type

Integer

Config Method (DCAuth Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* secureblackbox_dcauth_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

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

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

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DoAction Method (DCAuth Class)

Performs an additional action.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* DoAction(const char* lpszActionID, const char* lpszActionParams);

Unicode (Windows)
LPWSTR DoAction(LPCWSTR lpszActionID, LPCWSTR lpszActionParams);

char* secureblackbox_dcauth_doaction(void* lpObj, const char* lpszActionID, const char* lpszActionParams);

QString DoAction(const QString& qsActionID, const QString& qsActionParams);

Remarks

DoAction is a generic method available in every class. 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 insencitive) 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;....

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ProcessRequest Method (DCAuth Class)

Processes the request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ProcessRequest();

Unicode (Windows)
INT ProcessRequest();

int secureblackbox_dcauth_processrequest(void* lpObj);

int 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.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CustomParametersReceived Event (DCAuth Class)

Passes custom request parameters to the application.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireCustomParametersReceived(DCAuthCustomParametersReceivedEventParams *e);

typedef struct {
  const char *Value;
  int reserved;
} DCAuthCustomParametersReceivedEventParams;


Unicode (Windows)
virtual INT FireCustomParametersReceived(DCAuthCustomParametersReceivedEventParams *e);

typedef struct {
  LPCWSTR Value;
  INT reserved;
} DCAuthCustomParametersReceivedEventParams;

#define EID_DCAUTH_CUSTOMPARAMETERSRECEIVED 1

virtual INT SECUREBLACKBOX_CALL FireCustomParametersReceived(LPSTR &lpszValue);

class DCAuthCustomParametersReceivedEventParams {
public:
  const QString &Value();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void CustomParametersReceived(DCAuthCustomParametersReceivedEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireCustomParametersReceived(DCAuthCustomParametersReceivedEventParams *e) {...}

Remarks

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

Error Event (DCAuth Class)

Reports information about errors during request processing or signing.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(DCAuthErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} DCAuthErrorEventParams;


Unicode (Windows)
virtual INT FireError(DCAuthErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} DCAuthErrorEventParams;

#define EID_DCAUTH_ERROR 2

virtual INT SECUREBLACKBOX_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class DCAuthErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(DCAuthErrorEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireError(DCAuthErrorEventParams *e) {...}

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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireExternalSign(DCAuthExternalSignEventParams *e);

typedef struct {
  const char *OperationId;
  const char *HashAlgorithm;
  const char *Pars;
  const char *MethodPars;
  const char *Data;
  char *SignedData;
  int reserved;
} DCAuthExternalSignEventParams;


Unicode (Windows)
virtual INT FireExternalSign(DCAuthExternalSignEventParams *e);

typedef struct {
  LPCWSTR OperationId;
  LPCWSTR HashAlgorithm;
  LPCWSTR Pars;
  LPCWSTR MethodPars;
  LPCWSTR Data;
  LPWSTR SignedData;
  INT reserved;
} DCAuthExternalSignEventParams;

#define EID_DCAUTH_EXTERNALSIGN 3

virtual INT SECUREBLACKBOX_CALL FireExternalSign(LPSTR &lpszOperationId, LPSTR &lpszHashAlgorithm, LPSTR &lpszPars, LPSTR &lpszMethodPars, LPSTR &lpszData, LPSTR &lpszSignedData);

class DCAuthExternalSignEventParams {
public:
  const QString &OperationId();

  const QString &HashAlgorithm();

  const QString &Pars();

  const QString &MethodPars();

  const QString &Data();

  const QString &SignedData();
  void SetSignedData(const QString &qsSignedData);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ExternalSign(DCAuthExternalSignEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireExternalSign(DCAuthExternalSignEventParams *e) {...}

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 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 contain algorithm-dependent parameters.

The component uses base16 (hex) encoding for 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 a .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 Class)

Requests the key secret from the application.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireKeySecretNeeded(DCAuthKeySecretNeededEventParams *e);

typedef struct {
  const char *KeyId;
  char *KeySecret;
  int reserved;
} DCAuthKeySecretNeededEventParams;


Unicode (Windows)
virtual INT FireKeySecretNeeded(DCAuthKeySecretNeededEventParams *e);

typedef struct {
  LPCWSTR KeyId;
  LPWSTR KeySecret;
  INT reserved;
} DCAuthKeySecretNeededEventParams;

#define EID_DCAUTH_KEYSECRETNEEDED 4

virtual INT SECUREBLACKBOX_CALL FireKeySecretNeeded(LPSTR &lpszKeyId, LPSTR &lpszKeySecret);

class DCAuthKeySecretNeededEventParams {
public:
  const QString &KeyId();

  const QString &KeySecret();
  void SetKeySecret(const QString &qsKeySecret);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void KeySecretNeeded(DCAuthKeySecretNeededEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireKeySecretNeeded(DCAuthKeySecretNeededEventParams *e) {...}

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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotification(DCAuthNotificationEventParams *e);

typedef struct {
  const char *EventID;
  const char *EventParam;
  int reserved;
} DCAuthNotificationEventParams;


Unicode (Windows)
virtual INT FireNotification(DCAuthNotificationEventParams *e);

typedef struct {
  LPCWSTR EventID;
  LPCWSTR EventParam;
  INT reserved;
} DCAuthNotificationEventParams;

#define EID_DCAUTH_NOTIFICATION 5

virtual INT SECUREBLACKBOX_CALL FireNotification(LPSTR &lpszEventID, LPSTR &lpszEventParam);

class DCAuthNotificationEventParams {
public:
  const QString &EventID();

  const QString &EventParam();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Notification(DCAuthNotificationEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireNotification(DCAuthNotificationEventParams *e) {...}

Remarks

The class 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 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 Class)

Passes a standard request parameter to the user code.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireParameterReceived(DCAuthParameterReceivedEventParams *e);

typedef struct {
  const char *Name;
  const char *Value;
  int reserved;
} DCAuthParameterReceivedEventParams;


Unicode (Windows)
virtual INT FireParameterReceived(DCAuthParameterReceivedEventParams *e);

typedef struct {
  LPCWSTR Name;
  LPCWSTR Value;
  INT reserved;
} DCAuthParameterReceivedEventParams;

#define EID_DCAUTH_PARAMETERRECEIVED 6

virtual INT SECUREBLACKBOX_CALL FireParameterReceived(LPSTR &lpszName, LPSTR &lpszValue);

class DCAuthParameterReceivedEventParams {
public:
  const QString &Name();

  const QString &Value();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void ParameterReceived(DCAuthParameterReceivedEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireParameterReceived(DCAuthParameterReceivedEventParams *e) {...}

Remarks

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

SignRequest Event (DCAuth Class)

This event signifies the processing of an atomic signing request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSignRequest(DCAuthSignRequestEventParams *e);

typedef struct {
  int Method;
  const char *HashAlgorithm;
  const char *Hash;
  int lenHash;
  const char *KeyID;
  const char *Pars;
  const char *MethodPars;
  int Allow;
  int reserved;
} DCAuthSignRequestEventParams;


Unicode (Windows)
virtual INT FireSignRequest(DCAuthSignRequestEventParams *e);

typedef struct {
  INT Method;
  LPCWSTR HashAlgorithm;
  LPCSTR Hash;
  INT lenHash;
  LPCWSTR KeyID;
  LPCWSTR Pars;
  LPCWSTR MethodPars;
  BOOL Allow;
  INT reserved;
} DCAuthSignRequestEventParams;

#define EID_DCAUTH_SIGNREQUEST 7

virtual INT SECUREBLACKBOX_CALL FireSignRequest(INT &iMethod, LPSTR &lpszHashAlgorithm, LPSTR &lpHash, INT &lenHash, LPSTR &lpszKeyID, LPSTR &lpszPars, LPSTR &lpszMethodPars, BOOL &bAllow);

class DCAuthSignRequestEventParams {
public:
  int Method();

  const QString &HashAlgorithm();

  const QByteArray &Hash();

  const QString &KeyID();

  const QString &Pars();

  const QString &MethodPars();

  bool Allow();
  void SetAllow(bool bAllow);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SignRequest(DCAuthSignRequestEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireSignRequest(DCAuthSignRequestEventParams *e) {...}

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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireSignRequestCompleted(DCAuthSignRequestCompletedEventParams *e);

typedef struct {
  int Method;
  const char *HashAlgorithm;
  const char *Hash;
  int lenHash;
  const char *KeyID;
  const char *Pars;
  const char *MethodPars;
  const char *Signature;
  int lenSignature;
  int reserved;
} DCAuthSignRequestCompletedEventParams;


Unicode (Windows)
virtual INT FireSignRequestCompleted(DCAuthSignRequestCompletedEventParams *e);

typedef struct {
  INT Method;
  LPCWSTR HashAlgorithm;
  LPCSTR Hash;
  INT lenHash;
  LPCWSTR KeyID;
  LPCWSTR Pars;
  LPCWSTR MethodPars;
  LPCSTR Signature;
  INT lenSignature;
  INT reserved;
} DCAuthSignRequestCompletedEventParams;

#define EID_DCAUTH_SIGNREQUESTCOMPLETED 8

virtual INT SECUREBLACKBOX_CALL FireSignRequestCompleted(INT &iMethod, LPSTR &lpszHashAlgorithm, LPSTR &lpHash, INT &lenHash, LPSTR &lpszKeyID, LPSTR &lpszPars, LPSTR &lpszMethodPars, LPSTR &lpSignature, INT &lenSignature);

class DCAuthSignRequestCompletedEventParams {
public:
  int Method();

  const QString &HashAlgorithm();

  const QByteArray &Hash();

  const QString &KeyID();

  const QString &Pars();

  const QString &MethodPars();

  const QByteArray &Signature();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void SignRequestCompleted(DCAuthSignRequestCompletedEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireSignRequestCompleted(DCAuthSignRequestCompletedEventParams *e) {...}

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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTimestampRequest(DCAuthTimestampRequestEventParams *e);

typedef struct {
  const char *TSA;
  const char *TimestampRequest;
  char *TimestampResponse;
  int SuppressDefault;
  int reserved;
} DCAuthTimestampRequestEventParams;


Unicode (Windows)
virtual INT FireTimestampRequest(DCAuthTimestampRequestEventParams *e);

typedef struct {
  LPCWSTR TSA;
  LPCWSTR TimestampRequest;
  LPWSTR TimestampResponse;
  BOOL SuppressDefault;
  INT reserved;
} DCAuthTimestampRequestEventParams;

#define EID_DCAUTH_TIMESTAMPREQUEST 9

virtual INT SECUREBLACKBOX_CALL FireTimestampRequest(LPSTR &lpszTSA, LPSTR &lpszTimestampRequest, LPSTR &lpszTimestampResponse, BOOL &bSuppressDefault);

class DCAuthTimestampRequestEventParams {
public:
  const QString &TSA();

  const QString &TimestampRequest();

  const QString &TimestampResponse();
  void SetTimestampResponse(const QString &qsTimestampResponse);

  bool SuppressDefault();
  void SetSuppressDefault(bool bSuppressDefault);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TimestampRequest(DCAuthTimestampRequestEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireTimestampRequest(DCAuthTimestampRequestEventParams *e) {...}

Remarks

Subscribe to this event to be 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 TimestampServer property. Set 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 Class)

Fires when a remote TLS party requests a client certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSCertNeeded(DCAuthTLSCertNeededEventParams *e);

typedef struct {
  const char *Host;
  const char *CANames;
  int reserved;
} DCAuthTLSCertNeededEventParams;


Unicode (Windows)
virtual INT FireTLSCertNeeded(DCAuthTLSCertNeededEventParams *e);

typedef struct {
  LPCWSTR Host;
  LPCWSTR CANames;
  INT reserved;
} DCAuthTLSCertNeededEventParams;

#define EID_DCAUTH_TLSCERTNEEDED 10

virtual INT SECUREBLACKBOX_CALL FireTLSCertNeeded(LPSTR &lpszHost, LPSTR &lpszCANames);

class DCAuthTLSCertNeededEventParams {
public:
  const QString &Host();

  const QString &CANames();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSCertNeeded(DCAuthTLSCertNeededEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireTLSCertNeeded(DCAuthTLSCertNeededEventParams *e) {...}

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 (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 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSCertValidate(DCAuthTLSCertValidateEventParams *e);

typedef struct {
  const char *ServerHost;
  const char *ServerIP;
  int Accept;
  int reserved;
} DCAuthTLSCertValidateEventParams;


Unicode (Windows)
virtual INT FireTLSCertValidate(DCAuthTLSCertValidateEventParams *e);

typedef struct {
  LPCWSTR ServerHost;
  LPCWSTR ServerIP;
  BOOL Accept;
  INT reserved;
} DCAuthTLSCertValidateEventParams;

#define EID_DCAUTH_TLSCERTVALIDATE 11

virtual INT SECUREBLACKBOX_CALL FireTLSCertValidate(LPSTR &lpszServerHost, LPSTR &lpszServerIP, BOOL &bAccept);

class DCAuthTLSCertValidateEventParams {
public:
  const QString &ServerHost();

  const QString &ServerIP();

  bool Accept();
  void SetAccept(bool bAccept);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSCertValidate(DCAuthTLSCertValidateEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireTLSCertValidate(DCAuthTLSCertValidateEventParams *e) {...}

Remarks

This event is fired during a TLS handshake. Use TLSServerChain property to access the certificate chain. In general case, 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 Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSEstablished(DCAuthTLSEstablishedEventParams *e);

typedef struct {
  const char *Host;
  const char *Version;
  const char *Ciphersuite;
  const char *ConnectionId;
  int lenConnectionId;
  int Abort;
  int reserved;
} DCAuthTLSEstablishedEventParams;


Unicode (Windows)
virtual INT FireTLSEstablished(DCAuthTLSEstablishedEventParams *e);

typedef struct {
  LPCWSTR Host;
  LPCWSTR Version;
  LPCWSTR Ciphersuite;
  LPCSTR ConnectionId;
  INT lenConnectionId;
  BOOL Abort;
  INT reserved;
} DCAuthTLSEstablishedEventParams;

#define EID_DCAUTH_TLSESTABLISHED 12

virtual INT SECUREBLACKBOX_CALL FireTLSEstablished(LPSTR &lpszHost, LPSTR &lpszVersion, LPSTR &lpszCiphersuite, LPSTR &lpConnectionId, INT &lenConnectionId, BOOL &bAbort);

class DCAuthTLSEstablishedEventParams {
public:
  const QString &Host();

  const QString &Version();

  const QString &Ciphersuite();

  const QByteArray &ConnectionId();

  bool Abort();
  void SetAbort(bool bAbort);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSEstablished(DCAuthTLSEstablishedEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireTLSEstablished(DCAuthTLSEstablishedEventParams *e) {...}

Remarks

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

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

TLSHandshake Event (DCAuth Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSHandshake(DCAuthTLSHandshakeEventParams *e);

typedef struct {
  const char *Host;
  int Abort;
  int reserved;
} DCAuthTLSHandshakeEventParams;


Unicode (Windows)
virtual INT FireTLSHandshake(DCAuthTLSHandshakeEventParams *e);

typedef struct {
  LPCWSTR Host;
  BOOL Abort;
  INT reserved;
} DCAuthTLSHandshakeEventParams;

#define EID_DCAUTH_TLSHANDSHAKE 13

virtual INT SECUREBLACKBOX_CALL FireTLSHandshake(LPSTR &lpszHost, BOOL &bAbort);

class DCAuthTLSHandshakeEventParams {
public:
  const QString &Host();

  bool Abort();
  void SetAbort(bool bAbort);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSHandshake(DCAuthTLSHandshakeEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireTLSHandshake(DCAuthTLSHandshakeEventParams *e) {...}

Remarks

The class 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 with TLSEstablished event. If the server chooses to request a client certificate, TLSCertNeeded event will also be fired.

TLSShutdown Event (DCAuth Class)

Reports the graceful closure of a TLS connection.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireTLSShutdown(DCAuthTLSShutdownEventParams *e);

typedef struct {
  const char *Host;
  int reserved;
} DCAuthTLSShutdownEventParams;


Unicode (Windows)
virtual INT FireTLSShutdown(DCAuthTLSShutdownEventParams *e);

typedef struct {
  LPCWSTR Host;
  INT reserved;
} DCAuthTLSShutdownEventParams;

#define EID_DCAUTH_TLSSHUTDOWN 14

virtual INT SECUREBLACKBOX_CALL FireTLSShutdown(LPSTR &lpszHost);

class DCAuthTLSShutdownEventParams {
public:
  const QString &Host();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void TLSShutdown(DCAuthTLSShutdownEventParams *e);

// Or, subclass DCAuth and override this emitter function.
virtual int FireTLSShutdown(DCAuthTLSShutdownEventParams *e) {...}

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 Class)

DCAuth Config Settings

Base Config Settings

Trappable Errors (DCAuth Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.