File: gpgme.info,  Node: Decrypt,  Next: Verify,  Up: Crypto Operations

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.

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

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