KeyMgr Class

Properties Methods Events Config Settings Errors

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

Syntax

class ipworksopenpgp.KeyMgr

Remarks

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


key_curve	This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , or Ed448 .
key_effective_date	The date when this key becomes valid.
key_encoded	The key.
key_expiration_date	The date the key expires.
key_fingerprint	The hex-encoded, 20-byte fingerprint of the key.
key_id	The hex-encoded, 4-byte or 8-byte key Id.
key_other_user_ids	If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.
key_passphrase	The passphrase for the key's secret key (if any).
key_public_key	The public key of the key.
key_public_key_algorithm	A text description of the public key algorithm of the key.
key_public_key_length	The length of the public key in bits.
key_revoked	Whether or not the key is revoked.
key_secret_key	The secret key of the key (if available).
key_secret_key_available	Whether or not a secret key is available for the selected key.
key_usage	A text description of UsageFlags .
key_usage_flags	Flags that show the intended use for the key.
key_user_id	The user Id of the key.
key_version	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 class with short descriptions. Click on the links for further details.


add_revoker	Adds a designated revoker to the key.
add_user_id	Adds the specified user Id to the current key.
change_expiration_date	Changes the expiration date of the key.
change_passphrase	Changes the passphrase of the current key.
config	Sets or retrieves a configuration setting.
create_key	Creates an OpenPGP key pair.
create_sub_key	Creates a new subkey.
delete_key	Deletes the specified key.
export_public_key	Exports the public key of the current key.
export_secret_key	Exports the private key of the current key.
import_key	Imports the key specified by UserId to the current keyring.
import_key_b	Imports the key specified by UserId to the current keyring.
list_keys	Lists keys in the specified Keyring .
list_signatures	Lists all signatures of the current key.
list_subkeys	Lists the subkeys of the currently selected key.
load_keyring	Loads the keyring from disk.
load_keyring_b	Loads the keyring from SecretKeyringData and PublicKeyringData .
reset	Resets the class properties.
revoke_key	Revokes the specified key.
save_keyring	Saves the current Keyring to disk.
sign_user_id	Signs the specified user Id of the current key.
verify_passphrase	Verifies the passphrase of specified key.

Event List

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


on_error	Fired when information is available about errors during data delivery.
on_key_list	Fires for each key in the keyring when ListKeys is called.
on_key_passphrase	Fired if the passphrase of current key is incorrect or empty.
on_signature_list	Fires for each signature of the current key when ListSignatures is called.
on_status	Shows the progress of the operation.
on_subkey_list	Fires once for each subkey listed when ListSubkeys is called.

Config Settings

The following is a list of config settings for the class 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.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseFIPSCompliantAPI	Tells the class whether or not to use FIPS certified APIs.
UseInternalSecurityAPI	Whether or not to use the system security libraries or an internal implementation.

key_curve Property

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

Syntax

def get_key_curve() -> str: ...

key_curve = property(get_key_curve, None)

Default Value

Remarks

This property specifies the elliptic curve if key_public_key_algorithm 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.

key_effective_date Property

The date when this key becomes valid.

Syntax

def get_key_effective_date() -> str: ...

key_effective_date = property(get_key_effective_date, None)

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.

key_encoded Property

The key.

Syntax

def get_key_encoded() -> bytes: ...
def set_key_encoded(value: bytes) -> None: ...

key_encoded = property(get_key_encoded, set_key_encoded)

Default Value

Remarks

The key. This property can be used to assign a specific key. The key_fingerprint, key_id, and key_user_id properties may also be used to specify a key.

key_expiration_date Property

The date the key expires.

Syntax

def get_key_expiration_date() -> str: ...

key_expiration_date = property(get_key_expiration_date, None)

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.

key_fingerprint Property

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

Syntax

def get_key_fingerprint() -> str: ...
def set_key_fingerprint(value: str) -> None: ...

key_fingerprint = property(get_key_fingerprint, set_key_fingerprint)

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 classwill search the keyring for a key associated with the Fingerprint specified.

This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

key_id Property

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

Syntax

def get_key_id() -> str: ...
def set_key_id(value: str) -> None: ...

key_id = property(get_key_id, set_key_id)

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 class 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 key_fingerprint property when loading a key from the keyring, as it is possible for different keys to have the same Id.

key_other_user_ids Property

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

Syntax

def get_key_other_user_ids() -> str: ...

key_other_user_ids = property(get_key_other_user_ids, None)

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.

key_passphrase Property

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

Syntax

def get_key_passphrase() -> str: ...
def set_key_passphrase(value: str) -> None: ...

key_passphrase = property(get_key_passphrase, set_key_passphrase)

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 on_key_passphrase event, which will fire when a passphrase is required.

The passphrase is required when using the following methods in KeyMgr:

add_user_id
sign_user_id
change_expiration_date
change_passphrase

When using the OpenPGP class, or an email-based class, the following methods require a passphrase for the key:

decrypt
sign
sign_and_encrypt

key_public_key Property

The public key of the key.

Syntax

def get_key_public_key() -> str: ...

key_public_key = property(get_key_public_key, None)

Default Value

Remarks

The public key of the key. The key is provided as ASCII armored data.

This property is read-only.

key_public_key_algorithm Property

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

Syntax

def get_key_public_key_algorithm() -> str: ...

key_public_key_algorithm = property(get_key_public_key_algorithm, None)

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.

key_public_key_length Property

The length of the public key in bits.

Syntax

def get_key_public_key_length() -> int: ...

key_public_key_length = property(get_key_public_key_length, None)

Default Value

Remarks

The length of the public key in bits. Common values are 1024, 2048, and 3072.

If the key_public_key_algorithm property is ECDSA, EdDSA, Ed25519, or Ed448, the length of the public key is determined by the key_curve. 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.

key_revoked Property

Whether or not the key is revoked.

Syntax

def get_key_revoked() -> bool: ...

key_revoked = property(get_key_revoked, None)

Default Value

FALSE

Remarks

Whether or not the key is revoked.

This property is read-only.

key_secret_key Property

The secret key of the key (if available).

Syntax

def get_key_secret_key() -> str: ...

key_secret_key = property(get_key_secret_key, None)

Default Value

Remarks

The secret key of the key (if available). The key is provided as ASCII armored data.

This property is read-only.

key_secret_key_available Property

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

Syntax

def get_key_secret_key_available() -> bool: ...

key_secret_key_available = property(get_key_secret_key_available, None)

Default Value

FALSE

Remarks

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

This property is read-only.

key_usage Property

A text description of UsageFlags .

Syntax

def get_key_usage() -> str: ...

key_usage = property(get_key_usage, None)

Default Value

Remarks

A text description of key_usage_flags.

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.

key_usage_flags Property

Flags that show the intended use for the key.

Syntax

def get_key_usage_flags() -> int: ...

key_usage_flags = property(get_key_usage_flags, None)

Default Value

Remarks

Flags that show the intended use for the key. The default value is 0x0F. The value of key_usage_flags 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 key_usage property for a text representation of key_usage_flags.

This property is read-only.

key_user_id Property

The user Id of the key.

Syntax

def get_key_user_id() -> str: ...
def set_key_user_id(value: str) -> None: ...

key_user_id = property(get_key_user_id, set_key_user_id)

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 class 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 key_other_user_ids 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 class 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 class's on_recipient_info event.

key_version Property

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

Syntax

def get_key_version() -> int: ...

key_version = property(get_key_version, None)

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.

keyring Property

The location on disk of the keyring.

Syntax

def get_keyring() -> str: ...

keyring = property(get_keyring, None)

Default Value

Remarks

To load a keyring use the load_keyring method.

This property is read-only.

add_revoker Method

Adds a designated revoker to the key.

Syntax

def add_revoker(user_id: str) -> None: ...

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 key_passphrase or through the on_key_passphrase 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.

add_user_id Method

Adds the specified user Id to the current key.

Syntax

def add_user_id(user_id: str) -> None: ...

Remarks

The key's passphrase is required for this operation and may be specified via key_passphrase or through the on_key_passphrase 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.

change_expiration_date Method

Changes the expiration date of the key.

Syntax

def change_expiration_date(expiration_date: int) -> None: ...

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 key_passphrase or through the on_key_passphrase event.

Note: See KeyValidityTime for information on specifying the expiration date when creating the key with create_key.

change_passphrase Method

Changes the passphrase of the current key.

Syntax

def change_passphrase(passphrase: str) -> None: ...

Remarks

The Passphrase parameter specifies the new passphrase.

The key's passphrase is required for this operation and may be specified via key_passphrase or through the on_key_passphrase event.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

create_key Method

Creates an OpenPGP key pair.

Syntax

def create_key(user_id: str, passphrase: str) -> None: ...

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

create_sub_key Method

Creates a new subkey.

Syntax

def create_sub_key() -> None: ...

Remarks

This method creates a new subkey. Before calling this method the key_id 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

delete_key Method

Deletes the specified key.

Syntax

def delete_key(user_id: str) -> None: ...

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

export_public_key Method

Exports the public key of the current key.

Syntax

def export_public_key(file_name: str, use_ascii_armor: bool) -> None: ...

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.

export_secret_key Method

Exports the private key of the current key.

Syntax

def export_secret_key(file_name: str, use_ascii_armor: bool) -> None: ...

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.

import_key Method

Imports the key specified by UserId to the current keyring.

Syntax

def import_key(file_name: str, user_id: str) -> None: ...

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 class in this case.

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

import_key_b Method

Imports the key specified by UserId to the current keyring.

Syntax

def import_key_b(data: bytes, user_id: str) -> None: ...

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 class in this case.

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

list_keys Method

Lists keys in the specified Keyring .

Syntax

def list_keys() -> str: ...

Remarks

This method lists the keys (public/private key pairs) in the specified keyring. The results are provided through the on_key_list event.

KeyList data will also be returned from this method, however it is recommended to use the on_key_list event if possible.

list_signatures Method

Lists all signatures of the current key.

Syntax

def list_signatures() -> str: ...

Remarks

This method lists all the signatures of the currently selected key. The on_signature_list event will fire for each signature.

SignatureList data will also be returned from this method. However, it is recommended to use the on_signature_list event if possible.

list_subkeys Method

Lists the subkeys of the currently selected key.

Syntax

def list_subkeys() -> str: ...

Remarks

This method lists all subkeys of current key. The on_subkey_list event will be fired for each subkey.

SubkeyList data will also be returned from this method, however it is recommended to use the on_subkey_list event if possible.

load_keyring Method

Loads the keyring from disk.

Syntax

def load_keyring(keyring_path: str) -> None: ...

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 class will read the keyring and populate the key property with the first key found in the keyring. Set key_user_id to select a different key in the current keyring.

load_keyring_b Method

Loads the keyring from SecretKeyringData and PublicKeyringData .

Syntax

def load_keyring_b(secret_keyring_data: bytes, public_keyring_data: bytes) -> None: ...

Remarks

This method loads the keyring from SecretKeyringData and PublicKeyringData.

When this method is called the class will read the keyring and populate the key property with the first key found in the keyring. Set key_user_id to select a different key in the current keyring.

reset Method

Resets the class properties.

Syntax

def reset() -> None: ...

Remarks

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

revoke_key Method

Revokes the specified key.

Syntax

def revoke_key(key_id: str) -> str: ...

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 export_public_key after calling this method. Both formats are common, and both formats are acceptable when calling import_key.

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

save_keyring Method

Saves the current Keyring to disk.

Syntax

def save_keyring(keyring_path: str) -> None: ...

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

sign_user_id Method

Signs the specified user Id of the current key.

Syntax

def sign_user_id(user_id: str, issuer_user_id: str) -> None: ...

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 key_passphrase or through the on_key_passphrase event.

verify_passphrase Method

Verifies the passphrase of specified key.

Syntax

def verify_passphrase(passphrase: str) -> bool: ...

Remarks

This method verifies the passphrase of the key specified by user_id.

If the password is correct, this method returns True; otherwise, this method returns False.

on_error Event

Fired when information is available about errors during data delivery.

Syntax

class KeyMgrErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class KeyMgr:
@property
def on_error() -> Callable[[KeyMgrErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[KeyMgrErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class 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.

on_key_list Event

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

Syntax

class KeyMgrKeyListEventParams(object):
  @property
  def user_id() -> str: ...

  @property
  def key_id() -> str: ...

  @property
  def fingerprint() -> str: ...

  @property
  def has_secret_key() -> bool: ...

  @property
  def public_key_algorithm() -> str: ...

  @property
  def public_key_length() -> int: ...

  @property
  def curve() -> str: ...

# In class KeyMgr:
@property
def on_key_list() -> Callable[[KeyMgrKeyListEventParams], None]: ...
@on_key_list.setter
def on_key_list(event_hook: Callable[[KeyMgrKeyListEventParams], None]) -> None: ...

Remarks

This event fires once for each key in the keyring when list_keys 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

on_key_passphrase Event

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

Syntax

class KeyMgrKeyPassphraseEventParams(object):
  @property
  def user_id() -> str: ...

  @property
  def key_id() -> str: ...

  @property
  def fingerprint() -> str: ...

  @property
  def passphrase() -> str: ...
  @passphrase.setter
  def passphrase(value) -> None: ...

# In class KeyMgr:
@property
def on_key_passphrase() -> Callable[[KeyMgrKeyPassphraseEventParams], None]: ...
@on_key_passphrase.setter
def on_key_passphrase(event_hook: Callable[[KeyMgrKeyPassphraseEventParams], None]) -> None: ...

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 key_passphrase property before attempting the operation.

The passphrase is required when using the following methods in KeyMgr:

add_user_id
sign_user_id
change_expiration_date
change_passphrase

When using the OpenPGP class, or an email-based class, the following methods require a passphrase for the key:

decrypt
sign
sign_and_encrypt

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

on_signature_list Event

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

Syntax

class KeyMgrSignatureListEventParams(object):
  @property
  def key_id() -> str: ...

  @property
  def fingerprint() -> str: ...

  @property
  def user_id() -> str: ...

  @property
  def issuer_fingerprint() -> str: ...

  @property
  def issuer_key_id() -> str: ...

  @property
  def issuer_user_id() -> str: ...

  @property
  def public_key_algorithm() -> str: ...

  @property
  def curve() -> str: ...

  @property
  def hash_algorithm() -> str: ...

  @property
  def effective_date() -> str: ...

  @property
  def signature_class() -> int: ...

  @property
  def validity_status() -> int: ...

# In class KeyMgr:
@property
def on_signature_list() -> Callable[[KeyMgrSignatureListEventParams], None]: ...
@on_signature_list.setter
def on_signature_list(event_hook: Callable[[KeyMgrSignatureListEventParams], None]) -> None: ...

Remarks

This event fires once for each signature of the current key when list_signatures 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)

on_status Event

Shows the progress of the operation.

Syntax

class KeyMgrStatusEventParams(object):
  @property
  def message() -> str: ...

# In class KeyMgr:
@property
def on_status() -> Callable[[KeyMgrStatusEventParams], None]: ...
@on_status.setter
def on_status(event_hook: Callable[[KeyMgrStatusEventParams], None]) -> None: ...

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.

on_subkey_list Event

Fires once for each subkey listed when ListSubkeys is called.

Syntax

class KeyMgrSubkeyListEventParams(object):
  @property
  def key_id() -> str: ...

  @property
  def fingerprint() -> str: ...

  @property
  def public_key_algorithm() -> str: ...

  @property
  def public_key_length() -> int: ...

  @property
  def curve() -> str: ...

  @property
  def usage_flags() -> int: ...

  @property
  def usage() -> str: ...

  @property
  def effective_date() -> str: ...

  @property
  def expiration_date() -> str: ...

  @property
  def revoked() -> bool: ...

# In class KeyMgr:
@property
def on_subkey_list() -> Callable[[KeyMgrSubkeyListEventParams], None]: ...
@on_subkey_list.setter
def on_subkey_list(event_hook: Callable[[KeyMgrSubkeyListEventParams], None]) -> None: ...

Remarks

This event fires once for each subkey when list_subkeys 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.

KeyMgr Config Settings

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

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, create_key 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 create_key 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 create_key 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 create_key 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 class will continue loading keys when an invalid key is found. This is applicable when calling load_keyring. If set to False (default) the class fails with an error. If set to True the class will fire the on_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 class will additionally create a subkey marked for encryption when calling create_key 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 key_usage_flags.

Curve: The elliptic curve used when creating a key.

This configuration setting specifies the curve to use when calling create_key. 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 class 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 class 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 class 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 key_curve used by the key. When this setting is enabled (default) the class 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 class 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 import_key with a UserId parameter of "*" or "", the class 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 import_key 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 save_keyring. 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 create_key. 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 key_id 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 save_keyring. 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 create_key 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 create_key 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 create_key. 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 on_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 create_key. 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 create_key. 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 create_key. 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 create_key. 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 create_key. By default, this config will be set to automatic and the class 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 class 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 create_key. 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 create_key. 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 key_revoked is True. This may be set before calling revoke_key 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 key_revoked is True. This may be set before calling revoke_key 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 add_revoker). 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 create_sub_key. The default value is empty string and the class 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 create_key and PublicKeyAlgorithm is set to ECDSA, EdDSA, Ed25519, or Ed448, and SubKeyAlgorithm is unspecified.
When calling create_key or create_sub_key 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 create_key, or creating subkeys with create_sub_key. 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 create_sub_key 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 create_key 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 export_public_key where the UseAsciiArmor parameter is true. The default value is "IPWorks OpenPGP 2024".

Base Config Settings

BuildInfo: Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

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

LicenseInfo: Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class 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.

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 True to mask sensitive data. The default is True.

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

ProcessIdleEvents: Whether the class uses its internal event loop to process events when the main thread is idle.

If set to False, the class will not fire internal idle events. Set this to False to use the class in a background thread on Mac OS. By default, this setting is True.

SelectWaitMillis: The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.

If there are no events to process when do_events is called, the class will wait for the amount of time specified here before returning. The default value is 20.

UseFIPSCompliantAPI: Tells the class whether or not to use FIPS certified APIs.

When set to True, the class 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 classes 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.

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

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

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

On Windows, this setting is set to False by default. On Linux/macOS, this setting is set to True by default.

To use the system security libraries for Linux, OpenSSL support must be enabled. For more information on how to enable OpenSSL, please refer to the OpenSSL Notes section.

KeyMgr Errors

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.