Imported Upstream version 1.11.0upstream/1.11.0

1 files changed, 152 insertions, 142 deletions

diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1
index 4dc3349..888e180 100644
--- a/doc/gpgme.info-1
+++ b/doc/gpgme.info-1
@@ -19,8 +19,8 @@ END-INFO-DIR-ENTRY
 
    This file documents the GPGME library.
 
-   This is Edition 1.10.0, last updated 8 December 2017, of ‘The ‘GnuPG
-Made Easy’ Reference Manual’, for Version 1.10.0.
+   This is Edition 1.10.1-beta188, last updated 8 December 2017, of ‘The
+‘GnuPG Made Easy’ Reference Manual’, for Version 1.10.1-beta188.
 
    Copyright © 2002–2008, 2010, 2012–2017 g10 Code GmbH.
 
@@ -41,8 +41,9 @@ File: gpgme.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Main Menu
 *********
 
-This is Edition 1.10.0, last updated 8 December 2017, of ‘The ‘GnuPG
-Made Easy’ Reference Manual’, for Version 1.10.0 of the GPGME library.
+This is Edition 1.10.1-beta188, last updated 8 December 2017, of ‘The
+‘GnuPG Made Easy’ Reference Manual’, for Version 1.10.1-beta188 of the
+GPGME library.
 
 * Menu:
 
@@ -2421,20 +2422,26 @@ File: gpgme.info,  Node: Offline Mode,  Next: Pinentry Mode,  Prev: Text Mode,
      SINCE: 1.6.0
 
      The function ‘gpgme_set_offline’ specifies if offline mode should
-     be used.  By default, offline mode is not used.
+     be used.  Offline mode is disabled if YES is zero, and enabled
+     otherwise.  By default, offline mode is disabled.
 
-     The offline mode specifies if dirmngr should be used to do
-     additional validation that might require connections to external
-     services.  (e.g.  CRL / OCSP checks).
+     The details of the offline mode depend on the used protocol and its
+     backend engine.  It may eventually be extended to be more stricter
+     and for example completely disable the use of Dirmngr for any
+     engine.
 
-     Offline mode only affects the keylist mode
-     ‘GPGME_KEYLIST_MODE_VALIDATE’ and is only relevant to the CMS
-     crypto engine.  Offline mode is ignored otherwise.
+     For the CMS protocol the offline mode specifies whether Dirmngr
+     shall be used to do additional validation that might require
+     connecting external services (e.g.  CRL / OCSP checks).  Here the
+     offline mode only affects the keylist mode
+     ‘GPGME_KEYLIST_MODE_VALIDATE’.
 
-     This option may be extended in the future to completely disable the
-     use of dirmngr for any engine.
+     For the OpenPGP protocol offline mode entirely disables the use of
+     the Dirmngr and will thus guarantee that no network connections are
+     done as part of an operation on this context.  It has only an
+     effect with GnuPG versions 2.1.23 or later.
 
-     Offline mode is disabled if YES is zero, and enabled otherwise.
+     For all other protocols the offline mode is currently ignored.
 
  -- Function: int gpgme_get_offline (gpgme_ctx_t CTX)
      SINCE: 1.6.0
@@ -2570,6 +2577,11 @@ File: gpgme.info,  Node: Key Listing Mode,  Next: Passphrase Callback,  Prev: In
           ‘GPGME_KEYLIST_MODE_LOCAL’.  For example, it can be a remote
           keyserver or LDAP certificate server.
 
+     ‘GPGME_KEYLIST_MODE_LOCATE’
+          This is a shortcut for the combination of
+          ‘GPGME_KEYLIST_MODE_LOCAL’ and ‘GPGME_KEYLIST_MODE_EXTERN’ and
+          convenient when the –locate-key feature of OpenPGP is desired.
+
      ‘GPGME_KEYLIST_MODE_SIGS’
           The ‘GPGME_KEYLIST_MODE_SIGS’ symbol specifies that the key
           signatures should be included in the listed keys.
@@ -2860,6 +2872,19 @@ File: gpgme.info,  Node: Status Message Callback,  Next: Locale,  Prev: Progress
           the operator can tell both your IP address and the time when
           you verified the signature.
 
+     ‘"request-origin"’
+          The string given in VALUE is passed to the GnuPG engines to
+          request restrictions based on the origin of the request.
+          Valid values are documented in the GnuPG manual and the gpg
+          man page under the option “–request-origin”.  Requires at
+          least GnuPG 2.2.6 to have an effect.
+
+     ‘"no-symkey-cache"’
+          For OpenPGP disable the passphrase cache used for symmetrical
+          en- and decryption.  This cache is based on the message
+          specific salt value.  Requires at least GnuPG 2.2.7 to have an
+          effect.
+
      This function returns ‘0’ on success.
 
  -- Function: const char * gpgme_get_ctx_flag (gpgme_ctx_t CTX,
@@ -4423,6 +4448,12 @@ Importing keys means the same as running ‘gpg’ with the command
           A list of gpgme_import_status_t objects which contain more
           information about the keys for which an import was attempted.
 
+     ‘int skipped_v3_keys’
+          For security reasons modern versions of GnuPG do not anymore
+          support v3 keys (created with PGP 2.x) and ignores them on
+          import.  This counter provides the number of such skipped v3
+          keys.
+
  -- Function: gpgme_import_result_t gpgme_op_import_result
           (gpgme_ctx_t CTX)
      The function ‘gpgme_op_import_result’ returns a
@@ -4827,8 +4858,8 @@ File: gpgme.info,  Node: Decrypt,  Next: Verify,  Up: Crypto Operations
      SINCE: 1.8.0
 
      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.
+     ‘gpgme_op_decrypt’ 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:
@@ -4933,6 +4964,13 @@ File: gpgme.info,  Node: Decrypt,  Next: Verify,  Up: Crypto Operations
           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 "<algo>.<mode>".  Note that old 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
@@ -5592,7 +5630,7 @@ File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt
           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.
+          the OpenPGP crypto engine.
 
      ‘GPGME_ENCRYPT_THROW_KEYIDS’
           SINCE: 1.8.0
@@ -5611,6 +5649,19 @@ File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt
           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.
+
      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
@@ -5648,6 +5699,60 @@ File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt
      ‘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.
+
+ -- 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,
@@ -5692,6 +5797,36 @@ File: gpgme.info,  Node: Encrypting a Plaintext,  Up: Encrypt
      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.
+
 
 File: gpgme.info,  Node: Miscellaneous,  Next: Run Control,  Prev: Crypto Operations,  Up: Contexts
 
@@ -7132,128 +7267,3 @@ commands.  Afterwards, the actual operation is requested:
    FIXME: It may be nice to support an ‘EXPORT’ command as well, which
 is enabled by the context menu of the background of a directory.
 
-
-File: gpgme.info,  Node: UI Server Checksum Files,  Next: Miscellaneous UI Server Commands,  Prev: UI Server Import/Export Keys,  Up: UI Server Protocol
-
-A.9 UI Server: Create and verify checksums for files.
-=====================================================
-
-First, the input files need to be specified by one or more ‘FILE’
-commands.  Afterwards, the actual operation is requested:
-
- -- Command: CHECKSUM_CREATE_FILES --nohup
-     Request that checksums are created for the files specified by
-     ‘FILE’.  The choice of checksum algorithm and the destination
-     storage and format for the created checksums depend on the
-     preferences of the user and the functionality provided by the UI
-     server.  For directories, the server may offer multiple options to
-     the user (for example ignore or process recursively).
-
-     The option ‘--nohup’ is mandatory.  It is currently unspecified
-     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’
-     is present, the server always returns ‘OK’ promptly, and completes
-     the operation asynchronously.
-
- -- Command: CHECKSUM_VERIFY_FILES --nohup
-     Request that checksums are created for the files specified by
-     ‘FILE’ and verified against previously created and stored
-     checksums.  The choice of checksum algorithm and the source storage
-     and format for previously created checksums depend on the
-     preferences of the user and the functionality provided by the UI
-     server.  For directories, the server may offer multiple options to
-     the user (for example ignore or process recursively).
-
-     If the source storage of previously created checksums is available
-     to the user through the Windows shell, this command may also accept
-     such checksum files as ‘FILE’ arguments.  In this case, the UI
-     server should instead verify the checksum of the referenced files
-     as if they were given as INPUT files.
-
-     The option ‘--nohup’ is mandatory.  It is currently unspecified
-     what should happen if ‘--nohup’ is not present.  Because ‘--nohup’
-     is present, the server always returns ‘OK’ promptly, and completes
-     the operation asynchronously.
-
-
-File: gpgme.info,  Node: Miscellaneous UI Server Commands,  Prev: UI Server Checksum Files,  Up: UI Server Protocol
-
-A.10 Miscellaneous UI Server Commands
-=====================================
-
-The server needs to implement the following commands which are not
-related to a specific command:
-
- -- Command: GETINFO WHAT
-     This is a multi purpose command, commonly used to return a variety
-     of information.  The required subcommands as described by the WHAT
-     parameter are:
-
-     ‘pid’
-          Return the process id of the server in decimal notation using
-          an Assuan data line.
-
-To allow the server to pop up the windows in the correct relation to the
-client, the client is advised to tell the server by sending the option:
-
- -- Command option: window-id NUMBER
-     The NUMBER represents the native window ID of the clients current
-     window.  On Windows systems this is a windows handle (‘HWND’) and
-     on X11 systems it is the ‘X Window ID’.  The number needs to be
-     given as a hexadecimal value so that it is easier to convey pointer
-     values (e.g.  ‘HWND’).
-
-A client may want to fire up the certificate manager of the server.  To
-do this it uses the Assuan command:
-
- -- Command: START_KEYMANAGER
-     The server shall pop up the main window of the key manager (aka
-     certificate manager).  The client expects that the key manager is
-     brought into the foregound and that this command immediatley
-     returns (does not wait until the key manager has been fully brought
-     up).
-
-A client may want to fire up the configuration dialog of the server.  To
-do this it uses the Assuan command:
-
- -- Command: START_CONFDIALOG
-     The server shall pop up its configuration dialog.  The client
-     expects that this dialog is brought into the foregound and that
-     this command immediatley returns (i.e.  it does not wait until the
-     dialog has been fully brought up).
-
-When doing an operation on a mail, it is useful to let the server know
-the address of the sender:
-
- -- Command: SENDER [--info] [--protocol=NAME] EMAIL
-     EMAIL is the plain ASCII encoded address ("addr-spec" as per
-     RFC-2822) enclosed in angle brackets.  The address set with this
-     command is valid until a successful completion of the operation or
-     until a ‘RESET’ command.  A second command overrides the effect of
-     the first one; if EMAIL is not given and ‘--info’ is not used, the
-     server shall use the default signing key.
-
-     If option ‘--info’ is not given, the server shall also suggest a
-     protocol to use for signing.  The client may use this suggested
-     protocol on its own discretion.  The same status line as with
-     PREP_ENCRYPT is used for this.
-
-     The option ‘--protocol’ may be used to give the server a hint on
-     which signing protocol should be preferred.
-
-To allow the UI-server to visually identify a running operation or to
-associate operations the server MAY support the command:
-
- -- Command: SESSION NUMBER [STRING]
-     The NUMBER is an arbitrary value, a server may use to associate
-     simultaneous running sessions.  It is a 32 bit unsigned integer
-     with ‘0’ as a special value indicating that no session association
-     shall be done.
-
-     If STRING is given, the server may use this as the title of a
-     window or, in the case of an email operation, to extract the
-     sender’s address.  The string may contain spaces; thus no
-     plus-escaping is used.
-
-     This command may be used at any time and overrides the effect of
-     the last command.  A ‘RESET’ undoes the effect of this command.
-