# OpenPGP Class The OpenPGP class is used to encrypt/decrypt and sign/verify PGP messages. ## Syntax ```text class ipworkspgp.OpenPGP ``` ## Remarks The OpenPGP class supports encrypting/decrypting and signing/verifying OpenPGP messages. Supported message formats are specified by [RFC 4880](https://datatracker.ietf.org/doc/html/rfc4880), in addition to [RFC 9580](https://datatracker.ietf.org/doc/rfc9580/), which introduces support for OpenPGP Version 6. GnuPG (2.5.x and later) uses its own Version 5 message format (LibrePGP). The class supports creating and processing LibrePGP-formatted messages as well, for interoperability with GnuPG. See [CompatibilityProfile](#CompatibilityProfile) for details on choosing between the two formats. The [encrypt](#encrypt-method), [sign](#sign-method), and [sign_and_encrypt](#sign_and_encrypt-method) 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](#decrypt-method), [verify_signature](#verify_signature-method), and [decrypt_and_verify_signature](#decrypt_and_verify_signature-method) 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 class 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_file-property) - [input_message](#input_message-property) When a valid source is found the search stops. The order in which the output properties are checked is as follows: - [output_file](#output_file-property) - [output_message](#output_message-property): The output data is written to this property if no other destination is specified. ## Property List *The following is the full list of the properties of the class with short descriptions. Click on the links for further details.* | | | | --- | --- | | [ascii_armor](#ascii_armor-property) | Specifies whether to use ASCII armor to encode the output message. | | [auto_select_algorithms](#auto_select_algorithms-property) | Whether to automatically select algorithms when encrypting or signing. | | [clear_signature](#clear_signature-property) | Specifies whether or not to create a cleartext signature. | | [compression_method](#compression_method-property) | The compression algorithm used. | | [detached_signature](#detached_signature-property) | Specifies whether or not to generate a detached signature when signing a message. | | [encrypting_algorithm](#encrypting_algorithm-property) | The encryption algorithm used when encrypting. | | [input_file](#input_file-property) | The file to process. | | [input_message](#input_message-property) | The message to process. | | [key_count](#key_count-property) | The number of records in the Key arrays. | | [key_curve](#key_curve-property) | This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . | | [key_effective_date](#key_effective_date-property) | The date when this key becomes valid. | | [key_encoded](#key_encoded-property) | The key. | | [key_expiration_date](#key_expiration_date-property) | The date the key expires. | | [key_fingerprint](#key_fingerprint-property) | The hex-encoded, 20-byte fingerprint of the key. | | [key_id](#key_id-property) | The hex-encoded, 4-byte or 8-byte key Id. | | [keyring](#keyring-property) | The location of the keyring. | | [key_other_user_ids](#key_other_user_ids-property) | If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. | | [key_passphrase](#key_passphrase-property) | The passphrase for the key's secret key (if any). | | [key_public_key](#key_public_key-property) | The public key of the key. | | [key_public_key_algorithm](#key_public_key_algorithm-property) | A text description of the public key algorithm of the key. | | [key_public_key_length](#key_public_key_length-property) | The length of the public key in bits. | | [key_revoked](#key_revoked-property) | Whether or not the key is revoked. | | [key_secret_key](#key_secret_key-property) | The secret key of the key (if available). | | [key_secret_key_available](#key_secret_key_available-property) | Whether or not a secret key is available for the selected key. | | [key_usage](#key_usage-property) | A text description of UsageFlags . | | [key_usage_flags](#key_usage_flags-property) | Flags that show the intended use for the key. | | [key_user_id](#key_user_id-property) | The user Id of the key. | | [key_version](#key_version-property) | This property can be used to query the OpenPGP version of the currently selected Key . | | [message_header_count](#message_header_count-property) | The number of records in the MessageHeader arrays. | | [message_header_field](#message_header_field-property) | This property contains the name of the HTTP header (this is the same case as it is delivered). | | [message_header_value](#message_header_value-property) | This property contains the header contents. | | [output_file](#output_file-property) | The output file. | | [output_message](#output_message-property) | The output message after processing. | | [overwrite](#overwrite-property) | Indicates whether or not the class should overwrite files. | | [recipient_key_count](#recipient_key_count-property) | The number of records in the RecipientKey arrays. | | [recipient_key_curve](#recipient_key_curve-property) | This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . | | [recipient_key_effective_date](#recipient_key_effective_date-property) | The date when this key becomes valid. | | [recipient_key_encoded](#recipient_key_encoded-property) | The key. | | [recipient_key_expiration_date](#recipient_key_expiration_date-property) | The date the key expires. | | [recipient_key_fingerprint](#recipient_key_fingerprint-property) | The hex-encoded, 20-byte fingerprint of the key. | | [recipient_key_id](#recipient_key_id-property) | The hex-encoded, 4-byte or 8-byte key Id. | | [recipient_key_keyring](#recipient_key_keyring-property) | The location of the keyring. | | [recipient_key_other_user_ids](#recipient_key_other_user_ids-property) | If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. | | [recipient_key_passphrase](#recipient_key_passphrase-property) | The passphrase for the key's secret key (if any). | | [recipient_key_public_key](#recipient_key_public_key-property) | The public key of the key. | | [recipient_key_public_key_algorithm](#recipient_key_public_key_algorithm-property) | A text description of the public key algorithm of the key. | | [recipient_key_public_key_length](#recipient_key_public_key_length-property) | The length of the public key in bits. | | [recipient_key_revoked](#recipient_key_revoked-property) | Whether or not the key is revoked. | | [recipient_key_secret_key](#recipient_key_secret_key-property) | The secret key of the key (if available). | | [recipient_key_secret_key_available](#recipient_key_secret_key_available-property) | Whether or not a secret key is available for the selected key. | | [recipient_key_usage](#recipient_key_usage-property) | A text description of UsageFlags . | | [recipient_key_usage_flags](#recipient_key_usage_flags-property) | Flags that show the intended use for the key. | | [recipient_key_user_id](#recipient_key_user_id-property) | The user Id of the key. | | [recipient_key_version](#recipient_key_version-property) | This property can be used to query the OpenPGP version of the currently selected Key . | | [signer_key_count](#signer_key_count-property) | The number of records in the SignerKey arrays. | | [signer_key_curve](#signer_key_curve-property) | This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . | | [signer_key_effective_date](#signer_key_effective_date-property) | The date when this key becomes valid. | | [signer_key_encoded](#signer_key_encoded-property) | The key. | | [signer_key_expiration_date](#signer_key_expiration_date-property) | The date the key expires. | | [signer_key_fingerprint](#signer_key_fingerprint-property) | The hex-encoded, 20-byte fingerprint of the key. | | [signer_key_id](#signer_key_id-property) | The hex-encoded, 4-byte or 8-byte key Id. | | [signer_key_keyring](#signer_key_keyring-property) | The location of the keyring. | | [signer_key_other_user_ids](#signer_key_other_user_ids-property) | If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. | | [signer_key_passphrase](#signer_key_passphrase-property) | The passphrase for the key's secret key (if any). | | [signer_key_public_key](#signer_key_public_key-property) | The public key of the key. | | [signer_key_public_key_algorithm](#signer_key_public_key_algorithm-property) | A text description of the public key algorithm of the key. | | [signer_key_public_key_length](#signer_key_public_key_length-property) | The length of the public key in bits. | | [signer_key_revoked](#signer_key_revoked-property) | Whether or not the key is revoked. | | [signer_key_secret_key](#signer_key_secret_key-property) | The secret key of the key (if available). | | [signer_key_secret_key_available](#signer_key_secret_key_available-property) | Whether or not a secret key is available for the selected key. | | [signer_key_usage](#signer_key_usage-property) | A text description of UsageFlags . | | [signer_key_usage_flags](#signer_key_usage_flags-property) | Flags that show the intended use for the key. | | [signer_key_user_id](#signer_key_user_id-property) | The user Id of the key. | | [signer_key_version](#signer_key_version-property) | This property can be used to query the OpenPGP version of the currently selected Key . | | [signing_algorithm](#signing_algorithm-property) | The signature hash algorithm used when signing. | ## Method List *The following is the full list of the methods of the class with short descriptions. Click on the links for further details.* | | | | --- | --- | | [config](#config-method) | Sets or retrieves a configuration setting. | | [decrypt](#decrypt-method) | Decrypts the message. | | [decrypt_and_verify_signature](#decrypt_and_verify_signature-method) | Decrypts and verifies the signature of the message. | | [encrypt](#encrypt-method) | Encrypts the message. | | [get_recipient_info](#get_recipient_info-method) | Gets recipient information for an encrypted message. | | [interrupt](#interrupt-method) | Interrupt the current method. | | [reset](#reset-method) | Resets the class properties. | | [sign](#sign-method) | Signs the message. | | [sign_and_encrypt](#sign_and_encrypt-method) | Signs and encrypts the current message. | | [verify_signature](#verify_signature-method) | Verifies the signature of the current message. | ## Event List *The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.* | | | | --- | --- | | [on_error](#on_error-event) | Fired when information is available about errors during data delivery. | | [on_key_passphrase](#on_key_passphrase-event) | Fired if the passphrase of current key is incorrect or empty. | | [on_progress](#on_progress-event) | Fired as progress is made. | | [on_recipient_info](#on_recipient_info-event) | Fired for each recipient key of the encrypted message. | | [on_signature_info](#on_signature_info-event) | Fired during verification of the signed message. | | [on_status](#on_status-event) | Shows the progress of the operation. | | [on_verification_status](#on_verification_status-event) | Fired after verification of the signed message. | ## Config Settings *The following is a list of config settings for the class with short descriptions. Click on the links for further details.* | | | | --- | --- | | [AEADChunkSizeExp](#AEADChunkSizeExp) | Specifies the exponent used to calculate the plaintext chunk size for encryption. | | [AllowEmptyInput](#AllowEmptyInput) | Whether to allow empty files for input. | | [AllowOldPacketType](#AllowOldPacketType) | Whether to allow the older encrypted packet type. | | [Argon2Iterations](#Argon2Iterations) | Specifies the number of iterations used for Argon2. | | [Argon2MemorySizeExp](#Argon2MemorySizeExp) | Specifies the exponent used to calculate the memory size used when creating a key. | | [Argon2Parallelism](#Argon2Parallelism) | Specifies the degree of parallelism used for Argon2. | | [CloseInputStreamAfterProcessing](#CloseInputStreamAfterProcessing) | Determines whether or not the input stream is closed after processing. | | [CloseOutputStreamAfterProcessing](#CloseOutputStreamAfterProcessing) | Determines whether or not the output stream is closed after processing. | | [CompatibilityProfile](#CompatibilityProfile) | Specifies the OpenPGP compatibility profile used when creating messages. | | [CompressionLevel](#CompressionLevel) | The level of compression used. | | [DeleteOutputFileOnError](#DeleteOutputFileOnError) | Whether to delete the output file on an error. | | [DetachedSignatureData](#DetachedSignatureData) | The detached signature. | | [EnsureValidDSASignatureHashAlgorithm](#EnsureValidDSASignatureHashAlgorithm) | Whether or not to select a suitable signature hash algorithm automatically. | | [FileName](#FileName) | The original name of the encrypted file. | | [KeyIdLength](#KeyIdLength) | The length of the KeyId available. | | [KeySelectionMethod](#KeySelectionMethod) | The method used to select a key for encryption or signing. | | [LogLevel](#LogLevel) | Specifies the level of detail that is logged. | | [PGPZipDir](#PGPZipDir) | The directory used when creating or extracting a PGP zip file. | | [ProgressEventThreshold](#ProgressEventThreshold) | The amount of data in bytes to process before firing the progress event. | | [PublicKeyringFile](#PublicKeyringFile) | The file name of the public keyring file. | | [ReadFromProgressEvent](#ReadFromProgressEvent) | Whether to read input data from inside the progress event. | | [RecursiveDecryptMode](#RecursiveDecryptMode) | Whether the encrypted data should be decrypted recursively. | | [RequireEncryption](#RequireEncryption) | Whether to throw an error when decrypting and encryption is not detected. | | [RequireIntegrityProtectedPacket](#RequireIntegrityProtectedPacket) | Whether an MDC packet is required for decryption. | | [RequireSignature](#RequireSignature) | Whether to throw an error when verifying a signature and no signature is found. | | [RequireValidSignature](#RequireValidSignature) | Specifies if an invalid signature is considered an error condition. | | [S2KAlgorithm](#S2KAlgorithm) | Specifies the algorithm for S2K key derivation. | | [S2KIterations](#S2KIterations) | Sets the number of iterations for S2K key derivation. | | [SecretKeyringFile](#SecretKeyringFile) | The file name of the secret keyring file. | | [SplitHeaders](#SplitHeaders) | Controls whether ASCII Armor headers are split or not. | | [SymmetricPassphrase](#SymmetricPassphrase) | The password used for symmetric encryption or decryption. | | [UseArgon2](#UseArgon2) | Whether to use Argon2 for key derivation during symmetric encryption or decryption. | | [UseMemoryMode](#UseMemoryMode) | Determines whether the entire message is loaded into memory prior to encryption or decryption. | | [UsePlatformAES](#UsePlatformAES) | Whether to use the platform AES implementation. | | [VerifyClearTextSignatureWithCache](#VerifyClearTextSignatureWithCache) | Whether the cleartext message is cached in memory when verifying a cleartext signature. | | [VersionHeader](#VersionHeader) | The Version header value in the ASCII armored OpenPGP message. | | [WriteToProgressEvent](#WriteToProgressEvent) | Whether to write output data so it is accessible from inside the progress event. | | [BuildInfo](#BuildInfo) | Information about the product's build. | | [CodePage](#CodePage) | The system code page used for Unicode to Multibyte translations. | | [LicenseInfo](#LicenseInfo) | Information about the current license. | | [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. | | [ProcessIdleEvents](#ProcessIdleEvents) | Whether the class uses its internal event loop to process events when the main thread is idle. | | [SelectWaitMillis](#SelectWaitMillis) | The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process. | | [UseFIPSCompliantAPI](#UseFIPSCompliantAPI) | Tells the class whether or not to use FIPS certified APIs. | | [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. | # ascii_armor property Specifies whether to use ASCII armor to encode the output message. ## Syntax ```text def get_ascii_armor() -> bool: ... def set_ascii_armor(value: bool) -> None: ... ascii_armor = property(get_ascii_armor, set_ascii_armor) ``` ## Default Value FALSE ## Remarks This property controls whether or not ASCII armoring is used on the output message. The default value is False. # auto_select_algorithms property Whether to automatically select algorithms when encrypting or signing. ## Syntax ```text def get_auto_select_algorithms() -> int: ... def set_auto_select_algorithms(value: int) -> None: ... auto_select_algorithms = property(get_auto_select_algorithms, set_auto_select_algorithms) ``` ## 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](#encrypt-method) is called the class 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](#encrypting_algorithm-property) and [compression_method](#compression_method-property) properties are ignored. When [sign](#sign-method) is called the class 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](#signing_algorithm-property) and [compression_method](#compression_method-property) 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. # clear_signature property Specifies whether or not to create a cleartext signature. ## Syntax ```text def get_clear_signature() -> bool: ... def set_clear_signature(value: bool) -> None: ... clear_signature = property(get_clear_signature, set_clear_signature) ``` ## 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](#sign-method) is called. # compression_method property The compression algorithm used. ## Syntax ```text def get_compression_method() -> str: ... def set_compression_method(value: str) -> None: ... compression_method = property(get_compression_method, set_compression_method) ``` ## 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](#CompressionLevel) setting. # detached_signature property Specifies whether or not to generate a detached signature when signing a message. ## Syntax ```text def get_detached_signature() -> bool: ... def set_detached_signature(value: bool) -> None: ... detached_signature = property(get_detached_signature, set_detached_signature) ``` ## 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](#clear_signature-property) 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. # encrypting_algorithm property The encryption algorithm used when encrypting. ## Syntax ```text def get_encrypting_algorithm() -> str: ... def set_encrypting_algorithm(value: str) -> None: ... encrypting_algorithm = property(get_encrypting_algorithm, set_encrypting_algorithm) ``` ## 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 class uses a modified form of CFB mode in accordance with the OpenPGP standard. Note that if [UseArgon2](#UseArgon2) is enabled, and [SymmetricPassphrase](#SymmetricPassphrase) is specified, an AEAD encryption algorithm (*AES*-OCB* and *AES*-GCM*) must be specified for symmetric encryption. If [UseArgon2](#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](#encrypt-method)). In this case, the [AEADChunkSizeExp](#AEADChunkSizeExp) configuration will specify the chunk size for splitting plaintext for encryption. Please see [AEADChunkSizeExp](#AEADChunkSizeExp) for additional details. # input_file property The file to process. ## Syntax ```text def get_input_file() -> str: ... def set_input_file(value: str) -> None: ... input_file = property(get_input_file, set_input_file) ``` ## 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 class 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](#input_message-property) When a valid source is found the search stops. The order in which the output properties are checked is as follows: - [output_file](#output_file-property) - [output_message](#output_message-property): The output data is written to this property if no other destination is specified. # input_message property The message to process. ## Syntax ```text def get_input_message() -> bytes: ... def set_input_message(value: bytes) -> None: ... input_message = property(get_input_message, set_input_message) ``` ## Default Value "" ## Remarks This property specifies the message to be processed. Set this property to the OpenPGP message content. **Input and Output Properties** The class 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_file-property) - 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_file-property) - [output_message](#output_message-property): The output data is written to this property if no other destination is specified. # key_count property The number of records in the Key arrays. ## Syntax ```text def get_key_count() -> int: ... def set_key_count(value: int) -> None: ... key_count = property(get_key_count, set_key_count) ``` ## Default Value 0 ## Remarks This property controls the size of the following arrays: - [key_curve](#key_curve-property) - [key_effective_date](#key_effective_date-property) - [key_encoded](#key_encoded-property) - [key_expiration_date](#key_expiration_date-property) - [key_fingerprint](#key_fingerprint-property) - [key_id](#key_id-property) - [key_other_user_ids](#key_other_user_ids-property) - [key_passphrase](#key_passphrase-property) - [key_public_key](#key_public_key-property) - [key_public_key_algorithm](#key_public_key_algorithm-property) - [key_public_key_length](#key_public_key_length-property) - [key_revoked](#key_revoked-property) - [keyring](#keyring-property) - [key_secret_key](#key_secret_key-property) - [key_secret_key_available](#key_secret_key_available-property) - [key_usage](#key_usage-property) - [key_usage_flags](#key_usage_flags-property) - [key_user_id](#key_user_id-property) - [key_version](#key_version-property) The array indices start at *0* and end at *key_count - 1*. # key_curve property This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . ## Syntax ```text def get_key_curve(key_index: int) -> str: ... ``` ## Default Value "" ## Remarks This property specifies the elliptic curve if [key_public_key_algorithm](#key_public_key_algorithm-property) is *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448*. Possible values are: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_effective_date property The date when this key becomes valid. ## Syntax ```text def get_key_effective_date(key_index: int) -> str: ... ``` ## 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 *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_encoded property The key. ## Syntax ```text def get_key_encoded(key_index: int) -> bytes: ... def set_key_encoded(key_index: int, value: bytes) -> None: ... ``` ## Default Value "" ## Remarks The key. This property can be used to assign a specific key. The [key_fingerprint](#key_fingerprint-property), [key_id](#key_id-property), and [key_user_id](#key_user_id-property) properties may also be used to specify a key. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. # key_expiration_date property The date the key expires. ## Syntax ```text def get_key_expiration_date(key_index: int) -> str: ... ``` ## 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 *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_fingerprint property The hex-encoded, 20-byte fingerprint of the key. ## Syntax ```text def get_key_fingerprint(key_index: int) -> str: ... def set_key_fingerprint(key_index: int, value: str) -> None: ... ``` ## 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 [keyring](#OpenPGP_p_KeyKeyring). When this property is set the class will search the [keyring](#OpenPGP_p_KeyKeyring) for a key associated with the Fingerprint specified. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. # key_id property The hex-encoded, 4-byte or 8-byte key Id. ## Syntax ```text def get_key_id(key_index: int) -> str: ... def set_key_id(key_index: int, value: str) -> None: ... ``` ## 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: ```text 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 [keyring](#OpenPGP_p_KeyKeyring). When this property is set the class will search the [keyring](#OpenPGP_p_KeyKeyring) 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](#key_fingerprint-property) property when loading a key from the [keyring](#OpenPGP_p_KeyKeyring), as it is possible for different keys to have the same Id. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. # keyring property The location of the keyring. ## Syntax ```text def get_keyring(key_index: int) -> str: ... def set_keyring(key_index: int, value: str) -> None: ... ``` ## 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 class will read the keyring and populate the key property with the first key found in the keyring. Set [key_user_id](#KeyMgr_p_KeyUserId) to select a different key in the current keyring. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. # key_other_user_ids property If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. ## Syntax ```text def get_key_other_user_ids(key_index: int) -> str: ... ``` ## 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 *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_passphrase property The passphrase for the key's secret key (if any). ## Syntax ```text def get_key_passphrase(key_index: int) -> str: ... def set_key_passphrase(key_index: int, value: str) -> None: ... ``` ## 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 class, or an email-based class, the following methods require a passphrase for the key: - decrypt - sign - sign_and_encrypt The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. # key_public_key property The public key of the key. ## Syntax ```text def get_key_public_key(key_index: int) -> str: ... ``` ## Default Value "" ## Remarks The public key of the key. The key is provided as ASCII armored data. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_public_key_algorithm property A text description of the public key algorithm of the key. ## Syntax ```text def get_key_public_key_algorithm(key_index: int) -> str: ... ``` ## 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 *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_public_key_length property The length of the public key in bits. ## Syntax ```text def get_key_public_key_length(key_index: int) -> int: ... ``` ## 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](#key_public_key_algorithm-property) 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](#key_curve-property). Possible lengths are: | Curve | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_revoked property Whether or not the key is revoked. ## Syntax ```text def get_key_revoked(key_index: int) -> bool: ... ``` ## Default Value FALSE ## Remarks Whether or not the key is revoked. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_secret_key property The secret key of the key (if available). ## Syntax ```text def get_key_secret_key(key_index: int) -> str: ... ``` ## Default Value "" ## Remarks The secret key of the key (if available). The key is provided as ASCII armored data. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_secret_key_available property Whether or not a secret key is available for the selected key. ## Syntax ```text def get_key_secret_key_available(key_index: int) -> bool: ... ``` ## Default Value FALSE ## Remarks Whether or not a secret key is available for the selected key. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_usage property A text description of UsageFlags . ## Syntax ```text def get_key_usage(key_index: int) -> str: ... ``` ## Default Value "" ## Remarks A text description of [key_usage_flags](#key_usage_flags-property). 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 *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_usage_flags property Flags that show the intended use for the key. ## Syntax ```text def get_key_usage_flags(key_index: int) -> int: ... ``` ## Default Value 47 ## Remarks Flags that show the intended use for the key. The default value is 0x0F. The value of [key_usage_flags](#key_usage_flags-property) is a combination of the following flags: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | Please refer to the [key_usage](#key_usage-property) property for a text representation of [key_usage_flags](#key_usage_flags-property). The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # key_user_id property The user Id of the key. ## Syntax ```text def get_key_user_id(key_index: int) -> str: ... def set_key_user_id(key_index: int, value: str) -> None: ... ``` ## 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 [keyring](#OpenPGP_p_KeyKeyring). When this property is set the class will search the [keyring](#OpenPGP_p_KeyKeyring) 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](#KeyMgr_p_KeyOtherUserIds) after loading the key. The *UserId* format is: ```text FirstName LastName (Comment) ``` Not all values are required when selecting or generating a key, but at least FirstName or Email are required. Note that for OpenPGP v6, a key may be created with or without a *UserId*, as the field is optional. If a key was created without a *UserId*, the key's *Fingerprint* can be used as its identifier instead. When using this 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 class 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 class's on_recipient_info event. The *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. # key_version property This property can be used to query the OpenPGP version of the currently selected Key . ## Syntax ```text def get_key_version(key_index: int) -> int: ... ``` ## 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 *key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [key_count](#key_count-property) property. This property is read-only. # message_header_count property The number of records in the MessageHeader arrays. ## Syntax ```text def get_message_header_count() -> int: ... def set_message_header_count(value: int) -> None: ... message_header_count = property(get_message_header_count, set_message_header_count) ``` ## Default Value 0 ## Remarks This property controls the size of the following arrays: - [message_header_field](#message_header_field-property) - [message_header_value](#message_header_value-property) The array indices start at *0* and end at *message_header_count - 1*. # message_header_field property This property contains the name of the HTTP header (this is the same case as it is delivered). ## Syntax ```text def get_message_header_field(message_header_index: int) -> str: ... def set_message_header_field(message_header_index: int, value: str) -> None: ... ``` ## Default Value "" ## Remarks This property contains the name of the HTTP [Header](#Type_Header) (this is the same case as it is delivered). The *message_header_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [message_header_count](#message_header_count-property) property. # message_header_value property This property contains the header contents. ## Syntax ```text def get_message_header_value(message_header_index: int) -> str: ... def set_message_header_value(message_header_index: int, value: str) -> None: ... ``` ## Default Value "" ## Remarks This property contains the [Header](#Type_Header) contents. The *message_header_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [message_header_count](#message_header_count-property) property. # output_file property The output file. ## Syntax ```text def get_output_file() -> str: ... def set_output_file(value: str) -> None: ... output_file = property(get_output_file, set_output_file) ``` ## 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 class 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_file-property) - [input_message](#input_message-property) 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](#output_message-property): The output data is written to this property if no other destination is specified. # output_message property The output message after processing. ## Syntax ```text def get_output_message() -> bytes: ... def set_output_message(value: bytes) -> None: ... output_message = property(get_output_message, set_output_message) ``` ## Default Value "" ## Remarks This property will be populated with the output from the operation if [output_file](#output_file-property) is not set. **Input and Output Properties** The class 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_file-property) - [input_message](#input_message-property) When a valid source is found the search stops. The order in which the output properties are checked is as follows: - [output_file](#output_file-property) - output_message: The output data is written to this property if no other destination is specified. # overwrite property Indicates whether or not the class should overwrite files. ## Syntax ```text def get_overwrite() -> bool: ... def set_overwrite(value: bool) -> None: ... overwrite = property(get_overwrite, set_overwrite) ``` ## Default Value FALSE ## Remarks This property indicates whether or not the class will overwrite [output_file](#output_file-property). If overwrite is False, an error will be thrown whenever [output_file](#output_file-property) exists before an operation. The default value is False. # recipient_key_count property The number of records in the RecipientKey arrays. ## Syntax ```text def get_recipient_key_count() -> int: ... def set_recipient_key_count(value: int) -> None: ... recipient_key_count = property(get_recipient_key_count, set_recipient_key_count) ``` ## Default Value 0 ## Remarks This property controls the size of the following arrays: - [recipient_key_curve](#recipient_key_curve-property) - [recipient_key_effective_date](#recipient_key_effective_date-property) - [recipient_key_encoded](#recipient_key_encoded-property) - [recipient_key_expiration_date](#recipient_key_expiration_date-property) - [recipient_key_fingerprint](#recipient_key_fingerprint-property) - [recipient_key_id](#recipient_key_id-property) - [recipient_key_keyring](#recipient_key_keyring-property) - [recipient_key_other_user_ids](#recipient_key_other_user_ids-property) - [recipient_key_passphrase](#recipient_key_passphrase-property) - [recipient_key_public_key](#recipient_key_public_key-property) - [recipient_key_public_key_algorithm](#recipient_key_public_key_algorithm-property) - [recipient_key_public_key_length](#recipient_key_public_key_length-property) - [recipient_key_revoked](#recipient_key_revoked-property) - [recipient_key_secret_key](#recipient_key_secret_key-property) - [recipient_key_secret_key_available](#recipient_key_secret_key_available-property) - [recipient_key_usage](#recipient_key_usage-property) - [recipient_key_usage_flags](#recipient_key_usage_flags-property) - [recipient_key_user_id](#recipient_key_user_id-property) - [recipient_key_version](#recipient_key_version-property) The array indices start at *0* and end at *recipient_key_count - 1*. # recipient_key_curve property This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . ## Syntax ```text def get_recipient_key_curve(recipient_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks This property specifies the elliptic curve if [recipient_key_public_key_algorithm](#recipient_key_public_key_algorithm-property) is *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448*. Possible values are: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_effective_date property The date when this key becomes valid. ## Syntax ```text def get_recipient_key_effective_date(recipient_key_index: int) -> str: ... ``` ## 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 *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_encoded property The key. ## Syntax ```text def get_recipient_key_encoded(recipient_key_index: int) -> bytes: ... def set_recipient_key_encoded(recipient_key_index: int, value: bytes) -> None: ... ``` ## Default Value "" ## Remarks The key. This property can be used to assign a specific key. The [recipient_key_fingerprint](#recipient_key_fingerprint-property), [recipient_key_id](#recipient_key_id-property), and [recipient_key_user_id](#recipient_key_user_id-property) properties may also be used to specify a key. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. # recipient_key_expiration_date property The date the key expires. ## Syntax ```text def get_recipient_key_expiration_date(recipient_key_index: int) -> str: ... ``` ## 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 *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_fingerprint property The hex-encoded, 20-byte fingerprint of the key. ## Syntax ```text def get_recipient_key_fingerprint(recipient_key_index: int) -> str: ... def set_recipient_key_fingerprint(recipient_key_index: int, value: str) -> None: ... ``` ## 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](#recipient_key_keyring-property). When this property is set the class will search the [recipient_key_keyring](#recipient_key_keyring-property) for a key associated with the Fingerprint specified. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. # recipient_key_id property The hex-encoded, 4-byte or 8-byte key Id. ## Syntax ```text def get_recipient_key_id(recipient_key_index: int) -> str: ... def set_recipient_key_id(recipient_key_index: int, value: str) -> None: ... ``` ## 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: ```text 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](#recipient_key_keyring-property). When this property is set the class will search the [recipient_key_keyring](#recipient_key_keyring-property) 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](#recipient_key_fingerprint-property) property when loading a key from the [recipient_key_keyring](#recipient_key_keyring-property), as it is possible for different keys to have the same Id. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. # recipient_key_keyring property The location of the keyring. ## Syntax ```text def get_recipient_key_keyring(recipient_key_index: int) -> str: ... def set_recipient_key_keyring(recipient_key_index: int, value: str) -> None: ... ``` ## 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 class will read the keyring and populate the key property with the first key found in the keyring. Set [key_user_id](#KeyMgr_p_KeyUserId) to select a different key in the current keyring. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. # recipient_key_other_user_ids property If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. ## Syntax ```text def get_recipient_key_other_user_ids(recipient_key_index: int) -> str: ... ``` ## 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 *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_passphrase property The passphrase for the key's secret key (if any). ## Syntax ```text def get_recipient_key_passphrase(recipient_key_index: int) -> str: ... def set_recipient_key_passphrase(recipient_key_index: int, value: str) -> None: ... ``` ## 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 class, or an email-based class, the following methods require a passphrase for the key: - decrypt - sign - sign_and_encrypt The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. # recipient_key_public_key property The public key of the key. ## Syntax ```text def get_recipient_key_public_key(recipient_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks The public key of the key. The key is provided as ASCII armored data. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_public_key_algorithm property A text description of the public key algorithm of the key. ## Syntax ```text def get_recipient_key_public_key_algorithm(recipient_key_index: int) -> str: ... ``` ## 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 *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_public_key_length property The length of the public key in bits. ## Syntax ```text def get_recipient_key_public_key_length(recipient_key_index: int) -> int: ... ``` ## 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](#recipient_key_public_key_algorithm-property) 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](#recipient_key_curve-property). Possible lengths are: | Curve | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_revoked property Whether or not the key is revoked. ## Syntax ```text def get_recipient_key_revoked(recipient_key_index: int) -> bool: ... ``` ## Default Value FALSE ## Remarks Whether or not the key is revoked. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_secret_key property The secret key of the key (if available). ## Syntax ```text def get_recipient_key_secret_key(recipient_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks The secret key of the key (if available). The key is provided as ASCII armored data. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_secret_key_available property Whether or not a secret key is available for the selected key. ## Syntax ```text def get_recipient_key_secret_key_available(recipient_key_index: int) -> bool: ... ``` ## Default Value FALSE ## Remarks Whether or not a secret key is available for the selected key. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_usage property A text description of UsageFlags . ## Syntax ```text def get_recipient_key_usage(recipient_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks A text description of [recipient_key_usage_flags](#recipient_key_usage_flags-property). 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 *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_usage_flags property Flags that show the intended use for the key. ## Syntax ```text def get_recipient_key_usage_flags(recipient_key_index: int) -> int: ... ``` ## 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](#recipient_key_usage_flags-property) is a combination of the following flags: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | Please refer to the [recipient_key_usage](#recipient_key_usage-property) property for a text representation of [recipient_key_usage_flags](#recipient_key_usage_flags-property). The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # recipient_key_user_id property The user Id of the key. ## Syntax ```text def get_recipient_key_user_id(recipient_key_index: int) -> str: ... def set_recipient_key_user_id(recipient_key_index: int, value: str) -> None: ... ``` ## 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](#recipient_key_keyring-property). When this property is set the class will search the [recipient_key_keyring](#recipient_key_keyring-property) 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](#KeyMgr_p_KeyOtherUserIds) after loading the key. The *UserId* format is: ```text FirstName LastName (Comment) ``` Not all values are required when selecting or generating a key, but at least FirstName or Email are required. Note that for OpenPGP v6, a key may be created with or without a *UserId*, as the field is optional. If a key was created without a *UserId*, the key's *Fingerprint* can be used as its identifier instead. When using this 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 class 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 class's on_recipient_info event. The *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. # recipient_key_version property This property can be used to query the OpenPGP version of the currently selected Key . ## Syntax ```text def get_recipient_key_version(recipient_key_index: int) -> int: ... ``` ## 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 *recipient_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [recipient_key_count](#recipient_key_count-property) property. This property is read-only. # signer_key_count property The number of records in the SignerKey arrays. ## Syntax ```text def get_signer_key_count() -> int: ... def set_signer_key_count(value: int) -> None: ... signer_key_count = property(get_signer_key_count, set_signer_key_count) ``` ## Default Value 0 ## Remarks This property controls the size of the following arrays: - [signer_key_curve](#signer_key_curve-property) - [signer_key_effective_date](#signer_key_effective_date-property) - [signer_key_encoded](#signer_key_encoded-property) - [signer_key_expiration_date](#signer_key_expiration_date-property) - [signer_key_fingerprint](#signer_key_fingerprint-property) - [signer_key_id](#signer_key_id-property) - [signer_key_keyring](#signer_key_keyring-property) - [signer_key_other_user_ids](#signer_key_other_user_ids-property) - [signer_key_passphrase](#signer_key_passphrase-property) - [signer_key_public_key](#signer_key_public_key-property) - [signer_key_public_key_algorithm](#signer_key_public_key_algorithm-property) - [signer_key_public_key_length](#signer_key_public_key_length-property) - [signer_key_revoked](#signer_key_revoked-property) - [signer_key_secret_key](#signer_key_secret_key-property) - [signer_key_secret_key_available](#signer_key_secret_key_available-property) - [signer_key_usage](#signer_key_usage-property) - [signer_key_usage_flags](#signer_key_usage_flags-property) - [signer_key_user_id](#signer_key_user_id-property) - [signer_key_version](#signer_key_version-property) The array indices start at *0* and end at *signer_key_count - 1*. # signer_key_curve property This property specifies the elliptic curve if PublicKeyAlgorithm is ECDSA , EdDSA , Ed25519 , Ed448 , ML-DSA-65+Ed25519 , or ML-DSA-87+Ed448 . ## Syntax ```text def get_signer_key_curve(signer_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks This property specifies the elliptic curve if [signer_key_public_key_algorithm](#signer_key_public_key_algorithm-property) is *ECDSA*, *EdDSA*, *Ed25519*, *Ed448*, *ML-DSA-65+Ed25519*, or *ML-DSA-87+Ed448*. Possible values are: | Curve | Valid Public Key Algorithms | Description | | --- | --- | --- | | secp256r1 | ECDSA | NIST curve P-256 | | secp384r1 | ECDSA | NIST curve P-384 | | secp521r1 | ECDSA | NIST curve P-521 | | secp256k1 | ECDSA | Secp256k1 | | brainpoolP256r1 | ECDSA | Brainpool curve P-256r1 | | brainpoolP384r1 | ECDSA | Brainpool curve P-384r1 | | brainpoolP512r1 | ECDSA | Brainpool curve P-512r1 | | Ed25519 | EdDSA, Ed25519, ML-DSA-65+Ed25519 | Ed25519 | | Ed448 | Ed448, ML-DSA-87+Ed448 | Ed448 | The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_effective_date property The date when this key becomes valid. ## Syntax ```text def get_signer_key_effective_date(signer_key_index: int) -> str: ... ``` ## 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 *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_encoded property The key. ## Syntax ```text def get_signer_key_encoded(signer_key_index: int) -> bytes: ... def set_signer_key_encoded(signer_key_index: int, value: bytes) -> None: ... ``` ## Default Value "" ## Remarks The key. This property can be used to assign a specific key. The [signer_key_fingerprint](#signer_key_fingerprint-property), [signer_key_id](#signer_key_id-property), and [signer_key_user_id](#signer_key_user_id-property) properties may also be used to specify a key. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. # signer_key_expiration_date property The date the key expires. ## Syntax ```text def get_signer_key_expiration_date(signer_key_index: int) -> str: ... ``` ## 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 *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_fingerprint property The hex-encoded, 20-byte fingerprint of the key. ## Syntax ```text def get_signer_key_fingerprint(signer_key_index: int) -> str: ... def set_signer_key_fingerprint(signer_key_index: int, value: str) -> None: ... ``` ## 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](#signer_key_keyring-property). When this property is set the class will search the [signer_key_keyring](#signer_key_keyring-property) for a key associated with the Fingerprint specified. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. # signer_key_id property The hex-encoded, 4-byte or 8-byte key Id. ## Syntax ```text def get_signer_key_id(signer_key_index: int) -> str: ... def set_signer_key_id(signer_key_index: int, value: str) -> None: ... ``` ## 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: ```text 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](#signer_key_keyring-property). When this property is set the class will search the [signer_key_keyring](#signer_key_keyring-property) 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](#signer_key_fingerprint-property) property when loading a key from the [signer_key_keyring](#signer_key_keyring-property), as it is possible for different keys to have the same Id. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. # signer_key_keyring property The location of the keyring. ## Syntax ```text def get_signer_key_keyring(signer_key_index: int) -> str: ... def set_signer_key_keyring(signer_key_index: int, value: str) -> None: ... ``` ## 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 class will read the keyring and populate the key property with the first key found in the keyring. Set [key_user_id](#KeyMgr_p_KeyUserId) to select a different key in the current keyring. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. # signer_key_other_user_ids property If the specified key has alternate user Ids associated with it, this property returns a comma-separated list of the other user Ids. ## Syntax ```text def get_signer_key_other_user_ids(signer_key_index: int) -> str: ... ``` ## 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 *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_passphrase property The passphrase for the key's secret key (if any). ## Syntax ```text def get_signer_key_passphrase(signer_key_index: int) -> str: ... def set_signer_key_passphrase(signer_key_index: int, value: str) -> None: ... ``` ## 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 class, or an email-based class, the following methods require a passphrase for the key: - decrypt - sign - sign_and_encrypt The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. # signer_key_public_key property The public key of the key. ## Syntax ```text def get_signer_key_public_key(signer_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks The public key of the key. The key is provided as ASCII armored data. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_public_key_algorithm property A text description of the public key algorithm of the key. ## Syntax ```text def get_signer_key_public_key_algorithm(signer_key_index: int) -> str: ... ``` ## 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 *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_public_key_length property The length of the public key in bits. ## Syntax ```text def get_signer_key_public_key_length(signer_key_index: int) -> int: ... ``` ## 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](#signer_key_public_key_algorithm-property) 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](#signer_key_curve-property). Possible lengths are: | Curve | Public Key Length (bits) | | --- | --- | | secp256r1 | 256 | | secp384r1 | 384 | | secp521r1 | 528 | | secp256k1 | 256 | | Ed25519 | 256 | | Ed448 | 456 | The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_revoked property Whether or not the key is revoked. ## Syntax ```text def get_signer_key_revoked(signer_key_index: int) -> bool: ... ``` ## Default Value FALSE ## Remarks Whether or not the key is revoked. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_secret_key property The secret key of the key (if available). ## Syntax ```text def get_signer_key_secret_key(signer_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks The secret key of the key (if available). The key is provided as ASCII armored data. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_secret_key_available property Whether or not a secret key is available for the selected key. ## Syntax ```text def get_signer_key_secret_key_available(signer_key_index: int) -> bool: ... ``` ## Default Value FALSE ## Remarks Whether or not a secret key is available for the selected key. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_usage property A text description of UsageFlags . ## Syntax ```text def get_signer_key_usage(signer_key_index: int) -> str: ... ``` ## Default Value "" ## Remarks A text description of [signer_key_usage_flags](#signer_key_usage_flags-property). 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 *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_usage_flags property Flags that show the intended use for the key. ## Syntax ```text def get_signer_key_usage_flags(signer_key_index: int) -> int: ... ``` ## 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](#signer_key_usage_flags-property) is a combination of the following flags: | | | | --- | --- | | 0x01 | This key may be used to certify other keys. | | 0x02 | This key may be used to sign data. | | 0x0C | This key may be used to encrypt communications and encrypt storage. | | 0x10 | The private component of this key may have been split by a secret-sharing mechanism. | | 0x20 | This key may be used for authentication. | | 0x80 | The private component of this key may be in the possession of more than one person. | Please refer to the [signer_key_usage](#signer_key_usage-property) property for a text representation of [signer_key_usage_flags](#signer_key_usage_flags-property). The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signer_key_user_id property The user Id of the key. ## Syntax ```text def get_signer_key_user_id(signer_key_index: int) -> str: ... def set_signer_key_user_id(signer_key_index: int, value: str) -> None: ... ``` ## 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](#signer_key_keyring-property). When this property is set the class will search the [signer_key_keyring](#signer_key_keyring-property) 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](#KeyMgr_p_KeyOtherUserIds) after loading the key. The *UserId* format is: ```text FirstName LastName (Comment) ``` Not all values are required when selecting or generating a key, but at least FirstName or Email are required. Note that for OpenPGP v6, a key may be created with or without a *UserId*, as the field is optional. If a key was created without a *UserId*, the key's *Fingerprint* can be used as its identifier instead. When using this 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 class 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 class's on_recipient_info event. The *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. # signer_key_version property This property can be used to query the OpenPGP version of the currently selected Key . ## Syntax ```text def get_signer_key_version(signer_key_index: int) -> int: ... ``` ## 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 *signer_key_index* parameter specifies the index of the item in the array. The size of the array is controlled by the [signer_key_count](#signer_key_count-property) property. This property is read-only. # signing_algorithm property The signature hash algorithm used when signing. ## Syntax ```text def get_signing_algorithm() -> str: ... def set_signing_algorithm(value: str) -> None: ... signing_algorithm = property(get_signing_algorithm, set_signing_algorithm) ``` ## 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 Sets or retrieves a configuration setting. ## Syntax ```text def config(configuration_string: str) -> str: ... ``` ## Remarks config is a generic method available in every class. It is used to set and retrieve [configuration settings](#openpgp-config-settings) for the class. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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](#openpgp-config-settings), you must call *Config("PROPERTY")*. The value will be returned as a string. # decrypt method Decrypts the message. ## Syntax ```text def decrypt() -> None: ... ``` ## Remarks This method decrypts the specified message. The message will be decrypted using the keys specified in keys. Before decryption begins the class will fire the [on_recipient_info](#on_recipient_info-event) 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 Decrypts and verifies the signature of the message. ## Syntax ```text def decrypt_and_verify_signature() -> None: ... ``` ## Remarks This method attempts to both decrypt and verify the signature of the message. All of the properties affected by calling the [decrypt](#decrypt-method) and [verify_signature](#verify_signature-method) 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 class will perform the decryption without error. The message will be decrypted using the keys specified in keys. Before decryption begins the class will fire the [on_recipient_info](#on_recipient_info-event) 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 class will fire the [on_signature_info](#on_signature_info-event) 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 class fails with an error. The configuration setting [RequireValidSignature](#RequireValidSignature) may be set to False to disable this requirement. When [RequireValidSignature](#RequireValidSignature) is set to False, the *Status* parameter of the [on_verification_status](#on_verification_status-event) 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 Encrypts the message. ## Syntax ```text def encrypt() -> None: ... ``` ## 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 class: - [ascii_armor](#ascii_armor-property) - [compression_method](#compression_method-property) - [encrypting_algorithm](#encrypting_algorithm-property) Additionally, [CompatibilityProfile](#CompatibilityProfile) may be set to control whether the encrypted message uses RFC 9580 or GnuPG's LibrePGP format; see [CompatibilityProfile](#CompatibilityProfile) for details. # get_recipient_info method Gets recipient information for an encrypted message. ## Syntax ```text def get_recipient_info() -> None: ... ``` ## Remarks This method will fire a [on_recipient_info](#on_recipient_info-event) 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 Interrupt the current method. ## Syntax ```text def interrupt() -> None: ... ``` ## Remarks If there is no method in progress, interrupt simply returns, doing nothing. # reset method Resets the class properties. ## Syntax ```text def reset() -> None: ... ``` ## Remarks This method resets all message and key properties to their default values. # sign method Signs the message. ## Syntax ```text def sign() -> None: ... ``` ## 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 class: - [ascii_armor](#ascii_armor-property) - [clear_signature](#clear_signature-property) - [detached_signature](#detached_signature-property) - [signing_algorithm](#signing_algorithm-property) Additionally, [CompatibilityProfile](#CompatibilityProfile) may be set to control whether the signature uses RFC 9580 or GnuPG's LibrePGP format; see [CompatibilityProfile](#CompatibilityProfile) for details. # sign_and_encrypt method Signs and encrypts the current message. ## Syntax ```text def sign_and_encrypt() -> None: ... ``` ## 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 class: - [ascii_armor](#ascii_armor-property) - [compression_method](#compression_method-property) - [encrypting_algorithm](#encrypting_algorithm-property) Additionally, [CompatibilityProfile](#CompatibilityProfile) may be set to control whether the encrypted message uses RFC 9580 or GnuPG's LibrePGP format; see [CompatibilityProfile](#CompatibilityProfile) for details. When signing, the following properties may be used to further configure the class: - [ascii_armor](#ascii_armor-property) - [clear_signature](#clear_signature-property) - [detached_signature](#detached_signature-property) - [signing_algorithm](#signing_algorithm-property) Additionally, [CompatibilityProfile](#CompatibilityProfile) may be set to control whether the signature uses RFC 9580 or GnuPG's LibrePGP format; see [CompatibilityProfile](#CompatibilityProfile) for details. # verify_signature method Verifies the signature of the current message. ## Syntax ```text def verify_signature() -> None: ... ``` ## 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 class will fire the [on_signature_info](#on_signature_info-event) 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 class fails with an error. The configuration setting [RequireValidSignature](#RequireValidSignature) may be set to False to disable this requirement. When [RequireValidSignature](#RequireValidSignature) is set to False, the *Status* parameter of the [on_verification_status](#on_verification_status-event) event should be checked to determine the result of the operation. # on_error event Fired when information is available about errors during data delivery. ## Syntax ```text class OpenPGPErrorEventParams(object): @property def error_code() -> int: ... @property def description() -> str: ... # In class OpenPGP: @property def on_error() -> Callable[[OpenPGPErrorEventParams], None]: ... @on_error.setter def on_error(event_hook: Callable[[OpenPGPErrorEventParams], None]) -> None: ... ``` ## Remarks The on_error event is fired in case of exceptional conditions during message processing. Normally the class 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](#openpgp-errors) section. # on_key_passphrase event Fired if the passphrase of current key is incorrect or empty. ## Syntax ```text class OpenPGPKeyPassphraseEventParams(object): @property def user_id() -> str: ... @property def key_id() -> str: ... @property def fingerprint() -> str: ... @property def passphrase() -> str: ... @passphrase.setter def passphrase(value) -> None: ... # In class OpenPGP: @property def on_key_passphrase() -> Callable[[OpenPGPKeyPassphraseEventParams], None]: ... @on_key_passphrase.setter def on_key_passphrase(event_hook: Callable[[OpenPGPKeyPassphraseEventParams], None]) -> None: ... ``` ## 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](#key_passphrase-property) 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 class, or an email-based class, the following methods require a passphrase for the key: - [decrypt](#decrypt-method) - [sign](#sign-method) - [sign_and_encrypt](#sign_and_encrypt-method) *UserId* holds the user Id of the key the passphrase is required for. The *UserId* format is: ```text FirstName LastName (Comment) ``` Not all values are required when selecting or generating a key, but at least FirstName or Email are required. Note that for OpenPGP v6, a key may be created with or without a *UserId*, as the field is optional. If a key was created without a *UserId*, the key's *Fingerprint* can be used as its identifier instead. *KeyId* is the hex-encoded, 4-byte or 8-byte Id of the key the passphrase is required for. For OpenPGP v4 keys and earlier, the key Id corresponds to the last 4 or 8 bytes of the key's *Fingerprint*. For OpenPGP v6 keys, the key Id corresponds to the first 8 bytes of the key's *Fingerprint* instead. For instance: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key the passphrase is required for. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` # on_progress event Fired as progress is made. ## Syntax ```text class OpenPGPProgressEventParams(object): @property def bytes_processed() -> int: ... @property def percent_processed() -> int: ... @property def operation() -> int: ... @property def is_eof() -> bool: ... @is_eof.setter def is_eof(value) -> None: ... # In class OpenPGP: @property def on_progress() -> Callable[[OpenPGPProgressEventParams], None]: ... @on_progress.setter def on_progress(event_hook: Callable[[OpenPGPProgressEventParams], None]) -> None: ... ``` ## Remarks This event is fired automatically as data is processed by the class. 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](#ReadFromProgressEvent) or [WriteToProgressEvent](#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: | | | | --- | --- | | 0 | None | | 1 | Read | | 2 | Write | The *IsEOF* parameter is only applicable when either [ReadFromProgressEvent](#ReadFromProgressEvent) or [WriteToProgressEvent](#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 class. When the *Operation* is Write (2) this value may be queried to determine when all data has been processed. # on_recipient_info event Fired for each recipient key of the encrypted message. ## Syntax ```text class OpenPGPRecipientInfoEventParams(object): @property def key_id() -> str: ... @property def fingerprint() -> str: ... @property def public_key_algorithm() -> str: ... # In class OpenPGP: @property def on_recipient_info() -> Callable[[OpenPGPRecipientInfoEventParams], None]: ... @on_recipient_info.setter def on_recipient_info(event_hook: Callable[[OpenPGPRecipientInfoEventParams], None]) -> None: ... ``` ## Remarks This event fires when the [decrypt](#decrypt-method) or [decrypt_and_verify_signature](#decrypt_and_verify_signature-method) 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: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key. This is in the form: ```text 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 Fired during verification of the signed message. ## Syntax ```text class OpenPGPSignatureInfoEventParams(object): @property def key_id() -> str: ... @property def fingerprint() -> str: ... @property def signing_algorithm() -> str: ... @property def public_key_algorithm() -> str: ... # In class OpenPGP: @property def on_signature_info() -> Callable[[OpenPGPSignatureInfoEventParams], None]: ... @on_signature_info.setter def on_signature_info(event_hook: Callable[[OpenPGPSignatureInfoEventParams], None]) -> None: ... ``` ## Remarks This event fires when the [verify_signature](#verify_signature-method) or [decrypt_and_verify_signature](#decrypt_and_verify_signature-method) 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: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key. This is in the form: ```text 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 Shows the progress of the operation. ## Syntax ```text class OpenPGPStatusEventParams(object): @property def message() -> str: ... # In class OpenPGP: @property def on_status() -> Callable[[OpenPGPStatusEventParams], None]: ... @on_status.setter def on_status(event_hook: Callable[[OpenPGPStatusEventParams], None]) -> None: ... ``` ## Remarks The event is fired for informational and logging purposes only. It may be used to track the progress of an operation. The level of detail is controlled by the [LogLevel](#LogLevel) setting. # on_verification_status event Fired after verification of the signed message. ## Syntax ```text class OpenPGPVerificationStatusEventParams(object): @property def key_id() -> str: ... @property def fingerprint() -> str: ... @property def status() -> int: ... # In class OpenPGP: @property def on_verification_status() -> Callable[[OpenPGPVerificationStatusEventParams], None]: ... @on_verification_status.setter def on_verification_status(event_hook: Callable[[OpenPGPVerificationStatusEventParams], None]) -> None: ... ``` ## Remarks This event fires when [verify_signature](#verify_signature-method) or [decrypt_and_verify_signature](#decrypt_and_verify_signature-method) 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: ```text 5E70662EA810E768 ``` *Fingerprint* holds the hex-encoded, 20-byte fingerprint of the key. This is in the form: ```text 5E70662EA810E768391A2FE8F7B7D49C89C9D7B1 ``` *Status* holds the result of the operation. Possible values are: | | | | --- | --- | | 0 | Verification succeeded | | 1 | Verification failed | | 2 | The required key could not be found | | 3 | Verification succeeded but the key is expired. | # OpenPGP Config Settings The class 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 class, access to these *internal properties* is provided through the [config](#config-method) 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 [encrypting_algorithm](#encrypting_algorithm-property) 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 [encrypting_algorithm](#encrypting_algorithm-property). **AllowEmptyInput**: Whether to allow empty files for input.This setting controls whether the class allows empty input when processing. When True, the class will process 0 byte files specified by [input_file](#input_file-property), or 0 byte messages specified by [input_message](#input_message-property). The default value is False. **AllowOldPacketType**: Whether to allow the older encrypted packet type.By default the class 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 class 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](#UseArgon2) is *True* and [SymmetricPassphrase](#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)). **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](#UseArgon2) is *True* and [SymmetricPassphrase](#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](#Argon2Parallelism) (see below). The memory size (in KB) is calculated as 2^exp, where exp is the value of this configuration setting. For example, the default memory size would be: 2^(16) = 65,536 KB. NOTE: The memory size must be an integer number of kilobytes ranging from 8*p to 2^(32)-1, where p is the value of [Argon2Parallelism](#Argon2Parallelism). Therefore, [Argon2MemorySizeExp](#Argon2MemorySizeExp) must be an integer ranging from 3+ceil(log2(p)) to 31. For example, if [Argon2Parallelism](#Argon2Parallelism) is set to *8*, valid values for [Argon2MemorySizeExp](#Argon2MemorySizeExp) range from *6* to *31*. **Argon2Parallelism**: Specifies the degree of parallelism used for Argon2.This configuration setting specifies the degree of parallelism, or the number of lanes, used for passphrase-based key derivation during symmetric encryption/decryption. Note that this configuration setting is only applicable when [UseArgon2](#UseArgon2) is *True* and [SymmetricPassphrase](#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 set_input_stream 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 set_output_stream is closed after processing is complete. The default value is True. **CompatibilityProfile**: Specifies the OpenPGP compatibility profile used when creating messages.This setting specifies the OpenPGP compatibility profile used when creating messages via [encrypt](#encrypt-method), [sign](#sign-method), and [sign_and_encrypt](#sign_and_encrypt-method). Possible values are: | | | | --- | --- | | RFC9580 | Creates messages using RFC 9580 formats, including v6 session key packets, RFC 9980 composite ML-KEM recipient keys, and v2 SEIPD packets when AEAD is used. This is the default. | | LibrePGP | Creates messages compatible with GnuPG's LibrePGP format, including GnuPG ML-KEM recipient keys, v5 symmetric-key session key packets, and OCB Encrypted Data packets when AEAD is used. | Set this to match the format of the keys involved in the operation, rather than as a fixed preference: - When encrypting with a recipient key, or signing with a key, that was generated by GnuPG (2.5.x or later) or otherwise uses the LibrePGP key format (see the [KeyMgr](KeyMgr.md#KeyMgr) classes *KeyVersion* setting), set this to *LibrePGP*. This also restricts AEAD encryption to the OCB algorithm, since that is the only AEAD algorithm GnuPG supports. - When the keys involved are RFC 9580 keys not tied to GnuPG, leave this at the default, *RFC9580*. Unlike the [KeyMgr](KeyMgr.md#KeyMgr) class, there is no separate key/packet-version setting here: [CompatibilityProfile](#CompatibilityProfile) alone determines which packet version is written for session keys and signatures when a message is created. This setting only affects the format of messages the class generates. Decrypting and verifying existing messages (via [decrypt](#decrypt-method) and [verify_signature](#verify_signature-method)) supports both RFC 9580 and LibrePGP formats regardless of this setting. **CompressionLevel**: The level of compression used.This setting specifies the level of compression used: possible values depend on the value of [compression_method](#compression_method-property) and are detailed below. This value is passed directly to the underlying compression library: | | | | --- | --- | | zlib | -1 (library default), or 0-9 | | zip | -1 (library default), or 0-9 | | bzip2 | 1-9 | For *zlib* and *zip*, -1 requests the library's own default compression level (typically equivalent to *6*). For *bzip2*, which has no native default level, a value of -1 is treated as *4*. Higher values (other than -1) cause the class to compress better; lower values cause it to compress faster. The default value is -1. **DeleteOutputFileOnError**: Whether to delete the output file on an error.Set this to true to automatically delete any partially written [output_file](#output_file-property) if an error occurs. The default is *False* **DetachedSignatureData**: The detached signature.This setting is used to specify the detached signature before calling [verify_signature](#verify_signature-method). 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: ```text 89011C04000102000605025100459B000A0910E2... ``` **EnsureValidDSASignatureHashAlgorithm**: Whether or not to select a suitable signature hash algorithm automatically.This setting specifies whether the class 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 class 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 class 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 [key_curve](#key_curve-property) used by the key. When this setting is enabled (default) the class 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 class will automatically select a valid hash algorithm based on the curve as follows: | Curve | Hash 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 [input_file](#input_file-property) to encrypt from, this is included automatically in the encrypted packet. After decrypting, this will contain the file name of the original encrypted file. **KeyIdLength**: The length of the KeyId available.This controls the length of KeyId available when [on_recipient_info](#on_recipient_info-event) 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: ```text 5E70662EA810E768 ``` **KeySelectionMethod**: The method used to select a key for encryption or signing.When more than one key is present this class 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. ```text 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 [on_status](#on_status-event) 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 class 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](#encrypt-method). For instance: ```text OpenPGP1.Config("PGPZipDir=C:\MyFiles\*.txt"); OpenPGP1.OutputFile = "C:\PGPZip.pgp"; OpenPGP1.Encrypt(); ``` The created file returned in the [output_file](#output_file-property) property is the PGP zip. If [input_file](#input_file-property) 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 [input_file](#input_file-property) 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](#decrypt-method). For instance: ```text OpenPGP1.Config("PGPZipDir=C:\MyFiles"); OpenPGP1.InputFile = "C:\PGPZip.pgp"; OpenPGP1.Decrypt(); ``` The extracted files will be present in the specified directory. If [output_file](#output_file-property) is specified it is used to temporarily hold the Tar archive. The temporary file is not automatically deleted. If [output_file](#output_file-property) 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 [on_progress](#on_progress-event) event is fired as data is processed by the class. 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 [on_progress](#on_progress-event) event. The class will repeatedly fire the [on_progress](#on_progress-event) event to ask for data. Inside the event set [input_message](#input_message-property) 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 class will handle this situation. Options are: | | | | --- | --- | | 0 | Automatic - If the PGP message contains the special header version "PGP Command Line" then recursive decryption will be attempted. (Default) | | 1 | Always attempt recursive decryption. | | 2 | Never 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 class 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 class fails with an error. This setting may be set to False to disable this requirement. When False, the *Status* parameter of the [on_verification_status](#on_verification_status-event) event should be checked to determine the result of the operation. The default value is True. **S2KAlgorithm**: Specifies the algorithm for S2K key derivation.Specifies the S2K algorithm used to derive encryption keys from passphrases. Possible values are: - SHA1 (default) - MD5 - SHA256 - SHA384 - SHA512 - SHA224 - RIPEMD160 - SHA3-256 - SHA3-512 **S2KIterations**: Sets the number of iterations for S2K key derivation.Defines the number of iterations for the String-to-Key (S2K) function, affecting key derivation strength. By default, this value is *96*. Valid values range from *0* to *255*. **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 message_headers, the class 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](#encrypt-method) and [decrypt](#decrypt-method) are valid operations when a value is set. [sign](#sign-method), [sign_and_encrypt](#sign_and_encrypt-method), [verify_signature](#verify_signature-method), and [decrypt_and_verify_signature](#decrypt_and_verify_signature-method) 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](#SymmetricPassphrase) is specified and when calling [encrypt](#encrypt-method) or [decrypt](#decrypt-method). Additionally, the following configuration settings are applicable when this config is set to *True*: - [Argon2Iterations](#Argon2Iterations) - [Argon2Parallelism](#Argon2Parallelism) - [Argon2MemorySizeExp](#Argon2MemorySizeExp) Note that if [UseArgon2](#UseArgon2) is enabled, [encrypting_algorithm](#encrypting_algorithm-property) must be specified as an AEAD encryption algorithm (e.g., *AES192-OCB*). Please see the [encrypting_algorithm](#encrypting_algorithm-property) 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. **UsePlatformAES**: Whether to use the platform AES implementation.By default class will use an internal implementation to perform AES. This is more self-contained and managed. In certain scenarios it may be better to use the platform's implementation. Set this to true to perform AES using the platform implementation. This is only available on Unix. The default is false. **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 class will be unable to verify OpenPGP v6 cleartext signatures. In this case, the class will throw an exception when calling [verify_signature](#verify_signature-method) or [decrypt_and_verify_signature](#decrypt_and_verify_signature-method). **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](#encrypt-method), [sign](#sign-method), or [sign_and_encrypt](#sign_and_encrypt-method). The default value is "IPWorks PGP 2026". This setting will be populated after calling [decrypt](#decrypt-method), [verify_signature](#verify_signature-method), or [decrypt_and_verify_signature](#decrypt_and_verify_signature-method). **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 [on_progress](#on_progress-event) event. The class will repeatedly fire the [on_progress](#on_progress-event) event to provide output data. Inside the event check [output_message](#output_message-property) 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. **CodePage**: The system code page used for Unicode to Multibyte translations.The default code page is Unicode UTF-8 (65001). The following is a list of valid code page identifiers: | | | | --- | --- | | Identifier | Name | | 037 | IBM EBCDIC - U.S./Canada | | 437 | OEM - United States | | 500 | IBM EBCDIC - International | | 708 | Arabic - ASMO 708 | | 709 | Arabic - ASMO 449+, BCON V4 | | 710 | Arabic - Transparent Arabic | | 720 | Arabic - Transparent ASMO | | 737 | OEM - Greek (formerly 437G) | | 775 | OEM - Baltic | | 850 | OEM - Multilingual Latin I | | 852 | OEM - Latin II | | 855 | OEM - Cyrillic (primarily Russian) | | 857 | OEM - Turkish | | 858 | OEM - Multilingual Latin I + Euro symbol | | 860 | OEM - Portuguese | | 861 | OEM - Icelandic | | 862 | OEM - Hebrew | | 863 | OEM - Canadian-French | | 864 | OEM - Arabic | | 865 | OEM - Nordic | | 866 | OEM - Russian | | 869 | OEM - Modern Greek | | 870 | IBM EBCDIC - Multilingual/ROECE (Latin-2) | | 874 | ANSI/OEM - Thai (same as 28605, ISO 8859-15) | | 875 | IBM EBCDIC - Modern Greek | | 932 | ANSI/OEM - Japanese, Shift-JIS | | 936 | ANSI/OEM - Simplified Chinese (PRC, Singapore) | | 949 | ANSI/OEM - Korean (Unified Hangul Code) | | 950 | ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC) | | 1026 | IBM EBCDIC - Turkish (Latin-5) | | 1047 | IBM EBCDIC - Latin 1/Open System | | 1140 | IBM EBCDIC - U.S./Canada (037 + Euro symbol) | | 1141 | IBM EBCDIC - Germany (20273 + Euro symbol) | | 1142 | IBM EBCDIC - Denmark/Norway (20277 + Euro symbol) | | 1143 | IBM EBCDIC - Finland/Sweden (20278 + Euro symbol) | | 1144 | IBM EBCDIC - Italy (20280 + Euro symbol) | | 1145 | IBM EBCDIC - Latin America/Spain (20284 + Euro symbol) | | 1146 | IBM EBCDIC - United Kingdom (20285 + Euro symbol) | | 1147 | IBM EBCDIC - France (20297 + Euro symbol) | | 1148 | IBM EBCDIC - International (500 + Euro symbol) | | 1149 | IBM EBCDIC - Icelandic (20871 + Euro symbol) | | 1200 | Unicode UCS-2 Little-Endian (BMP of ISO 10646) | | 1201 | Unicode UCS-2 Big-Endian | | 1250 | ANSI - Central European | | 1251 | ANSI - Cyrillic | | 1252 | ANSI - Latin I | | 1253 | ANSI - Greek | | 1254 | ANSI - Turkish | | 1255 | ANSI - Hebrew | | 1256 | ANSI - Arabic | | 1257 | ANSI - Baltic | | 1258 | ANSI/OEM - Vietnamese | | 1361 | Korean (Johab) | | 10000 | MAC - Roman | | 10001 | MAC - Japanese | | 10002 | MAC - Traditional Chinese (Big5) | | 10003 | MAC - Korean | | 10004 | MAC - Arabic | | 10005 | MAC - Hebrew | | 10006 | MAC - Greek I | | 10007 | MAC - Cyrillic | | 10008 | MAC - Simplified Chinese (GB 2312) | | 10010 | MAC - Romania | | 10017 | MAC - Ukraine | | 10021 | MAC - Thai | | 10029 | MAC - Latin II | | 10079 | MAC - Icelandic | | 10081 | MAC - Turkish | | 10082 | MAC - Croatia | | 12000 | Unicode UCS-4 Little-Endian | | 12001 | Unicode UCS-4 Big-Endian | | 20000 | CNS - Taiwan | | 20001 | TCA - Taiwan | | 20002 | Eten - Taiwan | | 20003 | IBM5550 - Taiwan | | 20004 | TeleText - Taiwan | | 20005 | Wang - Taiwan | | 20105 | IA5 IRV International Alphabet No. 5 (7-bit) | | 20106 | IA5 German (7-bit) | | 20107 | IA5 Swedish (7-bit) | | 20108 | IA5 Norwegian (7-bit) | | 20127 | US-ASCII (7-bit) | | 20261 | T.61 | | 20269 | ISO 6937 Non-Spacing Accent | | 20273 | IBM EBCDIC - Germany | | 20277 | IBM EBCDIC - Denmark/Norway | | 20278 | IBM EBCDIC - Finland/Sweden | | 20280 | IBM EBCDIC - Italy | | 20284 | IBM EBCDIC - Latin America/Spain | | 20285 | IBM EBCDIC - United Kingdom | | 20290 | IBM EBCDIC - Japanese Katakana Extended | | 20297 | IBM EBCDIC - France | | 20420 | IBM EBCDIC - Arabic | | 20423 | IBM EBCDIC - Greek | | 20424 | IBM EBCDIC - Hebrew | | 20833 | IBM EBCDIC - Korean Extended | | 20838 | IBM EBCDIC - Thai | | 20866 | Russian - KOI8-R | | 20871 | IBM EBCDIC - Icelandic | | 20880 | IBM EBCDIC - Cyrillic (Russian) | | 20905 | IBM EBCDIC - Turkish | | 20924 | IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol) | | 20932 | JIS X 0208-1990 & 0121-1990 | | 20936 | Simplified Chinese (GB2312) | | 21025 | IBM EBCDIC - Cyrillic (Serbian, Bulgarian) | | 21027 | Extended Alpha Lowercase | | 21866 | Ukrainian (KOI8-U) | | 28591 | ISO 8859-1 Latin I | | 28592 | ISO 8859-2 Central Europe | | 28593 | ISO 8859-3 Latin 3 | | 28594 | ISO 8859-4 Baltic | | 28595 | ISO 8859-5 Cyrillic | | 28596 | ISO 8859-6 Arabic | | 28597 | ISO 8859-7 Greek | | 28598 | ISO 8859-8 Hebrew | | 28599 | ISO 8859-9 Latin 5 | | 28605 | ISO 8859-15 Latin 9 | | 29001 | Europa 3 | | 38598 | ISO 8859-8 Hebrew | | 50220 | ISO 2022 Japanese with no halfwidth Katakana | | 50221 | ISO 2022 Japanese with halfwidth Katakana | | 50222 | ISO 2022 Japanese JIS X 0201-1989 | | 50225 | ISO 2022 Korean | | 50227 | ISO 2022 Simplified Chinese | | 50229 | ISO 2022 Traditional Chinese | | 50930 | Japanese (Katakana) Extended | | 50931 | US/Canada and Japanese | | 50933 | Korean Extended and Korean | | 50935 | Simplified Chinese Extended and Simplified Chinese | | 50936 | Simplified Chinese | | 50937 | US/Canada and Traditional Chinese | | 50939 | Japanese (Latin) Extended and Japanese | | 51932 | EUC - Japanese | | 51936 | EUC - Simplified Chinese | | 51949 | EUC - Korean | | 51950 | EUC - Traditional Chinese | | 52936 | HZ-GB2312 Simplified Chinese | | 54936 | Windows XP: GB18030 Simplified Chinese (4 Byte) | | 57002 | ISCII Devanagari | | 57003 | ISCII Bengali | | 57004 | ISCII Tamil | | 57005 | ISCII Telugu | | 57006 | ISCII Assamese | | 57007 | ISCII Oriya | | 57008 | ISCII Kannada | | 57009 | ISCII Malayalam | | 57010 | ISCII Gujarati | | 57011 | ISCII Punjabi | | 65000 | Unicode UTF-7 | | 65001 | Unicode UTF-8 | The following is a list of valid code page identifiers for Mac OS only: | | | | --- | --- | | Identifier | Name | | 1 | ASCII | | 2 | NEXTSTEP | | 3 | JapaneseEUC | | 4 | UTF8 | | 5 | ISOLatin1 | | 6 | Symbol | | 7 | NonLossyASCII | | 8 | ShiftJIS | | 9 | ISOLatin2 | | 10 | Unicode | | 11 | WindowsCP1251 | | 12 | WindowsCP1252 | | 13 | WindowsCP1253 | | 14 | WindowsCP1254 | | 15 | WindowsCP1250 | | 21 | ISO2022JP | | 30 | MacOSRoman | | 10 | UTF16String | | 0x90000100 | UTF16BigEndian | | 0x94000100 | UTF16LittleEndian | | 0x8c000100 | UTF32String | | 0x98000100 | UTF32BigEndian | | 0x9c000100 | UTF32LittleEndian | | 65536 | Proprietary | **LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a class 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*. **ProcessIdleEvents**: Whether the class uses its internal event loop to process events when the main thread is idle.If set to False, the class will not fire internal idle events. Set this to False to use the class in a background thread on Mac OS. By default, this setting is True. **SelectWaitMillis**: The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.If there are no events to process when do_events is called, the class will wait for the amount of time specified here before returning. The default value is 20. **UseFIPSCompliantAPI**: Tells the class whether or not to use FIPS certified APIs.When set to *True*, the class 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 classes of the toolkit within the process. It is recommended to enable or disable this setting once before the component has been used to establish a connection. Enabling FIPS while an instance of the component is active and connected may result in unexpected behavior. For more details, please see the [FIPS 140-2 Compliance](https://www.nsoftware.com/kb/articles/fips.rst) article. NOTE: This setting is applicable only on Windows. NOTE: Enabling FIPS compliance requires a special license; please contact [sales@nsoftware.com](mailto:sales@nsoftware.com) for details. **UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *False*, the class will use the system security libraries by default to perform cryptographic functions where applicable. Setting this configuration setting to *True* tells the class 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. To use the system security libraries for Linux, OpenSSL support must be enabled. For more information on how to enable OpenSSL, please refer to the [OpenSSL Notes](platforms.md) section. # OpenPGP Errors ### 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. |