PGPKeyring Component
Properties Methods Events Config Settings Errors
The PGPKeyring class manages PGP keyring files.
Syntax
secureblackbox.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 component with short descriptions. Click on the links for further details.
| KeyCount | The number of records in the Key arrays. |
| KeyBitsInKey | Indicates the key length in bits. |
| KeyCanEncrypt | Returns True if this key can be used for encryption. |
| KeyCanSign | Returns True if this key can be used for signing. |
| KeyCurve | Indicates the elliptic curve associated with a EC key. |
| KeyEnabled | Enables or disables this key for use in encryption or signing operation. |
| KeyEncryptionAlgorithm | Indicates the symmetric algorithm used to encrypt the secret key. |
| KeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| KeyIsPublic | Returns True if this key is a public key, and False otherwise. |
| KeyIsSecret | Returns True if this key is a secret key, and False otherwise. |
| KeyIsSubkey | Returns True if this key is a subkey of another key, and False otherwise. |
| KeyFP | The 20-byte fingerprint (hash value) of this key. |
| KeyID | Contains a 8-byte key identifier. |
| KeyPassphrase | The key protection password. |
| KeyPassphraseValid | Use this property to check whether the specified Passphrase is valid and can be used to unlock the secret key. |
| KeyPrimaryKeyID | If this key is a subkey ( IsSubkey returns True), this property contains the identifier of the subkey's primary key. |
| KeyProtection | Specifies the level of protection applied to the secret key. |
| KeyPublicKeyAlgorithm | Specifies the asymmetric algorithm of the key. |
| KeyQBits | The length of the DSA Q (legitimate range: 160-512). |
| KeyTimestamp | Use this property to check the time the key was generated. |
| KeyUsername | Specifies the name of the user bound to this key. |
| KeyValidTo | Provide accurate expiration moment indication. |
| KeyVersion | Indicates the key version. |
| PinnedKeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| SelectedKeyCount | The number of records in the SelectedKey arrays. |
| SelectedKeyBitsInKey | Indicates the key length in bits. |
| SelectedKeyCanEncrypt | Returns True if this key can be used for encryption. |
| SelectedKeyCanSign | Returns True if this key can be used for signing. |
| SelectedKeyCurve | Indicates the elliptic curve associated with a EC key. |
| SelectedKeyEnabled | Enables or disables this key for use in encryption or signing operation. |
| SelectedKeyEncryptionAlgorithm | Indicates the symmetric algorithm used to encrypt the secret key. |
| SelectedKeyHandle | Allows to get or set a 'handle', a unique identifier of the underlying property object. |
| SelectedKeyIsPublic | Returns True if this key is a public key, and False otherwise. |
| SelectedKeyIsSecret | Returns True if this key is a secret key, and False otherwise. |
| SelectedKeyIsSubkey | Returns True if this key is a subkey of another key, and False otherwise. |
| SelectedKeyKeyFP | The 20-byte fingerprint (hash value) of this key. |
| SelectedKeyKeyID | Contains a 8-byte key identifier. |
| SelectedKeyPassphrase | The key protection password. |
| SelectedKeyPassphraseValid | Use this property to check whether the specified Passphrase is valid and can be used to unlock the secret key. |
| SelectedKeyPrimaryKeyID | If this key is a subkey ( IsSubkey returns True), this property contains the identifier of the subkey's primary key. |
| SelectedKeyProtection | Specifies the level of protection applied to the secret key. |
| SelectedKeyPublicKeyAlgorithm | Specifies the asymmetric algorithm of the key. |
| SelectedKeyQBits | The length of the DSA Q (legitimate range: 160-512). |
| SelectedKeyTimestamp | Use this property to check the time the key was generated. |
| SelectedKeyUsername | Specifies the name of the user bound to this key. |
| SelectedKeyValidTo | Provide accurate expiration moment indication. |
| SelectedKeyVersion | Indicates the key version. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
| Config | Sets or retrieves a configuration setting. |
| DoAction | Performs an additional action. |
| ExportBytes | Exports the keyring to a byte array. |
| ExportToFile | Exports the keyring to disk. |
| ImportBytes | Loads a key from a byte array. |
| ImportFromFile | Loads a key from a file. |
| ImportPinned | Imports a pinned secret key to the keyring. |
| Remove | Removes the specified key from the keyring. |
| RemoveByID | Removes key by its ID. |
| Reset | Creates a new empty keyring. |
| Select | Filters a selection of keys from the keyring using a template. |
| UpdatePinned | Update a pinned key in the keyring. |
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.
| Error | Information about errors during PGP key management. |
| Notification | This event notifies the application about an underlying control flow event. |
Config Settings
The following is a list of config settings for the component with short descriptions. Click on the links for further details.
| Armor | Enables or disables ASCII armouring. |
| ArmorBoundary | Specifies the armour boundary/title. |
| ArmorHeaders | Specifies armour headers. |
| RespectKeyUsage | Enables policy-based key usage checks. |
| SaveKeyTrust | Tells the class to include the trust packets with the serialized keys. |
| SaveSecretKeySignatures | Enforces saving of signature packets to the secret keyring file. |
| UseLongKeyIDs | Enables long (8-byte) KeyID representation. |
| ASN1UseGlobalTagCache | Controls whether ASN.1 module should use a global object cache. |
| AssignSystemSmartCardPins | Specifies whether CSP-level PINs should be assigned to CNG keys. |
| CheckKeyIntegrityBeforeUse | Enables or disable private key integrity check before use. |
| CookieCaching | Specifies whether a cookie cache should be used for HTTP(S) transports. |
| Cookies | Gets or sets local cookies for the class. |
| DefDeriveKeyIterations | Specifies the default key derivation algorithm iteration count. |
| DNSLocalSuffix | The suffix to assign for TLD names. |
| EnableClientSideSSLFFDHE | Enables or disables finite field DHE key exchange support in TLS clients. |
| EnableSSHMLKEM | Enables support for ML-KEM/hybrid key exchange algorithms in SSH client and server classes. |
| EnableTLSMLKEM | Enables support for ML-KEM and hybrid groups in TLS client and server classes. |
| GlobalCookies | Gets or sets global cookies for all the HTTP transports. |
| HardwareCryptoUsePolicy | The hardware crypto usage policy. |
| HttpUserAgent | Specifies the user agent name to be used by all HTTP clients. |
| HttpVersion | The HTTP version to use in any inner HTTP client classes created. |
| IgnoreExpiredMSCTLSigningCert | Whether to tolerate the expired Windows Update signing certificate. |
| ListDelimiter | The delimiter character for multi-element lists. |
| LogDestination | Specifies the debug log destination. |
| LogDetails | Specifies the debug log details to dump. |
| LogFile | Specifies the debug log filename. |
| LogFilters | Specifies the debug log filters. |
| LogFlushMode | Specifies the log flush mode. |
| LogLevel | Specifies the debug log level. |
| LogMaxEventCount | Specifies the maximum number of events to cache before further action is taken. |
| LogRotationMode | Specifies the log rotation mode. |
| MaxASN1BufferLength | Specifies the maximal allowed length for ASN.1 primitive tag data. |
| MaxASN1TreeDepth | Specifies the maximal depth for processed ASN.1 trees. |
| OCSPHashAlgorithm | Specifies the hash algorithm to be used to identify certificates in OCSP requests. |
| OldClientSideRSAFallback | Specifies whether the SSH client should use a SHA1 fallback. |
| PKICache | Specifies which PKI elements (certificates, CRLs, OCSP responses) should be cached. |
| PKICachePath | Specifies the file system path where cached PKI data is stored. |
| ProductVersion | Returns the version of the SecureBlackbox library. |
| ServerSSLDHKeyLength | Sets the size of the TLS DHE key exchange group. |
| StaticDNS | Specifies whether static DNS rules should be used. |
| StaticIPAddress[domain] | Gets or sets an IP address for the specified domain name. |
| StaticIPAddresses | Gets or sets all the static DNS rules. |
| Tag | Allows to store any custom data. |
| TLSSessionGroup | Specifies the group name of TLS sessions to be used for session resumption. |
| TLSSessionLifetime | Specifies lifetime in seconds of the cached TLS session. |
| TLSSessionPurgeInterval | Specifies how often the session cache should remove the expired TLS sessions. |
| UseCRLObjectCaching | Specifies whether reuse of loaded CRL objects is enabled. |
| UseInternalRandom | Switches between SecureBlackbox-own and platform PRNGs. |
| UseLegacyAdESValidation | Enables legacy AdES validation mode. |
| UseOCSPResponseObjectCaching | Specifies whether reuse of loaded OCSP response objects is enabled. |
| UseOwnDNSResolver | Specifies whether the client classes should use own DNS resolver. |
| UseSharedSystemStorages | Specifies whether the validation engine should use a global per-process copy of the system certificate stores. |
| UseSystemNativeSizeCalculation | An internal CryptoAPI access tweak. |
| UseSystemOAEPAndPSS | Enforces or disables the use of system-driven RSA OAEP and PSS computations. |
| UseSystemRandom | Enables or disables the use of the OS PRNG. |
| XMLRDNDescriptorName[OID] | Defines an OID mapping to descriptor names for the certificate's IssuerRDN or SubjectRDN. |
| XMLRDNDescriptorPriority[OID] | Specifies the priority of descriptor names associated with a specific OID. |
| XMLRDNDescriptorReverseOrder | Specifies whether to reverse the order of descriptors in RDN. |
| XMLRDNDescriptorSeparator | Specifies the separator used between descriptors in RDN. |
KeyCount Property (PGPKeyring Component)
The number of records in the Key arrays.
Syntax
func (obj *PGPKeyring) KeyCount() (int32, error)
Default Value
0
Remarks
This property controls the size of the following arrays:
- KeyBitsInKey
- KeyCanEncrypt
- KeyCanSign
- KeyCurve
- KeyEnabled
- KeyEncryptionAlgorithm
- KeyFP
- KeyHandle
- KeyID
- KeyIsPublic
- KeyIsSecret
- KeyIsSubkey
- KeyPassphrase
- KeyPassphraseValid
- KeyPrimaryKeyID
- KeyProtection
- KeyPublicKeyAlgorithm
- KeyQBits
- KeyTimestamp
- KeyUsername
- KeyValidTo
- KeyVersion
This property is read-only.
Data Type
int32
KeyBitsInKey Property (PGPKeyring Component)
Indicates the key length in bits.
Syntax
func (obj *PGPKeyring) KeyBitsInKey(KeyIndex int32) (int32, error)
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.
Data Type
int32
KeyCanEncrypt Property (PGPKeyring Component)
Returns True if this key can be used for encryption.
Syntax
func (obj *PGPKeyring) KeyCanEncrypt(KeyIndex int32) (bool, error)
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.
Data Type
bool
KeyCanSign Property (PGPKeyring Component)
Returns True if this key can be used for signing.
Syntax
func (obj *PGPKeyring) KeyCanSign(KeyIndex int32) (bool, error)
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.
Data Type
bool
KeyCurve Property (PGPKeyring Component)
Indicates the elliptic curve associated with a EC key.
Syntax
func (obj *PGPKeyring) KeyCurve(KeyIndex int32) (string, error)
Default Value
""
Remarks
Indicates the elliptic curve associated with a EC key.
Supported values:
| SB_PGP_CURVE_P256 | P256 | |
| SB_PGP_CURVE_P384 | P384 | |
| SB_PGP_CURVE_P521 | P521 | |
| SB_PGP_CURVE_ED25519 | ED25519 | |
| SB_PGP_CURVE_CURVE25519 | CURVE25519 | |
| SB_PGP_CURVE_BRAINPOOLP256R1 | BRAINPOOLP256 | |
| SB_PGP_CURVE_BRAINPOOLP512R1 | BRAINPOOLP512 |
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.
Data Type
string
KeyEnabled Property (PGPKeyring Component)
Enables or disables this key for use in encryption or signing operation.
Syntax
func (obj *PGPKeyring) KeyEnabled(KeyIndex int32) (bool, error)
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.
Data Type
bool
KeyEncryptionAlgorithm Property (PGPKeyring Component)
Indicates the symmetric algorithm used to encrypt the secret key.
Syntax
func (obj *PGPKeyring) KeyEncryptionAlgorithm(KeyIndex int32) (string, error)
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.
Data Type
string
KeyHandle Property (PGPKeyring Component)
Allows to get or set a 'handle', a unique identifier of the underlying property object.
Syntax
func (obj *PGPKeyring) KeyHandle(KeyIndex int32) (int64, error)
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.
Data Type
int64
KeyIsPublic Property (PGPKeyring Component)
Returns True if this key is a public key, and False otherwise.
Syntax
func (obj *PGPKeyring) KeyIsPublic(KeyIndex int32) (bool, error)
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.
Data Type
bool
KeyIsSecret Property (PGPKeyring Component)
Returns True if this key is a secret key, and False otherwise.
Syntax
func (obj *PGPKeyring) KeyIsSecret(KeyIndex int32) (bool, error)
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.
Data Type
bool
KeyIsSubkey Property (PGPKeyring Component)
Returns True if this key is a subkey of another key, and False otherwise.
Syntax
func (obj *PGPKeyring) KeyIsSubkey(KeyIndex int32) (bool, error)
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.
Data Type
bool
KeyFP Property (PGPKeyring Component)
The 20-byte fingerprint (hash value) of this key.
Syntax
func (obj *PGPKeyring) KeyFP(KeyIndex int32) (string, error)
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.
Data Type
string
KeyID Property (PGPKeyring Component)
Contains a 8-byte key identifier.
Syntax
func (obj *PGPKeyring) KeyID(KeyIndex int32) (string, error)
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.
Data Type
string
KeyPassphrase Property (PGPKeyring Component)
The key protection password.
Syntax
func (obj *PGPKeyring) KeyPassphrase(KeyIndex int32) (string, error)
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.
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
func (obj *PGPKeyring) KeyPassphraseValid(KeyIndex int32) (bool, error)
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.
Data Type
bool
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
func (obj *PGPKeyring) KeyPrimaryKeyID(KeyIndex int32) (string, error)
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.
Data Type
string
KeyProtection Property (PGPKeyring Component)
Specifies the level of protection applied to the secret key.
Syntax
func (obj *PGPKeyring) KeyProtection(KeyIndex int32) (int32, error)
Possible Values
0 // None
1 // Low
2 // Normal
3 // High
Default Value
0
Remarks
Specifies the level of protection applied to the secret key.
Allowed values:
| pptNone | 0 | Key is not encrypted |
| pptLow | 1 | Only the password hash is used to derive the secret key |
| pptNormal | 2 | Password hash with salt is used to derive the secret key |
| pptHigh | 3 | Hash from multiple passwords and salt are used for key derivation |
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.
Data Type
int32
KeyPublicKeyAlgorithm Property (PGPKeyring Component)
Specifies the asymmetric algorithm of the key.
Syntax
func (obj *PGPKeyring) KeyPublicKeyAlgorithm(KeyIndex int32) (string, error)
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.
Data Type
string
KeyQBits Property (PGPKeyring Component)
The length of the DSA Q (legitimate range: 160-512).
Syntax
func (obj *PGPKeyring) KeyQBits(KeyIndex int32) (int32, error)
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.
Data Type
int32
KeyTimestamp Property (PGPKeyring Component)
Use this property to check the time the key was generated.
Syntax
func (obj *PGPKeyring) KeyTimestamp(KeyIndex int32) (string, error)
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.
Data Type
string
KeyUsername Property (PGPKeyring Component)
Specifies the name of the user bound to this key.
Syntax
func (obj *PGPKeyring) KeyUsername(KeyIndex int32) (string, error)
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.
Data Type
string
KeyValidTo Property (PGPKeyring Component)
Provide accurate expiration moment indication.
Syntax
func (obj *PGPKeyring) KeyValidTo(KeyIndex int32) (string, error)
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.
Data Type
string
KeyVersion Property (PGPKeyring Component)
Indicates the key version.
Syntax
func (obj *PGPKeyring) KeyVersion(KeyIndex int32) (int32, error)
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.
Data Type
int32
PinnedKeyHandle Property (PGPKeyring Component)
Allows to get or set a 'handle', a unique identifier of the underlying property object.
Syntax
func (obj *PGPKeyring) PinnedKeyHandle() (int64, error)
func (obj *PGPKeyring) SetPinnedKeyHandle(value int64) error
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());
Data Type
int64
SelectedKeyCount Property (PGPKeyring Component)
The number of records in the SelectedKey arrays.
Syntax
func (obj *PGPKeyring) SelectedKeyCount() (int32, error)
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
This property is read-only.
Data Type
int32
SelectedKeyBitsInKey Property (PGPKeyring Component)
Indicates the key length in bits.
Syntax
func (obj *PGPKeyring) SelectedKeyBitsInKey(SelectedKeyIndex int32) (int32, error)
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.
Data Type
int32
SelectedKeyCanEncrypt Property (PGPKeyring Component)
Returns True if this key can be used for encryption.
Syntax
func (obj *PGPKeyring) SelectedKeyCanEncrypt(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
SelectedKeyCanSign Property (PGPKeyring Component)
Returns True if this key can be used for signing.
Syntax
func (obj *PGPKeyring) SelectedKeyCanSign(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
SelectedKeyCurve Property (PGPKeyring Component)
Indicates the elliptic curve associated with a EC key.
Syntax
func (obj *PGPKeyring) SelectedKeyCurve(SelectedKeyIndex int32) (string, error)
Default Value
""
Remarks
Indicates the elliptic curve associated with a EC key.
Supported values:
| SB_PGP_CURVE_P256 | P256 | |
| SB_PGP_CURVE_P384 | P384 | |
| SB_PGP_CURVE_P521 | P521 | |
| SB_PGP_CURVE_ED25519 | ED25519 | |
| SB_PGP_CURVE_CURVE25519 | CURVE25519 | |
| SB_PGP_CURVE_BRAINPOOLP256R1 | BRAINPOOLP256 | |
| SB_PGP_CURVE_BRAINPOOLP512R1 | BRAINPOOLP512 |
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.
Data Type
string
SelectedKeyEnabled Property (PGPKeyring Component)
Enables or disables this key for use in encryption or signing operation.
Syntax
func (obj *PGPKeyring) SelectedKeyEnabled(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
SelectedKeyEncryptionAlgorithm Property (PGPKeyring Component)
Indicates the symmetric algorithm used to encrypt the secret key.
Syntax
func (obj *PGPKeyring) SelectedKeyEncryptionAlgorithm(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyHandle Property (PGPKeyring Component)
Allows to get or set a 'handle', a unique identifier of the underlying property object.
Syntax
func (obj *PGPKeyring) SelectedKeyHandle(SelectedKeyIndex int32) (int64, error)
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.
Data Type
int64
SelectedKeyIsPublic Property (PGPKeyring Component)
Returns True if this key is a public key, and False otherwise.
Syntax
func (obj *PGPKeyring) SelectedKeyIsPublic(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
SelectedKeyIsSecret Property (PGPKeyring Component)
Returns True if this key is a secret key, and False otherwise.
Syntax
func (obj *PGPKeyring) SelectedKeyIsSecret(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
SelectedKeyIsSubkey Property (PGPKeyring Component)
Returns True if this key is a subkey of another key, and False otherwise.
Syntax
func (obj *PGPKeyring) SelectedKeyIsSubkey(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
SelectedKeyKeyFP Property (PGPKeyring Component)
The 20-byte fingerprint (hash value) of this key.
Syntax
func (obj *PGPKeyring) SelectedKeyKeyFP(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyKeyID Property (PGPKeyring Component)
Contains a 8-byte key identifier.
Syntax
func (obj *PGPKeyring) SelectedKeyKeyID(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyPassphrase Property (PGPKeyring Component)
The key protection password.
Syntax
func (obj *PGPKeyring) SelectedKeyPassphrase(SelectedKeyIndex int32) (string, error)
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.
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
func (obj *PGPKeyring) SelectedKeyPassphraseValid(SelectedKeyIndex int32) (bool, error)
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.
Data Type
bool
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
func (obj *PGPKeyring) SelectedKeyPrimaryKeyID(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyProtection Property (PGPKeyring Component)
Specifies the level of protection applied to the secret key.
Syntax
func (obj *PGPKeyring) SelectedKeyProtection(SelectedKeyIndex int32) (int32, error)
Possible Values
0 // None
1 // Low
2 // Normal
3 // High
Default Value
0
Remarks
Specifies the level of protection applied to the secret key.
Allowed values:
| pptNone | 0 | Key is not encrypted |
| pptLow | 1 | Only the password hash is used to derive the secret key |
| pptNormal | 2 | Password hash with salt is used to derive the secret key |
| pptHigh | 3 | Hash from multiple passwords and salt are used for key derivation |
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.
Data Type
int32
SelectedKeyPublicKeyAlgorithm Property (PGPKeyring Component)
Specifies the asymmetric algorithm of the key.
Syntax
func (obj *PGPKeyring) SelectedKeyPublicKeyAlgorithm(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyQBits Property (PGPKeyring Component)
The length of the DSA Q (legitimate range: 160-512).
Syntax
func (obj *PGPKeyring) SelectedKeyQBits(SelectedKeyIndex int32) (int32, error)
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.
Data Type
int32
SelectedKeyTimestamp Property (PGPKeyring Component)
Use this property to check the time the key was generated.
Syntax
func (obj *PGPKeyring) SelectedKeyTimestamp(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyUsername Property (PGPKeyring Component)
Specifies the name of the user bound to this key.
Syntax
func (obj *PGPKeyring) SelectedKeyUsername(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyValidTo Property (PGPKeyring Component)
Provide accurate expiration moment indication.
Syntax
func (obj *PGPKeyring) SelectedKeyValidTo(SelectedKeyIndex int32) (string, error)
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.
Data Type
string
SelectedKeyVersion Property (PGPKeyring Component)
Indicates the key version.
Syntax
func (obj *PGPKeyring) SelectedKeyVersion(SelectedKeyIndex int32) (int32, error)
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.
Data Type
int32
Config Method (PGPKeyring Component)
Sets or retrieves a configuration setting.
Syntax
func (obj *PGPKeyring) Config(ConfigurationString string) (string, error)
Remarks
Config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, 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
func (obj *PGPKeyring) DoAction(ActionID string, ActionParams string) (string, error)
Remarks
DoAction is a generic method available in every struct. 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:
| Action | Parameters | Returned value | Description |
| ResetTrustedListCache | none | none | Clears the cached list of trusted lists. |
| ResetCertificateCache | none | none | Clears the cached certificates. |
| ResetCRLCache | none | none | Clears the cached CRLs. |
| ResetOCSPResponseCache | none | none | Clears the cached OCSP responses. |
ExportBytes Method (PGPKeyring Component)
Exports the keyring to a byte array.
Syntax
func (obj *PGPKeyring) ExportBytes(Secret bool) ([]byte, error)
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
func (obj *PGPKeyring) ExportToFile(FileName string, Secret bool) error
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
func (obj *PGPKeyring) ImportBytes(Keyring []byte) error
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
func (obj *PGPKeyring) ImportFromFile(KeyringFile string) error
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
func (obj *PGPKeyring) ImportPinned() error
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
func (obj *PGPKeyring) Remove(Index int32) error
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
func (obj *PGPKeyring) RemoveByID(KeyID string) error
Remarks
Call this method to remove the specified key from the keyring.
Reset Method (PGPKeyring Component)
Creates a new empty keyring.
Syntax
func (obj *PGPKeyring) Reset() error
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
func (obj *PGPKeyring) Select(Filter string, SecretOnly bool, MaxCount int32) error
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
func (obj *PGPKeyring) UpdatePinned() error
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
// PGPKeyringErrorEventArgs carries the PGPKeyring Error event's parameters.
type PGPKeyringErrorEventArgs struct {...}
func (args *PGPKeyringErrorEventArgs) ErrorCode() int32
func (args *PGPKeyringErrorEventArgs) Description() string
// PGPKeyringErrorEvent defines the signature of the PGPKeyring Error event's handler function.
type PGPKeyringErrorEvent func(sender *PGPKeyring, args *PGPKeyringErrorEventArgs)
func (obj *PGPKeyring) GetOnErrorHandler() PGPKeyringErrorEvent
func (obj *PGPKeyring) SetOnErrorHandler(handlerFunc PGPKeyringErrorEvent)
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
// PGPKeyringNotificationEventArgs carries the PGPKeyring Notification event's parameters.
type PGPKeyringNotificationEventArgs struct {...}
func (args *PGPKeyringNotificationEventArgs) EventID() string
func (args *PGPKeyringNotificationEventArgs) EventParam() string
// PGPKeyringNotificationEvent defines the signature of the PGPKeyring Notification event's handler function.
type PGPKeyringNotificationEvent func(sender *PGPKeyring, args *PGPKeyringNotificationEventArgs)
func (obj *PGPKeyring) GetOnNotificationHandler() PGPKeyringNotificationEvent
func (obj *PGPKeyring) SetOnNotificationHandler(handlerFunc PGPKeyringNotificationEvent)
Remarks
The struct fires this event to let the application know about some event, occurrence, or milestone in the struct. 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 struct, the exact action it is performing, or the document being processed, one or both may be omitted.
Config Settings (PGPKeyring Component)
The struct 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 struct, access to these internal properties is provided through the Config method.PGPKeyring Config Settings
Base Config Settings
You can switch this property off to improve performance if your project only uses known, good private keys.
Supported values are:
| off | No caching (default) | |
| local | Local caching | |
| global | Global caching |
This setting only applies to sessions negotiated with TLS version 1.3.
Supported Values:
| auto | Use hardware cryptography if available; otherwise, fall back to software-based cryptography (default). |
| enable | Always attempt to use hardware cryptography. If unavailable, exception will be thrown. |
| disable | Do not use hardware cryptography. |
Supported values are:
| file | File | |
| console | Console | |
| systemlog | System Log (supported for Android only) | |
| debugger | Debugger (supported for VCL for Windows and .Net) |
Supported values are:
| time | Current time | |
| level | Level | |
| package | Package name | |
| module | Module name | |
| class | Class name | |
| method | Method name | |
| threadid | Thread Id | |
| contenttype | Content type | |
| content | Content | |
| all | All details |
Supported filter names are:
| exclude-package | Exclude a package specified in the value | |
| exclude-module | Exclude a module specified in the value | |
| exclude-class | Exclude a class specified in the value | |
| exclude-method | Exclude a method specified in the value | |
| include-package | Include a package specified in the value | |
| include-module | Include a module specified in the value | |
| include-class | Include a class specified in the value | |
| include-method | Include a method specified in the value |
| none | No flush (caching only) | |
| immediate | Immediate flush (real-time logging) | |
| maxcount | Flush cached entries upon reaching LogMaxEventCount entries in the cache. |
Supported values are:
| none | None (by default) | |
| fatal | Severe errors that cause premature termination. | |
| error | Other runtime errors or unexpected conditions. | |
| warning | Use of deprecated APIs, poor use of API, 'almost' errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong". | |
| info | Interesting runtime events (startup/shutdown). | |
| debug | Detailed information on flow of through the system. | |
| trace | More detailed information. |
The default value of this setting is 100.
| none | No rotation | |
| deleteolder | Delete older entries from the cache upon reaching LogMaxEventCount | |
| keepolder | Keep older entries in the cache upon reaching LogMaxEventCount (newer entries are discarded) |
Supported Values:
| certificate | Enables caching of certificates. |
| crl | Enables caching of Certificate Revocation Lists (CRLs). |
| ocsp | Enables caching of OCSP (Online Certificate Status Protocol) responses. |
Example (default value):
PKICache=certificate,crl,ocsp
In this example, the component caches certificates, CRLs, and OCSP responses.
The default value is an empty string - no cached PKI data is stored on disk.
Example:
PKICachePath=C:\Temp\cache
In this example, the cached PKI data is stored in the C:\Temp\cache directory.
Supported values are:
| none | No static DNS rules (default) | |
| local | Local static DNS rules | |
| global | Global static DNS rules |
This setting only applies to certificates originating from a Windows system store.
The property accepts comma-separated values where the first descriptor name is used when the OID is mapped, and subsequent values act as aliases for parsing.
Syntax:
Config("XMLRDNDescriptorName[OID]=PrimaryName,Alias1,Alias2");
Where:
OID: The Object Identifier from the certificate's IssuerRDN or SubjectRDN that you want to map.
PrimaryName: The main descriptor name used in the XML signature when the OID is encountered.
Alias1, Alias2, ...: Optional alternative names recognized during parsing.
Usage Examples:
Map OID 2.5.4.5 to SERIALNUMBER:
Config("XMLRDNDescriptorName[2.5.4.5]=SERIALNUMBER");
Map OID 1.2.840.113549.1.9.1 to E, with aliases EMAIL and EMAILADDRESS:
Config("XMLRDNDescriptorName[1.2.840.113549.1.9.1]=E,EMAIL,EMAILADDRESS");
Trappable Errors (PGPKeyring Component)
PGPKeyring Errors
| 1048577 | Invalid parameter (SB_ERROR_INVALID_PARAMETER) |
| 1048578 | Invalid configuration (SB_ERROR_INVALID_SETUP) |
| 1048579 | Invalid state (SB_ERROR_INVALID_STATE) |
| 1048580 | Invalid value (SB_ERROR_INVALID_VALUE) |
| 1048581 | Private key not found (SB_ERROR_NO_PRIVATE_KEY) |
| 1048582 | Cancelled by the user (SB_ERROR_CANCELLED_BY_USER) |
| 1048583 | The file was not found (SB_ERROR_NO_SUCH_FILE) |
| 1048584 | Unsupported feature or operation (SB_ERROR_UNSUPPORTED_FEATURE) |
| 1048585 | General error (SB_ERROR_GENERAL_ERROR) |
| 27262977 | The file was not found (SB_ERROR_PGP_FILE_NOT_EXISTS) |
| 27262978 | Invalid signing key (SB_ERROR_PGP_INVALID_KEY) |
| 27262980 | No secret key is available (SB_ERROR_PGP_NO_SECRET_KEY) |
| 27262982 | The operation is not supported on a subkey (SB_ERROR_PGP_OPERATION_ON_SUBKEY) |