PGPKeyring Class

Properties   Methods   Events   Config Settings   Errors  

The PGPKeyring class manages PGP keyring files.

Class Name

SecureBlackbox_PGPKeyring

Procedural Interface

 secureblackbox_pgpkeyring_open();
 secureblackbox_pgpkeyring_close($res);
 secureblackbox_pgpkeyring_register_callback($res, $id, $function);
 secureblackbox_pgpkeyring_get_last_error($res);
 secureblackbox_pgpkeyring_get_last_error_code($res);
 secureblackbox_pgpkeyring_set($res, $id, $index, $value);
 secureblackbox_pgpkeyring_get($res, $id, $index);
 secureblackbox_pgpkeyring_do_config($res, $configurationstring);
 secureblackbox_pgpkeyring_do_doaction($res, $actionid, $actionparams);
 secureblackbox_pgpkeyring_do_exportbytes($res, $secret);
 secureblackbox_pgpkeyring_do_exporttofile($res, $filename, $secret);
 secureblackbox_pgpkeyring_do_importbytes($res, $keyring);
 secureblackbox_pgpkeyring_do_importfromfile($res, $keyringfile);
 secureblackbox_pgpkeyring_do_importpinned($res);
 secureblackbox_pgpkeyring_do_remove($res, $index);
 secureblackbox_pgpkeyring_do_removebyid($res, $keyid);
 secureblackbox_pgpkeyring_do_reset($res);
 secureblackbox_pgpkeyring_do_select($res, $filter, $secretonly, $maxcount);
 secureblackbox_pgpkeyring_do_updatepinned($res);

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

KeyCount Property (SecureBlackbox_PGPKeyring Class)

The number of records in the Key arrays.

Object Oriented Interface

public function getKeyCount();

Procedural Interface

secureblackbox_pgpkeyring_get($res, 1 );

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

Indicates the key length in bits.

Object Oriented Interface

public function getKeyBitsInKey($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 2 , $keyindex);

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

Returns True if this key can be used for encryption.

Object Oriented Interface

public function getKeyCanEncrypt($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 3 , $keyindex);

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

Returns True if this key can be used for signing.

Object Oriented Interface

public function getKeyCanSign($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 4 , $keyindex);

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

Indicates the elliptic curve associated with a EC key.

Object Oriented Interface

public function getKeyCurve($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 5 , $keyindex);

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

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

Object Oriented Interface

public function getKeyEnabled($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 6 , $keyindex);

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

Indicates the symmetric algorithm used to encrypt the secret key.

Object Oriented Interface

public function getKeyEncryptionAlgorithm($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 7 , $keyindex);

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

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

Object Oriented Interface

public function getKeyHandle($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 8 , $keyindex);

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

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

Object Oriented Interface

public function getKeyIsPublic($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 9 , $keyindex);

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

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

Object Oriented Interface

public function getKeyIsSecret($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 10 , $keyindex);

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

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

Object Oriented Interface

public function getKeyIsSubkey($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 11 , $keyindex);

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

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

Object Oriented Interface

public function getKeyKeyFP($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 12 , $keyindex);

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

Contains a 8-byte key identifier.

Object Oriented Interface

public function getKeyKeyID($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 13 , $keyindex);

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

The key protection password.

Object Oriented Interface

public function getKeyPassphrase($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 14 , $keyindex);

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

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

Object Oriented Interface

public function getKeyPassphraseValid($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 15 , $keyindex);

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

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

Object Oriented Interface

public function getKeyPrimaryKeyID($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 16 , $keyindex);

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

Specifies the level of protection applied to the secret key.

Object Oriented Interface

public function getKeyProtection($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 17 , $keyindex);

Default Value

0

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

Specifies the asymmetric algorithm of the key.

Object Oriented Interface

public function getKeyPublicKeyAlgorithm($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 18 , $keyindex);

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

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

Object Oriented Interface

public function getKeyQBits($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 19 , $keyindex);

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

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

Object Oriented Interface

public function getKeyTimestamp($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 20 , $keyindex);

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

Specifies the name of the user bound to this key.

Object Oriented Interface

public function getKeyUsername($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 21 , $keyindex);

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

Provide accurate expiration moment indication.

Object Oriented Interface

public function getKeyValidTo($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 22 , $keyindex);

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

Indicates the key version.

Object Oriented Interface

public function getKeyVersion($keyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 23 , $keyindex);

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

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

Object Oriented Interface

public function getPinnedKeyHandle();
public function setPinnedKeyHandle($value);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 30 );
secureblackbox_pgpkeyring_set($res, 30, $value );

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

The number of records in the SelectedKey arrays.

Object Oriented Interface

public function getSelectedKeyCount();

Procedural Interface

secureblackbox_pgpkeyring_get($res, 46 );

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

Indicates the key length in bits.

Object Oriented Interface

public function getSelectedKeyBitsInKey($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 47 , $selectedkeyindex);

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

Returns True if this key can be used for encryption.

Object Oriented Interface

public function getSelectedKeyCanEncrypt($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 48 , $selectedkeyindex);

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

Returns True if this key can be used for signing.

Object Oriented Interface

public function getSelectedKeyCanSign($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 49 , $selectedkeyindex);

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

Indicates the elliptic curve associated with a EC key.

Object Oriented Interface

public function getSelectedKeyCurve($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 50 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyEnabled($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 51 , $selectedkeyindex);

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

Indicates the symmetric algorithm used to encrypt the secret key.

Object Oriented Interface

public function getSelectedKeyEncryptionAlgorithm($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 52 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyHandle($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 53 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyIsPublic($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 54 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyIsSecret($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 55 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyIsSubkey($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 56 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyKeyFP($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 57 , $selectedkeyindex);

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

Contains a 8-byte key identifier.

Object Oriented Interface

public function getSelectedKeyKeyID($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 58 , $selectedkeyindex);

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

The key protection password.

Object Oriented Interface

public function getSelectedKeyPassphrase($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 59 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyPassphraseValid($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 60 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyPrimaryKeyID($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 61 , $selectedkeyindex);

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

Specifies the level of protection applied to the secret key.

Object Oriented Interface

public function getSelectedKeyProtection($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 62 , $selectedkeyindex);

Default Value

0

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

Specifies the asymmetric algorithm of the key.

Object Oriented Interface

public function getSelectedKeyPublicKeyAlgorithm($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 63 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyQBits($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 64 , $selectedkeyindex);

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

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

Object Oriented Interface

public function getSelectedKeyTimestamp($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 65 , $selectedkeyindex);

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

Specifies the name of the user bound to this key.

Object Oriented Interface

public function getSelectedKeyUsername($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 66 , $selectedkeyindex);

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

Provide accurate expiration moment indication.

Object Oriented Interface

public function getSelectedKeyValidTo($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 67 , $selectedkeyindex);

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

Indicates the key version.

Object Oriented Interface

public function getSelectedKeyVersion($selectedkeyindex);

Procedural Interface

secureblackbox_pgpkeyring_get($res, 68 , $selectedkeyindex);

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

Sets or retrieves a configuration setting.

Object Oriented Interface

public function doConfig($configurationstring);

Procedural Interface

secureblackbox_pgpkeyring_do_config($res, $configurationstring);

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.

DoAction Method (SecureBlackbox_PGPKeyring Class)

Performs an additional action.

Object Oriented Interface

public function doDoAction($actionid, $actionparams);

Procedural Interface

secureblackbox_pgpkeyring_do_doaction($res, $actionid, $actionparams);

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:

ExportBytes Method (SecureBlackbox_PGPKeyring Class)

Exports the keyring to a byte array.

Object Oriented Interface

public function doExportBytes($secret);

Procedural Interface

secureblackbox_pgpkeyring_do_exportbytes($res, $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 (SecureBlackbox_PGPKeyring Class)

Exports the keyring to disk.

Object Oriented Interface

public function doExportToFile($filename, $secret);

Procedural Interface

secureblackbox_pgpkeyring_do_exporttofile($res, $filename, $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 (SecureBlackbox_PGPKeyring Class)

Loads a key from a byte array.

Object Oriented Interface

public function doImportBytes($keyring);

Procedural Interface

secureblackbox_pgpkeyring_do_importbytes($res, $keyring);

Remarks

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

ImportFromFile Method (SecureBlackbox_PGPKeyring Class)

Loads a key from a file.

Object Oriented Interface

public function doImportFromFile($keyringfile);

Procedural Interface

secureblackbox_pgpkeyring_do_importfromfile($res, $keyringfile);

Remarks

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

ImportPinned Method (SecureBlackbox_PGPKeyring Class)

Imports a pinned secret key to the keyring.

Object Oriented Interface

public function doImportPinned();

Procedural Interface

secureblackbox_pgpkeyring_do_importpinned($res);

Remarks

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

Remove Method (SecureBlackbox_PGPKeyring Class)

Removes the specified key from the keyring.

Object Oriented Interface

public function doRemove($index);

Procedural Interface

secureblackbox_pgpkeyring_do_remove($res, $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 (SecureBlackbox_PGPKeyring Class)

Removes key by its ID.

Object Oriented Interface

public function doRemoveByID($keyid);

Procedural Interface

secureblackbox_pgpkeyring_do_removebyid($res, $keyid);

Remarks

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

Reset Method (SecureBlackbox_PGPKeyring Class)

Creates a new empty keyring.

Object Oriented Interface

public function doReset();

Procedural Interface

secureblackbox_pgpkeyring_do_reset($res);

Remarks

Use this method to initialize a new empty keyring.

Select Method (SecureBlackbox_PGPKeyring Class)

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

Object Oriented Interface

public function doSelect($filter, $secretonly, $maxcount);

Procedural Interface

secureblackbox_pgpkeyring_do_select($res, $filter, $secretonly, $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 (SecureBlackbox_PGPKeyring Class)

Update a pinned key in the keyring.

Object Oriented Interface

public function doUpdatePinned();

Procedural Interface

secureblackbox_pgpkeyring_do_updatepinned($res);

Remarks

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

Error Event (SecureBlackbox_PGPKeyring Class)

Information about errors during PGP key management.

Object Oriented Interface

public function fireError($param);

Procedural Interface

secureblackbox_pgpkeyring_register_callback($res, 1, array($this, 'fireError'));

Parameter List

 'errorcode'
 'description'

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

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

Object Oriented Interface

public function fireNotification($param);

Procedural Interface

secureblackbox_pgpkeyring_register_callback($res, 2, array($this, 'fireNotification'));

Parameter List

 'eventid'
 'eventparam'

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.

Config Settings (PGPKeyring Class)

The class 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 class, access to these internal properties is provided through the Config method.

PGPKeyring Config Settings

Base Config Settings

Trappable Errors (PGPKeyring Class)

PGPKeyring Errors