7.7.5.1 Encrypting a Plaintext

The function gpgme_op_encrypt encrypts the plaintext in the
data object plain for the recipients recp and stores the
ciphertext in the data object cipher. The type of the
ciphertext created is determined by the ASCII armor (or, if
that is not set, by the encoding specified for cipher) and the
text mode attributes set for the context ctx.

recp must be a NULL-terminated array of keys. The user
must keep references for all keys during the whole duration of the
call (but see gpgme_op_encrypt_start for the requirements with
the asynchronous variant).

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

GPGME_ENCRYPT_ALWAYS_TRUST

The GPGME_ENCRYPT_ALWAYS_TRUST symbol specifies that all the
recipients in recp should be trusted, even if the keys do not
have a high enough validity in the keyring. This flag should be used
with care; in general it is not a good idea to use any untrusted keys.

GPGME_ENCRYPT_NO_ENCRYPT_TO

SINCE: 1.2.0

The GPGME_ENCRYPT_NO_ENCRYPT_TO symbol specifies that no
default or hidden default recipients as configured in the crypto
backend should be included. This can be useful for managing different
user profiles.

GPGME_ENCRYPT_NO_COMPRESS

SINCE: 1.5.0

The GPGME_ENCRYPT_NO_COMPRESS symbol specifies that the
plaintext shall not be compressed before it is encrypted. This is
in some cases useful if the length of the encrypted message
may reveal information about the plaintext.

GPGME_ENCRYPT_PREPARE

GPGME_ENCRYPT_EXPECT_SIGN

The GPGME_ENCRYPT_PREPARE symbol is used with the UI Server
protocol to prepare an encryption (i.e. sending the
PREP_ENCRYPT command). With the
GPGME_ENCRYPT_EXPECT_SIGN symbol the UI Server is advised to
also expect a sign command.

GPGME_ENCRYPT_SYMMETRIC

SINCE: 1.7.0

The GPGME_ENCRYPT_SYMMETRIC symbol specifies that the
output should be additionally encrypted symmetrically even
if recipients are provided. This feature is only supported for
for the OpenPGP crypto engine.

GPGME_ENCRYPT_THROW_KEYIDS

SINCE: 1.8.0

The GPGME_ENCRYPT_THROW_KEYIDS symbols requests that the
identifiers for the decrption keys are not included in the ciphertext.
On the receiving side, the use of this flag may slow down the
decryption process because all available secret keys must be tried.
This flag is only honored for OpenPGP encryption.

GPGME_ENCRYPT_WRAP

SINCE: 1.8.0

The GPGME_ENCRYPT_WRAP symbol specifies that the input is an
OpenPGP message and not a plain data. This is the counterpart to
GPGME_DECRYPT_UNWRAP.

If GPG_ERR_UNUSABLE_PUBKEY is returned, some recipients in
recp are invalid, but not all. In this case the plaintext might
be encrypted for all valid recipients and returned in cipher (if
this happens depends on the crypto engine). More information about
the invalid recipients is available with
gpgme_op_encrypt_result.

If recp is NULL, symmetric rather than public key
encryption is performed. Symmetrically encrypted cipher text can be
deciphered with gpgme_op_decrypt. Note that in this case the
crypto backend needs to retrieve a passphrase from the user.
Symmetric encryption is currently only supported for the OpenPGP
crypto backend.

The function returns the error code GPG_ERR_NO_ERROR if the
ciphertext could be created successfully, GPG_ERR_INV_VALUE if
ctx, recp, plain or cipher is not a valid
pointer, GPG_ERR_UNUSABLE_PUBKEY if recp contains some
invalid recipients, GPG_ERR_BAD_PASSPHRASE if the passphrase
for the symmetric key could not be retrieved, and passes through any
errors that are reported by the crypto engine support routines.

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

References to the keys only need to be held for the duration of this
call. The user can release its references to the keys after this
function returns, even if the operation is not yet finished.

The function returns the error code GPG_ERR_NO_ERROR if the
operation could be started successfully, GPG_ERR_INV_VALUE if
ctx, rset, plain or cipher is not a valid
pointer, and GPG_ERR_UNUSABLE_PUBKEY if rset does not
contain any valid recipients.

Data type: gpgme_encrypt_result_t

This is a pointer to a structure used to store the result of a
gpgme_op_encrypt operation. After successfully encrypting
data, you can retrieve the pointer to the result with
gpgme_op_encrypt_result. The structure contains the following
members:

gpgme_invalid_key_t invalid_recipients

A linked list with information about all invalid keys for which
the data could not be encrypted.

The function gpgme_op_encrypt_result returns a
gpgme_encrypt_result_t pointer to a structure holding the
result of a gpgme_op_encrypt operation. The pointer is only
valid if the last operation on the context was a
gpgme_op_encrypt, gpgme_op_encrypt_start,
gpgme_op_sign or gpgme_op_sign_start operation. If this
operation failed, this might be a NULL pointer. The returned
pointer is only valid until the next operation is started on the
context.