Decrypt (The ‘GnuPG Made Easy’ Reference Manual)

7.6.1 Decrypt

Function: gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx, gpgme_data_t cipher, gpgme_data_t plain) ¶

The function gpgme_op_decrypt decrypts the ciphertext in the data object cipher or, if a file name is set on the data object, the ciphertext stored in the corresponding file. The decrypted ciphertext is stored into the data object plain or written to the file set with gpgme_data_set_file_name for the data object plain.

The function returns the error code GPG_ERR_NO_ERROR if the ciphertext could be decrypted successfully, GPG_ERR_INV_VALUE if ctx, cipher or plain is not a valid pointer, GPG_ERR_NO_DATA if cipher does not contain any data to decrypt, GPG_ERR_DECRYPT_FAILED if cipher is not a valid cipher text, GPG_ERR_BAD_PASSPHRASE if the passphrase for the secret key could not be retrieved, and passes through some errors that are reported by the crypto engine support routines.

Function: gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher, gpgme_data_t plain) ¶

The function gpgme_op_decrypt_start initiates a gpgme_op_decrypt operation. It can be completed by calling gpgme_wait on the context. See Waiting For Completion.

The function returns the error code GPG_ERR_NO_ERROR if the operation could be started successfully, and GPG_ERR_INV_VALUE if cipher or plain is not a valid pointer.

Function: gpgme_error_t gpgme_op_decrypt_ext ( gpgme_ctx_t ctx, gpgme_decrypt_flags_t flags, gpgme_data_t cipher, gpgme_data_t plain) ¶

SINCE: 1.8.0

The function gpgme_op_decrypt_ext is the same as gpgme_op_decrypt but has an additional argument flags. If flags is 0 both function behave identically.

If the flag GPGME_DECRYPT_ARCHIVE is set, then an encrypted archive in the data object cipher is decrypted and extracted. The content of the archive is extracted into a directory named GPGARCH_n_ (where n is a number) or into the directory set with gpgme_data_set_file_name for the data object plain.

The value in flags is a bitwise-or combination of one or multiple of the following bit values:

GPGME_DECRYPT_VERIFY

SINCE: 1.8.0

The GPGME_DECRYPT_VERIFY symbol specifies that this function shall exactly act as gpgme_op_decrypt_verify.

GPGME_DECRYPT_ARCHIVE

SINCE: 1.19.0

The GPGME_DECRYPT_ARCHIVE symbol specifies that the input is an encrypted archive that shall be decrypted and extracted. This feature is currently only supported for the OpenPGP crypto engine and requires GnuPG 2.4.1.

GPGME_DECRYPT_UNWRAP

SINCE: 1.8.0

The GPGME_DECRYPT_UNWRAP symbol specifies that the output shall be an OpenPGP message with only the encryption layer removed. This requires GnuPG 2.1.12 and works only for OpenPGP. This is the counterpart to GPGME_ENCRYPT_WRAP.

The function returns the error codes as described for gpgme_op_decrypt.

Function: gpgme_error_t gpgme_op_decrypt_ext_start ( gpgme_ctx_t ctx, gpgme_decrypt_flags_t flags, gpgme_data_t cipher, gpgme_data_t plain) ¶

SINCE: 1.8.0

The function gpgme_op_decrypt_ext_start initiates a gpgme_op_decrypt_ext operation. It can be completed by calling gpgme_wait on the context. See Waiting For Completion.

The function returns the error code GPG_ERR_NO_ERROR if the operation could be started successfully, and GPG_ERR_INV_VALUE if cipher or plain is not a valid pointer.

Data type: gpgme_recipient_t ¶

SINCE: 1.1.0

This is a pointer to a structure used to store information about the recipient of an encrypted text which is decrypted in a gpgme_op_decrypt operation. This information (except for the status field) is even available before the operation finished successfully, for example in a passphrase callback. The structure contains the following members:

gpgme_recipient_t next: This is a pointer to the next recipient structure in the linked list, or NULL if this is the last element.
gpgme_pubkey_algo_t: The public key algorithm used in the encryption.
char *keyid: This is the key ID of the key (in hexadecimal digits) used as recipient.
gpgme_error_t status: This is an error number with the error code GPG_ERR_NO_SECKEY if the secret key for this recipient is not available, and 0 otherwise.

Data type: gpgme_decrypt_result_t ¶

This is a pointer to a structure used to store the result of a gpgme_op_decrypt operation. After successfully decrypting data, you can retrieve the pointer to the result with gpgme_op_decrypt_result. As with all result structures, it this structure shall be considered read-only and an application must not allocate such a strucure on its own. The structure contains the following members:

char *unsupported_algorithm

If an unsupported algorithm was encountered, this string describes the algorithm that is not supported.

unsigned int wrong_key_usage : 1

SINCE: 0.9.0 This is true if the key was not used according to its policy.

unsigned int legacy_cipher_nomdc : 1

SINCE: 1.11.2 The message was made by a legacy algorithm without any integrity protection. This might be an old but legitimate message.

unsigned int is_mime : 1;

SINCE: 1.11.0 The message claims that the content is a MIME object.

unsigned int is_de_vs : 1;

SINCE: 1.10.0 The message was encrypted in a VS-NfD compliant way. This is a specification in Germany for a restricted communication level.

unsigned int beta_compliance : 1;

SINCE: 1.24.0 The compliance flags (e.g. is_de_vs) are set but the software has not yet been approved or is in a beta state.

gpgme_recipient_t recipients

SINCE: 1.1.0

This is a linked list of recipients to which this message was encrypted.

char *file_name

This is the filename of the original plaintext message file if it is known, otherwise this is a null pointer.

char *session_key

SINCE: 1.8.0

A textual representation (nul-terminated string) of the session key used in symmetric encryption of the message, if the context has been set to export session keys (see gpgme_set_ctx_flag, "export-session-key"), and a session key was available for the most recent decryption operation. Otherwise, this is a null pointer.

You must not try to access this member of the struct unless gpgme_set_ctx_flag (ctx, "export-session-key") returns success or gpgme_get_ctx_flag (ctx, "export-session-key") returns true (non-empty string).

char *symkey_algo

SINCE: 1.11.0

A string with the symmetric encryption algorithm and mode using the format "<algo>.<mode>". Note that the deprecated non-MDC encryption mode of OpenPGP is given as "PGPCFB".

Function: gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx) ¶: The function gpgme_op_decrypt_result returns a gpgme_decrypt_result_t pointer to a structure holding the result of a gpgme_op_decrypt operation. The pointer is only valid if the last operation on the context was a gpgme_op_decrypt or gpgme_op_decrypt_start operation. If the operation failed this might be a NULL pointer. The returned pointer is only valid until the next operation is started on the context.