# KeyMgr Component The KeyMgr component is used to create and manage OpenPGP keys. ## Syntax ```text nsoftware.IPWorksPGP.KeyMgr ``` ## Remarks The KeyMgr component 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 component 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. ## Property List *The following is the full list of the properties of the component with short descriptions. Click on the links for further details.* | | | | --- | --- | | [Key](#key-property-keymgr-component) | The currently selected key. | ## Method List *The following is the full list of the methods of the component with short descriptions. Click on the links for further details.* | | | | --- | --- | | [AddRevoker](#addrevoker-method-keymgr-component) | Adds a designated revoker to the key. | | [AddUserId](#adduserid-method-keymgr-component) | Adds the specified user Id to the current key. | | [ChangeExpirationDate](#changeexpirationdate-method-keymgr-component) | Changes the expiration date of the key. | | [ChangePassphrase](#changepassphrase-method-keymgr-component) | Changes the passphrase of the current key. | | [Config](#config-method-keymgr-component) | Sets or retrieves a configuration setting. | | [CreateKey](#createkey-method-keymgr-component) | Creates an OpenPGP key pair. | | [CreateSubKey](#createsubkey-method-keymgr-component) | Creates a new subkey. | | [DeleteKey](#deletekey-method-keymgr-component) | Deletes the specified key. | | [ExportPublicKey](#exportpublickey-method-keymgr-component) | Exports the public key of the current key. | | [ExportSecretKey](#exportsecretkey-method-keymgr-component) | Exports the private key of the current key. | | [ImportKey](#importkey-method-keymgr-component) | Imports the key specified by UserId to the current keyring. | | [ImportKeyB](#importkeyb-method-keymgr-component) | Imports the key specified by UserId to the current keyring. | | [ListKeys](#listkeys-method-keymgr-component) | Lists keys in the specified Keyring . | | [ListSignatures](#listsignatures-method-keymgr-component) | Lists all signatures of the current key. | | [ListSubkeys](#listsubkeys-method-keymgr-component) | Lists the subkeys of the currently selected key. | | [LoadKeyring](#loadkeyring-method-keymgr-component) | Loads the keyring from disk. | | [LoadKeyringB](#loadkeyringb-method-keymgr-component) | Loads the keyring from SecretKeyringData and PublicKeyringData . | | [Reset](#reset-method-keymgr-component) | Resets the component properties. | | [RevokeKey](#revokekey-method-keymgr-component) | Revokes the specified key. | | [SaveKeyring](#savekeyring-method-keymgr-component) | Saves the current Keyring to disk. | | [SignUserId](#signuserid-method-keymgr-component) | Signs the specified user Id of the current key. | | [VerifyPassphrase](#verifypassphrase-method-keymgr-component) | Verifies the passphrase of specified key. | ## Event List *The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.* | | | | --- | --- | | [Error](#error-event-keymgr-component) | Fired when information is available about errors during data delivery. | | [KeyList](#keylist-event-keymgr-component) | Fires for each key in the keyring when [ListKeys](#listkeys-method-keymgr-component) is called. | | [KeyPassphrase](#keypassphrase-event-keymgr-component) | Fired if the passphrase of current key is incorrect or empty. | | [SignatureList](#signaturelist-event-keymgr-component) | Fires for each signature of the current key when [ListSignatures](#listsignatures-method-keymgr-component) is called. | | [Status](#status-event-keymgr-component) | Shows the progress of the operation. | | [SubkeyList](#subkeylist-event-keymgr-component) | Fires once for each subkey listed when [ListSubkeys](#listsubkeys-method-keymgr-component) is called. | ## Config Settings *The following is a list of config settings for the component 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. | | [ChangeSubkeyPassphrase](#ChangeSubkeyPassphrase) | Whether or not the passphrase for subkey's should be changed. | | [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. | | [GUIAvailable](#GUIAvailable) | Whether or not a message loop is available for processing events. | | [LicenseInfo](#LicenseInfo) | Information about the current license. | | [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. | | [UseFIPSCompliantAPI](#UseFIPSCompliantAPI) | Tells the component whether or not to use FIPS certified APIs. | | [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. | # Key Property ([KeyMgr](#keymgr-component) Component) The currently selected key. ## Syntax ```text public Key Key { get; set; } ``` ## Remarks This property holds the currently selected key. It is populated after calling [ImportKey](#importkey-method-keymgr-component). This may also be set to directly load an existing key. Both public keys and secret keys are supported. This property is not available at design time. Please refer to the [Key](#key-type) type for a complete list of fields. # AddRevoker Method ([KeyMgr](#keymgr-component) Component) Adds a designated revoker to the key. ## Syntax ```text public void AddRevoker(string userId); Async Version public async Task AddRevoker(string userId); public async Task AddRevoker(string userId, CancellationToken cancellationToken); ``` ## Remarks This method adds a designated revoker to the selected [Key](#key-property-keymgr-component). 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 [Passphrase](#Key_f_Passphrase) or through the [KeyPassphrase](#keypassphrase-event-keymgr-component) 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. # AddUserId Method ([KeyMgr](#keymgr-component) Component) Adds the specified user Id to the current key. ## Syntax ```text public void AddUserId(string userId); Async Version public async Task AddUserId(string userId); public async Task AddUserId(string userId, CancellationToken cancellationToken); ``` ## Remarks The key's passphrase is required for this operation and may be specified via [Passphrase](#Key_f_Passphrase) or through the [KeyPassphrase](#keypassphrase-event-keymgr-component) 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. # ChangeExpirationDate Method ([KeyMgr](#keymgr-component) Component) Changes the expiration date of the key. ## Syntax ```text public void ChangeExpirationDate(int expirationDate); Async Version public async Task ChangeExpirationDate(int expirationDate); public async Task ChangeExpirationDate(int expirationDate, CancellationToken cancellationToken); ``` ## Remarks This method changes the expiration date of the current [Key](#key-property-keymgr-component). 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 [Passphrase](#Key_f_Passphrase) or through the [KeyPassphrase](#keypassphrase-event-keymgr-component) event. Note: See [KeyValidityTime](#KeyValidityTime) for information on specifying the expiration date when creating the key with [CreateKey](#createkey-method-keymgr-component). # ChangePassphrase Method ([KeyMgr](#keymgr-component) Component) Changes the passphrase of the current key. ## Syntax ```text public void ChangePassphrase(string passphrase); Async Version public async Task ChangePassphrase(string passphrase); public async Task ChangePassphrase(string passphrase, CancellationToken cancellationToken); ``` ## Remarks The *Passphrase* parameter specifies the new passphrase. The key's passphrase is required for this operation and may be specified via [Passphrase](#Key_f_Passphrase) or through the [KeyPassphrase](#keypassphrase-event-keymgr-component) event. # Config Method ([KeyMgr](#keymgr-component) Component) Sets or retrieves a configuration setting. ## Syntax ```text public string Config(string configurationString); Async Version public async Task Config(string configurationString); public async Task Config(string configurationString, CancellationToken cancellationToken); ``` ## Remarks Config is a generic method available in every component. It is used to set and retrieve [configuration settings](#config-settings-keymgr-component) for the component. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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-component), you must call *Config("PROPERTY")*. The value will be returned as a string. # CreateKey Method ([KeyMgr](#keymgr-component) Component) Creates an OpenPGP key pair. ## Syntax ```text public void CreateKey(string userId, string passphrase); Async Version public async Task CreateKey(string userId, string passphrase); public async Task CreateKey(string userId, string passphrase, CancellationToken cancellationToken); ``` ## 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) # CreateSubKey Method ([KeyMgr](#keymgr-component) Component) Creates a new subkey. ## Syntax ```text public void CreateSubKey(); Async Version public async Task CreateSubKey(); public async Task CreateSubKey(CancellationToken cancellationToken); ``` ## Remarks This method creates a new subkey. Before calling this method the [Key](#key-property-keymgr-component) 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) # DeleteKey Method ([KeyMgr](#keymgr-component) Component) Deletes the specified key. ## Syntax ```text public void DeleteKey(string userId); Async Version public async Task DeleteKey(string userId); public async Task DeleteKey(string userId, CancellationToken cancellationToken); ``` ## 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 | # ExportPublicKey Method ([KeyMgr](#keymgr-component) Component) Exports the public key of the current key. ## Syntax ```text public void ExportPublicKey(string fileName, bool useAsciiArmor); Async Version public async Task ExportPublicKey(string fileName, bool useAsciiArmor); public async Task ExportPublicKey(string fileName, bool useAsciiArmor, CancellationToken cancellationToken); ``` ## Remarks This method exports the public key of the currently selected [Key](#key-property-keymgr-component). 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. # ExportSecretKey Method ([KeyMgr](#keymgr-component) Component) Exports the private key of the current key. ## Syntax ```text public void ExportSecretKey(string fileName, bool useAsciiArmor); Async Version public async Task ExportSecretKey(string fileName, bool useAsciiArmor); public async Task ExportSecretKey(string fileName, bool useAsciiArmor, CancellationToken cancellationToken); ``` ## Remarks This method exports the private key of the currently selected [Key](#key-property-keymgr-component). The *FileName* parameter specifies the file on disk that the private key will be written to. The *UseAsciiArmor* parameter determines whether or not ASCII armoring is used when writing the key to disk. # ImportKey Method ([KeyMgr](#keymgr-component) Component) Imports the key specified by UserId to the current keyring. ## Syntax ```text public void ImportKey(string fileName, string userId); Async Version public async Task ImportKey(string fileName, string userId); public async Task ImportKey(string fileName, string userId, CancellationToken cancellationToken); ``` ## Remarks This method imports the key specified by *UserId* from the key file specified by *FileName* into the current [Keyring](#Key_f_Keyring). The imported key will be automatically selected and available in the [Key](#key-property-keymgr-component) 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 component in this case. Note: If you simply wish to select a key in the current ring set [UserId](#Key_f_UserId) instead. # ImportKeyB Method ([KeyMgr](#keymgr-component) Component) Imports the key specified by UserId to the current keyring. ## Syntax ```text public void ImportKeyB(byte[] data, string userId); Async Version public async Task ImportKeyB(byte[] data, string userId); public async Task ImportKeyB(byte[] data, string userId, CancellationToken cancellationToken); ``` ## Remarks This method imports the key specified by *UserId* from the key data specified by *Data* into the current [Keyring](#Key_f_Keyring). The imported key will be automatically selected and available in the [Key](#key-property-keymgr-component) 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 component in this case. Note: If you simply wish to select a key in the current ring set [UserId](#Key_f_UserId) instead. # ListKeys Method ([KeyMgr](#keymgr-component) Component) Lists keys in the specified Keyring . ## Syntax ```text public string ListKeys(); Async Version public async Task ListKeys(); public async Task ListKeys(CancellationToken cancellationToken); ``` ## Remarks This method lists the keys (public/private key pairs) in the specified keyring. The results are provided through the [KeyList](#keylist-event-keymgr-component) event. KeyList data will also be returned from this method, however it is recommended to use the [KeyList](#keylist-event-keymgr-component) event if possible. # ListSignatures Method ([KeyMgr](#keymgr-component) Component) Lists all signatures of the current key. ## Syntax ```text public string ListSignatures(); Async Version public async Task ListSignatures(); public async Task ListSignatures(CancellationToken cancellationToken); ``` ## Remarks This method lists all the signatures of the currently selected key. The [SignatureList](#signaturelist-event-keymgr-component) event will fire for each signature. SignatureList data will also be returned from this method. However, it is recommended to use the [SignatureList](#signaturelist-event-keymgr-component) event if possible. # ListSubkeys Method ([KeyMgr](#keymgr-component) Component) Lists the subkeys of the currently selected key. ## Syntax ```text public string ListSubkeys(); Async Version public async Task ListSubkeys(); public async Task ListSubkeys(CancellationToken cancellationToken); ``` ## Remarks This method lists all subkeys of current key. The [SubkeyList](#subkeylist-event-keymgr-component) event will be fired for each subkey. SubkeyList data will also be returned from this method, however it is recommended to use the [SubkeyList](#subkeylist-event-keymgr-component) event if possible. # LoadKeyring Method ([KeyMgr](#keymgr-component) Component) Loads the keyring from disk. ## Syntax ```text public void LoadKeyring(string keyringPath); Async Version public async Task LoadKeyring(string keyringPath); public async Task LoadKeyring(string keyringPath, CancellationToken cancellationToken); ``` ## 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 component will read the keyring and populate the [Key](#key-property-keymgr-component) property with the first key found in the keyring. Set [UserId](#Key_f_UserId) to select a different key in the current keyring. # LoadKeyringB Method ([KeyMgr](#keymgr-component) Component) Loads the keyring from * SecretKeyringData * and * PublicKeyringData * . ## Syntax ```text public void LoadKeyringB(byte[] secretKeyringData, byte[] publicKeyringData); Async Version public async Task LoadKeyringB(byte[] secretKeyringData, byte[] publicKeyringData); public async Task LoadKeyringB(byte[] secretKeyringData, byte[] publicKeyringData, CancellationToken cancellationToken); ``` ## Remarks This method loads the keyring from *SecretKeyringData* and *PublicKeyringData*. When this method is called the component will read the keyring and populate the [Key](#key-property-keymgr-component) property with the first key found in the keyring. Set [UserId](#Key_f_UserId) to select a different key in the current keyring. # Reset Method ([KeyMgr](#keymgr-component) Component) Resets the component properties. ## Syntax ```text public void Reset(); Async Version public async Task Reset(); public async Task Reset(CancellationToken cancellationToken); ``` ## Remarks This method resets all message and key properties to their default values. # RevokeKey Method ([KeyMgr](#keymgr-component) Component) Revokes the specified key. ## Syntax ```text public string RevokeKey(string keyId); Async Version public async Task RevokeKey(string keyId); public async Task RevokeKey(string keyId, CancellationToken cancellationToken); ``` ## Remarks This method revokes the key specified by KeyId and returns the revocation certificate. When creating a revocation certificate there are two supported formats. The first format includes only the revocation signature. This format is returned by this method. The second format includes both the public key and the revocation signature. This format can be obtained by calling [ExportPublicKey](#exportpublickey-method-keymgr-component) after calling this method. Both formats are common, and both formats are acceptable when calling [ImportKey](#importkey-method-keymgr-component). Before calling this method a key must be selected and available in the [Key](#key-property-keymgr-component) 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 ``` # SaveKeyring Method ([KeyMgr](#keymgr-component) Component) Saves the current Keyring to disk. ## Syntax ```text public void SaveKeyring(string keyringPath); Async Version public async Task SaveKeyring(string keyringPath); public async Task SaveKeyring(string keyringPath, CancellationToken cancellationToken); ``` ## 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 component will create a "pubring.gpg" and "secring.gpg" file in the specified directory. If the files already exist they will be overwritten. To save the keyring to a key file set *KeyringPath* to a path and file name. If the file already exists it will be overwritten. # SignUserId Method ([KeyMgr](#keymgr-component) Component) Signs the specified user Id of the current key. ## Syntax ```text public void SignUserId(string userId, string issuerUserId); Async Version public async Task SignUserId(string userId, string issuerUserId); public async Task SignUserId(string userId, string issuerUserId, CancellationToken cancellationToken); ``` ## 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 [Passphrase](#Key_f_Passphrase) or through the [KeyPassphrase](#keypassphrase-event-keymgr-component) event. # VerifyPassphrase Method ([KeyMgr](#keymgr-component) Component) Verifies the passphrase of specified key. ## Syntax ```text public bool VerifyPassphrase(string passphrase); Async Version public async Task VerifyPassphrase(string passphrase); public async Task VerifyPassphrase(string passphrase, CancellationToken cancellationToken); ``` ## Remarks This method verifies the passphrase of the key specified by UserId. If the password is correct, this method returns True; otherwise, this method returns False. # Error Event ([KeyMgr](#keymgr-component) Component) Fired when information is available about errors during data delivery. ## Syntax ```text public event OnErrorHandler OnError; public delegate void OnErrorHandler(object sender, KeyMgrErrorEventArgs e); public class KeyMgrErrorEventArgs : EventArgs { public int ErrorCode { get; } public string Description { get; } } ``` ## Remarks The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception. The *ErrorCode* parameter contains an error code, and the *Description* parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the [Error Codes](#trappable-errors-keymgr-component) section. # KeyList Event ([KeyMgr](#keymgr-component) Component) Fires for each key in the keyring when [ListKeys](#listkeys-method-keymgr-component) is called. ## Syntax ```text public event OnKeyListHandler OnKeyList; public delegate void OnKeyListHandler(object sender, KeyMgrKeyListEventArgs e); public class KeyMgrKeyListEventArgs : EventArgs { public string UserId { get; } public string KeyId { get; } public string Fingerprint { get; } public bool HasSecretKey { get; } public string PublicKeyAlgorithm { get; } public int PublicKeyLength { get; } public string Curve { get; } } ``` ## Remarks This event fires once for each key in the [Keyring](#Key_f_Keyring) when [ListKeys](#listkeys-method-keymgr-component) 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 | # KeyPassphrase Event ([KeyMgr](#keymgr-component) Component) Fired if the passphrase of current key is incorrect or empty. ## Syntax ```text public event OnKeyPassphraseHandler OnKeyPassphrase; public delegate void OnKeyPassphraseHandler(object sender, KeyMgrKeyPassphraseEventArgs e); public class KeyMgrKeyPassphraseEventArgs : EventArgs { public string UserId { get; } public string KeyId { get; } public string Fingerprint { get; } public string Passphrase { get; set; } } ``` ## 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 [Passphrase](#Key_f_Passphrase) field before attempting the operation. The passphrase is required when using the following methods in KeyMgr: - [AddUserId](#adduserid-method-keymgr-component) - [SignUserId](#signuserid-method-keymgr-component) - [ChangeExpirationDate](#changeexpirationdate-method-keymgr-component) - [ChangePassphrase](#changepassphrase-method-keymgr-component) When using the OpenPGP component, or an email-based component, the following methods require a passphrase for the key: - Decrypt - Sign - SignAndEncrypt *UserId* holds the user Id of the key the passphrase is required for. The *UserId* format is: ```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 ``` # SignatureList Event ([KeyMgr](#keymgr-component) Component) Fires for each signature of the current key when [ListSignatures](#listsignatures-method-keymgr-component) is called. ## Syntax ```text public event OnSignatureListHandler OnSignatureList; public delegate void OnSignatureListHandler(object sender, KeyMgrSignatureListEventArgs e); public class KeyMgrSignatureListEventArgs : EventArgs { public string KeyId { get; } public string Fingerprint { get; } public string UserId { get; } public string IssuerFingerprint { get; } public string IssuerKeyId { get; } public string IssuerUserId { get; } public string PublicKeyAlgorithm { get; } public string Curve { get; } public string HashAlgorithm { get; } public string EffectiveDate { get; } public int SignatureClass { get; } public int ValidityStatus { get; } } ``` ## Remarks This event fires once for each signature of the current key when [ListSignatures](#listsignatures-method-keymgr-component) 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) | # Status Event ([KeyMgr](#keymgr-component) Component) Shows the progress of the operation. ## Syntax ```text public event OnStatusHandler OnStatus; public delegate void OnStatusHandler(object sender, KeyMgrStatusEventArgs e); public class KeyMgrStatusEventArgs : EventArgs { public string Message { get; } } ``` ## 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. # SubkeyList Event ([KeyMgr](#keymgr-component) Component) Fires once for each subkey listed when [ListSubkeys](#listsubkeys-method-keymgr-component) is called. ## Syntax ```text public event OnSubkeyListHandler OnSubkeyList; public delegate void OnSubkeyListHandler(object sender, KeyMgrSubkeyListEventArgs e); public class KeyMgrSubkeyListEventArgs : EventArgs { public string KeyId { get; } public string Fingerprint { get; } public string PublicKeyAlgorithm { get; } public int PublicKeyLength { get; } public string Curve { get; } public int UsageFlags { get; } public string Usage { get; } public string EffectiveDate { get; } public string ExpirationDate { get; } public bool Revoked { get; } } ``` ## Remarks This event fires once for each subkey when [ListSubkeys](#listsubkeys-method-keymgr-component) 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. # Key Type The OpenPGP key being used. ## Remarks This type describes the current key. The key may be a public or secret key. The fields are used to identify or select the key. The following fields are available: - [Curve](#Key_f_Curve) - [EffectiveDate](#Key_f_EffectiveDate) - [ExpirationDate](#Key_f_ExpirationDate) - [Keyring](#Key_f_Keyring) - [OtherUserIds](#Key_f_OtherUserIds) - [Passphrase](#Key_f_Passphrase) - [PublicKey](#Key_f_PublicKey) - [PublicKeyAlgorithm](#Key_f_PublicKeyAlgorithm) - [PublicKeyLength](#Key_f_PublicKeyLength) - [Revoked](#Key_f_Revoked) - [SecretKey](#Key_f_SecretKey) - [SecretKeyAvailable](#Key_f_SecretKeyAvailable) - [Usage](#Key_f_Usage) - [UsageFlags](#Key_f_UsageFlags) - [Version](#Key_f_Version) - [UserId](#Key_f_UserId) - [Id](#Key_f_Id) - [Fingerprint](#Key_f_Fingerprint) - [Encoded](#Key_f_Encoded) ## Fields **Curve** *string (read-only)* Default: "" This field specifies the elliptic curve if [PublicKeyAlgorithm](#Key_f_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 | **EffectiveDate** *string (read-only)* Default: "" 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. **ExpirationDate** *string (read-only)* Default: "" 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. **Keyring** *string* Default: "" 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 field is set the component will read the keyring and populate the Key property with the first key found in the keyring. Set [UserId](#Key_f_UserId) to select a different key in the current keyring. **OtherUserIds** *string (read-only)* Default: "" If the specified key has alternate user Ids associated with it, this field returns a comma-separated list of the other user Ids. **Passphrase** *string* Default: "" 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 field or through the KeyPassphrase event, which will fire when a passphrase is required. The passphrase is required when using the following methods in KeyMgr: - AddUserId - SignUserId - ChangeExpirationDate - ChangePassphrase When using the OpenPGP component, or an email-based component, the following methods require a passphrase for the key: - Decrypt - Sign - SignAndEncrypt **PublicKey** *string (read-only)* Default: "" The public key of the key. The key is provided as ASCII armored data. **PublicKeyAlgorithm** *string (read-only)* Default: "" 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 **PublicKeyLength** *int (read-only)* Default: 0 The length of the public key in bits. Common values are 1024, 2048, and 3072. If the [PublicKeyAlgorithm](#Key_f_PublicKeyAlgorithm) field 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](#Key_f_Curve). Possible lengths are: | Curve | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | **Revoked** *bool (read-only)* Default: False Whether or not the key is revoked. **SecretKey** *string (read-only)* Default: "" The secret key of the key (if available). The key is provided as ASCII armored data. **SecretKeyAvailable** *bool (read-only)* Default: False Whether or not a secret key is available for the selected key. **Usage** *string (read-only)* Default: "" A text description of [UsageFlags](#Key_f_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** *int (read-only)* Default: 47 Flags that show the intended use for the key. The default value is 0x0F. The value of [UsageFlags](#Key_f_UsageFlags) 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 [Usage](#Key_f_Usage) field for a text representation of [UsageFlags](#Key_f_UsageFlags). **Version** *int (read-only)* Default: 4 This field 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 **UserId** *string* Default: "" The user Id of the key. When a key is loaded this field is populated with the user Id associated with the key. This field may be set to load a key from the [Keyring](#Key_f_Keyring). When this field is set the component will search the [Keyring](#Key_f_Keyring) for a key associated with the UserId specified. When loading a key with multiple user Ids, this field 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 field and [OtherUserIds](#Key_f_OtherUserIds) 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 field to select a key you may also specify the key's Id, or any of its subkeys' Ids, instead of a user Id. The component 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 component's RecipientInfo event. **Id** *string* Default: "" 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 field is populated with the Id associated with the key. This field may be set to load a key from the [Keyring](#Key_f_Keyring). When this field is set the component will search the [Keyring](#Key_f_Keyring) for a key associated with the Id specified. The KeyIdLength setting may be set to control the length of the returned key Id. NOTE: It is recommended to use the [Fingerprint](#Key_f_Fingerprint) field when loading a key from the [Keyring](#Key_f_Keyring), as it is possible for different keys to have the same Id. **Fingerprint** *string* Default: "" The hex-encoded, 20-byte fingerprint of the key. When a key is loaded, this field is populated with the Fingerprint associated with the key. This field may be set to load a key from the [Keyring](#Key_f_Keyring). When this field is set the component will search the [Keyring](#Key_f_Keyring) for a key associated with the Fingerprint specified. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` **Encoded** *string* Default: "" The key. This field can be used to assign a specific key. The [Fingerprint](#Key_f_Fingerprint), [Id](#Key_f_Id), and [UserId](#Key_f_UserId) fields may also be used to specify a key. **EncodedB** *byte []* Default: "" The key. This field can be used to assign a specific key. The [Fingerprint](#Key_f_Fingerprint), [Id](#Key_f_Id), and [UserId](#Key_f_UserId) fields may also be used to specify a key. ## Constructors ```text public Key(string keyring); ``` Reads the OpenPGP public key from the specified * Keyring * . If multiple keys are present only the first one is used. ```text public Key(byte[] encoded); ``` Reads the OpenPGP key from the specified * Encoded * . Both binary-formatted and ASCII-armored data are accepted. ```text public Key(string keyring, string userId); ``` Searches the * Keyring * for an OpenPGP key with a matching * UserId * . The UserId parameter can be any of the following: UserID, Fingerprint or KeyId. If * UserId * is set to "*" the first key will be used. ```text public Key(string keyring, string secretKeyringFile, string publicKeyringFile, string userId); ``` Searches the * Keyring * for the specified * SecretKeyRingFile * and * PublicKeyringFile * . If * UserId * is set to "*" the first key will be used. ```text public Key(byte[] encoded, string userId); ``` Searches the * Encoded * for an OpenPGP key with a matching * UserId * . If * UserId * is set to "*" the first key will be used. # Config Settings ([KeyMgr](#keymgr-component) Component) The component 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 component, access to these *internal properties* is provided through the [Config](#config-method-keymgr-component) method. ### KeyMgr Config Settings **AllowEmptyPassword**: Whether a key can be created without a password.This controls whether a password will be used to encrypt a key. When true, [CreateKey](#createkey-method-keymgr-component) will accept an empty string as the password, leaving the key unencrypted. The default is false. **Argon2Iterations**: Specifies the number of iterations used for Argon2.This configuration setting specifies the number of iterations performed when calling [CreateKey](#createkey-method-keymgr-component) 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 [CreateKey](#createkey-method-keymgr-component) 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 [CreateKey](#createkey-method-keymgr-component) is called and [UseArgon2](#UseArgon2) is set to *True*. The default value is *4*. Valid values range from 1 to 2^(24)-1. **ChangeSubkeyPassphrase**: Whether or not the passphrase for subkey's should be changed.This setting determines whether or not subkeys' passphrases should be changed when [ChangePassphrase](#changepassphrase-method-keymgr-component) is called. The default value is *True*. **CompatibilityProfile**: Specifies the OpenPGP compatibility profile used when creating keys.This setting specifies the OpenPGP compatibility profile used when creating keys via [CreateKey](#createkey-method-keymgr-component) and [CreateSubKey](#createsubkey-method-keymgr-component). 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 component generates; importing existing keys (via [ImportKey](#importkey-method-keymgr-component) or [ImportKeyB](#importkeyb-method-keymgr-component)) supports both RFC 9580 and LibrePGP formats regardless of this setting. This same setting is also available in the [OpenPGP](OpenPGP.md#OpenPGP) component, where it controls the format of encrypted and signed messages rather than keys. See the [OpenPGP](OpenPGP.md#OpenPGP) components *CompatibilityProfile* setting for details. **ContinueOnInvalidKey**: Whether to continue loading the keyring when an invalid key is found.This setting determines whether the component will continue loading keys when an invalid key is found. This is applicable when calling [LoadKeyring](#loadkeyring-method-keymgr-component). If set to False (default) the component throws an exception. If set to True the component will fire the [Error](#error-event-keymgr-component) 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 component will additionally create a subkey marked for encryption when calling [CreateKey](#createkey-method-keymgr-component) 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 [UsageFlags](#Key_f_UsageFlags). **Curve**: The elliptic curve used when creating a key.This configuration setting specifies the curve to use when calling [CreateKey](#createkey-method-keymgr-component). 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 component 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 component 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 component 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 [Curve](#Key_f_Curve) used by the key. When this setting is enabled (default) the component 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 component will automatically select a valid hash algorithm based on the curve as follows: | Curve | Hash Algorithm | | --- | --- | | secp256r1 | SHA256 | | secp384r1 | SHA384 | | secp521r1 | SHA512 | | secp256k1 | SHA256 | **ImportAllKeys**: Whether or not to import all keys found in a key file.When calling [ImportKey](#importkey-method-keymgr-component) with a *UserId* parameter of "*" or "", the component will import all keys found in the file if this property is set to True (default). If this is set to False when the *UserId* parameter of [ImportKey](#importkey-method-keymgr-component) is set to "*" or "", only the first key found in the file will be imported. The default value is True. **KeyBoxProtectionMode**: Specifies the keybox protection mode used when saving a keyring.This configuration setting specifies the keybox protection mode used when calling [SaveKeyring](#savekeyring-method-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component). 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 [Id](#Key_f_Id) field 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](#key-property-keymgr-component). 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](#key-property-keymgr-component). 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](#key-property-keymgr-component). 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](#key-property-keymgr-component). This configuration setting is read-only. This configuration setting will return a comma-separated list of the key's preferred symmetric algorithms. For example: *"AES256, AES192, AES128, Blowfish, Twofish, IDEA, TripleDES, CAST5"* **KeyringFormat**: Specifies the keyring format to use when saving a keyring.This configuration setting specifies the keyring format to use when calling [SaveKeyring](#savekeyring-method-keymgr-component). 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](#key-property-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component) 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 component 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 [CreateKey](#createkey-method-keymgr-component) operation, it is only used by [CreateSubKey](#createsubkey-method-keymgr-component). **KeyValidityTime**: The validity period for the key being created.When [CreateKey](#createkey-method-keymgr-component) 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 [CreateKey](#createkey-method-keymgr-component). 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 [Status](#status-event-keymgr-component) event. Possible values are: | | | | --- | --- | | 0 (None) | No events are logged. | | 1 (Info - default) | Informational events are logged. | | 2 (Verbose) | Detailed data is logged. | | 3 (Debug) | Debug data is logged. | **PreferredAEADAlgorithms**: Specifies a key's preferred AEAD encryption algorithms when creating a key.This configuration setting is used to specify a key's preferred AEAD encryption algorithms when calling [CreateKey](#createkey-method-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component). By default, this config will be set to *automatic* and the component 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 component 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 [CreateKey](#createkey-method-keymgr-component). 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 [CreateKey](#createkey-method-keymgr-component). 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 [Revoked](#Key_f_Revoked) is True. This may be set before calling [RevokeKey](#revokekey-method-keymgr-component) 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 [Revoked](#Key_f_Revoked) is True. This may be set before calling [RevokeKey](#revokekey-method-keymgr-component) and may be queried after importing and selecting a revoked key. The default value is an empty string. **Revoker**: The revoker's key Id.This setting returns the key Id of the designated revoker associated with this key. This will only be present if a separate revoker was added to the key (for instance by calling [AddRevoker](#addrevoker-method-keymgr-component)). 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 [CreateKey](#createkey-method-keymgr-component), [AddUserId](#adduserid-method-keymgr-component), [SignUserId](#signuserid-method-keymgr-component), [AddRevoker](#addrevoker-method-keymgr-component), or [ChangeExpirationDate](#changeexpirationdate-method-keymgr-component). 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 [SignUserId](#signuserid-method-keymgr-component). - The 0x1F Direct-Key Signature created during [CreateKey](#createkey-method-keymgr-component) when [KeyVersion](#KeyVersion) is *6*. - The 0x1F Direct-Key Signature created by [AddRevoker](#addrevoker-method-keymgr-component). - The v6 0x1F Direct-Key Signature, and User Id certification signatures, regenerated by [ChangeExpirationDate](#changeexpirationdate-method-keymgr-component). 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 [CreateSubKey](#createsubkey-method-keymgr-component), and when [CreateKey](#createkey-method-keymgr-component) automatically creates an encryption subkey (see [KeyUsage](#KeyUsage) for details). The default value is an empty string, in which case the component will automatically select an appropriate algorithm based on the primary key's algorithm and the usage of the subkey being created. When calling [CreateSubKey](#createsubkey-method-keymgr-component), the usage is specified by [SubKeyUsage](#SubKeyUsage). When [CreateKey](#createkey-method-keymgr-component) 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 [CreateKey](#createkey-method-keymgr-component) and [PublicKeyAlgorithm](#PublicKeyAlgorithm) is set to *ECDSA*, *EdDSA*, *Ed25519*, or *Ed448*, and [SubKeyAlgorithm](#SubKeyAlgorithm) is unspecified. 2. When calling [CreateKey](#createkey-method-keymgr-component) or [CreateSubKey](#createsubkey-method-keymgr-component) 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 [CreateKey](#createkey-method-keymgr-component), or creating subkeys with [CreateSubKey](#createsubkey-method-keymgr-component). 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 [CreateSubKey](#createsubkey-method-keymgr-component) 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 [CreateSubKey](#createsubkey-method-keymgr-component). It does not affect the usage of the subkey that [CreateKey](#createkey-method-keymgr-component) 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 [CreateKey](#createkey-method-keymgr-component) 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 [ExportPublicKey](#exportpublickey-method-keymgr-component) 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. **GUIAvailable**: Whether or not a message loop is available for processing events.In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation. In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting [GUIAvailable](#GUIAvailable) to *false* will ensure that the component does not attempt to process external events. **LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a component 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*. **UseFIPSCompliantAPI**: Tells the component whether or not to use FIPS certified APIs.When set to *true*, the component will utilize the underlying operating system's certified APIs. Java editions, regardless of OS, utilize Bouncy Castle Federal Information Processing Standards (FIPS), while all other Windows editions make use of Microsoft security libraries. FIPS mode can be enabled by setting the *UseFIPSCompliantAPI* configuration setting to *true*. This is a static setting that applies to all instances of all components of the toolkit within the process. It is recommended to enable or disable this setting once before the component has been used to establish a connection. Enabling FIPS while an instance of the component is active and connected may result in unexpected behavior. For more details, please see the [FIPS 140-2 Compliance](https://www.nsoftware.com/kb/articles/fips.rst) article. NOTE: This setting is applicable only on Windows. NOTE: Enabling FIPS compliance requires a special license; please contact [sales@nsoftware.com](mailto:sales@nsoftware.com) for details. **UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments, this is not desirable. To use a completely managed security implementation, set this setting to *true*. Setting this configuration setting to *true* tells the component 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. NOTE: This setting is static. The value set is applicable to all components used in the application. When this value is set, the product's system dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file. # Trappable Errors ([KeyMgr](#keymgr-component) Component) ### 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. |