AuthenticodeSigner Class

Properties   Methods   Events   Config Settings   Errors  

The AuthenticodeSigner class signs executable files (EXE) and dynamically linked libraries (DLL) using Microsoft Authenticode format.

Syntax

AuthenticodeSigner

Remarks

Use this component to sign your binaries and optionally timestamp them.

Authenticode signing of executables is a must in the majority of modern Windows-based environments and infrastructures. A digital signature over the executable ensures that the executable comes from a trusted vendor, verified by the CA that issued the certificate.

While Microsoft provides a tool that facilitates creation of Authenticode signatures, in some cases that tool may be awkward or even impossible to use. In those cases the AuthenticodeSigner component can stand in for the job. Capable of signing executables on all supported platforms, using certificates residing on any kind of media (including remote ones, via PKI Proxy), AuthenticodeSigner can easily fit any build environments imaginable.

AuthenticodeSigner supports the latest security algorithms and standards, including SHA2, ECDSA, timestamping, and cross-signing certificates. AuthenticodeSigner signer = new AuthenticodeSigner(); signer.setHashAlgorithm("SHA256"); // Default hashing algorithm SHA256 // Select the file which contains the executable that will be signed signer.setInputFile("executable.exe"); // Select the file where the signed executable will be saved signer.setOutputFile("signedExecutable.exe"); // Specify the certificate that shall be used for signing the exectutable 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.

BlockedCertificates Property (AuthenticodeSigner Class)

The certificates that must be rejected as trust anchors.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetBlockedCertificates();
int SetBlockedCertificates(SecureBlackboxList<SecureBlackboxCertificate>* val);

int secureblackbox_authenticodesigner_getblockedcertcount(void* lpObj);
int secureblackbox_authenticodesigner_setblockedcertcount(void* lpObj, int iBlockedCertCount);

int secureblackbox_authenticodesigner_getblockedcertbytes(void* lpObj, int blockedcertindex, char** lpBlockedCertBytes, int* lenBlockedCertBytes);

int64 secureblackbox_authenticodesigner_getblockedcerthandle(void* lpObj, int blockedcertindex);
int secureblackbox_authenticodesigner_setblockedcerthandle(void* lpObj, int blockedcertindex, int64 lBlockedCertHandle);

int GetBlockedCertCount();
int SetBlockedCertCount(int iBlockedCertCount);

QByteArray GetBlockedCertBytes(int iBlockedCertIndex);

qint64 GetBlockedCertHandle(int iBlockedCertIndex);
int SetBlockedCertHandle(int iBlockedCertIndex, qint64 lBlockedCertHandle);

Remarks

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

This property is not available at design time.

Data Type

SecureBlackboxCertificate

ClaimedSigningTime Property (AuthenticodeSigner 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_authenticodesigner_getclaimedsigningtime(void* lpObj);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

Provides access to external signing and DC parameters.

Syntax

• C++
• C
• Qt

SecureBlackboxExternalCrypto* GetExternalCrypto();

char* secureblackbox_authenticodesigner_getexternalcryptoasyncdocumentid(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptoasyncdocumentid(void* lpObj, const char* lpszExternalCryptoAsyncDocumentID);

char* secureblackbox_authenticodesigner_getexternalcryptocustomparams(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptocustomparams(void* lpObj, const char* lpszExternalCryptoCustomParams);

char* secureblackbox_authenticodesigner_getexternalcryptodata(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptodata(void* lpObj, const char* lpszExternalCryptoData);

int secureblackbox_authenticodesigner_getexternalcryptoexternalhashcalculation(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptoexternalhashcalculation(void* lpObj, int bExternalCryptoExternalHashCalculation);

char* secureblackbox_authenticodesigner_getexternalcryptohashalgorithm(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptohashalgorithm(void* lpObj, const char* lpszExternalCryptoHashAlgorithm);

char* secureblackbox_authenticodesigner_getexternalcryptokeyid(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptokeyid(void* lpObj, const char* lpszExternalCryptoKeyID);

char* secureblackbox_authenticodesigner_getexternalcryptokeysecret(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptokeysecret(void* lpObj, const char* lpszExternalCryptoKeySecret);

int secureblackbox_authenticodesigner_getexternalcryptomethod(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptomethod(void* lpObj, int iExternalCryptoMethod);

int secureblackbox_authenticodesigner_getexternalcryptomode(void* lpObj);
int secureblackbox_authenticodesigner_setexternalcryptomode(void* lpObj, int iExternalCryptoMode);

char* secureblackbox_authenticodesigner_getexternalcryptopublickeyalgorithm(void* lpObj);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner 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_authenticodesigner_getfipsmode(void* lpObj);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

The hash algorithm to be used for signing.

Syntax

• C++
• C
• Qt

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

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

char* secureblackbox_authenticodesigner_gethashalgorithm(void* lpObj);
int secureblackbox_authenticodesigner_sethashalgorithm(void* lpObj, const char* lpszHashAlgorithm);

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

Default Value

"SHA256"

Remarks

The following algorithms are supported: MD5, SHA1, SHA224, SHA256, SHA384, SHA512, SHA3_224, SHA3_256, SHA3_384, SHA3_512.

Data Type

String

IgnoreChainValidationErrors Property (AuthenticodeSigner Class)

Makes the class tolerant to chain validation errors.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIgnoreChainValidationErrors();
int SetIgnoreChainValidationErrors(int bIgnoreChainValidationErrors);

Unicode (Windows)
BOOL GetIgnoreChainValidationErrors();
INT SetIgnoreChainValidationErrors(BOOL bIgnoreChainValidationErrors);

int secureblackbox_authenticodesigner_getignorechainvalidationerrors(void* lpObj);
int secureblackbox_authenticodesigner_setignorechainvalidationerrors(void* lpObj, int bIgnoreChainValidationErrors);

bool GetIgnoreChainValidationErrors();
int SetIgnoreChainValidationErrors(bool bIgnoreChainValidationErrors);

Default Value

FALSE

Remarks

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

Data Type

Boolean

InputBytes Property (AuthenticodeSigner 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_authenticodesigner_getinputbytes(void* lpObj, char** lpInputBytes, int* lenInputBytes);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

A path to the executable to be signed.

Syntax

• C++
• C
• Qt

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

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

char* secureblackbox_authenticodesigner_getinputfile(void* lpObj);
int secureblackbox_authenticodesigner_setinputfile(void* lpObj, const char* lpszInputFile);

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

Default Value

""

Remarks

A path to the file containing the executable to be signed. The input can alternatively be provided via InputStream.

Data Type

String

KnownCertificates Property (AuthenticodeSigner Class)

Additional certificates for chain validation.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetKnownCertificates();
int SetKnownCertificates(SecureBlackboxList<SecureBlackboxCertificate>* val);

int secureblackbox_authenticodesigner_getknowncertcount(void* lpObj);
int secureblackbox_authenticodesigner_setknowncertcount(void* lpObj, int iKnownCertCount);

int secureblackbox_authenticodesigner_getknowncertbytes(void* lpObj, int knowncertindex, char** lpKnownCertBytes, int* lenKnownCertBytes);

int64 secureblackbox_authenticodesigner_getknowncerthandle(void* lpObj, int knowncertindex);
int secureblackbox_authenticodesigner_setknowncerthandle(void* lpObj, int knowncertindex, int64 lKnownCertHandle);

int GetKnownCertCount();
int SetKnownCertCount(int iKnownCertCount);

QByteArray GetKnownCertBytes(int iKnownCertIndex);

qint64 GetKnownCertHandle(int iKnownCertIndex);
int SetKnownCertHandle(int iKnownCertIndex, qint64 lKnownCertHandle);

Remarks

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

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

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

This property is not available at design time.

Data Type

SecureBlackboxCertificate

KnownCRLs Property (AuthenticodeSigner Class)

Additional CRLs for chain validation.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCRL>* GetKnownCRLs();
int SetKnownCRLs(SecureBlackboxList<SecureBlackboxCRL>* val);

int secureblackbox_authenticodesigner_getknowncrlcount(void* lpObj);
int secureblackbox_authenticodesigner_setknowncrlcount(void* lpObj, int iKnownCRLCount);

int secureblackbox_authenticodesigner_getknowncrlbytes(void* lpObj, int knowncrlindex, char** lpKnownCRLBytes, int* lenKnownCRLBytes);

int64 secureblackbox_authenticodesigner_getknowncrlhandle(void* lpObj, int knowncrlindex);
int secureblackbox_authenticodesigner_setknowncrlhandle(void* lpObj, int knowncrlindex, int64 lKnownCRLHandle);

int GetKnownCRLCount();
int SetKnownCRLCount(int iKnownCRLCount);

QByteArray GetKnownCRLBytes(int iKnownCRLIndex);

qint64 GetKnownCRLHandle(int iKnownCRLIndex);
int SetKnownCRLHandle(int iKnownCRLIndex, qint64 lKnownCRLHandle);

Remarks

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

This property is not available at design time.

Data Type

SecureBlackboxCRL

KnownOCSPs Property (AuthenticodeSigner Class)

Additional OCSP responses for chain validation.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxOCSPResponse>* GetKnownOCSPs();
int SetKnownOCSPs(SecureBlackboxList<SecureBlackboxOCSPResponse>* val);

int secureblackbox_authenticodesigner_getknownocspcount(void* lpObj);
int secureblackbox_authenticodesigner_setknownocspcount(void* lpObj, int iKnownOCSPCount);

int secureblackbox_authenticodesigner_getknownocspbytes(void* lpObj, int knownocspindex, char** lpKnownOCSPBytes, int* lenKnownOCSPBytes);

int64 secureblackbox_authenticodesigner_getknownocsphandle(void* lpObj, int knownocspindex);
int secureblackbox_authenticodesigner_setknownocsphandle(void* lpObj, int knownocspindex, int64 lKnownOCSPHandle);

int GetKnownOCSPCount();
int SetKnownOCSPCount(int iKnownOCSPCount);

QByteArray GetKnownOCSPBytes(int iKnownOCSPIndex);

qint64 GetKnownOCSPHandle(int iKnownOCSPIndex);
int SetKnownOCSPHandle(int iKnownOCSPIndex, qint64 lKnownOCSPHandle);

Remarks

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

This property is not available at design time.

Data Type

SecureBlackboxOCSPResponse

OfflineMode Property (AuthenticodeSigner Class)

Switches the class to offline mode.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOfflineMode();
int SetOfflineMode(int bOfflineMode);

Unicode (Windows)
BOOL GetOfflineMode();
INT SetOfflineMode(BOOL bOfflineMode);

int secureblackbox_authenticodesigner_getofflinemode(void* lpObj);
int secureblackbox_authenticodesigner_setofflinemode(void* lpObj, int bOfflineMode);

bool GetOfflineMode();
int SetOfflineMode(bool bOfflineMode);

Default Value

FALSE

Remarks

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

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

Data Type

Boolean

OutputBytes Property (AuthenticodeSigner 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_authenticodesigner_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 (AuthenticodeSigner Class)

The file to save the signed executable to.

Syntax

• C++
• C
• Qt

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

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

char* secureblackbox_authenticodesigner_getoutputfile(void* lpObj);
int secureblackbox_authenticodesigner_setoutputfile(void* lpObj, const char* lpszOutputFile);

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

Default Value

""

Remarks

A path to the file where the class should save the signed executable file. Use OutputStream to save the signed file to a stream instead.

Data Type

String

Profile Property (AuthenticodeSigner 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_authenticodesigner_getprofile(void* lpObj);
int secureblackbox_authenticodesigner_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

Proxy Property (AuthenticodeSigner Class)

The proxy server settings.

Syntax

• C++
• C
• Qt

SecureBlackboxProxySettings* GetProxy();

char* secureblackbox_authenticodesigner_getproxyaddress(void* lpObj);
int secureblackbox_authenticodesigner_setproxyaddress(void* lpObj, const char* lpszProxyAddress);

int secureblackbox_authenticodesigner_getproxyauthentication(void* lpObj);
int secureblackbox_authenticodesigner_setproxyauthentication(void* lpObj, int iProxyAuthentication);

char* secureblackbox_authenticodesigner_getproxypassword(void* lpObj);
int secureblackbox_authenticodesigner_setproxypassword(void* lpObj, const char* lpszProxyPassword);

int secureblackbox_authenticodesigner_getproxyport(void* lpObj);
int secureblackbox_authenticodesigner_setproxyport(void* lpObj, int iProxyPort);

int secureblackbox_authenticodesigner_getproxyproxytype(void* lpObj);
int secureblackbox_authenticodesigner_setproxyproxytype(void* lpObj, int iProxyProxyType);

char* secureblackbox_authenticodesigner_getproxyrequestheaders(void* lpObj);
int secureblackbox_authenticodesigner_setproxyrequestheaders(void* lpObj, const char* lpszProxyRequestHeaders);

char* secureblackbox_authenticodesigner_getproxyresponsebody(void* lpObj);
int secureblackbox_authenticodesigner_setproxyresponsebody(void* lpObj, const char* lpszProxyResponseBody);

char* secureblackbox_authenticodesigner_getproxyresponseheaders(void* lpObj);
int secureblackbox_authenticodesigner_setproxyresponseheaders(void* lpObj, const char* lpszProxyResponseHeaders);

int secureblackbox_authenticodesigner_getproxyuseipv6(void* lpObj);
int secureblackbox_authenticodesigner_setproxyuseipv6(void* lpObj, int bProxyUseIPv6);

char* secureblackbox_authenticodesigner_getproxyusername(void* lpObj);
int secureblackbox_authenticodesigner_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

RemoveExistingSignatures Property (AuthenticodeSigner Class)

Specifies whether to remove any existing signatures before signing.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRemoveExistingSignatures();
int SetRemoveExistingSignatures(int bRemoveExistingSignatures);

Unicode (Windows)
BOOL GetRemoveExistingSignatures();
INT SetRemoveExistingSignatures(BOOL bRemoveExistingSignatures);

int secureblackbox_authenticodesigner_getremoveexistingsignatures(void* lpObj);
int secureblackbox_authenticodesigner_setremoveexistingsignatures(void* lpObj, int bRemoveExistingSignatures);

bool GetRemoveExistingSignatures();
int SetRemoveExistingSignatures(bool bRemoveExistingSignatures);

Default Value

FALSE

Remarks

If this property is set to True, all the existing Authenticode signatures will be removed from the executable before adding the new one. If this property is False, the new signature will be added on top of the existing ones.

Data Type

Boolean

RevocationCheck Property (AuthenticodeSigner Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRevocationCheck();
int SetRevocationCheck(int iRevocationCheck);

Unicode (Windows)
INT GetRevocationCheck();
INT SetRevocationCheck(INT iRevocationCheck);

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_authenticodesigner_getrevocationcheck(void* lpObj);
int secureblackbox_authenticodesigner_setrevocationcheck(void* lpObj, int iRevocationCheck);

int GetRevocationCheck();
int SetRevocationCheck(int iRevocationCheck);

Default Value

1

Remarks

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

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

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

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

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

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

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

Data Type

Integer

SignatureDescription Property (AuthenticodeSigner Class)

Sets human-readable signature description.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSignatureDescription();
int SetSignatureDescription(const char* lpszSignatureDescription);

Unicode (Windows)
LPWSTR GetSignatureDescription();
INT SetSignatureDescription(LPCWSTR lpszSignatureDescription);

char* secureblackbox_authenticodesigner_getsignaturedescription(void* lpObj);
int secureblackbox_authenticodesigner_setsignaturedescription(void* lpObj, const char* lpszSignatureDescription);

QString GetSignatureDescription();
int SetSignatureDescription(QString qsSignatureDescription);

Default Value

""

Remarks

Use this property to provide description for the new signature. This is optional.

Data Type

String

SignatureIndex Property (AuthenticodeSigner Class)

The index of the signature to timstamp or update.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSignatureIndex();
int SetSignatureIndex(int iSignatureIndex);

Unicode (Windows)
INT GetSignatureIndex();
INT SetSignatureIndex(INT iSignatureIndex);

int secureblackbox_authenticodesigner_getsignatureindex(void* lpObj);
int secureblackbox_authenticodesigner_setsignatureindex(void* lpObj, int iSignatureIndex);

int GetSignatureIndex();
int SetSignatureIndex(int iSignatureIndex);

Default Value

-1

Remarks

Use this property to specify the index of the existing signature before timestamping or adding custom unsigned attributes. -1 means all the existing signatures.

Data Type

Integer

SignatureURL Property (AuthenticodeSigner Class)

Sets the URL to include in the signature.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSignatureURL();
int SetSignatureURL(const char* lpszSignatureURL);

Unicode (Windows)
LPWSTR GetSignatureURL();
INT SetSignatureURL(LPCWSTR lpszSignatureURL);

char* secureblackbox_authenticodesigner_getsignatureurl(void* lpObj);
int secureblackbox_authenticodesigner_setsignatureurl(void* lpObj, const char* lpszSignatureURL);

QString GetSignatureURL();
int SetSignatureURL(QString qsSignatureURL);

Default Value

""

Remarks

Use this property to provide a custom URL with the signature. This is optional.

Data Type

String

SignedAttributes Property (AuthenticodeSigner Class)

Custom signature attributes to be covered by the electronic signature.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxSignatureAttribute>* GetSignedAttributes();

int secureblackbox_authenticodesigner_getsignedattributecount(void* lpObj);
int secureblackbox_authenticodesigner_setsignedattributecount(void* lpObj, int iSignedAttributeCount);

char* secureblackbox_authenticodesigner_getsignedattributeoid(void* lpObj, int signedattributeindex);
int secureblackbox_authenticodesigner_setsignedattributeoid(void* lpObj, int signedattributeindex, const char* lpszSignedAttributeOID);

int secureblackbox_authenticodesigner_getsignedattributevalue(void* lpObj, int signedattributeindex, char** lpSignedAttributeValue, int* lenSignedAttributeValue);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

The certificate to be used for signing.

Syntax

• C++
• C
• Qt

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

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

int64 secureblackbox_authenticodesigner_getsigningcerthandle(void* lpObj);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

The signing certificate chain.

Syntax

• C++
• C
• Qt

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

int secureblackbox_authenticodesigner_getsigningchaincount(void* lpObj);
int secureblackbox_authenticodesigner_setsigningchaincount(void* lpObj, int iSigningChainCount);

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

int64 secureblackbox_authenticodesigner_getsigningchainhandle(void* lpObj, int signingchainindex);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

Manages network connection settings.

Syntax

• C++
• C
• Qt

SecureBlackboxSocketSettings* GetSocketSettings();

int secureblackbox_authenticodesigner_getsocketdnsmode(void* lpObj);
int secureblackbox_authenticodesigner_setsocketdnsmode(void* lpObj, int iSocketDNSMode);

int secureblackbox_authenticodesigner_getsocketdnsport(void* lpObj);
int secureblackbox_authenticodesigner_setsocketdnsport(void* lpObj, int iSocketDNSPort);

int secureblackbox_authenticodesigner_getsocketdnsquerytimeout(void* lpObj);
int secureblackbox_authenticodesigner_setsocketdnsquerytimeout(void* lpObj, int iSocketDNSQueryTimeout);

char* secureblackbox_authenticodesigner_getsocketdnsservers(void* lpObj);
int secureblackbox_authenticodesigner_setsocketdnsservers(void* lpObj, const char* lpszSocketDNSServers);

int secureblackbox_authenticodesigner_getsocketdnstotaltimeout(void* lpObj);
int secureblackbox_authenticodesigner_setsocketdnstotaltimeout(void* lpObj, int iSocketDNSTotalTimeout);

int secureblackbox_authenticodesigner_getsocketincomingspeedlimit(void* lpObj);
int secureblackbox_authenticodesigner_setsocketincomingspeedlimit(void* lpObj, int iSocketIncomingSpeedLimit);

char* secureblackbox_authenticodesigner_getsocketlocaladdress(void* lpObj);
int secureblackbox_authenticodesigner_setsocketlocaladdress(void* lpObj, const char* lpszSocketLocalAddress);

int secureblackbox_authenticodesigner_getsocketlocalport(void* lpObj);
int secureblackbox_authenticodesigner_setsocketlocalport(void* lpObj, int iSocketLocalPort);

int secureblackbox_authenticodesigner_getsocketoutgoingspeedlimit(void* lpObj);
int secureblackbox_authenticodesigner_setsocketoutgoingspeedlimit(void* lpObj, int iSocketOutgoingSpeedLimit);

int secureblackbox_authenticodesigner_getsockettimeout(void* lpObj);
int secureblackbox_authenticodesigner_setsockettimeout(void* lpObj, int iSocketTimeout);

int secureblackbox_authenticodesigner_getsocketuseipv6(void* lpObj);
int secureblackbox_authenticodesigner_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

StatementType Property (AuthenticodeSigner Class)

Sets the signature statement type.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetStatementType();
int SetStatementType(int iStatementType);

Unicode (Windows)
INT GetStatementType();
INT SetStatementType(INT iStatementType);

ACS_UNKNOWN(0), 
ACS_INDIVIDUAL(1), 
ACS_COMMERCIAL(2)

int secureblackbox_authenticodesigner_getstatementtype(void* lpObj);
int secureblackbox_authenticodesigner_setstatementtype(void* lpObj, int iStatementType);

int GetStatementType();
int SetStatementType(int iStatementType);

Default Value

1

Remarks

Use this property to specify the signature statement type.

Data Type

Integer

TimestampServer Property (AuthenticodeSigner 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_authenticodesigner_gettimestampserver(void* lpObj);
int secureblackbox_authenticodesigner_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

TimestampType Property (AuthenticodeSigner Class)

Sets the signature timestamp type.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetTimestampType();
int SetTimestampType(int iTimestampType);

Unicode (Windows)
INT GetTimestampType();
INT SetTimestampType(INT iTimestampType);

ACT_UNKNOWN(0), 
ACT_LEGACY(1), 
ACT_TRUSTED(2)

int secureblackbox_authenticodesigner_gettimestamptype(void* lpObj);
int secureblackbox_authenticodesigner_settimestamptype(void* lpObj, int iTimestampType);

int GetTimestampType();
int SetTimestampType(int iTimestampType);

Default Value

2

Remarks

Use this property to specify the signature timestamp type. This can either be a "trusted" timestamp (a weird name applied by the Authenticode specification to a standard RFC 3161 timestamp), or a "legacy" timestamp (an older variant of the base64-encoded TSP protocol).

Data Type

Integer

TLSClientChain Property (AuthenticodeSigner Class)

The TLS client certificate chain.

Syntax

• C++
• C
• Qt

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

int secureblackbox_authenticodesigner_gettlsclientcertcount(void* lpObj);
int secureblackbox_authenticodesigner_settlsclientcertcount(void* lpObj, int iTLSClientCertCount);

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

int64 secureblackbox_authenticodesigner_gettlsclientcerthandle(void* lpObj, int tlsclientcertindex);
int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

The TLS server's certificate chain.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetTLSServerChain();

int secureblackbox_authenticodesigner_gettlsservercertcount(void* lpObj);

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

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

int64 secureblackbox_authenticodesigner_gettlsservercerthandle(void* lpObj, int tlsservercertindex);

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

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

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

int secureblackbox_authenticodesigner_gettlsservercertkeybits(void* lpObj, int tlsservercertindex);

int secureblackbox_authenticodesigner_gettlsservercertkeyusage(void* lpObj, int tlsservercertindex);

int secureblackbox_authenticodesigner_gettlsservercertselfsigned(void* lpObj, int tlsservercertindex);

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

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

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

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

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

char* secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

Manages TLS layer settings.

Syntax

• C++
• C
• Qt

SecureBlackboxTLSSettings* GetTLSSettings();

int secureblackbox_authenticodesigner_gettlsautovalidatecertificates(void* lpObj);
int secureblackbox_authenticodesigner_settlsautovalidatecertificates(void* lpObj, int bTLSAutoValidateCertificates);

int secureblackbox_authenticodesigner_gettlsbaseconfiguration(void* lpObj);
int secureblackbox_authenticodesigner_settlsbaseconfiguration(void* lpObj, int iTLSBaseConfiguration);

char* secureblackbox_authenticodesigner_gettlsciphersuites(void* lpObj);
int secureblackbox_authenticodesigner_settlsciphersuites(void* lpObj, const char* lpszTLSCiphersuites);

int secureblackbox_authenticodesigner_gettlsclientauth(void* lpObj);
int secureblackbox_authenticodesigner_settlsclientauth(void* lpObj, int iTLSClientAuth);

char* secureblackbox_authenticodesigner_gettlseccurves(void* lpObj);
int secureblackbox_authenticodesigner_settlseccurves(void* lpObj, const char* lpszTLSECCurves);

char* secureblackbox_authenticodesigner_gettlsextensions(void* lpObj);
int secureblackbox_authenticodesigner_settlsextensions(void* lpObj, const char* lpszTLSExtensions);

int secureblackbox_authenticodesigner_gettlsforceresumeifdestinationchanges(void* lpObj);
int secureblackbox_authenticodesigner_settlsforceresumeifdestinationchanges(void* lpObj, int bTLSForceResumeIfDestinationChanges);

char* secureblackbox_authenticodesigner_gettlspresharedidentity(void* lpObj);
int secureblackbox_authenticodesigner_settlspresharedidentity(void* lpObj, const char* lpszTLSPreSharedIdentity);

char* secureblackbox_authenticodesigner_gettlspresharedkey(void* lpObj);
int secureblackbox_authenticodesigner_settlspresharedkey(void* lpObj, const char* lpszTLSPreSharedKey);

char* secureblackbox_authenticodesigner_gettlspresharedkeyciphersuite(void* lpObj);
int secureblackbox_authenticodesigner_settlspresharedkeyciphersuite(void* lpObj, const char* lpszTLSPreSharedKeyCiphersuite);

int secureblackbox_authenticodesigner_gettlsrenegotiationattackpreventionmode(void* lpObj);
int secureblackbox_authenticodesigner_settlsrenegotiationattackpreventionmode(void* lpObj, int iTLSRenegotiationAttackPreventionMode);

int secureblackbox_authenticodesigner_gettlsrevocationcheck(void* lpObj);
int secureblackbox_authenticodesigner_settlsrevocationcheck(void* lpObj, int iTLSRevocationCheck);

int secureblackbox_authenticodesigner_gettlsssloptions(void* lpObj);
int secureblackbox_authenticodesigner_settlsssloptions(void* lpObj, int iTLSSSLOptions);

int secureblackbox_authenticodesigner_gettlstlsmode(void* lpObj);
int secureblackbox_authenticodesigner_settlstlsmode(void* lpObj, int iTLSTLSMode);

int secureblackbox_authenticodesigner_gettlsuseextendedmastersecret(void* lpObj);
int secureblackbox_authenticodesigner_settlsuseextendedmastersecret(void* lpObj, int bTLSUseExtendedMasterSecret);

int secureblackbox_authenticodesigner_gettlsusesessionresumption(void* lpObj);
int secureblackbox_authenticodesigner_settlsusesessionresumption(void* lpObj, int bTLSUseSessionResumption);

int secureblackbox_authenticodesigner_gettlsversions(void* lpObj);
int secureblackbox_authenticodesigner_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

TrustedCertificates Property (AuthenticodeSigner Class)

A list of trusted certificates for chain validation.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxCertificate>* GetTrustedCertificates();
int SetTrustedCertificates(SecureBlackboxList<SecureBlackboxCertificate>* val);

int secureblackbox_authenticodesigner_gettrustedcertcount(void* lpObj);
int secureblackbox_authenticodesigner_settrustedcertcount(void* lpObj, int iTrustedCertCount);

int secureblackbox_authenticodesigner_gettrustedcertbytes(void* lpObj, int trustedcertindex, char** lpTrustedCertBytes, int* lenTrustedCertBytes);

int64 secureblackbox_authenticodesigner_gettrustedcerthandle(void* lpObj, int trustedcertindex);
int secureblackbox_authenticodesigner_settrustedcerthandle(void* lpObj, int trustedcertindex, int64 lTrustedCertHandle);

int GetTrustedCertCount();
int SetTrustedCertCount(int iTrustedCertCount);

QByteArray GetTrustedCertBytes(int iTrustedCertIndex);

qint64 GetTrustedCertHandle(int iTrustedCertIndex);
int SetTrustedCertHandle(int iTrustedCertIndex, qint64 lTrustedCertHandle);

Remarks

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

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

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

This property is not available at design time.

Data Type

SecureBlackboxCertificate

UnsignedAttributes Property (AuthenticodeSigner Class)

Custom unsigned attributes to be included in the electronic signature.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxSignatureAttribute>* GetUnsignedAttributes();

int secureblackbox_authenticodesigner_getunsignedattributecount(void* lpObj);
int secureblackbox_authenticodesigner_setunsignedattributecount(void* lpObj, int iUnsignedAttributeCount);

char* secureblackbox_authenticodesigner_getunsignedattributeoid(void* lpObj, int unsignedattributeindex);
int secureblackbox_authenticodesigner_setunsignedattributeoid(void* lpObj, int unsignedattributeindex, const char* lpszUnsignedAttributeOID);

int secureblackbox_authenticodesigner_getunsignedattributevalue(void* lpObj, int unsignedattributeindex, char** lpUnsignedAttributeValue, int* lenUnsignedAttributeValue);
int secureblackbox_authenticodesigner_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

ValidationLog Property (AuthenticodeSigner Class)

Contains the complete log of the certificate validation routine.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetValidationLog();

Unicode (Windows)
LPWSTR GetValidationLog();

char* secureblackbox_authenticodesigner_getvalidationlog(void* lpObj);

QString GetValidationLog();

Default Value

""

Remarks

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

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

Data Type

String

AddAttribute Method (AuthenticodeSigner 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_authenticodesigner_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 (AuthenticodeSigner 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_authenticodesigner_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 (AuthenticodeSigner 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_authenticodesigner_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 (AuthenticodeSigner 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_authenticodesigner_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 (AuthenticodeSigner Class)

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int secureblackbox_authenticodesigner_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 (AuthenticodeSigner Class)

Calculates and adds a signature to the executable.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Sign();

Unicode (Windows)
INT Sign();

int secureblackbox_authenticodesigner_sign(void* lpObj);

int Sign();

Remarks

Use this method to create a new Authenticode signature over the executable as per the configuration of the component.

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

Initiates the asynchronous signing operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* SignAsyncBegin();

Unicode (Windows)
LPWSTR SignAsyncBegin();

char* secureblackbox_authenticodesigner_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 (AuthenticodeSigner 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_authenticodesigner_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.)

SignExternal Method (AuthenticodeSigner Class)

Signs the document using an external signing facility.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SignExternal();

Unicode (Windows)
INT SignExternal();

int secureblackbox_authenticodesigner_signexternal(void* lpObj);

int SignExternal();

Remarks

Use this method to create an Authenticode signature using an external signing facility for the cryptographic computations. SignExternal delegates the low-level signing operation to an external, remote, or custom signing engine. This method is useful if the signature has to be made by a device accessible through a custom or non-standard signing interface.

When all preparations are done and hash is computed, the class fires ExternalSign event which allows to pass the hash value for signing.

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

Use this method to add a timestamp to a new or to an existing signature.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Timestamp();

Unicode (Windows)
INT Timestamp();

int secureblackbox_authenticodesigner_timestamp(void* lpObj);

int Timestamp();

Remarks

Call this method to timestamp the signature(s). If only one of the existing signatures should be timestamped, specify its index using the SignatureIndex property.

Use the TimestampServer property to provide the address of the TSA (Time Stamping Authority) server which should be used for timestamping. Use the TimestampType property to specify the type of timestamp to create.

If a timestamp already exists, this will be handled according to the value of the TimestampConflictResolution config 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.)

Update Method (AuthenticodeSigner Class)

Update an existing signature (or all the signatures) by adding or removing its (their) custom unsigned attributes.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Update();

Unicode (Windows)
INT Update();

int secureblackbox_authenticodesigner_update(void* lpObj);

int Update();

Remarks

Call this method to add one or mode custom unsigned attributes to an existing signature (specify its index using the SignatureIndex property) or to all the existing signatures (set SignatureIndex to -1).

Use the UnsignedAttributes property to provide new attributes to be added. If an unsigned attribute with the same OID already exists, this will be handled according to the value of the AttributeConflictResolution config property.

If the UnsignedAttributes property is empty, all the existing unsigned attributes in the specified signature (or all the signatures) will be removed.

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

ChainElementDownload Event (AuthenticodeSigner Class)

Fires when there is a need to download a chain element from an online source.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireChainElementDownload(AuthenticodeSignerChainElementDownloadEventParams *e);

typedef struct {
  int Kind;
  const char *CertRDN;
  const char *CACertRDN;
  const char *Location;
  int Action;
  int reserved;
} AuthenticodeSignerChainElementDownloadEventParams;


Unicode (Windows)
virtual INT FireChainElementDownload(AuthenticodeSignerChainElementDownloadEventParams *e);

typedef struct {
  INT Kind;
  LPCWSTR CertRDN;
  LPCWSTR CACertRDN;
  LPCWSTR Location;
  INT Action;
  INT reserved;
} AuthenticodeSignerChainElementDownloadEventParams;

#define EID_AUTHENTICODESIGNER_CHAINELEMENTDOWNLOAD 1

virtual INT SECUREBLACKBOX_CALL FireChainElementDownload(INT &iKind, LPSTR &lpszCertRDN, LPSTR &lpszCACertRDN, LPSTR &lpszLocation, INT &iAction);

class AuthenticodeSignerChainElementDownloadEventParams {
public:
  int Kind();

  const QString &CertRDN();

  const QString &CACertRDN();

  const QString &Location();

  int Action();
  void SetAction(int iAction);

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireChainElementDownload(AuthenticodeSignerChainElementDownloadEventParams *e) {...}

Remarks

Subscribe to this event to be notified about validation element retrievals. Use the Action parameter to suppress the download if required.

ChainElementNeeded Event (AuthenticodeSigner Class)

Fires when an element required to validate the chain was not located.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireChainElementNeeded(AuthenticodeSignerChainElementNeededEventParams *e);

typedef struct {
  int Kind;
  const char *CertRDN;
  const char *CACertRDN;
  int reserved;
} AuthenticodeSignerChainElementNeededEventParams;


Unicode (Windows)
virtual INT FireChainElementNeeded(AuthenticodeSignerChainElementNeededEventParams *e);

typedef struct {
  INT Kind;
  LPCWSTR CertRDN;
  LPCWSTR CACertRDN;
  INT reserved;
} AuthenticodeSignerChainElementNeededEventParams;

#define EID_AUTHENTICODESIGNER_CHAINELEMENTNEEDED 2

virtual INT SECUREBLACKBOX_CALL FireChainElementNeeded(INT &iKind, LPSTR &lpszCertRDN, LPSTR &lpszCACertRDN);

class AuthenticodeSignerChainElementNeededEventParams {
public:
  int Kind();

  const QString &CertRDN();

  const QString &CACertRDN();

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireChainElementNeeded(AuthenticodeSignerChainElementNeededEventParams *e) {...}

Remarks

Subscribe to this event to be notified about missing validation elements. Use the KnownCRLs, KnownCertificates, and KnownOCSPs properties in the event handler to provide the missing piece.

ChainValidationProgress Event (AuthenticodeSigner Class)

This event is fired multiple times during chain validation to report various stages of the validation procedure.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireChainValidationProgress(AuthenticodeSignerChainValidationProgressEventParams *e);

typedef struct {
  const char *EventKind;
  const char *CertRDN;
  const char *CACertRDN;
  int Action;
  int reserved;
} AuthenticodeSignerChainValidationProgressEventParams;


Unicode (Windows)
virtual INT FireChainValidationProgress(AuthenticodeSignerChainValidationProgressEventParams *e);

typedef struct {
  LPCWSTR EventKind;
  LPCWSTR CertRDN;
  LPCWSTR CACertRDN;
  INT Action;
  INT reserved;
} AuthenticodeSignerChainValidationProgressEventParams;

#define EID_AUTHENTICODESIGNER_CHAINVALIDATIONPROGRESS 3

virtual INT SECUREBLACKBOX_CALL FireChainValidationProgress(LPSTR &lpszEventKind, LPSTR &lpszCertRDN, LPSTR &lpszCACertRDN, INT &iAction);

class AuthenticodeSignerChainValidationProgressEventParams {
public:
  const QString &EventKind();

  const QString &CertRDN();

  const QString &CACertRDN();

  int Action();
  void SetAction(int iAction);

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireChainValidationProgress(AuthenticodeSignerChainValidationProgressEventParams *e) {...}

Remarks

Subscribe to this event to be notified about chain validation progress. Use the Action parameter to alter the validation flow.

The EventKind parameter reports the nature of the event being reported. The CertRDN and CACertRDN parameters report the distinguished names of the certificates that are relevant for the event invocation (one or both can be empty, depending on EventKind). Use the Action parameter to adjust the validation flow.

Error Event (AuthenticodeSigner Class)

Information about errors during Authenticode signing.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_ERROR 4

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

class AuthenticodeSignerErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

This event is fired in case of exceptional conditions during binary processing.

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

ExternalSign Event (AuthenticodeSigner Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_EXTERNALSIGN 5

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireExternalSign(AuthenticodeSignerExternalSignEventParams *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 (AuthenticodeSigner Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_NOTIFICATION 6

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireNotification(AuthenticodeSignerNotificationEventParams *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:

Start Event (AuthenticodeSigner Class)

This event is fired when the class is about to start the signing process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireStart(AuthenticodeSignerStartEventParams *e);

typedef struct {
  int SpecifiedChecksum;
  int ActualChecksum;
  int IsSigned;
  int Cancel;
  int reserved;
} AuthenticodeSignerStartEventParams;


Unicode (Windows)
virtual INT FireStart(AuthenticodeSignerStartEventParams *e);

typedef struct {
  INT SpecifiedChecksum;
  INT ActualChecksum;
  BOOL IsSigned;
  BOOL Cancel;
  INT reserved;
} AuthenticodeSignerStartEventParams;

#define EID_AUTHENTICODESIGNER_START 7

virtual INT SECUREBLACKBOX_CALL FireStart(INT &iSpecifiedChecksum, INT &iActualChecksum, BOOL &bIsSigned, BOOL &bCancel);

class AuthenticodeSignerStartEventParams {
public:
  int SpecifiedChecksum();

  int ActualChecksum();

  bool IsSigned();

  bool Cancel();
  void SetCancel(bool bCancel);

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireStart(AuthenticodeSignerStartEventParams *e) {...}

Remarks

This event marks the start of the signing process over a certain file.

SpecifiedChecksum is the checksum specified in the file itself, ActualChecksum is the actual checksum computed by the class, IsSigned specifies whether the file is already signed, and Cancel allows to stop the operation.

TimestampRequest Event (AuthenticodeSigner 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(AuthenticodeSignerTimestampRequestEventParams *e);

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


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

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

#define EID_AUTHENTICODESIGNER_TIMESTAMPREQUEST 8

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireTimestampRequest(AuthenticodeSignerTimestampRequestEventParams *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 (AuthenticodeSigner Class)

Fires when a remote TLS party requests a client certificate.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_TLSCERTNEEDED 9

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireTLSCertNeeded(AuthenticodeSignerTLSCertNeededEventParams *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 (AuthenticodeSigner 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(AuthenticodeSignerTLSCertValidateEventParams *e);

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


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

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

#define EID_AUTHENTICODESIGNER_TLSCERTVALIDATE 10

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireTLSCertValidate(AuthenticodeSignerTLSCertValidateEventParams *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 (AuthenticodeSigner Class)

Fires when a TLS handshake with Host successfully completes.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_TLSESTABLISHED 11

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireTLSEstablished(AuthenticodeSignerTLSEstablishedEventParams *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 (AuthenticodeSigner Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_TLSHANDSHAKE 12

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireTLSHandshake(AuthenticodeSignerTLSHandshakeEventParams *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 (AuthenticodeSigner Class)

Reports the graceful closure of a TLS connection.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_AUTHENTICODESIGNER_TLSSHUTDOWN 13

virtual INT SECUREBLACKBOX_CALL FireTLSShutdown(LPSTR &lpszHost);

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

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

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

// Or, subclass AuthenticodeSigner and override this emitter function.
virtual int FireTLSShutdown(AuthenticodeSignerTLSShutdownEventParams *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()

CRL Type

Represents a Certificate Revocation List.

Syntax

SecureBlackboxCRL (declared in secureblackbox.h)

Remarks

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

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

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

Fields

Constructors

CRL()

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

OCSPResponse Type

Represents a single OCSP response originating from an OCSP responder.

Syntax

SecureBlackboxOCSPResponse (declared in secureblackbox.h)

Remarks

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

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

Fields

Constructors

OCSPResponse()

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