# Struct ipworkspgp::KeyMgr The KeyMgr struct is used to create and manage OpenPGP keys. ## Syntax ```text ipworkspgp::KeyMgr ``` ## Remarks The KeyMgr struct supports key management according to the specifications outlined in [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880), in addition to [RFC 9580](https://datatracker.ietf.org/doc/rfc9580/), 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](#KeyVersion) and [CompatibilityProfile](#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.* | | | | --- | --- | | [key_curve](#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 . | | [key_effective_date](#key_effective_date-property-keymgr-struct) | The date when this key becomes valid. | | [key_expiration_date](#key_expiration_date-property-keymgr-struct) | The date the key expires. | | [keyring](#keyring-property-keymgr-struct) | The location of the keyring. | | [key_other_user_ids](#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. | | [key_passphrase](#key_passphrase-property-keymgr-struct) | The passphrase for the key's secret key (if any). | | [key_public_key](#key_public_key-property-keymgr-struct) | The public key of the key. | | [key_public_key_algorithm](#key_public_key_algorithm-property-keymgr-struct) | A text description of the public key algorithm of the key. | | [key_public_key_length](#key_public_key_length-property-keymgr-struct) | The length of the public key in bits. | | [key_revoked](#key_revoked-property-keymgr-struct) | Whether or not the key is revoked. | | [key_secret_key](#key_secret_key-property-keymgr-struct) | The secret key of the key (if available). | | [key_secret_key_available](#key_secret_key_available-property-keymgr-struct) | Whether or not a secret key is available for the selected key. | | [key_usage](#key_usage-property-keymgr-struct) | A text description of UsageFlags . | | [key_usage_flags](#key_usage_flags-property-keymgr-struct) | Flags that show the intended use for the key. | | [key_version](#key_version-property-keymgr-struct) | This property can be used to query the OpenPGP version of the currently selected Key . | | [key_user_id](#key_user_id-property-keymgr-struct) | The user Id of the key. | | [key_id](#key_id-property-keymgr-struct) | The hex-encoded, 4-byte or 8-byte key Id. | | [key_fingerprint](#key_fingerprint-property-keymgr-struct) | The hex-encoded, 20-byte fingerprint of the key. | | [key_encoded](#key_encoded-property-keymgr-struct) | The key. | ## Method List *The following is the full list of the methods of the struct with short descriptions. Click on the links for further details.* | | | | --- | --- | | [add_revoker](#add_revoker-method-keymgr-struct) | Adds a designated revoker to the key. | | [add_user_id](#add_user_id-method-keymgr-struct) | Adds the specified user Id to the current key. | | [change_expiration_date](#change_expiration_date-method-keymgr-struct) | Changes the expiration date of the key. | | [change_passphrase](#change_passphrase-method-keymgr-struct) | Changes the passphrase of the current key. | | [config](#config-method-keymgr-struct) | Sets or retrieves a configuration setting. | | [create_key](#create_key-method-keymgr-struct) | Creates an OpenPGP key pair. | | [create_sub_key](#create_sub_key-method-keymgr-struct) | Creates a new subkey. | | [delete_key](#delete_key-method-keymgr-struct) | Deletes the specified key. | | [export_public_key](#export_public_key-method-keymgr-struct) | Exports the public key of the current key. | | [export_secret_key](#export_secret_key-method-keymgr-struct) | Exports the private key of the current key. | | [import_key](#import_key-method-keymgr-struct) | Imports the key specified by UserId to the current keyring. | | [import_key_b](#import_key_b-method-keymgr-struct) | Imports the key specified by UserId to the current keyring. | | [list_keys](#list_keys-method-keymgr-struct) | Lists keys in the specified Keyring . | | [list_signatures](#list_signatures-method-keymgr-struct) | Lists all signatures of the current key. | | [list_subkeys](#list_subkeys-method-keymgr-struct) | Lists the subkeys of the currently selected key. | | [load_keyring](#load_keyring-method-keymgr-struct) | Loads the keyring from disk. | | [load_keyring_b](#load_keyring_b-method-keymgr-struct) | Loads the keyring from SecretKeyringData and PublicKeyringData . | | [reset](#reset-method-keymgr-struct) | Resets the struct properties. | | [revoke_key](#revoke_key-method-keymgr-struct) | Revokes the specified key. | | [save_keyring](#save_keyring-method-keymgr-struct) | Saves the current Keyring to disk. | | [sign_user_id](#sign_user_id-method-keymgr-struct) | Signs the specified user Id of the current key. | | [verify_passphrase](#verify_passphrase-method-keymgr-struct) | Verifies the passphrase of specified key. | ## 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.* | | | | --- | --- | | [on_error](#on_error-event-keymgr-struct) | Fired when information is available about errors during data delivery. | | [on_key_list](#on_key_list-event-keymgr-struct) | Fires for each key in the keyring when ListKeys is called. | | [on_key_passphrase](#on_key_passphrase-event-keymgr-struct) | Fired if the passphrase of current key is incorrect or empty. | | [on_signature_list](#on_signature_list-event-keymgr-struct) | Fires for each signature of the current key when ListSignatures is called. | | [on_status](#on_status-event-keymgr-struct) | Shows the progress of the operation. | | [on_subkey_list](#on_subkey_list-event-keymgr-struct) | Fires once for each subkey listed when ListSubkeys is called. | ## Config Settings *The following is a list of config settings for the struct with short descriptions. Click on the links for further details.* | | | | --- | --- | | [AllowEmptyPassword](#AllowEmptyPassword) | Whether a key can be created without a password. | | [Argon2Iterations](#Argon2Iterations) | Specifies the number of iterations used for Argon2. | | [Argon2MemorySizeExp](#Argon2MemorySizeExp) | Specifies the exponent used to calculate the memory size used when creating a key. | | [Argon2Parallelism](#Argon2Parallelism) | Specifies the degree of parallelism used for Argon2. | | [CompatibilityProfile](#CompatibilityProfile) | Specifies the OpenPGP compatibility profile used when creating keys. | | [ContinueOnInvalidKey](#ContinueOnInvalidKey) | Whether to continue loading the keyring when an invalid key is found. | | [CreateRSASubkeyForEncrypt](#CreateRSASubkeyForEncrypt) | Whether to create a subkey when creating an RSA key. | | [CurrentKeyPrimaryKeyUsageFlags](#CurrentKeyPrimaryKeyUsageFlags) | The usage flags of the currently selected primary key. | | [Curve](#Curve) | The elliptic curve used when creating a key. | | [EnsureValidDSASignatureHashAlgorithm](#EnsureValidDSASignatureHashAlgorithm) | Whether or not to select a suitable signature hash algorithm automatically. | | [ImportAllKeys](#ImportAllKeys) | Whether or not to import all keys found in a key file. | | [KeyBoxProtectionMode](#KeyBoxProtectionMode) | Specifies the keybox protection mode used when saving a keyring. | | [KeyEncryptionAlgorithm](#KeyEncryptionAlgorithm) | The encryption algorithm used when creating a key. | | [KeyIdLength](#KeyIdLength) | Specifies the length of the key's Id. | | [KeyPreferredAEADAlgorithms](#KeyPreferredAEADAlgorithms) | Indicates the preferred AEAD encryption algorithms associated with the currently selected key. | | [KeyPreferredCompressionAlgorithms](#KeyPreferredCompressionAlgorithms) | Indicates the preferred compression algorithms associated with the currently selected key. | | [KeyPreferredHashAlgorithms](#KeyPreferredHashAlgorithms) | Indicates the preferred hash algorithms associated with the currently selected key. | | [KeyPreferredSymmetricAlgorithms](#KeyPreferredSymmetricAlgorithms) | Indicates the preferred symmetric algorithms associated with the currently selected key. | | [KeyringFormat](#KeyringFormat) | Specifies the keyring format to use when saving a keyring. | | [KeySignatureNotationCount](#KeySignatureNotationCount) | The number of notations present in a key's signatures. | | [KeySignatureNotationName\[i\]](#KeySignatureNotationName[i]) | The name of a notation present in a key's signatures. | | [KeySignatureNotationValue\[i\]](#KeySignatureNotationValue[i]) | The value of a notation present in a key's signatures. | | [KeyUsage](#KeyUsage) | Flags that show intended use for the key being created. | | [KeyValidityTime](#KeyValidityTime) | The validity period for the key being created. | | [KeyVersion](#KeyVersion) | Specifies the OpenPGP version for the key being created. | | [LogLevel](#LogLevel) | Specifies the level of detail that is logged. | | [PreferredAEADAlgorithms](#PreferredAEADAlgorithms) | Specifies a key's preferred AEAD encryption algorithms when creating a key. | | [PreferredCompressionAlgorithms](#PreferredCompressionAlgorithms) | Specifies a key's preferred compression algorithms when creating a key. | | [PreferredHashAlgorithms](#PreferredHashAlgorithms) | Specifies a key's preferred hash algorithms when creating a key. | | [PreferredSymmetricAlgorithms](#PreferredSymmetricAlgorithms) | Specifies a key's preferred symmetric algorithms when creating a key. | | [PublicKeyAlgorithm](#PublicKeyAlgorithm) | The public key algorithm for the key being created. | | [PublicKeyLength](#PublicKeyLength) | Specifies the public key length when creating a key. | | [PublicKeyringFile](#PublicKeyringFile) | The file name of the public keyring file. | | [PublicKeySignatureHashAlgorithm](#PublicKeySignatureHashAlgorithm) | The public key signature hash algorithm used when creating a key. | | [RawKeyData](#RawKeyData) | Returns detailed key and keyring data for debugging purposes. | | [RevocationCode](#RevocationCode) | The reason why the key was revoked. | | [RevocationReason](#RevocationReason) | Text describing why the key was revoked. | | [Revoker](#Revoker) | The revoker's key Id. | | [SecretKeyringFile](#SecretKeyringFile) | The file name of the secret keyring file. | | [SignatureNotationCount](#SignatureNotationCount) | The number of notations to add to a key's signatures. | | [SignatureNotationName\[i\]](#SignatureNotationName[i]) | The name of a notation to add to a key's signatures. | | [SignatureNotationValue\[i\]](#SignatureNotationValue[i]) | The value of a notation to add to a key's signatures. | | [SubKeyAlgorithm](#SubKeyAlgorithm) | The public key algorithm for the subkey being created. | | [SubKeyCurve](#SubKeyCurve) | The elliptic curve of the sub key. | | [SubKeyLength](#SubKeyLength) | Specifies the public subkey length when creating a key or subkey. | | [SubKeyUsage](#SubKeyUsage) | Flags that show intended use for the subkey being created. | | [UseArgon2](#UseArgon2) | Whether to use Argon2 for key derivation when creating a key. | | [VersionHeader](#VersionHeader) | The Version header value in ASCII armored public keys. | | [BuildInfo](#BuildInfo) | Information about the product's build. | | [CodePage](#CodePage) | The system code page used for Unicode to Multibyte translations. | | [LicenseInfo](#LicenseInfo) | Information about the current license. | | [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. | | [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. | # key_curve property ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . ## Syntax *Rust Syntax* ```text fn key_curve(&self ) -> Result ``` ## Default Value "" ## Remarks This property specifies the elliptic curve if [key_public_key_algorithm](#key_public_key_algorithm-property-keymgr-struct) is *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448*. Possible values are: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | This property is read-only. ## Data Type String # key_effective_date property ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) The date when this key becomes valid. ## Syntax *Rust Syntax* ```text fn key_effective_date(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) The date the key expires. ## Syntax *Rust Syntax* ```text fn key_expiration_date(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) The location of the keyring. ## Syntax *Rust Syntax* ```text fn keyring(&self ) -> Result fn set_keyring(&self, value : &str) -> Option fn set_keyring_ref(&self, value : &String) -> Option ``` ## 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](#key_user_id-property-keymgr-struct) to select a different key in the current keyring. ## Data Type String # key_other_user_ids property ([KeyMgr](#struct-ipworkspgpkeymgr) 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 *Rust Syntax* ```text fn key_other_user_ids(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) The passphrase for the key's secret key (if any). ## Syntax *Rust Syntax* ```text fn key_passphrase(&self ) -> Result fn set_key_passphrase(&self, value : &str) -> Option fn set_key_passphrase_ref(&self, value : &String) -> Option ``` ## 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-ipworkspgpkeymgr) Struct) The public key of the key. ## Syntax *Rust Syntax* ```text fn key_public_key(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) A text description of the public key algorithm of the key. ## Syntax *Rust Syntax* ```text fn key_public_key_algorithm(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) The length of the public key in bits. ## Syntax *Rust Syntax* ```text fn key_public_key_length(&self ) -> Result ``` ## 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](#key_public_key_algorithm-property-keymgr-struct) 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](#key_curve-property-keymgr-struct). Possible lengths are: | Curve | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | This property is read-only. ## Data Type i32 # key_revoked property ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Whether or not the key is revoked. ## Syntax *Rust Syntax* ```text fn key_revoked(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) The secret key of the key (if available). ## Syntax *Rust Syntax* ```text fn key_secret_key(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) Whether or not a secret key is available for the selected key. ## Syntax *Rust Syntax* ```text fn key_secret_key_available(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) A text description of UsageFlags . ## Syntax *Rust Syntax* ```text fn key_usage(&self ) -> Result ``` ## Default Value "" ## Remarks A text description of [key_usage_flags](#key_usage_flags-property-keymgr-struct). 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-ipworkspgpkeymgr) Struct) Flags that show the intended use for the key. ## Syntax *Rust Syntax* ```text fn key_usage_flags(&self ) -> Result ``` ## Default Value 47 ## Remarks Flags that show the intended use for the key. The default value is 0x0F. The value of [key_usage_flags](#key_usage_flags-property-keymgr-struct) is a combination of the following flags: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | Please refer to the [key_usage](#key_usage-property-keymgr-struct) property for a text representation of [key_usage_flags](#key_usage_flags-property-keymgr-struct). This property is read-only. ## Data Type i32 # key_version property ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) This property can be used to query the OpenPGP version of the currently selected Key . ## Syntax *Rust Syntax* ```text fn key_version(&self ) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) The user Id of the key. ## Syntax *Rust Syntax* ```text fn key_user_id(&self ) -> Result fn set_key_user_id(&self, value : &str) -> Option fn set_key_user_id_ref(&self, value : &String) -> Option ``` ## 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](#KeyMgr_p_KeyKeyring). When this property is set the struct will search the [key_keyring](#KeyMgr_p_KeyKeyring) 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](#key_other_user_ids-property-keymgr-struct) after loading the key. The *UserId* format is: ```text FirstName LastName (Comment) ``` 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 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-ipworkspgpkeymgr) Struct) The hex-encoded, 4-byte or 8-byte key Id. ## Syntax *Rust Syntax* ```text fn key_id(&self ) -> Result fn set_key_id(&self, value : &str) -> Option fn set_key_id_ref(&self, value : &String) -> Option ``` ## 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: ```text 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](#KeyMgr_p_KeyKeyring). When this property is set the struct will search the [key_keyring](#KeyMgr_p_KeyKeyring) 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](#key_fingerprint-property-keymgr-struct) property when loading a key from the [key_keyring](#KeyMgr_p_KeyKeyring), as it is possible for different keys to have the same Id. ## Data Type String # key_fingerprint property ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) The hex-encoded, 20-byte fingerprint of the key. ## Syntax *Rust Syntax* ```text fn key_fingerprint(&self ) -> Result fn set_key_fingerprint(&self, value : &str) -> Option fn set_key_fingerprint_ref(&self, value : &String) -> Option ``` ## 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](#KeyMgr_p_KeyKeyring). When this property is set the struct will search the [key_keyring](#KeyMgr_p_KeyKeyring) for a key associated with the Fingerprint specified. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` ## Data Type String # key_encoded property ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) The key. ## Syntax *Rust Syntax* ```text fn key_encoded(&self ) -> Result, IPWorksPGPError> fn set_key_encoded(&self, value : Vec) -> Option fn set_key_encoded_ref(&self, value : &[u8]) -> Option ``` ## Default Value "" ## Remarks The key. This property can be used to assign a specific key. The [key_fingerprint](#key_fingerprint-property-keymgr-struct), [key_id](#key_id-property-keymgr-struct), and [key_user_id](#key_user_id-property-keymgr-struct) properties may also be used to specify a key. ## Data Type Vec # add_revoker method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Adds a designated revoker to the key. ## Syntax *Rust Syntax* ```text 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](#key_passphrase-property-keymgr-struct) or through the [on_key_passphrase](#on_key_passphrase-event-keymgr-struct) event. The *UserId* format is: ```text FirstName LastName (Comment) ``` 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 its identifier instead. # add_user_id method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Adds the specified user Id to the current key. ## Syntax *Rust Syntax* ```text 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](#key_passphrase-property-keymgr-struct) or through the [on_key_passphrase](#on_key_passphrase-event-keymgr-struct) event. The *UserId* format is: ```text FirstName LastName (Comment) ``` 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 its identifier instead. # change_expiration_date method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Changes the expiration date of the key. ## Syntax *Rust Syntax* ```text 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](#key_passphrase-property-keymgr-struct) or through the [on_key_passphrase](#on_key_passphrase-event-keymgr-struct) event. Note: See [KeyValidityTime](#KeyValidityTime) for information on specifying the expiration date when creating the key with [create_key](#create_key-method-keymgr-struct). # change_passphrase method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Changes the passphrase of the current key. ## Syntax *Rust Syntax* ```text 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](#key_passphrase-property-keymgr-struct) or through the [on_key_passphrase](#on_key_passphrase-event-keymgr-struct) event. # config method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Sets or retrieves a configuration setting. ## Syntax *Rust Syntax* ```text fn config(&self, configuration_string : &str) -> Result ``` ## Remarks config is a generic method available in every struct. It is used to set and retrieve [configuration settings](#config-settings-keymgr-struct) 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](#config-settings-keymgr-struct), you must call *Config("PROPERTY")*. The value will be returned as a string. # create_key method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Creates an OpenPGP key pair. ## Syntax *Rust Syntax* ```text 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](#KeyVersion) is *6*, this parameter may be an empty string. The *UserId* format is: ```text FirstName LastName (Comment) ``` 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 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](#KeyEncryptionAlgorithm) - [KeyUsage](#KeyUsage) - [KeyValidityTime](#KeyValidityTime) - [PublicKeyLength](#PublicKeyLength) - [PublicKeyAlgorithm](#PublicKeyAlgorithm) - [PublicKeySignatureHashAlgorithm](#PublicKeySignatureHashAlgorithm) - [Curve](#Curve) - [SubKeyAlgorithm](#SubKeyAlgorithm) - [SubKeyLength](#SubKeyLength) - [SubKeyCurve](#SubKeyCurve) - [UseArgon2](#UseArgon2) - [Argon2Iterations](#Argon2Iterations) - [Argon2Parallelism](#Argon2Parallelism) - [KeyVersion](#KeyVersion) - [CompatibilityProfile](#CompatibilityProfile) # create_sub_key method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Creates a new subkey. ## Syntax *Rust Syntax* ```text fn create_sub_key(&self) -> Result<(), IPWorksPGPError> ``` ## Remarks This method creates a new subkey. Before calling this method the [key_id](#key_id-property-keymgr-struct) 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](#KeyValidityTime) - [PublicKeyLength](#PublicKeyLength) - [SubKeyAlgorithm](#SubKeyAlgorithm) - [SubKeyLength](#SubKeyLength) - [SubKeyCurve](#SubKeyCurve) - [SubKeyUsage](#SubKeyUsage) # delete_key method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Deletes the specified key. ## Syntax *Rust Syntax* ```text 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: | Id Type | Example | | --- | --- | | UserId | FirstName LastName | | 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 ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Exports the public key of the current key. ## Syntax *Rust Syntax* ```text 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](#VersionHeader) setting may also be set to specify your own header value. # export_secret_key method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Exports the private key of the current key. ## Syntax *Rust Syntax* ```text 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-ipworkspgpkeymgr) Struct) Imports the key specified by UserId to the current keyring. ## Syntax *Rust Syntax* ```text 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](#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](#key_user_id-property-keymgr-struct) instead. # import_key_b method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Imports the key specified by UserId to the current keyring. ## Syntax *Rust Syntax* ```text 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](#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](#key_user_id-property-keymgr-struct) instead. # list_keys method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Lists keys in the specified Keyring . ## Syntax *Rust Syntax* ```text fn list_keys(&self) -> Result ``` ## Remarks This method lists the keys (public/private key pairs) in the specified keyring. The results are provided through the [on_key_list](#on_key_list-event-keymgr-struct) event. KeyList data will also be returned from this method, however it is recommended to use the [on_key_list](#on_key_list-event-keymgr-struct) event if possible. # list_signatures method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Lists all signatures of the current key. ## Syntax *Rust Syntax* ```text fn list_signatures(&self) -> Result ``` ## Remarks This method lists all the signatures of the currently selected key. The [on_signature_list](#on_signature_list-event-keymgr-struct) 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](#on_signature_list-event-keymgr-struct) event if possible. # list_subkeys method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Lists the subkeys of the currently selected key. ## Syntax *Rust Syntax* ```text fn list_subkeys(&self) -> Result ``` ## Remarks This method lists all subkeys of current key. The [on_subkey_list](#on_subkey_list-event-keymgr-struct) 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](#on_subkey_list-event-keymgr-struct) event if possible. # load_keyring method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Loads the keyring from disk. ## Syntax *Rust Syntax* ```text 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](#key_user_id-property-keymgr-struct) to select a different key in the current keyring. # load_keyring_b method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Loads the keyring from SecretKeyringData and PublicKeyringData . ## Syntax *Rust Syntax* ```text 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](#key_user_id-property-keymgr-struct) to select a different key in the current keyring. # reset method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Resets the struct properties. ## Syntax *Rust Syntax* ```text fn reset(&self) -> Result<(), IPWorksPGPError> ``` ## Remarks This method resets all message and key properties to their default values. # revoke_key method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Revokes the specified key. ## Syntax *Rust Syntax* ```text fn revoke_key(&self, key_id : &str) -> Result ``` ## 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](#export_public_key-method-keymgr-struct) after calling this method. Both formats are common, and both formats are acceptable when calling [import_key](#import_key-method-keymgr-struct). 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: ```text 5E70662EA810E768 ``` # save_keyring method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Saves the current Keyring to disk. ## Syntax *Rust Syntax* ```text 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-ipworkspgpkeymgr) Struct) Signs the specified user Id of the current key. ## Syntax *Rust Syntax* ```text 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](#key_passphrase-property-keymgr-struct) or through the [on_key_passphrase](#on_key_passphrase-event-keymgr-struct) event. # verify_passphrase method ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Verifies the passphrase of specified key. ## Syntax *Rust Syntax* ```text fn verify_passphrase(&self, passphrase : &str) -> Result ``` ## 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-ipworkspgpkeymgr) Struct) Fired when information is available about errors during data delivery. ## Syntax *Rust Syntax* ```text // 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](#trappable-errors-keymgr-struct) section. # on_key_list event ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Fires for each key in the keyring when ListKeys is called. ## Syntax *Rust Syntax* ```text // 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](#list_keys-method-keymgr-struct) is called. *UserId* holds the current user Id of the key. The *UserId* format is: ```text FirstName LastName (Comment) ``` 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 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: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key. This is in the form: ```text 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 | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | *Curve* is the curve used by the key when *PublicKeyAlgorithm* is *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448*. Possible values are: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | # on_key_passphrase event ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Fired if the passphrase of current key is incorrect or empty. ## Syntax *Rust Syntax* ```text // 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](#key_passphrase-property-keymgr-struct) property before attempting the operation. The passphrase is required when using the following methods in KeyMgr: - [add_user_id](#add_user_id-method-keymgr-struct) - [sign_user_id](#sign_user_id-method-keymgr-struct) - [change_expiration_date](#change_expiration_date-method-keymgr-struct) - [change_passphrase](#change_passphrase-method-keymgr-struct) 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: ```text FirstName LastName (Comment) ``` 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 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: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key the passphrase is required for. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` # on_signature_list event ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Fires for each signature of the current key when ListSignatures is called. ## Syntax *Rust Syntax* ```text // 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](#list_signatures-method-keymgr-struct) 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: ```text 5E70662EA810E768 ``` *UserId* and *IssuerUserId* hold the user Id of the respective key. The *UserId* format is: ```text FirstName LastName (Comment) ``` 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 its identifier instead. *Fingerprint* and *IssuerFingerprint* hold the hex-encoded, 20-byte fingerprint of the respective key. This is in the form: ```text 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: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | *HashAlgorithm* is the hash algorithm used by the signature. Possible values are: - *SHA1* - *MD5* - *SHA256* - *SHA384* - *SHA512* - *SHA224* - *RIPEMD160* - *SHA3-256* - *SHA3-512* *EffectiveDate* is the date when this signature became valid. The following example illustrates the format of an encoded date: *23-Jan-2000 15:00:00 *. *SignatureClass* is the type of signature. Possible values are: | | | | --- | --- | | 16 | Generic Signature | | 17 | Personal Signature | | 18 | Casual Signature | | 19 | Positive Signature (self-signed) | *ValidityStatus* specifies the current validity status of the signature. Possible values are: | | | | --- | --- | | 1 | Invalid | | 2 | Valid | | 3 | Unknown (the issuer's public key could not be found) | # on_status event ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Shows the progress of the operation. ## Syntax *Rust Syntax* ```text // 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](#LogLevel) setting. # on_subkey_list event ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) Fires once for each subkey listed when ListSubkeys is called. ## Syntax *Rust Syntax* ```text // 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](#list_subkeys-method-keymgr-struct) 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: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key. This is in the form: ```text 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 | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | | Curve25519 | 256 | | Curve448 | 448 | *Curve* is the curve used by the key when *PublicKeyAlgorithm* is *ECDSA*, *EdDSA*, *ECDH*, *Ed25519*, *Ed448*, *X25519*, *X448*, *ML-KEM*, *ML-KEM-768+X25519*, *ML-KEM-1024+X448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448*. Possible values are: | Subkey Curve | Possible Subkey Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA, ECDH, ML-KEM | NIST curve P-256 | | secp384r1 | ECDSA, ECDH, ML-KEM | NIST curve P-384 | | secp521r1 | ECDSA, ECDH, ML-KEM | NIST curve P-521 | | secp256k1 | ECDSA, ECDH, ML-KEM | Secp256k1 | | brainpoolP256r1 | ECDSA, ECDH, ML-KEM | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA, ECDH, ML-KEM | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA, ECDH, ML-KEM | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | EdDSA, Ed448, ML-DSA-87+Ed448 | Ed448 | | Curve25519 | ECDH, X25519, ML-KEM-768+X25519, ML-KEM | Curve25519 | | Curve448 | X448, ML-KEM-1024+X448, ML-KEM | Curve448 | *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](#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: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | *EffectiveDate* is the date when this key became valid. The following example illustrates the format of an encoded date: *23-Jan-2000 15:00:00*. *ExpirationDate* is the date the key expires. After this date the key will no longer be valid. The following example illustrates the format of an encoded date: *23-Jan-2000 15:00:00*. If the ExpirationDate is not populated this indicates that the key never expires. *Revoked* Indicates whether the subkey is revoked or not. # Config Settings ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) The struct 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 struct, access to these *internal properties* is provided through the [config](#config-method-keymgr-struct) 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](#create_key-method-keymgr-struct) 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](#create_key-method-keymgr-struct) and [UseArgon2](#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)). **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](#create_key-method-keymgr-struct) and [UseArgon2](#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](#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](#Argon2Parallelism). Therefore, [Argon2MemorySizeExp](#Argon2MemorySizeExp) must be an integer ranging from 3+ceil(log2(p)) to 31. For example, if [Argon2Parallelism](#Argon2Parallelism) is set to *8*, valid values for [Argon2MemorySizeExp](#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](#create_key-method-keymgr-struct) is called and [UseArgon2](#UseArgon2) is set to *True*. The default value is *4*. Valid values range from 1 to 2^(24)-1. **CompatibilityProfile**: Specifies the OpenPGP compatibility profile used when creating keys.This setting specifies the OpenPGP compatibility profile used when creating keys via [create_key](#create_key-method-keymgr-struct) and [create_sub_key](#create_sub_key-method-keymgr-struct). Possible values are: | | | | --- | --- | | RFC9580 | Creates keys using RFC 9580-compatible defaults, such as native algorithm identifiers for Ed25519, Ed448, X25519, and X448, and RFC 9980 composite post-quantum algorithms (e.g. ML-KEM-768+X25519). This is the default. | | LibrePGP | Creates keys using the conventions GnuPG expects: legacy EdDSA/ECDH algorithm identifiers plus an explicit curve, GnuPG's own ML-KEM composite encoding, and OCB as the only supported AEAD algorithm. | [CompatibilityProfile](#CompatibilityProfile) and [KeyVersion](#KeyVersion) are not fully independent: [KeyVersion](#KeyVersion) *5* requires [CompatibilityProfile](#CompatibilityProfile) to be *LibrePGP*, and [KeyVersion](#KeyVersion) *6* requires it to be *RFC9580*. Only [KeyVersion](#KeyVersion) *4* may be used with either profile. Specifically: - To create a key that GnuPG (2.5.x or later) can use, set [KeyVersion](#KeyVersion) to *5* and [CompatibilityProfile](#CompatibilityProfile) to *LibrePGP*. - To create an RFC 9580 key, including one that uses the RFC 9980 post-quantum algorithms, set [KeyVersion](#KeyVersion) to *6* and [CompatibilityProfile](#CompatibilityProfile) to *RFC9580* (the default). - [KeyVersion](#KeyVersion) *4* may be used with either [CompatibilityProfile](#CompatibilityProfile) value, since the differences between the two profiles mainly involve algorithms and packet versions introduced for OpenPGP v5/v6. Setting [KeyVersion](#KeyVersion) to *5* with [CompatibilityProfile](#CompatibilityProfile) set to *RFC9580*, or [KeyVersion](#KeyVersion) to *6* with [CompatibilityProfile](#CompatibilityProfile) set to *LibrePGP*, raises an error. This setting only affects the format of keys the struct generates; importing existing keys (via [import_key](#import_key-method-keymgr-struct) or [import_key_b](#import_key_b-method-keymgr-struct)) supports both RFC 9580 and LibrePGP formats regardless of this setting. This same setting is also available in the [OpenPGP](OpenPGP.md#OpenPGP) struct, where it controls the format of encrypted and signed messages rather than keys. See the [OpenPGP](OpenPGP.md#OpenPGP) structs *CompatibilityProfile* setting for details. **ContinueOnInvalidKey**: Whether to continue loading the keyring when an invalid key is found.This setting determines whether the struct will continue loading keys when an invalid key is found. This is applicable when calling [load_keyring](#load_keyring-method-keymgr-struct). If set to False (default) the struct fails with an error. If set to True the struct will fire the [on_error](#on_error-event-keymgr-struct) 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 struct will additionally create a subkey marked for encryption when calling [create_key](#create_key-method-keymgr-struct) when [PublicKeyAlgorithm](#PublicKeyAlgorithm) is set to *RSA*. The default is true. Note that if [KeyVersion](#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](#key_usage_flags-property-keymgr-struct). **Curve**: The elliptic curve used when creating a key.This configuration setting specifies the curve to use when calling [create_key](#create_key-method-keymgr-struct). This is only applicable when [PublicKeyAlgorithm](#PublicKeyAlgorithm) is set to *ECDSA*, *EdDSA*, *Ed25519*, or *Ed448*. For *ML-DSA-65+Ed25519* and *ML-DSA-87+Ed448*, the curve is already fixed by the algorithm name (*Ed25519* and *Ed448*, respectively), so [Curve](#Curve) does not need to be set (and if set, must match the curve implied by the algorithm name). Possible curves and [PublicKeyAlgorithm](#PublicKeyAlgorithm) combinations are: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | **EnsureValidDSASignatureHashAlgorithm**: Whether or not to select a suitable signature hash algorithm automatically.This setting specifies whether the struct 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 struct 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 struct 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](#key_curve-property-keymgr-struct) used by the key. When this setting is enabled (default) the struct 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 struct will automatically select a valid hash algorithm based on the curve as follows: | Curve | Hash Algorithm | | --- | --- | | secp256r1 | SHA256 | | secp384r1 | SHA384 | | secp521r1 | SHA512 | | secp256k1 | SHA256 | **ImportAllKeys**: Whether or not to import all keys found in a key file.When calling [import_key](#import_key-method-keymgr-struct) with a *UserId* parameter of "*" or "", the struct 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](#import_key-method-keymgr-struct) 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](#save_keyring-method-keymgr-struct). This is only applicable when [KeyringFormat](#KeyringFormat) is set to *2* (GPG 2.1 and newer). Possible values are as follows: | | | | --- | --- | | 0 | openpgp-s2k3-sha1-aes-cbc (default) | | 1 | openpgp-s2k3-sha1-aes256-cbc | | 2 | openpgp-s2k3-ocb-aes | **KeyEncryptionAlgorithm**: The encryption algorithm used when creating a key.Specifies the encryption algorithm to use when calling [create_key](#create_key-method-keymgr-struct). 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](#UseArgon2) is enabled. In this case, this config must be set to one of the above AEAD encryption algorithms. If [UseArgon2](#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](#key_id-property-keymgr-struct) 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: ```text 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](#save_keyring-method-keymgr-struct). GPG has two formats to store multiple keys. Supported values are as follows: | Config Value | Keyring Format | | --- | --- | | 1 | GPG 2.0 and older (Default) | | 2 | GPG 2.1 and newer | Versions 2.0 and older use keyrings. Public keys are stored in *pubring.gpg*. Secret keys are stored in *secring.gpg*. Versions 2.1 and newer use a keybox. Public keys are stored in a *.kbx* file. Private keys are stored in *private-keys-v1.d*. The default keybox protection mode is *openpgp-s2k3-sha1-aes-cbc*. See [KeyBoxProtectionMode](#KeyBoxProtectionMode) for additional details. For example: ```text keymgr1.Config("KeyringFormat=2"); keymgr1.SaveKeyring("C:\\keyring"); ``` **KeySignatureNotationCount**: The number of notations present in a key's signatures.This setting is read-only. It returns the number of notation data subpackets found in the applicable signatures on the currently selected key. Individual notations may be inspected via [KeySignatureNotationName](#KeySignatureNotationName) and [KeySignatureNotationValue](#KeySignatureNotationValue). Notation data is read from the hashed subpackets of Direct-Key Signatures and User ID certification signatures. For example: ```csharp int count = int.Parse(mgr.Config("KeySignatureNotationCount")); for (int i = 0; i < count; i++) { string name = mgr.Config($"KeySignatureNotationName[{i}]"); string value = mgr.Config($"KeySignatureNotationValue[{i}]"); Console.WriteLine($"{name}: {value}"); } ``` Note that [KeySignatureNotationCount](#KeySignatureNotationCount), [KeySignatureNotationName](#KeySignatureNotationName), and [KeySignatureNotationValue](#KeySignatureNotationValue) are read-only and report notation data already present on the loaded key. To specify notation data when creating or modifying a key, use [SignatureNotationCount](#SignatureNotationCount), [SignatureNotationName](#SignatureNotationName), and [SignatureNotationValue](#SignatureNotationValue) instead. **KeySignatureNotationName[i]**: The name of a notation present in a key's signatures.This setting is read-only. It returns the name of the notation at the specified index. See [KeySignatureNotationCount](#KeySignatureNotationCount) for details, and [SignatureNotationName](#SignatureNotationName) for details about notation name formats and namespaces. **KeySignatureNotationValue[i]**: The value of a notation present in a key's signatures.This setting is read-only. It returns the value of the notation at the specified index. See [KeySignatureNotationCount](#KeySignatureNotationCount) for details. **KeyUsage**: Flags that show intended use for the key being created.When calling [create_key](#create_key-method-keymgr-struct) this setting defines the flags that show the intended use for the key. The default value is (0x0F). The value of [KeyUsage](#KeyUsage) is a combination of the following flags: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | If [KeyUsage](#KeyUsage) includes the encryption flag (0x0C), the struct will automatically create a subkey for encryption. The primary key retains only the remaining (non-encryption) flags. For example, the default value of *0x0F* results in a primary key with usage *0x03* (certify and sign) and a subkey with usage *0x0C* (encrypt). Note that [SubKeyUsage](#SubKeyUsage) is not used during the [create_key](#create_key-method-keymgr-struct) operation, it is only used by [create_sub_key](#create_sub_key-method-keymgr-struct). **KeyValidityTime**: The validity period for the key being created.When [create_key](#create_key-method-keymgr-struct) creates a new key, the key is valid the moment it is created. [KeyValidityTime](#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](#create_key-method-keymgr-struct). Possible values are: | | | | --- | --- | | 4 | The classic OpenPGP key format, originally specified by RFC 4880 and updated by RFC 9580. This is the default, and is understood by essentially every OpenPGP implementation in existence, including every version of GnuPG. Valid with either [CompatibilityProfile](#CompatibilityProfile) value. | | 5 | The GnuPG/LibrePGP key format. Rather than support OpenPGP v6/RFC 9580, GnuPG 2.5.x and later uses this version (also known as LibrePGP). This is the only key version that is structurally compatible with GnuPG 2.5.x+. This version requires [CompatibilityProfile](#CompatibilityProfile) to be set to LibrePGP. Attempting to create a version 5 key with any other profile raises an error. | | 6 | The newest key format, introduced by RFC 9580. This version is required for the RFC 9980 post-quantum algorithms (e.g. ML-DSA-65+Ed25519, ML-KEM-768+X25519), and is supported by other OpenPGP software that has adopted RFC 9580, though not by GnuPG. This version requires [CompatibilityProfile](#CompatibilityProfile) to be set to RFC9580 (the default). Attempting to create a version 6 key with CompatibilityProfile=LibrePGP raises an error, since LibrePGP does not define a version 6 key. | [KeyVersion](#KeyVersion) only determines the structural format of the key packet (e.g. fingerprint algorithm, length encoding). [CompatibilityProfile](#CompatibilityProfile) separately determines which algorithm identifiers and encodings are used within that structure. See [CompatibilityProfile](#CompatibilityProfile) for details on how the two configs are typically used together. **LogLevel**: Specifies the level of detail that is logged.This setting controls the level of detail that is logged through the [on_status](#on_status-event-keymgr-struct) 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](#create_key-method-keymgr-struct). 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: ```csharp // 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](#create_key-method-keymgr-struct). 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: ```csharp // 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](#create_key-method-keymgr-struct). 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: ```csharp // 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](#create_key-method-keymgr-struct). 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: ```csharp // 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](#create_key-method-keymgr-struct). By default, this config will be set to *automatic* and the struct will automatically choose an appropriate algorithm depending on the [KeyVersion](#KeyVersion). For OpenPGP v4, *EdDSA* will be selected as the default. For LibrePGP v5 and OpenPGP v6, *Ed25519* will be selected as the default. Supported values depend on the [KeyVersion](#KeyVersion). Please see below for supported values for each version. | Public Key Algorithm | Supported for OpenPGP v4 | Supported for LibrePGP v5 | Supported for OpenPGP v6 | | --- | --- | --- | --- | | RSA | | | | | DSA | | | | | ECDSA | | | | | EdDSA | | | | | Ed25519 | | | | | Ed448 | | | | | ML-DSA-65+Ed25519 | | | | | ML-DSA-87+Ed448 | | | | | RSA-Legacy | | | | When creating an *RSA* key and [KeyVersion](#KeyVersion) is specified as 6, note that the [PublicKeyLength](#PublicKeyLength) must be greater than or equal to 3072 (default). Additionally, [CreateRSASubkeyForEncrypt](#CreateRSASubkeyForEncrypt) must be disabled. Note that while supported, it is not recommended to create an *RSA* key when [KeyVersion](#KeyVersion) is set to 6. When creating a *DSA* key, the [PublicKeySignatureHashAlgorithm](#PublicKeySignatureHashAlgorithm) value "MD5" is not supported. When creating an *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448* key, the [PublicKeyLength](#PublicKeyLength) value is automatically determined based on the [Curve](#Curve). If [Curve](#Curve) is not specified, the following defaults will be used: | Public Key Algorithm | Default Curve | | --- | --- | | ECDSA | secp256r1 | | EdDSA | Ed25519 | | Ed25519 | Ed25519 | | Ed448 | Ed448 | | ML-DSA-65+Ed25519 | Ed25519 | | ML-DSA-87+Ed448 | Ed448 | The below configurations may be utilized to configure the subkey associated with this key. By default, the struct will automatically select appropriate values based on the [PublicKeyAlgorithm](#PublicKeyAlgorithm). - [SubKeyAlgorithm](#SubKeyAlgorithm) - [SubKeyLength](#SubKeyLength) - [SubKeyCurve](#SubKeyCurve) NOTE: The *RSA-Legacy* algorithm should not be used under normal circumstances. It should only be used to create PGP 2.6.2 compatible keys, when required. This type of key will not have subkeys. **PublicKeyLength**: Specifies the public key length when creating a key.Specifies the length of the public key when calling [create_key](#create_key-method-keymgr-struct). The default value is 3072. This configuration setting is only applicable when [PublicKeyAlgorithm](#PublicKeyAlgorithm) is specified as *RSA* or *DSA*. Note that when [PublicKeyAlgorithm](#PublicKeyAlgorithm) is set to *RSA* and [KeyVersion](#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](#create_key-method-keymgr-struct). 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](#key_revoked-property-keymgr-struct) is True. This may be set before calling [revoke_key](#revoke_key-method-keymgr-struct) and may be inspected after importing and selecting a revoked key. Possible values are: | | | | --- | --- | | 0 | No reason specified | | 1 | Key is superseded | | 2 | Key material has been compromised | | 3 | Key is retired and no longer used | | 4 | User Id information is no longer valid | | 100-110 | Private Use | The default value is 0. **RevocationReason**: Text describing why the key was revoked.This setting specifies text description of why the key was revoked. It is only applicable if [key_revoked](#key_revoked-property-keymgr-struct) is True. This may be set before calling [revoke_key](#revoke_key-method-keymgr-struct) 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](#add_revoker-method-keymgr-struct)). 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. **SignatureNotationCount**: The number of notations to add to a key's signatures.This setting specifies the number of notations to include in a key's signatures when calling [create_key](#create_key-method-keymgr-struct), [add_user_id](#add_user_id-method-keymgr-struct), [sign_user_id](#sign_user_id-method-keymgr-struct), [add_revoker](#add_revoker-method-keymgr-struct), or [change_expiration_date](#change_expiration_date-method-keymgr-struct). Each notation is defined by [SignatureNotationName](#SignatureNotationName) and [SignatureNotationValue](#SignatureNotationValue). The default value is 0. Notations are included in the following signatures, as applicable: - User ID self-signatures / certification signatures. - User ID certification signatures created by [sign_user_id](#sign_user_id-method-keymgr-struct). - The 0x1F Direct-Key Signature created during [create_key](#create_key-method-keymgr-struct) when [KeyVersion](#KeyVersion) is *6*. - The 0x1F Direct-Key Signature created by [add_revoker](#add_revoker-method-keymgr-struct). - The v6 0x1F Direct-Key Signature, and User Id certification signatures, regenerated by [change_expiration_date](#change_expiration_date-method-keymgr-struct). To add notations, set this setting to the number of notations to include, then set [SignatureNotationName](#SignatureNotationName) and [SignatureNotationValue](#SignatureNotationValue) for each index from 0 to ([SignatureNotationCount](#SignatureNotationCount) - 1). For example: ```csharp mgr.Config("SignatureNotationCount=1"); mgr.Config("SignatureNotationName[0]=example@notation.test"); mgr.Config("SignatureNotationValue[0]=some notation value"); mgr.CreateKey("test", "test"); ``` **SignatureNotationName[i]**: The name of a notation to add to a key's signatures.This setting specifies the name of the notation at the specified index. See [SignatureNotationCount](#SignatureNotationCount) for details. Per RFC 9580, notation names belong to one of two namespaces. User namespace notation names have the format *tag@domain*, where *domain* is a DNS domain name owned by the entity defining the notation (for example, *sample@example.com*). The *tag* portion must not contain an *@* character. Notation names that do not contain the *@* character belong to the IETF namespace and must be registered with IANA. The default value is an empty string. **SignatureNotationValue[i]**: The value of a notation to add to a key's signatures.This setting specifies the value of the notation at the specified index. See [SignatureNotationCount](#SignatureNotationCount) for details. The default value is an empty string. **SubKeyAlgorithm**: The public key algorithm for the subkey being created.Specifies the public key algorithm for a subkey. This setting applies both when calling [create_sub_key](#create_sub_key-method-keymgr-struct), and when [create_key](#create_key-method-keymgr-struct) automatically creates an encryption subkey (see [KeyUsage](#KeyUsage) for details). The default value is an empty string, in which case the struct will automatically select an appropriate algorithm based on the primary key's algorithm and the usage of the subkey being created. When calling [create_sub_key](#create_sub_key-method-keymgr-struct), the usage is specified by [SubKeyUsage](#SubKeyUsage). When [create_key](#create_key-method-keymgr-struct) automatically creates an encryption subkey, [SubKeyUsage](#SubKeyUsage) is not used. Instead, the usage is fixed to the encryption flag (0x0C), based on [KeyUsage](#KeyUsage). Supported values depend on the [KeyVersion](#KeyVersion). Please see below for applicable values for each supported version. | Public Key Algorithm | Supported Subkey Operations | Supported for OpenPGP v4 | Supported for LibrePGP v5 | 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 | | | | | ML-KEM | Encrypt | | | | | ML-KEM-768+X25519 | Encrypt | | | | | ML-KEM-1024+X448 | Encrypt | | | | | ML-DSA-65+Ed25519 | Sign | | | | | ML-DSA-87+Ed448 | Sign | | | | *ML-KEM* requires a LibrePGP v5 key ([KeyVersion](#KeyVersion)=5 and [CompatibilityProfile](#CompatibilityProfile)=LibrePGP); an error is raised otherwise. *ML-KEM-768+X25519*, *ML-KEM-1024+X448*, *ML-DSA-65+Ed25519*, and *ML-DSA-87+Ed448* require an OpenPGP v6 key ([KeyVersion](#KeyVersion)=6 and [CompatibilityProfile](#CompatibilityProfile)=RFC9580) instead; an error is likewise raised otherwise. The [SubKeyCurve](#SubKeyCurve) configuration setting is applicable for subkey algorithms *ECDH*, *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *X25519*, *X448*, and *ML-KEM*. For the composite algorithms *ML-KEM-768+X25519*, *ML-KEM-1024+X448*, *ML-DSA-65+Ed25519*, and *ML-DSA-87+Ed448*, the curve is already fixed by the algorithm name, so [SubKeyCurve](#SubKeyCurve) does not need to be set. If [SubKeyCurve](#SubKeyCurve) is not specified, the following subkey curves will be used by default for each [SubKeyAlgorithm](#SubKeyAlgorithm) (for the composite algorithms, this also shows the curve fixed by the algorithm name): | Sub Key Algorithm | Default Curve | | --- | --- | | ECDSA | secp256r1 | | ECDH | secp256r1 | | EdDSA | Ed25519 | | Ed25519 | Ed25519 | | Ed448 | Ed448 | | X25519 | Curve25519 | | X448 | Curve448 | | ML-KEM | Curve25519 | | ML-KEM-768+X25519 | Curve25519 | | ML-KEM-1024+X448 | Curve448 | | ML-DSA-65+Ed25519 | Ed25519 | | ML-DSA-87+Ed448 | Ed448 | Note that the [SubKeyLength](#SubKeyLength) will be automatically determined by the specified [SubKeyCurve](#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](#Curve). This is applicable in either of the following scenarios: 1. When calling [create_key](#create_key-method-keymgr-struct) and [PublicKeyAlgorithm](#PublicKeyAlgorithm) is set to *ECDSA*, *EdDSA*, *Ed25519*, or *Ed448*, and [SubKeyAlgorithm](#SubKeyAlgorithm) is unspecified. 2. When calling [create_key](#create_key-method-keymgr-struct) or [create_sub_key](#create_sub_key-method-keymgr-struct) and [SubKeyAlgorithm](#SubKeyAlgorithm) is set to *ECDH*, *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *X25519*, *X448*, or *ML-KEM*. For the composite algorithms *ML-KEM-768+X25519*, *ML-KEM-1024+X448*, *ML-DSA-65+Ed25519*, and *ML-DSA-87+Ed448*, the curve is already fixed by the algorithm name, so [SubKeyCurve](#SubKeyCurve) does not need to be set (and if set, must match the curve implied by the algorithm name). *ML-KEM* (GnuPG's own, non-composite ML-KEM subkey algorithm) is the exception: it supports multiple curves (defaulting to *Curve25519*), so [SubKeyCurve](#SubKeyCurve) is a meaningful setting for it. Possible values for the [SubKeyCurve](#SubKeyCurve) and associated [SubKeyAlgorithm](#SubKeyAlgorithm)'s are: | Subkey Curve | Possible Subkey Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA, ECDH, ML-KEM | NIST curve P-256 | | secp384r1 | ECDSA, ECDH, ML-KEM | NIST curve P-384 | | secp521r1 | ECDSA, ECDH, ML-KEM | NIST curve P-521 | | secp256k1 | ECDSA, ECDH, ML-KEM | Secp256k1 | | brainpoolP256r1 | ECDSA, ECDH, ML-KEM | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA, ECDH, ML-KEM | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA, ECDH, ML-KEM | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | EdDSA, Ed448, ML-DSA-87+Ed448 | Ed448 | | Curve25519 | ECDH, X25519, ML-KEM-768+X25519, ML-KEM | Curve25519 | | Curve448 | X448, ML-KEM-1024+X448, ML-KEM | Curve448 | *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](#SubKeyCurve). Note if [KeyVersion](#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](#create_key-method-keymgr-struct), or creating subkeys with [create_sub_key](#create_sub_key-method-keymgr-struct). 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](#PublicKeyLength). This configuration setting is only applicable when [PublicKeyAlgorithm](#PublicKeyAlgorithm) is specified as *RSA*, *DSA*, or *ElGamal*, or when [SubKeyAlgorithm](#SubKeyAlgorithm) is *ML-KEM* with *CompatibilityProfile=LibrePGP*. When [SubKeyAlgorithm](#SubKeyAlgorithm) is *ML-KEM* with *CompatibilityProfile=LibrePGP*, [SubKeyLength](#SubKeyLength) selects the ML-KEM parameter set. Valid values are *768* (the default, used if [SubKeyLength](#SubKeyLength) is not specified) and *1024*. Note that when [PublicKeyAlgorithm](#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](#create_sub_key-method-keymgr-struct) this setting defines the flags that show the intended use for the key. The default value is (0x0C). The value of [SubKeyUsage](#SubKeyUsage) is a combination of the following flags: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | Note that if [KeyVersion](#KeyVersion) is 6 and [SubKeyAlgorithm](#SubKeyAlgorithm) is *RSA*, the key must have both signing and encrypting capabilities (0x0F). Additionally, note that [SubKeyUsage](#SubKeyUsage) is only applicable when calling [create_sub_key](#create_sub_key-method-keymgr-struct). It does not affect the usage of the subkey that [create_key](#create_key-method-keymgr-struct) automatically creates for encryption. See [KeyUsage](#KeyUsage) for additional details. **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](#create_key-method-keymgr-struct) is called. The default value is *False*. The following configuration settings are applicable when this config is set to *True*: - [Argon2Iterations](#Argon2Iterations) - [Argon2Parallelism](#Argon2Parallelism) - [Argon2MemorySizeExp](#Argon2MemorySizeExp) Note if [UseArgon2](#UseArgon2) is enabled, an AEAD encryption algorithm must be specified by [KeyEncryptionAlgorithm](#KeyEncryptionAlgorithm) (e.g., *AES192-OCB*). Please see [KeyEncryptionAlgorithm](#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](#export_public_key-method-keymgr-struct) where the UseAsciiArmor parameter is true. The default value is "IPWorks PGP 2024". ### Base Config Settings **BuildInfo**: Information about the product's build.When queried, this setting will return a string containing information about the product's build. **CodePage**: The system code page used for Unicode to Multibyte translations.The default code page is Unicode UTF-8 (65001). The following is a list of valid code page identifiers: | | | | --- | --- | | Identifier | Name | | 037 | IBM EBCDIC - U.S./Canada | | 437 | OEM - United States | | 500 | IBM EBCDIC - International | | 708 | Arabic - ASMO 708 | | 709 | Arabic - ASMO 449+, BCON V4 | | 710 | Arabic - Transparent Arabic | | 720 | Arabic - Transparent ASMO | | 737 | OEM - Greek (formerly 437G) | | 775 | OEM - Baltic | | 850 | OEM - Multilingual Latin I | | 852 | OEM - Latin II | | 855 | OEM - Cyrillic (primarily Russian) | | 857 | OEM - Turkish | | 858 | OEM - Multilingual Latin I + Euro symbol | | 860 | OEM - Portuguese | | 861 | OEM - Icelandic | | 862 | OEM - Hebrew | | 863 | OEM - Canadian-French | | 864 | OEM - Arabic | | 865 | OEM - Nordic | | 866 | OEM - Russian | | 869 | OEM - Modern Greek | | 870 | IBM EBCDIC - Multilingual/ROECE (Latin-2) | | 874 | ANSI/OEM - Thai (same as 28605, ISO 8859-15) | | 875 | IBM EBCDIC - Modern Greek | | 932 | ANSI/OEM - Japanese, Shift-JIS | | 936 | ANSI/OEM - Simplified Chinese (PRC, Singapore) | | 949 | ANSI/OEM - Korean (Unified Hangul Code) | | 950 | ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC) | | 1026 | IBM EBCDIC - Turkish (Latin-5) | | 1047 | IBM EBCDIC - Latin 1/Open System | | 1140 | IBM EBCDIC - U.S./Canada (037 + Euro symbol) | | 1141 | IBM EBCDIC - Germany (20273 + Euro symbol) | | 1142 | IBM EBCDIC - Denmark/Norway (20277 + Euro symbol) | | 1143 | IBM EBCDIC - Finland/Sweden (20278 + Euro symbol) | | 1144 | IBM EBCDIC - Italy (20280 + Euro symbol) | | 1145 | IBM EBCDIC - Latin America/Spain (20284 + Euro symbol) | | 1146 | IBM EBCDIC - United Kingdom (20285 + Euro symbol) | | 1147 | IBM EBCDIC - France (20297 + Euro symbol) | | 1148 | IBM EBCDIC - International (500 + Euro symbol) | | 1149 | IBM EBCDIC - Icelandic (20871 + Euro symbol) | | 1200 | Unicode UCS-2 Little-Endian (BMP of ISO 10646) | | 1201 | Unicode UCS-2 Big-Endian | | 1250 | ANSI - Central European | | 1251 | ANSI - Cyrillic | | 1252 | ANSI - Latin I | | 1253 | ANSI - Greek | | 1254 | ANSI - Turkish | | 1255 | ANSI - Hebrew | | 1256 | ANSI - Arabic | | 1257 | ANSI - Baltic | | 1258 | ANSI/OEM - Vietnamese | | 1361 | Korean (Johab) | | 10000 | MAC - Roman | | 10001 | MAC - Japanese | | 10002 | MAC - Traditional Chinese (Big5) | | 10003 | MAC - Korean | | 10004 | MAC - Arabic | | 10005 | MAC - Hebrew | | 10006 | MAC - Greek I | | 10007 | MAC - Cyrillic | | 10008 | MAC - Simplified Chinese (GB 2312) | | 10010 | MAC - Romania | | 10017 | MAC - Ukraine | | 10021 | MAC - Thai | | 10029 | MAC - Latin II | | 10079 | MAC - Icelandic | | 10081 | MAC - Turkish | | 10082 | MAC - Croatia | | 12000 | Unicode UCS-4 Little-Endian | | 12001 | Unicode UCS-4 Big-Endian | | 20000 | CNS - Taiwan | | 20001 | TCA - Taiwan | | 20002 | Eten - Taiwan | | 20003 | IBM5550 - Taiwan | | 20004 | TeleText - Taiwan | | 20005 | Wang - Taiwan | | 20105 | IA5 IRV International Alphabet No. 5 (7-bit) | | 20106 | IA5 German (7-bit) | | 20107 | IA5 Swedish (7-bit) | | 20108 | IA5 Norwegian (7-bit) | | 20127 | US-ASCII (7-bit) | | 20261 | T.61 | | 20269 | ISO 6937 Non-Spacing Accent | | 20273 | IBM EBCDIC - Germany | | 20277 | IBM EBCDIC - Denmark/Norway | | 20278 | IBM EBCDIC - Finland/Sweden | | 20280 | IBM EBCDIC - Italy | | 20284 | IBM EBCDIC - Latin America/Spain | | 20285 | IBM EBCDIC - United Kingdom | | 20290 | IBM EBCDIC - Japanese Katakana Extended | | 20297 | IBM EBCDIC - France | | 20420 | IBM EBCDIC - Arabic | | 20423 | IBM EBCDIC - Greek | | 20424 | IBM EBCDIC - Hebrew | | 20833 | IBM EBCDIC - Korean Extended | | 20838 | IBM EBCDIC - Thai | | 20866 | Russian - KOI8-R | | 20871 | IBM EBCDIC - Icelandic | | 20880 | IBM EBCDIC - Cyrillic (Russian) | | 20905 | IBM EBCDIC - Turkish | | 20924 | IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol) | | 20932 | JIS X 0208-1990 & 0121-1990 | | 20936 | Simplified Chinese (GB2312) | | 21025 | IBM EBCDIC - Cyrillic (Serbian, Bulgarian) | | 21027 | Extended Alpha Lowercase | | 21866 | Ukrainian (KOI8-U) | | 28591 | ISO 8859-1 Latin I | | 28592 | ISO 8859-2 Central Europe | | 28593 | ISO 8859-3 Latin 3 | | 28594 | ISO 8859-4 Baltic | | 28595 | ISO 8859-5 Cyrillic | | 28596 | ISO 8859-6 Arabic | | 28597 | ISO 8859-7 Greek | | 28598 | ISO 8859-8 Hebrew | | 28599 | ISO 8859-9 Latin 5 | | 28605 | ISO 8859-15 Latin 9 | | 29001 | Europa 3 | | 38598 | ISO 8859-8 Hebrew | | 50220 | ISO 2022 Japanese with no halfwidth Katakana | | 50221 | ISO 2022 Japanese with halfwidth Katakana | | 50222 | ISO 2022 Japanese JIS X 0201-1989 | | 50225 | ISO 2022 Korean | | 50227 | ISO 2022 Simplified Chinese | | 50229 | ISO 2022 Traditional Chinese | | 50930 | Japanese (Katakana) Extended | | 50931 | US/Canada and Japanese | | 50933 | Korean Extended and Korean | | 50935 | Simplified Chinese Extended and Simplified Chinese | | 50936 | Simplified Chinese | | 50937 | US/Canada and Traditional Chinese | | 50939 | Japanese (Latin) Extended and Japanese | | 51932 | EUC - Japanese | | 51936 | EUC - Simplified Chinese | | 51949 | EUC - Korean | | 51950 | EUC - Traditional Chinese | | 52936 | HZ-GB2312 Simplified Chinese | | 54936 | Windows XP: GB18030 Simplified Chinese (4 Byte) | | 57002 | ISCII Devanagari | | 57003 | ISCII Bengali | | 57004 | ISCII Tamil | | 57005 | ISCII Telugu | | 57006 | ISCII Assamese | | 57007 | ISCII Oriya | | 57008 | ISCII Kannada | | 57009 | ISCII Malayalam | | 57010 | ISCII Gujarati | | 57011 | ISCII Punjabi | | 65000 | Unicode UTF-7 | | 65001 | Unicode UTF-8 | The following is a list of valid code page identifiers for Mac OS only: | | | | --- | --- | | Identifier | Name | | 1 | ASCII | | 2 | NEXTSTEP | | 3 | JapaneseEUC | | 4 | UTF8 | | 5 | ISOLatin1 | | 6 | Symbol | | 7 | NonLossyASCII | | 8 | ShiftJIS | | 9 | ISOLatin2 | | 10 | Unicode | | 11 | WindowsCP1251 | | 12 | WindowsCP1252 | | 13 | WindowsCP1253 | | 14 | WindowsCP1254 | | 15 | WindowsCP1250 | | 21 | ISO2022JP | | 30 | MacOSRoman | | 10 | UTF16String | | 0x90000100 | UTF16BigEndian | | 0x94000100 | UTF16LittleEndian | | 0x8c000100 | UTF32String | | 0x98000100 | UTF32BigEndian | | 0x9c000100 | UTF32LittleEndian | | 65536 | Proprietary | **LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a struct 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*. **UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the struct will use the system security libraries by default to perform cryptographic functions where applicable. Setting this configuration setting to *true* tells the struct 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](platforms.md) section. # Trappable Errors ([KeyMgr](#struct-ipworkspgpkeymgr) Struct) ### 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. |