PGPKeyring Component

Properties   Methods   Events   Config Settings   Errors  

The PGPKeyring component manages PGP keyring files.

Syntax

TsbxPGPKeyring

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.

Note: PGPKeyring provides access to keyring contents but does not let you edit or generate keys. To achieve these, please see PGPKeyManager.

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 component with short descriptions. Click on the links for further details.

Method List

---

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

---

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

---

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

KeyCount Property (PGPKeyring Component)

The number of records in the Key arrays.

Syntax

__property int KeyCount = { read=FKeyCount };

Default Value

0

Remarks

This property controls the size of the following arrays:

• KeyBitsInKey
• KeyCanEncrypt
• KeyCanSign
• KeyCurve
• KeyEnabled
• KeyEncryptionAlgorithm
• KeyHandle
• KeyIsPublic
• KeyIsSecret
• KeyIsSubkey
• KeyKeyFP
• KeyKeyID
• KeyPassphrase
• KeyPassphraseValid
• KeyPrimaryKeyID
• KeyProtection
• KeyPublicKeyAlgorithm
• KeyQBits
• KeyTimestamp
• KeyUsername
• KeyValidTo
• KeyVersion

The array indices start at 0 and end at KeyCount - 1.

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

Data Type

Integer

KeyBitsInKey Property (PGPKeyring Component)

Indicates the key length in bits.

Syntax

__property int KeyBitsInKey[int KeyIndex] = { read=FKeyBitsInKey };

Default Value

2048

Remarks

Indicates the key length in bits.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Integer

KeyCanEncrypt Property (PGPKeyring Component)

Returns True if this key can be used for encryption.

Syntax

__property bool KeyCanEncrypt[int KeyIndex] = { read=FKeyCanEncrypt };

Default Value

false

Remarks

Returns True if this key can be used for encryption.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyCanSign Property (PGPKeyring Component)

Returns True if this key can be used for signing.

Syntax

__property bool KeyCanSign[int KeyIndex] = { read=FKeyCanSign };

Default Value

false

Remarks

Returns True if this key can be used for signing.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyCurve Property (PGPKeyring Component)

Indicates the elliptic curve associated with a EC key.

Syntax

__property String KeyCurve[int KeyIndex] = { read=FKeyCurve };

Default Value

""

Remarks

Indicates the elliptic curve associated with a EC key.

Supported values:

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyEnabled Property (PGPKeyring Component)

Enables or disables this key for use in encryption or signing operation.

Syntax

__property bool KeyEnabled[int KeyIndex] = { read=FKeyEnabled };

Default Value

false

Remarks

Enables or disables this key for use in encryption or signing operation.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyEncryptionAlgorithm Property (PGPKeyring Component)

Indicates the symmetric algorithm used to encrypt the secret key.

Syntax

__property String KeyEncryptionAlgorithm[int KeyIndex] = { read=FKeyEncryptionAlgorithm };

Default Value

"AES128"

Remarks

Indicates the symmetric algorithm used to encrypt the secret key.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyHandle Property (PGPKeyring Component)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

__property __int64 KeyHandle[int KeyIndex] = { read=FKeyHandle };

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Long64

KeyIsPublic Property (PGPKeyring Component)

Returns True if this key is a public key, and False otherwise.

Syntax

__property bool KeyIsPublic[int KeyIndex] = { read=FKeyIsPublic };

Default Value

false

Remarks

Returns True if this key is a public key, and False otherwise.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyIsSecret Property (PGPKeyring Component)

Returns True if this key is a secret key, and False otherwise.

Syntax

__property bool KeyIsSecret[int KeyIndex] = { read=FKeyIsSecret };

Default Value

false

Remarks

Returns True if this key is a secret key, and False otherwise.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyIsSubkey Property (PGPKeyring Component)

Returns True if this key is a subkey of another key, and False otherwise.

Syntax

__property bool KeyIsSubkey[int KeyIndex] = { read=FKeyIsSubkey };

Default Value

false

Remarks

Returns True if this key is a subkey of another key, and False otherwise.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyKeyFP Property (PGPKeyring Component)

The 20-byte fingerprint (hash value) of this key.

Syntax

__property String KeyKeyFP[int KeyIndex] = { read=FKeyKeyFP };

Default Value

""

Remarks

The 20-byte fingerprint (hash value) of this key.

KeyFP could be used to distinguish two keys with the same KeyID.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyKeyID Property (PGPKeyring Component)

Contains a 8-byte key identifier.

Syntax

__property String KeyKeyID[int KeyIndex] = { read=FKeyKeyID };

Default Value

""

Remarks

Contains a 8-byte key identifier.

It is quite rare that IDs of two keys collide. If that happens, their fingerprints (KeyFP) can be used for distinguish between the keys. Please note that many PGP implementations show only 4 lowest bytes of the KeyID to the user.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyPassphrase Property (PGPKeyring Component)

The key protection password.

Syntax

__property String KeyPassphrase[int KeyIndex] = { read=FKeyPassphrase };

Default Value

""

Remarks

The key protection password.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyPassphraseValid Property (PGPKeyring Component)

Use this property to check whether the specified Passphrase is valid and can be used to unlock the secret key.

Syntax

__property bool KeyPassphraseValid[int KeyIndex] = { read=FKeyPassphraseValid };

Default Value

false

Remarks

Use this property to check whether the specified KeyPassphrase is valid and can be used to unlock the secret key.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Boolean

KeyPrimaryKeyID Property (PGPKeyring Component)

If this key is a subkey ( IsSubkey returns True), this property contains the identifier of the subkey's primary key.

Syntax

__property String KeyPrimaryKeyID[int KeyIndex] = { read=FKeyPrimaryKeyID };

Default Value

""

Remarks

If this key is a subkey (KeyIsSubkey returns True), this property contains the identifier of the subkey's primary key.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyProtection Property (PGPKeyring Component)

Specifies the level of protection applied to the secret key.

Syntax

__property TsbxPGPKeyringKeyProtections KeyProtection[int KeyIndex] = { read=FKeyProtection };

enum TsbxPGPKeyringKeyProtections {
  pptNone=0,
  pptLow=1,
  pptNormal=2,
  pptHigh=3
};

Default Value

pptNone

Remarks

Specifies the level of protection applied to the secret key.

Allowed values:

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Integer

KeyPublicKeyAlgorithm Property (PGPKeyring Component)

Specifies the asymmetric algorithm of the key.

Syntax

__property String KeyPublicKeyAlgorithm[int KeyIndex] = { read=FKeyPublicKeyAlgorithm };

Default Value

""

Remarks

Specifies the asymmetric algorithm of the key.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyQBits Property (PGPKeyring Component)

The length of the DSA Q (legitimate range: 160-512).

Syntax

__property int KeyQBits[int KeyIndex] = { read=FKeyQBits };

Default Value

0

Remarks

The length of the DSA Q (legitimate range: 160-512).

This parameter corresponds to the hash algorithm used with the key. For example, if the value of Q is 256, SHA-256 will be used.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Integer

KeyTimestamp Property (PGPKeyring Component)

Use this property to check the time the key was generated.

Syntax

__property String KeyTimestamp[int KeyIndex] = { read=FKeyTimestamp };

Default Value

""

Remarks

Use this property to check the time the key was generated. The date and time are stored and retrieved in Universal Coordinate Time (UTC).

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyUsername Property (PGPKeyring Component)

Specifies the name of the user bound to this key.

Syntax

__property String KeyUsername[int KeyIndex] = { read=FKeyUsername };

Default Value

""

Remarks

Specifies the name of the user bound to this key.

The PGP username is typically represented with a full name and an email address, but generally can be any non-empty string.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyValidTo Property (PGPKeyring Component)

Provide accurate expiration moment indication.

Syntax

__property String KeyValidTo[int KeyIndex] = { read=FKeyValidTo };

Default Value

"0"

Remarks

Provide accurate expiration moment indication. This is different to expires property which only contains expiration time in days in old keys.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

String

KeyVersion Property (PGPKeyring Component)

Indicates the key version.

Syntax

__property int KeyVersion[int KeyIndex] = { read=FKeyVersion };

Default Value

0

Remarks

Indicates the key version.

The key version refers to the version of the public-key packet format as defined in RFC 4880.

Only four versions are currently allowed here: 3, 4, 5 and 6. It is recommended that all new keys are created with version of 6.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

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

Data Type

Integer

PinnedKeyHandle Property (PGPKeyring Component)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

__property __int64 PinnedKeyHandle = { read=FPinnedKeyHandle, write=FSetPinnedKeyHandle };

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

This property is not available at design time.

Data Type

Long64

SelectedKeyCount Property (PGPKeyring Component)

The number of records in the SelectedKey arrays.

Syntax

__property int SelectedKeyCount = { read=FSelectedKeyCount };

Default Value

0

Remarks

This property controls the size of the following arrays:

• SelectedKeyBitsInKey
• SelectedKeyCanEncrypt
• SelectedKeyCanSign
• SelectedKeyCurve
• SelectedKeyEnabled
• SelectedKeyEncryptionAlgorithm
• SelectedKeyHandle
• SelectedKeyIsPublic
• SelectedKeyIsSecret
• SelectedKeyIsSubkey
• SelectedKeyKeyFP
• SelectedKeyKeyID
• SelectedKeyPassphrase
• SelectedKeyPassphraseValid
• SelectedKeyPrimaryKeyID
• SelectedKeyProtection
• SelectedKeyPublicKeyAlgorithm
• SelectedKeyQBits
• SelectedKeyTimestamp
• SelectedKeyUsername
• SelectedKeyValidTo
• SelectedKeyVersion

The array indices start at 0 and end at SelectedKeyCount - 1.

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

Data Type

Integer

SelectedKeyBitsInKey Property (PGPKeyring Component)

Indicates the key length in bits.

Syntax

__property int SelectedKeyBitsInKey[int SelectedKeyIndex] = { read=FSelectedKeyBitsInKey };

Default Value

2048

Remarks

Indicates the key length in bits.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Integer

SelectedKeyCanEncrypt Property (PGPKeyring Component)

Returns True if this key can be used for encryption.

Syntax

__property bool SelectedKeyCanEncrypt[int SelectedKeyIndex] = { read=FSelectedKeyCanEncrypt };

Default Value

false

Remarks

Returns True if this key can be used for encryption.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyCanSign Property (PGPKeyring Component)

Returns True if this key can be used for signing.

Syntax

__property bool SelectedKeyCanSign[int SelectedKeyIndex] = { read=FSelectedKeyCanSign };

Default Value

false

Remarks

Returns True if this key can be used for signing.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyCurve Property (PGPKeyring Component)

Indicates the elliptic curve associated with a EC key.

Syntax

__property String SelectedKeyCurve[int SelectedKeyIndex] = { read=FSelectedKeyCurve };

Default Value

""

Remarks

Indicates the elliptic curve associated with a EC key.

Supported values:

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyEnabled Property (PGPKeyring Component)

Enables or disables this key for use in encryption or signing operation.

Syntax

__property bool SelectedKeyEnabled[int SelectedKeyIndex] = { read=FSelectedKeyEnabled };

Default Value

false

Remarks

Enables or disables this key for use in encryption or signing operation.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyEncryptionAlgorithm Property (PGPKeyring Component)

Indicates the symmetric algorithm used to encrypt the secret key.

Syntax

__property String SelectedKeyEncryptionAlgorithm[int SelectedKeyIndex] = { read=FSelectedKeyEncryptionAlgorithm };

Default Value

"AES128"

Remarks

Indicates the symmetric algorithm used to encrypt the secret key.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyHandle Property (PGPKeyring Component)

Allows to get or set a 'handle', a unique identifier of the underlying property object.

Syntax

__property __int64 SelectedKeyHandle[int SelectedKeyIndex] = { read=FSelectedKeyHandle };

Default Value

0

Remarks

Allows to get or set a 'handle', a unique identifier of the underlying property object. Use this property to assign objects of the same type in a quicker manner, without copying them fieldwise.

When you pass a handle of one object to another, the source object is copied to the destination rather than assigned. It is safe to get rid of the original object after such operation. pdfSigner.setSigningCertHandle(certMgr.getCertHandle());

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Long64

SelectedKeyIsPublic Property (PGPKeyring Component)

Returns True if this key is a public key, and False otherwise.

Syntax

__property bool SelectedKeyIsPublic[int SelectedKeyIndex] = { read=FSelectedKeyIsPublic };

Default Value

false

Remarks

Returns True if this key is a public key, and False otherwise.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyIsSecret Property (PGPKeyring Component)

Returns True if this key is a secret key, and False otherwise.

Syntax

__property bool SelectedKeyIsSecret[int SelectedKeyIndex] = { read=FSelectedKeyIsSecret };

Default Value

false

Remarks

Returns True if this key is a secret key, and False otherwise.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyIsSubkey Property (PGPKeyring Component)

Returns True if this key is a subkey of another key, and False otherwise.

Syntax

__property bool SelectedKeyIsSubkey[int SelectedKeyIndex] = { read=FSelectedKeyIsSubkey };

Default Value

false

Remarks

Returns True if this key is a subkey of another key, and False otherwise.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyKeyFP Property (PGPKeyring Component)

The 20-byte fingerprint (hash value) of this key.

Syntax

__property String SelectedKeyKeyFP[int SelectedKeyIndex] = { read=FSelectedKeyKeyFP };

Default Value

""

Remarks

The 20-byte fingerprint (hash value) of this key.

KeyFP could be used to distinguish two keys with the same KeyID.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyKeyID Property (PGPKeyring Component)

Contains a 8-byte key identifier.

Syntax

__property String SelectedKeyKeyID[int SelectedKeyIndex] = { read=FSelectedKeyKeyID };

Default Value

""

Remarks

Contains a 8-byte key identifier.

It is quite rare that IDs of two keys collide. If that happens, their fingerprints (KeyFP) can be used for distinguish between the keys. Please note that many PGP implementations show only 4 lowest bytes of the KeyID to the user.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyPassphrase Property (PGPKeyring Component)

The key protection password.

Syntax

__property String SelectedKeyPassphrase[int SelectedKeyIndex] = { read=FSelectedKeyPassphrase };

Default Value

""

Remarks

The key protection password.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyPassphraseValid Property (PGPKeyring Component)

Use this property to check whether the specified Passphrase is valid and can be used to unlock the secret key.

Syntax

__property bool SelectedKeyPassphraseValid[int SelectedKeyIndex] = { read=FSelectedKeyPassphraseValid };

Default Value

false

Remarks

Use this property to check whether the specified SelectedKeyPassphrase is valid and can be used to unlock the secret key.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Boolean

SelectedKeyPrimaryKeyID Property (PGPKeyring Component)

If this key is a subkey ( IsSubkey returns True), this property contains the identifier of the subkey's primary key.

Syntax

__property String SelectedKeyPrimaryKeyID[int SelectedKeyIndex] = { read=FSelectedKeyPrimaryKeyID };

Default Value

""

Remarks

If this key is a subkey (SelectedKeyIsSubkey returns True), this property contains the identifier of the subkey's primary key.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyProtection Property (PGPKeyring Component)

Specifies the level of protection applied to the secret key.

Syntax

__property TsbxPGPKeyringSelectedKeyProtections SelectedKeyProtection[int SelectedKeyIndex] = { read=FSelectedKeyProtection };

enum TsbxPGPKeyringSelectedKeyProtections {
  pptNone=0,
  pptLow=1,
  pptNormal=2,
  pptHigh=3
};

Default Value

pptNone

Remarks

Specifies the level of protection applied to the secret key.

Allowed values:

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Integer

SelectedKeyPublicKeyAlgorithm Property (PGPKeyring Component)

Specifies the asymmetric algorithm of the key.

Syntax

__property String SelectedKeyPublicKeyAlgorithm[int SelectedKeyIndex] = { read=FSelectedKeyPublicKeyAlgorithm };

Default Value

""

Remarks

Specifies the asymmetric algorithm of the key.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyQBits Property (PGPKeyring Component)

The length of the DSA Q (legitimate range: 160-512).

Syntax

__property int SelectedKeyQBits[int SelectedKeyIndex] = { read=FSelectedKeyQBits };

Default Value

0

Remarks

The length of the DSA Q (legitimate range: 160-512).

This parameter corresponds to the hash algorithm used with the key. For example, if the value of Q is 256, SHA-256 will be used.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Integer

SelectedKeyTimestamp Property (PGPKeyring Component)

Use this property to check the time the key was generated.

Syntax

__property String SelectedKeyTimestamp[int SelectedKeyIndex] = { read=FSelectedKeyTimestamp };

Default Value

""

Remarks

Use this property to check the time the key was generated. The date and time are stored and retrieved in Universal Coordinate Time (UTC).

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyUsername Property (PGPKeyring Component)

Specifies the name of the user bound to this key.

Syntax

__property String SelectedKeyUsername[int SelectedKeyIndex] = { read=FSelectedKeyUsername };

Default Value

""

Remarks

Specifies the name of the user bound to this key.

The PGP username is typically represented with a full name and an email address, but generally can be any non-empty string.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyValidTo Property (PGPKeyring Component)

Provide accurate expiration moment indication.

Syntax

__property String SelectedKeyValidTo[int SelectedKeyIndex] = { read=FSelectedKeyValidTo };

Default Value

"0"

Remarks

Provide accurate expiration moment indication. This is different to expires property which only contains expiration time in days in old keys.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

String

SelectedKeyVersion Property (PGPKeyring Component)

Indicates the key version.

Syntax

__property int SelectedKeyVersion[int SelectedKeyIndex] = { read=FSelectedKeyVersion };

Default Value

0

Remarks

Indicates the key version.

The key version refers to the version of the public-key packet format as defined in RFC 4880.

Only four versions are currently allowed here: 3, 4, 5 and 6. It is recommended that all new keys are created with version of 6.

The SelectedKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SelectedKeyCount property.

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

Data Type

Integer

Config Method (PGPKeyring Component)

Sets or retrieves a configuration setting.

Syntax

String __fastcall Config(String ConfigurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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.

DoAction Method (PGPKeyring Component)

Performs an additional action.

Syntax

String __fastcall DoAction(String ActionID, String ActionParams);

Remarks

DoAction is a generic method available in every component. 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:

ExportBytes Method (PGPKeyring Component)

Exports the keyring to a byte array.

Syntax

DynamicArray<Byte> __fastcall ExportBytes(bool Secret);

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

ExportToFile Method (PGPKeyring Component)

Exports the keyring to disk.

Syntax

void __fastcall ExportToFile(String FileName, bool Secret);

Remarks

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

ImportBytes Method (PGPKeyring Component)

Loads a key from a byte array.

Syntax

void __fastcall ImportBytes(DynamicArray<Byte> Keyring);

Remarks

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

ImportFromFile Method (PGPKeyring Component)

Loads a key from a file.

Syntax

void __fastcall ImportFromFile(String KeyringFile);

Remarks

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

ImportPinned Method (PGPKeyring Component)

Imports a pinned secret key to the keyring.

Syntax

void __fastcall ImportPinned();

Remarks

Use this method to import a key provided via PinnedKey to the keyring. This can be a public or secret key.

Remove Method (PGPKeyring Component)

Removes the specified key from the keyring.

Syntax

void __fastcall Remove(int Index);

Remarks

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

RemoveByID Method (PGPKeyring Component)

Removes key by its ID.

Syntax

void __fastcall RemoveByID(String KeyID);

Remarks

Call this method to remove the specified key from the keyring.

Reset Method (PGPKeyring Component)

Creates a new empty keyring.

Syntax

void __fastcall Reset();

Remarks

Use this method to initialize a new empty keyring.

Select Method (PGPKeyring Component)

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

Syntax

void __fastcall Select(String Filter, bool SecretOnly, int MaxCount);

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.

UpdatePinned Method (PGPKeyring Component)

Update a pinned key in the keyring.

Syntax

void __fastcall UpdatePinned();

Remarks

Use this method to update a key provided via PinnedKey in the keyring. This can be a public or secret key.

Error Event (PGPKeyring Component)

Information about errors during PGP key management.

Syntax

typedef struct {
  int ErrorCode;
  String Description;
} TsbxPGPKeyringErrorEventParams;
typedef void __fastcall (__closure *TsbxPGPKeyringErrorEvent)(System::TObject* Sender, TsbxPGPKeyringErrorEventParams *e);
__property TsbxPGPKeyringErrorEvent OnError = { read=FOnError, write=FOnError };

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

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

Syntax

typedef struct {
  String EventID;
  String EventParam;
} TsbxPGPKeyringNotificationEventParams;
typedef void __fastcall (__closure *TsbxPGPKeyringNotificationEvent)(System::TObject* Sender, TsbxPGPKeyringNotificationEventParams *e);
__property TsbxPGPKeyringNotificationEvent OnNotification = { read=FOnNotification, write=FOnNotification };

Remarks

The component 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 the 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.

Config Settings (PGPKeyring Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

PGPKeyring Config Settings

Base Config Settings

Trappable Errors (PGPKeyring Component)

PGPKeyring Errors