File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt

7.6.5.1 Encrypting a Plaintext
..............................

 -- Function: gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t CTX,
          gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
          gpgme_data_t PLAIN, gpgme_data_t CIPHER)
     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 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 and returned in the
     data object CIPHER.  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’.

     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.

     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.

 -- Function: gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t CTX,
          gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
          gpgme_data_t PLAIN, gpgme_data_t CIPHER)
     The function ‘gpgme_op_encrypt_start’ initiates a
     ‘gpgme_op_encrypt’ operation.  It can be completed by calling
     ‘gpgme_wait’ on the context.  *Note 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.

 -- Function: gpgme_error_t gpgme_op_encrypt_ext (gpgme_ctx_t CTX,
          gpgme_key_t RECP[], const char *RECPSTRING,
          gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
          gpgme_data_t CIPHER)

     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.

 -- Function: gpgme_error_t gpgme_op_encrypt_ext_start (gpgme_ctx_t CTX,
          gpgme_key_t RECP[], const char *RECPSTRING,
          gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
          gpgme_data_t CIPHER)

     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.

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

 -- Function: gpgme_encrypt_result_t gpgme_op_encrypt_result
          (gpgme_ctx_t CTX)
     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.

 -- Function: gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t CTX,
          gpgme_key_t RECP[], gpgme_encrypt_flags_t FLAGS,
          gpgme_data_t PLAIN, gpgme_data_t CIPHER)
     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.

 -- Function: gpgme_error_t gpgme_op_encrypt_sign_start
          (gpgme_ctx_t CTX, gpgme_key_t RECP[],
          gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
          gpgme_data_t CIPHER)
     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.  *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
     CTX, RSET, PLAIN or CIPHER is not a valid pointer.

 -- Function: gpgme_error_t gpgme_op_encrypt_sign_ext (gpgme_ctx_t CTX,
          gpgme_key_t RECP[], const char *RECPSTRING,
          gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
          gpgme_data_t CIPHER)

     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.

 -- Function: gpgme_error_t gpgme_op_encrypt_sign_ext_start
          (gpgme_ctx_t CTX, gpgme_key_t RECP[], const char *RECPSTRING,
          gpgme_encrypt_flags_t FLAGS, gpgme_data_t PLAIN,
          gpgme_data_t CIPHER)

     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.