OpenPGP Component

Properties   Methods   Events   Config Settings   Errors  

The OpenPGP component is used to encrypt/decrypt and sign/verify PGP messages.

Syntax

nsoftware.IPWorksOpenPGP.OpenPGP

Remarks

The OpenPGP component supports encrypting/decrypting and signing/verifying OpenPGP messages. Supported message formats are specified by RFC 4880, in addition to RFC 9580, which introduces support for OpenPGP Version 6.

The Encrypt, Sign, and SignAndEncrypt methods are used to create a message to be sent to your partner. You can additionally create messages bound for multiple recipients with different keys, simultaneously encrypt and compress with the most popular compression algorithms, and control other aspects such as the encrypting algorithm to use.

When a message is received, the Decrypt, VerifySignature, and DecryptAndVerifySignature methods are used to process the incoming message.

The Keys property holds the key (with private key) used to sign and decrypt.

The SignerKeys property holds the key used to verify a signature.

The RecipientKeys property holds the key used to encrypt.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Property List

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

ASCIIArmorSpecifies whether to use ASCII armor to encode the output message.
AutoSelectAlgorithmsWhether to automatically select algorithms when encrypting or signing.
ClearSignatureSpecifies whether or not to create a cleartext signature.
CompressionMethodThe compression algorithm used.
DetachedSignatureSpecifies whether or not to generate a detached signature when signing a message.
EncryptingAlgorithmThe encryption algorithm used when encrypting.
InputFileThe file to process.
InputMessageThe message to process.
KeysA collection of keys used for cryptographic operations.
MessageHeadersA collection of headers in the ASCII armored message.
OutputFileThe output file.
OutputMessageThe output message after processing.
OverwriteIndicates whether or not the component should overwrite files.
RecipientKeysThe collection of keys belonging to the recipient of the message.
SignerKeysThe collection of keys belonging to the signer of the message.
SigningAlgorithmThe signature hash algorithm used when signing.

Method List

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

ConfigSets or retrieves a configuration setting.
DecryptDecrypts the message.
DecryptAndVerifySignatureDecrypts and verifies the signature of the message.
EncryptEncrypts the message.
GetRecipientInfoGets recipient information for an encrypted message.
InterruptInterrupt the current method.
ResetResets the component properties.
SetInputStreamSets the stream from which the component will read data to encrypt or decrypt.
SetOutputStreamThe stream to which the component will write the fully encrypted or decrypted OpenPGP data.
SignSigns the message.
SignAndEncryptSigns and encrypts the current message.
VerifySignatureVerifies the signature of the current message.

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.

ErrorFired when information is available about errors during data delivery.
KeyPassphraseFired if the passphrase of current key is incorrect or empty.
ProgressFired as progress is made.
RecipientInfoFired for each recipient key of the encrypted message.
SignatureInfoFired during verification of the signed message.
StatusShows the progress of the operation.
VerificationStatusFired after verification of the signed message.

Config Settings

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

AEADChunkSizeExpSpecifies the exponent used to calculate the plaintext chunk size for encryption.
AllowEmptyInputWhether to allow empty files for input.
AllowOldPacketTypeWhether to allow the older encrypted packet type.
Argon2IterationsSpecifies the number of iterations used for Argon2.
Argon2MemorySizeExpSpecifies the exponent used to calculate the memory size used when creating a key.
Argon2ParallelismSpecifies the degree of parallelism used for Argon2.
CloseInputStreamAfterProcessingDetermines whether or not the input stream is closed after processing.
CloseOutputStreamAfterProcessingDetermines whether or not the output stream is closed after processing.
CompressionLevelThe level of compression used.
DeleteOutputFileOnErrorWhether to delete the output file on an error.
DetachedSignatureDataThe detached signature.
EnsureValidDSASignatureHashAlgorithmWhether or not to select a suitable signature hash algorithm automatically.
FileNameThe original name of the encrypted file.
ForceV3SignatureWhether to use v3 signatures.
KeyIdLengthThe length of the KeyId available.
KeySelectionMethodThe method used to select a key for encryption or signing.
LogLevelSpecifies the level of detail that is logged.
PGPZipDirThe directory used when creating or extracting a PGP zip file.
ProgressEventThresholdThe amount of data in bytes to process before firing the progress event.
PublicKeyringFileThe file name of the public keyring file.
ReadFromProgressEventWhether to read input data from inside the progress event.
RecursiveDecryptModeWhether the encrypted data should be decrypted recursively.
RequireEncryptionWhether to throw an error when decrypting and encryption is not detected.
RequireIntegrityProtectedPacketWhether an MDC packet is required for decryption.
RequireSignatureWhether to throw an error when verifying a signature and no signature is found.
RequireValidSignatureSpecifies if an invalid signature is considered an error condition.
SecretKeyringFileThe file name of the secret keyring file.
SplitHeadersControls whether ASCII Armor headers are split or not.
SymmetricPassphraseThe password used for symmetric encryption or decryption.
UseArgon2Whether to use Argon2 for key derivation during symmetric encryption or decryption.
UseMemoryModeDetermines whether the entire message is loaded into memory prior to encryption or decryption.
VerifyClearTextSignatureWithCacheWhether the cleartext message is cached in memory when verifying a cleartext signature.
VersionHeaderThe Version header value in the ASCII armored OpenPGP message.
WriteToProgressEventWhether to write output data so it is accessible from inside the progress event.
BuildInfoInformation about the product's build.
GUIAvailableWhether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
MaskSensitiveDataWhether sensitive data is masked in log messages.
UseFIPSCompliantAPITells the component whether or not to use FIPS certified APIs.
UseInternalSecurityAPIWhether or not to use the system security libraries or an internal implementation.

ASCIIArmor Property (OpenPGP Component)

Specifies whether to use ASCII armor to encode the output message.

Syntax

public bool ASCIIArmor { get; set; }

Public Property ASCIIArmor As Boolean

Default Value

False

Remarks

This property controls whether or not ASCII armoring is used on the output message. The default value is False.

AutoSelectAlgorithms Property (OpenPGP Component)

Whether to automatically select algorithms when encrypting or signing.

Syntax

public int AutoSelectAlgorithms { get; set; }

Public Property AutoSelectAlgorithms As Integer

Default Value

0

Remarks

This property is set to the binary 'OR' of one or more options indicating which algorithms to automatically select.

When enabled automatic selection is performed by examining the preferred algorithms specified by the key.

When Encrypt is called the component will read the preferred encryption algorithm and compression method from the key specified in RecipientKeys .

If multiple keys are specified the preferred encryption algorithm and compression method from the last key is used. The EncryptingAlgorithm and CompressionMethod properties are ignored.

When Sign is called the component will read the preferred MAC algorithm and compression method from the private key specified in Keys . If multiple keys are specified the preferred MAC algorithm and compression method from the last key is used. The SigningAlgorithm and CompressionMethod properties are ignored.

The list below defines available options.

Compression Algorithm 1 (Hex 0x01)
Cipher Algorithm 2 (Hex 0x02)
MAC Algorithm 4 (Hex 0x04)

The default value is 0 which means algorithms are not automatically selected.

ClearSignature Property (OpenPGP Component)

Specifies whether or not to create a cleartext signature.

Syntax

public bool ClearSignature { get; set; }

Public Property ClearSignature As Boolean

Default Value

False

Remarks

This property controls whether or not a cleartext signature is created during signing. The default value is False. When set to true a clear text signature will be created when Sign is called.

CompressionMethod Property (OpenPGP Component)

The compression algorithm used.

Syntax

public string CompressionMethod { get; set; }

Public Property CompressionMethod As String

Default Value

"zip"

Remarks

This property specifies which compression method is used when generating output. Possible values are:

  • zip (default)
  • zlib
  • bzip2
  • none or uncompressed
Note: The level of compression is controlled by the CompressionLevel setting.

DetachedSignature Property (OpenPGP Component)

Specifies whether or not to generate a detached signature when signing a message.

Syntax

public bool DetachedSignature { get; set; }

Public Property DetachedSignature As Boolean

Default Value

False

Remarks

This property specifies whether or not a detached signature is created when signing a message. The default value is False.

If set to true the output will only be the signature. The data being signed will not be included in the output. If set to true ClearSignature will be ignored.

When this property is false (default) the signature is not detached. The output will contain both the signed data and the signature.

EncryptingAlgorithm Property (OpenPGP Component)

The encryption algorithm used when encrypting.

Syntax

public string EncryptingAlgorithm { get; set; }

Public Property EncryptingAlgorithm As String

Default Value

"AES128"

Remarks

This property specifies the encryption algorithm used when encrypting. Possible values are:

  • CAST5
  • 3DES or TripleDES
  • AES256
  • AES192
  • AES128 (default)
  • BLOWFISH
  • TWOFISH
  • IDEA
  • AES256-OCB (AEAD)
  • AES192-OCB (AEAD)
  • AES128-OCB (AEAD)
  • AES256-GCM (AEAD)
  • AES192-GCM (AEAD)
  • AES128-GCM (AEAD)

Note that if UseArgon2 is enabled, and SymmetricPassphrase is specified, an AEAD encryption algorithm (AES*-OCB and AES*-GCM) must be specified for symmetric encryption. If UseArgon2 is disabled, and an AEAD encryption algorithm is specified, the AEAD mode (OCB or GCM) will be ignored when performing symmetric encryption.

An AEAD encryption algorithm may optionally be utilized when encrypting messages (when calling Encrypt). In this case, the AEADChunkSizeExp configuration will specify the chunk size for splitting plaintext for encryption. Please see AEADChunkSizeExp for additional details.

InputFile Property (OpenPGP Component)

The file to process.

Syntax

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

This property specifies the file to be processed. Set this property to the full or relative path to the file which will be processed.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

InputMessage Property (OpenPGP Component)

The message to process.

Syntax

public string InputMessage { get; set; }
public byte[] InputMessageB { get; set; }

Public Property InputMessage As String
Public Property InputMessageB As Byte()

Default Value

""

Remarks

This property specifies the message to be processed. Set this property to the OpenPGP message content.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Keys Property (OpenPGP Component)

A collection of keys used for cryptographic operations.

Syntax

public KeyList Keys { get; }

Public Property Keys As KeyList

Remarks

This collection holds keys that are used for signing and decrypting. In most cases only one key will be specified, however multiple keys may be needed in some cases.

This property is not available at design time.

Please refer to the Key type for a complete list of fields.

MessageHeaders Property (OpenPGP Component)

A collection of headers in the ASCII armored message.

Syntax

public HeaderList MessageHeaders { get; }

Public Property MessageHeaders As HeaderList

Remarks

This property holds a collection of headers specified in the message. It is only applicable when ASCIIArmor is set to true.

When generating ASCII armored output the component will include the headers specified here in addition to the standard Version header.

After decrypting or verifying a message that is ASCII armored this collection will be populated with the headers that were present in the message.

This property is not available at design time.

Please refer to the Header type for a complete list of fields.

OutputFile Property (OpenPGP Component)

The output file.

Syntax

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

This property specifies the file to which the output will be written. This may be set to an absolute or relative path.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

OutputMessage Property (OpenPGP Component)

The output message after processing.

Syntax

public string OutputMessage { get; set; }
public byte[] OutputMessageB { get; set; }

Public Property OutputMessage As String
Public Property OutputMessageB As Byte()

Default Value

""

Remarks

This property will be populated with the output from the operation if OutputFile and SetOutputStream are not set.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Overwrite Property (OpenPGP Component)

Indicates whether or not the component should overwrite files.

Syntax

public bool Overwrite { get; set; }

Public Property Overwrite As Boolean

Default Value

False

Remarks

This property indicates whether or not the component will overwrite OutputFile. If Overwrite is False, an error will be thrown whenever OutputFile exists before an operation. The default value is False.

RecipientKeys Property (OpenPGP Component)

The collection of keys belonging to the recipient of the message.

Syntax

public KeyList RecipientKeys { get; }

Public Property RecipientKeys As KeyList

Remarks

This property contains the keys of the message recipient.

Set this property before calling Encrypt or SignAndEncrypt.

This property is not available at design time.

Please refer to the Key type for a complete list of fields.

SignerKeys Property (OpenPGP Component)

The collection of keys belonging to the signer of the message.

Syntax

public KeyList SignerKeys { get; }

Public Property SignerKeys As KeyList

Remarks

This property contains the keys of the message signer.

Set this property before calling VerifySignature or DecryptAndVerifySignature.

This property is not available at design time.

Please refer to the Key type for a complete list of fields.

SigningAlgorithm Property (OpenPGP Component)

The signature hash algorithm used when signing.

Syntax

public string SigningAlgorithm { get; set; }

Public Property SigningAlgorithm As String

Default Value

"SHA256"

Remarks

This property specifies the signature hash algorithm used when signing. Possible values are:

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

Config Method (OpenPGP Component)

Sets or retrieves a configuration setting.

Syntax

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.

Decrypt Method (OpenPGP Component)

Decrypts the message.

Syntax

public void Decrypt();

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

Public Sub Decrypt()

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

Remarks

This method decrypts the specified message.

The message will be decrypted using the keys specified in Keys. Before decryption begins the component will fire the RecipientInfo event with information about the encrypted message, including the key used to encrypt the message. Within this event you may use the available information to load the correct key into Keys.

DecryptAndVerifySignature Method (OpenPGP Component)

Decrypts and verifies the signature of the message.

Syntax

public void DecryptAndVerifySignature();

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

Public Sub DecryptAndVerifySignature()

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

Remarks

This method attempts to both decrypt and verify the signature of the message. All of the properties affected by calling the Decrypt and VerifySignature methods are affected in the same manner.

This method may be used when the data is signed, encrypted, or signed and encrypted. For instance, if the data is encrypted but not signed you may still use this method and the component will perform the decryption without error.

The message will be decrypted using the keys specified in Keys. Before decryption begins the component will fire the RecipientInfo event with information about the encrypted message, including the key used to encrypt the message. Within this event you may use the available information to load the correct key into Keys.

The message will be verified using the keys specified in SignerKeys. Before verification begins the component will fire the SignatureInfo event with information about the signature including the key used to sign the message. Within this event you may use the information available to load the correct key into SignerKeys.

By default, if the signature is not valid the component throws an exception. The configuration setting RequireValidSignature may be set to False to disable this requirement. When RequireValidSignature is set to False, the Status parameter of the VerificationStatus event should be checked to determine the result of the operation.

NOTE: This method does not attempt to check the validity of the signing key itself.

Encrypt Method (OpenPGP Component)

Encrypts the message.

Syntax

public void Encrypt();

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

Public Sub Encrypt()

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

Remarks

This method encrypts the specified message.

The message is encrypted with the public keys specified in RecipientKeys.

When encrypting, the following properties may be used to further configure the component:

GetRecipientInfo Method (OpenPGP Component)

Gets recipient information for an encrypted message.

Syntax

public void GetRecipientInfo();

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

Public Sub GetRecipientInfo()

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

Remarks

This method will fire a RecipientInfo event for every recipient key for which the message has been encrypted. The event will provide the KeyId and Fingerprint, which can be used to identify the correct key to be used for decryption.

Interrupt Method (OpenPGP Component)

Interrupt the current method.

Syntax

public void Interrupt();

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

Public Sub Interrupt()

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

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

Reset Method (OpenPGP 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.

SetInputStream Method (OpenPGP Component)

Sets the stream from which the component will read data to encrypt or decrypt.

Syntax

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the stream from which the component will read data to encrypt or decrypt. If an input stream is set before the component attempts to encode or decode an OpenPGP message, the data is read from the input stream instead of from the InputFile or InputMessage properties.

Encrypt and/or Sign

You can call this method to set the input stream that you would like to sign and/or encrypt. Then call Sign, Encrypt, or SignAndEncrypt to sign and/or encrypt the message. The appropriate ASCII Armor headers will be generated in MessageHeaders.

Decrypt and/or Verify

You can call this method to specify a valid input stream that contains the signed and/or encrypted data you would like to verify or decrypt. Then call VerifySignature, Decrypt, or DecryptAndVerifySignature to verify and/or decrypt the message.

The content of the stream will be read from the current position all the way to the end and no bytes will be skipped.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

SetOutputStream Method (OpenPGP Component)

The stream to which the component will write the fully encrypted or decrypted OpenPGP data.

Syntax

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the stream to which the component will write the fully encrypted or decrypted OpenPGP data. If an output stream is set before the component attempts to encode or decode an OpenPGP message, the component will write the data to the output stream instead of populating OutputMessage or writing to OutputFile.

Sign and/or Encrypt

To sign and/or encrypt a message to an output stream, you must first populate the Message property with the data you would like to sign and/or encrypt. Next, this method must be called with a valid output stream for which the component may write the signed or encrypted data. Then call Sign, Encrypt, or SignAndEncrypt to sign and/or encrypt the message. The appropriate ASCII Armor headers will be generated in MessageHeaders.

Decrypt and/or Verify

If you would like to decrypt a message or verify its signature and write the resulting message to an output stream, you should set the Message property to the signed and/or encrypted message you would like to verify or decrypt. Next, you must call this method to specify a valid stream for the component to write the data to. Then call VerifySignature, Decrypt, or DecryptAndVerifySignature to verify and/or decrypt the message.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

  • SetOutputStream
  • OutputFile
  • OutputMessage: The output data is written to this property if no other destination is specified.

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

Sign Method (OpenPGP Component)

Signs the message.

Syntax

public void Sign();

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

Public Sub Sign()

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

Remarks

This method signs the specified message.

The message is signed with the private key specified in Keys .

When signing, the following properties may be used to further configure the component:

SignAndEncrypt Method (OpenPGP Component)

Signs and encrypts the current message.

Syntax

public void SignAndEncrypt();

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

Public Sub SignAndEncrypt()

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

Remarks

This method signs and encrypts the specified message.

The message is encrypted with the public keys specified in RecipientKeys and signed with the private key specified in Keys.

When encrypting, the following properties may be used to further configure the component:

When signing, the following properties may be used to further configure the component:

VerifySignature Method (OpenPGP Component)

Verifies the signature of the current message.

Syntax

public void VerifySignature();

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

Public Sub VerifySignature()

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

Remarks

This method verifies the signature of the message.

The message will be verified using the keys specified in SignerKeys. Before verification begins the component will fire the SignatureInfo event with information about the signature including the key used to sign the message. Within this event you may use the information available to load the correct key into SignerKeys.

By default, if the signature is not valid the component throws an exception. The configuration setting RequireValidSignature may be set to False to disable this requirement. When RequireValidSignature is set to False, the Status parameter of the VerificationStatus event should be checked to determine the result of the operation.

Error Event (OpenPGP Component)

Fired when information is available about errors during data delivery.

Syntax

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

Public Class OpenPGPErrorEventArgs 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.

KeyPassphrase Event (OpenPGP Component)

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

Syntax

public event OnKeyPassphraseHandler OnKeyPassphrase;

public delegate void OnKeyPassphraseHandler(object sender, OpenPGPKeyPassphraseEventArgs e);

public class OpenPGPKeyPassphraseEventArgs : 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 OpenPGPKeyPassphraseEventArgs)

Public Class OpenPGPKeyPassphraseEventArgs 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:

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

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.

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

Progress Event (OpenPGP Component)

Fired as progress is made.

Syntax

public event OnProgressHandler OnProgress;

public delegate void OnProgressHandler(object sender, OpenPGPProgressEventArgs e);

public class OpenPGPProgressEventArgs : EventArgs {
  public long BytesProcessed { get; }
  public int PercentProcessed { get; }
  public int Operation { get; }
  public bool IsEOF { get; set; }
}

Public Event OnProgress As OnProgressHandler

Public Delegate Sub OnProgressHandler(sender As Object, e As OpenPGPProgressEventArgs)

Public Class OpenPGPProgressEventArgs Inherits EventArgs
  Public ReadOnly Property BytesProcessed As Long
  Public ReadOnly Property PercentProcessed As Integer
  Public ReadOnly Property Operation As Integer
  Public Property IsEOF As Boolean
End Class

Remarks

This event is fired automatically as data is processed by the component.

The PercentProcessed parameter indicates the current status of the operation.

The BytesProcessed parameter holds the total number of bytes processed so far.

The Operation parameter is only applicable when either ReadFromProgressEvent or WriteToProgressEvent is set to True. This parameter defines whether a Read or Write operation is required. If the configuration settings are not set this parameter will always return 0. Possible values are:

0None
1Read
2Write

The IsEOF parameter is only applicable when either ReadFromProgressEvent or WriteToProgressEvent is set to True. This parameter defines whether the Read or Write operation is complete. When the Operation is Read (1) this parameter must be set to indicate that all data has been supplied to the component. When the Operation is Write (2) this value may be queried to determine when all data has been processed.

RecipientInfo Event (OpenPGP Component)

Fired for each recipient key of the encrypted message.

Syntax

public event OnRecipientInfoHandler OnRecipientInfo;

public delegate void OnRecipientInfoHandler(object sender, OpenPGPRecipientInfoEventArgs e);

public class OpenPGPRecipientInfoEventArgs : EventArgs {
  public string KeyId { get; }
  public string Fingerprint { get; }
  public string PublicKeyAlgorithm { get; }
}

Public Event OnRecipientInfo As OnRecipientInfoHandler

Public Delegate Sub OnRecipientInfoHandler(sender As Object, e As OpenPGPRecipientInfoEventArgs)

Public Class OpenPGPRecipientInfoEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public ReadOnly Property PublicKeyAlgorithm As String
End Class

Remarks

This event fires when the Decrypt or DecryptAndVerifySignature method is called.

KeyId is the hex-encoded 4- or 8-byte Id of the key used to encrypt the message. If a subkey was used to encrypt the message this will be the Id of that 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

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

The KeyId and Fingerprint parameters can be used to identify the correct key to specify in Keys. Keys can be set from within this event as this event fires directly before the decryption process begins.

It is recommended to use the Fingerprint to identify the correct key, as it is possible for different keys to have the same KeyId.

PublicKeyAlgorithm is the algorithm of the public key used to encrypt the message. Possible values are:

  • RSA
  • DSA
  • ECDSA
  • EdDSA
  • Ed25519
  • Ed448
  • RSA-Legacy
  • ECDH (Subkeys only)
  • X25519 (Subkeys only)
  • X448 (Subkeys only)

SignatureInfo Event (OpenPGP Component)

Fired during verification of the signed message.

Syntax

public event OnSignatureInfoHandler OnSignatureInfo;

public delegate void OnSignatureInfoHandler(object sender, OpenPGPSignatureInfoEventArgs e);

public class OpenPGPSignatureInfoEventArgs : EventArgs {
  public string KeyId { get; }
  public string Fingerprint { get; }
  public string SigningAlgorithm { get; }
  public string PublicKeyAlgorithm { get; }
}

Public Event OnSignatureInfo As OnSignatureInfoHandler

Public Delegate Sub OnSignatureInfoHandler(sender As Object, e As OpenPGPSignatureInfoEventArgs)

Public Class OpenPGPSignatureInfoEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public ReadOnly Property SigningAlgorithm As String
  Public ReadOnly Property PublicKeyAlgorithm As String
End Class

Remarks

This event fires when the VerifySignature or DecryptAndVerifySignature method is called. It provides information about the signature of the message.

KeyId is the hex-encoded 4- or 8-byte Id of the key used to sign the message. If a subkey was used to sign the message this will be the Id of that 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

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

The KeyId and Fingerprint parameters can be used to identify the correct key to specify in SignerKeys. SignerKeys can be set from within this event as this event fires directly before the verification process begins.

It is recommended to use the Fingerprint to identify the correct key, as it is possible for different keys to have the same KeyId.

SigningAlgorithm describes the hash algorithm used when the message was originally signed. This value is applicable only to the message signature, not the key used to sign the message. Possible values are:

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

PublicKeyAlgorithm is the algorithm of the public key used to sign the message. Possible values are:

  • RSA
  • DSA
  • ECDSA
  • EdDSA
  • Ed25519
  • Ed448
  • RSA-Legacy
  • ECDH (Subkeys only)
  • X25519 (Subkeys only)
  • X448 (Subkeys only)

Status Event (OpenPGP Component)

Shows the progress of the operation.

Syntax

public event OnStatusHandler OnStatus;

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

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

Public Event OnStatus As OnStatusHandler

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

Public Class OpenPGPStatusEventArgs 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.

VerificationStatus Event (OpenPGP Component)

Fired after verification of the signed message.

Syntax

public event OnVerificationStatusHandler OnVerificationStatus;

public delegate void OnVerificationStatusHandler(object sender, OpenPGPVerificationStatusEventArgs e);

public class OpenPGPVerificationStatusEventArgs : EventArgs {
  public string KeyId { get; }
  public string Fingerprint { get; }
  public int Status { get; }
}

Public Event OnVerificationStatus As OnVerificationStatusHandler

Public Delegate Sub OnVerificationStatusHandler(sender As Object, e As OpenPGPVerificationStatusEventArgs)

Public Class OpenPGPVerificationStatusEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Fingerprint As String
  Public ReadOnly Property Status As Integer
End Class

Remarks

This event fires when VerifySignature or DecryptAndVerifySignature is called. It provides information about the result.

KeyId is the hex-encoded 4- or 8-byte Id of the key used to sign the message. 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

Status holds the result of the operation. Possible values are:

0Verification succeeded
1Verification failed
2The required key could not be found
3Verification succeeded but the key is expired.

Header Type

This is an HTTP header as it is received from the server.

Remarks

When a header is received through a Header event, it is parsed into a Header type. This type contains a Field, and its corresponding Value.

The following fields are available:
  • Field
  • Value

    • Fields

    Field
    string
    Default: ""

    This field contains the name of the HTTP Header (this is the same case as it is delivered).

    Value
    string
    Default: ""

    This field contains the Header contents.

    Constructors

    public Header();

    Public Header()

    public Header(string field, string value);

    Public Header(ByVal Field As String, ByVal Value As String)

    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
  • EffectiveDate
  • Encoded
  • ExpirationDate
  • Fingerprint
  • Id
  • OtherUserIds
  • Passphrase
  • PublicKey
  • PublicKeyAlgorithm
  • PublicKeyLength
  • Revoked
  • SecretKey
  • SecretKeyAvailable
  • Usage
  • UsageFlags
  • UserId
  • Version

    • Fields

    Curve
    string (read-only)
    Default: ""

    This field specifies the elliptic curve if PublicKeyAlgorithm is ECDSA, EdDSA, Ed25519, or Ed448. Possible values are:

    CurveValid Public Key AlgorithmsDescription
    secp256r1 ECDSA NIST curve P-256
    secp384r1 ECDSA NIST curve P-384
    secp521r1 ECDSA NIST curve P-521
    secp256k1 ECDSA Secp256k1
    Ed25519 EdDSA, Ed25519 Ed25519
    Ed448 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.

    Encoded
    string
    Default: ""

    The key. This field can be used to assign a specific key. The Fingerprint, Id, and 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, Id, and UserId fields may also be used to specify a key.

    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.

    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. When this field is set the componentwill search the Keyring for a key associated with the Fingerprint specified.

    This is in the form: 

    5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

    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: 

    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. When this field is set the component will search the 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 field when loading a key from the Keyring, as it is possible for different keys to have the same Id.

    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
    • 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 field is ECDSA, EdDSA, Ed25519, or Ed448, the length of the public key is determined by the Curve. Possible lengths are:

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

    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 is a combination of the following flags:

    0x01This key may be used to certify other keys.
    0x02This key may be used to sign data.
    0x0CThis key may be used to encrypt communications and encrypt storage.
    0x10The private component of this key may have been split by a secret-sharing mechanism.
    0x20This key may be used for authentication.
    0x80The 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: ""

    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.

    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.

    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.

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

    Constructors

    public Key(string keyring);

    Public Key(ByVal Keyring As String)

    Reads the OpenPGP public key from the specified Keyring . If multiple keys are present only the first one is used. 

    public Key(byte[] encoded);

    Public Key(ByVal Encoded As Byte())

    Reads the OpenPGP key from the specified Encoded . Both binary-formatted and ASCII-armored data are accepted. 

    public Key(string keyring, string userId);

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

    Searches the Keyring for an OpenPGP key with a matching UserId . If UserId is set to "*" the first key will be used. 

    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)

    Searches the Keyring for the specified SecretKeyRingFile and PublicKeyringFile . If UserId is set to "*" the first key will be used. 

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

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

    Searches the Encoded for an OpenPGP key with a matching UserId . If UserId is set to "*" the first key will be used.

    Config Settings (OpenPGP 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.

    OpenPGP Config Settings

    AEADChunkSizeExp:   Specifies the exponent used to calculate the plaintext chunk size for encryption.

    This config specifies the exponent used to calculate the plaintext chunk size for encryption. Note this config is only applicable when EncryptingAlgorithm is set to AES*-OCB or AES*-GCM (AEAD encryption algorithms).

    By default, this value is 6. Valid values range from 6 to 22.

    The chunk size is calculated as 2^exp (in octets, or bytes), where exp is the value of this configuration setting. For example, the default chunk size would be: 2^(6) = 64 bytes. In this case, the plaintext would be split into chunks of 64 bytes, each of which will be individually encrypted using the specified EncryptingAlgorithm.

    AllowEmptyInput:   Whether to allow empty files for input.

    This setting controls whether the component allows empty input when processing. When True, the component will process 0 byte files specified by InputFile, or 0 byte messages specified by InputMessage. The default value is False.

    AllowOldPacketType:   Whether to allow the older encrypted packet type.

    By default the component will only encrypt data using the newer and more secure integrity protected data packet type. Old implementations such as PGP 6.5.8 may require the older less secure data packet type.

    When set to True the component will read the features from the recipient key to determine if the older packet type is required. If the key does require the old packet type, then the older packet type will be used. If the key does not require the old packet type, then the new integrity protected packet type will still be used.

    By default this value is False. This means under no conditions is the older less secure packet type used. The newer integrity protected packet type is always used.

    Only enable this setting if you have a requirement to do so.

    Argon2Iterations:   Specifies the number of iterations used for Argon2.

    This configuration setting specifies the number of iterations performed for passphrase-based key derivation during symmetric encryption/decryption. Note that this configuration setting is only applicable when UseArgon2 is True and SymmetricPassphrase is specified.

    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:   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 for passphrase-based key derivation during symmetric encryption/decryption. Note that this configuration setting is only applicable when UseArgon2 is True and SymmetricPassphrase is specified.

    The default value is 16. Valid values range from 3 to 31, though the minimum can vary depending on the value of 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. Therefore, Argon2MemorySizeExp must be an integer ranging from 3+ceil(log2(p)) to 31. For example, if Argon2Parallelism is set to 8, valid values for 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 for passphrase-based key derivation during symmetric encryption/decryption. Note that this configuration setting is only applicable when UseArgon2 is True and SymmetricPassphrase is specified.

    The default value is 4. Valid values range from 1 to 2^(24)-1.

    CloseInputStreamAfterProcessing:   Determines whether or not the input stream is closed after processing.

    Determines whether or not the input stream set by SetInputStream is closed after processing is complete. The default value is True.

    CloseOutputStreamAfterProcessing:   Determines whether or not the output stream is closed after processing.

    Determines whether or not the output stream set by SetOutputStream is closed after processing is complete. The default value is True.

    CompressionLevel:   The level of compression used.

    This setting specifies the level of compression used: possible values depend on the value of CompressionMethod and are detailed below.

    zlib 1-6
    zip 1-6
    bzip21-9
    Higher values will cause the component to compress better; lower values will cause the component to compress faster. The default value for all methods is 4.
    DeleteOutputFileOnError:   Whether to delete the output file on an error.

    Set this to true to automatically delete any partially written OutputFile if an error occurs. The default is false

    DetachedSignatureData:   The detached signature.

    This setting is used to specify the detached signature before calling VerifySignature. The message data should be specified normally and this setting should be set to the detached signature data. Both hex-string and OpenPGP ASCII-armored message formats are allowed. Hex-encoded data should be provided as a string like so: 

    89011C04000102000605025100459B000A0910E2...
    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 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:

    CurveHash Algorithm
    secp256r1 SHA256
    secp384r1 SHA384
    secp521r1 SHA512
    secp256k1 SHA256

    FileName:   The original name of the encrypted file.

    When encrypting, this configuration setting can be used to specify the original name of the encrypted data. When specifying an InputFile to encrypt from, this is included automatically in the encrypted packet. After decrypting, this will contain the file name of the original encrypted file.

    ForceV3Signature:   Whether to use v3 signatures.

    This setting is used to force v3 signatures for compatibility with older PGP implementations (versions 5 through 7).

    The default value is False.

    KeyIdLength:   The length of the KeyId available.

    This controls the length of KeyId available when RecipientInfo fires. Possible values are 4 or 8 (default).

    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

    KeySelectionMethod:   The method used to select a key for encryption or signing.

    When more than one key is present this component can be configured to automatically select a key based on certain criteria (described below) or allow for manual selection.

    0 Automatic selection, first suitable subkey. Expired keys accepted.
    1 Automatic selection, first suitable subkey. Expired keys not accepted.
    2 Automatic selection, newest suitable subkey. Expired keys not accepted (Default).
    99 Manual Selection.
    A key's suitability is determined by its usage flags.

    Manual Selection

    To manually select a key for any operation pass the key's Id in the constructor. Openpgp pgp = new Openpgp(); pgp.Config("KeySelectionMethod=99"); pgp.RecipientKeys.Add(new Key(@"C:\path\to\key.asc", "7CA1376C39768977")); // Key with Id 7CA1376C39768977 will be used for encryption.

    LogLevel:   Specifies the level of detail that is logged.

    This setting controls the level of detail that is logged through the Status 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.
    PGPZipDir:   The directory used when creating or extracting a PGP zip file.

    A PGP zip file is a Tar archive that is encrypted. It is commonly used by utilities to protect multiple files in one OpenPGP message. The component supports creating and extracting these types of files.

    • To create a PGP zip file set this value to a location on disk including a filemask and call Encrypt. For instance: OpenPGP1.Config("PGPZipDir=C:\MyFiles\*.txt"); OpenPGP1.OutputFile = "C:\PGPZip.pgp"; OpenPGP1.Encrypt(); The created file returned in the OutputFile property is the PGP zip. If InputFile is specified it is used to temporarily hold the Tar archive while creating the PGP zip file. The temporary file is not automatically deleted. If InputFile is not specified the Tar archive is held in memory while creating the PGP zip file.
    • To extract a PGP zip file set this value to a location on disk and call Decrypt. For instance: OpenPGP1.Config("PGPZipDir=C:\MyFiles"); OpenPGP1.InputFile = "C:\PGPZip.pgp"; OpenPGP1.Decrypt(); The extracted files will be present in the specified directory. If OutputFile is specified it is used to temporarily hold the Tar archive. The temporary file is not automatically deleted. If OutputFile is not specified the Tar archive is held in memory while extracting the PGP zip file. Note that if the OpenPGP message supplied is not a PGP zip file the decryption will occur as normal without error.

    ProgressEventThreshold:   The amount of data in bytes to process before firing the progress event.

    When encrypting or decrypting, the Progress event is fired as data is processed by the component. When this setting is specified, the event will only fire after processing at least the specified number of bytes. The default value is 0.

    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.

    ReadFromProgressEvent:   Whether to read input data from inside the progress event.

    When set to True this setting allows input data to be specified from within the Progress event. The component will repeatedly fire the Progress event to ask for data. Inside the event set InputMessage when the Operation parameter of the event is 1 (Read). When all data has been provided set the IsEOF parameter of the event to True. This allows input data to be chunked and provided piece by piece. The default value is False.

    RecursiveDecryptMode:   Whether the encrypted data should be decrypted recursively.

    In some instances data will be encrypted multiple times. This configuration option determines how the component will handle this situation. Options are:

    0Automatic - If the PGP message contains the special header version "PGP Command Line" then recursive decryption will be attempted. (Default)
    1Always attempt recursive decryption.
    2Never attempt recursive decryption.
    RequireEncryption:   Whether to throw an error when decrypting and encryption is not detected.

    By default, the component's decryption methods will succeed if the message is not encrypted. To cause an error to be thrown in this case, set this option to true.

    The default value is false.

    RequireIntegrityProtectedPacket:   Whether an MDC packet is required for decryption.

    When set to true, the component will throw an exception if the message being decrypted does not contain a Message Detection Code (MDC) packet. The default value is false.

    RequireSignature:   Whether to throw an error when verifying a signature and no signature is found.

    By default, the component's signature verification methods will succeed if the message is not signed. To cause an error to be thrown in this case, set this option to true.

    The default value is false.

    RequireValidSignature:   Specifies if an invalid signature is considered an error condition.

    By default, if the signature is not valid the component throws an exception. This setting may be set to False to disable this requirement. When False, the Status parameter of the VerificationStatus event should be checked to determine the result of the operation. The default value is True.

    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.

    SplitHeaders:   Controls whether ASCII Armor headers are split or not.

    By default, when headers are specified via MessageHeaders, the component will split headers over a certain length onto multiple lines. This is done to avoid potential errors during transport of the message. If false, the headers will be on one line regardless of length. The default value is True.

    SymmetricPassphrase:   The password used for symmetric encryption or decryption.

    This setting specifies the passphrase when using symmetric encryption. If a value is provided, symmetric encryption/decryption will be attempted. In this case no keys are used for either encryption or decryption. Only Encrypt and Decrypt are valid operations when a value is set. Sign, SignAndEncrypt, VerifySignature, and DecryptAndVerifySignature are not valid operations when using this option.

    UseArgon2:   Whether to use Argon2 for key derivation during symmetric encryption or decryption.

    Determines whether the Argon2 algorithm is used as the String-to-Key (S2K) method for passphrase-based key derivation during symmetric encryption/decryption. The default value is False.

    This configuration is only applicable when SymmetricPassphrase is specified and when calling Encrypt or Decrypt. Additionally, the following configuration settings are applicable when this config is set to True:

    Note that if UseArgon2 is enabled, EncryptingAlgorithm must be specified as an AEAD encryption algorithm (e.g., AES192-OCB). Please see the EncryptingAlgorithm for additional details.

    UseMemoryMode:   Determines whether the entire message is loaded into memory prior to encryption or decryption.

    This config determines whether the entire message is loaded into memory prior to encryption or decryption.

    By default, this config is False, and messages will be encrypted or decrypted in a stream-based manner. When True, the entire message will be loaded into memory prior to encryption or decryption.

    VerifyClearTextSignatureWithCache:   Whether the cleartext message is cached in memory when verifying a cleartext signature.

    When verifying a cleartext signature, this configuration setting determines whether the cleartext message is cached in memory.

    This config is True by default, and must be true when verifying an OpenPGP v6 cleartext signature. When enabled, the cleartext portion will be cached in memory until the signature is fully processed.

    Note: If the signature is known to be an OpenPGP v4 cleartext signature beforehand (i.e., signed with a v4 key), this config may be set to False. However, if this config is disabled, the component will be unable to verify OpenPGP v6 cleartext signatures. In this case, the component will throw an exception when calling VerifySignature or DecryptAndVerifySignature.

    VersionHeader:   The Version header value in the ASCII armored OpenPGP message.

    This setting specifies the Version header value included in the ASCII armored OpenPGP message. This may be set before calling Encrypt, Sign, or SignAndEncrypt. The default value is "IPWorks! OpenPGP 2022".

    This setting will be populated after calling Decrypt, VerifySignature, or DecryptAndVerifySignature.

    WriteToProgressEvent:   Whether to write output data so it is accessible from inside the progress event.

    When set to True this setting allows output data to be obtained from within the Progress event. The component will repeatedly fire the Progress event to provide output data. Inside the event check OutputMessage when the Operation parameter of the event is 2 (Write). The IsEOF parameter should be checked inside the event to determine when all output data has been provided. This allows output data to be chunked and obtained piece by piece. The default value is False.

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

    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.

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

    Note: This setting is applicable only on Windows.

    Note: Enabling FIPS compliance requires a special license; please contact 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.

    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 (OpenPGP 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.