KeyMgr Component
Properties Methods Events Config Settings Errors
The KeyMgr component is used to create and manage OpenPGP keys.
Syntax
nsoftware.IPWorksEncrypt.Keymgr
Remarks
The KeyMgr component can be used to perform a variety of key-related actions. You can create, delete, import, export, and manage keys. Both individual keys and keyrings can be created and used.
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.
AddRevoker | Adds a designated revoker to the key. |
AddUserId | Adds the specified user Id to the current key. |
ChangeExpirationDate | Changes the expiration date of the key. |
ChangePassphrase | Changes the passphrase of the current key. |
Config | Sets or retrieves a configuration setting. |
CreateKey | Creates an OpenPGP key pair. |
CreateSubKey | Creates a new subkey. |
DeleteKey | Deletes the specified key. |
ExportPublicKey | Exports the public key of the current key. |
ExportSecretKey | Exports the private key of the current key. |
ImportKey | Imports the key specified by UserId to the current keyring. |
ImportKeyB | Imports the key specified by UserId to the current keyring. |
ListKeys | Lists keys in the specified Keyring . |
ListSignatures | Lists all signatures of the current key. |
ListSubkeys | Lists the subkeys of the currently selected key. |
LoadKeyring | Loads the keyring from disk. |
LoadKeyringB | Loads the keyring from SecretKeyringData and PublicKeyringData . |
Reset | Resets the component properties. |
RevokeKey | Revokes the specified key. |
SaveKeyring | Saves the current Keyring to disk. |
SignUserId | Signs the specified user Id of the current key. |
VerifyPassphrase | 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 | Fired when information is available about errors during data delivery. |
KeyList | Fires for each key in the keyring when ListKeys is called. |
KeyPassphrase | Fired if the passphrase of current key is incorrect or empty. |
SignatureList | Fires for each signature of the current key when ListSignatures is called. |
Status | Shows the progress of the operation. |
SubkeyList | Fires once for each subkey listed when ListSubkeys 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 | Whether a key can be created without a password. |
ChangeSubkeyPassphrase | Whether or not the passphrase for subkey's should be changed. |
ContinueOnInvalidKey | Whether to continue loading the keyring when an invalid key is found. |
CreateRSASubkeyforEncrypt | Whether to create a subkey when creating an RSA key. |
CurrentKeyPrimaryKeyUsageFlags | The usage flags of the currently selected primary key. |
Curve | The elliptic curve used when calling CreateKey. |
DSAPublicSubKeyLength | Specifies the public subkey length when creating a DSA key. |
EnsureValidDSASignatureHashAlgorithm | Whether or not to select a suitable signature hash algorithm automatically. |
ImportAllKeys | Whether or not to import all keys found in a key file. |
KeyEncryptionAlgorithm | The encryption algorithm used when creating a key. |
KeyIdLength | Specifies the length of the key's Id. |
KeyringFormat | Which format of keyring to use. |
KeyUsage | Flags that show intended use for the key being created. |
KeyValidityTime | The validity period for the key being created. |
LogLevel | Specifies the level of detail that is logged. |
PublicKeyAlgorithm | The public key algorithm for the key being created. |
PublicKeyLength | Specifies the public key length when creating a key. |
PublicKeyringFile | The file name of the public keyring file. |
PublicKeySignatureHashAlgorithm | The public key signature hash algorithm used when creating a key. |
RawKeyData | Returns detailed key and keyring data for debugging purposes. |
RevocationCode | The reason why the key was revoked. |
RevocationReason | Text describing why the key was revoked. |
Revoker | The revoker's key Id. |
SecretKeyringFile | The file name of the secret keyring file. |
SubKeyAlgorithm | The subkey algorithm for the subkey being created. |
SubKeyCurve | The elliptic curve of the sub key. |
SubKeyUsage | Flags that show intended use for the subkey being created. |
UseFipsCompliantAlgorithms | Restricts the usage to FIPS compliant algorithms only. |
VersionHeader | The Version header value in ASCII armored public keys. |
BuildInfo | Information about the product's build. |
GUIAvailable | Whether or not a message loop is available for processing events. |
LicenseInfo | Information about the current license. |
MaskSensitive | Whether sensitive data is masked in log messages. |
UseInternalSecurityAPI | Whether or not to use the system security libraries or an internal implementation. |
Key Property (KeyMgr Component)
The currently selected key.
Syntax
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.
Please refer to the Key type for a complete list of fields.Keyring Property (KeyMgr Component)
The location on disk of the keyring.
Syntax
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
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>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
AddUserId Method (KeyMgr Component)
Adds the specified user Id to the current key.
Syntax
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>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
ChangeExpirationDate Method (KeyMgr Component)
Changes the expiration date of the key.
Syntax
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
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
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
Remarks
This method creates a new OpenPGP key pair. The UserId parameter specifies the user Id of the key.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
Additional configuration settings may be set to further configure the details of the key being created. Please see the following settings for details:
- KeyEncryptionAlgorithm
- KeyUsage
- KeyValidityTime
- PublicKeyLength
- PublicKeyAlgorithm
- PublicKeySignatureHashAlgorithm
- Curve
- SubKeyCurve
CreateSubKey Method (KeyMgr Component)
Creates a new subkey.
Syntax
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:
DeleteKey Method (KeyMgr Component)
Deletes the specified key.
Syntax
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:
Id Type | Example |
UserId | FirstName LastName <user@mail.com> |
UserId (name only) | FirstName LastName |
UserId (first name only) | FirstName |
UserId (email only) | user@mail.com |
Short KeyId | 89C9D7B1 |
Long KeyId | F7B7D49C89C9D7B1 |
ExportPublicKey Method (KeyMgr Component)
Exports the public key of the current key.
Syntax
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
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
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
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
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
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
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
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
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
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
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.
SaveKeyring Method (KeyMgr Component)
Saves the current Keyring to disk.
Syntax
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
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
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
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
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>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
KeyId is the hex-encoded, 4-byte or 8-byte Id of the key. It is the same as the last 4 or 8 bytes of the Fingerprint. For instance:
BF52A0AB
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
PublicKeyLength is the length of the public key. Common values are 512, 1024, and 2048. If the PublicKeyAlgorithm is ECDSA or EdDSA the length of the public key is determined by the Curve. Possible lengths are:
Curve | Public Key Length (bits) |
secp256r1 | 256 |
secp384r1 | 384 |
secp521r1 | 521 |
Ed25519 | 256 |
secp256k1 | 256 |
Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA or EdDSA. Possible values are:
Value | PublicKeyAlgorithm | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
Ed25519 | EdDSA | Ed25519 |
secp256k1 | EdDSA | Secp256k1 |
KeyPassphrase Event (KeyMgr Component)
Fired if the passphrase of current key is incorrect or empty.
Syntax
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 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 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:
When using the OpenPGP component, or an email-based component, the following methods require a passphrase for the key:
- Decrypt
- Sign
- SignAndEncrypt
SignatureList Event (KeyMgr Component)
Fires for each signature of the current key when ListSignatures is called.
Syntax
public event OnSignatureListHandler OnSignatureList; public delegate void OnSignatureListHandler(object sender, KeymgrSignatureListEventArgs e); public class KeymgrSignatureListEventArgs : EventArgs { public string UserId { 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 UserId 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.
UserId holds the current user Id of the key.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
IssuerKeyId is the hex-encoded, 4- or-8-byte Id of the issuer's key. It is the same as the last 4 or 8 bytes of the Fingerprint. For instance: BF52A0AB
IssuerUserId is the user Id of the issuer. If this is empty 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
Curve is the curve used by the key when PublicKeyAlgorithm is ECDSA or EdDSA. Possible values are:
Value | PublicKeyAlgorithm | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
Ed25519 | EdDSA | Ed25519 |
secp256k1 | EdDSA | Secp256k1 |
HashAlgorithm is the hash algorithm used by the signature. Possible values are:
- SHA1
- SHA256
- SHA384
- SHA512
- SHA224
- MD5
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 Component)
Shows the progress of the operation.
Syntax
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
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. It is the same as the last 4 or 8 bytes of the Fingerprint. For instance:
BF52A0AB
Fingerprint holds the hex-encoded, 20-byte fingerprint of the key. This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
PublicKeyAlgorithm is the public key algorithm. Possible values are:
- RSA
- Elgamal
- ECDH (Only used with ECDSA and EdDSA keys)
PublicKeyLength is the length of the public key. Common values are 512, 1024, and 2048.
Curve is the curve used by the key when PublicKeyAlgorithm is ECDH. Possible values are:
Value | Description |
secp256r1 | NIST curve P-256 |
secp384r1 | NIST curve P-384 |
secp521r1 | NIST curve P-521 |
Curve25519 | Curve25519 |
Ed25519 | Ed25519 |
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.
Fields
Curve
string (read-only)
Default Value: ""
This field specifies the elliptic curve used in the ECDSA or EdDSA key. This field is only applicable if PublicKeyAlgorithm is ECDSA or EdDSA. Possible values are:
Value | PublicKeyAlgorithm | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
Ed25519 | EdDSA | Ed25519 |
secp256k1 | EdDSA | Secp256k1 |
EffectiveDate
string (read-only)
Default Value: ""
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.
Encoded
string
Default Value: ""
The key. This field is used to assign a specific key. The UserId fields may also be used to specify a key.
EncodedB
byte []
Default Value: ""
The key. This field is used to assign a specific key. The UserId fields may also be used to specify a key.
ExpirationDate
string (read-only)
Default Value: ""
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.
Fingerprint
string (read-only)
Default Value: ""
The hex-encoded, 20-byte fingerprint of the key.
This is in the form:
5E70662EA810E768391A2FE8F7B7D49C89C9D7B1
Id
string (read-only)
Default Value: ""
The hex-encoded, 4-byte key Id. It is same as last 4 bytes of Fingerprint.
This is in the form:
89C9D7B1The KeyIdLength setting may be set to a value of 8 to return the last 8 bytes instead of the last 4 bytes.
OtherUserIds
string (read-only)
Default Value: ""
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 Value: ""
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 Value: ""
The public key of the key. The key is provided as ASCII armored data.
PublicKeyAlgorithm
string (read-only)
Default Value: ""
A text description of the public key algorithm of the key. Possible values are:
- RSA
- DSA
- ECDSA
- EdDSA
- RSA-Legacy
PublicKeyLength
int (read-only)
Default Value: 0
The length of the public key in bits. Common values are 512, 1024, and 2048.
If the PublicKeyAlgorithm field is ECDSA or EcDSA the length of the public key is determined by the Curve. Possible lenghts are:
Curve | Public Key Length (bits) |
secp256r1 | 256 |
secp384r1 | 384 |
secp521r1 | 521 |
Ed25519 | 256 |
secp256k1 | 256 |
Revoked
bool (read-only)
Default Value: False
Whether or not the key is revoked.
SecretKey
string (read-only)
Default Value: ""
The secret key of the key (if available). The key is provided as ASCII armored data.
SecretKeyAvailable
bool (read-only)
Default Value: False
Whether or not a secret key is available for the selected key.
Usage
string (read-only)
Default Value: ""
A text 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
int (read-only)
Default Value: 47
Flags that show the intended use for the key. The default value is 0x0F. The value of 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 field for a text representation of UsageFlags.
UserId
string
Default Value: ""
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. When this field is set the component will search the 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 after loading the key.
The UserId format is:
FirstName LastName (Comment) <Email>Not all values are required when selecting or generating a key, but at least FirstName or Email are required.
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.
Constructors
Reads the OpenPGP public key from the specified KeyPath . If multiple keys are present only the first one is used.
Reads the OpenPGP key from the specified KeyData . Both binary-formatted and ASCII-armored data are accepted.
Searches the KeyPath for an OpenPGP key with a matching UserId . If UserId is set to "*" the first key will be used.
Searches the KeyPath for the specified SecretKeyRingFile and PublicKeyringFile . If UserId is set to "*" the first key will be used.
Searches the KeyData for an OpenPGP key with a matching UserId . If UserId is set to "*" the first key will be used.
Config Settings (KeyMgr 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 method.KeyMgr Config Settings
Value | PublicKeyAlgorithm | Description |
secp256r1 | ECDSA | NIST curve P-256 |
secp384r1 | ECDSA | NIST curve P-384 |
secp521r1 | ECDSA | NIST curve P-521 |
Ed25519 | EdDSA | Ed25519 |
secp256k1 | EdDSA | Secp256k1 |
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 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 |
keymgr1.Config("KeyringFormat=2");
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.
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. |
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. |
- RSA
- DSA
- ECDSA
- EdDSA
- RSA-Legacy
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.
Note: When creating a DSA key only PublicKeyLength values of 512 and 1024 are supported. Additionally the PublicKeySignatureHashAlgorithm value "MD5" is not supported with DSA keys.
ECDSA and EdDSA Notes
When creating an ECDSA or EdDSA key the PublicKeyLength value is automatically determined based on the Curve. The Curve and SubKeyCurve settings is also applicable.
If Curve and SubKeyCurve are not specified the following defaults will be used:
PublicKeyAlgorithm | Default Curve |
ECDSA | secp256r1 |
EdDSA | Ed2519 |
When PublicKeyAlgorithm is set to ECDSA or EdDSA this setting is not applicable and the public key length is automatically determined based on the Curve selected. The public key length values are as follows:
Curve | Public Key Length (bits) |
secp256r1 | 256 |
secp384r1 | 384 |
secp521r1 | 521 |
Ed25519 | 256 |
secp256k1 | 256 |
- SHA1
- MD5
- SHA256 (default)
- SHA384
- SHA512
- SHA224
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 |
Key Algorithm | Supported Operations |
RSA | Sign and Encrypt |
DSA | Sign |
ElGamal | Encrypt |
ECDSA | Sign |
EdDSA | Sign |
ECDH | Encrypt |
Value | Description |
secp256r1 | NIST curve P-256 |
secp384r1 | NIST curve P-384 |
secp521r1 | NIST curve P-521 |
Curve25519 | Curve25519 |
Ed25519 | Ed25519 |
Note: It is valid to specify the subkey curve of Curve25519 when Curve is set to secp256r1, secp384r1, or secp521r1. It is also valid to set a subkey curve of secp256r1, secp384r1, or secp521r1 when Curve is set to Ed25519.
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. |
- 3DES
- AES128
- AES192
- AES256
- RSA
- DSA
- SHA1
- SHA256
- SHA384
- SHA512
- SHA224
Base Config Settings
In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.
- 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.
This setting only works on these components: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.
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.
If using the .NET Standard Library, this setting will be true on all platforms. The .NET Standard library does not support using the system security libraries.
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 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. |