CryptoKeyManager Class

Properties   Methods   Events   Config Settings   Errors  

The CryptoKeyManager class provides a simple way to load, generate and manage generic cryptographic keys.

Syntax

CryptoKeyManager

Remarks

CryptoKeyManager allows you to load, save, generate, import, and export low-level cryptographic keys. Two examples of such keys are raw RSA keys stored in PKCS1 format or AES256 keys. CryptoKeyManager supports asymmetric, symmetric, and HMAC keys.

CryptoKeyManager is a typical companion for low-level cryptography classes, such as PublicKeyCrypto, SymmetricCrypto, and HashFunction. It can also be used to provide external key material to certificate objects, and to derive cryptographic keys from passwords.

Use ImportBytes or ImportFromFile method to load the key material from a buffer or file. Use ImportFromCert (and remember to assign the certificate object to the Certificate property before calling it) to import a key from an X.509 certificate. Once loaded, the key will be available in the Key property. // Loading an AES key and setting its IV CryptoKeyManager.ImportBytes(Key, kffDER, "AES256", "", "", ktSecret, ""); CryptoKeyManager.Key.IV = IV; // Loading an ECDSA private key from a file CryptoKeyManager.ImportFromFile("ec-secp256k1-priv-key.pem", kffAuto, "ECDSA", "NISTP256", "", ktSecret, ""); // Loading an ECDSA public key from a file CryptoKeyManager.ImportFromFile("ec-secp256k1-pub-key.pem", kffAuto, "ECDSA", "NISTP256", "", ktPublic, ""); // Importing a private key from a certificate object CertMgr.ImportFromFile("cert.pfx", "password"); CryptoKeyManager.Certificate = CertMgr.Certificate; CryptoKeyManager.ImportFromCert();

To generate a new key or keypair use Generate method. You can export the generated key using ExportBytes or ExportToFile method. You can attach the generated or loaded key to an external certificate object using the ExportToCert method. // Generating an EdDSA Curve25519 keypair CryptoKeyManager.Generate("EDDSA", "CURVE25519", "", 256); // Generating an ECDSA NIST P256 curve keypair CryptoKeyManager.Generate("ECDSA", "NISTP256", "", 256); // Generating an RSA 2048 bit keypair CryptoKeyManager.Generate("RSA", "", "", 2048); // Generating a symmetric AES256 key CryptoKeyManager.Generate("AES256", "", "", 256);

Use DeriveKey to derive a strong cryptographic key from a password using one of supported key derivation functions (KDFs): CryptoKeyManager.DerivationAlgorithm = "PKCS5"; CryptoKeyManager.HMACAlgorithm = "SHA256"; CryptoKeyManager.DeriveIterations = 10000; CryptoKeyManager.DeriveKey(256, "password", "hex:41424344"); Key = CryptoKeyManager.Key.Key;

CryptoKeyManager supports the majority of modern cryptographic algorithms:

• Asymmetric: RSA, ECDSA, EdDSA, ElGamal, DSS, Diffie-Hellman
• Symmetric: AES, Blowfish, Camellia, CAST5, ChaCha20, DES, 3DES-EDE, IDEA, RC2, RC4, Serpent, Twofish.
• KDFs: PKCS5, PBKDF2 (an alias to PKCS5), BCrypt, SCrypt, Argon2d, Argon2i, Argon2id.

See the "Supported Algorithms" section in the FAQ for the complete list.

Note: CryptoKeyManager can only work with one cryptographic key at a time. Use CryptoKeyStorage to access media containing more than one key.

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.

Certificate Property (CryptoKeyManager Class)

A container for the certificate object.

Syntax

• C++
• C
• Qt

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

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

int secureblackbox_cryptokeymanager_getcertca(void* lpObj);
int secureblackbox_cryptokeymanager_setcertca(void* lpObj, int bCertCA);

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

int secureblackbox_cryptokeymanager_getcertcerttype(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertcrldistributionpoints(void* lpObj);
int secureblackbox_cryptokeymanager_setcertcrldistributionpoints(void* lpObj, const char* lpszCertCRLDistributionPoints);

char* secureblackbox_cryptokeymanager_getcertcurve(void* lpObj);
int secureblackbox_cryptokeymanager_setcertcurve(void* lpObj, const char* lpszCertCurve);

char* secureblackbox_cryptokeymanager_getcertfingerprint(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertfriendlyname(void* lpObj);

int64 secureblackbox_cryptokeymanager_getcerthandle(void* lpObj);
int secureblackbox_cryptokeymanager_setcerthandle(void* lpObj, int64 lCertHandle);

char* secureblackbox_cryptokeymanager_getcerthashalgorithm(void* lpObj);
int secureblackbox_cryptokeymanager_setcerthashalgorithm(void* lpObj, const char* lpszCertHashAlgorithm);

char* secureblackbox_cryptokeymanager_getcertissuer(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertissuerrdn(void* lpObj);
int secureblackbox_cryptokeymanager_setcertissuerrdn(void* lpObj, const char* lpszCertIssuerRDN);

char* secureblackbox_cryptokeymanager_getcertkeyalgorithm(void* lpObj);
int secureblackbox_cryptokeymanager_setcertkeyalgorithm(void* lpObj, const char* lpszCertKeyAlgorithm);

int secureblackbox_cryptokeymanager_getcertkeybits(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertkeyfingerprint(void* lpObj);

int secureblackbox_cryptokeymanager_getcertkeyusage(void* lpObj);
int secureblackbox_cryptokeymanager_setcertkeyusage(void* lpObj, int iCertKeyUsage);

int secureblackbox_cryptokeymanager_getcertkeyvalid(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertocsplocations(void* lpObj);
int secureblackbox_cryptokeymanager_setcertocsplocations(void* lpObj, const char* lpszCertOCSPLocations);

int secureblackbox_cryptokeymanager_getcertocspnocheck(void* lpObj);
int secureblackbox_cryptokeymanager_setcertocspnocheck(void* lpObj, int bCertOCSPNoCheck);

int secureblackbox_cryptokeymanager_getcertorigin(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertpolicyids(void* lpObj);
int secureblackbox_cryptokeymanager_setcertpolicyids(void* lpObj, const char* lpszCertPolicyIDs);

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

int secureblackbox_cryptokeymanager_getcertprivatekeyexists(void* lpObj);

int secureblackbox_cryptokeymanager_getcertprivatekeyextractable(void* lpObj);

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

int secureblackbox_cryptokeymanager_getcertqualified(void* lpObj);

int secureblackbox_cryptokeymanager_getcertqualifiedstatements(void* lpObj);
int secureblackbox_cryptokeymanager_setcertqualifiedstatements(void* lpObj, int iCertQualifiedStatements);

char* secureblackbox_cryptokeymanager_getcertqualifiers(void* lpObj);

int secureblackbox_cryptokeymanager_getcertselfsigned(void* lpObj);

int secureblackbox_cryptokeymanager_getcertserialnumber(void* lpObj, char** lpCertSerialNumber, int* lenCertSerialNumber);
int secureblackbox_cryptokeymanager_setcertserialnumber(void* lpObj, const char* lpCertSerialNumber, int lenCertSerialNumber);

char* secureblackbox_cryptokeymanager_getcertsigalgorithm(void* lpObj);

int secureblackbox_cryptokeymanager_getcertsource(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertsubject(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertsubjectalternativename(void* lpObj);
int secureblackbox_cryptokeymanager_setcertsubjectalternativename(void* lpObj, const char* lpszCertSubjectAlternativeName);

int secureblackbox_cryptokeymanager_getcertsubjectkeyid(void* lpObj, char** lpCertSubjectKeyID, int* lenCertSubjectKeyID);
int secureblackbox_cryptokeymanager_setcertsubjectkeyid(void* lpObj, const char* lpCertSubjectKeyID, int lenCertSubjectKeyID);

char* secureblackbox_cryptokeymanager_getcertsubjectrdn(void* lpObj);
int secureblackbox_cryptokeymanager_setcertsubjectrdn(void* lpObj, const char* lpszCertSubjectRDN);

int secureblackbox_cryptokeymanager_getcertvalid(void* lpObj);

char* secureblackbox_cryptokeymanager_getcertvalidfrom(void* lpObj);
int secureblackbox_cryptokeymanager_setcertvalidfrom(void* lpObj, const char* lpszCertValidFrom);

char* secureblackbox_cryptokeymanager_getcertvalidto(void* lpObj);
int secureblackbox_cryptokeymanager_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 an import or export action is to be performed.

This property is not available at design time.

Data Type

SecureBlackboxCertificate

DerivationAlgorithm Property (CryptoKeyManager Class)

Specifies the algorithm to use for key derivation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDerivationAlgorithm();
int SetDerivationAlgorithm(const char* lpszDerivationAlgorithm);

Unicode (Windows)
LPWSTR GetDerivationAlgorithm();
INT SetDerivationAlgorithm(LPCWSTR lpszDerivationAlgorithm);

char* secureblackbox_cryptokeymanager_getderivationalgorithm(void* lpObj);
int secureblackbox_cryptokeymanager_setderivationalgorithm(void* lpObj, const char* lpszDerivationAlgorithm);

QString GetDerivationAlgorithm();
int SetDerivationAlgorithm(QString qsDerivationAlgorithm);

Default Value

"PKCS5"

Remarks

Use this property to specify the key derivation algorithm to use.

Class supports the following algorithms: PKCS5, PBKDF2 (an alias to PKCS5), BCrypt, SCrypt, Argon2d, Argon2i, Argon2id.

Data Type

String

DeriveIterations Property (CryptoKeyManager Class)

Specifies the number of iterations to use as part of key derivation routine.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDeriveIterations();
int SetDeriveIterations(int iDeriveIterations);

Unicode (Windows)
INT GetDeriveIterations();
INT SetDeriveIterations(INT iDeriveIterations);

int secureblackbox_cryptokeymanager_getderiveiterations(void* lpObj);
int secureblackbox_cryptokeymanager_setderiveiterations(void* lpObj, int iDeriveIterations);

int GetDeriveIterations();
int SetDeriveIterations(int iDeriveIterations);

Default Value

2048

Remarks

Use this property to adjust the number of hash algorithm iterations to employ as part of key derivation function.

Data Type

Integer

FIPSMode Property (CryptoKeyManager 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_cryptokeymanager_getfipsmode(void* lpObj);
int secureblackbox_cryptokeymanager_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

HMACAlgorithm Property (CryptoKeyManager Class)

Specifies the HMAC algorithm to use with the key derivation algorithm.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetHMACAlgorithm();
int SetHMACAlgorithm(const char* lpszHMACAlgorithm);

Unicode (Windows)
LPWSTR GetHMACAlgorithm();
INT SetHMACAlgorithm(LPCWSTR lpszHMACAlgorithm);

char* secureblackbox_cryptokeymanager_gethmacalgorithm(void* lpObj);
int secureblackbox_cryptokeymanager_sethmacalgorithm(void* lpObj, const char* lpszHMACAlgorithm);

QString GetHMACAlgorithm();
int SetHMACAlgorithm(QString qsHMACAlgorithm);

Default Value

"SHA1"

Remarks

Use this property to specify the HMAC algorithm to use with the chosen key derivation algorithm.

Class supports the following algorithms: SHA1, SHA224, SHA256, SHA384, SHA512, MD5, RIPEMD, HMAC.

Data Type

String

Key Property (CryptoKeyManager Class)

The key object that the manager is currently working with.

Syntax

• C++
• C
• Qt

SecureBlackboxCryptoKey* GetKey();
int SetKey(SecureBlackboxCryptoKey* val);

char* secureblackbox_cryptokeymanager_getkeyalgorithm(void* lpObj);
int secureblackbox_cryptokeymanager_setkeyalgorithm(void* lpObj, const char* lpszKeyAlgorithm);

int secureblackbox_cryptokeymanager_getkeybits(void* lpObj);

char* secureblackbox_cryptokeymanager_getkeycurve(void* lpObj);
int secureblackbox_cryptokeymanager_setkeycurve(void* lpObj, const char* lpszKeyCurve);

int secureblackbox_cryptokeymanager_getkeyexportable(void* lpObj);

char* secureblackbox_cryptokeymanager_getkeyfingerprint(void* lpObj);

int64 secureblackbox_cryptokeymanager_getkeyhandle(void* lpObj);
int secureblackbox_cryptokeymanager_setkeyhandle(void* lpObj, int64 lKeyHandle);

int secureblackbox_cryptokeymanager_getkeyid(void* lpObj, char** lpKeyID, int* lenKeyID);
int secureblackbox_cryptokeymanager_setkeyid(void* lpObj, const char* lpKeyID, int lenKeyID);

int secureblackbox_cryptokeymanager_getkeyiv(void* lpObj, char** lpKeyIV, int* lenKeyIV);
int secureblackbox_cryptokeymanager_setkeyiv(void* lpObj, const char* lpKeyIV, int lenKeyIV);

int secureblackbox_cryptokeymanager_getkeykey(void* lpObj, char** lpKeyKey, int* lenKeyKey);

int secureblackbox_cryptokeymanager_getkeynonce(void* lpObj, char** lpKeyNonce, int* lenKeyNonce);
int secureblackbox_cryptokeymanager_setkeynonce(void* lpObj, const char* lpKeyNonce, int lenKeyNonce);

int secureblackbox_cryptokeymanager_getkeyprivate(void* lpObj);

int secureblackbox_cryptokeymanager_getkeypublic(void* lpObj);

int secureblackbox_cryptokeymanager_getkeysubject(void* lpObj, char** lpKeySubject, int* lenKeySubject);
int secureblackbox_cryptokeymanager_setkeysubject(void* lpObj, const char* lpKeySubject, int lenKeySubject);

int secureblackbox_cryptokeymanager_getkeysymmetric(void* lpObj);

int secureblackbox_cryptokeymanager_getkeyvalid(void* lpObj);

QString GetKeyAlgorithm();
int SetKeyAlgorithm(QString qsKeyAlgorithm);

int GetKeyBits();

QString GetKeyCurve();
int SetKeyCurve(QString qsKeyCurve);

bool GetKeyExportable();

QString GetKeyFingerprint();

qint64 GetKeyHandle();
int SetKeyHandle(qint64 lKeyHandle);

QByteArray GetKeyID();
int SetKeyID(QByteArray qbaKeyID);

QByteArray GetKeyIV();
int SetKeyIV(QByteArray qbaKeyIV);

QByteArray GetKeyKey();

QByteArray GetKeyNonce();
int SetKeyNonce(QByteArray qbaKeyNonce);

bool GetKeyPrivate();

bool GetKeyPublic();

QByteArray GetKeySubject();
int SetKeySubject(QByteArray qbaKeySubject);

bool GetKeySymmetric();

bool GetKeyValid();

Remarks

Use this property to pass a key to the manager (for example, for serialization), or to obtain a key from the manager (e.g., after generating or importing it).

This property is not available at design time.

Data Type

SecureBlackboxCryptoKey

Config Method (CryptoKeyManager 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_cryptokeymanager_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 (CryptoKeyManager Class)

Creates a template for a new keypair.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateNew();

Unicode (Windows)
INT CreateNew();

int secureblackbox_cryptokeymanager_createnew(void* lpObj);

int CreateNew();

Remarks

This method pre-generates a template for a new key.

Adjust the properties of the Key object and call Generate to complete the 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.)

DeriveKey Method (CryptoKeyManager Class)

Generates a strong cryptographic key from a password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeriveKey(int iKeyBits, const char* lpszPassword, const char* lpszSalt);

Unicode (Windows)
INT DeriveKey(INT iKeyBits, LPCWSTR lpszPassword, LPCWSTR lpszSalt);

int secureblackbox_cryptokeymanager_derivekey(void* lpObj, int iKeyBits, const char* lpszPassword, const char* lpszSalt);

int DeriveKey(int iKeyBits, const QString& qsPassword, const QString& qsSalt);

Remarks

Use this method to generate a cryptographically strong key of a needed length from a password.

This method uses the key derivation function specified in DerivationAlgorithm, the HMAC algorithm provided in HMACAlgorithm, over DeriveIterations iterations, to generate a cryptographic key of the needed length from a password and salt.

Salt is expected to contain a human-readable text string. To provide a binary salt, use the hex prefix with base16-encoded salt value: hex:01AB8F20004F10FE. CryptoKeyManager.DerivationAlgorithm = "PKCS5"; CryptoKeyManager.HMACAlgorithm = "SHA256"; CryptoKeyManager.DeriveIterations = 10000; CryptoKeyManager.DeriveKey(256, "password", "hex:41424344"); Key = CryptoKeyManager.Key.Key;

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

Exports the key to a byte array.

Syntax

• C++
• C
• Qt

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

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

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

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

Remarks

Use this method to save the Key (both the public and secret parts) to a byte array.

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.

ExportToCert Method (CryptoKeyManager Class)

Exports the key to a certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportToCert();

Unicode (Windows)
INT ExportToCert();

int secureblackbox_cryptokeymanager_exporttocert(void* lpObj);

int ExportToCert();

Remarks

Use this method to save the Key (both the public and secret parts) to the certificate specified in Certificate.

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

Exports the key to a file.

Syntax

• C++
• C
• Qt

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

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

int secureblackbox_cryptokeymanager_exporttofile(void* lpObj, const char* lpszFileName, int iFormat, int iKeyType, const char* lpszPassword);

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

Remarks

Use this method to save the Key (both the public and secret parts) to the file passed via the FileName parameter.

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

Exports the key to a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportToStream(SecureBlackboxStream* sStream, int iFormat, int iKeyType, const char* lpszPassword);

Unicode (Windows)
INT ExportToStream(SecureBlackboxStream* sStream, INT iFormat, INT iKeyType, LPCWSTR lpszPassword);

int secureblackbox_cryptokeymanager_exporttostream(void* lpObj, SecureBlackboxStream* sStream, int iFormat, int iKeyType, const char* lpszPassword);

int ExportToStream(SecureBlackboxStream* sStream, int iFormat, int iKeyType, const QString& qsPassword);

Remarks

Use this method to save the Key (both the public and secret parts) to a stream pointed by the Stream parameter.

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

Generates a new crypto key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Generate(const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyBits);

Unicode (Windows)
INT Generate(LPCWSTR lpszKeyAlgorithm, LPCWSTR lpszScheme, LPCWSTR lpszSchemeParams, INT iKeyBits);

int secureblackbox_cryptokeymanager_generate(void* lpObj, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyBits);

int Generate(const QString& qsKeyAlgorithm, const QString& qsScheme, const QString& qsSchemeParams, int iKeyBits);

Remarks

Call this method to generate a new key or keypair with the desired KeyAlgorithm and KeyBits of length.

The generated key will be populated in the Key property. // Generating an EdDSA Curve25519 keypair CryptoKeyManager.Generate("EDDSA", "CURVE25519", "", 256); // Generating an ECDSA NIST P256 curve keypair CryptoKeyManager.Generate("ECDSA", "NISTP256", "", 256); // Generating an RSA 2048 bit keypair CryptoKeyManager.Generate("RSA", "", "", 2048); // Generating a symmetric AES256 key CryptoKeyManager.Generate("AES256", "", "", 256);

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

GetKeyParam Method (CryptoKeyManager Class)

Returns a binary algorithm-specific key parameter.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetKeyParam(const char* lpszName, int *lpSize = NULL);

Unicode (Windows)
LPSTR GetKeyParam(LPCWSTR lpszName, LPINT lpSize = NULL);

char* secureblackbox_cryptokeymanager_getkeyparam(void* lpObj, const char* lpszName, int *lpSize);

QByteArray GetKeyParam(const QString& qsName);

Remarks

Use this method to retrieve a binary algorithm-specific key parameter.

The following parameters are currently supported:

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.

GetKeyParamStr Method (CryptoKeyManager Class)

Returns a string algorithm-specific key parameter.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetKeyParamStr(const char* lpszName);

Unicode (Windows)
LPWSTR GetKeyParamStr(LPCWSTR lpszName);

char* secureblackbox_cryptokeymanager_getkeyparamstr(void* lpObj, const char* lpszName);

QString GetKeyParamStr(const QString& qsName);

Remarks

Use this method to get an human-readable algorithm-specific key parameter.

The following parameters are currently supported:

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.

ImportBytes Method (CryptoKeyManager Class)

Loads a key from a byte array.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportBytes(const char* lpValue, int lenValue, int iFormat, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyType, const char* lpszPassword);

Unicode (Windows)
INT ImportBytes(LPCSTR lpValue, INT lenValue, INT iFormat, LPCWSTR lpszKeyAlgorithm, LPCWSTR lpszScheme, LPCWSTR lpszSchemeParams, INT iKeyType, LPCWSTR lpszPassword);

int secureblackbox_cryptokeymanager_importbytes(void* lpObj, const char* lpValue, int lenValue, int iFormat, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyType, const char* lpszPassword);

int ImportBytes(QByteArray qbaValue, int iFormat, const QString& qsKeyAlgorithm, const QString& qsScheme, const QString& qsSchemeParams, int iKeyType, const QString& qsPassword);

Remarks

Use this method to load a key, either public or secret, from a byte array.

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

ImportFromCert Method (CryptoKeyManager Class)

Loads a key from a certificate.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromCert();

Unicode (Windows)
INT ImportFromCert();

int secureblackbox_cryptokeymanager_importfromcert(void* lpObj);

int ImportFromCert();

Remarks

Use this method to load a key, either public or secret, from a certificate.

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

Loads a key from a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromFile(const char* lpszFileName, int iFormat, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyType, const char* lpszPassword);

Unicode (Windows)
INT ImportFromFile(LPCWSTR lpszFileName, INT iFormat, LPCWSTR lpszKeyAlgorithm, LPCWSTR lpszScheme, LPCWSTR lpszSchemeParams, INT iKeyType, LPCWSTR lpszPassword);

int secureblackbox_cryptokeymanager_importfromfile(void* lpObj, const char* lpszFileName, int iFormat, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyType, const char* lpszPassword);

int ImportFromFile(const QString& qsFileName, int iFormat, const QString& qsKeyAlgorithm, const QString& qsScheme, const QString& qsSchemeParams, int iKeyType, const QString& qsPassword);

Remarks

Use this method to load a key, either public or secret, from a file.

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

Loads a key from a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromStream(SecureBlackboxStream* sStream, int iFormat, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyType, const char* lpszPassword);

Unicode (Windows)
INT ImportFromStream(SecureBlackboxStream* sStream, INT iFormat, LPCWSTR lpszKeyAlgorithm, LPCWSTR lpszScheme, LPCWSTR lpszSchemeParams, INT iKeyType, LPCWSTR lpszPassword);

int secureblackbox_cryptokeymanager_importfromstream(void* lpObj, SecureBlackboxStream* sStream, int iFormat, const char* lpszKeyAlgorithm, const char* lpszScheme, const char* lpszSchemeParams, int iKeyType, const char* lpszPassword);

int ImportFromStream(SecureBlackboxStream* sStream, int iFormat, const QString& qsKeyAlgorithm, const QString& qsScheme, const QString& qsSchemeParams, int iKeyType, const QString& qsPassword);

Remarks

Use this method to load a key, either public or secret, from a stream.

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

Reset Method (CryptoKeyManager Class)

Resets the class settings.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

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

SetKeyParam Method (CryptoKeyManager Class)

Sets an algorithm-specific key parameter.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetKeyParam(const char* lpszName, const char* lpValue, int lenValue);

Unicode (Windows)
INT SetKeyParam(LPCWSTR lpszName, LPCSTR lpValue, INT lenValue);

int secureblackbox_cryptokeymanager_setkeyparam(void* lpObj, const char* lpszName, const char* lpValue, int lenValue);

int SetKeyParam(const QString& qsName, QByteArray qbaValue);

Remarks

Use this method to set an algorithm-specific key parameter.

The following parameters are currently supported:

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

SetKeyParamStr Method (CryptoKeyManager Class)

Sets a string-based algorithm-specific key parameter.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetKeyParamStr(const char* lpszName, const char* lpszValueStr);

Unicode (Windows)
INT SetKeyParamStr(LPCWSTR lpszName, LPCWSTR lpszValueStr);

int secureblackbox_cryptokeymanager_setkeyparamstr(void* lpObj, const char* lpszName, const char* lpszValueStr);

int SetKeyParamStr(const QString& qsName, const QString& qsValueStr);

Remarks

Use this method to set a string-based algorithm-specific key parameter.

Error Handling (C++)

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

Error Event (CryptoKeyManager Class)

Informs about an error during an operation.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_CRYPTOKEYMANAGER_ERROR 1

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

class CryptoKeyManagerErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

The event is fired when an error happens in the middle of the class's work.

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

Notification Event (CryptoKeyManager Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_CRYPTOKEYMANAGER_NOTIFICATION 2

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

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

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

This event is fired when a decryption password is needed.

Syntax

• C++
• C
• Qt

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

typedef struct {
  const char *NeededFor;
  char *Password;
  int Cancel;
  int reserved;
} CryptoKeyManagerPasswordNeededEventParams;


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

typedef struct {
  LPCWSTR NeededFor;
  LPWSTR Password;
  BOOL Cancel;
  INT reserved;
} CryptoKeyManagerPasswordNeededEventParams;

#define EID_CRYPTOKEYMANAGER_PASSWORDNEEDED 3

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

class CryptoKeyManagerPasswordNeededEventParams {
public:
  const QString &NeededFor();

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

// Or, subclass CryptoKeyManager and override this emitter function.
virtual int FirePasswordNeeded(CryptoKeyManagerPasswordNeededEventParams *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.

The NeededFor parameter identifies the certificate for which the password is requested.

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

CryptoKey Type

This container represents a cryptographic key.

Syntax

SecureBlackboxCryptoKey (declared in secureblackbox.h)

Remarks

This type is a universal placeholder for cryptographic keys.

Fields

Constructors

CryptoKey()

SecureBlackboxStream Type

Syntax

SecureBlackboxStream (declared in secureblackbox.h)

Remarks

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

CryptoKeyManager Config Settings

Base Config Settings

Trappable Errors (CryptoKeyManager 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.

CryptoKeyManager Errors