Imported Upstream version 1.9.0upstream/1.9.0

1 files changed, 223 insertions, 47 deletions

diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1
index bc822a4..4b9ec87 100644
--- a/doc/gpgme.info-1
+++ b/doc/gpgme.info-1
@@ -1,6 +1,6 @@
-This is gpgme.info, produced by makeinfo version 5.2 from gpgme.texi.
+This is gpgme.info, produced by makeinfo version 6.3 from gpgme.texi.
 
-Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH.
+Copyright © 2002–2008, 2010, 2012–2017 g10 Code GmbH.
 
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU General Public License as
@@ -19,10 +19,10 @@ END-INFO-DIR-ENTRY
 
    This file documents the GPGME library.
 
-   This is Edition 1.8.0-beta50, last updated 16 November 2016, of ‘The
-‘GnuPG Made Easy’ Reference Manual’, for Version 1.8.0-beta50.
+   This is Edition 1.9.0, last updated 16 November 2016, of ‘The ‘GnuPG
+Made Easy’ Reference Manual’, for Version 1.9.0.
 
-   Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH.
+   Copyright © 2002–2008, 2010, 2012–2017 g10 Code GmbH.
 
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU General Public License as
@@ -41,9 +41,8 @@ File: gpgme.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Main Menu
 *********
 
-This is Edition 1.8.0-beta50, last updated 16 November 2016, of ‘The
-‘GnuPG Made Easy’ Reference Manual’, for Version 1.8.0-beta50 of the
-GPGME library.
+This is Edition 1.9.0, last updated 16 November 2016, of ‘The ‘GnuPG
+Made Easy’ Reference Manual’, for Version 1.9.0 of the GPGME library.
 
 * Menu:
 
@@ -899,6 +898,9 @@ File: gpgme.info,  Node: Engine Version Check,  Next: Engine Information,  Up: P
      ‘g13-name’
           Return the name of the file container encryption engine.
 
+     ‘gpg-wks-client-name’
+          Return the name of the Web Key Service tool.
+
  -- Function: gpgme_error_t gpgme_engine_check_version
           (gpgme_protocol_t PROTOCOL)
      The function ‘gpgme_engine_check_version’ verifies that the engine
@@ -2689,6 +2691,26 @@ File: gpgme.info,  Node: Status Message Callback,  Next: Locale,  Prev: Progress
      set by this function.  The properties are identified by the
      following values for NAME:
 
+     ‘"redraw"’
+          This flag is normally not changed by the caller because GPGME
+          sets and clears it automatically: The flag is cleared before
+          an operation and set if an operation noticed that the engine
+          has launched a Pinentry.  A Curses based application may use
+          this information to redraw the screen; for example:
+
+                   err = gpgme_op_keylist_start (ctx, "foo@example.org", 0);
+                   while (!err)
+                     {
+                       err = gpgme_op_keylist_next (ctx, &key);
+                       if (err)
+                         break;
+                       show_key (key);
+                       gpgme_key_release (key);
+                     }
+                   if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s)
+                     redraw_screen ();
+                   gpgme_release (ctx);
+
      ‘"full-status"’
           Using a VALUE of "1" the status callback set by
           gpgme_set_status_cb returns all status lines with the
@@ -2850,6 +2872,9 @@ long as the key object itself is valid.
           secret keys has been requested or if
           ‘GPGME_KEYLIST_MODE_WITH_SECRET’ is active.
 
+     ‘unsigned int origin : 5’
+          Reserved for the origin of this key.
+
      ‘gpgme_protocol_t protocol’
           This is the protocol supported by this key.
 
@@ -2884,6 +2909,9 @@ long as the key object itself is valid.
           a subkey may be missing but this field may be set
           nevertheless.
 
+     ‘unsigned long last_update’
+          Reserved for the time of the last update of this key.
+
  -- Data type: gpgme_subkey_t
 
      The ‘gpgme_subkey_t’ type is a pointer to a subkey structure.
@@ -2929,6 +2957,12 @@ long as the key object itself is valid.
           This is true if the subkey can be used for qualified
           signatures according to local government regulations.
 
+     ‘unsigned int is_de_vs : 1’
+          This is true if the subkey complies with the rules for
+          classified information in Germany at the restricted level
+          (VS-NfD). This are currently RSA keys of at least 2048 bits or
+          ECDH/ECDSA keys using a Brainpool curve.
+
      ‘unsigned int secret : 1’
           This is true if the subkey is a secret key.  Note that it will
           be false if the key is actually a stub key; i.e.  a secret key
@@ -3016,6 +3050,12 @@ long as the key object itself is valid.
      ‘gpgme_key_sig_t signatures’
           This is a linked list with the signatures on this user ID.
 
+     ‘unsigned int origin : 5’
+          Reserved for the origin of this user ID.
+
+     ‘unsigned long last_update’
+          Reserved for the time of the last update of this user ID.
+
  -- Data type: gpgme_key_sig_t
 
      The ‘gpgme_key_sig_t’ type is a pointer to a key signature
@@ -3098,6 +3138,7 @@ File: gpgme.info,  Node: Listing Keys,  Next: Information About Keys,  Prev: Key
 
  -- Function: gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t CTX,
           const char *PATTERN, int SECRET_ONLY)
+
      The function ‘gpgme_op_keylist_start’ initiates a key listing
      operation inside the context CTX.  It sets everything up so that
      subsequent invocations of ‘gpgme_op_keylist_next’ return the keys
@@ -3125,6 +3166,7 @@ File: gpgme.info,  Node: Listing Keys,  Next: Information About Keys,  Prev: Key
 
  -- Function: gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t CTX,
           const char *PATTERN[], int SECRET_ONLY, int RESERVED)
+
      The function ‘gpgme_op_keylist_ext_start’ initiates an extended key
      listing operation inside the context CTX.  It sets everything up so
      that subsequent invocations of ‘gpgme_op_keylist_next’ return the
@@ -3154,8 +3196,34 @@ File: gpgme.info,  Node: Listing Keys,  Next: Information About Keys,  Prev: Key
      not a valid pointer, and passes through any errors that are
      reported by the crypto engine support routines.
 
+ -- Function: gpgme_error_t gpgme_op_keylist_from_data (gpgme_ctx_t CTX,
+          gpgme_data_t DATA, int RESERVED)
+
+     The function ‘gpgme_op_keylist_from_data_start’ initiates a key
+     listing operation inside the context CTX.  In contrast to the other
+     key listing operation the keys are read from the supplied DATA and
+     not from the local key database.  The keys are also not imported
+     into the local key database.  The function sets everything up so
+     that subsequent invocations of ‘gpgme_op_keylist_next’ return the
+     keys from DATA.
+
+     The value of RESERVED must be ‘0’.
+
+     This function requires at least GnuPG version 2.1.14 and currently
+     works only with OpenPGP keys.
+
+     The context will be busy until either all keys are received (and
+     ‘gpgme_op_keylist_next’ returns ‘GPG_ERR_EOF’), or
+     ‘gpgme_op_keylist_end’ is called to finish the operation.  While
+     the context is busy DATA may not be released.
+
+     The function returns the error code ‘GPG_ERR_INV_VALUE’ if CTX is
+     not a valid pointer, and passes through any errors that are
+     reported by the crypto engine support routines.
+
  -- Function: gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t CTX,
           gpgme_key_t *R_KEY)
+
      The function ‘gpgme_op_keylist_next’ returns the next key in the
      list created by a previous ‘gpgme_op_keylist_start’ operation in
      the context CTX.  The key will have one reference for the user.
@@ -3171,6 +3239,7 @@ File: gpgme.info,  Node: Listing Keys,  Next: Information About Keys,  Prev: Key
      enough memory for the operation.
 
  -- Function: gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t CTX)
+
      The function ‘gpgme_op_keylist_end’ ends a pending key list
      operation in the context CTX.
 
@@ -3183,7 +3252,7 @@ File: gpgme.info,  Node: Listing Keys,  Next: Information About Keys,  Prev: Key
 
    The following example illustrates how all keys containing a certain
 string (‘g10code’) can be listed with their key ID and the name and
-e-mail address of the main user ID:
+email address of the main user ID:
 
      gpgme_ctx_t ctx;
      gpgme_key_t key;
@@ -3349,13 +3418,13 @@ provide a fallback to the old function if the error code
 
      RESERVED must be set to zero.
 
-     EXPIRES can be set to the number of seconds since Epoch of the
-     desired expiration date in UTC for the new key.  Using 0 does not
-     set an expiration date.  Note that this parameter takes an unsigned
-     long value and not a ‘time_t’ to avoid problems on systems which
-     use a signed 32 bit ‘time_t’.  Note further that the OpenPGP
-     protocol uses 32 bit values for timestamps and thus can only encode
-     dates up to the year 2106.
+     EXPIRES specifies the expiration time in seconds.  If you supply 0,
+     a reasonable expiration time is chosen.  Use the flag
+     ‘GPGME_CREATE_NOEXPIRE’ to create keys that do not expire.  Note
+     that this parameter takes an unsigned long value and not a ‘time_t’
+     to avoid problems on systems which use a signed 32 bit ‘time_t’.
+     Note further that the OpenPGP protocol uses 32 bit values for
+     timestamps and thus can only encode dates up to the year 2106.
 
      EXTRAKEY is currently not used and must be set to ‘NULL’.  A future
      version of GPGME may use this parameter to create X.509 keys.
@@ -3397,6 +3466,9 @@ provide a fallback to the old function if the error code
           already existing in the local key database.  This flag can be
           used to override this check.
 
+     ‘GPGME_CREATE_NOEXPIRE’
+          Request generation of keys that do not expire.
+
      After the operation completed successfully, information about the
      created key can be retrieved with ‘gpgme_op_genkey_result’.
 
@@ -3438,13 +3510,13 @@ provide a fallback to the old function if the error code
 
      RESERVED must be set to zero.
 
-     EXPIRES can be set to the number of seconds since Epoch of the
-     desired expiration date in UTC for the new subkey.  Using 0 does
-     not set an expiration date.  Note that this parameter takes an
-     unsigned long value and not a ‘time_t’ to avoid problems on systems
-     which use a signed 32 bit ‘time_t’.  Note further that the OpenPGP
-     protocol uses 32 bit values for timestamps and thus can only encode
-     dates up to the year 2106.
+     EXPIRES specifies the expiration time in seconds.  If you supply 0,
+     a reasonable expiration time is chosen.  Use the flag
+     ‘GPGME_CREATE_NOEXPIRE’ to create keys that do not expire.  Note
+     that this parameter takes an unsigned long value and not a ‘time_t’
+     to avoid problems on systems which use a signed 32 bit ‘time_t’.
+     Note further that the OpenPGP protocol uses 32 bit values for
+     timestamps and thus can only encode dates up to the year 2106.
 
      FLAGS takes the same values as described above for
      ‘gpgme_op_createkey’.
@@ -3530,6 +3602,45 @@ provide a fallback to the old function if the error code
      operation; see there for details.  It must be completed by calling
      ‘gpgme_wait’ on the context.  *Note Waiting For Completion::.
 
+ -- Function: gpgme_error_t gpgme_op_set_ui_flag (gpgme_ctx_t CTX,
+          gpgme_key_t KEY, const char *USERID, cons char * NAME,
+          cons char * VALUE);
+
+     The function ‘gpgme_op_set_uid_flag’ is used to set flags on a user
+     ID from the OpenPGP key given by KEY.  Setting flags on user IDs
+     after key creation is a feature of the OpenPGP protocol and thus
+     the protocol for the context CTX must be set to OpenPGP.
+
+     KEY specifies the key to operate on.  This parameters is required.
+
+     USERID is the user ID of the key to be manipulated.  This user ID
+     must be given verbatim because the engine does an exact and case
+     sensitive match.  Thus the ‘uid’ field from the user ID object
+     (‘gpgme_user_id_t’) is to be used.  This is a required parameter.
+
+     NAME names the flag which is to be changed.  The only currently
+     supported flag is:
+
+     ‘primary’
+          This sets the primary key flag on the given user ID. All other
+          primary key flag on other user IDs are removed.  VALUE must be
+          given as NULL. For technical reasons this functions bumps the
+          creation timestamp of all affected self-signatures up by one
+          second.  At least GnuPG version 2.1.20 is required.
+
+     The function returns zero on success, ‘GPG_ERR_NOT_SUPPORTED’ if
+     the engine does not support the command, or a bunch of other error
+     codes.
+
+ -- Function: gpgme_error_t gpgme_op_set_uid_flag_start
+          (gpgme_ctx_t CTX, gpgme_key_t KEY, const char *USERID,
+          cons char * NAME, cons char * VALUE);
+
+     The function ‘gpgme_op_set_uid_flag_start’ initiates a
+     ‘gpgme_op_set_uid_flag’ operation; see there for details.  It must
+     be completed by calling ‘gpgme_wait’ on the context.  *Note Waiting
+     For Completion::.
+
  -- Function: gpgme_error_t gpgme_op_genkey (gpgme_ctx_t CTX,
           const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET)
 
@@ -3548,11 +3659,17 @@ provide a fallback to the old function if the error code
      signed by the certification authority and imported before it can be
      used.  GpgSM does not make the fingerprint available.
 
-     The argument PARMS specifies parameters for the key in an XML
-     string.  The details about the format of PARMS are specific to the
-     crypto engine used by CTX.  Here is an example for GnuPG as the
-     crypto engine (all parameters of OpenPGP key generation are
-     documented in the GPG manual):
+     The argument PARMS specifies parameters for the key in an string
+     that looks something like XML. The details about the format of
+     PARMS are specific to the crypto engine used by CTX.  The first
+     line of the parameters must be ‘<GnupgKeyParams format="internal">’
+     and the last line must be ‘</GnupgKeyParams>’.  Every line in
+     between the first and last lines is treated as a Header: Value
+     pair.  In particular, no XML escaping is necessary if you need to
+     include the characters ‘<’, ‘>’, or ‘&’.
+
+     Here is an example for GnuPG as the crypto engine (all parameters
+     of OpenPGP key generation are documented in the GPG manual):
 
           <GnupgKeyParms format="internal">
           Key-Type: default
@@ -3584,9 +3701,10 @@ provide a fallback to the old function if the error code
 
      The function returns the error code ‘GPG_ERR_NO_ERROR’ if the
      operation could be started successfully, ‘GPG_ERR_INV_VALUE’ if
-     PARMS is not a valid XML string, ‘GPG_ERR_NOT_SUPPORTED’ if PUBLIC
-     or SECRET is not valid, and ‘GPG_ERR_GENERAL’ if no key was created
-     by the backend.
+     PARMS is not a well-formed string (e.g.  does not have the expected
+     tag-like headers and footers), ‘GPG_ERR_NOT_SUPPORTED’ if PUBLIC or
+     SECRET is not valid, and ‘GPG_ERR_GENERAL’ if no key was created by
+     the backend.
 
  -- Function: gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t CTX,
           const char *PARMS, gpgme_data_t PUBLIC, gpgme_data_t SECRET)
@@ -3681,16 +3799,15 @@ to create key signatures when using modern GnuPG versions.
      put them all into one string separated by linefeeds characters
      (‘\n’) and set the flag ‘GPGME_KEYSIGN_LFSEP’.
 
-     EXPIRES can be set to the number of seconds since Epoch of the
-     desired expiration date in UTC for the new signature.  The common
-     case is to use 0 to not set an expiration date.  However, if the
-     configuration of the engine defines a default expiration for key
-     signatures, that is still used unless the flag
-     ‘GPGME_KEYSIGN_NOEXPIRE’ is used.  Note that this parameter takes
-     an unsigned long value and not a ‘time_t’ to avoid problems on
-     systems which use a signed 32 bit ‘time_t’.  Note further that the
-     OpenPGP protocol uses 32 bit values for timestamps and thus can
-     only encode dates up to the year 2106.
+     EXPIRES specifies the expiration time of the new signature in
+     seconds.  The common case is to use 0 to not set an expiration
+     date.  However, if the configuration of the engine defines a
+     default expiration for key signatures, that is still used unless
+     the flag ‘GPGME_KEYSIGN_NOEXPIRE’ is used.  Note that this
+     parameter takes an unsigned long value and not a ‘time_t’ to avoid
+     problems on systems which use a signed 32 bit ‘time_t’.  Note
+     further that the OpenPGP protocol uses 32 bit values for timestamps
+     and thus can only encode dates up to the year 2106.
 
      FLAGS can be set to the bit-wise OR of the following flags:
 
@@ -4099,7 +4216,7 @@ File: gpgme.info,  Node: Changing TOFU Data,  Next: Advanced Key Editing,  Prev:
 -------------------------
 
 The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation
-model.  For resolving clonflics it is necessary to declare the policy
+model.  For resolving conflicts it is necessary to declare the policy
 for a key.  See the GnuPG manual for details on the TOFU implementation.
 
  -- Data type: enum gpgme_tofu_policy_t
@@ -4109,7 +4226,7 @@ for a key.  See the GnuPG manual for details on the TOFU implementation.
      ‘GPGME_TOFU_POLICY_AUTO’
           Set the policy to “auto”.
      ‘GPGME_TOFU_POLICY_GOOD’
-          Set the policy to “goog”.
+          Set the policy to “good”.
      ‘GPGME_TOFU_POLICY_BAD’
           Set the policy to “bad”.
      ‘GPGME_TOFU_POLICY_ASK’
@@ -4366,6 +4483,42 @@ File: gpgme.info,  Node: Decrypt,  Next: Verify,  Up: Crypto Operations
      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)
+
+     The function ‘gpgme_op_decrypt_ext’ is the same as
+     ‘gpgme_op_decrypt_ext’ but has an additional argument FLAGS.  If
+     FLAGS is 0 both function behave identically.
+
+     The value in FLAGS is a bitwise-or combination of one or multiple
+     of the following bit values:
+
+     ‘GPGME_DECRYPT_VERIFY’
+          The ‘GPGME_DECRYPT_VERIFY’ symbol specifies that this function
+          shall exacty act as ‘gpgme_op_decrypt_verify’.
+
+     ‘GPGME_DECRYPT_UNWRAP’
+          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 descriped for
+     ‘gpgme_op_decrypt’ respective ‘gpgme_op_encrypt’.
+
+ -- 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)
+
+     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
      This is a pointer to a structure used to store information about
      the recipient of an encrypted text which is decrypted in a
@@ -4538,7 +4691,17 @@ File: gpgme.info,  Node: Verify,  Next: Decrypt and Verify,  Prev: Decrypt,  Up:
           This is a bit vector giving a summary of the signature status.
           It provides an easy interface to a defined semantic of the
           signature status.  Checking just one bit is sufficient to see
-          whether a signature is valid without any restrictions.
+          whether a signature is valid without any restrictions.  This
+          means that you can check for GPGME_SIGSUM_VALID like this:
+
+               if ((sig.summary & GPGME_SIGSUM_VALID))
+               {
+                  ..do stuff if valid..
+               }
+               else
+               {
+                  ..do stuff if not fully valid..
+               }
 
           The defined bits are:
           ‘GPGME_SIGSUM_VALID’
@@ -5047,10 +5210,23 @@ File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt
 
      ‘GPGME_ENCRYPT_SYMMETRIC’
           The ‘GPGME_ENCRYPT_SYMMETRIC’ symbol specifies that the output
-          should be additionally encrypted symmetically even if
+          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’
+          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’
+          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
@@ -5121,7 +5297,7 @@ File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt
      for the OpenPGP crypto engine.
 
  -- Function: gpgme_error_t gpgme_op_encrypt_sign_start
-          (gpgme_ctx_t CTX, gpgme_key_t RECP,
+          (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
@@ -5879,7 +6055,7 @@ next.  We only support waiting for the success of a single operation.
            exit (1);
          }
        /* Evaluate verify result.  */
-       …
+       ...
        return 0;
      }