CertificateManager Class

Properties   Methods   Events   Config Settings   Errors  

The CertificateManager class supports importing, exporting, and generating X.509 certificates.

Syntax

CertificateManager

Remarks

Usage of this class includes importing and exporting certificates and keys in various formats, as well as certificate generation.

Loading certificates

To load a certificate from a file, use the ImportFromFile method. This method supports all existing certificate formats, including PFX, PEM, DER, and P7B. Note that keys contained in PFX and PEM certificates are often encrypted with a password, so you will likely need to provide one for the certificate to be loaded correctly. You can either provide the password via the method's parameter, or provide it on-demand by subscribing to the PasswordNeeded event.

Alternatively, you can use ImportBytes to load a certificate from a different type of media, such as a database.

If your certificate and its private key are stored in separate files or buffers - which is often the case where PEM or DER format is used - please load the certificate with the ImportFromFile method first, and then add the key to it with a separate call to the ImportKeyFromFile method. You can mix and match the certificate and key formats in this case; CertificateManager will handle this automatically.

Note that CertificateManager can only keep one certificate at a time. If your PFX or PEM file contains more than one certificate, use CertificateStorage component to load it instead.

Generating certificates

• call CreateNew to initialize a new certificate template.
• set all the needed certificate properties - for example, its subject, serial number, and validity period - via the Certificate property. Some of these properties will be pre-set by the preceding CreateNew call.
• load the CA certificate to a different CertificateManager object, and assign it to the CACertificate property. Note that the CA certificate should have an associated private key. Alternatively, the CA certificate can be loaded using a CertificateStorage object, which allows to import it from a hardware device or a system store.

  Note: you do not need to load and set the CA certificate if generating a self-signed certificate.

• Call Generate to generate a new keypair and wrap it into a certificate.
• Save the certificate using ExportToFile or ExportBytes methods.

  Note: take care to choose a format that supports storing private keys. If you do not save the new private key at this stage, you won't be able to recover it later.

  Note: you can save the private key separately using the ExportKey method.

Generating certificate requests

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.

CACertificate Property (CertificateManager Class)

A container for the CA certificate.

Syntax

• C++
• C
• Qt

SecureBlackboxCertificate* GetCACertificate();
int SetCACertificate(SecureBlackboxCertificate* val);

int secureblackbox_certificatemanager_getcacertbytes(void* lpObj, char** lpCACertBytes, int* lenCACertBytes);

int64 secureblackbox_certificatemanager_getcacerthandle(void* lpObj);
int secureblackbox_certificatemanager_setcacerthandle(void* lpObj, int64 lCACertHandle);

QByteArray GetCACertBytes();

qint64 GetCACertHandle();
int SetCACertHandle(qint64 lCACertHandle);

Remarks

Use this property to supply the CA certificate when needed.

You need to assign a valid CA certificate when generating a new certificate (including renewals), and when validating existing certificates. In the former case the assigned CA certificate should include the private key.

This property is not available at design time.

Data Type

SecureBlackboxCertificate

Certificate Property (CertificateManager Class)

A container for the certificate object.

Syntax

• C++
• C
• Qt

SecureBlackboxCertificate* GetCertificate();
int SetCertificate(SecureBlackboxCertificate* val);

int secureblackbox_certificatemanager_getcertbytes(void* lpObj, char** lpCertBytes, int* lenCertBytes);

int secureblackbox_certificatemanager_getcertca(void* lpObj);
int secureblackbox_certificatemanager_setcertca(void* lpObj, int bCertCA);

int secureblackbox_certificatemanager_getcertcakeyid(void* lpObj, char** lpCertCAKeyID, int* lenCertCAKeyID);

int secureblackbox_certificatemanager_getcertcerttype(void* lpObj);

char* secureblackbox_certificatemanager_getcertcrldistributionpoints(void* lpObj);
int secureblackbox_certificatemanager_setcertcrldistributionpoints(void* lpObj, const char* lpszCertCRLDistributionPoints);

char* secureblackbox_certificatemanager_getcertcurve(void* lpObj);
int secureblackbox_certificatemanager_setcertcurve(void* lpObj, const char* lpszCertCurve);

char* secureblackbox_certificatemanager_getcertfingerprint(void* lpObj);

char* secureblackbox_certificatemanager_getcertfriendlyname(void* lpObj);

int64 secureblackbox_certificatemanager_getcerthandle(void* lpObj);
int secureblackbox_certificatemanager_setcerthandle(void* lpObj, int64 lCertHandle);

char* secureblackbox_certificatemanager_getcerthashalgorithm(void* lpObj);
int secureblackbox_certificatemanager_setcerthashalgorithm(void* lpObj, const char* lpszCertHashAlgorithm);

char* secureblackbox_certificatemanager_getcertissuer(void* lpObj);

char* secureblackbox_certificatemanager_getcertissuerrdn(void* lpObj);
int secureblackbox_certificatemanager_setcertissuerrdn(void* lpObj, const char* lpszCertIssuerRDN);

char* secureblackbox_certificatemanager_getcertkeyalgorithm(void* lpObj);
int secureblackbox_certificatemanager_setcertkeyalgorithm(void* lpObj, const char* lpszCertKeyAlgorithm);

int secureblackbox_certificatemanager_getcertkeybits(void* lpObj);

char* secureblackbox_certificatemanager_getcertkeyfingerprint(void* lpObj);

int secureblackbox_certificatemanager_getcertkeyusage(void* lpObj);
int secureblackbox_certificatemanager_setcertkeyusage(void* lpObj, int iCertKeyUsage);

int secureblackbox_certificatemanager_getcertkeyvalid(void* lpObj);

char* secureblackbox_certificatemanager_getcertocsplocations(void* lpObj);
int secureblackbox_certificatemanager_setcertocsplocations(void* lpObj, const char* lpszCertOCSPLocations);

int secureblackbox_certificatemanager_getcertocspnocheck(void* lpObj);
int secureblackbox_certificatemanager_setcertocspnocheck(void* lpObj, int bCertOCSPNoCheck);

int secureblackbox_certificatemanager_getcertorigin(void* lpObj);

char* secureblackbox_certificatemanager_getcertpolicyids(void* lpObj);
int secureblackbox_certificatemanager_setcertpolicyids(void* lpObj, const char* lpszCertPolicyIDs);

int secureblackbox_certificatemanager_getcertprivatekeybytes(void* lpObj, char** lpCertPrivateKeyBytes, int* lenCertPrivateKeyBytes);

int secureblackbox_certificatemanager_getcertprivatekeyexists(void* lpObj);

int secureblackbox_certificatemanager_getcertprivatekeyextractable(void* lpObj);

int secureblackbox_certificatemanager_getcertpublickeybytes(void* lpObj, char** lpCertPublicKeyBytes, int* lenCertPublicKeyBytes);

int secureblackbox_certificatemanager_getcertqualified(void* lpObj);

int secureblackbox_certificatemanager_getcertqualifiedstatements(void* lpObj);
int secureblackbox_certificatemanager_setcertqualifiedstatements(void* lpObj, int iCertQualifiedStatements);

char* secureblackbox_certificatemanager_getcertqualifiers(void* lpObj);

int secureblackbox_certificatemanager_getcertselfsigned(void* lpObj);

int secureblackbox_certificatemanager_getcertserialnumber(void* lpObj, char** lpCertSerialNumber, int* lenCertSerialNumber);
int secureblackbox_certificatemanager_setcertserialnumber(void* lpObj, const char* lpCertSerialNumber, int lenCertSerialNumber);

char* secureblackbox_certificatemanager_getcertsigalgorithm(void* lpObj);

int secureblackbox_certificatemanager_getcertsource(void* lpObj);

char* secureblackbox_certificatemanager_getcertsubject(void* lpObj);

char* secureblackbox_certificatemanager_getcertsubjectalternativename(void* lpObj);
int secureblackbox_certificatemanager_setcertsubjectalternativename(void* lpObj, const char* lpszCertSubjectAlternativeName);

int secureblackbox_certificatemanager_getcertsubjectkeyid(void* lpObj, char** lpCertSubjectKeyID, int* lenCertSubjectKeyID);
int secureblackbox_certificatemanager_setcertsubjectkeyid(void* lpObj, const char* lpCertSubjectKeyID, int lenCertSubjectKeyID);

char* secureblackbox_certificatemanager_getcertsubjectrdn(void* lpObj);
int secureblackbox_certificatemanager_setcertsubjectrdn(void* lpObj, const char* lpszCertSubjectRDN);

int secureblackbox_certificatemanager_getcertvalid(void* lpObj);

char* secureblackbox_certificatemanager_getcertvalidfrom(void* lpObj);
int secureblackbox_certificatemanager_setcertvalidfrom(void* lpObj, const char* lpszCertValidFrom);

char* secureblackbox_certificatemanager_getcertvalidto(void* lpObj);
int secureblackbox_certificatemanager_setcertvalidto(void* lpObj, const char* lpszCertValidTo);

QByteArray GetCertBytes();

bool GetCertCA();
int SetCertCA(bool bCertCA);

QByteArray GetCertCAKeyID();

int GetCertCertType();

QString GetCertCRLDistributionPoints();
int SetCertCRLDistributionPoints(QString qsCertCRLDistributionPoints);

QString GetCertCurve();
int SetCertCurve(QString qsCertCurve);

QString GetCertFingerprint();

QString GetCertFriendlyName();

qint64 GetCertHandle();
int SetCertHandle(qint64 lCertHandle);

QString GetCertHashAlgorithm();
int SetCertHashAlgorithm(QString qsCertHashAlgorithm);

QString GetCertIssuer();

QString GetCertIssuerRDN();
int SetCertIssuerRDN(QString qsCertIssuerRDN);

QString GetCertKeyAlgorithm();
int SetCertKeyAlgorithm(QString qsCertKeyAlgorithm);

int GetCertKeyBits();

QString GetCertKeyFingerprint();

int GetCertKeyUsage();
int SetCertKeyUsage(int iCertKeyUsage);

bool GetCertKeyValid();

QString GetCertOCSPLocations();
int SetCertOCSPLocations(QString qsCertOCSPLocations);

bool GetCertOCSPNoCheck();
int SetCertOCSPNoCheck(bool bCertOCSPNoCheck);

int GetCertOrigin();

QString GetCertPolicyIDs();
int SetCertPolicyIDs(QString qsCertPolicyIDs);

QByteArray GetCertPrivateKeyBytes();

bool GetCertPrivateKeyExists();

bool GetCertPrivateKeyExtractable();

QByteArray GetCertPublicKeyBytes();

bool GetCertQualified();

int GetCertQualifiedStatements();
int SetCertQualifiedStatements(int iCertQualifiedStatements);

QString GetCertQualifiers();

bool GetCertSelfSigned();

QByteArray GetCertSerialNumber();
int SetCertSerialNumber(QByteArray qbaCertSerialNumber);

QString GetCertSigAlgorithm();

int GetCertSource();

QString GetCertSubject();

QString GetCertSubjectAlternativeName();
int SetCertSubjectAlternativeName(QString qsCertSubjectAlternativeName);

QByteArray GetCertSubjectKeyID();
int SetCertSubjectKeyID(QByteArray qbaCertSubjectKeyID);

QString GetCertSubjectRDN();
int SetCertSubjectRDN(QString qsCertSubjectRDN);

bool GetCertValid();

QString GetCertValidFrom();
int SetCertValidFrom(QString qsCertValidFrom);

QString GetCertValidTo();
int SetCertValidTo(QString qsCertValidTo);

Remarks

Use this property to set or access the properties of the certificate object on which the action is to be performed.

This property is not available at design time.

Data Type

SecureBlackboxCertificate

ExternalCrypto Property (CertificateManager Class)

Provides access to external signing and DC parameters.

Syntax

• C++
• C
• Qt

SecureBlackboxExternalCrypto* GetExternalCrypto();

char* secureblackbox_certificatemanager_getexternalcryptoasyncdocumentid(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptoasyncdocumentid(void* lpObj, const char* lpszExternalCryptoAsyncDocumentID);

char* secureblackbox_certificatemanager_getexternalcryptocustomparams(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptocustomparams(void* lpObj, const char* lpszExternalCryptoCustomParams);

char* secureblackbox_certificatemanager_getexternalcryptodata(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptodata(void* lpObj, const char* lpszExternalCryptoData);

int secureblackbox_certificatemanager_getexternalcryptoexternalhashcalculation(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptoexternalhashcalculation(void* lpObj, int bExternalCryptoExternalHashCalculation);

char* secureblackbox_certificatemanager_getexternalcryptohashalgorithm(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptohashalgorithm(void* lpObj, const char* lpszExternalCryptoHashAlgorithm);

char* secureblackbox_certificatemanager_getexternalcryptokeyid(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptokeyid(void* lpObj, const char* lpszExternalCryptoKeyID);

char* secureblackbox_certificatemanager_getexternalcryptokeysecret(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptokeysecret(void* lpObj, const char* lpszExternalCryptoKeySecret);

int secureblackbox_certificatemanager_getexternalcryptomethod(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptomethod(void* lpObj, int iExternalCryptoMethod);

int secureblackbox_certificatemanager_getexternalcryptomode(void* lpObj);
int secureblackbox_certificatemanager_setexternalcryptomode(void* lpObj, int iExternalCryptoMode);

char* secureblackbox_certificatemanager_getexternalcryptopublickeyalgorithm(void* lpObj);
int secureblackbox_certificatemanager_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 (CertificateManager 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_certificatemanager_getfipsmode(void* lpObj);
int secureblackbox_certificatemanager_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

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

CreateNew Method (CertificateManager Class)

Creates a template for a new certificate or CSR with a particular purpose in the Certificate property.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateNew(int iCertType, const char* lpszPurpose, const char* lpszSubject);

Unicode (Windows)
INT CreateNew(INT iCertType, LPCWSTR lpszPurpose, LPCWSTR lpszSubject);

int secureblackbox_certificatemanager_createnew(void* lpObj, int iCertType, const char* lpszPurpose, const char* lpszSubject);

int CreateNew(int iCertType, const QString& qsPurpose, const QString& qsSubject);

Remarks

This method pre-generates a certificate template that matches the specified purpose. The created template has its subject and default extensions initialized according to the selected purpose. Use Generate method to complete the process by generating a new keypair and signing it with the CA certificate (if provided).

The CertType parameter specifies the type of the object that you need to create. This can be a certificate or a certificate request (CSR).

• "generic" or an empty string: a generic certificate with no specific purpose. No extensions are pre-generated.
• "tls": a TLS server certificate
• "tls-client": a client-side TLS certificate
• "email": a secure e-mail (S/MIME) certificate
• "digsig": a digital signature certificate

Subject specifies the common name to include in the certificate. It can be a string of arbitrary format (e.g. "*.domain.com"), or a formatted RDN (e.g. "/C=US/O=Big Company, Inc./CN=Accounts receivable").

Leave all parameters empty to generate an empty template.

Error Handling (C++)

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

DoAction Method (CertificateManager 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_certificatemanager_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.

ExportBytes Method (CertificateManager Class)

Exports the certificate in the chosen format.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ExportBytes(int iFormat, int bExportKey, const char* lpszPassword, int *lpSize = NULL);

Unicode (Windows)
LPSTR ExportBytes(INT iFormat, BOOL bExportKey, LPCWSTR lpszPassword, LPINT lpSize = NULL);

char* secureblackbox_certificatemanager_exportbytes(void* lpObj, int iFormat, int bExportKey, const char* lpszPassword, int *lpSize);

QByteArray ExportBytes(int iFormat, bool bExportKey, const QString& qsPassword);

Remarks

Use this method to save the certificate or certificate request in one of the formats defined below.

ExportKey specifies whether to export the private key together with the certificate. Pass the encryption password via the Password parameter if needed.

Note that not all formats support encryption, and some (like PEM) only support partial encryption (key only). Keep this in mind when considering which format to choose for storing your certificates.

Error Handling (C++)

This method returns a Byte Array value (with length lpSize); 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.

ExportKey Method (CertificateManager Class)

Exports the certificate's private key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ExportKey(int iFormat, const char* lpszPassword, int *lpSize = NULL);

Unicode (Windows)
LPSTR ExportKey(INT iFormat, LPCWSTR lpszPassword, LPINT lpSize = NULL);

char* secureblackbox_certificatemanager_exportkey(void* lpObj, int iFormat, const char* lpszPassword, int *lpSize);

QByteArray ExportKey(int iFormat, const QString& qsPassword);

Remarks

Use this method to save the certificate private key in one of the formats given below. Pass the encryption password via the Password parameter.

Supported certificate key format values:

Error Handling (C++)

This method returns a Byte Array value (with length lpSize); 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.

ExportKeyToFile Method (CertificateManager Class)

Exports the private key to a file in the chosen format.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportKeyToFile(const char* lpszKeyFile, int iFormat, const char* lpszPassword);

Unicode (Windows)
INT ExportKeyToFile(LPCWSTR lpszKeyFile, INT iFormat, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_exportkeytofile(void* lpObj, const char* lpszKeyFile, int iFormat, const char* lpszPassword);

int ExportKeyToFile(const QString& qsKeyFile, int iFormat, const QString& qsPassword);

Remarks

Use this method to save the certificate key in one of the formats given below. Pass the encryption password via the Password parameter.

Supported certificate key format values:

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

ExportKeyToStream Method (CertificateManager Class)

Saves the private key to a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportKeyToStream(SecureBlackboxStream* sKeyStream, int iFormat, const char* lpszPassword);

Unicode (Windows)
INT ExportKeyToStream(SecureBlackboxStream* sKeyStream, INT iFormat, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_exportkeytostream(void* lpObj, SecureBlackboxStream* sKeyStream, int iFormat, const char* lpszPassword);

int ExportKeyToStream(SecureBlackboxStream* sKeyStream, int iFormat, const QString& qsPassword);

Remarks

Use this method to export the private key to a stream in one of the formats given below. Pass the encryption password via the Password parameter.

Supported certificate key format values:

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

ExportToFile Method (CertificateManager Class)

Exports the certificate to a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportToFile(const char* lpszFileName, int iFormat, int bExportKey, const char* lpszPassword);

Unicode (Windows)
INT ExportToFile(LPCWSTR lpszFileName, INT iFormat, BOOL bExportKey, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_exporttofile(void* lpObj, const char* lpszFileName, int iFormat, int bExportKey, const char* lpszPassword);

int ExportToFile(const QString& qsFileName, int iFormat, bool bExportKey, const QString& qsPassword);

Remarks

Use this method to save the certificate to a file in one of the formats given below. Pass the encryption password via the Password parameter. Set ExportKey to true to save the private key together with the certificate.

Note that not all formats support encryption, and some (like PEM) only support partial encryption (key only). Keep this in mind when considering which format to choose for storing your certificates.

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

ExportToStream Method (CertificateManager Class)

Exports the certificate to a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportToStream(SecureBlackboxStream* sCertStream, int iFormat, int bExportKey, const char* lpszPassword);

Unicode (Windows)
INT ExportToStream(SecureBlackboxStream* sCertStream, INT iFormat, BOOL bExportKey, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_exporttostream(void* lpObj, SecureBlackboxStream* sCertStream, int iFormat, int bExportKey, const char* lpszPassword);

int ExportToStream(SecureBlackboxStream* sCertStream, int iFormat, bool bExportKey, const QString& qsPassword);

Remarks

Use this method to save the certificate to a stream in one of the formats given below. Pass the encryption password via the Password parameter. Set ExportKey to true to save the private key together with the certificate.

Note that not all formats support encryption, and some (like PEM) only support partial encryption (key only). Keep this in mind when considering which format to choose for storing your certificates.

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

Generate Method (CertificateManager Class)

Generates a new certificate or certificate request.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Generate(int iKeyBits);

Unicode (Windows)
INT Generate(INT iKeyBits);

int secureblackbox_certificatemanager_generate(void* lpObj, int iKeyBits);

int Generate(int iKeyBits);

Remarks

Call this method to generate a new certificate based on the information provided in the Certificate and CACertificate properties:

If CACertificate is not set, a self-signed certificate or certificate request will be generated based on the information set up in Certificate object.

If Certificate contains a certificate, and CACertificate is set, a certificate signed by the CA certificate will be generated based on the information configured in the Certificate object. The resulting certificate will remain in Certificate

If Certificate contains a signed certificate request, and CACertificate is set, a certificate based on the certificate request and signed by the CA certificate will be generated.

KeyBits specifies the number of bits in the key to be generated. Note that this property is ignored in the case of request-based generation.

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

GenerateAsyncBegin Method (CertificateManager Class)

Initiates asynchronous (DC) certificate generation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GenerateAsyncBegin(int iKeyBits);

Unicode (Windows)
LPWSTR GenerateAsyncBegin(INT iKeyBits);

char* secureblackbox_certificatemanager_generateasyncbegin(void* lpObj, int iKeyBits);

QString GenerateAsyncBegin(int iKeyBits);

Remarks

Call this method to initiate an asynchronous certificate generation process. Pass the obtained async state to the DC server for signing. To finalize the generation, pass the async state received from the DC server to GenerateAsyncEnd.

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.

GenerateAsyncEnd Method (CertificateManager Class)

Completes asynchronous certificate generation.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT GenerateAsyncEnd(LPCWSTR lpszAsyncReply);

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

int GenerateAsyncEnd(const QString& qsAsyncReply);

Remarks

Call this method to finalize the asynchronous generation process and pass the async state received from DC server via AsyncReply parameter.

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

GenerateExternal Method (CertificateManager Class)

Generates a new certificate or request over an existing public key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GenerateExternal(const char* lpKeyBytes, int lenKeyBytes, const char* lpszKeyPassword);

Unicode (Windows)
INT GenerateExternal(LPCSTR lpKeyBytes, INT lenKeyBytes, LPCWSTR lpszKeyPassword);

int secureblackbox_certificatemanager_generateexternal(void* lpObj, const char* lpKeyBytes, int lenKeyBytes, const char* lpszKeyPassword);

int GenerateExternal(QByteArray qbaKeyBytes, const QString& qsKeyPassword);

Remarks

This method does exactly the same as Generate. The only difference is that instead of generating a new keypair, this method generates a new certificate over an existing keypair. See the rules of the Generate method to learn about parameter configurations for different generation scenarios.

Note: KeyBytes can contain a public or private key - as long as SecureBlackbox recognises the format, it will be processed.

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

GetExtensionData Method (CertificateManager Class)

Returns extension data.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetExtensionData(const char* lpszOID, int *lpSize = NULL);

Unicode (Windows)
LPSTR GetExtensionData(LPCWSTR lpszOID, LPINT lpSize = NULL);

char* secureblackbox_certificatemanager_getextensiondata(void* lpObj, const char* lpszOID, int *lpSize);

QByteArray GetExtensionData(const QString& qsOID);

Remarks

Use this method to retrieve extension data in ASN.1 encoded format. Use GetExtensionState to check the availability of the extension and establish its critical attribute.

Error Handling (C++)

This method returns a Byte Array value (with length lpSize); 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.

GetExtensionState Method (CertificateManager Class)

Returns certificate extension state.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetExtensionState(const char* lpszOID);

Unicode (Windows)
INT GetExtensionState(LPCWSTR lpszOID);

int secureblackbox_certificatemanager_getextensionstate(void* lpObj, const char* lpszOID);

int GetExtensionState(const QString& qsOID);

Remarks

Use this method to find out whether the extension is included in the certificate/CRL and check its critical attribute.

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.

ImportBytes Method (CertificateManager Class)

Imports a certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportBytes(const char* lpCertBytes, int lenCertBytes, const char* lpszPassword);

Unicode (Windows)
INT ImportBytes(LPCSTR lpCertBytes, INT lenCertBytes, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_importbytes(void* lpObj, const char* lpCertBytes, int lenCertBytes, const char* lpszPassword);

int ImportBytes(QByteArray qbaCertBytes, const QString& qsPassword);

Remarks

Use this method to load a certificate or certificate request from a byte array. Provide the password via the Password parameter. The Password parameter is optional. If it is omitted and it is later discovered that the key is password-encrypted, the PasswordNeeded event will be fired to request it. This method supports certificates in DER, PEM, PFX, and SPC formats.

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

ImportFromFile Method (CertificateManager Class)

Loads a certificate from a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromFile(const char* lpszPath, const char* lpszPassword);

Unicode (Windows)
INT ImportFromFile(LPCWSTR lpszPath, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_importfromfile(void* lpObj, const char* lpszPath, const char* lpszPassword);

int ImportFromFile(const QString& qsPath, const QString& qsPassword);

Remarks

This method can load certificates saved in one of the following formats: DER, PEM, PFX, SPC.

Use the Path parameter to provide a path to the certificate, and Password to specify the password. The Password parameter is optional. If it is omitted and it is later discovered that the certificate is password-encrypted, the PasswordNeeded event will be fired to request it.

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

ImportFromObject Method (CertificateManager Class)

Imports a certificate from a platform object.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromObject(int64 lSrcObj);

Unicode (Windows)
INT ImportFromObject(LONG64 lSrcObj);

int secureblackbox_certificatemanager_importfromobject(void* lpObj, int64 lSrcObj);

int ImportFromObject(qint64 lSrcObj);

Remarks

Use this method to import a certificate from a native platform object, such as X509Certificate2. Depending on the platform, the ObjHandle parameter can be one of the following:

• .NET: X509Certificate2
• Java: X509Certificate
• Windows-based platforms: PCCERT_CONTEXT

Note: in .NET edition, this method is currently only supported on Windows.

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

ImportFromStream Method (CertificateManager Class)

Loads a certificate from a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromStream(SecureBlackboxStream* sCertStream, const char* lpszPassword);

Unicode (Windows)
INT ImportFromStream(SecureBlackboxStream* sCertStream, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_importfromstream(void* lpObj, SecureBlackboxStream* sCertStream, const char* lpszPassword);

int ImportFromStream(SecureBlackboxStream* sCertStream, const QString& qsPassword);

Remarks

This method can load certificates saved in one of the following formats: DER, PEM, PFX, SPC.

Use the CertStream parameter to provide a stream containing the certificate data, and Password to specify the password. The Password parameter is optional. If it is omitted and it is later discovered that the certificate is password-encrypted, the PasswordNeeded event will be fired to request it.

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

ImportKey Method (CertificateManager Class)

Imports a private key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportKey(const char* lpKey, int lenKey, const char* lpszPassword);

Unicode (Windows)
INT ImportKey(LPCSTR lpKey, INT lenKey, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_importkey(void* lpObj, const char* lpKey, int lenKey, const char* lpszPassword);

int ImportKey(QByteArray qbaKey, const QString& qsPassword);

Remarks

Use this method to load a private key from a byte array. Provide the encryption password via the Password parameter. The Password parameter is optional. If it is omitted and it is later discovered that the key is password-encrypted, the PasswordNeeded event will be fired to request it. If there is an initialized certificate or certificate request object inside the manager, the loaded key gets associated with that object. This method supports keys in DER, PEM, PKCS#8, and PVK formats.

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

ImportKeyFromFile Method (CertificateManager Class)

Imports a private key from a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportKeyFromFile(const char* lpszPath, const char* lpszPassword);

Unicode (Windows)
INT ImportKeyFromFile(LPCWSTR lpszPath, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_importkeyfromfile(void* lpObj, const char* lpszPath, const char* lpszPassword);

int ImportKeyFromFile(const QString& qsPath, const QString& qsPassword);

Remarks

Use this method to load a private key from a file. Provide the encryption password via the Password parameter. The Password parameter is optional. If it is omitted and it is later discovered that the key is password-encrypted, the PasswordNeeded event will be fired to request it. If there is an initialized certificate or certificate request object inside the manager, the loaded key gets associated with that object. This method supports keys in DER, PEM, PKCS#8, and PVK formats.

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

ImportKeyFromStream Method (CertificateManager Class)

Imports a private key from a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportKeyFromStream(SecureBlackboxStream* sCertStream, const char* lpszPassword);

Unicode (Windows)
INT ImportKeyFromStream(SecureBlackboxStream* sCertStream, LPCWSTR lpszPassword);

int secureblackbox_certificatemanager_importkeyfromstream(void* lpObj, SecureBlackboxStream* sCertStream, const char* lpszPassword);

int ImportKeyFromStream(SecureBlackboxStream* sCertStream, const QString& qsPassword);

Remarks

Use this method to load a private key from a stream. Provide the encryption password via the Password parameter. The Password parameter is optional. If it is omitted and it is later discovered that the key is password-encrypted, the PasswordNeeded event will be fired to request it. If there is an initialized certificate or certificate request object inside the manager, the loaded key gets associated with that object. This method supports keys in DER, PEM, PKCS#8, and PVK formats.

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

ListExtensions Method (CertificateManager Class)

List extensions currently available in the certificate or CRL.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ListExtensions();

Unicode (Windows)
LPWSTR ListExtensions();

char* secureblackbox_certificatemanager_listextensions(void* lpObj);

QString ListExtensions();

Remarks

Use this method to list the extensions included in the certificate or CRL. The method returns a list of OIDs separated by newline characters.

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

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

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

SetExtensionData Method (CertificateManager Class)

Sets extension data.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT SetExtensionData(LPCWSTR lpszOID, LPCSTR lpValue, INT lenValue);

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

int SetExtensionData(const QString& qsOID, QByteArray qbaValue);

Remarks

Use this method to set extension data in encoded ASN.1 format. Use SetExtensionState to enable the extension or change its critical attribute.

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

SetExtensionState Method (CertificateManager Class)

Sets certificate extension state.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetExtensionState(const char* lpszOID, int iState);

Unicode (Windows)
INT SetExtensionState(LPCWSTR lpszOID, INT iState);

int secureblackbox_certificatemanager_setextensionstate(void* lpObj, const char* lpszOID, int iState);

int SetExtensionState(const QString& qsOID, int iState);

Remarks

Use this method to enable or disable the extension and set its critical attribute.

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

Renews the certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Update();

Unicode (Windows)
INT Update();

int secureblackbox_certificatemanager_update(void* lpObj);

int Update();

Remarks

This method renews a certificate by updating its validity period and re-signing the updated version.

Note that this operation expects both Certificate and CACertificate properties to be set.

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

Validate Method (CertificateManager Class)

Validates the certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Validate();

Unicode (Windows)
INT Validate();

int secureblackbox_certificatemanager_validate(void* lpObj);

int Validate();

Remarks

Use this method to validate the certificate contained in Certificate. If the certificate being validated is not self-signed, please provide the CA certificate via CACertificate property.

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.

Error Event (CertificateManager Class)

Information about errors during certificate loading, saving or validation.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_CERTIFICATEMANAGER_ERROR 1

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

class CertificateManagerErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

Reports exceptional conditions during certificate loading, exporting, or validation.

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

ExternalSign Event (CertificateManager Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_CERTIFICATEMANAGER_EXTERNALSIGN 2

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

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

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

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_CERTIFICATEMANAGER_NOTIFICATION 3

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

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

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

PasswordNeeded Event (CertificateManager Class)

This event is fired when a decryption password is needed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FirePasswordNeeded(CertificateManagerPasswordNeededEventParams *e);

typedef struct {
  char *Password;
  int Cancel;
  int reserved;
} CertificateManagerPasswordNeededEventParams;


Unicode (Windows)
virtual INT FirePasswordNeeded(CertificateManagerPasswordNeededEventParams *e);

typedef struct {
  LPWSTR Password;
  BOOL Cancel;
  INT reserved;
} CertificateManagerPasswordNeededEventParams;

#define EID_CERTIFICATEMANAGER_PASSWORDNEEDED 4

virtual INT SECUREBLACKBOX_CALL FirePasswordNeeded(LPSTR &lpszPassword, BOOL &bCancel);

class CertificateManagerPasswordNeededEventParams {
public:
  const QString &Password();
  void SetPassword(const QString &qsPassword);

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

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

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

// Or, subclass CertificateManager and override this emitter function.
virtual int FirePasswordNeeded(CertificateManagerPasswordNeededEventParams *e) {...}

Remarks

The class fires this event when a password is needed to decrypt a certificate or a private key.

In the handler of this event, assign the password to the Password parameter, or set Cancel to true to abort the operation.

Certificate Type

Encapsulates an individual X.509 certificate.

Syntax

SecureBlackboxCertificate (declared in secureblackbox.h)

Remarks

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

Fields

Constructors

Certificate()

ExternalCrypto Type

Specifies the parameters of external cryptographic calls.

Syntax

SecureBlackboxExternalCrypto (declared in secureblackbox.h)

Remarks

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

Fields

Constructors

ExternalCrypto()

SecureBlackboxStream Type

Syntax

SecureBlackboxStream (declared in secureblackbox.h)

Remarks

The CertificateManager class includes one or more API members that take a stream object as a parameter. To use such API members, create a concrete class that implements the SecureBlackboxStream interface and pass the CertificateManager class an instance of that concrete class.

When implementing the SecureBlackboxStream interface's properties and methods, they must behave as described below. If the concrete class's implementation does not behave as expected, undefined behavior may occur.

bool CanRead() { return true; }

bool CanSeek() { return true; }

bool CanWrite() { return true; }

int64 GetLength() = 0;

void Close() {}

int Flush() { return 0; }

int Read(void* buffer, int count) = 0;

int64 Seek(int64 offset, int seekOrigin) = 0;

int Write(const void* buffer, int count) = 0;

Config Settings (CertificateManager Class)

CertificateManager Config Settings

Base Config Settings

Trappable Errors (CertificateManager Class)

Error Handling (C++)

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

CertificateManager Errors