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 or writes it directly to the
file set with gpgme_data_set_file_name
for 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. If a filename has been set with gpgme_data_set_file_name
for the data object plain then this filename is stored in the
ciphertext.
If the flag GPGME_ENCRYPT_FILE
is set and a filename has been set
with gpgme_data_set_file_name
for the data object plain,
then this filename is passed to gpg, so that gpg reads the plaintext
directly from this file instead of from the data object plain.
If the flag GPGME_ENCRYPT_ARCHIVE
is set, then an encrypted
archive is created from the files and directories given as NUL-separated
list in the data object plain. The paths of the files and
directories have to be given as paths relative to the current working
directory or relative to the base directory set with
gpgme_data_set_file_name
for the data object plain.
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.
For the S/MIME (CMS) protocol this flag allows to encrypt to a certificate without running any checks on the validity of the certificate.
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 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
.
GPGME_ENCRYPT_WANT_ADDRESS
SINCE: 1.11.0
The GPGME_ENCRYPT_WANT_ADDRESS
symbol requests that all
supplied keys or key specifications include a syntactically valid mail
address. If this is not the case the operation is not even tried and
the error code GPG_ERR_INV_USER_ID
is returned. Only the
address part of the key specification is conveyed to the backend. As
of now the key must be specified using the recpstring argument
of the extended encrypt functions. This feature is currently only
supported for the OpenPGP crypto engine.
GPGME_ENCRYPT_ARCHIVE
SINCE: 1.19.0
The GPGME_ENCRYPT_ARCHIVE
symbol specifies that the input is a
NUL-separated list of file paths and directory paths that shall be
encrypted into an archive. This feature is currently only supported
for the OpenPGP crypto engine and requires GnuPG 2.4.1.
GPGME_ENCRYPT_FILE
SINCE: 1.24.0
The GPGME_ENCRYPT_FILE
symbol specifies that the filename set
with gpgme_data_set_file_name
for the data object plain
is passed to gpg, so that gpg reads the plaintext directly from this
file instead of from the data object plain. This feature is
currently only supported for the OpenPGP crypto engine.
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.
SINCE: 1.11.0
This is an extended version of gpgme_op_encrypt
with
recpstring as additional parameter. If recp is NULL and
recpstring is not NULL, the latter is expected to be a linefeed
delimited string with the set of key specifications. In contrast to
recp the keys are given directly as strings and there is no need
to first create key objects. Leading and trailing white space is
remove from each line in recpstring. The keys are then passed
verbatim to the backend engine.
For the OpenPGP backend several special keywords are supported to modify the operation. These keywords are given instead of a key specification. The currently supported keywords are:
--hidden
--no-hidden
These keywords toggle between normal and hidden recipients for all following key specifications. When a hidden recipient is requested the gpg option -R (or -F in file mode) is used instead of -r (-f in file mode).
--file
--no-file
These keywords toggle between regular and file mode for all following
key specification. In file mode the option -f or -F
is passed to gpg. At least GnuPG version 2.1.14 is required to handle
these options. The GPGME_ENCRYPT_WANT_ADDRESS
flag is ignored
in file mode.
--
This keyword disables all keyword detection up to the end of the string. All keywords are treated as verbatim arguments.
To create a recpstring it is often useful to employ a strconcat style function. For example this function creates a string to encrypt to two keys:
char * xbuild_recpstring (const char *key1, const char *key2) { char *result = gpgrt_strconcat ("--\n", key1, "\n", key2, NULL); if (!result) { perror ("strconcat failed"); exit (2); } return result; }
Note the use of the double dash here; unless you want to specify a
keyword, it is a good idea to avoid any possible trouble with key
specifications starting with a double dash. The used strconcat
function is available in Libgpg-error 1.28 and later; Libgpg-error
(aka Gpgrt) is a dependency of GPGME. The number of arguments to
gpgrt_strconcat
is limited to 47 but that should always be
sufficient. In case a larger and non-fixed number of keys are to be
supplied the following code can be used:
char * xbuild_long_recpstring (void) { gpgrt_stream_t memfp; const char *s; void *result; memfp = gpgrt_fopenmem (0, "w+b"); if (!memfp) { perror ("fopenmem failed"); exit (2); } gpgrt_fputs ("--", memfp); while ((s = get_next_keyspec ())) { gpgrt_fputc ('\n', memfp); gpgrt_fputs (s, memfp); } gpgrt_fputc (0, memfp); if (gpgrt_ferror (memfp)) { perror ("writing to memstream failed"); exit (2); } if (gpgrt_fclose_snatch (memfp, &result, NULL)) { perror ("fclose_snatch failed"); exit (2); } return result; }
In this example get_next_keyspec
is expected to return the next
key to be added to the string. Please take care: Encrypting to a
large number of recipients is often questionable due to security
reasons and also for the technicality that all keys are currently
passed on the command line to gpg
which has as a platform
specific length limitation.
SINCE: 1.11.0
This is an extended version of gpgme_op_encrypt_start
with
recpstring as additional parameter. If recp is NULL and
recpstring is not NULL, the latter is expected to be a linefeed
delimited string with the set of key specifications. In contrast to
recp the keys are given directly as strings and there is no need
to first create key objects. The keys are passed verbatim to the
backend engine.
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.
The function gpgme_op_encrypt_sign
does a combined encrypt and
sign operation. It is used like gpgme_op_encrypt
, but the
ciphertext also contains signatures for the signers listed in
ctx.
The combined encrypt and sign operation is currently only available for the OpenPGP crypto engine.
The function gpgme_op_encrypt_sign_start
initiates a
gpgme_op_encrypt_sign
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 ctx, rset, plain or cipher is not a valid
pointer.
SINCE: 1.11.0
This is an extended version of gpgme_op_encrypt_sign
with
recpstring as additional parameter. If recp is NULL and
recpstring is not NULL, the latter is expected to be a linefeed
delimited string with the set of key specifications. In contrast to
recp the keys are given directly as strings and there is no need
to first create the key objects. The keys are passed verbatim to the
backend engine.
SINCE: 1.11.0
This is an extended version of gpgme_op_encrypt_sign_start
with
recpstring as additional parameter. If recp is NULL and
recpstring is not NULL, the latter is expected to be a linefeed
delimited string with the set of key specifications. In contrast to
recp the keys are given directly as strings and there is no need
to first create the key objects. The keys are passed verbatim to the
backend engine.