KeyMgr Component
Properties Methods Events Config Settings Errors
The KeyMgr component is used to create and manage OpenPGP keys.
Syntax
TipgKeyMgr
Remarks
The KeyMgr component supports key management according to the specifications outlined in RFC 4880, in addition to RFC 9580, which introduces support for OpenPGP Version 6. You can create, delete, import, export, and manage keys, including both individual keys and keyrings.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
KeyCurve | This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , or Ed448 . |
KeyEffectiveDate | The date when this key becomes valid. |
KeyEncoded | The key. |
KeyExpirationDate | The date the key expires. |
KeyFingerprint | The hex-encoded, 20-byte fingerprint of the key. |
KeyId | The hex-encoded, 4-byte or 8-byte key Id. |
KeyOtherUserIds | If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. |
KeyPassphrase | The passphrase for the key's secret key (if any). |
KeyPublicKey | The public key of the key. |
KeyPublicKeyAlgorithm | A text description of the public key algorithm of the key. |
KeyPublicKeyLength | The length of the public key in bits. |
KeyRevoked | Whether or not the key is revoked. |
KeySecretKey | The secret key of the key (if available). |
KeySecretKeyAvailable | Whether or not a secret key is available for the selected key. |
KeyUsage | A text description of UsageFlags . |
KeyUsageFlags | Flags that show the intended use for the key. |
KeyUserId | The user Id of the key. |
KeyVersion | This property can be used to query the OpenPGP version of the currently selected Key . |
Keyring | The location on disk of the keyring. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
AddRevoker | Adds a designated revoker to the key. |
AddUserId | Adds the specified user Id to the current key. |
ChangeExpirationDate | Changes the expiration date of the key. |
ChangePassphrase | Changes the passphrase of the current key. |
Config | Sets or retrieves a configuration setting. |
CreateKey | Creates an OpenPGP key pair. |
CreateSubKey | Creates a new subkey. |
DeleteKey | Deletes the specified key. |
ExportPublicKey | Exports the public key of the current key. |
ExportSecretKey | Exports the private key of the current key. |
ImportKey | Imports the key specified by UserId to the current keyring. |
ImportKeyB | Imports the key specified by UserId to the current keyring. |
ListKeys | Lists keys in the specified Keyring . |
ListSignatures | Lists all signatures of the current key. |
ListSubkeys | Lists the subkeys of the currently selected key. |
LoadKeyring | Loads the keyring from disk. |
LoadKeyringB | Loads the keyring from SecretKeyringData and PublicKeyringData . |
Reset | Resets the component properties. |
RevokeKey | Revokes the specified key. |
SaveKeyring | Saves the current Keyring to disk. |
SignUserId | Signs the specified user Id of the current key. |
VerifyPassphrase | Verifies the passphrase of specified key. |
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 | Fired when information is available about errors during data delivery. |
KeyList | Fires for each key in the keyring when ListKeys is called. |
KeyPassphrase | Fired if the passphrase of current key is incorrect or empty. |
SignatureList | Fires for each signature of the current key when ListSignatures is called. |
Status | Shows the progress of the operation. |
SubkeyList | Fires once for each subkey listed when ListSubkeys is called. |
Config Settings
The following is a list of config settings for the component with short descriptions. Click on the links for further details.
AllowEmptyPassword | Whether a key can be created without a password. |
Argon2Iterations | Specifies the number of iterations used for Argon2. |
Argon2MemorySizeExp | Specifies the exponent used to calculate the memory size used when creating a key. |
Argon2Parallelism | Specifies the degree of parallelism used for Argon2. |
ContinueOnInvalidKey | Whether to continue loading the keyring when an invalid key is found. |
CreateRSASubkeyForEncrypt | Whether to create a subkey when creating an RSA key. |
CurrentKeyPrimaryKeyUsageFlags | The usage flags of the currently selected primary key. |
Curve | The elliptic curve used when creating a key. |
EnsureValidDSASignatureHashAlgorithm | Whether or not to select a suitable signature hash algorithm automatically. |
ImportAllKeys | Whether or not to import all keys found in a key file. |
KeyBoxProtectionMode | Specifies the keybox protection mode used when saving a keyring. |
KeyEncryptionAlgorithm | The encryption algorithm used when creating a key. |
KeyIdLength | Specifies the length of the key's Id. |
KeyPreferredAEADAlgorithms | Indicates the preferred AEAD encryption algorithms associated with the currently selected key. |
KeyPreferredCompressionAlgorithms | Indicates the preferred compression algorithms associated with the currently selected key. |
KeyPreferredHashAlgorithms | Indicates the preferred hash algorithms associated with the currently selected key. |
KeyPreferredSymmetricAlgorithms | Indicates the preferred symmetric algorithms associated with the currently selected key. |
KeyringFormat | Specifies the keyring format to use when saving a keyring. |
KeyUsage | Flags that show intended use for the key being created. |
KeyValidityTime | The validity period for the key being created. |
KeyVersion | Specifies the OpenPGP version for the key being created. |
LogLevel | Specifies the level of detail that is logged. |
PreferredAEADAlgorithms | Specifies a key's preferred AEAD encryption algorithms when creating a key. |
PreferredCompressionAlgorithms | Specifies a key's preferred compression algorithms when creating a key. |
PreferredHashAlgorithms | Specifies a key's preferred hash algorithms when creating a key. |
PreferredSymmetricAlgorithms | Specifies a key's preferred symmetric algorithms when creating a key. |
PublicKeyAlgorithm | The public key algorithm for the key being created. |
PublicKeyLength | Specifies the public key length when creating a key. |
PublicKeyringFile | The file name of the public keyring file. |
PublicKeySignatureHashAlgorithm | The public key signature hash algorithm used when creating a key. |
RawKeyData | Returns detailed key and keyring data for debugging purposes. |
RevocationCode | The reason why the key was revoked. |
RevocationReason | Text describing why the key was revoked. |
Revoker | The revoker's key Id. |
SecretKeyringFile | The file name of the secret keyring file. |
SubKeyAlgorithm | The public key algorithm for the subkey being created. |
SubKeyCurve | The elliptic curve of the sub key. |
SubKeyLength | Specifies the public subkey length when creating a key or subkey. |
SubKeyUsage | Flags that show intended use for the subkey being created. |
UseArgon2 | Whether to use Argon2 for key derivation when creating a key. |
VersionHeader | The Version header value in ASCII armored public keys. |
BuildInfo | Information about the product's build. |
CodePage | The system code page used for Unicode to Multibyte translations. |
LicenseInfo | Information about the current license. |
MaskSensitiveData | Whether sensitive data is masked in log messages. |
UseFIPSCompliantAPI | Tells the component whether or not to use FIPS certified APIs. |
UseInternalSecurityAPI | Whether or not to use the system security libraries or an internal implementation. |
KeyCurve Property (KeyMgr Component)
This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , or Ed448 .
Syntax
__property String KeyCurve = { read=FKeyCurve };
Default Value
""
Remarks
This property specifies the elliptic curve if KeyPublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448. Possible values are:
Curve | Valid Public Key Algorithms | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
secp256k1 | ECDSA | Secp256k1 |
Ed25519 | EdDSA, Ed25519 | Ed25519 |
Ed448 | Ed448 | Ed448 |
This property is read-only and not available at design time.
Data Type
String
KeyEffectiveDate Property (KeyMgr Component)
The date when this key becomes valid.
Syntax
__property String KeyEffectiveDate = { read=FKeyEffectiveDate };
Default Value
""
Remarks
The date when this key becomes valid. Prior to this it is not valid. The following is an example of a valid encoded date:
23-Jan-2000 15:00:00.
This property is read-only and not available at design time.
Data Type
String
KeyEncoded Property (KeyMgr Component)
The key.
Syntax
__property String KeyEncoded = { read=FKeyEncoded, write=FSetKeyEncoded }; __property DynamicArray<Byte> KeyEncodedB = { read=FKeyEncodedB, write=FSetKeyEncodedB };
Default Value
""
Remarks
The key. This property can be used to assign a specific key. The KeyFingerprint, KeyId, and KeyUserId properties may also be used to specify a key.
This property is not available at design time.
Data Type
Byte Array
KeyExpirationDate Property (KeyMgr Component)
The date the key expires.
Syntax
__property String KeyExpirationDate = { read=FKeyExpirationDate };
Default Value
""
Remarks
The date the key expires. After this date the key will no longer be valid. The following is an example of a valid encoded date:
23-Jan-2001 15:00:00.
This property is read-only and not available at design time.
Data Type
String
KeyFingerprint Property (KeyMgr Component)
The hex-encoded, 20-byte fingerprint of the key.
Syntax
__property String KeyFingerprint = { read=FKeyFingerprint, write=FSetKeyFingerprint };
Default Value
""
Remarks
The hex-encoded, 20-byte fingerprint of the key.
When a key is loaded, this property is populated with the Fingerprint associated with the key. This property may be set to load a key from the Keyring. When this property is set the componentwill search the Keyring for a key associated with the Fingerprint specified.
This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
This property is not available at design time.
Data Type
String
KeyId Property (KeyMgr Component)
The hex-encoded, 4-byte or 8-byte key Id.
Syntax
__property String KeyId = { read=FKeyId, write=FSetKeyId };
Default Value
""
Remarks
The hex-encoded, 4-byte or 8-byte key Id. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
When a key is loaded, this property is populated with the Id associated with the key. This property may be set to load a key from the Keyring. When this property is set the component will search the Keyring for a key associated with the Id specified.
The KeyIdLength setting may be set to control the length of the returned key Id.
Note: It is recommended to use the KeyFingerprint property when loading a key from the Keyring, as it is possible for different keys to have the same Id.
This property is not available at design time.
Data Type
String
KeyOtherUserIds Property (KeyMgr Component)
If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.
Syntax
__property String KeyOtherUserIds = { read=FKeyOtherUserIds };
Default Value
""
Remarks
If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.
This property is read-only and not available at design time.
Data Type
String
KeyPassphrase Property (KeyMgr Component)
The passphrase for the key's secret key (if any).
Syntax
__property String KeyPassphrase = { read=FKeyPassphrase, write=FSetKeyPassphrase };
Default Value
""
Remarks
The passphrase for the key's secret key (if any). This must be specified before operations requiring the secret key are attempted. The passphrase may be supplied in this property or through the KeyPassphrase event, which will fire when a passphrase is required.
The passphrase is required when using the following methods in KeyMgr:
- AddUserId
- SignUserId
- ChangeExpirationDate
- ChangePassphrase
When using the OpenPGP component, or an email-based component, the following methods require a passphrase for the key:
- Decrypt
- Sign
- SignAndEncrypt
This property is not available at design time.
Data Type
String
KeyPublicKey Property (KeyMgr Component)
The public key of the key.
Syntax
__property String KeyPublicKey = { read=FKeyPublicKey };
Default Value
""
Remarks
The public key of the key. The key is provided as ASCII armored data.
This property is read-only and not available at design time.
Data Type
String
KeyPublicKeyAlgorithm Property (KeyMgr Component)
A text description of the public key algorithm of the key.
Syntax
__property String KeyPublicKeyAlgorithm = { read=FKeyPublicKeyAlgorithm };
Default Value
""
Remarks
A text description of the public key algorithm of the key. Possible values are:
- RSA
- DSA
- ECDSA
- EdDSA
- Ed25519
- Ed448
- RSA-Legacy
This property is read-only and not available at design time.
Data Type
String
KeyPublicKeyLength Property (KeyMgr Component)
The length of the public key in bits.
Syntax
__property int KeyPublicKeyLength = { read=FKeyPublicKeyLength };
Default Value
0
Remarks
The length of the public key in bits. Common values are 1024, 2048, and 3072.
If the KeyPublicKeyAlgorithm property is ECDSA, EdDSA, Ed25519, or Ed448, the length of the public key is determined by the KeyCurve. Possible lengths are:
Curve | Public Key Length (bits) |
secp256r1 | 256 |
secp384r1 | 384 |
secp521r1 | 528 |
secp256k1 | 256 |
Ed25519 | 256 |
Ed448 | 456 |
This property is read-only and not available at design time.
Data Type
Integer
KeyRevoked Property (KeyMgr Component)
Whether or not the key is revoked.
Syntax
__property bool KeyRevoked = { read=FKeyRevoked };
Default Value
false
Remarks
Whether or not the key is revoked.
This property is read-only and not available at design time.
Data Type
Boolean
KeySecretKey Property (KeyMgr Component)
The secret key of the key (if available).
Syntax
__property String KeySecretKey = { read=FKeySecretKey };
Default Value
""
Remarks
The secret key of the key (if available). The key is provided as ASCII armored data.
This property is read-only and not available at design time.
Data Type
String
KeySecretKeyAvailable Property (KeyMgr Component)
Whether or not a secret key is available for the selected key.
Syntax
__property bool KeySecretKeyAvailable = { read=FKeySecretKeyAvailable };
Default Value
false
Remarks
Whether or not a secret key is available for the selected key.
This property is read-only and not available at design time.
Data Type
Boolean
KeyUsage Property (KeyMgr Component)
A text description of UsageFlags .
Syntax
__property String KeyUsage = { read=FKeyUsage };
Default Value
""
Remarks
A text description of KeyUsageFlags.
The value will be of one or more of the following strings, separated by commas:
- Certifying Other Certificates
- Signing Emails and Files
- Encrypting Emails and Files
- Split Key
- Authenticate Against Servers
- Group Key
This property is read-only and not available at design time.
Data Type
String
KeyUsageFlags Property (KeyMgr Component)
Flags that show the intended use for the key.
Syntax
__property int KeyUsageFlags = { read=FKeyUsageFlags };
Default Value
47
Remarks
Flags that show the intended use for the key. The default value is 0x0F. The value of KeyUsageFlags is a combination of the following flags:
0x01 | This key may be used to certify other keys. |
0x02 | This key may be used to sign data. |
0x0C | This key may be used to encrypt communications and encrypt storage. |
0x10 | The private component of this key may have been split by a secret-sharing mechanism. |
0x20 | This key may be used for authentication. |
0x80 | The private component of this key may be in the possession of more than one person. |
Please refer to the KeyUsage property for a text representation of KeyUsageFlags.
This property is read-only and not available at design time.
Data Type
Integer
KeyUserId Property (KeyMgr Component)
The user Id of the key.
Syntax
__property String KeyUserId = { read=FKeyUserId, write=FSetKeyUserId };
Default Value
""
Remarks
The user Id of the key. When a key is loaded this property is populated with the user Id associated with the key. This property may be set to load a key from the Keyring. When this property is set the component will search the Keyring for a key associated with the UserId specified.
When loading a key with multiple user Ids, this property will be populated with the UserId that was most recently added to the key. To discover all of the UserIds associated with a key query this property and KeyOtherUserIds after loading the key.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
When using this property to select a key you may also specify the key's Id, or any of its subkeys' Ids, instead of a user Id. The component will then search for a key with a matching Id. This is helpful in situations where you do not have the UserId but still need to load the key, such as within the OpenPGP component's RecipientInfo event.
This property is not available at design time.
Data Type
String
KeyVersion Property (KeyMgr Component)
This property can be used to query the OpenPGP version of the currently selected Key .
Syntax
__property int KeyVersion = { read=FKeyVersion };
Default Value
4
Remarks
This property can be used to query the OpenPGP version of the currently selected Key. Possible values are:
- 4 - OpenPGP v4 (default)
- 6 - OpenPGP v6
This property is read-only and not available at design time.
Data Type
Integer
Keyring Property (KeyMgr Component)
The location on disk of the keyring.
Syntax
__property String Keyring = { read=FKeyring };
Default Value
""
Remarks
To load a keyring use the LoadKeyring method.
This property is read-only.
Data Type
String
AddRevoker Method (KeyMgr Component)
Adds a designated revoker to the key.
Syntax
void __fastcall AddRevoker(String UserId);
Remarks
This method adds a designated revoker to the selected Key. The UserId parameter specifies the revoker to add. The revoker's key must be present in the current keyring. Use this with caution: once added, a revoker cannot be removed. The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
AddUserId Method (KeyMgr Component)
Adds the specified user Id to the current key.
Syntax
void __fastcall AddUserId(String UserId);
Remarks
The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
ChangeExpirationDate Method (KeyMgr Component)
Changes the expiration date of the key.
Syntax
void __fastcall ChangeExpirationDate(int ExpirationDate);
Remarks
This method changes the expiration date of the current Key. The ExpirationDate parameter specifies the number of days for which the key is valid starting today. For instance a value of "31" means the key is valid for the next 31 days.
The special value "0" means the key will never expire.
The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.
Note: See KeyValidityTime for information on specifying the expiration date when creating the key with CreateKey.
ChangePassphrase Method (KeyMgr Component)
Changes the passphrase of the current key.
Syntax
void __fastcall ChangePassphrase(String Passphrase);
Remarks
The Passphrase parameter specifies the new passphrase.
The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.
Config Method (KeyMgr Component)
Sets or retrieves a configuration setting.
Syntax
String __fastcall Config(String ConfigurationString);
Remarks
Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.
These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.
To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.
CreateKey Method (KeyMgr Component)
Creates an OpenPGP key pair.
Syntax
void __fastcall CreateKey(String UserId, String Passphrase);
Remarks
This method creates a new OpenPGP key pair. The UserId parameter specifies the user Id of the key. If KeyVersion is 6, this parameter may be an empty string.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
Additional configuration settings may be set to further configure the details of the key (and subkey) being created. Please see the following settings for details:
- KeyEncryptionAlgorithm
- KeyUsage
- KeyValidityTime
- PublicKeyLength
- PublicKeyAlgorithm
- PublicKeySignatureHashAlgorithm
- Curve
- SubKeyAlgorithm
- SubKeyLength
- SubKeyCurve
- UseArgon2
- Argon2Iterations
- Argon2Parallelism
CreateSubKey Method (KeyMgr Component)
Creates a new subkey.
Syntax
void __fastcall CreateSubKey();
Remarks
This method creates a new subkey. Before calling this method the KeyId property must be set to a valid private key.
The following settings may optionally be set to define specific values for the created subkey:
DeleteKey Method (KeyMgr Component)
Deletes the specified key.
Syntax
void __fastcall DeleteKey(String UserId);
Remarks
This method deletes the key specified by UserId from the current keyring. Below is a table of the type of Ids that may be specified to identify the key:
Id Type | Example |
UserId | FirstName LastName <user@mail.com> |
UserId (name only) | FirstName LastName |
UserId (first name only) | FirstName |
UserId (email only) | user@mail.com |
Short KeyId | 89C9D7B1 |
Long KeyId | F7B7D49C89C9D7B1 |
Fingerprint (OpenPGP v6 only) | 2A62207E927A9C125B9226FE764E796ECE849D623FFA03C845B8B2A5B6398EC8 |
ExportPublicKey Method (KeyMgr Component)
Exports the public key of the current key.
Syntax
void __fastcall ExportPublicKey(String FileName, bool useAsciiArmor);
Remarks
This method exports the public key of the currently selected Key. The FileName parameter specifies the file on disk to which the public key will be written. The UseAsciiArmor parameter determines whether or not ASCII armoring is used when writing the key to disk.
Note: When UseAsciiArmor is set to True the VersionHeader setting may also be set to specify your own header value.
ExportSecretKey Method (KeyMgr Component)
Exports the private key of the current key.
Syntax
void __fastcall ExportSecretKey(String FileName, bool useAsciiArmor);
Remarks
This method exports the private key of the currently selected Key. The FileName parameter specifies the file on disk that the private key will be written to. The UseAsciiArmor parameter determines whether or not ASCII armoring is used when writing the key to disk.
ImportKey Method (KeyMgr Component)
Imports the key specified by UserId to the current keyring.
Syntax
void __fastcall ImportKey(String FileName, String UserId);
Remarks
This method imports the key specified by UserId from the key file specified by FileName into the current Keyring. The imported key will be automatically selected and available in the Key property.
If the FileName specifies a key file which contains multiple keys only the key belonging to UserId will be imported.
If UserId is set to "*" or "" (empty string) all keys in the key file will be imported. The ImportAllKeys setting controls the behavior of the component in this case.
Note: If you simply wish to select a key in the current ring set KeyUserId instead.
ImportKeyB Method (KeyMgr Component)
Imports the key specified by UserId to the current keyring.
Syntax
void __fastcall ImportKeyB(DynamicArray<Byte> Data, String UserId);
Remarks
This method imports the key specified by UserId from the key data specified by Data into the current Keyring. The imported key will be automatically selected and available in the Key property.
If the Data specifies key data that contains multiple keys only the key belonging to UserId will be imported.
If UserId is set to "*" or "" (empty string) all keys in the key data will be imported. The ImportAllKeys setting controls the behavior of the component in this case.
Note: If you simply wish to select a key in the current ring set KeyUserId instead.
ListKeys Method (KeyMgr Component)
Lists keys in the specified Keyring .
Syntax
String __fastcall ListKeys();
Remarks
This method lists the keys (public/private key pairs) in the specified keyring. The results are provided through the KeyList event.
KeyList data will also be returned from this method, however it is recommended to use the KeyList event if possible.
ListSignatures Method (KeyMgr Component)
Lists all signatures of the current key.
Syntax
String __fastcall ListSignatures();
Remarks
This method lists all the signatures of the currently selected key. The SignatureList event will fire for each signature.
SignatureList data will also be returned from this method. However, it is recommended to use the SignatureList event if possible.
ListSubkeys Method (KeyMgr Component)
Lists the subkeys of the currently selected key.
Syntax
String __fastcall ListSubkeys();
Remarks
This method lists all subkeys of current key. The SubkeyList event will be fired for each subkey.
SubkeyList data will also be returned from this method, however it is recommended to use the SubkeyList event if possible.
LoadKeyring Method (KeyMgr Component)
Loads the keyring from disk.
Syntax
void __fastcall LoadKeyring(String KeyringPath);
Remarks
This method loads the keyring from disk. If the keyring is stored in a directory, set KeyringPath to the directory. The directory must contain the files "secring.gpg" and "pubring.gpg". A keyring may also be stored in a single file. If the keyring is a file KeyringPath should be set to the path of the file.
When this method is called the component will read the keyring and populate the Key property with the first key found in the keyring. Set KeyUserId to select a different key in the current keyring.
LoadKeyringB Method (KeyMgr Component)
Loads the keyring from SecretKeyringData and PublicKeyringData .
Syntax
void __fastcall LoadKeyringB(DynamicArray<Byte> SecretKeyringData, DynamicArray<Byte> PublicKeyringData);
Remarks
This method loads the keyring from SecretKeyringData and PublicKeyringData.
When this method is called the component will read the keyring and populate the Key property with the first key found in the keyring. Set KeyUserId to select a different key in the current keyring.
Reset Method (KeyMgr Component)
Resets the component properties.
Syntax
void __fastcall Reset();
Remarks
This method resets all message and key properties to their default values.
RevokeKey Method (KeyMgr Component)
Revokes the specified key.
Syntax
String __fastcall RevokeKey(String KeyId);
Remarks
This method revokes the key specified by KeyId and returns the revocation certificate.
When creating a revocation certificate there are two supported formats. The first format includes only the revocation signature. This format is returned by this method. The second format includes both the public key and the revocation signature. This format can be obtained by calling ExportPublicKey after calling this method. Both formats are common, and both formats are acceptable when calling ImportKey.
Before calling this method a key must be selected and available in the Key property.
The KeyId may be the Id of the main key or a subkey. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
SaveKeyring Method (KeyMgr Component)
Saves the current Keyring to disk.
Syntax
void __fastcall SaveKeyring(String KeyringPath);
Remarks
This method saves the current keyring to disk. There are two output options. The keyring may either be saved to a single key file or may be saved to a directory.
To save the keyring to a directory set KeyringPath to the path. The directory must already exist. The component will create a "pubring.gpg" and "secring.gpg" file in the specified directory. If the files already exist they will be overwritten.
To save the keyring to a key file set KeyringPath to a path and file name. If the file already exists it will be overwritten.
SignUserId Method (KeyMgr Component)
Signs the specified user Id of the current key.
Syntax
void __fastcall SignUserId(String UserId, String IssuerUserId);
Remarks
This method signs the UserId with the IssuerUserId.
To sign all user Ids in the current key set the UserId parameter to "*".
The key's passphrase is required for this operation and may be specified via KeyPassphrase or through the KeyPassphrase event.
VerifyPassphrase Method (KeyMgr Component)
Verifies the passphrase of specified key.
Syntax
bool __fastcall VerifyPassphrase(String Passphrase);
Remarks
This method verifies the passphrase of the key specified by UserId.
If the password is correct, this method returns True; otherwise, this method returns False.
Error Event (KeyMgr Component)
Fired when information is available about errors during data delivery.
Syntax
typedef struct { int ErrorCode; String Description; } TipgKeyMgrErrorEventParams; typedef void __fastcall (__closure *TipgKeyMgrErrorEvent)(System::TObject* Sender, TipgKeyMgrErrorEventParams *e); __property TipgKeyMgrErrorEvent OnError = { read=FOnError, write=FOnError };
Remarks
The Error event is fired in case of exceptional conditions during message processing. Normally the component raises an exception.
The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.
KeyList Event (KeyMgr Component)
Fires for each key in the keyring when ListKeys is called.
Syntax
typedef struct { String UserId; String KeyId; String Fingerprint; bool HasSecretKey; String PublicKeyAlgorithm; int PublicKeyLength; String Curve; } TipgKeyMgrKeyListEventParams; typedef void __fastcall (__closure *TipgKeyMgrKeyListEvent)(System::TObject* Sender, TipgKeyMgrKeyListEventParams *e); __property TipgKeyMgrKeyListEvent OnKeyList = { read=FOnKeyList, write=FOnKeyList };
Remarks
This event fires once for each key in the Keyring when ListKeys is called.
UserId holds the current user Id of the key.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
KeyId is the hex-encoded, 4-byte or 8-byte Id of the key. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
Fingerprint holds the hex-encoded, 20-byte fingerprint of the key. This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
HasSecretKey returns True if the key contains a secret key.
PublicKeyAlgorithm is the public key algorithm. Possible values are:
- RSA
- DSA
- ECDSA
- EdDSA
- Ed25519
- Ed448
PublicKeyLength is the length of the public key. Common values are 1024, 2048, and 3072. If the PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448, the length of the public key is determined by the Curve. Possible lengths are:
Curve | Public Key Length (bits) |
secp256r1 | 256 |
secp384r1 | 384 |
secp521r1 | 528 |
secp256k1 | 256 |
Ed25519 | 256 |
Ed448 | 456 |
Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448. Possible values are:
Curve | Valid Public Key Algorithms | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
secp256k1 | ECDSA | Secp256k1 |
Ed25519 | EdDSA, Ed25519 | Ed25519 |
Ed448 | Ed448 | Ed448 |
KeyPassphrase Event (KeyMgr Component)
Fired if the passphrase of current key is incorrect or empty.
Syntax
typedef struct { String UserId; String KeyId; String Fingerprint; String Passphrase; } TipgKeyMgrKeyPassphraseEventParams; typedef void __fastcall (__closure *TipgKeyMgrKeyPassphraseEvent)(System::TObject* Sender, TipgKeyMgrKeyPassphraseEventParams *e); __property TipgKeyMgrKeyPassphraseEvent OnKeyPassphrase = { read=FOnKeyPassphrase, write=FOnKeyPassphrase };
Remarks
This event fires when the passphrase for the key is required. The passphrase must be specified before operations requiring the secret key are attempted. The passphrase may be supplied by setting the Passphrase parameter in this event, or by specifying the KeyPassphrase property before attempting the operation.
The passphrase is required when using the following methods in KeyMgr:
When using the OpenPGP component, or an email-based component, the following methods require a passphrase for the key:
- Decrypt
- Sign
- SignAndEncrypt
UserId holds the user Id of the key the passphrase is required for.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
KeyId is the hex-encoded, 4-byte or 8-byte Id of the key the passphrase is required for. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
Fingerprint holds the hex-encoded, 20-byte fingerprint of the key the passphrase is required for. This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
SignatureList Event (KeyMgr Component)
Fires for each signature of the current key when ListSignatures is called.
Syntax
typedef struct { String KeyId; String Fingerprint; String UserId; String IssuerFingerprint; String IssuerKeyId; String IssuerUserId; String PublicKeyAlgorithm; String Curve; String HashAlgorithm; String EffectiveDate; int SignatureClass; int ValidityStatus; } TipgKeyMgrSignatureListEventParams; typedef void __fastcall (__closure *TipgKeyMgrSignatureListEvent)(System::TObject* Sender, TipgKeyMgrSignatureListEventParams *e); __property TipgKeyMgrSignatureListEvent OnSignatureList = { read=FOnSignatureList, write=FOnSignatureList };
Remarks
This event fires once for each signature of the current key when ListSignatures is called.
The KeyId, UserId, and Fingerprint parameters contain relevant information for the current key. Similarly, the IssuerKeyId, IssuerUserId, and IssuerFingerprint parameters contain relevant information for the issuer's key. The format of these parameters are described below.
KeyId and IssuerKeyId hold the hex-encoded, 4- or 8-byte Id of the respective key. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
UserId and IssuerUserId hold the user Id of the respective key. The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.
Fingerprint and IssuerFingerprint hold the hex-encoded, 20-byte fingerprint of the respective key. This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
Note that if IssuerUserId and IssuerFingerprint are empty, this indicates that the issuer's key could not be found in the current keyring.
PublicKeyAlgorithm is the public key algorithm. Possible values are:
- RSA
- DSA
- ECDSA
- EdDSA
- Ed25519
- Ed448
Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448. Possible values are:
Curve | Valid Public Key Algorithms | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
secp256k1 | ECDSA | Secp256k1 |
Ed25519 | EdDSA, Ed25519 | Ed25519 |
Ed448 | Ed448 | Ed448 |
HashAlgorithm is the hash algorithm used by the signature. Possible values are:
- SHA1
- MD5
- SHA256
- SHA384
- SHA512
- SHA224
- RIPEMD160
- SHA3-256
- SHA3-512
EffectiveDate is the date when this signature became valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00 .
SignatureClass is the type of signature. Possible values are:
16 | Generic Signature |
17 | Personal Signature |
18 | Casual Signature |
19 | Positive Signature (self-signed) |
ValidityStatus specifies the current validity status of the signature. Possible values are:
1 | Invalid |
2 | Valid |
3 | Unknown (the issuer's public key could not be found) |
Status Event (KeyMgr Component)
Shows the progress of the operation.
Syntax
typedef struct { String Message; } TipgKeyMgrStatusEventParams; typedef void __fastcall (__closure *TipgKeyMgrStatusEvent)(System::TObject* Sender, TipgKeyMgrStatusEventParams *e); __property TipgKeyMgrStatusEvent OnStatus = { read=FOnStatus, write=FOnStatus };
Remarks
The event is fired for informational and logging purposes only. It may be used to track the progress of an operation.
The level of detail is controlled by the LogLevel setting.
SubkeyList Event (KeyMgr Component)
Fires once for each subkey listed when ListSubkeys is called.
Syntax
typedef struct { String KeyId; String Fingerprint; String PublicKeyAlgorithm; int PublicKeyLength; String Curve; int UsageFlags; String Usage; String EffectiveDate; String ExpirationDate; bool Revoked; } TipgKeyMgrSubkeyListEventParams; typedef void __fastcall (__closure *TipgKeyMgrSubkeyListEvent)(System::TObject* Sender, TipgKeyMgrSubkeyListEventParams *e); __property TipgKeyMgrSubkeyListEvent OnSubkeyList = { read=FOnSubkeyList, write=FOnSubkeyList };
Remarks
This event fires once for each subkey when ListSubkeys is called.
KeyId is the hex-encoded, 4- or 8-byte Id of the key. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
Fingerprint holds the hex-encoded, 20-byte fingerprint of the key. This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
PublicKeyAlgorithm is the public key algorithm of the subkey. Possible values are:
- RSA
- DSA
- ElGamal
- ECDSA
- EdDSA
- ECDH
- Ed25519
- Ed448
- X25519
- X448
PublicKeyLength is the length of the subkey. Common values are 1024, 2048, and 3072. If PublicKeyAlgorithm is ECDSA, EdDSA, ECDH, Ed25519, Ed448, X25519, or X448, the length of the public key is determined by the Curve. Possible lengths are:
Curve | Public Key Length (bits) |
secp256r1 | 256 |
secp384r1 | 384 |
secp521r1 | 528 |
secp256k1 | 256 |
Ed25519 | 256 |
Ed448 | 456 |
Curve25519 | 256 |
Curve448 | 448 |
Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, ECDH, Ed25519, Ed448, X25519, or X448. Possible values are:
Subkey Curve | Possible Subkey Algorithms | Description |
secp256r1 | ECDSA, ECDH | NIST curve P-256 |
secp384r1 | ECDSA, ECDH | NIST curve P-384 |
secp521r1 | ECDSA, ECDH | NIST curve P-521 |
secp256k1 | ECDSA, ECDH | Secp256k1 |
Ed25519 | EdDSA, Ed25519 | Ed25519 |
Ed448 | EdDSA, Ed448 | Ed448 |
Curve25519 | ECDH, X25519 | Curve25519 |
Curve448 | X448 | Curve448 |
Usage is the textual description of UsageFlags.
The value will be of one or more of the following strings, separated by commas:
- Certifying Other Certificates
- Signing Emails and Files
- Encrypting Emails and Files
- Split Key
- Authenticate Against Servers
- Group Key
UsageFlags is an integer flag that shows the intended use for the key. The value is a combination of the following flags:
0x01 | This key may be used to certify other keys. |
0x02 | This key may be used to sign data. |
0x0C | This key may be used to encrypt communications and encrypt storage. |
0x10 | The private component of this key may have been split by a secret-sharing mechanism. |
0x20 | This key may be used for authentication. |
0x80 | The private component of this key may be in the possession of more than one person. |
EffectiveDate is the date when this key became valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00.
ExpirationDate is the date the key expires. After this date the key will no longer be valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00. If the ExpirationDate is not populated this indicates that the key never expires.
Revoked Indicates whether the subkey is revoked or not.
Config Settings (KeyMgr Component)
The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.KeyMgr Config Settings
This controls whether a password will be used to encrypt a key. When true, CreateKey will accept an empty string as the password, leaving the key unencrypted. The default is false.
This configuration setting specifies the number of iterations performed when calling CreateKey and UseArgon2 is True. The default value is 3. Valid values range from 1 to 2^(32)-1. Higher values provide more brute-force protection for the key passphrase at the cost of performance. This configuration can be used to tune the running time independently of the memory size (see Argon2MemorySizeExp).
This configuration setting specifies the exponent used when calculating the memory size used when calling CreateKey and UseArgon2 is True. The default value is 16. Valid values range from 3 to 31, though the minimum can vary depending on the value of Argon2Parallelism (see below). The memory size (in KB) is calculated as 2^exp, where exp is the value of this configuration setting. For example, the default memory size would be: 2^(16) = 65,536 KB.
Note: The memory size must be an integer number of kilobytes ranging from 8*p to 2^(32)-1, where p is the value of Argon2Parallelism. Therefore, Argon2MemorySizeExp must be an integer ranging from 3+ceil(log2(p)) to 31. For example, if Argon2Parallelism is set to 8, valid values for Argon2MemorySizeExp range from 6 to 31.
This configuration setting specifies the degree of parallelism, or the number of lanes, used when CreateKey is called and UseArgon2 is set to True. The default value is 4. Valid values range from 1 to 2^(24)-1.
This setting determines whether the component will continue loading keys when an invalid key is found. This is applicable when calling LoadKeyring. If set to False (default) the component raises an exception. If set to True the component will fire the Error event with information about the key which failed to load, and then continue loading additional keys.
This setting determines whether the component will additionally create a subkey marked for encryption when calling CreateKey when PublicKeyAlgorithm is set to RSA. The default is true.
Note that if KeyVersion is set to 6, this setting must be disabled to create an RSA key.
When queried, this will return the usage flags of the currently selected primary key, returned in decimal representation. Individual flags may be checked against the list at KeyUsageFlags.
This configuration setting specifies the curve to use when calling CreateKey. This is only applicable when PublicKeyAlgorithm is set to ECDSA, EdDSA, Ed25519, or Ed448. Possible curves and PublicKeyAlgorithm combinations are:
Curve | Valid Public Key Algorithms | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
secp256k1 | ECDSA | Secp256k1 |
Ed25519 | EdDSA, Ed25519 | Ed25519 |
Ed448 | Ed448 | Ed448 |
This setting specifies whether the component ensures a valid hash algorithm is selected for use with the loaded DSA or ECDSA key. The default value is True.
DSA Notes
DSA requires that the hash be 160 bits or larger, which means MD5 is not a suitable algorithm. When DSA Signature Hash Algorithm selection is enabled (default) the component will use the preferred algorithm from the key if it meets the requirements for DSA. If the preferred algorithm is MD5 and does not meed the requirements for DSA the component will automatically use a suitable algorithm based on the Q element of the DSA key (may be SHA1, SHA224, or SHA256).
ECDSA Notes
The ECDSA Signature Hash Algorithm requirements are directly related to the KeyCurve used by the key. When this setting is enabled (default) the component will use the preferred algorithm from the key if it meets the requirements for ECDSA. If the preferred algorithm does not meet the requirements the component will automatically select a valid hash algorithm based on the curve as follows:
Curve | Hash Algorithm |
secp256r1 | SHA256 |
secp384r1 | SHA384 |
secp521r1 | SHA512 |
secp256k1 | SHA256 |
When calling ImportKey with a UserId parameter of "*" or "", the component will import all keys found in the file if this property is set to True (default). If this is set to False when the UserId parameter of ImportKey is set to "*" or "", only the first key found in the file will be imported. The default value is True.
This configuration setting specifies the keybox protection mode used when calling SaveKeyring. This is only applicable when KeyringFormat is set to 2 (GPG 2.1 and newer). Possible values are as follows:
0 | openpgp-s2k3-sha1-aes-cbc (default) |
1 | openpgp-s2k3-sha1-aes256-cbc |
2 | openpgp-s2k3-ocb-aes |
Specifies the encryption algorithm to use when calling CreateKey. The default value is AES128. Possible values are:
- CAST5
- 3DES
- AES256
- AES192
- AES128
- IDEA
- BLOWFISH
- AES256-OCB (AEAD)
- AES192-OCB (AEAD)
- AES128-OCB (AEAD)
- AES256-GCM (AEAD)
- AES192-GCM (AEAD)
- AES128-GCM (AEAD)
The listed AEAD encryption algorithms (AES*-OCB or AES*-GCM) are only relevant if UseArgon2 is enabled. In this case, this config must be set to one of the above AEAD encryption algorithms. If UseArgon2 is disabled, and an AEAD encryption algorithm is specified, the AEAD mode (OCB or GCM) will be ignored.
When querying the KeyId property the value will be returned with the length (in octets) specified. The default value is 8. The only other acceptable value is 4.
For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:
5E70662EA810E768
This configuration setting indicates the preferred AEAD encryption algorithms associated with the currently selected Key. This configuration setting is read-only.
This configuration setting will return a comma-separated list of the key's preferred AEAD encryption algorithms. For example: "AES256-OCB, AES256-GCM, AES192-OCB, AES192-GCM, AES128-OCB, AES128-GCM"
This configuration setting indicates the preferred compression algorithms associated with the currently selected Key. This configuration setting is read-only.
This configuration setting will return a comma-separated list of the key's preferred compression algorithms. For example: "ZIP, ZLIB, BZip2, Uncompressed"
This configuration setting indicates the preferred hash algorithms associated with the currently selected Key. This configuration setting is read-only.
This configuration setting will return a comma-separated list of the key's preferred hash algorithms. For example: "SHA256, SHA384, SHA224, SHA1, MD5, RIPEMD160"
This configuration setting indicates the preferred symmetric algorithms associated with the currently selected Key. This configuration setting is read-only.
This configuration setting will return a comma-separated list of the key's preferred symmetric algorithms. For example: "AES256, AES192, AES128, Blowfish, Twofish, IDEA, TripleDES, CAST5"
This configuration setting specifies the keyring format to use when calling SaveKeyring. GPG has two formats to store multiple keys. Supported values are as follows:
Config Value | Keyring Format |
1 | GPG 2.0 and older (Default) |
2 | GPG 2.1 and newer |
Versions 2.0 and older use keyrings. Public keys are stored in pubring.gpg. Secret keys are stored in secring.gpg.
Versions 2.1 and newer use a keybox. Public keys are stored in a .kbx file. Private keys are stored in private-keys-v1.d. The default keybox protection mode is openpgp-s2k3-sha1-aes-cbc. See KeyBoxProtectionMode for additional details.
For example:
keymgr1.Config("KeyringFormat=2");
keymgr1.SaveKeyring("C:\\keyring");
When calling CreateKey this setting defines the flags that show the intended use for the key. The default value is (0x0F). The value of KeyUsage is a combination of the following flags:
0x01 | This key may be used to certify other keys. |
0x02 | This key may be used to sign data. |
0x0C | This key may be used to encrypt communications and encrypt storage. |
0x10 | The private component of this key may have been split by a secret-sharing mechanism. |
0x20 | This key may be used for authentication. |
0x80 | The private component of this key may be in the possession of more than one person. |
When CreateKey creates a new key, the key is valid the moment it is created. KeyValidityTime determines the number of days until expiration. The default value is 365 days. The special value 0 means the key will never expire.
This configuration is used to specify the OpenPGP version for the key being created via CreateKey. Possible values are:
- 4 (OpenPGP v4)
- 6 (OpenPGP v6)
This setting controls the level of detail that is logged through the Status event. Possible values are:
0 (None) | No events are logged. |
1 (Info - default) | Informational events are logged. |
2 (Verbose) | Detailed data is logged. |
3 (Debug) | Debug data is logged. |
This configuration setting is used to specify a key's preferred AEAD encryption algorithms when calling CreateKey. This can be set as a combination of the following hex values (in string format):
- 0702 - AES128-OCB
- 0703 - AES128-GCM
- 0802 - AES192-OCB
- 0803 - AES192-GCM
- 0902 - AES256-OCB
- 0903 - AES256-GCM
For example, to set the preferred AEAD encryption algorithms to AES256-OCB and AES256-GCM, this config can be set like so:
// AES256-OCB (0902), AES256-GCM (0903)
keyMgr.Config("PreferredAEADAlgorithms=09020903");
keyMgr.CreateKey("test", "test");
By default, this configuration setting is equal to the following string: 090209030802080307020703
This configuration setting is used to specify a key's preferred compression algorithms when calling CreateKey. This can be set as a combination of the following hex values (in string format):
- 00 - Uncompressed
- 01 - ZIP
- 02 - ZLIB
- 03 - BZip2
For example, to set the preferred compression algorithms to ZIP and ZLIB, this config can be set like so:
// ZIP (01), ZLIB (02)
keyMgr.Config("PreferredCompressionAlgorithms=0102");
keyMgr.CreateKey("test", "test");
By default, this configuration setting is equal to the following string: 01020300
This configuration setting is used to specify a key's preferred hash algorithms when calling CreateKey. This can be set as a combination of the following hex values (in string format):
- 01 - MD5
- 02 - SHA1
- 03 - RIPEMD60
- 08 - SHA256
- 09 - SHA384
- 0a - SHA512
- 0b - SHA224
- 0c - SHA3_256
- 0f - SHA3_512
For example, to set the preferred hash algorithms to SHA256, SHA384, and SHA512, this config can be set like so:
// SHA256 (08), SHA384 (09), SHA512 (0a)
keyMgr.Config("PreferredHashAlgorithms=08090a");
keyMgr.CreateKey("test", "test");
By default, this configuration setting is equal to the following string: 08090a0b020103
This configuration setting is used to specify a key's preferred symmetric algorithms when calling CreateKey. This can be set as a combination of the following hex values (in string format):
- 00 - Plaintext
- 01 - IDEA
- 02 - TripleDES
- 03 - CAST5
- 04 - Blowfish
- 07 - AES128
- 08 - AES192
- 09 - AES256
- 0a - Twofish
For example, to set the preferred symmetric algorithms to AES256, AES192, and AES128, this config can be set like so:
// AES256 (09), AES192 (08), AES128 (07)
keyMgr.Config("PreferredSymmetricAlgorithms=090807");
keyMgr.CreateKey("test", "test");
By default, this configuration setting is equal to the following string: 090807040a010203
Specifies the public key algorithm to use when creating the key via CreateKey. By default, this config will be set to automatic and the component will automatically choose an appropriate algorithm depending on the KeyVersion. For OpenPGP v4, EdDSA will be selected as the default. For OpenPGP v6, Ed25519 will be selected as the default.
Supported values depend on the KeyVersion. Please see below for supported values for each version.
Public Key Algorithm | Supported for OpenPGP v4 | Supported for OpenPGP v6 |
RSA | ||
DSA | ||
ECDSA | ||
EdDSA | ||
Ed25519 | ||
Ed448 | ||
RSA-Legacy |
When creating an RSA key and KeyVersion is specified as 6, note that the PublicKeyLength must be greater than or equal to 3072 (default). Additionally, CreateRSASubkeyForEncrypt must be disabled. Note that while supported, it is not recommended to create an RSA key when KeyVersion is set to 6.
When creating a DSA key, the PublicKeySignatureHashAlgorithm value "MD5" is not supported.
When creating an ECDSA, EdDSA, Ed25519, or Ed448 key, the PublicKeyLength value is automatically determined based on the Curve. If Curve is not specified, the following defaults will be used:
Public Key Algorithm | Default Curve |
ECDSA | secp256r1 |
EdDSA | Ed25519 |
Ed25519 | Ed25519 |
Ed448 | Ed448 |
The below configurations may be utilized to configure the subkey associated with this key. By default, the component will automatically select appropriate values based on the PublicKeyAlgorithm.
Note: The RSA-Legacy algorithm should not be used under normal circumstances. It should only be used to create PGP 2.6.2 compatible keys, when required. This type of key will not have subkeys.
Specifies the length of the public key when calling CreateKey. The default value is 3072.
This configuration setting is only applicable when PublicKeyAlgorithm is specified as RSA or DSA.
Note that when PublicKeyAlgorithm is set to RSA and KeyVersion is set to 6, the public key length must be greater than or equal to 3072.
This specifies the name of the public keyring file. The default value is "pubring.gpg". This may be set to a file name only, or a full path including the file name.
This setting specifies the public key signature algorithm to be used when calling CreateKey. The default value is "SHA256". Possible values are:
- SHA1
- MD5
- SHA256 (default)
- SHA384
- SHA512
- SHA224
- RIPEMD160
- SHA3-256
- SHA3-512
This setting will return detailed debugging information about the current key and keyring.
This setting specifies why the key was revoked. It is only applicable if KeyRevoked is True. This may be set before calling RevokeKey and may be inspected after importing and selecting a revoked key. Possible values are:
0 | No reason specified |
1 | Key is superseded |
2 | Key material has been compromised |
3 | Key is retired and no longer used |
4 | User Id information is no longer valid |
100-110 | Private Use |
This setting specifies text description of why the key was revoked. It is only applicable if KeyRevoked is True. This may be set before calling RevokeKey and may be queried after importing and selecting a revoked key. The default value is an empty string.
This setting returns the key Id of the designated revoker associated with this key. This will only be present if a separate revoker was added to the key (for instance by calling AddRevoker). If more than one revoker was added this setting will return a comma-separated list of key Ids.
This specifies the name of the secret keyring file. The default value is "secring.gpg". This may be set to a file name only, or a full path including the file name.
Specifies the public key algorithm for a subkey created when calling CreateSubKey. The default value is empty string and the component will automatically select an appropriate algorithm based on SubKeyUsage.
Supported values depend on the KeyVersion. Please see below for applicable values for each supported version.
Public Key Algorithm | Supported Subkey Operations | Supported for OpenPGP v4 | Supported for OpenPGP v6 |
RSA | Sign and Encrypt | ||
DSA | Sign | ||
ElGamal | Encrypt | ||
ECDSA | Sign | ||
EdDSA | Sign | ||
ECDH | Encrypt | ||
Ed25519 | Sign | ||
Ed448 | Sign | ||
X25519 | Encrypt | ||
X448 | Encrypt |
The SubKeyCurve configuration setting is applicable for subkey algorithms ECDH, ECDSA, EdDSA, Ed25519, Ed448, X25519, or X448. If SubKeyCurve is not specified, the following subkey curves will be used by default for each SubKeyAlgorithm:
Sub Key Algorithm | Default Curve |
ECDSA | secp256r1 |
ECDH | secp256r1 |
EdDSA | Ed25519 |
Ed25519 | Ed25519 |
Ed448 | Ed448 |
X25519 | Curve25519 |
X448 | Curve448 |
Note that the SubKeyLength will be automatically determined by the specified SubKeyCurve, if applicable.
This configuration setting may optionally be specified to set a curve for the subkey which differs from the key curve specified by Curve. This is applicable in either of the following scenarios:
- When calling CreateKey and PublicKeyAlgorithm is set to ECDSA, EdDSA, Ed25519, or Ed448, and SubKeyAlgorithm is unspecified.
- When calling CreateKey or CreateSubKey and SubKeyAlgorithm is set to ECDH, ECDSA, EdDSA, Ed25519, Ed448, X25519, or X448.
Subkey Curve | Possible Subkey Algorithms | Description |
secp256r1 | ECDSA, ECDH | NIST curve P-256 |
secp384r1 | ECDSA, ECDH | NIST curve P-384 |
secp521r1 | ECDSA, ECDH | NIST curve P-521 |
secp256k1 | ECDSA, ECDH | Secp256k1 |
Ed25519 | EdDSA, Ed25519 | Ed25519 |
Ed448 | EdDSA, Ed448 | Ed448 |
Curve25519 | ECDH, X25519 | Curve25519 |
Curve448 | X448 | Curve448 |
Note if KeyVersion is set to 6, Curve25519 is not a valid subkey curve for ECDH.
This setting is applicable when creating keys with CreateKey, or creating subkeys with CreateSubKey. This specifies the length of the public subkey. The default value is 0, in which case the subkey will have the length specified by PublicKeyLength.
This configuration setting is only applicable when PublicKeyAlgorithm is specified as RSA, DSA, or ElGamal.
Note that when PublicKeyAlgorithm is set to RSA, it is highly recommended that the subkey length is at least 3072.
When calling CreateSubKey this setting defines the flags that show the intended use for the key. The default value is (0x0C). The value of SubKeyUsage is a combination of the following flags:
0x01 | This key may be used to certify other keys. |
0x02 | This key may be used to sign data. |
0x0C | This key may be used to encrypt communications and encrypt storage. |
0x10 | The private component of this key may have been split by a secret-sharing mechanism. |
0x20 | This key may be used for authentication. |
0x80 | The private component of this key may be in the possession of more than one person. |
Note that if KeyVersion is 6 and SubKeyAlgorithm is RSA, the key must have both signing and encrypting capabilities (0x0F).
Determines whether the Argon2 algorithm is used as the String-to-Key (S2K) method for passphrase-based key derivation when CreateKey is called. The default value is False.
The following configuration settings are applicable when this config is set to True:
Note if UseArgon2 is enabled, an AEAD encryption algorithm must be specified by KeyEncryptionAlgorithm (e.g., AES192-OCB). Please see KeyEncryptionAlgorithm for additional details.
This setting specifies the Version header value included in newly created public keys. This includes keys that are exported via ExportPublicKey where the UseAsciiArmor parameter is true. The default value is "IPWorks OpenPGP 2024".
Base Config Settings
When queried, this setting will return a string containing information about the product's build.
The default code page is Unicode UTF-8 (65001).
The following is a list of valid code page identifiers:
Identifier | Name |
037 | IBM EBCDIC - U.S./Canada |
437 | OEM - United States |
500 | IBM EBCDIC - International |
708 | Arabic - ASMO 708 |
709 | Arabic - ASMO 449+, BCON V4 |
710 | Arabic - Transparent Arabic |
720 | Arabic - Transparent ASMO |
737 | OEM - Greek (formerly 437G) |
775 | OEM - Baltic |
850 | OEM - Multilingual Latin I |
852 | OEM - Latin II |
855 | OEM - Cyrillic (primarily Russian) |
857 | OEM - Turkish |
858 | OEM - Multilingual Latin I + Euro symbol |
860 | OEM - Portuguese |
861 | OEM - Icelandic |
862 | OEM - Hebrew |
863 | OEM - Canadian-French |
864 | OEM - Arabic |
865 | OEM - Nordic |
866 | OEM - Russian |
869 | OEM - Modern Greek |
870 | IBM EBCDIC - Multilingual/ROECE (Latin-2) |
874 | ANSI/OEM - Thai (same as 28605, ISO 8859-15) |
875 | IBM EBCDIC - Modern Greek |
932 | ANSI/OEM - Japanese, Shift-JIS |
936 | ANSI/OEM - Simplified Chinese (PRC, Singapore) |
949 | ANSI/OEM - Korean (Unified Hangul Code) |
950 | ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC) |
1026 | IBM EBCDIC - Turkish (Latin-5) |
1047 | IBM EBCDIC - Latin 1/Open System |
1140 | IBM EBCDIC - U.S./Canada (037 + Euro symbol) |
1141 | IBM EBCDIC - Germany (20273 + Euro symbol) |
1142 | IBM EBCDIC - Denmark/Norway (20277 + Euro symbol) |
1143 | IBM EBCDIC - Finland/Sweden (20278 + Euro symbol) |
1144 | IBM EBCDIC - Italy (20280 + Euro symbol) |
1145 | IBM EBCDIC - Latin America/Spain (20284 + Euro symbol) |
1146 | IBM EBCDIC - United Kingdom (20285 + Euro symbol) |
1147 | IBM EBCDIC - France (20297 + Euro symbol) |
1148 | IBM EBCDIC - International (500 + Euro symbol) |
1149 | IBM EBCDIC - Icelandic (20871 + Euro symbol) |
1200 | Unicode UCS-2 Little-Endian (BMP of ISO 10646) |
1201 | Unicode UCS-2 Big-Endian |
1250 | ANSI - Central European |
1251 | ANSI - Cyrillic |
1252 | ANSI - Latin I |
1253 | ANSI - Greek |
1254 | ANSI - Turkish |
1255 | ANSI - Hebrew |
1256 | ANSI - Arabic |
1257 | ANSI - Baltic |
1258 | ANSI/OEM - Vietnamese |
1361 | Korean (Johab) |
10000 | MAC - Roman |
10001 | MAC - Japanese |
10002 | MAC - Traditional Chinese (Big5) |
10003 | MAC - Korean |
10004 | MAC - Arabic |
10005 | MAC - Hebrew |
10006 | MAC - Greek I |
10007 | MAC - Cyrillic |
10008 | MAC - Simplified Chinese (GB 2312) |
10010 | MAC - Romania |
10017 | MAC - Ukraine |
10021 | MAC - Thai |
10029 | MAC - Latin II |
10079 | MAC - Icelandic |
10081 | MAC - Turkish |
10082 | MAC - Croatia |
12000 | Unicode UCS-4 Little-Endian |
12001 | Unicode UCS-4 Big-Endian |
20000 | CNS - Taiwan |
20001 | TCA - Taiwan |
20002 | Eten - Taiwan |
20003 | IBM5550 - Taiwan |
20004 | TeleText - Taiwan |
20005 | Wang - Taiwan |
20105 | IA5 IRV International Alphabet No. 5 (7-bit) |
20106 | IA5 German (7-bit) |
20107 | IA5 Swedish (7-bit) |
20108 | IA5 Norwegian (7-bit) |
20127 | US-ASCII (7-bit) |
20261 | T.61 |
20269 | ISO 6937 Non-Spacing Accent |
20273 | IBM EBCDIC - Germany |
20277 | IBM EBCDIC - Denmark/Norway |
20278 | IBM EBCDIC - Finland/Sweden |
20280 | IBM EBCDIC - Italy |
20284 | IBM EBCDIC - Latin America/Spain |
20285 | IBM EBCDIC - United Kingdom |
20290 | IBM EBCDIC - Japanese Katakana Extended |
20297 | IBM EBCDIC - France |
20420 | IBM EBCDIC - Arabic |
20423 | IBM EBCDIC - Greek |
20424 | IBM EBCDIC - Hebrew |
20833 | IBM EBCDIC - Korean Extended |
20838 | IBM EBCDIC - Thai |
20866 | Russian - KOI8-R |
20871 | IBM EBCDIC - Icelandic |
20880 | IBM EBCDIC - Cyrillic (Russian) |
20905 | IBM EBCDIC - Turkish |
20924 | IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol) |
20932 | JIS X 0208-1990 & 0121-1990 |
20936 | Simplified Chinese (GB2312) |
21025 | IBM EBCDIC - Cyrillic (Serbian, Bulgarian) |
21027 | Extended Alpha Lowercase |
21866 | Ukrainian (KOI8-U) |
28591 | ISO 8859-1 Latin I |
28592 | ISO 8859-2 Central Europe |
28593 | ISO 8859-3 Latin 3 |
28594 | ISO 8859-4 Baltic |
28595 | ISO 8859-5 Cyrillic |
28596 | ISO 8859-6 Arabic |
28597 | ISO 8859-7 Greek |
28598 | ISO 8859-8 Hebrew |
28599 | ISO 8859-9 Latin 5 |
28605 | ISO 8859-15 Latin 9 |
29001 | Europa 3 |
38598 | ISO 8859-8 Hebrew |
50220 | ISO 2022 Japanese with no halfwidth Katakana |
50221 | ISO 2022 Japanese with halfwidth Katakana |
50222 | ISO 2022 Japanese JIS X 0201-1989 |
50225 | ISO 2022 Korean |
50227 | ISO 2022 Simplified Chinese |
50229 | ISO 2022 Traditional Chinese |
50930 | Japanese (Katakana) Extended |
50931 | US/Canada and Japanese |
50933 | Korean Extended and Korean |
50935 | Simplified Chinese Extended and Simplified Chinese |
50936 | Simplified Chinese |
50937 | US/Canada and Traditional Chinese |
50939 | Japanese (Latin) Extended and Japanese |
51932 | EUC - Japanese |
51936 | EUC - Simplified Chinese |
51949 | EUC - Korean |
51950 | EUC - Traditional Chinese |
52936 | HZ-GB2312 Simplified Chinese |
54936 | Windows XP: GB18030 Simplified Chinese (4 Byte) |
57002 | ISCII Devanagari |
57003 | ISCII Bengali |
57004 | ISCII Tamil |
57005 | ISCII Telugu |
57006 | ISCII Assamese |
57007 | ISCII Oriya |
57008 | ISCII Kannada |
57009 | ISCII Malayalam |
57010 | ISCII Gujarati |
57011 | ISCII Punjabi |
65000 | Unicode UTF-7 |
65001 | Unicode UTF-8 |
Identifier | Name |
1 | ASCII |
2 | NEXTSTEP |
3 | JapaneseEUC |
4 | UTF8 |
5 | ISOLatin1 |
6 | Symbol |
7 | NonLossyASCII |
8 | ShiftJIS |
9 | ISOLatin2 |
10 | Unicode |
11 | WindowsCP1251 |
12 | WindowsCP1252 |
13 | WindowsCP1253 |
14 | WindowsCP1254 |
15 | WindowsCP1250 |
21 | ISO2022JP |
30 | MacOSRoman |
10 | UTF16String |
0x90000100 | UTF16BigEndian |
0x94000100 | UTF16LittleEndian |
0x8c000100 | UTF32String |
0x98000100 | UTF32BigEndian |
0x9c000100 | UTF32LittleEndian |
65536 | Proprietary |
When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:
- Product: The product the license is for.
- Product Key: The key the license was generated from.
- License Source: Where the license was found (e.g., RuntimeLicense, License File).
- License Type: The type of license installed (e.g., Royalty Free, Single Server).
- Last Valid Build: The last valid build number for which the license will work.
In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to true to mask sensitive data. The default is true.
This setting only works on these components: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.
When set to true, the component will utilize the underlying operating system's certified APIs. Java editions, regardless of OS, utilize Bouncy Castle Federal Information Processing Standards (FIPS), while all other Windows editions make use of Microsoft security libraries.
FIPS mode can be enabled by setting the UseFIPSCompliantAPI configuration setting to true. This is a static setting that applies to all instances of all components of the toolkit within the process. It is recommended to enable or disable this setting once before the component has been used to establish a connection. Enabling FIPS while an instance of the component is active and connected may result in unexpected behavior.
For more details, please see the FIPS 140-2 Compliance article.
Note: This setting is applicable only on Windows.
Note: Enabling FIPS compliance requires a special license; please contact sales@nsoftware.com for details.
When set to false, the component will use the system security libraries by default to perform cryptographic functions where applicable.
Setting this configuration setting to true tells the component to use the internal implementation instead of using the system security libraries.
This setting is set to false by default on all platforms.
Trappable Errors (KeyMgr Component)
OpenPGP Errors
101 | Cannot decode ASCII Armor data. |
102 | Unknown ASCII Armor data type. |
103 | Checksum failed. |
104 | Unknown ASCII Armor header. |
105 | Cannot decode PGP packet. |
106 | Cannot encode PGP packet. |
107 | Unknown PGP packet tag. |
108 | Unsupported version. |
109 | Unsupported algorithm. |
110 | Unknown subpacket. |
111 | Internal error. |
112 | Feature not supported. |
113 | Secret data was not encrypted. |
114 | Cannot find the key. |
115 | Error reading file. |
116 | Error writing file. |
117 | Error reading key. |
118 | Error writing key. |
119 | Cannot verify signature. |
120 | Cannot create signature. |
121 | Invalid UserId. |
122 | Invalid passphrase. |
123 | Data encryption failed. |
124 | Error creating key. |
125 | Unsupported symmetric algorithm. |
126 | Unsupported hash. |
127 | Unsupported compression algorithm. |
128 | Invalid key usage. |
129 | Component is busy. |
130 | Error decrypting data. |
131 | Data is not compressed. |
132 | Error decompressing data. |
133 | Error compressing data. |
134 | Unsupported signature. |
135 | Failed to overwrite file. |
141 | No input. |
142 | Signing was required, but the message was not signed. |
143 | Encryption was required, but the message was not encrypted. |
146 | No data integrity packet was found (MDC), but one was required. |
200 | Out of memory. |