MessageSigner Class

Properties   Methods   Events   Config Settings   Errors  

The MessageSigner class digitally signs data and stores it in the PKCS#7 format.

Syntax

MessageSigner

Remarks

PKCS#7 (Public Key Cryptography Standard #7) is a common format used to store encrypted and signed data. It is used by a variety of protocols, including S/MIME and CMS.

MessageSigner can sign binary data into PKCS#7 SignedData and AuthenticatedData subformats. RSA, ECDSA, and EdDSA algorithms are supported.

Setting up and using MessageSigner is easy:

• Set up your source and destination via InputFile (InputBytes) and OutputFile (OutputBytes) properties.
• Set SignatureType as per the desired signature type (PKCS#7 SignedData or AuthenticatedData, or PKCS#1) and the detached option.
• Set signature properties, such as ClaimedSigningTime and attributes (AddAttribute).
• For the SignedData-type signature (most commonly used), assign the signing certificate with its private key to the SigningCertificate property.
• For the AuthenticatedData-type signature, assign the recipient's certificate to RecipientCertificate property.
• Optionally provide the timestamping server URL to TimestampServer.
• Call Sign to execute the operation.

Note that MessageSigner always produces binary PKCS#7-compliant signed messages. For S/MIME email signing, see MailWriter. For PGP signing, see PGPWriter. For XML-SIG encryption, see XMLSigner.

MessageSigner is a simplified form of CAdESSigner. Both classes work with PKCS#7 signed messages. CAdESSigner, however, provides support for advanced (CAdES) signatures, including long-term validity, archival, and full chain validation capabilities. These advanced capabilities are absent from MessageSigner, which is only capable of creating basic PKCS#7 signatures. MessageSigner signer = new MessageSigner(); signer.setHashAlgorithm("SHA256"); // Default hashing algorithm SHA256 // Select the file which contains the message that will be signed signer.setInputFile("message.txt"); // Select the file where the signed message will be written signer.setOutputFile("signedMessage.bin"); // Specify the certificate that shall be used for signing the data signer.setSigningCertificate(new Certificate("cert.pfx","password")); // Provide the address of the Time Stamping Authority (TSA) server to be used for timestamping the signature signer.setTimestampServer("http://..."); signer.sign(); // Sign

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 (MessageSigner 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_messagesigner_getclaimedsigningtime(void* lpObj);
int secureblackbox_messagesigner_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

ExternalCrypto Property (MessageSigner Class)

Provides access to external signing and DC parameters.

Syntax

• C++
• C
• Qt

SecureBlackboxExternalCrypto* GetExternalCrypto();

char* secureblackbox_messagesigner_getexternalcryptoasyncdocumentid(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptoasyncdocumentid(void* lpObj, const char* lpszExternalCryptoAsyncDocumentID);

char* secureblackbox_messagesigner_getexternalcryptocustomparams(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptocustomparams(void* lpObj, const char* lpszExternalCryptoCustomParams);

char* secureblackbox_messagesigner_getexternalcryptodata(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptodata(void* lpObj, const char* lpszExternalCryptoData);

int secureblackbox_messagesigner_getexternalcryptoexternalhashcalculation(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptoexternalhashcalculation(void* lpObj, int bExternalCryptoExternalHashCalculation);

char* secureblackbox_messagesigner_getexternalcryptohashalgorithm(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptohashalgorithm(void* lpObj, const char* lpszExternalCryptoHashAlgorithm);

char* secureblackbox_messagesigner_getexternalcryptokeyid(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptokeyid(void* lpObj, const char* lpszExternalCryptoKeyID);

char* secureblackbox_messagesigner_getexternalcryptokeysecret(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptokeysecret(void* lpObj, const char* lpszExternalCryptoKeySecret);

int secureblackbox_messagesigner_getexternalcryptomethod(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptomethod(void* lpObj, int iExternalCryptoMethod);

int secureblackbox_messagesigner_getexternalcryptomode(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptomode(void* lpObj, int iExternalCryptoMode);

char* secureblackbox_messagesigner_getexternalcryptopublickeyalgorithm(void* lpObj);
int secureblackbox_messagesigner_setexternalcryptopublickeyalgorithm(void* lpObj, const char* lpszExternalCryptoPublicKeyAlgorithm);

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

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

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

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

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

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

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

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

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

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

Remarks

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

This property is read-only.

Data Type

SecureBlackboxExternalCrypto

FIPSMode Property (MessageSigner 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_messagesigner_getfipsmode(void* lpObj);
int secureblackbox_messagesigner_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

HashAlgorithm Property (MessageSigner Class)

Specifies the hash algorithm to be used.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetHashAlgorithm();
int SetHashAlgorithm(const char* lpszHashAlgorithm);

Unicode (Windows)
LPWSTR GetHashAlgorithm();
INT SetHashAlgorithm(LPCWSTR lpszHashAlgorithm);

char* secureblackbox_messagesigner_gethashalgorithm(void* lpObj);
int secureblackbox_messagesigner_sethashalgorithm(void* lpObj, const char* lpszHashAlgorithm);

QString GetHashAlgorithm();
int SetHashAlgorithm(QString qsHashAlgorithm);

Default Value

"SHA256"

Remarks

This property specifies the hash algorithm to used for calculating the signature.

Data Type

String

InputBytes Property (MessageSigner Class)

Use this property to pass the input to class in byte array form.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetInputBytes(char* &lpInputBytes, int &lenInputBytes);
int SetInputBytes(const char* lpInputBytes, int lenInputBytes);

Unicode (Windows)
INT GetInputBytes(LPSTR &lpInputBytes, INT &lenInputBytes);
INT SetInputBytes(LPCSTR lpInputBytes, INT lenInputBytes);

int secureblackbox_messagesigner_getinputbytes(void* lpObj, char** lpInputBytes, int* lenInputBytes);
int secureblackbox_messagesigner_setinputbytes(void* lpObj, const char* lpInputBytes, int lenInputBytes);

QByteArray GetInputBytes();
int SetInputBytes(QByteArray qbaInputBytes);

Remarks

Assign a byte array containing the data to be processed to this property.

This property is not available at design time.

Data Type

Byte Array

InputFile Property (MessageSigner Class)

A path to the source file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetInputFile();
int SetInputFile(const char* lpszInputFile);

Unicode (Windows)
LPWSTR GetInputFile();
INT SetInputFile(LPCWSTR lpszInputFile);

char* secureblackbox_messagesigner_getinputfile(void* lpObj);
int secureblackbox_messagesigner_setinputfile(void* lpObj, const char* lpszInputFile);

QString GetInputFile();
int SetInputFile(QString qsInputFile);

Default Value

""

Remarks

Use this property to provide a path to the file containing the data to be signed.

Data Type

String

InputIsHash Property (MessageSigner Class)

Specifies whether the input source contains the hash of the data or the actual data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetInputIsHash();
int SetInputIsHash(int bInputIsHash);

Unicode (Windows)
BOOL GetInputIsHash();
INT SetInputIsHash(BOOL bInputIsHash);

int secureblackbox_messagesigner_getinputishash(void* lpObj);
int secureblackbox_messagesigner_setinputishash(void* lpObj, int bInputIsHash);

bool GetInputIsHash();
int SetInputIsHash(bool bInputIsHash);

Default Value

FALSE

Remarks

Use this property to tell the component whether the input source contains the actual data or its hash.

This property is not available at design time.

Data Type

Boolean

MACAlgorithm Property (MessageSigner Class)

Specifies the keyed MAC algorithm to use.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMACAlgorithm();
int SetMACAlgorithm(const char* lpszMACAlgorithm);

Unicode (Windows)
LPWSTR GetMACAlgorithm();
INT SetMACAlgorithm(LPCWSTR lpszMACAlgorithm);

char* secureblackbox_messagesigner_getmacalgorithm(void* lpObj);
int secureblackbox_messagesigner_setmacalgorithm(void* lpObj, const char* lpszMACAlgorithm);

QString GetMACAlgorithm();
int SetMACAlgorithm(QString qsMACAlgorithm);

Default Value

"SHA256"

Remarks

This property specifies the MAC algorithm to use for calculating the MAC signature.

Data Type

String

OutputBytes Property (MessageSigner Class)

Use this property to read the output the class object has produced.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOutputBytes(char* &lpOutputBytes, int &lenOutputBytes);

Unicode (Windows)
INT GetOutputBytes(LPSTR &lpOutputBytes, INT &lenOutputBytes);

int secureblackbox_messagesigner_getoutputbytes(void* lpObj, char** lpOutputBytes, int* lenOutputBytes);

QByteArray GetOutputBytes();

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the OutputFile and OutputStream properties had not been assigned.

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

Data Type

Byte Array

OutputFile Property (MessageSigner Class)

A path to the output file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOutputFile();
int SetOutputFile(const char* lpszOutputFile);

Unicode (Windows)
LPWSTR GetOutputFile();
INT SetOutputFile(LPCWSTR lpszOutputFile);

char* secureblackbox_messagesigner_getoutputfile(void* lpObj);
int secureblackbox_messagesigner_setoutputfile(void* lpObj, const char* lpszOutputFile);

QString GetOutputFile();
int SetOutputFile(QString qsOutputFile);

Default Value

""

Remarks

Use this property to specify the file to save the signed message to.

Data Type

String

Proxy Property (MessageSigner Class)

The proxy server settings.

Syntax

• C++
• C
• Qt

SecureBlackboxProxySettings* GetProxy();

char* secureblackbox_messagesigner_getproxyaddress(void* lpObj);
int secureblackbox_messagesigner_setproxyaddress(void* lpObj, const char* lpszProxyAddress);

int secureblackbox_messagesigner_getproxyauthentication(void* lpObj);
int secureblackbox_messagesigner_setproxyauthentication(void* lpObj, int iProxyAuthentication);

char* secureblackbox_messagesigner_getproxypassword(void* lpObj);
int secureblackbox_messagesigner_setproxypassword(void* lpObj, const char* lpszProxyPassword);

int secureblackbox_messagesigner_getproxyport(void* lpObj);
int secureblackbox_messagesigner_setproxyport(void* lpObj, int iProxyPort);

int secureblackbox_messagesigner_getproxyproxytype(void* lpObj);
int secureblackbox_messagesigner_setproxyproxytype(void* lpObj, int iProxyProxyType);

char* secureblackbox_messagesigner_getproxyrequestheaders(void* lpObj);
int secureblackbox_messagesigner_setproxyrequestheaders(void* lpObj, const char* lpszProxyRequestHeaders);

char* secureblackbox_messagesigner_getproxyresponsebody(void* lpObj);
int secureblackbox_messagesigner_setproxyresponsebody(void* lpObj, const char* lpszProxyResponseBody);

char* secureblackbox_messagesigner_getproxyresponseheaders(void* lpObj);
int secureblackbox_messagesigner_setproxyresponseheaders(void* lpObj, const char* lpszProxyResponseHeaders);

int secureblackbox_messagesigner_getproxyuseipv6(void* lpObj);
int secureblackbox_messagesigner_setproxyuseipv6(void* lpObj, int bProxyUseIPv6);

char* secureblackbox_messagesigner_getproxyusername(void* lpObj);
int secureblackbox_messagesigner_setproxyusername(void* lpObj, const char* lpszProxyUsername);

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

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

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

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

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

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

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

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

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

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

Remarks

Use this property to tune up the proxy server settings.

This property is read-only.

Data Type

SecureBlackboxProxySettings

RecipientCertificate Property (MessageSigner Class)

The recipient certificate for HMAC-based signing.

Syntax

• C++
• C
• Qt

SecureBlackboxCertificate* GetRecipientCertificate();
int SetRecipientCertificate(SecureBlackboxCertificate* val);

int secureblackbox_messagesigner_getrecipientcertbytes(void* lpObj, char** lpRecipientCertBytes, int* lenRecipientCertBytes);

int64 secureblackbox_messagesigner_getrecipientcerthandle(void* lpObj);
int secureblackbox_messagesigner_setrecipientcerthandle(void* lpObj, int64 lRecipientCertHandle);

QByteArray GetRecipientCertBytes();

qint64 GetRecipientCertHandle();
int SetRecipientCertHandle(qint64 lRecipientCertHandle);

Remarks

Use this property to specify the certificate to be used for encryption of the HMAC key. This is a "recipient's" certificate, and as such it does not need to have an associated private key.

The certificate is used with SignatureType set to one of the MAC options to generate an encrypted session key block. Upon receiving the signed message, the recipient decrypts the HMAC key and uses that to verify the integrity of the message.

This property is not available at design time.

Data Type

SecureBlackboxCertificate

SignatureType Property (MessageSigner Class)

Specifies the kind of signature to create.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSignatureType();
int SetSignatureType(int iSignatureType);

Unicode (Windows)
INT GetSignatureType();
INT SetSignatureType(INT iSignatureType);

ST_UNKNOWN(0), 
ST_PKCS1DETACHED(1), 
ST_PKCS7DETACHED(2), 
ST_PKCS7ENVELOPING(3), 
ST_PKCS7MACDETACHED(4), 
ST_PKCS7MACENVELOPING(5)

int secureblackbox_messagesigner_getsignaturetype(void* lpObj);
int secureblackbox_messagesigner_setsignaturetype(void* lpObj, int iSignatureType);

int GetSignatureType();
int SetSignatureType(int iSignatureType);

Default Value

2

Remarks

Possible values:

Data Type

Integer

SignedAttributes Property (MessageSigner Class)

Custom signature attributes to be covered by the electronic signature.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxSignatureAttribute>* GetSignedAttributes();

int secureblackbox_messagesigner_getsignedattributecount(void* lpObj);
int secureblackbox_messagesigner_setsignedattributecount(void* lpObj, int iSignedAttributeCount);

char* secureblackbox_messagesigner_getsignedattributeoid(void* lpObj, int signedattributeindex);
int secureblackbox_messagesigner_setsignedattributeoid(void* lpObj, int signedattributeindex, const char* lpszSignedAttributeOID);

int secureblackbox_messagesigner_getsignedattributevalue(void* lpObj, int signedattributeindex, char** lpSignedAttributeValue, int* lenSignedAttributeValue);
int secureblackbox_messagesigner_setsignedattributevalue(void* lpObj, int signedattributeindex, const char* lpSignedAttributeValue, int lenSignedAttributeValue);

int GetSignedAttributeCount();
int SetSignedAttributeCount(int iSignedAttributeCount);

QString GetSignedAttributeOID(int iSignedAttributeIndex);
int SetSignedAttributeOID(int iSignedAttributeIndex, QString qsSignedAttributeOID);

QByteArray GetSignedAttributeValue(int iSignedAttributeIndex);
int SetSignedAttributeValue(int iSignedAttributeIndex, QByteArray qbaSignedAttributeValue);

Remarks

Signature attributes are used to store auxiliary information in the signature. Values included as signed attributes are covered by the signature.

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

Data Type

SecureBlackboxSignatureAttribute

SigningCertificate Property (MessageSigner Class)

The certificate to be used for signing.

Syntax

• C++
• C
• Qt

SecureBlackboxCertificate* GetSigningCertificate();
int SetSigningCertificate(SecureBlackboxCertificate* val);

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

int64 secureblackbox_messagesigner_getsigningcerthandle(void* lpObj);
int secureblackbox_messagesigner_setsigningcerthandle(void* lpObj, int64 lSigningCertHandle);

QByteArray GetSigningCertBytes();

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

Remarks

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

This property is not available at design time.

Data Type

SecureBlackboxCertificate

SigningChain Property (MessageSigner Class)

The signing certificate chain.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetSigningChain();
int SetSigningChain(SecureBlackboxList<SecureBlackboxCertificate>* val);

int secureblackbox_messagesigner_getsigningchaincount(void* lpObj);
int secureblackbox_messagesigner_setsigningchaincount(void* lpObj, int iSigningChainCount);

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

int64 secureblackbox_messagesigner_getsigningchainhandle(void* lpObj, int signingchainindex);
int secureblackbox_messagesigner_setsigningchainhandle(void* lpObj, int signingchainindex, int64 lSigningChainHandle);

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

QByteArray GetSigningChainBytes(int iSigningChainIndex);

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

Remarks

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

This property is not available at design time.

Data Type

SecureBlackboxCertificate

SocketSettings Property (MessageSigner Class)

Manages network connection settings.

Syntax

• C++
• C
• Qt

SecureBlackboxSocketSettings* GetSocketSettings();

int secureblackbox_messagesigner_getsocketdnsmode(void* lpObj);
int secureblackbox_messagesigner_setsocketdnsmode(void* lpObj, int iSocketDNSMode);

int secureblackbox_messagesigner_getsocketdnsport(void* lpObj);
int secureblackbox_messagesigner_setsocketdnsport(void* lpObj, int iSocketDNSPort);

int secureblackbox_messagesigner_getsocketdnsquerytimeout(void* lpObj);
int secureblackbox_messagesigner_setsocketdnsquerytimeout(void* lpObj, int iSocketDNSQueryTimeout);

char* secureblackbox_messagesigner_getsocketdnsservers(void* lpObj);
int secureblackbox_messagesigner_setsocketdnsservers(void* lpObj, const char* lpszSocketDNSServers);

int secureblackbox_messagesigner_getsocketdnstotaltimeout(void* lpObj);
int secureblackbox_messagesigner_setsocketdnstotaltimeout(void* lpObj, int iSocketDNSTotalTimeout);

int secureblackbox_messagesigner_getsocketincomingspeedlimit(void* lpObj);
int secureblackbox_messagesigner_setsocketincomingspeedlimit(void* lpObj, int iSocketIncomingSpeedLimit);

char* secureblackbox_messagesigner_getsocketlocaladdress(void* lpObj);
int secureblackbox_messagesigner_setsocketlocaladdress(void* lpObj, const char* lpszSocketLocalAddress);

int secureblackbox_messagesigner_getsocketlocalport(void* lpObj);
int secureblackbox_messagesigner_setsocketlocalport(void* lpObj, int iSocketLocalPort);

int secureblackbox_messagesigner_getsocketoutgoingspeedlimit(void* lpObj);
int secureblackbox_messagesigner_setsocketoutgoingspeedlimit(void* lpObj, int iSocketOutgoingSpeedLimit);

int secureblackbox_messagesigner_getsockettimeout(void* lpObj);
int secureblackbox_messagesigner_setsockettimeout(void* lpObj, int iSocketTimeout);

int secureblackbox_messagesigner_getsocketuseipv6(void* lpObj);
int secureblackbox_messagesigner_setsocketuseipv6(void* lpObj, int bSocketUseIPv6);

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

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

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

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

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

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

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

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

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

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

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

Remarks

Use this property to tune up network connection parameters.

This property is read-only.

Data Type

SecureBlackboxSocketSettings

TimestampServer Property (MessageSigner 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_messagesigner_gettimestampserver(void* lpObj);
int secureblackbox_messagesigner_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&ignorenonce=true

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.

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

All the parameters are optional.

Data Type

String

TLSClientChain Property (MessageSigner Class)

The TLS client certificate chain.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetTLSClientChain();
int SetTLSClientChain(SecureBlackboxList<SecureBlackboxCertificate>* val);

int secureblackbox_messagesigner_gettlsclientcertcount(void* lpObj);
int secureblackbox_messagesigner_settlsclientcertcount(void* lpObj, int iTLSClientCertCount);

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

int64 secureblackbox_messagesigner_gettlsclientcerthandle(void* lpObj, int tlsclientcertindex);
int secureblackbox_messagesigner_settlsclientcerthandle(void* lpObj, int tlsclientcertindex, int64 lTLSClientCertHandle);

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

QByteArray GetTLSClientCertBytes(int iTLSClientCertIndex);

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

Remarks

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

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

This property is not available at design time.

Data Type

SecureBlackboxCertificate

TLSServerChain Property (MessageSigner Class)

The TLS server's certificate chain.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetTLSServerChain();

int secureblackbox_messagesigner_gettlsservercertcount(void* lpObj);

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

char* secureblackbox_messagesigner_gettlsservercertfingerprint(void* lpObj, int tlsservercertindex);

int64 secureblackbox_messagesigner_gettlsservercerthandle(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertissuer(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertissuerrdn(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertkeyalgorithm(void* lpObj, int tlsservercertindex);

int secureblackbox_messagesigner_gettlsservercertkeybits(void* lpObj, int tlsservercertindex);

int secureblackbox_messagesigner_gettlsservercertkeyusage(void* lpObj, int tlsservercertindex);

int secureblackbox_messagesigner_gettlsservercertselfsigned(void* lpObj, int tlsservercertindex);

int secureblackbox_messagesigner_gettlsservercertserialnumber(void* lpObj, int tlsservercertindex, char** lpTLSServerCertSerialNumber, int* lenTLSServerCertSerialNumber);

char* secureblackbox_messagesigner_gettlsservercertsigalgorithm(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertsubject(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertsubjectrdn(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertvalidfrom(void* lpObj, int tlsservercertindex);

char* secureblackbox_messagesigner_gettlsservercertvalidto(void* lpObj, int tlsservercertindex);

int GetTLSServerCertCount();

QByteArray GetTLSServerCertBytes(int iTLSServerCertIndex);

QString GetTLSServerCertFingerprint(int iTLSServerCertIndex);

qint64 GetTLSServerCertHandle(int iTLSServerCertIndex);

QString GetTLSServerCertIssuer(int iTLSServerCertIndex);

QString GetTLSServerCertIssuerRDN(int iTLSServerCertIndex);

QString GetTLSServerCertKeyAlgorithm(int iTLSServerCertIndex);

int GetTLSServerCertKeyBits(int iTLSServerCertIndex);

int GetTLSServerCertKeyUsage(int iTLSServerCertIndex);

bool GetTLSServerCertSelfSigned(int iTLSServerCertIndex);

QByteArray GetTLSServerCertSerialNumber(int iTLSServerCertIndex);

QString GetTLSServerCertSigAlgorithm(int iTLSServerCertIndex);

QString GetTLSServerCertSubject(int iTLSServerCertIndex);

QString GetTLSServerCertSubjectRDN(int iTLSServerCertIndex);

QString GetTLSServerCertValidFrom(int iTLSServerCertIndex);

QString GetTLSServerCertValidTo(int iTLSServerCertIndex);

Remarks

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

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

Data Type

SecureBlackboxCertificate

TLSSettings Property (MessageSigner Class)

Manages TLS layer settings.

Syntax

• C++
• C
• Qt

SecureBlackboxTLSSettings* GetTLSSettings();

int secureblackbox_messagesigner_gettlsautovalidatecertificates(void* lpObj);
int secureblackbox_messagesigner_settlsautovalidatecertificates(void* lpObj, int bTLSAutoValidateCertificates);

int secureblackbox_messagesigner_gettlsbaseconfiguration(void* lpObj);
int secureblackbox_messagesigner_settlsbaseconfiguration(void* lpObj, int iTLSBaseConfiguration);

char* secureblackbox_messagesigner_gettlsciphersuites(void* lpObj);
int secureblackbox_messagesigner_settlsciphersuites(void* lpObj, const char* lpszTLSCiphersuites);

int secureblackbox_messagesigner_gettlsclientauth(void* lpObj);
int secureblackbox_messagesigner_settlsclientauth(void* lpObj, int iTLSClientAuth);

char* secureblackbox_messagesigner_gettlseccurves(void* lpObj);
int secureblackbox_messagesigner_settlseccurves(void* lpObj, const char* lpszTLSECCurves);

char* secureblackbox_messagesigner_gettlsextensions(void* lpObj);
int secureblackbox_messagesigner_settlsextensions(void* lpObj, const char* lpszTLSExtensions);

int secureblackbox_messagesigner_gettlsforceresumeifdestinationchanges(void* lpObj);
int secureblackbox_messagesigner_settlsforceresumeifdestinationchanges(void* lpObj, int bTLSForceResumeIfDestinationChanges);

char* secureblackbox_messagesigner_gettlspresharedidentity(void* lpObj);
int secureblackbox_messagesigner_settlspresharedidentity(void* lpObj, const char* lpszTLSPreSharedIdentity);

char* secureblackbox_messagesigner_gettlspresharedkey(void* lpObj);
int secureblackbox_messagesigner_settlspresharedkey(void* lpObj, const char* lpszTLSPreSharedKey);

char* secureblackbox_messagesigner_gettlspresharedkeyciphersuite(void* lpObj);
int secureblackbox_messagesigner_settlspresharedkeyciphersuite(void* lpObj, const char* lpszTLSPreSharedKeyCiphersuite);

int secureblackbox_messagesigner_gettlsrenegotiationattackpreventionmode(void* lpObj);
int secureblackbox_messagesigner_settlsrenegotiationattackpreventionmode(void* lpObj, int iTLSRenegotiationAttackPreventionMode);

int secureblackbox_messagesigner_gettlsrevocationcheck(void* lpObj);
int secureblackbox_messagesigner_settlsrevocationcheck(void* lpObj, int iTLSRevocationCheck);

int secureblackbox_messagesigner_gettlsssloptions(void* lpObj);
int secureblackbox_messagesigner_settlsssloptions(void* lpObj, int iTLSSSLOptions);

int secureblackbox_messagesigner_gettlstlsmode(void* lpObj);
int secureblackbox_messagesigner_settlstlsmode(void* lpObj, int iTLSTLSMode);

int secureblackbox_messagesigner_gettlsuseextendedmastersecret(void* lpObj);
int secureblackbox_messagesigner_settlsuseextendedmastersecret(void* lpObj, int bTLSUseExtendedMasterSecret);

int secureblackbox_messagesigner_gettlsusesessionresumption(void* lpObj);
int secureblackbox_messagesigner_settlsusesessionresumption(void* lpObj, int bTLSUseSessionResumption);

int secureblackbox_messagesigner_gettlsversions(void* lpObj);
int secureblackbox_messagesigner_settlsversions(void* lpObj, int iTLSVersions);

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

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

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

int GetTLSClientAuth();
int SetTLSClientAuth(int iTLSClientAuth);

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

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

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

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

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

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

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

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

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

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

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

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

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

Remarks

Use this property to tune up the TLS layer parameters.

This property is read-only.

Data Type

SecureBlackboxTLSSettings

UnsignedAttributes Property (MessageSigner Class)

Custom unsigned attributes to be included in the electronic signature.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxSignatureAttribute>* GetUnsignedAttributes();

int secureblackbox_messagesigner_getunsignedattributecount(void* lpObj);
int secureblackbox_messagesigner_setunsignedattributecount(void* lpObj, int iUnsignedAttributeCount);

char* secureblackbox_messagesigner_getunsignedattributeoid(void* lpObj, int unsignedattributeindex);
int secureblackbox_messagesigner_setunsignedattributeoid(void* lpObj, int unsignedattributeindex, const char* lpszUnsignedAttributeOID);

int secureblackbox_messagesigner_getunsignedattributevalue(void* lpObj, int unsignedattributeindex, char** lpUnsignedAttributeValue, int* lenUnsignedAttributeValue);
int secureblackbox_messagesigner_setunsignedattributevalue(void* lpObj, int unsignedattributeindex, const char* lpUnsignedAttributeValue, int lenUnsignedAttributeValue);

int GetUnsignedAttributeCount();
int SetUnsignedAttributeCount(int iUnsignedAttributeCount);

QString GetUnsignedAttributeOID(int iUnsignedAttributeIndex);
int SetUnsignedAttributeOID(int iUnsignedAttributeIndex, QString qsUnsignedAttributeOID);

QByteArray GetUnsignedAttributeValue(int iUnsignedAttributeIndex);
int SetUnsignedAttributeValue(int iUnsignedAttributeIndex, QByteArray qbaUnsignedAttributeValue);

Remarks

Signature attributes are used to store auxiliary information in the signature. Values included as unsigned attributes are not covered by the signature and can be changed or removed without affecting the signature.

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

Data Type

SecureBlackboxSignatureAttribute

AddAttribute Method (MessageSigner Class)

Adds an attribute to the signature.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddAttribute(const char* lpszOID, const char* lpValue, int lenValue, int bSignedAttribute);

Unicode (Windows)
INT AddAttribute(LPCWSTR lpszOID, LPCSTR lpValue, INT lenValue, BOOL bSignedAttribute);

int secureblackbox_messagesigner_addattribute(void* lpObj, const char* lpszOID, const char* lpValue, int lenValue, int bSignedAttribute);

int AddAttribute(const QString& qsOID, QByteArray qbaValue, bool bSignedAttribute);

Remarks

Use this method to add a signed or unsigned attribute to the collection of attributes included in the new signature.

Note that CAdESSigner creates certain mandatory and/or widely used attributes automatically in accordance with requirements for a specific signing profile. For example, attributes such as SigningCertificateV2 or SigningTime are always added. Policy attributes are added if specified via the PolicyID or PolicyURI properties of the signature object.

Use the OID parameter to provide the object identifier of the attribute, in string form. For example, the OID for the SigningCertificateV2 attribute is 1.2.840.113549.1.9.16.2.47. The Value parameter should contain a well-formed, DER-encoded representation of the attribute value, in accordance with its specification.

Error Handling (C++)

This method returns an Integer 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.

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

Countersign Method (MessageSigner Class)

Countersigns an existing signature.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Countersign();

Unicode (Windows)
INT Countersign();

int secureblackbox_messagesigner_countersign(void* lpObj);

int Countersign();

Remarks

Use this method to certify an existing document signature. Countersigning doesn't alter the existing signatures or the signed document itself.

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

DoAction Method (MessageSigner 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_messagesigner_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 insensitive) of the action is provided in the ActionID parameter.

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

Common ActionIDs:

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.

ExtractAsyncData Method (MessageSigner Class)

Extracts user data from the DC signing service response.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ExtractAsyncData(const char* lpszAsyncReply);

Unicode (Windows)
LPWSTR ExtractAsyncData(LPCWSTR lpszAsyncReply);

char* secureblackbox_messagesigner_extractasyncdata(void* lpObj, const char* lpszAsyncReply);

QString ExtractAsyncData(const QString& qsAsyncReply);

Remarks

Call this method before finalizing the asynchronous signing process to extract the data passed to the ExternalCrypto.Data property on the pre-signing stage.

The Data parameter can be used to pass some state or document identifier along with the signing request from the pre-signing to the completion async stage.

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.

Reset Method (MessageSigner Class)

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int secureblackbox_messagesigner_reset(void* lpObj);

int Reset();

Remarks

Reset is a generic method available in every class.

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

Sign Method (MessageSigner Class)

Signs the data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Sign();

Unicode (Windows)
INT Sign();

int secureblackbox_messagesigner_sign(void* lpObj);

int Sign();

Remarks

This method signs the data provided via InputFile (or InputStream) with SigningCertificate, and saves the signature in OutputFile (OutputStream). Set the desired signature variant via SignatureType property.

The class automatically timestamps the created signature if a TimestampServer is provided.

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

SignAsyncBegin Method (MessageSigner Class)

Initiates the asynchronous signing operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* SignAsyncBegin();

Unicode (Windows)
LPWSTR SignAsyncBegin();

char* secureblackbox_messagesigner_signasyncbegin(void* lpObj);

QString SignAsyncBegin();

Remarks

When using the DC framework, call this method to initiate the asynchronous signing process. Upon completion, a pre-signed copy of the document will be saved in OutputFile (or OutputStream). Keep the pre-signed copy somewhere local, and pass the returned string ('the request state') to the DC processor for handling.

Upon receiving the response state from the DC processor, assign the path to the pre-signed copy to InputFile (or InputStream), and call SignAsyncEnd to finalize the signing.

Note that depending on the signing method and DC configuration used, you may still need to provide the public part of the signing certificate via the SigningCertificate property.

Use the ExternalCrypto.AsyncDocumentID property to supply a unique document ID to include in the request. This is helpful when creating batches of multiple async requests, as it allows you to pass the whole response batch to SignAsyncEnd and expect it to recover the correct response from the batch automatically.

AsyncState is a message of the distributed cryptography (DC) protocol. The DC protocol is based on the exchange of async states between a DC client (an application that wants to sign a PDF, XML, or Office document) and a DC server (an application that controls access to the private key). An async state can carry one or more signing requests, comprised of document hashes, or one or more signatures produced over those hashes.

In a typical scenario you get a client-side async state from the SignAsyncBegin method. This state contains document hashes to be signed on the DC server side. You then send the async state to the DC server (often represented by the DCAuth class), which processes it and produces a matching signature state. The async state produced by the server is then passed to the SignAsyncEnd method.

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.

SignAsyncEnd Method (MessageSigner Class)

Completes the asynchronous signing operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SignAsyncEnd(const char* lpszAsyncReply);

Unicode (Windows)
INT SignAsyncEnd(LPCWSTR lpszAsyncReply);

int secureblackbox_messagesigner_signasyncend(void* lpObj, const char* lpszAsyncReply);

int SignAsyncEnd(const QString& qsAsyncReply);

Remarks

When using the DC framework, call this method upon receiving the response state from the DC processor to complete the asynchronous signing process.

Before calling this method, assign the path to the pre-signed copy of the document obtained from the prior SignAsyncBegin call to InputFile (or InputStream). The method will embed the signature into the pre-signed document, and save the complete signed document to OutputFile (or OutputStream).

Note that depending on the signing method and DC configuration used, you may still need to provide the public part of the signing certificate via the SigningCertificate property.

Use the ExternalCrypto.AsyncDocumentID parameter to pass a specific document ID if using batched AsyncReply. If used, it should match the value provided on the pre-signing (SignAsyncBegin) stage.

AsyncState is a message of the distributed cryptography (DC) protocol. The DC protocol is based on the exchange of async states between a DC client (an application that wants to sign a PDF, XML, or Office document) and a DC server (an application that controls access to the private key). An async state can carry one or more signing requests, comprised of document hashes, or one or more signatures produced over those hashes.

In a typical scenario you get a client-side async state from the SignAsyncBegin method. This state contains document hashes to be signed on the DC server side. You then send the async state to the DC server (often represented by the DCAuth class), which processes it and produces a matching signature state. The async state produced by the server is then passed to the SignAsyncEnd method.

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

Timestamp Method (MessageSigner Class)

Timestamps a signature.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Timestamp();

Unicode (Windows)
INT Timestamp();

int secureblackbox_messagesigner_timestamp(void* lpObj);

int Timestamp();

Remarks

This method timestamps an existing PKCS#7 signature with TimestampServer. Pass your existing signature via InputFile (or InputStream), and collect the timestamped variant from OutputFile (OutputStream).

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

Error Event (MessageSigner Class)

Information about errors during PKCS#7 message signing.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_ERROR 1

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

class MessageSignerErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

The event is fired in case of exceptional conditions during message processing.

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

ExternalSign Event (MessageSigner Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_EXTERNALSIGN 2

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

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

  const QString &HashAlgorithm();

  const QString &Pars();

  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(MessageSignerExternalSignEventParams *e);

// Or, subclass MessageSigner and override this emitter function.
virtual int FireExternalSign(MessageSignerExternalSignEventParams *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 class via the SignedData parameter.

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

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

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

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

Notification Event (MessageSigner Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_NOTIFICATION 3

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

class MessageSignerNotificationEventParams {
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(MessageSignerNotificationEventParams *e);

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

Remarks

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

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

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

TimestampRequest Event (MessageSigner 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(MessageSignerTimestampRequestEventParams *e);

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


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

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

#define EID_MESSAGESIGNER_TIMESTAMPREQUEST 4

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

class MessageSignerTimestampRequestEventParams {
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(MessageSignerTimestampRequestEventParams *e);

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

Remarks

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

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

TLSCertNeeded Event (MessageSigner Class)

Fires when a remote TLS party requests a client certificate.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_TLSCERTNEEDED 5

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

class MessageSignerTLSCertNeededEventParams {
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(MessageSignerTLSCertNeededEventParams *e);

// Or, subclass MessageSigner and override this emitter function.
virtual int FireTLSCertNeeded(MessageSignerTLSCertNeededEventParams *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 parameter (optional, according to the TLS spec) advises on the accepted issuing CAs.

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

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

TLSCertValidate Event (MessageSigner 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(MessageSignerTLSCertValidateEventParams *e);

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


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

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

#define EID_MESSAGESIGNER_TLSCERTVALIDATE 6

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

class MessageSignerTLSCertValidateEventParams {
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(MessageSignerTLSCertValidateEventParams *e);

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

Remarks

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

TLSEstablished Event (MessageSigner Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_TLSESTABLISHED 7

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

class MessageSignerTLSEstablishedEventParams {
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(MessageSignerTLSEstablishedEventParams *e);

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

Remarks

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

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

TLSHandshake Event (MessageSigner Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_TLSHANDSHAKE 8

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

class MessageSignerTLSHandshakeEventParams {
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(MessageSignerTLSHandshakeEventParams *e);

// Or, subclass MessageSigner and override this emitter function.
virtual int FireTLSHandshake(MessageSignerTLSHandshakeEventParams *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 by the TLSEstablished event. If the server chooses to request a client certificate, the TLSCertNeeded event will also be fired.

TLSShutdown Event (MessageSigner Class)

Reports the graceful closure of a TLS connection.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_MESSAGESIGNER_TLSSHUTDOWN 9

virtual INT SECUREBLACKBOX_CALL FireTLSShutdown(LPSTR &lpszHost);

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

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

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

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

Remarks

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

Certificate Type

Encapsulates an individual X.509 certificate.

Syntax

SecureBlackboxCertificate (declared in secureblackbox.h)

Remarks

This type keeps and provides access to X.509 certificate details.

Fields

Constructors

Certificate()

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Syntax

SecureBlackboxExternalCrypto (declared in secureblackbox.h)

Remarks

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

Fields

Constructors

ExternalCrypto()

ProxySettings Type

A container for proxy server settings.

Syntax

SecureBlackboxProxySettings (declared in secureblackbox.h)

Remarks

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

Fields

Constructors

ProxySettings()

SignatureAttribute Type

Represents an attribute of a digital PKCS#7/CMS signature.

Syntax

SecureBlackboxSignatureAttribute (declared in secureblackbox.h)

Remarks

Attributes store auxiliary information about the signed message, the signature, or the owner. Each attribute is a OID=Value pair.

Common attributes are signing time, a content type, a policy identifier, and a signature timestamp.

Fields

Constructors

SignatureAttribute()

SocketSettings Type

A container for the socket settings.

Syntax

SecureBlackboxSocketSettings (declared in secureblackbox.h)

Remarks

This type is a container for socket-layer parameters.

Fields

Constructors

SocketSettings()

TLSSettings Type

A container for TLS connection settings.

Syntax

SecureBlackboxTLSSettings (declared in secureblackbox.h)

Remarks

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

Fields

Constructors

TLSSettings()

SecureBlackboxList Type

Syntax

SecureBlackboxList<T> (declared in secureblackbox.h)

Remarks

SecureBlackboxList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the MessageSigner class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

T* Set(int index, T* value) {}

Config Settings (MessageSigner Class)

MessageSigner Config Settings

Base Config Settings