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_curveThis property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , or Ed448 .
key_effective_dateThe date when this key becomes valid.
key_encodedThe key.
key_expiration_dateThe date the key expires.
key_fingerprintThe hex-encoded, 20-byte fingerprint of the key.
key_idThe hex-encoded, 4-byte or 8-byte key Id.
key_other_user_idsIf the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.
key_passphraseThe passphrase for the key's secret key (if any).
key_public_keyThe public key of the key.
key_public_key_algorithmA text description of the public key algorithm of the key.
key_public_key_lengthThe length of the public key in bits.
key_revokedWhether or not the key is revoked.
key_secret_keyThe secret key of the key (if available).
key_secret_key_availableWhether or not a secret key is available for the selected key.
key_usageA text description of UsageFlags .
key_usage_flagsFlags that show the intended use for the key.
key_user_idThe user Id of the key.
key_versionThis property can be used to query the OpenPGP version of the currently selected Key .
keyringThe 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_revokerAdds a designated revoker to the key.
add_user_idAdds the specified user Id to the current key.
change_expiration_dateChanges the expiration date of the key.
change_passphraseChanges the passphrase of the current key.
configSets or retrieves a configuration setting.
create_keyCreates an OpenPGP key pair.
create_sub_keyCreates a new subkey.
delete_keyDeletes the specified key.
export_public_keyExports the public key of the current key.
export_secret_keyExports the private key of the current key.
import_keyImports the key specified by UserId to the current keyring.
import_key_bImports the key specified by UserId to the current keyring.
list_keysLists keys in the specified Keyring .
list_signaturesLists all signatures of the current key.
list_subkeysLists the subkeys of the currently selected key.
load_keyringLoads the keyring from disk.
load_keyring_bLoads the keyring from SecretKeyringData and PublicKeyringData .
resetResets the class properties.
revoke_keyRevokes the specified key.
save_keyringSaves the current Keyring to disk.
sign_user_idSigns the specified user Id of the current key.
verify_passphraseVerifies 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_errorFired when information is available about errors during data delivery.
on_key_listFires for each key in the keyring when ListKeys is called.
on_key_passphraseFired if the passphrase of current key is incorrect or empty.
on_signature_listFires for each signature of the current key when ListSignatures is called.
on_statusShows the progress of the operation.
on_subkey_listFires 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.

AllowEmptyPasswordWhether a key can be created without a password.
Argon2IterationsSpecifies the number of iterations used for Argon2.
Argon2MemorySizeExpSpecifies the exponent used to calculate the memory size used when creating a key.
Argon2ParallelismSpecifies the degree of parallelism used for Argon2.
ContinueOnInvalidKeyWhether to continue loading the keyring when an invalid key is found.
CreateRSASubkeyForEncryptWhether to create a subkey when creating an RSA key.
CurrentKeyPrimaryKeyUsageFlagsThe usage flags of the currently selected primary key.
CurveThe elliptic curve used when creating a key.
EnsureValidDSASignatureHashAlgorithmWhether or not to select a suitable signature hash algorithm automatically.
ImportAllKeysWhether or not to import all keys found in a key file.
KeyBoxProtectionModeSpecifies the keybox protection mode used when saving a keyring.
KeyEncryptionAlgorithmThe encryption algorithm used when creating a key.
KeyIdLengthSpecifies the length of the key's Id.
KeyPreferredAEADAlgorithmsIndicates the preferred AEAD encryption algorithms associated with the currently selected key.
KeyPreferredCompressionAlgorithmsIndicates the preferred compression algorithms associated with the currently selected key.
KeyPreferredHashAlgorithmsIndicates the preferred hash algorithms associated with the currently selected key.
KeyPreferredSymmetricAlgorithmsIndicates the preferred symmetric algorithms associated with the currently selected key.
KeyringFormatSpecifies the keyring format to use when saving a keyring.
KeyUsageFlags that show intended use for the key being created.
KeyValidityTimeThe validity period for the key being created.
KeyVersionSpecifies the OpenPGP version for the key being created.
LogLevelSpecifies the level of detail that is logged.
PreferredAEADAlgorithmsSpecifies a key's preferred AEAD encryption algorithms when creating a key.
PreferredCompressionAlgorithmsSpecifies a key's preferred compression algorithms when creating a key.
PreferredHashAlgorithmsSpecifies a key's preferred hash algorithms when creating a key.
PreferredSymmetricAlgorithmsSpecifies a key's preferred symmetric algorithms when creating a key.
PublicKeyAlgorithmThe public key algorithm for the key being created.
PublicKeyLengthSpecifies the public key length when creating a key.
PublicKeyringFileThe file name of the public keyring file.
PublicKeySignatureHashAlgorithmThe public key signature hash algorithm used when creating a key.
RawKeyDataReturns detailed key and keyring data for debugging purposes.
RevocationCodeThe reason why the key was revoked.
RevocationReasonText describing why the key was revoked.
RevokerThe revoker's key Id.
SecretKeyringFileThe file name of the secret keyring file.
SubKeyAlgorithmThe public key algorithm for the subkey being created.
SubKeyCurveThe elliptic curve of the sub key.
SubKeyLengthSpecifies the public subkey length when creating a key or subkey.
SubKeyUsageFlags that show intended use for the subkey being created.
UseArgon2Whether to use Argon2 for key derivation when creating a key.
VersionHeaderThe Version header value in ASCII armored public keys.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
MaskSensitiveDataWhether sensitive data is masked in log messages.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseFIPSCompliantAPITells the class whether or not to use FIPS certified APIs.
UseInternalSecurityAPIWhether 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:

CurveValid Public Key AlgorithmsDescription
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

0

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:

CurvePublic 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

47

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:

0x01This key may be used to certify other keys.
0x02This key may be used to sign data.
0x0CThis key may be used to encrypt communications and encrypt storage.
0x10The private component of this key may have been split by a secret-sharing mechanism.
0x20This key may be used for authentication.
0x80The 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

4

Remarks

This property can be used to query the OpenPGP version of the currently selected key. Possible values are:

  • 4 - OpenPGP v4 (default)
  • 6 - OpenPGP v6

This property is read-only.

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.

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.

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.

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.

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.

Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.

Additional configuration settings may be set to further configure the details of the key (and subkey) being created. Please see the following settings for details:

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:

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.

Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.

KeyId is the hex-encoded, 4-byte or 8-byte Id of the key. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:

5E70662EA810E768

Fingerprint holds the hex-encoded, 20-byte fingerprint of the key. This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

HasSecretKey returns True if the key contains a secret key.

PublicKeyAlgorithm is the public key algorithm. Possible values are:

  • RSA
  • DSA
  • ECDSA
  • EdDSA
  • Ed25519
  • Ed448

PublicKeyLength is the length of the public key. Common values are 1024, 2048, and 3072. If the PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448, the length of the public key is determined by the Curve. Possible lengths are:

CurvePublic 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:

CurveValid Public Key AlgorithmsDescription
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:

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.

Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.

KeyId is the hex-encoded, 4-byte or 8-byte Id of the key the passphrase is required for. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:

5E70662EA810E768

Fingerprint holds the hex-encoded, 20-byte fingerprint of the key the passphrase is required for. This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

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.

Note that for OpenPGP v6, a key may be created with or without a UserId, as the field is optional. If a key was created without a UserId, the key's Fingerprint can be used as it's identifier instead.

Fingerprint and IssuerFingerprint hold the hex-encoded, 20-byte fingerprint of the respective key. This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

Note that if IssuerUserId and IssuerFingerprint are empty, this indicates that the issuer's key could not be found in the current keyring.

PublicKeyAlgorithm is the public key algorithm. Possible values are:

  • RSA
  • DSA
  • ECDSA
  • EdDSA
  • Ed25519
  • Ed448

Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448. Possible values are:

CurveValid Public Key AlgorithmsDescription
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:

16Generic Signature
17Personal Signature
18Casual Signature
19Positive Signature (self-signed)

ValidityStatus specifies the current validity status of the signature. Possible values are:

1Invalid
2Valid
3Unknown (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:

CurvePublic 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 CurvePossible Subkey AlgorithmsDescription
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:

0x01This key may be used to certify other keys.
0x02This key may be used to sign data.
0x0CThis key may be used to encrypt communications and encrypt storage.
0x10The private component of this key may have been split by a secret-sharing mechanism.
0x20This key may be used for authentication.
0x80The 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:

CurveValid Public Key AlgorithmsDescription
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:

CurveHash 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:

0openpgp-s2k3-sha1-aes-cbc (default)
1openpgp-s2k3-sha1-aes256-cbc
2openpgp-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 ValueKeyring Format
1GPG 2.0 and older (Default)
2GPG 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:

0x01This key may be used to certify other keys.
0x02This key may be used to sign data.
0x0CThis key may be used to encrypt communications and encrypt storage.
0x10The private component of this key may have been split by a secret-sharing mechanism.
0x20This key may be used for authentication.
0x80The 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 AlgorithmSupported for OpenPGP v4Supported 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 AlgorithmDefault 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.

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:

0No reason specified
1Key is superseded
2Key material has been compromised
3Key is retired and no longer used
4User Id information is no longer valid
100-110Private 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 AlgorithmDefault 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:

  1. When calling create_key and PublicKeyAlgorithm is set to ECDSA, EdDSA, Ed25519, or Ed448, and SubKeyAlgorithm is unspecified.
  2. 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 CurvePossible Subkey AlgorithmsDescription
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:

0x01This key may be used to certify other keys.
0x02This key may be used to sign data.
0x0CThis key may be used to encrypt communications and encrypt storage.
0x10The private component of this key may have been split by a secret-sharing mechanism.
0x20This key may be used for authentication.
0x80The 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:

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:

IdentifierName
037IBM EBCDIC - U.S./Canada
437OEM - United States
500IBM EBCDIC - International
708Arabic - ASMO 708
709Arabic - ASMO 449+, BCON V4
710Arabic - Transparent Arabic
720Arabic - Transparent ASMO
737OEM - Greek (formerly 437G)
775OEM - Baltic
850OEM - Multilingual Latin I
852OEM - Latin II
855OEM - Cyrillic (primarily Russian)
857OEM - Turkish
858OEM - Multilingual Latin I + Euro symbol
860OEM - Portuguese
861OEM - Icelandic
862OEM - Hebrew
863OEM - Canadian-French
864OEM - Arabic
865OEM - Nordic
866OEM - Russian
869OEM - Modern Greek
870IBM EBCDIC - Multilingual/ROECE (Latin-2)
874ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875IBM EBCDIC - Modern Greek
932ANSI/OEM - Japanese, Shift-JIS
936ANSI/OEM - Simplified Chinese (PRC, Singapore)
949ANSI/OEM - Korean (Unified Hangul Code)
950ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026IBM EBCDIC - Turkish (Latin-5)
1047IBM EBCDIC - Latin 1/Open System
1140IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141IBM EBCDIC - Germany (20273 + Euro symbol)
1142IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144IBM EBCDIC - Italy (20280 + Euro symbol)
1145IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147IBM EBCDIC - France (20297 + Euro symbol)
1148IBM EBCDIC - International (500 + Euro symbol)
1149IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201Unicode UCS-2 Big-Endian
1250ANSI - Central European
1251ANSI - Cyrillic
1252ANSI - Latin I
1253ANSI - Greek
1254ANSI - Turkish
1255ANSI - Hebrew
1256ANSI - Arabic
1257ANSI - Baltic
1258ANSI/OEM - Vietnamese
1361Korean (Johab)
10000MAC - Roman
10001MAC - Japanese
10002MAC - Traditional Chinese (Big5)
10003MAC - Korean
10004MAC - Arabic
10005MAC - Hebrew
10006MAC - Greek I
10007MAC - Cyrillic
10008MAC - Simplified Chinese (GB 2312)
10010MAC - Romania
10017MAC - Ukraine
10021MAC - Thai
10029MAC - Latin II
10079MAC - Icelandic
10081MAC - Turkish
10082MAC - Croatia
12000Unicode UCS-4 Little-Endian
12001Unicode UCS-4 Big-Endian
20000CNS - Taiwan
20001TCA - Taiwan
20002Eten - Taiwan
20003IBM5550 - Taiwan
20004TeleText - Taiwan
20005Wang - Taiwan
20105IA5 IRV International Alphabet No. 5 (7-bit)
20106IA5 German (7-bit)
20107IA5 Swedish (7-bit)
20108IA5 Norwegian (7-bit)
20127US-ASCII (7-bit)
20261T.61
20269ISO 6937 Non-Spacing Accent
20273IBM EBCDIC - Germany
20277IBM EBCDIC - Denmark/Norway
20278IBM EBCDIC - Finland/Sweden
20280IBM EBCDIC - Italy
20284IBM EBCDIC - Latin America/Spain
20285IBM EBCDIC - United Kingdom
20290IBM EBCDIC - Japanese Katakana Extended
20297IBM EBCDIC - France
20420IBM EBCDIC - Arabic
20423IBM EBCDIC - Greek
20424IBM EBCDIC - Hebrew
20833IBM EBCDIC - Korean Extended
20838IBM EBCDIC - Thai
20866Russian - KOI8-R
20871IBM EBCDIC - Icelandic
20880IBM EBCDIC - Cyrillic (Russian)
20905IBM EBCDIC - Turkish
20924IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932JIS X 0208-1990 & 0121-1990
20936Simplified Chinese (GB2312)
21025IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027Extended Alpha Lowercase
21866Ukrainian (KOI8-U)
28591ISO 8859-1 Latin I
28592ISO 8859-2 Central Europe
28593ISO 8859-3 Latin 3
28594ISO 8859-4 Baltic
28595ISO 8859-5 Cyrillic
28596ISO 8859-6 Arabic
28597ISO 8859-7 Greek
28598ISO 8859-8 Hebrew
28599ISO 8859-9 Latin 5
28605ISO 8859-15 Latin 9
29001Europa 3
38598ISO 8859-8 Hebrew
50220ISO 2022 Japanese with no halfwidth Katakana
50221ISO 2022 Japanese with halfwidth Katakana
50222ISO 2022 Japanese JIS X 0201-1989
50225ISO 2022 Korean
50227ISO 2022 Simplified Chinese
50229ISO 2022 Traditional Chinese
50930Japanese (Katakana) Extended
50931US/Canada and Japanese
50933Korean Extended and Korean
50935Simplified Chinese Extended and Simplified Chinese
50936Simplified Chinese
50937US/Canada and Traditional Chinese
50939Japanese (Latin) Extended and Japanese
51932EUC - Japanese
51936EUC - Simplified Chinese
51949EUC - Korean
51950EUC - Traditional Chinese
52936HZ-GB2312 Simplified Chinese
54936Windows XP: GB18030 Simplified Chinese (4 Byte)
57002ISCII Devanagari
57003ISCII Bengali
57004ISCII Tamil
57005ISCII Telugu
57006ISCII Assamese
57007ISCII Oriya
57008ISCII Kannada
57009ISCII Malayalam
57010ISCII Gujarati
57011ISCII Punjabi
65000Unicode UTF-7
65001Unicode UTF-8
The following is a list of valid code page identifiers for Mac OS only:
IdentifierName
1ASCII
2NEXTSTEP
3JapaneseEUC
4UTF8
5ISOLatin1
6Symbol
7NonLossyASCII
8ShiftJIS
9ISOLatin2
10Unicode
11WindowsCP1251
12WindowsCP1252
13WindowsCP1253
14WindowsCP1254
15WindowsCP1250
21ISO2022JP
30MacOSRoman
10UTF16String
0x90000100UTF16BigEndian
0x94000100UTF16LittleEndian
0x8c000100UTF32String
0x98000100UTF32BigEndian
0x9c000100UTF32LittleEndian
65536Proprietary

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.