Struct ipworkspgp::OpenPGP

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

ipworkspgp::OpenPGP

Remarks

The OpenPGP struct 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.

GnuPG (2.5.x and later) uses its own Version 5 message format (LibrePGP). The struct supports creating and processing LibrePGP-formatted messages as well, for interoperability with GnuPG. See CompatibilityProfile for details on choosing between the two formats.

The encrypt, sign, and sign_and_encrypt 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, verify_signature, and decrypt_and_verify_signature methods are used to process the incoming message.

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

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

The recipient_keys property holds the key used to encrypt.

Input and Output Properties

The struct 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:

• input_file
• input_message

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

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksPGP. Due to this, the OpenPGP struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of OpenPGP when you have finished using the instance.

Property List

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

Method List

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

Event List

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

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

ascii_armor property (OpenPGP Struct)

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

Syntax

fn ascii_armor(&self ) -> Result<bool, IPWorksPGPError> 
fn set_ascii_armor(&self, value : bool) ->  Option<IPWorksPGPError> 

Default Value

false

Remarks

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

Data Type

bool

auto_select_algorithms property (OpenPGP Struct)

Whether to automatically select algorithms when encrypting or signing.

Syntax

fn auto_select_algorithms(&self ) -> Result<i32, IPWorksPGPError> 
fn set_auto_select_algorithms(&self, value : i32) ->  Option<IPWorksPGPError> 

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 struct will read the preferred encryption algorithm and compression method from the key specified in the RecipientKey* properties.

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

When sign is called the struct will read the preferred MAC algorithm and compression method from the private key specified in the Key* properties. If multiple keys are specified the preferred MAC algorithm and compression method from the last key is used. The signing_algorithm and compression_method properties are ignored.

The list below defines available options.

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

Data Type

i32

clear_signature property (OpenPGP Struct)

Specifies whether or not to create a cleartext signature.

Syntax

fn clear_signature(&self ) -> Result<bool, IPWorksPGPError> 
fn set_clear_signature(&self, value : bool) ->  Option<IPWorksPGPError> 

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.

Data Type

bool

compression_method property (OpenPGP Struct)

The compression algorithm used.

Syntax

fn compression_method(&self ) -> Result<String, IPWorksPGPError> 
fn set_compression_method(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_compression_method_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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

Data Type

String

detached_signature property (OpenPGP Struct)

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

Syntax

fn detached_signature(&self ) -> Result<bool, IPWorksPGPError> 
fn set_detached_signature(&self, value : bool) ->  Option<IPWorksPGPError> 

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

Data Type

bool

encrypting_algorithm property (OpenPGP Struct)

The encryption algorithm used when encrypting.

Syntax

fn encrypting_algorithm(&self ) -> Result<String, IPWorksPGPError> 
fn set_encrypting_algorithm(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_encrypting_algorithm_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 for AES256, AES192, and AES128, the struct uses a modified form of CFB mode in accordance with the OpenPGP standard.

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.

Data Type

String

input_file property (OpenPGP Struct)

The file to process.

Syntax

fn input_file(&self ) -> Result<String, IPWorksPGPError> 
fn set_input_file(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_input_file_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 struct 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:

• input_file
• input_message

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

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

String

input_message property (OpenPGP Struct)

The message to process.

Syntax

fn input_message(&self ) -> Result<Vec<u8>, IPWorksPGPError> 
fn set_input_message(&self, value : Vec<u8>) ->  Option<IPWorksPGPError> 
fn set_input_message_ref(&self, value : &[u8]) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

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

Input and Output Properties

The struct 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:

• input_file
• input_message

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

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

Vec

key_count property (OpenPGP Struct)

The number of records in the Key arrays.

Syntax

fn key_count(&self ) -> Result<i32, IPWorksPGPError> 
fn set_key_count(&self, value : i32) ->  Option<IPWorksPGPError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• key_curve
• key_effective_date
• key_encoded
• key_expiration_date
• key_fingerprint
• key_id
• key_other_user_ids
• key_passphrase
• key_public_key
• key_public_key_algorithm
• key_public_key_length
• key_revoked
• keyring
• key_secret_key
• key_secret_key_available
• key_usage
• key_usage_flags
• key_user_id
• key_version

The array indices start at 0 and end at key_count - 1.

Data Type

i32

key_curve property (OpenPGP Struct)

This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 .

Syntax

fn key_curve(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

This property specifies the elliptic curve if key_public_key_algorithm is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_effective_date property (OpenPGP Struct)

The date when this key becomes valid.

Syntax

fn key_effective_date(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The date when this key becomes valid. Prior to this it is not valid. The following is an example of a valid encoded date:

23-Jan-2000 15:00:00.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_expiration_date property (OpenPGP Struct)

The date the key expires.

Syntax

fn key_expiration_date(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The date the key expires. After this date the key will no longer be valid. The following is an example of a valid encoded date:

23-Jan-2001 15:00:00.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

keyring property (OpenPGP Struct)

The location of the keyring.

Syntax

fn keyring(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_keyring(&self, KeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_keyring_ref(&self, KeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The location of the keyring.

If the keyring is stored in a directory, set this property to the directory. The directory must contain the files "secring.gpg" and "pubring.gpg". A keyring may also be stored in a single file. If the keyring is a file this property should be set to the path of the file.

When This property is set the struct will read the keyring and populate the key property with the first key found in the keyring. Set key_user_id to select a different key in the current keyring.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

Data Type

String

key_other_user_ids property (OpenPGP Struct)

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

Syntax

fn key_other_user_ids(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_passphrase property (OpenPGP Struct)

The passphrase for the key's secret key (if any).

Syntax

fn key_passphrase(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_key_passphrase(&self, KeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_passphrase_ref(&self, KeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The passphrase for the key's secret key (if any). This must be specified before operations requiring the secret key are attempted. The passphrase may be supplied in this property or through the on_key_passphrase event, which will fire when a passphrase is required.

The passphrase is required when using the following methods in KeyMgr:

• add_user_id
• sign_user_id
• change_expiration_date
• change_passphrase

When using the OpenPGP struct, or an email-based struct, the following methods require a passphrase for the key:

• decrypt
• sign
• sign_and_encrypt

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

Data Type

String

key_public_key property (OpenPGP Struct)

The public key of the key.

Syntax

fn key_public_key(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The public key of the key. The key is provided as ASCII armored data.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_public_key_algorithm property (OpenPGP Struct)

A text description of the public key algorithm of the key.

Syntax

fn key_public_key_algorithm(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of the public key algorithm of the key. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA
• Ed25519
• Ed448
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448
• RSA-Legacy

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_public_key_length property (OpenPGP Struct)

The length of the public key in bits.

Syntax

fn key_public_key_length(&self , KeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

0

Remarks

The length of the public key in bits. Common values are 1024, 2048, and 3072.

If the key_public_key_algorithm property is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448, the length of the public key is determined by the key_curve. Possible lengths are:

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

i32

key_revoked property (OpenPGP Struct)

Whether or not the key is revoked.

Syntax

fn key_revoked(&self , KeyIndex : i32) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not the key is revoked.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

bool

key_secret_key property (OpenPGP Struct)

The secret key of the key (if available).

Syntax

fn key_secret_key(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The secret key of the key (if available). The key is provided as ASCII armored data.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_secret_key_available property (OpenPGP Struct)

Whether or not a secret key is available for the selected key.

Syntax

fn key_secret_key_available(&self , KeyIndex : i32) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not a secret key is available for the selected key.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

bool

key_usage property (OpenPGP Struct)

A text description of UsageFlags .

Syntax

fn key_usage(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of key_usage_flags.

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

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

String

key_usage_flags property (OpenPGP Struct)

Flags that show the intended use for the key.

Syntax

fn key_usage_flags(&self , KeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

47

Remarks

Flags that show the intended use for the key. The default value is 0x0F. The value of key_usage_flags is a combination of the following flags:

Please refer to the key_usage property for a text representation of key_usage_flags.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

i32

key_version property (OpenPGP Struct)

This property can be used to query the OpenPGP version of the currently selected Key .

Syntax

fn key_version(&self , KeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

4

Remarks

This property can be used to query the OpenPGP version of the currently selected key. Possible values are:

• 4 - OpenPGP v4 (default)
• 5 - LibrePGP v5
• 6 - OpenPGP v6

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

This property is read-only.

Data Type

i32

key_user_id property (OpenPGP Struct)

The user Id of the key.

Syntax

fn key_user_id(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_key_user_id(&self, KeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_user_id_ref(&self, KeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The user Id of the key. When a key is loaded this property is populated with the user Id associated with the key. This property may be set to load a key from the key_keyring. When this property is set the struct will search the key_keyring for a key associated with the UserId specified.

When loading a key with multiple user Ids, this property will be populated with the UserId that was most recently added to the key. To discover all of the UserIds associated with a key query this property and key_other_user_ids after loading the key.

The UserId format is:

FirstName LastName (Comment) <Email>

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

When using this property to select a key you may also specify the key's Id, or any of its subkeys' Ids, instead of a user Id. The struct will then search for a key with a matching Id. This is helpful in situations where you do not have the UserId but still need to load the key, such as within the OpenPGP struct's on_recipient_info event.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

Data Type

String

key_id property (OpenPGP Struct)

The hex-encoded, 4-byte or 8-byte key Id.

Syntax

fn key_id(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_key_id(&self, KeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_id_ref(&self, KeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

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

5E70662EA810E768

When a key is loaded, this property is populated with the Id associated with the key. This property may be set to load a key from the key_keyring. When this property is set the struct will search the key_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 key_fingerprint property when loading a key from the key_keyring, as it is possible for different keys to have the same Id.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

Data Type

String

key_fingerprint property (OpenPGP Struct)

The hex-encoded, 20-byte fingerprint of the key.

Syntax

fn key_fingerprint(&self , KeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_key_fingerprint(&self, KeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_key_fingerprint_ref(&self, KeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The hex-encoded, 20-byte fingerprint of the key.

When a key is loaded, this property is populated with the Fingerprint associated with the key. This property may be set to load a key from the key_keyring. When this property is set the struct will search the key_keyring for a key associated with the Fingerprint specified.

This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

Data Type

String

key_encoded property (OpenPGP Struct)

The key.

Syntax

fn key_encoded(&self , KeyIndex : i32) -> Result<Vec<u8>, IPWorksPGPError> 
fn set_key_encoded(&self, KeyIndex : i32, value : Vec<u8>) ->  Option<IPWorksPGPError> 
fn set_key_encoded_ref(&self, KeyIndex : i32, value : &[u8]) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The key. This property can be used to assign a specific key. The key_fingerprint, key_id, and key_user_id properties may also be used to specify a key.

The KeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the KeyCount property.

Data Type

Vec

message_header_count property (OpenPGP Struct)

The number of records in the MessageHeader arrays.

Syntax

fn message_header_count(&self ) -> Result<i32, IPWorksPGPError> 
fn set_message_header_count(&self, value : i32) ->  Option<IPWorksPGPError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• message_header_field
• message_header_value

The array indices start at 0 and end at message_header_count - 1.

Data Type

i32

message_header_field property (OpenPGP Struct)

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

Syntax

fn message_header_field(&self , MessageHeaderIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_message_header_field(&self, MessageHeaderIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_message_header_field_ref(&self, MessageHeaderIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

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

The MessageHeaderIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MessageHeaderCount property.

Data Type

String

message_header_value property (OpenPGP Struct)

This property contains the header contents.

Syntax

fn message_header_value(&self , MessageHeaderIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_message_header_value(&self, MessageHeaderIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_message_header_value_ref(&self, MessageHeaderIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

This property contains the Header contents.

The MessageHeaderIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MessageHeaderCount property.

Data Type

String

output_file property (OpenPGP Struct)

The output file.

Syntax

fn output_file(&self ) -> Result<String, IPWorksPGPError> 
fn set_output_file(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_output_file_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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 struct 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:

• input_file
• input_message

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

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

String

output_message property (OpenPGP Struct)

The output message after processing.

Syntax

fn output_message(&self ) -> Result<Vec<u8>, IPWorksPGPError> 
fn set_output_message(&self, value : Vec<u8>) ->  Option<IPWorksPGPError> 
fn set_output_message_ref(&self, value : &[u8]) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

This property will be populated with the output from the operation if output_file is not set.

Input and Output Properties

The struct 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:

• input_file
• input_message

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

• output_file
• output_message: The output data is written to this property if no other destination is specified.

Data Type

Vec

overwrite property (OpenPGP Struct)

Indicates whether or not the struct should overwrite files.

Syntax

fn overwrite(&self ) -> Result<bool, IPWorksPGPError> 
fn set_overwrite(&self, value : bool) ->  Option<IPWorksPGPError> 

Default Value

false

Remarks

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

Data Type

bool

recipient_key_count property (OpenPGP Struct)

The number of records in the RecipientKey arrays.

Syntax

fn recipient_key_count(&self ) -> Result<i32, IPWorksPGPError> 
fn set_recipient_key_count(&self, value : i32) ->  Option<IPWorksPGPError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• recipient_key_curve
• recipient_key_effective_date
• recipient_key_encoded
• recipient_key_expiration_date
• recipient_key_fingerprint
• recipient_key_id
• recipient_key_keyring
• recipient_key_other_user_ids
• recipient_key_passphrase
• recipient_key_public_key
• recipient_key_public_key_algorithm
• recipient_key_public_key_length
• recipient_key_revoked
• recipient_key_secret_key
• recipient_key_secret_key_available
• recipient_key_usage
• recipient_key_usage_flags
• recipient_key_user_id
• recipient_key_version

The array indices start at 0 and end at recipient_key_count - 1.

Data Type

i32

recipient_key_curve property (OpenPGP Struct)

This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 .

Syntax

fn recipient_key_curve(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

This property specifies the elliptic curve if recipient_key_public_key_algorithm is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_effective_date property (OpenPGP Struct)

The date when this key becomes valid.

Syntax

fn recipient_key_effective_date(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The date when this key becomes valid. Prior to this it is not valid. The following is an example of a valid encoded date:

23-Jan-2000 15:00:00.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_expiration_date property (OpenPGP Struct)

The date the key expires.

Syntax

fn recipient_key_expiration_date(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The date the key expires. After this date the key will no longer be valid. The following is an example of a valid encoded date:

23-Jan-2001 15:00:00.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_keyring property (OpenPGP Struct)

The location of the keyring.

Syntax

fn recipient_key_keyring(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_recipient_key_keyring(&self, RecipientKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_recipient_key_keyring_ref(&self, RecipientKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The location of the keyring.

If the keyring is stored in a directory, set this property to the directory. The directory must contain the files "secring.gpg" and "pubring.gpg". A keyring may also be stored in a single file. If the keyring is a file this property should be set to the path of the file.

When This property is set the struct will read the keyring and populate the key property with the first key found in the keyring. Set key_user_id to select a different key in the current keyring.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

Data Type

String

recipient_key_other_user_ids property (OpenPGP Struct)

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

Syntax

fn recipient_key_other_user_ids(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_passphrase property (OpenPGP Struct)

The passphrase for the key's secret key (if any).

Syntax

fn recipient_key_passphrase(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_recipient_key_passphrase(&self, RecipientKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_recipient_key_passphrase_ref(&self, RecipientKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The passphrase for the key's secret key (if any). This must be specified before operations requiring the secret key are attempted. The passphrase may be supplied in this property or through the on_key_passphrase event, which will fire when a passphrase is required.

The passphrase is required when using the following methods in KeyMgr:

• add_user_id
• sign_user_id
• change_expiration_date
• change_passphrase

When using the OpenPGP struct, or an email-based struct, the following methods require a passphrase for the key:

• decrypt
• sign
• sign_and_encrypt

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

Data Type

String

recipient_key_public_key property (OpenPGP Struct)

The public key of the key.

Syntax

fn recipient_key_public_key(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The public key of the key. The key is provided as ASCII armored data.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_public_key_algorithm property (OpenPGP Struct)

A text description of the public key algorithm of the key.

Syntax

fn recipient_key_public_key_algorithm(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of the public key algorithm of the key. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA
• Ed25519
• Ed448
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448
• RSA-Legacy

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_public_key_length property (OpenPGP Struct)

The length of the public key in bits.

Syntax

fn recipient_key_public_key_length(&self , RecipientKeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

0

Remarks

The length of the public key in bits. Common values are 1024, 2048, and 3072.

If the recipient_key_public_key_algorithm property is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448, the length of the public key is determined by the recipient_key_curve. Possible lengths are:

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

i32

recipient_key_revoked property (OpenPGP Struct)

Whether or not the key is revoked.

Syntax

fn recipient_key_revoked(&self , RecipientKeyIndex : i32) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not the key is revoked.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

bool

recipient_key_secret_key property (OpenPGP Struct)

The secret key of the key (if available).

Syntax

fn recipient_key_secret_key(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The secret key of the key (if available). The key is provided as ASCII armored data.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_secret_key_available property (OpenPGP Struct)

Whether or not a secret key is available for the selected key.

Syntax

fn recipient_key_secret_key_available(&self , RecipientKeyIndex : i32) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not a secret key is available for the selected key.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

bool

recipient_key_usage property (OpenPGP Struct)

A text description of UsageFlags .

Syntax

fn recipient_key_usage(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of recipient_key_usage_flags.

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

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

String

recipient_key_usage_flags property (OpenPGP Struct)

Flags that show the intended use for the key.

Syntax

fn recipient_key_usage_flags(&self , RecipientKeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

47

Remarks

Flags that show the intended use for the key. The default value is 0x0F. The value of recipient_key_usage_flags is a combination of the following flags:

Please refer to the recipient_key_usage property for a text representation of recipient_key_usage_flags.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

i32

recipient_key_version property (OpenPGP Struct)

This property can be used to query the OpenPGP version of the currently selected Key .

Syntax

fn recipient_key_version(&self , RecipientKeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

4

Remarks

This property can be used to query the OpenPGP version of the currently selected key. Possible values are:

• 4 - OpenPGP v4 (default)
• 5 - LibrePGP v5
• 6 - OpenPGP v6

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

This property is read-only.

Data Type

i32

recipient_key_user_id property (OpenPGP Struct)

The user Id of the key.

Syntax

fn recipient_key_user_id(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_recipient_key_user_id(&self, RecipientKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_recipient_key_user_id_ref(&self, RecipientKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The user Id of the key. When a key is loaded this property is populated with the user Id associated with the key. This property may be set to load a key from the recipient_key_keyring. When this property is set the struct will search the recipient_key_keyring for a key associated with the UserId specified.

When loading a key with multiple user Ids, this property will be populated with the UserId that was most recently added to the key. To discover all of the UserIds associated with a key query this property and key_other_user_ids after loading the key.

The UserId format is:

FirstName LastName (Comment) <Email>

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

When using this property to select a key you may also specify the key's Id, or any of its subkeys' Ids, instead of a user Id. The struct will then search for a key with a matching Id. This is helpful in situations where you do not have the UserId but still need to load the key, such as within the OpenPGP struct's on_recipient_info event.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

Data Type

String

recipient_key_id property (OpenPGP Struct)

The hex-encoded, 4-byte or 8-byte key Id.

Syntax

fn recipient_key_id(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_recipient_key_id(&self, RecipientKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_recipient_key_id_ref(&self, RecipientKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

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

5E70662EA810E768

When a key is loaded, this property is populated with the Id associated with the key. This property may be set to load a key from the recipient_key_keyring. When this property is set the struct will search the recipient_key_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 recipient_key_fingerprint property when loading a key from the recipient_key_keyring, as it is possible for different keys to have the same Id.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

Data Type

String

recipient_key_fingerprint property (OpenPGP Struct)

The hex-encoded, 20-byte fingerprint of the key.

Syntax

fn recipient_key_fingerprint(&self , RecipientKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_recipient_key_fingerprint(&self, RecipientKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_recipient_key_fingerprint_ref(&self, RecipientKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The hex-encoded, 20-byte fingerprint of the key.

When a key is loaded, this property is populated with the Fingerprint associated with the key. This property may be set to load a key from the recipient_key_keyring. When this property is set the struct will search the recipient_key_keyring for a key associated with the Fingerprint specified.

This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

Data Type

String

recipient_key_encoded property (OpenPGP Struct)

The key.

Syntax

fn recipient_key_encoded(&self , RecipientKeyIndex : i32) -> Result<Vec<u8>, IPWorksPGPError> 
fn set_recipient_key_encoded(&self, RecipientKeyIndex : i32, value : Vec<u8>) ->  Option<IPWorksPGPError> 
fn set_recipient_key_encoded_ref(&self, RecipientKeyIndex : i32, value : &[u8]) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The key. This property can be used to assign a specific key. The recipient_key_fingerprint, recipient_key_id, and recipient_key_user_id properties may also be used to specify a key.

The RecipientKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RecipientKeyCount property.

Data Type

Vec

signer_key_count property (OpenPGP Struct)

The number of records in the SignerKey arrays.

Syntax

fn signer_key_count(&self ) -> Result<i32, IPWorksPGPError> 
fn set_signer_key_count(&self, value : i32) ->  Option<IPWorksPGPError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• signer_key_curve
• signer_key_effective_date
• signer_key_encoded
• signer_key_expiration_date
• signer_key_fingerprint
• signer_key_id
• signer_key_keyring
• signer_key_other_user_ids
• signer_key_passphrase
• signer_key_public_key
• signer_key_public_key_algorithm
• signer_key_public_key_length
• signer_key_revoked
• signer_key_secret_key
• signer_key_secret_key_available
• signer_key_usage
• signer_key_usage_flags
• signer_key_user_id
• signer_key_version

The array indices start at 0 and end at signer_key_count - 1.

Data Type

i32

signer_key_curve property (OpenPGP Struct)

This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 .

Syntax

fn signer_key_curve(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

This property specifies the elliptic curve if signer_key_public_key_algorithm is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448. Possible values are:

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_effective_date property (OpenPGP Struct)

The date when this key becomes valid.

Syntax

fn signer_key_effective_date(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The date when this key becomes valid. Prior to this it is not valid. The following is an example of a valid encoded date:

23-Jan-2000 15:00:00.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_expiration_date property (OpenPGP Struct)

The date the key expires.

Syntax

fn signer_key_expiration_date(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The date the key expires. After this date the key will no longer be valid. The following is an example of a valid encoded date:

23-Jan-2001 15:00:00.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_keyring property (OpenPGP Struct)

The location of the keyring.

Syntax

fn signer_key_keyring(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_signer_key_keyring(&self, SignerKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_signer_key_keyring_ref(&self, SignerKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The location of the keyring.

If the keyring is stored in a directory, set this property to the directory. The directory must contain the files "secring.gpg" and "pubring.gpg". A keyring may also be stored in a single file. If the keyring is a file this property should be set to the path of the file.

When This property is set the struct will read the keyring and populate the key property with the first key found in the keyring. Set key_user_id to select a different key in the current keyring.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

Data Type

String

signer_key_other_user_ids property (OpenPGP Struct)

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

Syntax

fn signer_key_other_user_ids(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_passphrase property (OpenPGP Struct)

The passphrase for the key's secret key (if any).

Syntax

fn signer_key_passphrase(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_signer_key_passphrase(&self, SignerKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_signer_key_passphrase_ref(&self, SignerKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The passphrase for the key's secret key (if any). This must be specified before operations requiring the secret key are attempted. The passphrase may be supplied in this property or through the on_key_passphrase event, which will fire when a passphrase is required.

The passphrase is required when using the following methods in KeyMgr:

• add_user_id
• sign_user_id
• change_expiration_date
• change_passphrase

When using the OpenPGP struct, or an email-based struct, the following methods require a passphrase for the key:

• decrypt
• sign
• sign_and_encrypt

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

Data Type

String

signer_key_public_key property (OpenPGP Struct)

The public key of the key.

Syntax

fn signer_key_public_key(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The public key of the key. The key is provided as ASCII armored data.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_public_key_algorithm property (OpenPGP Struct)

A text description of the public key algorithm of the key.

Syntax

fn signer_key_public_key_algorithm(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of the public key algorithm of the key. Possible values are:

• RSA
• DSA
• ECDSA
• EdDSA
• Ed25519
• Ed448
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448
• RSA-Legacy

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_public_key_length property (OpenPGP Struct)

The length of the public key in bits.

Syntax

fn signer_key_public_key_length(&self , SignerKeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

0

Remarks

The length of the public key in bits. Common values are 1024, 2048, and 3072.

If the signer_key_public_key_algorithm property is ECDSA, EdDSA, Ed25519, Ed448, ML-DSA-65+Ed25519, or ML-DSA-87+Ed448, the length of the public key is determined by the signer_key_curve. Possible lengths are:

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

i32

signer_key_revoked property (OpenPGP Struct)

Whether or not the key is revoked.

Syntax

fn signer_key_revoked(&self , SignerKeyIndex : i32) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not the key is revoked.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

bool

signer_key_secret_key property (OpenPGP Struct)

The secret key of the key (if available).

Syntax

fn signer_key_secret_key(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

The secret key of the key (if available). The key is provided as ASCII armored data.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_secret_key_available property (OpenPGP Struct)

Whether or not a secret key is available for the selected key.

Syntax

fn signer_key_secret_key_available(&self , SignerKeyIndex : i32) -> Result<bool, IPWorksPGPError> 

Default Value

false

Remarks

Whether or not a secret key is available for the selected key.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

bool

signer_key_usage property (OpenPGP Struct)

A text description of UsageFlags .

Syntax

fn signer_key_usage(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 

Default Value

""

Remarks

A text description of signer_key_usage_flags.

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

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

String

signer_key_usage_flags property (OpenPGP Struct)

Flags that show the intended use for the key.

Syntax

fn signer_key_usage_flags(&self , SignerKeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

47

Remarks

Flags that show the intended use for the key. The default value is 0x0F. The value of signer_key_usage_flags is a combination of the following flags:

Please refer to the signer_key_usage property for a text representation of signer_key_usage_flags.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

i32

signer_key_version property (OpenPGP Struct)

This property can be used to query the OpenPGP version of the currently selected Key .

Syntax

fn signer_key_version(&self , SignerKeyIndex : i32) -> Result<i32, IPWorksPGPError> 

Default Value

4

Remarks

This property can be used to query the OpenPGP version of the currently selected key. Possible values are:

• 4 - OpenPGP v4 (default)
• 5 - LibrePGP v5
• 6 - OpenPGP v6

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

This property is read-only.

Data Type

i32

signer_key_user_id property (OpenPGP Struct)

The user Id of the key.

Syntax

fn signer_key_user_id(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_signer_key_user_id(&self, SignerKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_signer_key_user_id_ref(&self, SignerKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The user Id of the key. When a key is loaded this property is populated with the user Id associated with the key. This property may be set to load a key from the signer_key_keyring. When this property is set the struct will search the signer_key_keyring for a key associated with the UserId specified.

When loading a key with multiple user Ids, this property will be populated with the UserId that was most recently added to the key. To discover all of the UserIds associated with a key query this property and key_other_user_ids after loading the key.

The UserId format is:

FirstName LastName (Comment) <Email>

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

When using this property to select a key you may also specify the key's Id, or any of its subkeys' Ids, instead of a user Id. The struct will then search for a key with a matching Id. This is helpful in situations where you do not have the UserId but still need to load the key, such as within the OpenPGP struct's on_recipient_info event.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

Data Type

String

signer_key_id property (OpenPGP Struct)

The hex-encoded, 4-byte or 8-byte key Id.

Syntax

fn signer_key_id(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_signer_key_id(&self, SignerKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_signer_key_id_ref(&self, SignerKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

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

5E70662EA810E768

When a key is loaded, this property is populated with the Id associated with the key. This property may be set to load a key from the signer_key_keyring. When this property is set the struct will search the signer_key_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 signer_key_fingerprint property when loading a key from the signer_key_keyring, as it is possible for different keys to have the same Id.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

Data Type

String

signer_key_fingerprint property (OpenPGP Struct)

The hex-encoded, 20-byte fingerprint of the key.

Syntax

fn signer_key_fingerprint(&self , SignerKeyIndex : i32) -> Result<String, IPWorksPGPError> 
fn set_signer_key_fingerprint(&self, SignerKeyIndex : i32, value : &str) ->  Option<IPWorksPGPError> 
fn set_signer_key_fingerprint_ref(&self, SignerKeyIndex : i32, value : &String) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The hex-encoded, 20-byte fingerprint of the key.

When a key is loaded, this property is populated with the Fingerprint associated with the key. This property may be set to load a key from the signer_key_keyring. When this property is set the struct will search the signer_key_keyring for a key associated with the Fingerprint specified.

This is in the form:

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

Data Type

String

signer_key_encoded property (OpenPGP Struct)

The key.

Syntax

fn signer_key_encoded(&self , SignerKeyIndex : i32) -> Result<Vec<u8>, IPWorksPGPError> 
fn set_signer_key_encoded(&self, SignerKeyIndex : i32, value : Vec<u8>) ->  Option<IPWorksPGPError> 
fn set_signer_key_encoded_ref(&self, SignerKeyIndex : i32, value : &[u8]) ->  Option<IPWorksPGPError> 

Default Value

""

Remarks

The key. This property can be used to assign a specific key. The signer_key_fingerprint, signer_key_id, and signer_key_user_id properties may also be used to specify a key.

The SignerKeyIndex parameter specifies the index of the item in the array. The size of the array is controlled by the SignerKeyCount property.

Data Type

Vec

signing_algorithm property (OpenPGP Struct)

The signature hash algorithm used when signing.

Syntax

fn signing_algorithm(&self ) -> Result<String, IPWorksPGPError> 
fn set_signing_algorithm(&self, value : &str) ->  Option<IPWorksPGPError> 
fn set_signing_algorithm_ref(&self, value : &String) ->  Option<IPWorksPGPError> 

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

Data Type

String

config method (OpenPGP Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksPGPError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

decrypt method (OpenPGP Struct)

Decrypts the message.

Syntax

fn decrypt(&self) -> Result<(), IPWorksPGPError>

Remarks

This method decrypts the specified message.

The message will be decrypted using the keys specified in keys. Before decryption begins the struct will fire the on_recipient_info 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.

decrypt_and_verify_signature method (OpenPGP Struct)

Decrypts and verifies the signature of the message.

Syntax

fn decrypt_and_verify_signature(&self) -> Result<(), IPWorksPGPError>

Remarks

This method attempts to both decrypt and verify the signature of the message. All of the properties affected by calling the decrypt and verify_signature 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 struct will perform the decryption without error.

The message will be decrypted using the keys specified in keys. Before decryption begins the struct will fire the on_recipient_info 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 signer_keys. Before verification begins the struct will fire the on_signature_info 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 signer_keys.

By default, if the signature is not valid the struct fails with an error. The configuration setting RequireValidSignature may be set to False to disable this requirement. When RequireValidSignature is set to False, the Status parameter of the on_verification_status 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 Struct)

Encrypts the message.

Syntax

fn encrypt(&self) -> Result<(), IPWorksPGPError>

Remarks

This method encrypts the specified message.

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

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

• ascii_armor
• compression_method
• encrypting_algorithm

Additionally, CompatibilityProfile may be set to control whether the encrypted message uses RFC 9580 or GnuPG's LibrePGP format; see CompatibilityProfile for details.

get_recipient_info method (OpenPGP Struct)

Gets recipient information for an encrypted message.

Syntax

fn get_recipient_info(&self) -> Result<(), IPWorksPGPError>

Remarks

This method will fire a on_recipient_info 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 Struct)

Interrupt the current method.

Syntax

fn interrupt(&self) -> Result<(), IPWorksPGPError>

Remarks

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

reset method (OpenPGP Struct)

Resets the struct properties.

Syntax

fn reset(&self) -> Result<(), IPWorksPGPError>

Remarks

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

sign method (OpenPGP Struct)

Signs the message.

Syntax

fn sign(&self) -> Result<(), IPWorksPGPError>

Remarks

This method signs the specified message.

The message is signed with the private key specified in the Key* properties.

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

• ascii_armor
• clear_signature
• detached_signature
• signing_algorithm

Additionally, CompatibilityProfile may be set to control whether the signature uses RFC 9580 or GnuPG's LibrePGP format; see CompatibilityProfile for details.

sign_and_encrypt method (OpenPGP Struct)

Signs and encrypts the current message.

Syntax

fn sign_and_encrypt(&self) -> Result<(), IPWorksPGPError>

Remarks

This method signs and encrypts the specified message.

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

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

• ascii_armor
• compression_method
• encrypting_algorithm

Additionally, CompatibilityProfile may be set to control whether the encrypted message uses RFC 9580 or GnuPG's LibrePGP format; see CompatibilityProfile for details.

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

• ascii_armor
• clear_signature
• detached_signature
• signing_algorithm

Additionally, CompatibilityProfile may be set to control whether the signature uses RFC 9580 or GnuPG's LibrePGP format; see CompatibilityProfile for details.

verify_signature method (OpenPGP Struct)

Verifies the signature of the current message.

Syntax

fn verify_signature(&self) -> Result<(), IPWorksPGPError>

Remarks

This method verifies the signature of the message.

The message will be verified using the keys specified in signer_keys. Before verification begins the struct will fire the on_signature_info 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 signer_keys.

By default, if the signature is not valid the struct fails with an error. The configuration setting RequireValidSignature may be set to False to disable this requirement. When RequireValidSignature is set to False, the Status parameter of the on_verification_status event should be checked to determine the result of the operation.

on_error event (OpenPGP Struct)

Fired when information is available about errors during data delivery.

Syntax

// OpenPGPErrorEventArgs carries the OpenPGP Error event's parameters.
pub struct OpenPGPErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// OpenPGPErrorEvent defines the signature of the OpenPGP Error event's handler function.
pub trait OpenPGPErrorEvent {
  fn on_error(&self, sender : OpenPGP, e : &mut OpenPGPErrorEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_error(&self) -> &'a dyn OpenPGPErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn OpenPGPErrorEvent);
  ...
}

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the struct fails with an error.

The error_code parameter contains an error code, and the description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_key_passphrase event (OpenPGP Struct)

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

Syntax

// OpenPGPKeyPassphraseEventArgs carries the OpenPGP KeyPassphrase event's parameters.
pub struct OpenPGPKeyPassphraseEventArgs {
  fn user_id(&self) -> &String
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn passphrase(&self) -> &String
  fn set_passphrase(&self, value : &str)
  fn set_passphrase_ref(&self, value : &String)
}

// OpenPGPKeyPassphraseEvent defines the signature of the OpenPGP KeyPassphrase event's handler function.
pub trait OpenPGPKeyPassphraseEvent {
  fn on_key_passphrase(&self, sender : OpenPGP, e : &mut OpenPGPKeyPassphraseEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_key_passphrase(&self) -> &'a dyn OpenPGPKeyPassphraseEvent;
  pub fn set_on_key_passphrase(&mut self, value : &'a dyn OpenPGPKeyPassphraseEvent);
  ...
}

Remarks

This event fires when the passphrase for the key is required. The passphrase must be specified before operations requiring the secret key are attempted. The passphrase may be supplied by setting the Passphrase parameter in this event, or by specifying the key_passphrase property before attempting the operation.

The passphrase is required when using the following methods in KeyMgr:

• add_user_id
• sign_user_id
• change_expiration_date
• change_passphrase

When using the OpenPGP struct, or an email-based struct, the following methods require a passphrase for the key:

• decrypt
• sign
• sign_and_encrypt

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

The UserId format is:

FirstName LastName (Comment) <Email>

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

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

5E70662EA810E768

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

5E70662EA810E768391A2FE8F7B7D49C89C9D7B1

on_progress event (OpenPGP Struct)

Fired as progress is made.

Syntax

// OpenPGPProgressEventArgs carries the OpenPGP Progress event's parameters.
pub struct OpenPGPProgressEventArgs {
  fn bytes_processed(&self) -> i64
  fn percent_processed(&self) -> i32
  fn operation(&self) -> i32
  fn is_eof(&self) -> bool
  fn set_is_eof(&self, value : bool)
}

// OpenPGPProgressEvent defines the signature of the OpenPGP Progress event's handler function.
pub trait OpenPGPProgressEvent {
  fn on_progress(&self, sender : OpenPGP, e : &mut OpenPGPProgressEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_progress(&self) -> &'a dyn OpenPGPProgressEvent;
  pub fn set_on_progress(&mut self, value : &'a dyn OpenPGPProgressEvent);
  ...
}

Remarks

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

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:

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 struct. When the Operation is Write (2) this value may be queried to determine when all data has been processed.

on_recipient_info event (OpenPGP Struct)

Fired for each recipient key of the encrypted message.

Syntax

// OpenPGPRecipientInfoEventArgs carries the OpenPGP RecipientInfo event's parameters.
pub struct OpenPGPRecipientInfoEventArgs {
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn public_key_algorithm(&self) -> &String
}

// OpenPGPRecipientInfoEvent defines the signature of the OpenPGP RecipientInfo event's handler function.
pub trait OpenPGPRecipientInfoEvent {
  fn on_recipient_info(&self, sender : OpenPGP, e : &mut OpenPGPRecipientInfoEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_recipient_info(&self) -> &'a dyn OpenPGPRecipientInfoEvent;
  pub fn set_on_recipient_info(&mut self, value : &'a dyn OpenPGPRecipientInfoEvent);
  ...
}

Remarks

This event fires when the decrypt or decrypt_and_verify_signature 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 the Key* properties. The Key* properties 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)
• ML-KEM (Subkeys only; LibrePGP/GnuPG)
• ML-KEM-768+X25519 (Subkeys only)
• ML-KEM-1024+X448 (Subkeys only)

on_signature_info event (OpenPGP Struct)

Fired during verification of the signed message.

Syntax

// OpenPGPSignatureInfoEventArgs carries the OpenPGP SignatureInfo event's parameters.
pub struct OpenPGPSignatureInfoEventArgs {
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn signing_algorithm(&self) -> &String
  fn public_key_algorithm(&self) -> &String
}

// OpenPGPSignatureInfoEvent defines the signature of the OpenPGP SignatureInfo event's handler function.
pub trait OpenPGPSignatureInfoEvent {
  fn on_signature_info(&self, sender : OpenPGP, e : &mut OpenPGPSignatureInfoEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_signature_info(&self) -> &'a dyn OpenPGPSignatureInfoEvent;
  pub fn set_on_signature_info(&mut self, value : &'a dyn OpenPGPSignatureInfoEvent);
  ...
}

Remarks

This event fires when the verify_signature or decrypt_and_verify_signature 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 the SignerKey* properties. The SignerKey* properties 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
• ML-DSA-65+Ed25519
• ML-DSA-87+Ed448
• ECDH (Subkeys only)
• X25519 (Subkeys only)
• X448 (Subkeys only)

on_status event (OpenPGP Struct)

Shows the progress of the operation.

Syntax

// OpenPGPStatusEventArgs carries the OpenPGP Status event's parameters.
pub struct OpenPGPStatusEventArgs {
  fn message(&self) -> &String
}

// OpenPGPStatusEvent defines the signature of the OpenPGP Status event's handler function.
pub trait OpenPGPStatusEvent {
  fn on_status(&self, sender : OpenPGP, e : &mut OpenPGPStatusEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_status(&self) -> &'a dyn OpenPGPStatusEvent;
  pub fn set_on_status(&mut self, value : &'a dyn OpenPGPStatusEvent);
  ...
}

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.

on_verification_status event (OpenPGP Struct)

Fired after verification of the signed message.

Syntax

// OpenPGPVerificationStatusEventArgs carries the OpenPGP VerificationStatus event's parameters.
pub struct OpenPGPVerificationStatusEventArgs {
  fn key_id(&self) -> &String
  fn fingerprint(&self) -> &String
  fn status(&self) -> i32
}

// OpenPGPVerificationStatusEvent defines the signature of the OpenPGP VerificationStatus event's handler function.
pub trait OpenPGPVerificationStatusEvent {
  fn on_verification_status(&self, sender : OpenPGP, e : &mut OpenPGPVerificationStatusEventArgs);
}

impl <'a> OpenPGP<'a> {
  pub fn on_verification_status(&self) -> &'a dyn OpenPGPVerificationStatusEvent;
  pub fn set_on_verification_status(&mut self, value : &'a dyn OpenPGPVerificationStatusEvent);
  ...
}

Remarks

This event fires when verify_signature or decrypt_and_verify_signature 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:

Config Settings (OpenPGP Struct)

OpenPGP Config Settings

89011C04000102000605025100459B000A0910E2...

5E70662EA810E768

Base Config Settings

Trappable Errors (OpenPGP Struct)

OpenPGP Errors