KeyMgr Component

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

nsoftware.IPWorksOpenPGP.KeyMgr

Remarks

The KeyMgr component supports key management according to the specifications outlined in RFC 4880, in addition to RFC 9580, which introduces support for OpenPGP Version 6. You can create, delete, import, export, and manage keys, including both individual keys and keyrings.

Property List

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

Method List

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

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.

Config Settings

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

Key Property (KeyMgr Component)

The currently selected key.

Syntax

• C#
• VB.NET

public Key Key { get; set; }

Public Property Key As Key

Remarks

This property holds the currently selected key. It is populated after calling ImportKey or after setting Keyring. 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.

Keyring Property (KeyMgr Component)

The location on disk of the keyring.

Syntax

• C#
• VB.NET

public string Keyring { get; }

Public ReadOnly Property Keyring As String

Default Value

""

Remarks

To load a keyring use the LoadKeyring method.

This property is read-only.

AddRevoker Method (KeyMgr Component)

Adds a designated revoker to the key.

Syntax

• C#
• VB.NET

public void AddRevoker(string userId);

Async Version
public async Task AddRevoker(string userId);
public async Task AddRevoker(string userId, CancellationToken cancellationToken);

Public Sub AddRevoker(ByVal UserId As String)

Async Version
Public Sub AddRevoker(ByVal UserId As String) As Task
Public Sub AddRevoker(ByVal UserId As String, cancellationToken As CancellationToken) As Task

Remarks

This method adds a designated revoker to the selected Key. The UserId parameter specifies the revoker to add. The revoker's key must be present in the current keyring. Use this with caution: once added, a revoker cannot be removed. The key's passphrase is required for this operation and may be specified via Passphrase or through the KeyPassphrase event.

The UserId format is:

FirstName LastName (Comment) <Email>

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

AddUserId Method (KeyMgr Component)

Adds the specified user Id to the current key.

Syntax

• C#
• VB.NET

public void AddUserId(string userId);

Async Version
public async Task AddUserId(string userId);
public async Task AddUserId(string userId, CancellationToken cancellationToken);

Public Sub AddUserId(ByVal UserId As String)

Async Version
Public Sub AddUserId(ByVal UserId As String) As Task
Public Sub AddUserId(ByVal UserId As String, cancellationToken As CancellationToken) As Task

Remarks

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

The UserId format is:

FirstName LastName (Comment) <Email>

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

ChangeExpirationDate Method (KeyMgr Component)

Changes the expiration date of the key.

Syntax

• C#
• VB.NET

public void ChangeExpirationDate(int expirationDate);

Async Version
public async Task ChangeExpirationDate(int expirationDate);
public async Task ChangeExpirationDate(int expirationDate, CancellationToken cancellationToken);

Public Sub ChangeExpirationDate(ByVal ExpirationDate As Integer)

Async Version
Public Sub ChangeExpirationDate(ByVal ExpirationDate As Integer) As Task
Public Sub ChangeExpirationDate(ByVal ExpirationDate As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method changes the expiration date of the current Key. The ExpirationDate parameter specifies the number of days for which the key is valid starting today. For instance a value of "31" means the key is valid for the next 31 days.

The special value "0" means the key will never expire.

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

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

ChangePassphrase Method (KeyMgr Component)

Changes the passphrase of the current key.

Syntax

• C#
• VB.NET

public void ChangePassphrase(string passphrase);

Async Version
public async Task ChangePassphrase(string passphrase);
public async Task ChangePassphrase(string passphrase, CancellationToken cancellationToken);

Public Sub ChangePassphrase(ByVal Passphrase As String)

Async Version
Public Sub ChangePassphrase(ByVal Passphrase As String) As Task
Public Sub ChangePassphrase(ByVal Passphrase As String, cancellationToken As CancellationToken) As Task

Remarks

The Passphrase parameter specifies the new passphrase.

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

Config Method (KeyMgr Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings 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, you must call Config("PROPERTY"). The value will be returned as a string.

CreateKey Method (KeyMgr Component)

Creates an OpenPGP key pair.

Syntax

• C#
• VB.NET

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);

Public Sub CreateKey(ByVal UserId As String, ByVal Passphrase As String)

Async Version
Public Sub CreateKey(ByVal UserId As String, ByVal Passphrase As String) As Task
Public Sub CreateKey(ByVal UserId As String, ByVal Passphrase As String, cancellationToken As CancellationToken) As Task

Remarks

This method creates a new OpenPGP key pair. The UserId parameter specifies the user Id of the key. If KeyVersion is 6, this parameter may be an empty string.

The UserId format is:

FirstName LastName (Comment) <Email>

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

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

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

CreateSubKey Method (KeyMgr Component)

Creates a new subkey.

Syntax

• C#
• VB.NET

public void CreateSubKey();

Async Version
public async Task CreateSubKey();
public async Task CreateSubKey(CancellationToken cancellationToken);

Public Sub CreateSubKey()

Async Version
Public Sub CreateSubKey() As Task
Public Sub CreateSubKey(cancellationToken As CancellationToken) As Task

Remarks

This method creates a new subkey. Before calling this method the Key property must be set to a valid private key.

The following settings may optionally be set to define specific values for the created subkey:

• KeyValidityTime
• PublicKeyLength
• SubKeyAlgorithm
• SubKeyLength
• SubKeyCurve
• SubKeyUsage

DeleteKey Method (KeyMgr Component)

Deletes the specified key.

Syntax

• C#
• VB.NET

public void DeleteKey(string userId);

Async Version
public async Task DeleteKey(string userId);
public async Task DeleteKey(string userId, CancellationToken cancellationToken);

Public Sub DeleteKey(ByVal UserId As String)

Async Version
Public Sub DeleteKey(ByVal UserId As String) As Task
Public Sub DeleteKey(ByVal UserId As String, cancellationToken As CancellationToken) As Task

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:

ExportPublicKey Method (KeyMgr Component)

Exports the public key of the current key.

Syntax

• C#
• VB.NET

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);

Public Sub ExportPublicKey(ByVal FileName As String, ByVal useAsciiArmor As Boolean)

Async Version
Public Sub ExportPublicKey(ByVal FileName As String, ByVal useAsciiArmor As Boolean) As Task
Public Sub ExportPublicKey(ByVal FileName As String, ByVal useAsciiArmor As Boolean, cancellationToken As CancellationToken) As Task

Remarks

This method exports the public key of the currently selected Key. The FileName parameter specifies the file on disk to which the public key will be written. The UseAsciiArmor parameter determines whether or not ASCII armoring is used when writing the key to disk.

Note: When UseAsciiArmor is set to True the VersionHeader setting may also be set to specify your own header value.

ExportSecretKey Method (KeyMgr Component)

Exports the private key of the current key.

Syntax

• C#
• VB.NET

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);

Public Sub ExportSecretKey(ByVal FileName As String, ByVal useAsciiArmor As Boolean)

Async Version
Public Sub ExportSecretKey(ByVal FileName As String, ByVal useAsciiArmor As Boolean) As Task
Public Sub ExportSecretKey(ByVal FileName As String, ByVal useAsciiArmor As Boolean, cancellationToken As CancellationToken) As Task

Remarks

This method exports the private key of the currently selected Key. The FileName parameter specifies the file on disk that the private key will be written to. The UseAsciiArmor parameter determines whether or not ASCII armoring is used when writing the key to disk.

ImportKey Method (KeyMgr Component)

Imports the key specified by UserId to the current keyring.

Syntax

• C#
• VB.NET

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);

Public Sub ImportKey(ByVal FileName As String, ByVal UserId As String)

Async Version
Public Sub ImportKey(ByVal FileName As String, ByVal UserId As String) As Task
Public Sub ImportKey(ByVal FileName As String, ByVal UserId As String, cancellationToken As CancellationToken) As Task

Remarks

This method imports the key specified by UserId from the key file specified by FileName into the current Keyring. The imported key will be automatically selected and available in the Key property.

If the FileName specifies a key file which contains multiple keys only the key belonging to UserId will be imported.

If UserId is set to "*" or "" (empty string) all keys in the key file will be imported. The ImportAllKeys setting controls the behavior of the component in this case.

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

ImportKeyB Method (KeyMgr Component)

Imports the key specified by UserId to the current keyring.

Syntax

• C#
• VB.NET

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);

Public Sub ImportKeyB(ByVal Data As String, ByVal UserId As String)

Async Version
Public Sub ImportKeyB(ByVal Data As String, ByVal UserId As String) As Task
Public Sub ImportKeyB(ByVal Data As String, ByVal UserId As String, cancellationToken As CancellationToken) As Task

Remarks

This method imports the key specified by UserId from the key data specified by Data into the current Keyring. The imported key will be automatically selected and available in the Key property.

If the Data specifies key data that contains multiple keys only the key belonging to UserId will be imported.

If UserId is set to "*" or "" (empty string) all keys in the key data will be imported. The ImportAllKeys setting controls the behavior of the component in this case.

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

ListKeys Method (KeyMgr Component)

Lists keys in the specified Keyring .

Syntax

• C#
• VB.NET

public string ListKeys();

Async Version
public async Task<string> ListKeys();
public async Task<string> ListKeys(CancellationToken cancellationToken);

Public Function ListKeys() As String

Async Version
Public Function ListKeys() As Task(Of String)
Public Function ListKeys(cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

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

ListSignatures Method (KeyMgr Component)

Lists all signatures of the current key.

Syntax

• C#
• VB.NET

public string ListSignatures();

Async Version
public async Task<string> ListSignatures();
public async Task<string> ListSignatures(CancellationToken cancellationToken);

Public Function ListSignatures() As String

Async Version
Public Function ListSignatures() As Task(Of String)
Public Function ListSignatures(cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

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

ListSubkeys Method (KeyMgr Component)

Lists the subkeys of the currently selected key.

Syntax

• C#
• VB.NET

public string ListSubkeys();

Async Version
public async Task<string> ListSubkeys();
public async Task<string> ListSubkeys(CancellationToken cancellationToken);

Public Function ListSubkeys() As String

Async Version
Public Function ListSubkeys() As Task(Of String)
Public Function ListSubkeys(cancellationToken As CancellationToken) As Task(Of String)

Remarks

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

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

LoadKeyring Method (KeyMgr Component)

Loads the keyring from disk.

Syntax

• C#
• VB.NET

public void LoadKeyring(string keyringPath);

Async Version
public async Task LoadKeyring(string keyringPath);
public async Task LoadKeyring(string keyringPath, CancellationToken cancellationToken);

Public Sub LoadKeyring(ByVal KeyringPath As String)

Async Version
Public Sub LoadKeyring(ByVal KeyringPath As String) As Task
Public Sub LoadKeyring(ByVal KeyringPath As String, cancellationToken As CancellationToken) As Task

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 property with the first key found in the keyring. Set UserId to select a different key in the current keyring.

LoadKeyringB Method (KeyMgr Component)

Loads the keyring from SecretKeyringData and PublicKeyringData .

Syntax

• C#
• VB.NET

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);

Public Sub LoadKeyringB(ByVal SecretKeyringData As String, ByVal PublicKeyringData As String)

Async Version
Public Sub LoadKeyringB(ByVal SecretKeyringData As String, ByVal PublicKeyringData As String) As Task
Public Sub LoadKeyringB(ByVal SecretKeyringData As String, ByVal PublicKeyringData As String, cancellationToken As CancellationToken) As Task

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 property with the first key found in the keyring. Set UserId to select a different key in the current keyring.

Reset Method (KeyMgr Component)

Resets the component properties.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

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

RevokeKey Method (KeyMgr Component)

Revokes the specified key.

Syntax

• C#
• VB.NET

public string RevokeKey(string keyId);

Async Version
public async Task<string> RevokeKey(string keyId);
public async Task<string> RevokeKey(string keyId, CancellationToken cancellationToken);

Public Function RevokeKey(ByVal KeyId As String) As String

Async Version
Public Function RevokeKey(ByVal KeyId As String) As Task(Of String)
Public Function RevokeKey(ByVal KeyId As String, cancellationToken As CancellationToken) As Task(Of String)

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

Before calling this method a key must be selected and available in the Key property.

The KeyId may be the Id of the main key or a subkey. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's Fingerprint. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's Fingerprint instead. For instance:

5E70662EA810E768

SaveKeyring Method (KeyMgr Component)

Saves the current Keyring to disk.

Syntax

• C#
• VB.NET

public void SaveKeyring(string keyringPath);

Async Version
public async Task SaveKeyring(string keyringPath);
public async Task SaveKeyring(string keyringPath, CancellationToken cancellationToken);

Public Sub SaveKeyring(ByVal KeyringPath As String)

Async Version
Public Sub SaveKeyring(ByVal KeyringPath As String) As Task
Public Sub SaveKeyring(ByVal KeyringPath As String, cancellationToken As CancellationToken) As Task

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 Component)

Signs the specified user Id of the current key.

Syntax

• C#
• VB.NET

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);

Public Sub SignUserId(ByVal UserId As String, ByVal IssuerUserId As String)

Async Version
Public Sub SignUserId(ByVal UserId As String, ByVal IssuerUserId As String) As Task
Public Sub SignUserId(ByVal UserId As String, ByVal IssuerUserId As String, cancellationToken As CancellationToken) As Task

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

VerifyPassphrase Method (KeyMgr Component)

Verifies the passphrase of specified key.

Syntax

• C#
• VB.NET

public bool VerifyPassphrase(string passphrase);

Async Version
public async Task<bool> VerifyPassphrase(string passphrase);
public async Task<bool> VerifyPassphrase(string passphrase, CancellationToken cancellationToken);

Public Function VerifyPassphrase(ByVal Passphrase As String) As Boolean

Async Version
Public Function VerifyPassphrase(ByVal Passphrase As String) As Task(Of Boolean)
Public Function VerifyPassphrase(ByVal Passphrase As String, cancellationToken As CancellationToken) As Task(Of Boolean)

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 Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, KeyMgrErrorEventArgs e);

public class KeyMgrErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As KeyMgrErrorEventArgs)

Public Class KeyMgrErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

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

KeyList Event (KeyMgr Component)

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

Syntax

• C#
• VB.NET

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; }
}

Public Event OnKeyList As OnKeyListHandler

Public Delegate Sub OnKeyListHandler(sender As Object, e As KeyMgrKeyListEventArgs)

Public Class KeyMgrKeyListEventArgs Inherits EventArgs
  Public ReadOnly Property UserId As String
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public ReadOnly Property HasSecretKey As Boolean
  Public ReadOnly Property PublicKeyAlgorithm As String
  Public ReadOnly Property PublicKeyLength As Integer
  Public ReadOnly Property Curve As String
End Class

Remarks

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

UserId holds the current user Id of the key.

The UserId format is:

FirstName LastName (Comment) <Email>

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

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

5E70662EA810E768

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

HasSecretKey returns True if the key contains a secret key.

PublicKeyAlgorithm is the public key algorithm. Possible values are:

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

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

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

KeyPassphrase Event (KeyMgr Component)

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

Syntax

• C#
• VB.NET

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; }
}

Public Event OnKeyPassphrase As OnKeyPassphraseHandler

Public Delegate Sub OnKeyPassphraseHandler(sender As Object, e As KeyMgrKeyPassphraseEventArgs)

Public Class KeyMgrKeyPassphraseEventArgs Inherits EventArgs
  Public ReadOnly Property UserId As String
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public Property Passphrase As String
End Class

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

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

UserId holds the user Id of the key the passphrase is required for.

The UserId format is:

FirstName LastName (Comment) <Email>

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

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

5E70662EA810E768

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

SignatureList Event (KeyMgr Component)

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

Syntax

• C#
• VB.NET

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; }
}

Public Event OnSignatureList As OnSignatureListHandler

Public Delegate Sub OnSignatureListHandler(sender As Object, e As KeyMgrSignatureListEventArgs)

Public Class KeyMgrSignatureListEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public ReadOnly Property UserId As String
  Public ReadOnly Property IssuerFingerprint As String
  Public ReadOnly Property IssuerKeyId As String
  Public ReadOnly Property IssuerUserId As String
  Public ReadOnly Property PublicKeyAlgorithm As String
  Public ReadOnly Property Curve As String
  Public ReadOnly Property HashAlgorithm As String
  Public ReadOnly Property EffectiveDate As String
  Public ReadOnly Property SignatureClass As Integer
  Public ReadOnly Property ValidityStatus As Integer
End Class

Remarks

This event fires once for each signature of the current key when ListSignatures is called.

The KeyId, UserId, and Fingerprint parameters contain relevant information for the current key. Similarly, the IssuerKeyId, IssuerUserId, and IssuerFingerprint parameters contain relevant information for the issuer's key. The format of these parameters are described below.

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

5E70662EA810E768

UserId and IssuerUserId hold the user Id of the respective key. The UserId format is:

FirstName LastName (Comment) <Email>

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

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

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

PublicKeyAlgorithm is the public key algorithm. Possible values are:

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

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

HashAlgorithm is the hash algorithm used by the signature. Possible values are:

• SHA1
• MD5
• SHA256
• SHA384
• SHA512
• SHA224
• RIPEMD160
• SHA3-256
• SHA3-512

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

SignatureClass is the type of signature. Possible values are:

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

Status Event (KeyMgr Component)

Shows the progress of the operation.

Syntax

• C#
• VB.NET

public event OnStatusHandler OnStatus;

public delegate void OnStatusHandler(object sender, KeyMgrStatusEventArgs e);

public class KeyMgrStatusEventArgs : EventArgs {
  public string Message { get; }
}

Public Event OnStatus As OnStatusHandler

Public Delegate Sub OnStatusHandler(sender As Object, e As KeyMgrStatusEventArgs)

Public Class KeyMgrStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Message As String
End Class

Remarks

The event is fired for informational and logging purposes only. It may be used to track the progress of an operation.

The level of detail is controlled by the LogLevel setting.

SubkeyList Event (KeyMgr Component)

Fires once for each subkey listed when ListSubkeys is called.

Syntax

• C#
• VB.NET

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; }
}

Public Event OnSubkeyList As OnSubkeyListHandler

Public Delegate Sub OnSubkeyListHandler(sender As Object, e As KeyMgrSubkeyListEventArgs)

Public Class KeyMgrSubkeyListEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public ReadOnly Property PublicKeyAlgorithm As String
  Public ReadOnly Property PublicKeyLength As Integer
  Public ReadOnly Property Curve As String
  Public ReadOnly Property UsageFlags As Integer
  Public ReadOnly Property Usage As String
  Public ReadOnly Property EffectiveDate As String
  Public ReadOnly Property ExpirationDate As String
  Public ReadOnly Property Revoked As Boolean
End Class

Remarks

This event fires once for each subkey when ListSubkeys is called.

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

5E70662EA810E768

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

PublicKeyAlgorithm is the public key algorithm of the subkey. Possible values are:

• RSA
• DSA
• ElGamal
• ECDSA
• EdDSA
• ECDH
• Ed25519
• Ed448
• X25519
• X448

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

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

Usage is the textual description of UsageFlags.

The value will be of one or more of the following strings, separated by commas:

• Certifying Other Certificates
• Signing Emails and Files
• Encrypting Emails and Files
• Split Key
• Authenticate Against Servers
• Group Key

UsageFlags is an integer flag that shows the intended use for the key. The value is a combination of the following flags:

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

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

Revoked Indicates whether the subkey is revoked or not.

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.

Fields

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

5E70662EA810E768

FirstName LastName (Comment) <Email>

Constructors

• C#
• VB.NET

public Key(string keyring);

Public Key(ByVal Keyring As String)

• C#
• VB.NET

public Key(byte[] encoded);

Public Key(ByVal Encoded As Byte())

• C#
• VB.NET

public Key(string keyring, string userId);

Public Key(ByVal Keyring As String, ByVal UserId As String)

• C#
• VB.NET

public Key(string keyring, string secretKeyringFile, string publicKeyringFile, string userId);

Public Key(ByVal Keyring As String, ByVal SecretKeyringFile As String, ByVal PublicKeyringFile As String, ByVal UserId As String)

• C#
• VB.NET

public Key(byte[] encoded, string userId);

Public Key(ByVal Encoded As Byte(), ByVal UserId As String)

Config Settings (KeyMgr Component)

KeyMgr Config Settings

5E70662EA810E768

Base Config Settings

Trappable Errors (KeyMgr Component)

OpenPGP Errors