PGPKeyManager Class

Properties   Methods   Events   Config Settings   Errors  

The PGPKeyManager class manages PGP keys.

Syntax

PGPKeyManager

Remarks

PGPKeyManager allows you to load, save, generate, import, and export PGP keys.

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.

Key Property (PGPKeyManager Class)

The key to manipulate on.

Syntax

• C++
• C
• Qt

SecureBlackboxPGPKey* GetKey();

int secureblackbox_pgpkeymanager_getkeybitsinkey(void* lpObj);

char* secureblackbox_pgpkeymanager_getkeycurve(void* lpObj);

char* secureblackbox_pgpkeymanager_getkeyencryptionalgorithm(void* lpObj);

int64 secureblackbox_pgpkeymanager_getkeyhandle(void* lpObj);

char* secureblackbox_pgpkeymanager_getkeypassphrase(void* lpObj);

int secureblackbox_pgpkeymanager_getkeyprotection(void* lpObj);

char* secureblackbox_pgpkeymanager_getkeypublickeyalgorithm(void* lpObj);

int secureblackbox_pgpkeymanager_getkeyqbits(void* lpObj);

char* secureblackbox_pgpkeymanager_getkeyusername(void* lpObj);

int GetKeyBitsInKey();

QString GetKeyCurve();

QString GetKeyEncryptionAlgorithm();

qint64 GetKeyHandle();

QString GetKeyPassphrase();

int GetKeyProtection();

QString GetKeyPublicKeyAlgorithm();

int GetKeyQBits();

QString GetKeyUsername();

Remarks

Use this property to specify the key to perform operations on.

This property is read-only.

Data Type

SecureBlackboxPGPKey

PinnedKey Property (PGPKeyManager Class)

A PGP key that is being manipulated on.

Syntax

• C++
• C
• Qt

SecureBlackboxPGPKey* GetPinnedKey();
int SetPinnedKey(SecureBlackboxPGPKey* val);

int64 secureblackbox_pgpkeymanager_getpinnedkeyhandle(void* lpObj);
int secureblackbox_pgpkeymanager_setpinnedkeyhandle(void* lpObj, int64 lPinnedKeyHandle);

qint64 GetPinnedKeyHandle();
int SetPinnedKeyHandle(qint64 lPinnedKeyHandle);

Remarks

Use this property to specify a key to perform operations on, such as adding.

This property is not available at design time.

Data Type

SecureBlackboxPGPKey

Signatures Property (PGPKeyManager Class)

Signatures available in the key.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxPGPSignature>* GetSignatures();

int secureblackbox_pgpkeymanager_getsignaturecount(void* lpObj);

int secureblackbox_pgpkeymanager_getsignaturecertificationtype(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturecreationtime(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignatureexpirationtime(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignatureexportable(void* lpObj, int signatureindex);

int64 secureblackbox_pgpkeymanager_getsignaturehandle(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturehashalgorithm(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturehashmark(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturekeyexpirationtime(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturekeyflags(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturelegacyformat(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturepolicyurl(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturepreferredalgorithms(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignatureprimaryuserid(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturereasonforrevocation(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturerevocable(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturerevocation(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturesignatureclass(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturesignerkeyid(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturesigneruserid(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturestrictlyvalid(void* lpObj, int signatureindex);

char* secureblackbox_pgpkeymanager_getsignaturetarget(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturetextsignature(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturetrustamount(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturetrustlevel(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturevalidated(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignaturevalidity(void* lpObj, int signatureindex);

int secureblackbox_pgpkeymanager_getsignatureversion(void* lpObj, int signatureindex);

int GetSignatureCount();

int GetSignatureCertificationType(int iSignatureIndex);

QString GetSignatureCreationTime(int iSignatureIndex);

int GetSignatureExpirationTime(int iSignatureIndex);

bool GetSignatureExportable(int iSignatureIndex);

qint64 GetSignatureHandle(int iSignatureIndex);

QString GetSignatureHashAlgorithm(int iSignatureIndex);

int GetSignatureHashMark(int iSignatureIndex);

int GetSignatureKeyExpirationTime(int iSignatureIndex);

int GetSignatureKeyFlags(int iSignatureIndex);

bool GetSignatureLegacyFormat(int iSignatureIndex);

QString GetSignaturePolicyURL(int iSignatureIndex);

QString GetSignaturePreferredAlgorithms(int iSignatureIndex);

bool GetSignaturePrimaryUserID(int iSignatureIndex);

QString GetSignatureReasonForRevocation(int iSignatureIndex);

bool GetSignatureRevocable(int iSignatureIndex);

bool GetSignatureRevocation(int iSignatureIndex);

int GetSignatureSignatureClass(int iSignatureIndex);

QString GetSignatureSignerKeyID(int iSignatureIndex);

QString GetSignatureSignerUserID(int iSignatureIndex);

bool GetSignatureStrictlyValid(int iSignatureIndex);

QString GetSignatureTarget(int iSignatureIndex);

bool GetSignatureTextSignature(int iSignatureIndex);

int GetSignatureTrustAmount(int iSignatureIndex);

int GetSignatureTrustLevel(int iSignatureIndex);

bool GetSignatureValidated(int iSignatureIndex);

int GetSignatureValidity(int iSignatureIndex);

int GetSignatureVersion(int iSignatureIndex);

Remarks

This property populates a collection of all signatures contained in the key.

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

Data Type

SecureBlackboxPGPSignature

SigningKey Property (PGPKeyManager Class)

A PGP key that is being manipulated on.

Syntax

• C++
• C
• Qt

SecureBlackboxPGPKey* GetSigningKey();
int SetSigningKey(SecureBlackboxPGPKey* val);

int64 secureblackbox_pgpkeymanager_getsigningkeyhandle(void* lpObj);
int secureblackbox_pgpkeymanager_setsigningkeyhandle(void* lpObj, int64 lSigningKeyHandle);

qint64 GetSigningKeyHandle();
int SetSigningKeyHandle(qint64 lSigningKeyHandle);

Remarks

Use this property to specify a key to perform operations on, such as adding.

This property is not available at design time.

Data Type

SecureBlackboxPGPKey

Subkeys Property (PGPKeyManager Class)

PGP subkeys available in the key.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxPGPKey>* GetSubkeys();

int secureblackbox_pgpkeymanager_getsubkeycount(void* lpObj);

int secureblackbox_pgpkeymanager_getsubkeybitsinkey(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeycanencrypt(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeycansign(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeycurve(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyenabled(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeyencryptionalgorithm(void* lpObj, int subkeyindex);

int64 secureblackbox_pgpkeymanager_getsubkeyhandle(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyispublic(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyissecret(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyissubkey(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeykeyfp(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeykeyid(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeypassphrase(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeypassphrasevalid(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeyprimarykeyid(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyprotection(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeypublickeyalgorithm(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyqbits(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeytimestamp(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeyusername(void* lpObj, int subkeyindex);

char* secureblackbox_pgpkeymanager_getsubkeyvalidto(void* lpObj, int subkeyindex);

int secureblackbox_pgpkeymanager_getsubkeyversion(void* lpObj, int subkeyindex);

int GetSubkeyCount();

int GetSubkeyBitsInKey(int iSubkeyIndex);

bool GetSubkeyCanEncrypt(int iSubkeyIndex);

bool GetSubkeyCanSign(int iSubkeyIndex);

QString GetSubkeyCurve(int iSubkeyIndex);

bool GetSubkeyEnabled(int iSubkeyIndex);

QString GetSubkeyEncryptionAlgorithm(int iSubkeyIndex);

qint64 GetSubkeyHandle(int iSubkeyIndex);

bool GetSubkeyIsPublic(int iSubkeyIndex);

bool GetSubkeyIsSecret(int iSubkeyIndex);

bool GetSubkeyIsSubkey(int iSubkeyIndex);

QString GetSubkeyKeyFP(int iSubkeyIndex);

QString GetSubkeyKeyID(int iSubkeyIndex);

QString GetSubkeyPassphrase(int iSubkeyIndex);

bool GetSubkeyPassphraseValid(int iSubkeyIndex);

QString GetSubkeyPrimaryKeyID(int iSubkeyIndex);

int GetSubkeyProtection(int iSubkeyIndex);

QString GetSubkeyPublicKeyAlgorithm(int iSubkeyIndex);

int GetSubkeyQBits(int iSubkeyIndex);

QString GetSubkeyTimestamp(int iSubkeyIndex);

QString GetSubkeyUsername(int iSubkeyIndex);

QString GetSubkeyValidTo(int iSubkeyIndex);

int GetSubkeyVersion(int iSubkeyIndex);

Remarks

This property populates a collection of all subkeys contained in the key.

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

Data Type

SecureBlackboxPGPKey

Users Property (PGPKeyManager Class)

Users available in the key.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxPGPUser>* GetUsers();

int secureblackbox_pgpkeymanager_getusercount(void* lpObj);

int64 secureblackbox_pgpkeymanager_getuserhandle(void* lpObj, int userindex);

char* secureblackbox_pgpkeymanager_getuserusername(void* lpObj, int userindex);

int GetUserCount();

qint64 GetUserHandle(int iUserIndex);

QString GetUserUsername(int iUserIndex);

Remarks

This property populates a collection of all users contained in the key.

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

Data Type

SecureBlackboxPGPUser

ChangePassphrase Method (PGPKeyManager Class)

Changes the password of the secret key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ChangePassphrase(const char* lpszOldPassphrase, const char* lpszNewPassphrase);

Unicode (Windows)
INT ChangePassphrase(LPCWSTR lpszOldPassphrase, LPCWSTR lpszNewPassphrase);

int secureblackbox_pgpkeymanager_changepassphrase(void* lpObj, const char* lpszOldPassphrase, const char* lpszNewPassphrase);

int ChangePassphrase(const QString& qsOldPassphrase, const QString& qsNewPassphrase);

Remarks

Call this method to change the password that protects the secret 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.)

ChangeProtection Method (PGPKeyManager Class)

Changes the protection level of the secret key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ChangeProtection(const char* lpszOldPassphrase, const char* lpszNewPassphrase, int iProtType, const char* lpszEncAlgorithm, const char* lpszHashAlgorithm);

Unicode (Windows)
INT ChangeProtection(LPCWSTR lpszOldPassphrase, LPCWSTR lpszNewPassphrase, INT iProtType, LPCWSTR lpszEncAlgorithm, LPCWSTR lpszHashAlgorithm);

int secureblackbox_pgpkeymanager_changeprotection(void* lpObj, const char* lpszOldPassphrase, const char* lpszNewPassphrase, int iProtType, const char* lpszEncAlgorithm, const char* lpszHashAlgorithm);

int ChangeProtection(const QString& qsOldPassphrase, const QString& qsNewPassphrase, int iProtType, const QString& qsEncAlgorithm, const QString& qsHashAlgorithm);

Remarks

Use this method to change the protection level of the Key.

OldPassphrase specifies the current password to decrypt the key, NewPassphrase is the new password for the key, ProtType is the new protection type (see for more details), EncAlgorithm is the key encryption algorithm, and

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

CheckPassphrase Method (PGPKeyManager Class)

Checks if the password matches the secret key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool CheckPassphrase(const char* lpszPassphrase);

Unicode (Windows)
INT CheckPassphrase(LPCWSTR lpszPassphrase);

bool secureblackbox_pgpkeymanager_checkpassphrase(void* lpObj, const char* lpszPassphrase);

bool CheckPassphrase(const QString& qsPassphrase);

Remarks

Use this method to check if a password can decrypt the Key.

Error Handling (C++)

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

Config Method (PGPKeyManager Class)

This method 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_pgpkeymanager_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.

CreateKey Method (PGPKeyManager Class)

Generates a new key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateKey(int iVersion, const char* lpszAlgorithm, int iBits, const char* lpszValidTo, const char* lpszPassword);

Unicode (Windows)
INT CreateKey(INT iVersion, LPCWSTR lpszAlgorithm, INT iBits, LPCWSTR lpszValidTo, LPCWSTR lpszPassword);

int secureblackbox_pgpkeymanager_createkey(void* lpObj, int iVersion, const char* lpszAlgorithm, int iBits, const char* lpszValidTo, const char* lpszPassword);

int CreateKey(int iVersion, const QString& qsAlgorithm, int iBits, const QString& qsValidTo, const QString& qsPassword);

Remarks

ToDo

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

CreateSubkey Method (PGPKeyManager Class)

Generates a new subkey.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateSubkey(const char* lpszAlgorithm, int iBits, const char* lpszValidTo, const char* lpszPassword);

Unicode (Windows)
INT CreateSubkey(LPCWSTR lpszAlgorithm, INT iBits, LPCWSTR lpszValidTo, LPCWSTR lpszPassword);

int secureblackbox_pgpkeymanager_createsubkey(void* lpObj, const char* lpszAlgorithm, int iBits, const char* lpszValidTo, const char* lpszPassword);

int CreateSubkey(const QString& qsAlgorithm, int iBits, const QString& qsValidTo, const QString& qsPassword);

Remarks

ToDo

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

CreateUser Method (PGPKeyManager Class)

Generates a new user.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateUser(const char* lpszUsername);

Unicode (Windows)
INT CreateUser(LPCWSTR lpszUsername);

int secureblackbox_pgpkeymanager_createuser(void* lpObj, const char* lpszUsername);

int CreateUser(const QString& qsUsername);

Remarks

ToDo

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 (PGPKeyManager 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_pgpkeymanager_doaction(void* lpObj, const char* lpszActionID, const char* lpszActionParams);

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

Remarks

DoAction is a generic method available in every class. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insencitive) of the action is provided in the ActionID parameter.

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

Error Handling (C++)

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

ExportBytes Method (PGPKeyManager Class)

Serializes the key to a byte array.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ExportBytes(int bSecret, int *lpSize = NULL);

Unicode (Windows)
LPSTR ExportBytes(BOOL bSecret, LPINT lpSize = NULL);

char* secureblackbox_pgpkeymanager_exportbytes(void* lpObj, int bSecret, int *lpSize);

QByteArray ExportBytes(bool bSecret);

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.

ExportToFile Method (PGPKeyManager Class)

Exports the key to a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportToFile(const char* lpszKeyFile, int bSecret);

Unicode (Windows)
INT ExportToFile(LPCWSTR lpszKeyFile, BOOL bSecret);

int secureblackbox_pgpkeymanager_exporttofile(void* lpObj, const char* lpszKeyFile, int bSecret);

int ExportToFile(const QString& qsKeyFile, bool bSecret);

Remarks

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

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

Exports the key to a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ExportToStream(SecureBlackboxStream* sKeyStream, int bSecret);

Unicode (Windows)
INT ExportToStream(SecureBlackboxStream* sKeyStream, BOOL bSecret);

int secureblackbox_pgpkeymanager_exporttostream(void* lpObj, SecureBlackboxStream* sKeyStream, int bSecret);

int ExportToStream(SecureBlackboxStream* sKeyStream, bool bSecret);

Remarks

Use this method to save the Key (both the public and secret parts) to a stream pointed by 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.)

GeneratePair Method (PGPKeyManager Class)

Generates a new pair of PGP keys.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GeneratePair(int iVersion, const char* lpszUsername, int iStrength, const char* lpszValidTo, const char* lpszPassword);

Unicode (Windows)
INT GeneratePair(INT iVersion, LPCWSTR lpszUsername, INT iStrength, LPCWSTR lpszValidTo, LPCWSTR lpszPassword);

int secureblackbox_pgpkeymanager_generatepair(void* lpObj, int iVersion, const char* lpszUsername, int iStrength, const char* lpszValidTo, const char* lpszPassword);

int GeneratePair(int iVersion, const QString& qsUsername, int iStrength, const QString& qsValidTo, const QString& qsPassword);

Remarks

ToDo Use this method to create a new key-subkey pair. This is the primary method for generating conformant PGP keys.

Pass the user ID of the new key via the Username property. This typically should be in the format of User Name <user@email>, for example Robert Frost <robert@frost.com>, but generally can be an arbitrary text string.

Set KeyAlgorithm and SubKeyAlgorithm to the public key algorithms that you want to use for the new key. See the full list of algorithms below. Where ECDSA or ECDH algorithm is used, you can specify a particular curve after the algorithm name, separated with the colon: ECDSA:P384 or ECDH:BRAINPOOLP256. KeyBits and SubKeyBits specify the number of bits in the key and the subkey. These parameters can be set to zero if the key length is implicitly defined by the algorithm of the key. For example, ECDSA P256 keys are always 256 bit long, so you may pass 0 as the corresponding KeyBits or SubKeyBits parameter.

Provide the key encryption password and the validity period in days via the Password and Expires parameters. Set Expires to zero to indicate that the key does not expire.

While you can use any combination of algorithms for your key and subkey, most implementations got used to specific hard-wired combinations. Sticking to those will help make sure your keys are understood by other implementations. Typical combinations are:

• EDDSA main key with ECDH:CURVE25519 subkey;
• ECDSA main key with ECDH subkey; both with NIST curves (P256, P384, or P512);
• ECDSA main key with ECDH subkey; both with Brainpool curves (BRAINPOOLP256 or BRAINPOOLP512);
• RSA main key with RSA subkey.

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

ImportBytes Method (PGPKeyManager Class)

Loads a key from a byte array.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT ImportBytes(LPCSTR lpKey, INT lenKey);

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

int ImportBytes(QByteArray qbaKey);

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

ImportFromFile Method (PGPKeyManager Class)

Loads a key from a file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromFile(const char* lpszFileName);

Unicode (Windows)
INT ImportFromFile(LPCWSTR lpszFileName);

int secureblackbox_pgpkeymanager_importfromfile(void* lpObj, const char* lpszFileName);

int ImportFromFile(const QString& qsFileName);

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

Loads a key from a stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportFromStream(SecureBlackboxStream* sKeyStream);

Unicode (Windows)
INT ImportFromStream(SecureBlackboxStream* sKeyStream);

int secureblackbox_pgpkeymanager_importfromstream(void* lpObj, SecureBlackboxStream* sKeyStream);

int ImportFromStream(SecureBlackboxStream* sKeyStream);

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

ImportPinned Method (PGPKeyManager Class)

Loads a key from a pinned key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportPinned();

Unicode (Windows)
INT ImportPinned();

int secureblackbox_pgpkeymanager_importpinned(void* lpObj);

int ImportPinned();

Remarks

ToDo

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

RemoveSignature Method (PGPKeyManager Class)

Unbinds the specified signature from the key, subkey or user.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveSignature(int iIndex);

Unicode (Windows)
INT RemoveSignature(INT iIndex);

int secureblackbox_pgpkeymanager_removesignature(void* lpObj, int iIndex);

int RemoveSignature(int iIndex);

Remarks

Use this method to remove the specified signature from the list of Signatures bound to the key, subkey or user.

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

RemoveSubkey Method (PGPKeyManager Class)

Removes the specified subkey from the key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveSubkey(int iIndex);

Unicode (Windows)
INT RemoveSubkey(INT iIndex);

int secureblackbox_pgpkeymanager_removesubkey(void* lpObj, int iIndex);

int RemoveSubkey(int iIndex);

Remarks

Use this method to remove the subkey referred by its Index from the 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.)

RemoveUser Method (PGPKeyManager Class)

Unbinds the specified user from the key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveUser(int iIndex);

Unicode (Windows)
INT RemoveUser(INT iIndex);

int secureblackbox_pgpkeymanager_removeuser(void* lpObj, int iIndex);

int RemoveUser(int iIndex);

Remarks

Use this method to remove the specified user from the list of UserIDs bound to the 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.)

Reset Method (PGPKeyManager Class)

Creates a new empty keyring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int secureblackbox_pgpkeymanager_reset(void* lpObj);

int Reset();

Remarks

Use this method to initialize a new empty keyring.

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

RevokeKey Method (PGPKeyManager Class)

Revokes the key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RevokeKey(int iReason, const char* lpszComment);

Unicode (Windows)
INT RevokeKey(INT iReason, LPCWSTR lpszComment);

int secureblackbox_pgpkeymanager_revokekey(void* lpObj, int iReason, const char* lpszComment);

int RevokeKey(int iReason, const QString& qsComment);

Remarks

Use this method to revoke the key by adding a revocation signature.

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

RevokeSubkey Method (PGPKeyManager Class)

Revokes the key's subkey.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RevokeSubkey(int iIndex, int iReason, const char* lpszComment);

Unicode (Windows)
INT RevokeSubkey(INT iIndex, INT iReason, LPCWSTR lpszComment);

int secureblackbox_pgpkeymanager_revokesubkey(void* lpObj, int iIndex, int iReason, const char* lpszComment);

int RevokeSubkey(int iIndex, int iReason, const QString& qsComment);

Remarks

Use this method to revoke the subkey with a given Index by adding a revocation signature.

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

RevokeUser Method (PGPKeyManager Class)

Revokes a user certification.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RevokeUser(int iIndex, int iReason, const char* lpszComment);

Unicode (Windows)
INT RevokeUser(INT iIndex, INT iReason, LPCWSTR lpszComment);

int secureblackbox_pgpkeymanager_revokeuser(void* lpObj, int iIndex, int iReason, const char* lpszComment);

int RevokeUser(int iIndex, int iReason, const QString& qsComment);

Remarks

Use this method to revoke the user with the specified Index by adding a revocation signature to the 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.)

SignKey Method (PGPKeyManager Class)

Sign the key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SignKey(const char* lpszKeyValidTo, const char* lpszHashAlgorithm, const char* lpszPreferredAlgs, int iKeyFlags);

Unicode (Windows)
INT SignKey(LPCWSTR lpszKeyValidTo, LPCWSTR lpszHashAlgorithm, LPCWSTR lpszPreferredAlgs, INT iKeyFlags);

int secureblackbox_pgpkeymanager_signkey(void* lpObj, const char* lpszKeyValidTo, const char* lpszHashAlgorithm, const char* lpszPreferredAlgs, int iKeyFlags);

int SignKey(const QString& qsKeyValidTo, const QString& qsHashAlgorithm, const QString& qsPreferredAlgs, int iKeyFlags);

Remarks

Use this method to sign the 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.)

SignSubkey Method (PGPKeyManager Class)

Sign the key's subkey.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SignSubkey(int iIndex, const char* lpszKeyValidTo, const char* lpszHashAlgorithm, const char* lpszPreferredAlgs, int iKeyFlags);

Unicode (Windows)
INT SignSubkey(INT iIndex, LPCWSTR lpszKeyValidTo, LPCWSTR lpszHashAlgorithm, LPCWSTR lpszPreferredAlgs, INT iKeyFlags);

int secureblackbox_pgpkeymanager_signsubkey(void* lpObj, int iIndex, const char* lpszKeyValidTo, const char* lpszHashAlgorithm, const char* lpszPreferredAlgs, int iKeyFlags);

int SignSubkey(int iIndex, const QString& qsKeyValidTo, const QString& qsHashAlgorithm, const QString& qsPreferredAlgs, int iKeyFlags);

Remarks

Use this method to sign the subkey with a given Index.

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

SignUser Method (PGPKeyManager Class)

Sign a user certification.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SignUser(int iIndex, const char* lpszKeyValidTo, const char* lpszHashAlgorithm, int bPrimary, int iCertType);

Unicode (Windows)
INT SignUser(INT iIndex, LPCWSTR lpszKeyValidTo, LPCWSTR lpszHashAlgorithm, BOOL bPrimary, INT iCertType);

int secureblackbox_pgpkeymanager_signuser(void* lpObj, int iIndex, const char* lpszKeyValidTo, const char* lpszHashAlgorithm, int bPrimary, int iCertType);

int SignUser(int iIndex, const QString& qsKeyValidTo, const QString& qsHashAlgorithm, bool bPrimary, int iCertType);

Remarks

Use this method to sign the user with the specified Index.

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

Verify Method (PGPKeyManager Class)

Verify the signature.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
bool Verify(int iIndex);

Unicode (Windows)
INT Verify(INT iIndex);

bool secureblackbox_pgpkeymanager_verify(void* lpObj, int iIndex);

bool Verify(int iIndex);

Remarks

ToDo

Error Handling (C++)

This method returns a Boolean 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 (PGPKeyManager Class)

Information about errors during PGP key management.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_PGPKEYMANAGER_ERROR 1

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

class PGPKeyManagerErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

The event is fired in case of exceptional conditions during key management.

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

KeyPassphraseNeeded Event (PGPKeyManager Class)

Requests a key protection password from the application.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireKeyPassphraseNeeded(PGPKeyManagerKeyPassphraseNeededEventParams *e);

typedef struct {
  const char *KeyID;
  const char *UserID;
  int MainKey;
  char *Passphrase;
  int Skip;
  int reserved;
} PGPKeyManagerKeyPassphraseNeededEventParams;


Unicode (Windows)
virtual INT FireKeyPassphraseNeeded(PGPKeyManagerKeyPassphraseNeededEventParams *e);

typedef struct {
  LPCWSTR KeyID;
  LPCWSTR UserID;
  BOOL MainKey;
  LPWSTR Passphrase;
  BOOL Skip;
  INT reserved;
} PGPKeyManagerKeyPassphraseNeededEventParams;

#define EID_PGPKEYMANAGER_KEYPASSPHRASENEEDED 2

virtual INT SECUREBLACKBOX_CALL FireKeyPassphraseNeeded(LPSTR &lpszKeyID, LPSTR &lpszUserID, BOOL &bMainKey, LPSTR &lpszPassphrase, BOOL &bSkip);

class PGPKeyManagerKeyPassphraseNeededEventParams {
public:
  const QString &KeyID();

  const QString &UserID();

  bool MainKey();

  const QString &Passphrase();
  void SetPassphrase(const QString &qsPassphrase);

  bool Skip();
  void SetSkip(bool bSkip);

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

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

// Or, subclass PGPKeyManager and override this emitter function.
virtual int FireKeyPassphraseNeeded(PGPKeyManagerKeyPassphraseNeededEventParams *e) {...}

Remarks

The class fires this event to request a secret key passphrase from the application. Note that this event asks for a key protection passphrase rather than a message protection passphrase. The class fires it when it attempts to use a secret key to sign the data.

This event is fired for every protected secret key residing in SigningKeys. KeyID specifies the key for which the password is requested, and UserID identifies its user. MainKey tells whether the key is a master key or a subkey.

The handler should provide password via the Passphrase parameter, or set Skip to True to skip this key.

For each key KeyPassphraseNeeded is called in a loop until the correct password is provided or the maximum number of password attempts reached.

Notification Event (PGPKeyManager Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_PGPKEYMANAGER_NOTIFICATION 3

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

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

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

Remarks

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

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

PGPKey Type

This container represents a PGP key.

Syntax

SecureBlackboxPGPKey (declared in secureblackbox.h)

Remarks

OpenPGP standard supports several types of keys. In our days, a typical OpenPGP keypair actually consists of two cryptographic keys: a primary key and a subkey. The primary key is normally used for signing, while the subkey is used for encryption.

While it is typical for PGP environments to use a primary key/subkey bundle, this is not a must. Sometimes you may come across standalone keys (mainly when dealing with older implementations), as well as whole key trees, each of those carrying a bunch of differently-purposed subkeys bound to the same primary key.

Algorithm-wise, OpenPGP keys also differ. Generally speaking, OpenPGP supports the following public key algorithms: RSA, Elgamal (often incorrectly referred to as DH), DSA, ECDH and ECDSA. When it comes to primary key/subkey bundles, DSA/Elgamal, RSA/RSA and ECDSA/ECDH pairs are typically used. Although there's no restriction on algorithm bundles, and, e.g. a ECDSA/Elgamal key bundle is perfectly possible, such combination is rarely used in practice.

A typical OpenPGP key is associated with some kind of user ID (Username). It is normally represented with a user's e-mail address, while in theory can be any piece of text. The secret part of the OpenPGP keypair is protected with a password (Passphrase).

Fields

Constructors

>

PGPKey()

Creates an empty PGP key object.

PGPKey(const char* lpszFileName)

Create a PGP key object from a key file.

PGPSignature Type

A container for PGP signature properties.

Syntax

SecureBlackboxPGPSignature (declared in secureblackbox.h)

Remarks

PGPSignature contains details and validation information for a PGP signature.

Fields

Constructors

>

PGPSignature()

Creates an empty PGPSignature object.

PGPUser Type

A container for PGP user properties.

Syntax

SecureBlackboxPGPUser (declared in secureblackbox.h)

Remarks

PGPUser contains details information for a PGP user.

Fields

Constructors

>

PGPUser()

Creates an empty PGPUser object.

SecureBlackboxList Type

Syntax

SecureBlackboxList<T> (declared in secureblackbox.h)

Remarks

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

int GetCount() {}

int SetCount() {}

T* Get(int index) {}

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

SecureBlackboxStream Type

Syntax

SecureBlackboxStream (declared in secureblackbox.h)

Remarks

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

PGPKeyManager Config Settings

Base Config Settings

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

PGPKeyManager Errors