Struct ipworkspgp::KeyMgr

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

ipworkspgp::KeyMgr

Remarks

The KeyMgr struct 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.

GnuPG (2.5.x and later) uses its own Version 5 key format (LibrePGP). The struct supports creating and parsing LibrePGP Version 5 keys as well, for interoperability with GnuPG. See KeyVersion and CompatibilityProfile for details on choosing between the two formats.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksPGP. Due to this, the KeyMgr struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of KeyMgr when you have finished using the instance.

Property List

The following is the full list of the properties of the struct with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.

Event List

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

Config Settings

The following is a list of config settings for the struct with short descriptions. Click on the links for further details.

key_curve property (KeyMgr Struct)

This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 .

Syntax

fn key_curve(&self ) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

This property specifies the elliptic curve if key_public_key_algorithm is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

This property is read-only.

Data Type

String

key_effective_date property (KeyMgr Struct)

The date when this key becomes valid.

Syntax

fn key_effective_date(&self ) -> Result<String, IPWorksPGPError> 

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.

Data Type

String

key_expiration_date property (KeyMgr Struct)

The date the key expires.

Syntax

fn key_expiration_date(&self ) -> Result<String, IPWorksPGPError> 

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.

Data Type

String

keyring property (KeyMgr Struct)

The location of the keyring.

Syntax

fn keyring(&self ) -> Result<String, IPWorksPGPError> 
fn set_keyring(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_keyring_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The location of the keyring.

If the keyring is stored in a directory, set this property 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 this property should be set to the path of the file.

When This property is set the struct 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.

Data Type

String

key_other_user_ids property (KeyMgr Struct)

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

Syntax

fn key_other_user_ids(&self ) -> Result<String, IPWorksPGPError> 

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.

Data Type

String

key_passphrase property (KeyMgr Struct)

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

Syntax

fn key_passphrase(&self ) -> Result<String, IPWorksPGPError> 
fn set_key_passphrase(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_passphrase_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 struct, or an email-based struct, the following methods require a passphrase for the key:

• decrypt
• sign
• sign_and_encrypt

Data Type

String

key_public_key property (KeyMgr Struct)

The public key of the key.

Syntax

fn key_public_key(&self ) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

key_public_key_algorithm property (KeyMgr Struct)

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

Syntax

fn key_public_key_algorithm(&self ) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of the public key algorithm of the key. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA
• Ed25519
• Ed448
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448
• RSA-Legacy

This property is read-only.

Data Type

String

key_public_key_length property (KeyMgr Struct)

The length of the public key in bits.

Syntax

fn key_public_key_length(&self ) -> Result<i32, IPWorksPGPError> 

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, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448, the length of the public key is determined by the key_curve. Possible lengths are:

This property is read-only.

Data Type

i32

key_revoked property (KeyMgr Struct)

Whether or not the key is revoked.

Syntax

fn key_revoked(&self ) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not the key is revoked.

This property is read-only.

Data Type

bool

key_secret_key property (KeyMgr Struct)

The secret key of the key (if available).

Syntax

fn key_secret_key(&self ) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

String

key_secret_key_available property (KeyMgr Struct)

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

Syntax

fn key_secret_key_available(&self ) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

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

This property is read-only.

Data Type

bool

key_usage property (KeyMgr Struct)

A text description of UsageFlags .

Syntax

fn key_usage(&self ) -> Result<String, IPWorksPGPError> 

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.

Data Type

String

key_usage_flags property (KeyMgr Struct)

Flags that show the intended use for the key.

Syntax

fn key_usage_flags(&self ) -> Result<i32, IPWorksPGPError> 

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:

Please refer to the key_usage property for a text representation of key_usage_flags.

This property is read-only.

Data Type

i32

key_version property (KeyMgr Struct)

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

Syntax

fn key_version(&self ) -> Result<i32, IPWorksPGPError> 

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)
• 5 - LibrePGP v5
• 6 - OpenPGP v6

This property is read-only.

Data Type

i32

key_user_id property (KeyMgr Struct)

The user Id of the key.

Syntax

fn key_user_id(&self ) -> Result<String, IPWorksPGPError> 
fn set_key_user_id(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_user_id_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 key_keyring. When this property is set the struct will search the key_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>

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 its 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 struct 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 struct's on_recipient_info event.

Data Type

String

key_id property (KeyMgr Struct)

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

Syntax

fn key_id(&self ) -> Result<String, IPWorksPGPError> 
fn set_key_id(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_id_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 key_keyring. When this property is set the struct will search the key_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 key_keyring, as it is possible for different keys to have the same Id.

Data Type

String

key_fingerprint property (KeyMgr Struct)

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

Syntax

fn key_fingerprint(&self ) -> Result<String, IPWorksPGPError> 
fn set_key_fingerprint(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_fingerprint_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 key_keyring. When this property is set the struct will search the key_keyring for a key associated with the Fingerprint specified.

This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

Data Type

String

key_encoded property (KeyMgr Struct)

The key.

Syntax

fn key_encoded(&self ) -> Result<Vec<u8>, IPWorksPGPError> 
fn set_key_encoded(&self, value : Vec<u8>) ->  Option<IPWorksPGPError> 
fn set_key_encoded_ref(&self, value : &[u8]) ->  Option<IPWorksPGPError> 

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.

Data Type

Vec

add_revoker method (KeyMgr Struct)

Adds a designated revoker to the key.

Syntax

fn add_revoker(&self, user_id : &str) -> Result<(), IPWorksPGPError>

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>

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 its identifier instead.

add_user_id method (KeyMgr Struct)

Adds the specified user Id to the current key.

Syntax

fn add_user_id(&self, user_id : &str) -> Result<(), IPWorksPGPError>

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>

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 its identifier instead.

change_expiration_date method (KeyMgr Struct)

Changes the expiration date of the key.

Syntax

fn change_expiration_date(&self, expiration_date : i32) -> Result<(), IPWorksPGPError>

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 (KeyMgr Struct)

Changes the passphrase of the current key.

Syntax

fn change_passphrase(&self, passphrase : &str) -> Result<(), IPWorksPGPError>

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 (KeyMgr Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksPGPError>

Remarks

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

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

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

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

create_key method (KeyMgr Struct)

Creates an OpenPGP key pair.

Syntax

fn create_key(&self, user_id : &str, passphrase : &str) -> Result<(), IPWorksPGPError>

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>

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 its identifier instead.

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

• KeyEncryptionAlgorithm
• KeyUsage
• KeyValidityTime
• PublicKeyLength
• PublicKeyAlgorithm
• PublicKeySignatureHashAlgorithm
• Curve
• SubKeyAlgorithm
• SubKeyLength
• SubKeyCurve
• UseArgon2
• Argon2Iterations
• Argon2Parallelism
• KeyVersion
• CompatibilityProfile

create_sub_key method (KeyMgr Struct)

Creates a new subkey.

Syntax

fn create_sub_key(&self) -> Result<(), IPWorksPGPError>

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 (KeyMgr Struct)

Deletes the specified key.

Syntax

fn delete_key(&self, user_id : &str) -> Result<(), IPWorksPGPError>

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:

export_public_key method (KeyMgr Struct)

Exports the public key of the current key.

Syntax

fn export_public_key(&self, file_name : &str, use_ascii_armor : bool) -> Result<(), IPWorksPGPError>

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 (KeyMgr Struct)

Exports the private key of the current key.

Syntax

fn export_secret_key(&self, file_name : &str, use_ascii_armor : bool) -> Result<(), IPWorksPGPError>

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 (KeyMgr Struct)

Imports the key specified by UserId to the current keyring.

Syntax

fn import_key(&self, file_name : &str, user_id : &str) -> Result<(), IPWorksPGPError>

Remarks

This method imports the key specified by UserId from the key file specified by FileName into the current . 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 struct 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 (KeyMgr Struct)

Imports the key specified by UserId to the current keyring.

Syntax

fn import_key_b(&self, data : &[u8], user_id : &str) -> Result<(), IPWorksPGPError>

Remarks

This method imports the key specified by UserId from the key data specified by Data into the current . 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 struct in this case.

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

list_keys method (KeyMgr Struct)

Lists keys in the specified Keyring .

Syntax

fn list_keys(&self) ->  Result<String, IPWorksPGPError>

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 (KeyMgr Struct)

Lists all signatures of the current key.

Syntax

fn list_signatures(&self) ->  Result<String, IPWorksPGPError>

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 (KeyMgr Struct)

Lists the subkeys of the currently selected key.

Syntax

fn list_subkeys(&self) ->  Result<String, IPWorksPGPError>

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 (KeyMgr Struct)

Loads the keyring from disk.

Syntax

fn load_keyring(&self, keyring_path : &str) -> Result<(), IPWorksPGPError>

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 struct 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 (KeyMgr Struct)

Loads the keyring from SecretKeyringData and PublicKeyringData .

Syntax

fn load_keyring_b(&self, secret_keyring_data : &[u8], public_keyring_data : &[u8]) -> Result<(), IPWorksPGPError>

Remarks

This method loads the keyring from SecretKeyringData and PublicKeyringData.

When this method is called the struct 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 (KeyMgr Struct)

Resets the struct properties.

Syntax

fn reset(&self) -> Result<(), IPWorksPGPError>

Remarks

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

revoke_key method (KeyMgr Struct)

Revokes the specified key.

Syntax

fn revoke_key(&self, key_id : &str) ->  Result<String, IPWorksPGPError>

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 (KeyMgr Struct)

Saves the current Keyring to disk.

Syntax

fn save_keyring(&self, keyring_path : &str) -> Result<(), IPWorksPGPError>

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 struct 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 (KeyMgr Struct)

Signs the specified user Id of the current key.

Syntax

fn sign_user_id(&self, user_id : &str, issuer_user_id : &str) -> Result<(), IPWorksPGPError>

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 (KeyMgr Struct)

Verifies the passphrase of specified key.

Syntax

fn verify_passphrase(&self, passphrase : &str) ->  Result<bool, IPWorksPGPError>

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 (KeyMgr Struct)

Fired when information is available about errors during data delivery.

Syntax

// KeyMgrErrorEventArgs carries the KeyMgr Error event's parameters.
pub struct KeyMgrErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// KeyMgrErrorEvent defines the signature of the KeyMgr Error event's handler function.
pub trait KeyMgrErrorEvent {
  fn on_error(&self, sender : KeyMgr, e : &mut KeyMgrErrorEventArgs);
}

impl <'a> KeyMgr<'a> {
  pub fn on_error(&self) -> &'a dyn KeyMgrErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn KeyMgrErrorEvent);
  ...
}

Remarks

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

The error_code 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 (KeyMgr Struct)

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

Syntax

// KeyMgrKeyListEventArgs carries the KeyMgr KeyList event's parameters.
pub struct KeyMgrKeyListEventArgs {
  fn user_id(&self) -> &String
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn has_secret_key(&self) -> bool
  fn public_key_algorithm(&self) -> &String
  fn public_key_length(&self) -> i32
  fn curve(&self) -> &String
}

// KeyMgrKeyListEvent defines the signature of the KeyMgr KeyList event's handler function.
pub trait KeyMgrKeyListEvent {
  fn on_key_list(&self, sender : KeyMgr, e : &mut KeyMgrKeyListEventArgs);
}

impl <'a> KeyMgr<'a> {
  pub fn on_key_list(&self) -> &'a dyn KeyMgrKeyListEvent;
  pub fn set_on_key_list(&mut self, value : &'a dyn KeyMgrKeyListEvent);
  ...
}

Remarks

This event fires once for each key in the when list_keys is called.

UserId holds the current user Id of the key.

The UserId format is:

FirstName LastName (Comment) <Email>

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 its 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
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448

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

Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

on_key_passphrase event (KeyMgr Struct)

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

Syntax

// KeyMgrKeyPassphraseEventArgs carries the KeyMgr KeyPassphrase event's parameters.
pub struct KeyMgrKeyPassphraseEventArgs {
  fn user_id(&self) -> &String
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn passphrase(&self) -> &String
  fn set_passphrase(&self, value : &str)
  fn set_passphrase_ref(&self, value : &String)
}

// KeyMgrKeyPassphraseEvent defines the signature of the KeyMgr KeyPassphrase event's handler function.
pub trait KeyMgrKeyPassphraseEvent {
  fn on_key_passphrase(&self, sender : KeyMgr, e : &mut KeyMgrKeyPassphraseEventArgs);
}

impl <'a> KeyMgr<'a> {
  pub fn on_key_passphrase(&self) -> &'a dyn KeyMgrKeyPassphraseEvent;
  pub fn set_on_key_passphrase(&mut self, value : &'a dyn KeyMgrKeyPassphraseEvent);
  ...
}

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 struct, or an email-based struct, 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>

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 its 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 (KeyMgr Struct)

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

Syntax

// KeyMgrSignatureListEventArgs carries the KeyMgr SignatureList event's parameters.
pub struct KeyMgrSignatureListEventArgs {
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn user_id(&self) -> &String
  fn issuer_fingerprint(&self) -> &String
  fn issuer_key_id(&self) -> &String
  fn issuer_user_id(&self) -> &String
  fn public_key_algorithm(&self) -> &String
  fn curve(&self) -> &String
  fn hash_algorithm(&self) -> &String
  fn effective_date(&self) -> &String
  fn signature_class(&self) -> i32
  fn validity_status(&self) -> i32
}

// KeyMgrSignatureListEvent defines the signature of the KeyMgr SignatureList event's handler function.
pub trait KeyMgrSignatureListEvent {
  fn on_signature_list(&self, sender : KeyMgr, e : &mut KeyMgrSignatureListEventArgs);
}

impl <'a> KeyMgr<'a> {
  pub fn on_signature_list(&self) -> &'a dyn KeyMgrSignatureListEvent;
  pub fn set_on_signature_list(&mut self, value : &'a dyn KeyMgrSignatureListEvent);
  ...
}

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>

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 its 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
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448

Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

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:

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

on_status event (KeyMgr Struct)

Shows the progress of the operation.

Syntax

// KeyMgrStatusEventArgs carries the KeyMgr Status event's parameters.
pub struct KeyMgrStatusEventArgs {
  fn message(&self) -> &String
}

// KeyMgrStatusEvent defines the signature of the KeyMgr Status event's handler function.
pub trait KeyMgrStatusEvent {
  fn on_status(&self, sender : KeyMgr, e : &mut KeyMgrStatusEventArgs);
}

impl <'a> KeyMgr<'a> {
  pub fn on_status(&self) -> &'a dyn KeyMgrStatusEvent;
  pub fn set_on_status(&mut self, value : &'a dyn KeyMgrStatusEvent);
  ...
}

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 (KeyMgr Struct)

Fires once for each subkey listed when ListSubkeys is called.

Syntax

// KeyMgrSubkeyListEventArgs carries the KeyMgr SubkeyList event's parameters.
pub struct KeyMgrSubkeyListEventArgs {
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn public_key_algorithm(&self) -> &String
  fn public_key_length(&self) -> i32
  fn curve(&self) -> &String
  fn usage_flags(&self) -> i32
  fn usage(&self) -> &String
  fn effective_date(&self) -> &String
  fn expiration_date(&self) -> &String
  fn revoked(&self) -> bool
}

// KeyMgrSubkeyListEvent defines the signature of the KeyMgr SubkeyList event's handler function.
pub trait KeyMgrSubkeyListEvent {
  fn on_subkey_list(&self, sender : KeyMgr, e : &mut KeyMgrSubkeyListEventArgs);
}

impl <'a> KeyMgr<'a> {
  pub fn on_subkey_list(&self) -> &'a dyn KeyMgrSubkeyListEvent;
  pub fn set_on_subkey_list(&mut self, value : &'a dyn KeyMgrSubkeyListEvent);
  ...
}

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
• ML-KEM (LibrePGP/GnuPG)
• ML-KEM-768+X25519
• ML-KEM-1024+X448
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448

PublicKeyLength is the length of the subkey. Common values are 1024, 2048, and 3072. If PublicKeyAlgorithm is ECDSA, EdDSA, ECDH, Ed25519, Ed448, X25519, X448, ML-KEM, ML-KEM-768+X25519, ML-KEM-1024+X448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448, the length of the public key is determined by the Curve. Possible lengths are:

Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA, EdDSA, ECDH, Ed25519, Ed448, X25519, X448, ML-KEM, ML-KEM-768+X25519, ML-KEM-1024+X448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

ML-KEM-768+X25519 and ML-KEM-1024+X448 are RFC 9980/OpenPGP v6 composite KEM algorithms. With CompatibilityProfile=LibrePGP, use SubKeyAlgorithm=ML-KEM and select the curve separately with SubKeyCurve.

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:

EffectiveDate is the date when this key became valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00.

ExpirationDate is the date the key expires. After this date the key will no longer be valid. The following example illustrates the format of an encoded date: 23-Jan-2000 15:00:00. If the ExpirationDate is not populated this indicates that the key never expires.

Revoked Indicates whether the subkey is revoked or not.

Config Settings (KeyMgr Struct)

KeyMgr Config Settings

5E70662EA810E768

Base Config Settings

Trappable Errors (KeyMgr Struct)

OpenPGP Errors