KeyMgr Control

Properties Methods Events Config Settings Errors

The KeyMgr control is used to create and manage OpenPGP keys.

Syntax

KeyMgr

Remarks

The KeyMgr control 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 control 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 control 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 control 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 control 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 control 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.
CodePage	The system code page used for Unicode to Multibyte translations.
MaskSensitiveData	Whether sensitive data is masked in log messages.
UseInternalSecurityAPI	Whether or not to use the system security libraries or an internal implementation.

KeyCurve Property (KeyMgr Control)

This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , or Ed448 .

Syntax

keymgrcontrol.KeyCurve

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

The date when this key becomes valid.

Syntax

keymgrcontrol.KeyEffectiveDate

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

The key.

Syntax

keymgrcontrol.KeyEncoded[=string]

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.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .KeyEncodedB.

This property is not available at design time.

Data Type

Binary String

KeyExpirationDate Property (KeyMgr Control)

The date the key expires.

Syntax

keymgrcontrol.KeyExpirationDate

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

The hex-encoded, 20-byte fingerprint of the key.

Syntax

keymgrcontrol.KeyFingerprint[=string]

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 controlwill 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 Control)

The hex-encoded, 4-byte or 8-byte key Id.

Syntax

keymgrcontrol.KeyId[=string]

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 control 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 Control)

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

Syntax

keymgrcontrol.KeyOtherUserIds

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

The passphrase for the key's secret key (if any).

Syntax

keymgrcontrol.KeyPassphrase[=string]

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 control, or an email-based control, 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 Control)

The public key of the key.

Syntax

keymgrcontrol.KeyPublicKey

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

A text description of the public key algorithm of the key.

Syntax

keymgrcontrol.KeyPublicKeyAlgorithm

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

The length of the public key in bits.

Syntax

keymgrcontrol.KeyPublicKeyLength

Default Value

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

Whether or not the key is revoked.

Syntax

keymgrcontrol.KeyRevoked

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

The secret key of the key (if available).

Syntax

keymgrcontrol.KeySecretKey

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

Whether or not a secret key is available for the selected key.

Syntax

keymgrcontrol.KeySecretKeyAvailable

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

A text description of UsageFlags .

Syntax

keymgrcontrol.KeyUsage

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

Flags that show the intended use for the key.

Syntax

keymgrcontrol.KeyUsageFlags

Default Value

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

The user Id of the key.

Syntax

keymgrcontrol.KeyUserId[=string]

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 control 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 control 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 control's RecipientInfo event.

This property is not available at design time.

Data Type

String

KeyVersion Property (KeyMgr Control)

This property can be used to query the OpenPGP version of the currently selected Key .

Syntax

keymgrcontrol.KeyVersion

Default Value

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

The location on disk of the keyring.

Syntax

keymgrcontrol.Keyring

Default Value

Remarks

To load a keyring use the LoadKeyring method.

This property is read-only.

Data Type

String

AddRevoker Method (KeyMgr Control)

Adds a designated revoker to the key.

Syntax

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

AddUserId Method (KeyMgr Control)

Adds the specified user Id to the current key.

Syntax

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

ChangeExpirationDate Method (KeyMgr Control)

Changes the expiration date of the key.

Syntax

keymgrcontrol.ChangeExpirationDate 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 Control)

Changes the passphrase of the current key.

Syntax

keymgrcontrol.ChangePassphrase 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 Control)

Sets or retrieves a configuration setting.

Syntax

keymgrcontrol.Config ConfigurationString

Remarks

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

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

Creates an OpenPGP key pair.

Syntax

keymgrcontrol.CreateKey UserId, 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.

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

Creates a new subkey.

Syntax

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

KeyValidityTime
PublicKeyLength
SubKeyAlgorithm
SubKeyLength
SubKeyCurve
SubKeyUsage

DeleteKey Method (KeyMgr Control)

Deletes the specified key.

Syntax

keymgrcontrol.DeleteKey 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 Control)

Exports the public key of the current key.

Syntax

keymgrcontrol.ExportPublicKey FileName, 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 Control)

Exports the private key of the current key.

Syntax

keymgrcontrol.ExportSecretKey FileName, 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 Control)

Imports the key specified by UserId to the current keyring.

Syntax

keymgrcontrol.ImportKey FileName, 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 control in this case.

Note: If you simply wish to select a key in the current ring set KeyUserId instead.

ImportKeyB Method (KeyMgr Control)

Imports the key specified by UserId to the current keyring.

Syntax

keymgrcontrol.ImportKeyB Data, 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 control in this case.

Note: If you simply wish to select a key in the current ring set KeyUserId instead.

ListKeys Method (KeyMgr Control)

Lists keys in the specified Keyring .

Syntax

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

Lists all signatures of the current key.

Syntax

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

Lists the subkeys of the currently selected key.

Syntax

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

Loads the keyring from disk.

Syntax

keymgrcontrol.LoadKeyring 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 control 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 Control)

Loads the keyring from SecretKeyringData and PublicKeyringData .

Syntax

keymgrcontrol.LoadKeyringB SecretKeyringData, PublicKeyringData

Remarks

This method loads the keyring from SecretKeyringData and PublicKeyringData.

When this method is called the control 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 Control)

Resets the control properties.

Syntax

keymgrcontrol.Reset

Remarks

This method resets all message and key properties to their default values.

RevokeKey Method (KeyMgr Control)

Revokes the specified key.

Syntax

keymgrcontrol.RevokeKey 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 Control)

Saves the current Keyring to disk.

Syntax

keymgrcontrol.SaveKeyring 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 control 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 Control)

Signs the specified user Id of the current key.

Syntax

keymgrcontrol.SignUserId UserId, 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 Control)

Verifies the passphrase of specified key.

Syntax

keymgrcontrol.VerifyPassphrase 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 Control)

Fired when information is available about errors during data delivery.

Syntax

Sub keymgrcontrol_Error(ErrorCode As Integer, Description As String)

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the control fails with an error.

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

Fires for each key in the keyring when ListKeys is called.

Syntax

Sub keymgrcontrol_KeyList(UserId As String, KeyId As String, Fingerprint As String, HasSecretKey As Boolean, PublicKeyAlgorithm As String, PublicKeyLength As Integer, Curve As String)

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.

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

Fired if the passphrase of current key is incorrect or empty.

Syntax

Sub keymgrcontrol_KeyPassphrase(UserId As String, KeyId As String, Fingerprint As String, Passphrase As String)

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:

AddUserId
SignUserId
ChangeExpirationDate
ChangePassphrase

When using the OpenPGP control, or an email-based control, 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.

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

Fires for each signature of the current key when ListSignatures is called.

Syntax

Sub keymgrcontrol_SignatureList(KeyId As String, Fingerprint As String, UserId As String, IssuerFingerprint As String, IssuerKeyId As String, IssuerUserId As String, PublicKeyAlgorithm As String, Curve As String, HashAlgorithm As String, EffectiveDate As String, SignatureClass As Integer, ValidityStatus As Integer)

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.

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

Shows the progress of the operation.

Syntax

Sub keymgrcontrol_Status(Message As String)

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

Fires once for each subkey listed when ListSubkeys is called.

Syntax

Sub keymgrcontrol_SubkeyList(KeyId As String, Fingerprint As String, PublicKeyAlgorithm As String, PublicKeyLength As Integer, Curve As String, UsageFlags As Integer, Usage As String, EffectiveDate As String, ExpirationDate As String, Revoked As Boolean)

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

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

KeyMgr Config Settings

AllowEmptyPassword: Whether a key can be created without a password.

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.

Argon2Iterations: Specifies the number of iterations used for Argon2.

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

Argon2MemorySizeExp: Specifies the exponent used to calculate the memory size used when creating a key.

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.

Argon2Parallelism: Specifies the degree of parallelism used for Argon2.

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.

ContinueOnInvalidKey: Whether to continue loading the keyring when an invalid key is found.

This setting determines whether the control will continue loading keys when an invalid key is found. This is applicable when calling LoadKeyring. If set to False (default) the control fails with an error. If set to True the control will fire the Error event with information about the key which failed to load, and then continue loading additional keys.

CreateRSASubkeyForEncrypt: Whether to create a subkey when creating an RSA key.

This setting determines whether the control 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.

CurrentKeyPrimaryKeyUsageFlags: The usage flags of the currently selected primary 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.

Curve: The elliptic curve used when creating a key.

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

EnsureValidDSASignatureHashAlgorithm: Whether or not to select a suitable signature hash algorithm automatically.

This setting specifies whether the control 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 control 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 control 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 control 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 control will automatically select a valid hash algorithm based on the curve as follows:


Curve	Hash Algorithm
secp256r1	SHA256
secp384r1	SHA384
secp521r1	SHA512
secp256k1	SHA256

ImportAllKeys: Whether or not to import all keys found in a key file.

When calling ImportKey with a UserId parameter of "*" or "", the control 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.

KeyBoxProtectionMode: Specifies the keybox protection mode used when saving a keyring.

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

KeyEncryptionAlgorithm: The encryption algorithm used when creating a key.

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.

KeyIdLength: Specifies the length of the key's Id.

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

KeyPreferredAEADAlgorithms: Indicates the preferred AEAD encryption algorithms associated with the currently selected key.

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"

KeyPreferredCompressionAlgorithms: Indicates the preferred compression algorithms associated with the currently selected key.

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"

KeyPreferredHashAlgorithms: Indicates the preferred hash algorithms associated with the currently selected key.

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"

KeyPreferredSymmetricAlgorithms: Indicates the preferred symmetric algorithms associated with the currently selected key.

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"

KeyringFormat: Specifies the keyring format to use when saving a keyring.

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");

KeyUsage: Flags that show intended use for the key being created.

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.

KeyValidityTime: The validity period for the key being created.

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.

KeyVersion: Specifies the OpenPGP version for the key being created.

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)

LogLevel: Specifies the level of detail that is logged.

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.

PreferredAEADAlgorithms: Specifies a key's preferred AEAD encryption algorithms when creating a key.

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

PreferredCompressionAlgorithms: Specifies a key's preferred compression algorithms when creating a key.

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

PreferredHashAlgorithms: Specifies a key's preferred hash algorithms when creating a key.

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

PreferredSymmetricAlgorithms: Specifies a key's preferred symmetric algorithms when creating a key.

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

PublicKeyAlgorithm: The public key algorithm for the key being created.

Specifies the public key algorithm to use when creating the key via CreateKey. By default, this config will be set to automatic and the control 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 control will automatically select appropriate values based on the PublicKeyAlgorithm.

SubKeyAlgorithm
SubKeyLength
SubKeyCurve

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.

PublicKeyLength: Specifies the public key length when creating a key.

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.

PublicKeyringFile: The file name of the public keyring file.

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.

PublicKeySignatureHashAlgorithm: The public key signature hash algorithm used when creating a key.

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

RawKeyData: Returns detailed key and keyring data for debugging purposes.

This setting will return detailed debugging information about the current key and keyring.

RevocationCode: The reason why the key was revoked.

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

The default value is 0.

RevocationReason: Text describing why the key was revoked.

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.

Revoker: The revoker's key Id.

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.

SecretKeyringFile: The file name of the secret keyring file.

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.

SubKeyAlgorithm: The public key algorithm for the subkey being created.

Specifies the public key algorithm for a subkey created when calling CreateSubKey. The default value is empty string and the control 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.

SubKeyCurve: The elliptic curve of the sub key.

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.

Possible values for the SubKeyCurve and associated SubKeyAlgorithm's 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

Note if KeyVersion is set to 6, Curve25519 is not a valid subkey curve for ECDH.

SubKeyLength: Specifies the public subkey length when creating a key or subkey.

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.

SubKeyUsage: Flags that show intended use for the subkey being created.

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

UseArgon2: Whether to use Argon2 for key derivation when creating a key.

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:

Argon2Iterations
Argon2Parallelism
Argon2MemorySizeExp

Note if UseArgon2 is enabled, an AEAD encryption algorithm must be specified by KeyEncryptionAlgorithm (e.g., AES192-OCB). Please see KeyEncryptionAlgorithm for additional details.

VersionHeader: The Version header value in ASCII armored public keys.

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

CodePage: The system code page used for Unicode to Multibyte translations.

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

The following is a list of valid code page identifiers for Mac OS only:


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

MaskSensitiveData: Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to to mask sensitive data. The default is .

This setting only works on these controls: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

UseInternalSecurityAPI: Whether or not to use the system security libraries or an internal implementation.

When set to , the control will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to tells the control to use the internal implementation instead of using the system security libraries.

This setting is set to by default on all platforms.

Trappable Errors (KeyMgr Control)

OpenPGP Errors

20102	Cannot decode ASCII Armor data.
20103	Unknown ASCII Armor data type.
20104	Checksum failed.
20105	Unknown ASCII Armor header.
20106	Cannot decode PGP packet.
20107	Cannot encode PGP packet.
20108	Unknown PGP packet tag.
20109	Unsupported version.
20110	Unsupported algorithm.
20111	Unknown subpacket.
20112	Internal error.
20113	Feature not supported.
20114	Secret data was not encrypted.
20115	Cannot find the key.
20116	Error reading file.
20117	Error writing file.
20118	Error reading key.
20119	Error writing key.
20120	Cannot verify signature.
20121	Cannot create signature.
20122	Invalid UserId.
20123	Invalid passphrase.
20124	Data encryption failed.
20125	Error creating key.
20126	Unsupported symmetric algorithm.
20127	Unsupported hash.
20128	Unsupported compression algorithm.
20129	Invalid key usage.
20130	Component is busy.
20131	Error decrypting data.
20132	Data is not compressed.
20133	Error decompressing data.
20134	Error compressing data.
20135	Unsupported signature.
20136	Failed to overwrite file.
20142	No input.
20143	Signing was required, but the message was not signed.
20144	Encryption was required, but the message was not encrypted.
20147	No data integrity packet was found (MDC), but one was required.
20201	Out of memory.