PGPKeyring Class

Properties   Methods   Events   Config Settings   Errors  

The PGPKeyring class manages PGP keyring files.

Syntax

PGPKeyring

Remarks

Keyring keep the details of local PGP key collections. A typical keyring consists of two parts, with the first part containing the public keys of other people, and the second part containing the secret keys of the keyring owner (i.e. your secret keys).

PGPKeyring can work with RSA, Elgamal (DH), ECDSA, DSS, and EdDSA keypairs with or without subkeys. Public and private PGP keys of versions 2, 3, 4, 5, and 6 are supported.

Depending on your task at hand, you may need to only use the public part, or both. However, there is a couple of catches here. Some PGP implementations operate with just one keyring file that contains both the public and secret keys. The others sometimes mess-up the keys, with secret key accidentally ending up in the public part of the keyring, or the other way round.

Our suggestion therefore is to load all the keyring files that you have into PGPKeyring using consecutive ImportFromFile (or ImportBytes) calls, and then look for the keys that match the required parameters in the Keys collection. That would provide fault-tolerant and smooth experience to your customers. PGPKeyring keyring = new PGPKeyring(); keyring.ImportFromFile("pubring.pkr"); keyring.ImportFromFile("secring.skr");

Once you have loaded your keyring files into the keyring, you can perform the following operations on the keys:

• Iterate over the whole set of keys using Keys collection.
• Add new keys to the keyring using methods such as ImportBytes, ImportPinned, or ImportFromFile.
• Save the updated keyring using ExportBytes or ExportToFile methods.
• Use Select to filter keys by certain criteria (public/private, KeyID) into a separate SelectedKeys list.
• Remove keys from the keyring.
• Assign the keyring keys to properties like PGPWriter.SigningKeys to use them for encryption or signing.

Once you have completed your work with PGPKeyring, dispose of the object or call Reset to clean up all the key information from memory.

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.

Keys Property (PGPKeyring Class)

PGP keys available in the keyring.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxPGPKey>* GetKeys();

int secureblackbox_pgpkeyring_getkeycount(void* lpObj);

int secureblackbox_pgpkeyring_getkeybitsinkey(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeycanencrypt(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeycansign(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeycurve(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyenabled(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeyencryptionalgorithm(void* lpObj, int keyindex);

int64 secureblackbox_pgpkeyring_getkeyhandle(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyispublic(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyissecret(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyissubkey(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeykeyfp(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeykeyid(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeypassphrase(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeypassphrasevalid(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeyprimarykeyid(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyprotection(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeypublickeyalgorithm(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyqbits(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeytimestamp(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeyusername(void* lpObj, int keyindex);

char* secureblackbox_pgpkeyring_getkeyvalidto(void* lpObj, int keyindex);

int secureblackbox_pgpkeyring_getkeyversion(void* lpObj, int keyindex);

int GetKeyCount();

int GetKeyBitsInKey(int iKeyIndex);

bool GetKeyCanEncrypt(int iKeyIndex);

bool GetKeyCanSign(int iKeyIndex);

QString GetKeyCurve(int iKeyIndex);

bool GetKeyEnabled(int iKeyIndex);

QString GetKeyEncryptionAlgorithm(int iKeyIndex);

qint64 GetKeyHandle(int iKeyIndex);

bool GetKeyIsPublic(int iKeyIndex);

bool GetKeyIsSecret(int iKeyIndex);

bool GetKeyIsSubkey(int iKeyIndex);

QString GetKeyKeyFP(int iKeyIndex);

QString GetKeyKeyID(int iKeyIndex);

QString GetKeyPassphrase(int iKeyIndex);

bool GetKeyPassphraseValid(int iKeyIndex);

QString GetKeyPrimaryKeyID(int iKeyIndex);

int GetKeyProtection(int iKeyIndex);

QString GetKeyPublicKeyAlgorithm(int iKeyIndex);

int GetKeyQBits(int iKeyIndex);

QString GetKeyTimestamp(int iKeyIndex);

QString GetKeyUsername(int iKeyIndex);

QString GetKeyValidTo(int iKeyIndex);

int GetKeyVersion(int iKeyIndex);

Remarks

This property populates a collection of all pgp keys contained in the keyring.

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

Data Type

SecureBlackboxPGPKey

PinnedKey Property (PGPKeyring Class)

A PGP key that is being manipulated on.

Syntax

• C++
• C
• Qt

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

int64 secureblackbox_pgpkeyring_getpinnedkeyhandle(void* lpObj);
int secureblackbox_pgpkeyring_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

SelectedKeys Property (PGPKeyring Class)

The keys matching the selection criteria.

Syntax

• C++
• C
• Qt

SecureBlackboxList<SecureBlackboxPGPKey>* GetSelectedKeys();

int secureblackbox_pgpkeyring_getselectedkeycount(void* lpObj);

int secureblackbox_pgpkeyring_getselectedkeybitsinkey(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeycanencrypt(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeycansign(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeycurve(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyenabled(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeyencryptionalgorithm(void* lpObj, int selectedkeyindex);

int64 secureblackbox_pgpkeyring_getselectedkeyhandle(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyispublic(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyissecret(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyissubkey(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeykeyfp(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeykeyid(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeypassphrase(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeypassphrasevalid(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeyprimarykeyid(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyprotection(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeypublickeyalgorithm(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyqbits(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeytimestamp(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeyusername(void* lpObj, int selectedkeyindex);

char* secureblackbox_pgpkeyring_getselectedkeyvalidto(void* lpObj, int selectedkeyindex);

int secureblackbox_pgpkeyring_getselectedkeyversion(void* lpObj, int selectedkeyindex);

int GetSelectedKeyCount();

int GetSelectedKeyBitsInKey(int iSelectedKeyIndex);

bool GetSelectedKeyCanEncrypt(int iSelectedKeyIndex);

bool GetSelectedKeyCanSign(int iSelectedKeyIndex);

QString GetSelectedKeyCurve(int iSelectedKeyIndex);

bool GetSelectedKeyEnabled(int iSelectedKeyIndex);

QString GetSelectedKeyEncryptionAlgorithm(int iSelectedKeyIndex);

qint64 GetSelectedKeyHandle(int iSelectedKeyIndex);

bool GetSelectedKeyIsPublic(int iSelectedKeyIndex);

bool GetSelectedKeyIsSecret(int iSelectedKeyIndex);

bool GetSelectedKeyIsSubkey(int iSelectedKeyIndex);

QString GetSelectedKeyKeyFP(int iSelectedKeyIndex);

QString GetSelectedKeyKeyID(int iSelectedKeyIndex);

QString GetSelectedKeyPassphrase(int iSelectedKeyIndex);

bool GetSelectedKeyPassphraseValid(int iSelectedKeyIndex);

QString GetSelectedKeyPrimaryKeyID(int iSelectedKeyIndex);

int GetSelectedKeyProtection(int iSelectedKeyIndex);

QString GetSelectedKeyPublicKeyAlgorithm(int iSelectedKeyIndex);

int GetSelectedKeyQBits(int iSelectedKeyIndex);

QString GetSelectedKeyTimestamp(int iSelectedKeyIndex);

QString GetSelectedKeyUsername(int iSelectedKeyIndex);

QString GetSelectedKeyValidTo(int iSelectedKeyIndex);

int GetSelectedKeyVersion(int iSelectedKeyIndex);

Remarks

This property contains all the keys that match the selection filter passed to Select method.

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

Data Type

SecureBlackboxPGPKey

Config Method (PGPKeyring 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_pgpkeyring_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

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

DoAction Method (PGPKeyring 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_pgpkeyring_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 (PGPKeyring Class)

Exports the keyring 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_pgpkeyring_exportbytes(void* lpObj, int bSecret, int *lpSize);

QByteArray ExportBytes(bool bSecret);

Remarks

Use this method to export the keyring to a byte array. PGP software typically uses two files to store keyrings. Use Secret parameter to specify which part of the keyring you would like to export (public or secret).

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

Exports the keyring to disk.

Syntax

• C++
• C
• Qt

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

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

int secureblackbox_pgpkeyring_exporttofile(void* lpObj, const char* lpszFileName, int bSecret);

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

Remarks

Use this method to export the keyring to disk. PGP software typically uses two files to store keyrings, public and private.

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

Exports the keyring to streams.

Syntax

• C++
• C
• Qt

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

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

int secureblackbox_pgpkeyring_exporttostream(void* lpObj, SecureBlackboxStream* sKeyringStream, int bSecret);

int ExportToStream(SecureBlackboxStream* sKeyringStream, bool bSecret);

Remarks

Use this method to export the keyring to streams. PGP software typically uses two files to store keyrings, public and private.

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

Loads a key from a byte array.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportBytes(const char* lpKeyring, int lenKeyring);

Unicode (Windows)
INT ImportBytes(LPCSTR lpKeyring, INT lenKeyring);

int secureblackbox_pgpkeyring_importbytes(void* lpObj, const char* lpKeyring, int lenKeyring);

int ImportBytes(QByteArray qbaKeyring);

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

Loads a key from a file.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT ImportFromFile(LPCWSTR lpszKeyringFile);

int secureblackbox_pgpkeyring_importfromfile(void* lpObj, const char* lpszKeyringFile);

int ImportFromFile(const QString& qsKeyringFile);

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

Loads a key from a stream.

Syntax

• C++
• C
• Qt

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

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

int secureblackbox_pgpkeyring_importfromstream(void* lpObj, SecureBlackboxStream* sKeyringStream);

int ImportFromStream(SecureBlackboxStream* sKeyringStream);

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

Imports a pinned secret key to the keyring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ImportPinned();

Unicode (Windows)
INT ImportPinned();

int secureblackbox_pgpkeyring_importpinned(void* lpObj);

int ImportPinned();

Remarks

Use this method to import a key provided via PinnedKey to the keyring. This can be a public or 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.)

Remove Method (PGPKeyring Class)

Removes the specified key from the keyring.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT Remove(INT iIndex);

int secureblackbox_pgpkeyring_remove(void* lpObj, int iIndex);

int Remove(int iIndex);

Remarks

Use this method to remove a key from the keyring. Use Index to pass the index of the key to be removed.

Error Handling (C++)

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

RemoveByID Method (PGPKeyring Class)

Removes key by its ID.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int RemoveByID(const char* lpszKeyID);

Unicode (Windows)
INT RemoveByID(LPCWSTR lpszKeyID);

int secureblackbox_pgpkeyring_removebyid(void* lpObj, const char* lpszKeyID);

int RemoveByID(const QString& qsKeyID);

Remarks

Call this method to remove the specified key from the 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.)

Reset Method (PGPKeyring Class)

Creates a new empty keyring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

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

Select Method (PGPKeyring Class)

Filters a selection of keys from the keyring using a template.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Select(const char* lpszFilter, int bSecretOnly, int iMaxCount);

Unicode (Windows)
INT Select(LPCWSTR lpszFilter, BOOL bSecretOnly, INT iMaxCount);

int secureblackbox_pgpkeyring_select(void* lpObj, const char* lpszFilter, int bSecretOnly, int iMaxCount);

int Select(const QString& qsFilter, bool bSecretOnly, int iMaxCount);

Remarks

Use this method to get a list of keys that satisfy the Filter criteria. The filter should follow the "Name=Value" format, where Name can be one of the following:

• userid
• fp or fingerprint
• keyid

Set SecretOnly to True to only search for secret keys. MaxCount allows to limit the number of keys returned.

Once the method completes, the keys that match the criteria will be available in SelectedKeys property.

Error Handling (C++)

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

UpdatePinned Method (PGPKeyring Class)

Update a pinned key in the keyring.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int UpdatePinned();

Unicode (Windows)
INT UpdatePinned();

int secureblackbox_pgpkeyring_updatepinned(void* lpObj);

int UpdatePinned();

Remarks

Use this method to update a key provided via PinnedKey in the keyring. This can be a public or 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.)

Error Event (PGPKeyring Class)

Information about errors during PGP key management.

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_PGPKEYRING_ERROR 1

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

class PGPKeyringErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

// Or, subclass PGPKeyring and override this emitter function.
virtual int FireError(PGPKeyringErrorEventParams *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.

Notification Event (PGPKeyring Class)

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

Syntax

• C++
• C
• Qt

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

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


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

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

#define EID_PGPKEYRING_NOTIFICATION 2

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

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

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

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

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 PGPKeyring class.

int GetCount() {}

int SetCount(int count) {}

T* Get(int index) {}

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

SecureBlackboxStream Type

Syntax

SecureBlackboxStream (declared in secureblackbox.h)

Remarks

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

PGPKeyring Config Settings

Base Config Settings

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

PGPKeyring Errors