diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 4 | ||||
| -rw-r--r-- | doc/gpgme.info | 252 | ||||
| -rw-r--r-- | doc/gpgme.info-1 | 270 | ||||
| -rw-r--r-- | doc/gpgme.info-2 | 173 | ||||
| -rw-r--r-- | doc/gpgme.texi | 283 |
5 files changed, 689 insertions, 293 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index 1fd44b6..2f628fc 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -110,8 +110,8 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/ax_cxx_compile_stdcxx.m4 \ $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \ $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/m4/pkg.m4 \ - $(top_srcdir)/m4/qt.m4 $(top_srcdir)/acinclude.m4 \ - $(top_srcdir)/configure.ac + $(top_srcdir)/m4/python.m4 $(top_srcdir)/m4/qt.m4 \ + $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(SHELL) $(top_srcdir)/build-aux/mkinstalldirs diff --git a/doc/gpgme.info b/doc/gpgme.info index 801e07a..b6b6e44 100644 --- a/doc/gpgme.info +++ b/doc/gpgme.info @@ -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 @@ -37,130 +37,130 @@ Public License for more details. Indirect: -gpgme.info-1: 1686 -gpgme.info-2: 314031 +gpgme.info-1: 1672 +gpgme.info-2: 321787 Tag Table: (Indirect) -Node: Top1686 -Node: Introduction9293 -Node: Getting Started10083 -Node: Features11544 -Node: Overview12856 -Node: Preparation13965 -Node: Header14962 -Node: Building the Source15709 -Node: Largefile Support (LFS)17853 -Node: Using Automake23267 -Node: Using Libtool25820 -Node: Library Version Check26182 -Node: Signal Handling32194 -Node: Multi-Threading33464 -Ref: Multi-Threading-Footnote-134880 -Node: Protocols and Engines35303 -Node: Engine Version Check37948 -Node: Engine Information40365 -Node: Engine Configuration44225 -Node: OpenPGP45509 -Node: Cryptographic Message Syntax45849 -Node: Assuan46162 -Node: Algorithms46536 -Ref: Algorithms-Footnote-147015 -Node: Public Key Algorithms47143 -Node: Hash Algorithms49630 -Node: Error Handling50820 -Node: Error Values52694 -Node: Error Sources57897 -Node: Error Codes60337 -Node: Error Strings65128 -Node: Exchanging Data66935 -Node: Creating Data Buffers68801 -Node: Memory Based Data Buffers69317 -Node: File Based Data Buffers72750 -Node: Callback Based Data Buffers74952 -Node: Destroying Data Buffers79143 -Node: Manipulating Data Buffers80631 -Node: Data Buffer I/O Operations81123 -Node: Data Buffer Meta-Data83496 -Node: Data Buffer Convenience87862 -Node: Contexts89839 -Node: Creating Contexts91025 -Node: Destroying Contexts91872 -Node: Result Management92211 -Node: Context Attributes93754 -Node: Protocol Selection94791 -Node: Crypto Engine95823 -Node: Setting the Sender97673 -Node: ASCII Armor99148 -Node: Text Mode99777 -Node: Offline Mode100711 -Node: Pinentry Mode101783 -Node: Included Certificates103468 -Node: Key Listing Mode104890 -Node: Passphrase Callback108982 -Node: Progress Meter Callback112369 -Node: Status Message Callback114354 -Node: Locale118175 -Node: Key Management119734 -Node: Key objects120962 -Node: Listing Keys131962 -Node: Information About Keys139408 -Node: Manipulating Keys140716 -Node: Generating Keys141286 -Node: Signing Keys156760 -Node: Exporting Keys160358 -Node: Importing Keys167051 -Ref: Importing Keys-Footnote-1173956 -Node: Deleting Keys174084 -Node: Changing Passphrases175529 -Node: Changing TOFU Data176818 -Node: Advanced Key Editing178869 -Node: Trust Item Management181518 -Node: Listing Trust Items182554 -Node: Manipulating Trust Items184915 -Node: Crypto Operations185558 -Node: Decrypt186822 -Node: Verify191524 -Node: Decrypt and Verify203484 -Node: Sign206320 -Node: Selecting Signers206884 -Node: Creating a Signature208271 -Node: Signature Notation Data213041 -Node: Encrypt215269 -Node: Encrypting a Plaintext215625 -Node: Miscellaneous222588 -Node: Running other Programs223000 -Node: Using the Assuan protocol225076 -Node: Checking for updates227798 -Node: Run Control232556 -Node: Waiting For Completion233300 -Node: Using External Event Loops235418 -Node: I/O Callback Interface237390 -Node: Registering I/O Callbacks242628 -Node: I/O Callback Example244666 -Node: I/O Callback Example GTK+251291 -Node: I/O Callback Example GDK253080 -Node: I/O Callback Example Qt254722 -Node: Cancellation257010 -Node: UI Server Protocol259280 -Ref: UI Server Protocol-Footnote-1260715 -Node: UI Server Encrypt260834 -Node: UI Server Sign266192 -Node: UI Server Decrypt268545 -Node: UI Server Verify270200 -Node: UI Server Set Input Files273772 -Node: UI Server Sign/Encrypt Files274842 -Node: UI Server Verify/Decrypt Files276650 -Node: UI Server Import/Export Keys278526 -Node: UI Server Checksum Files279588 -Node: Miscellaneous UI Server Commands281804 -Ref: command SENDER283735 -Node: Debugging285437 -Node: Deprecated Functions287186 -Node: Library Copying314031 -Node: Copying342247 -Node: Concept Index379997 -Node: Function and Data Index394776 +Node: Top1672 +Node: Introduction9265 +Node: Getting Started10055 +Node: Features11516 +Node: Overview12828 +Node: Preparation13937 +Node: Header14934 +Node: Building the Source15681 +Node: Largefile Support (LFS)17825 +Node: Using Automake23239 +Node: Using Libtool25792 +Node: Library Version Check26154 +Node: Signal Handling32166 +Node: Multi-Threading33436 +Ref: Multi-Threading-Footnote-134852 +Node: Protocols and Engines35275 +Node: Engine Version Check37920 +Node: Engine Information40424 +Node: Engine Configuration44284 +Node: OpenPGP45568 +Node: Cryptographic Message Syntax45908 +Node: Assuan46221 +Node: Algorithms46595 +Ref: Algorithms-Footnote-147074 +Node: Public Key Algorithms47202 +Node: Hash Algorithms49689 +Node: Error Handling50879 +Node: Error Values52753 +Node: Error Sources57956 +Node: Error Codes60396 +Node: Error Strings65187 +Node: Exchanging Data66994 +Node: Creating Data Buffers68860 +Node: Memory Based Data Buffers69376 +Node: File Based Data Buffers72809 +Node: Callback Based Data Buffers75011 +Node: Destroying Data Buffers79202 +Node: Manipulating Data Buffers80690 +Node: Data Buffer I/O Operations81182 +Node: Data Buffer Meta-Data83555 +Node: Data Buffer Convenience87921 +Node: Contexts89898 +Node: Creating Contexts91084 +Node: Destroying Contexts91931 +Node: Result Management92270 +Node: Context Attributes93813 +Node: Protocol Selection94850 +Node: Crypto Engine95882 +Node: Setting the Sender97732 +Node: ASCII Armor99207 +Node: Text Mode99836 +Node: Offline Mode100770 +Node: Pinentry Mode101842 +Node: Included Certificates103527 +Node: Key Listing Mode104949 +Node: Passphrase Callback109041 +Node: Progress Meter Callback112428 +Node: Status Message Callback114413 +Node: Locale119123 +Node: Key Management120682 +Node: Key objects121910 +Node: Listing Keys133583 +Node: Information About Keys142211 +Node: Manipulating Keys143519 +Node: Generating Keys144089 +Node: Signing Keys162005 +Node: Exporting Keys165552 +Node: Importing Keys172245 +Ref: Importing Keys-Footnote-1179150 +Node: Deleting Keys179278 +Node: Changing Passphrases180723 +Node: Changing TOFU Data182012 +Node: Advanced Key Editing184063 +Node: Trust Item Management186712 +Node: Listing Trust Items187748 +Node: Manipulating Trust Items190109 +Node: Crypto Operations190752 +Node: Decrypt192016 +Node: Verify198345 +Node: Decrypt and Verify210614 +Node: Sign213450 +Node: Selecting Signers214014 +Node: Creating a Signature215401 +Node: Signature Notation Data220171 +Node: Encrypt222399 +Node: Encrypting a Plaintext222755 +Node: Miscellaneous230358 +Node: Running other Programs230770 +Node: Using the Assuan protocol232846 +Node: Checking for updates235568 +Node: Run Control240326 +Node: Waiting For Completion241070 +Node: Using External Event Loops243188 +Node: I/O Callback Interface245160 +Node: Registering I/O Callbacks250398 +Node: I/O Callback Example252436 +Node: I/O Callback Example GTK+259061 +Node: I/O Callback Example GDK260850 +Node: I/O Callback Example Qt262492 +Node: Cancellation264780 +Node: UI Server Protocol267050 +Ref: UI Server Protocol-Footnote-1268485 +Node: UI Server Encrypt268604 +Node: UI Server Sign273962 +Node: UI Server Decrypt276315 +Node: UI Server Verify277970 +Node: UI Server Set Input Files281542 +Node: UI Server Sign/Encrypt Files282612 +Node: UI Server Verify/Decrypt Files284420 +Node: UI Server Import/Export Keys286296 +Node: UI Server Checksum Files287358 +Node: Miscellaneous UI Server Commands289574 +Ref: command SENDER291505 +Node: Debugging293207 +Node: Deprecated Functions294956 +Node: Library Copying321787 +Node: Copying350007 +Node: Concept Index387757 +Node: Function and Data Index402536 End Tag Table 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; } diff --git a/doc/gpgme.info-2 b/doc/gpgme.info-2 index 7c32470..3285b3b 100644 --- a/doc/gpgme.info-2 +++ b/doc/gpgme.info-2 @@ -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 @@ -122,7 +122,7 @@ combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. - We call this license the "Lesser" General Public License because it + We call this license the “Lesser” General Public License because it does _Less_ to protect the user’s freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are @@ -1527,17 +1527,17 @@ Function and Data Index * enum gpgme_sig_mode_t: Creating a Signature. (line 6) * enum gpgme_sig_stat_t: Deprecated Functions. - (line 427) + (line 434) * enum gpgme_tofu_policy_t: Changing TOFU Data. (line 10) * FILE: UI Server Set Input Files. (line 9) * GETINFO: Miscellaneous UI Server Commands. (line 9) -* gpgme_addrspec_from_uid: Decrypt and Verify. (line 47) +* gpgme_addrspec_from_uid: Decrypt and Verify. (line 48) * gpgme_attr_t: Deprecated Functions. - (line 136) + (line 137) * gpgme_attr_t <1>: Deprecated Functions. - (line 313) + (line 314) * gpgme_cancel: Cancellation. (line 16) * gpgme_cancel_async: Cancellation. (line 36) * gpgme_check_version: Library Version Check. @@ -1556,7 +1556,7 @@ Function and Data Index * gpgme_data_new: Memory Based Data Buffers. (line 12) * gpgme_data_new_from_cbs: Callback Based Data Buffers. - (line 81) + (line 80) * gpgme_data_new_from_fd: File Based Data Buffers. (line 10) * gpgme_data_new_from_file: Memory Based Data Buffers. @@ -1578,13 +1578,13 @@ Function and Data Index * gpgme_data_release_and_get_mem: Destroying Data Buffers. (line 11) * gpgme_data_release_cb_t: Callback Based Data Buffers. - (line 56) + (line 55) * gpgme_data_rewind: Deprecated Functions. - (line 130) + (line 131) * gpgme_data_seek: Data Buffer I/O Operations. - (line 25) + (line 26) * gpgme_data_seek_cb_t: Callback Based Data Buffers. - (line 47) + (line 46) * gpgme_data_set_encoding: Data Buffer Meta-Data. (line 75) * gpgme_data_set_file_name: Data Buffer Meta-Data. @@ -1597,24 +1597,24 @@ Function and Data Index * gpgme_data_write: Data Buffer I/O Operations. (line 16) * gpgme_data_write_cb_t: Callback Based Data Buffers. - (line 30) -* gpgme_decrypt_result_t: Decrypt. (line 54) + (line 29) +* gpgme_decrypt_result_t: Decrypt. (line 91) * gpgme_edit_cb_t: Deprecated Functions. - (line 36) + (line 35) * gpgme_encrypt_result_t: Encrypting a Plaintext. - (line 93) + (line 108) * gpgme_engine_check_version: Engine Version Check. - (line 62) + (line 65) * gpgme_engine_info_t: Engine Information. (line 6) * gpgme_error: Error Values. (line 65) -* gpgme_error_from_errno: Error Values. (line 88) +* gpgme_error_from_errno: Error Values. (line 89) * gpgme_error_t: Error Values. (line 24) * gpgme_error_t (*gpgme_assuan_data_cb_t) (void *OPAQUE, const void *DATA, size_t DATALEN): Using the Assuan protocol. (line 15) * gpgme_error_t (*gpgme_assuan_inquire_cb_t) (void *OPAQUE, const char *NAME, const char *ARGS, gpgme_data_t *R_DATA): Using the Assuan protocol. - (line 23) + (line 22) * gpgme_error_t (*gpgme_assuan_status_cb_t) (void *OPAQUE, const char *STATUS, const char *ARGS): Using the Assuan protocol. - (line 35) + (line 34) * gpgme_error_t (*gpgme_edit_cb_t) (void *HANDLE, gpgme_status_code_t STATUS, const char *ARGS, int FD): Deprecated Functions. (line 33) * gpgme_error_t (*gpgme_interact_cb_t) (void *HANDLE, const char *STATUS, const char *ARGS, int FD): Advanced Key Editing. @@ -1628,11 +1628,11 @@ Function and Data Index * gpgme_error_t (*gpgme_status_cb_t)(void *HOOK, const char *KEYWORD, const char *ARGS): Status Message Callback. (line 6) * gpgme_err_code: Error Values. (line 42) -* gpgme_err_code_from_errno: Error Values. (line 97) +* gpgme_err_code_from_errno: Error Values. (line 98) * gpgme_err_code_t: Error Values. (line 6) -* gpgme_err_code_to_errno: Error Values. (line 102) +* gpgme_err_code_to_errno: Error Values. (line 103) * gpgme_err_make: Error Values. (line 57) -* gpgme_err_make_from_errno: Error Values. (line 82) +* gpgme_err_make_from_errno: Error Values. (line 83) * gpgme_err_source: Error Values. (line 49) * gpgme_err_source_t: Error Values. (line 13) * gpgme_event_io_t: I/O Callback Interface. @@ -1641,18 +1641,18 @@ Function and Data Index (line 7) * gpgme_free: Destroying Data Buffers. (line 25) -* gpgme_genkey_result_t: Generating Keys. (line 295) +* gpgme_genkey_result_t: Generating Keys. (line 347) * gpgme_get_armor: ASCII Armor. (line 13) * gpgme_get_ctx_flag: Status Message Callback. - (line 73) + (line 93) * gpgme_get_dirinfo: Engine Version Check. (line 6) * gpgme_get_engine_info: Engine Information. (line 46) * gpgme_get_include_certs: Included Certificates. - (line 34) + (line 35) * gpgme_get_io_cbs: Registering I/O Callbacks. (line 44) -* gpgme_get_key: Listing Keys. (line 147) +* gpgme_get_key: Listing Keys. (line 177) * gpgme_get_keylist_mode: Key Listing Mode. (line 73) * gpgme_get_offline: Offline Mode. (line 23) * gpgme_get_passphrase_cb: Passphrase Callback. (line 59) @@ -1662,15 +1662,15 @@ Function and Data Index * gpgme_get_protocol: Protocol Selection. (line 21) * gpgme_get_protocol_name: Protocols and Engines. (line 51) -* gpgme_get_sender: Setting the Sender. (line 26) +* gpgme_get_sender: Setting the Sender. (line 27) * gpgme_get_sig_key: Deprecated Functions. - (line 626) + (line 634) * gpgme_get_sig_status: Deprecated Functions. - (line 475) + (line 482) * gpgme_get_sig_string_attr: Deprecated Functions. - (line 530) + (line 538) * gpgme_get_sig_ulong_attr: Deprecated Functions. - (line 564) + (line 572) * gpgme_get_status_cb: Status Message Callback. (line 29) * gpgme_get_textmode: Text Mode. (line 20) @@ -1679,73 +1679,75 @@ Function and Data Index * gpgme_import_result_t: Importing Keys. (line 110) * gpgme_import_status_t: Importing Keys. (line 72) * gpgme_interact_cb_t: Advanced Key Editing. - (line 9) + (line 8) * gpgme_invalid_key_t: Crypto Operations. (line 10) * gpgme_io_cb_t: I/O Callback Interface. (line 7) -* gpgme_keylist_result_t: Listing Keys. (line 124) +* gpgme_keylist_result_t: Listing Keys. (line 154) * gpgme_key_get_string_attr: Deprecated Functions. - (line 278) + (line 279) * gpgme_key_get_ulong_attr: Deprecated Functions. - (line 292) + (line 293) * gpgme_key_ref: Manipulating Keys. (line 6) * gpgme_key_release: Deprecated Functions. (line 14) * gpgme_key_sig_get_string_attr: Deprecated Functions. - (line 369) + (line 370) * gpgme_key_sig_get_ulong_attr: Deprecated Functions. - (line 383) -* gpgme_key_sig_t: Key objects. (line 226) + (line 386) +* gpgme_key_sig_t: Key objects. (line 244) * gpgme_key_t: Key objects. (line 10) * gpgme_key_unref: Manipulating Keys. (line 10) * gpgme_new: Creating Contexts. (line 6) * gpgme_new_signature_t: Creating a Signature. (line 57) * gpgme_off_t: Exchanging Data. (line 24) -* gpgme_op_adduid: Generating Keys. (line 161) -* gpgme_op_adduid_start: Generating Keys. (line 185) +* gpgme_op_adduid: Generating Keys. (line 167) +* gpgme_op_adduid_start: Generating Keys. (line 191) * gpgme_op_assuan_transact_ext: Using the Assuan protocol. (line 56) * gpgme_op_assuan_transact_start: Using the Assuan protocol. - (line 43) + (line 41) * gpgme_op_card_edit: Deprecated Functions. (line 82) * gpgme_op_card_edit_start: Deprecated Functions. (line 92) * gpgme_op_createkey: Generating Keys. (line 14) -* gpgme_op_createkey_start: Generating Keys. (line 99) -* gpgme_op_createsubkey: Generating Keys. (line 109) -* gpgme_op_createsubkey_start: Generating Keys. (line 151) +* gpgme_op_createkey_start: Generating Keys. (line 103) +* gpgme_op_createsubkey: Generating Keys. (line 114) +* gpgme_op_createsubkey_start: Generating Keys. (line 156) * gpgme_op_decrypt: Decrypt. (line 6) -* gpgme_op_decrypt_result: Decrypt. (line 91) +* gpgme_op_decrypt_ext: Decrypt. (line 30) +* gpgme_op_decrypt_ext_start: Decrypt. (line 54) +* gpgme_op_decrypt_result: Decrypt. (line 128) * gpgme_op_decrypt_start: Decrypt. (line 20) * gpgme_op_decrypt_verify: Decrypt and Verify. (line 6) * gpgme_op_decrypt_verify_start: Decrypt and Verify. (line 30) * gpgme_op_delete: Deleting Keys. (line 6) * gpgme_op_delete_start: Deleting Keys. (line 20) * gpgme_op_edit: Deprecated Functions. - (line 47) + (line 46) * gpgme_op_edit_start: Deprecated Functions. (line 68) * gpgme_op_encrypt: Encrypting a Plaintext. (line 6) * gpgme_op_encrypt_result: Encrypting a Plaintext. - (line 104) + (line 119) * gpgme_op_encrypt_sign: Encrypting a Plaintext. - (line 115) + (line 130) * gpgme_op_encrypt_sign_start: Encrypting a Plaintext. - (line 125) + (line 141) * gpgme_op_encrypt_start: Encrypting a Plaintext. - (line 76) + (line 90) * gpgme_op_export: Exporting Keys. (line 38) -* gpgme_op_export_ext: Exporting Keys. (line 69) -* gpgme_op_export_ext_start: Exporting Keys. (line 90) -* gpgme_op_export_keys: Exporting Keys. (line 101) -* gpgme_op_export_keys_start: Exporting Keys. (line 124) -* gpgme_op_export_start: Exporting Keys. (line 58) -* gpgme_op_genkey: Generating Keys. (line 225) -* gpgme_op_genkey_result: Generating Keys. (line 328) -* gpgme_op_genkey_start: Generating Keys. (line 283) +* gpgme_op_export_ext: Exporting Keys. (line 71) +* gpgme_op_export_ext_start: Exporting Keys. (line 93) +* gpgme_op_export_keys: Exporting Keys. (line 105) +* gpgme_op_export_keys_start: Exporting Keys. (line 130) +* gpgme_op_export_start: Exporting Keys. (line 59) +* gpgme_op_genkey: Generating Keys. (line 270) +* gpgme_op_genkey_result: Generating Keys. (line 380) +* gpgme_op_genkey_start: Generating Keys. (line 335) * gpgme_op_import: Importing Keys. (line 9) * gpgme_op_import_ext: Deprecated Functions. (line 22) @@ -1754,16 +1756,17 @@ Function and Data Index * gpgme_op_import_result: Importing Keys. (line 160) * gpgme_op_import_start: Importing Keys. (line 24) * gpgme_op_interact: Advanced Key Editing. - (line 21) + (line 20) * gpgme_op_interact_start: Advanced Key Editing. - (line 46) -* gpgme_op_keylist_end: Listing Keys. (line 81) -* gpgme_op_keylist_ext_start: Listing Keys. (line 33) -* gpgme_op_keylist_next: Listing Keys. (line 65) -* gpgme_op_keylist_result: Listing Keys. (line 135) + (line 45) +* gpgme_op_keylist_end: Listing Keys. (line 110) +* gpgme_op_keylist_ext_start: Listing Keys. (line 34) +* gpgme_op_keylist_from_data: Listing Keys. (line 67) +* gpgme_op_keylist_next: Listing Keys. (line 93) +* gpgme_op_keylist_result: Listing Keys. (line 165) * gpgme_op_keylist_start: Listing Keys. (line 6) * gpgme_op_keysign: Signing Keys. (line 12) -* gpgme_op_keysign_start: Signing Keys. (line 68) +* gpgme_op_keysign_start: Signing Keys. (line 67) * gpgme_op_passwd: Changing Passphrases. (line 6) * gpgme_op_passwd_start: Changing Passphrases. @@ -1772,8 +1775,10 @@ Function and Data Index (line 66) * gpgme_op_query_swdb_result: Checking for updates. (line 76) -* gpgme_op_revuid: Generating Keys. (line 192) -* gpgme_op_revuid_start: Generating Keys. (line 218) +* gpgme_op_revuid: Generating Keys. (line 198) +* gpgme_op_revuid_start: Generating Keys. (line 224) +* gpgme_op_set_uid_flag_start: Generating Keys. (line 261) +* gpgme_op_set_ui_flag: Generating Keys. (line 231) * gpgme_op_sign: Creating a Signature. (line 21) * gpgme_op_sign_result: Creating a Signature. @@ -1790,7 +1795,7 @@ Function and Data Index * gpgme_op_trustlist_next: Listing Trust Items. (line 27) * gpgme_op_trustlist_start: Listing Trust Items. (line 6) * gpgme_op_verify: Verify. (line 6) -* gpgme_op_verify_result: Verify. (line 262) +* gpgme_op_verify_result: Verify. (line 272) * gpgme_op_verify_start: Verify. (line 26) * gpgme_passphrase_cb_t: Passphrase Callback. (line 10) * gpgme_pinentry_mode_t: Pinentry Mode. (line 20) @@ -1802,12 +1807,12 @@ Function and Data Index * gpgme_pubkey_algo_name: Public Key Algorithms. (line 50) * gpgme_pubkey_algo_string: Public Key Algorithms. - (line 59) + (line 60) * gpgme_pubkey_algo_t: Public Key Algorithms. (line 10) * gpgme_query_swdb_result_t: Checking for updates. (line 11) -* gpgme_recipient_t: Decrypt. (line 30) +* gpgme_recipient_t: Decrypt. (line 67) * gpgme_register_io_cb_t: I/O Callback Interface. (line 23) * gpgme_release: Destroying Contexts. (line 6) @@ -1819,7 +1824,7 @@ Function and Data Index * gpgme_set_engine_info: Engine Configuration. (line 11) * gpgme_set_global_flag: Library Version Check. - (line 42) + (line 43) * gpgme_set_include_certs: Included Certificates. (line 6) * gpgme_set_io_cbs: Registering I/O Callbacks. @@ -1853,19 +1858,19 @@ Function and Data Index (line 41) * gpgme_sig_notation_t: Verify. (line 38) * gpgme_sig_stat_t: Deprecated Functions. - (line 428) + (line 435) * gpgme_ssize_t: Exchanging Data. (line 30) * gpgme_status_cb_t: Status Message Callback. (line 8) * gpgme_strerror: Error Strings. (line 6) * gpgme_strerror_r: Error Strings. (line 15) * gpgme_strsource: Error Strings. (line 26) -* gpgme_subkey_t: Key objects. (line 94) +* gpgme_subkey_t: Key objects. (line 100) * gpgme_tofu_policy_t: Changing TOFU Data. (line 11) * gpgme_trust_item_get_int_attr: Deprecated Functions. - (line 413) + (line 419) * gpgme_trust_item_get_string_attr: Deprecated Functions. - (line 399) + (line 404) * gpgme_trust_item_ref: Manipulating Trust Items. (line 6) * gpgme_trust_item_release: Deprecated Functions. @@ -1874,10 +1879,10 @@ Function and Data Index (line 8) * gpgme_trust_item_unref: Manipulating Trust Items. (line 10) -* gpgme_user_id_t: Key objects. (line 180) +* gpgme_user_id_t: Key objects. (line 192) * gpgme_validity_t: Information About Keys. (line 9) -* gpgme_verify_result_t: Verify. (line 247) +* gpgme_verify_result_t: Verify. (line 257) * gpgme_wait: Waiting For Completion. (line 6) * IMPORT_FILES: UI Server Import/Export Keys. @@ -1889,7 +1894,7 @@ Function and Data Index * MESSAGE: UI Server Verify. (line 10) * MICALG: UI Server Sign. (line 43) * off_t (*gpgme_data_seek_cb_t) (void *HANDLE, off_t OFFSET, int WHENCE): Callback Based Data Buffers. - (line 44) + (line 43) * OUTPUT: UI Server Encrypt. (line 36) * OUTPUT <1>: UI Server Sign. (line 18) * OUTPUT <2>: UI Server Decrypt. (line 19) @@ -1914,14 +1919,14 @@ Function and Data Index * START_KEYMANAGER: Miscellaneous UI Server Commands. (line 31) * struct gpgme_data_cbs: Callback Based Data Buffers. - (line 60) + (line 59) * struct gpgme_io_cbs: Registering I/O Callbacks. (line 6) * VERIFY: UI Server Verify. (line 31) * VERIFY_FILES: UI Server Verify/Decrypt Files. (line 10) * void (*gpgme_data_release_cb_t) (void *HANDLE): Callback Based Data Buffers. - (line 55) + (line 54) * void (*gpgme_event_io_cb_t) (void *DATA, gpgme_event_io_t TYPE, void *TYPE_DATA): I/O Callback Interface. (line 89) * void (*gpgme_progress_cb_t)(void *HOOK, const char *WHAT, int TYPE, int CURRENT, int TOTAL): Progress Meter Callback. diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 32e0861..40423cf 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -14,7 +14,7 @@ @syncodeindex pg fn @copying -Copyright @copyright{} 2002--2008, 2010, 2012--2016 g10 Code GmbH. +Copyright @copyright{} 2002--2008, 2010, 2012--2017 g10 Code GmbH. @quotation Permission is granted to copy, distribute and/or modify this document @@ -979,6 +979,9 @@ Return the file name of the CMS engine. @item g13-name Return the name of the file container encryption engine. +@item gpg-wks-client-name +Return the name of the Web Key Service tool. + @end table @end deftypefun @@ -2888,6 +2891,29 @@ by this function. The properties are identified by the following values for @var{name}: @table @code +@item "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: + +@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); +@end example + + @item "full-status" Using a @var{value} of "1" the status callback set by gpgme_set_status_cb returns all status lines with the exception of @@ -3052,6 +3078,9 @@ be true even if the corresponding subkey flag may be false (offline/stub keys). This is only set if a listing of secret keys has been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active. +@item unsigned int origin : 5 +Reserved for the origin of this key. + @item gpgme_protocol_t protocol This is the protocol supported by this key. @@ -3085,6 +3114,9 @@ this is a copy of the fingerprint of the first subkey. For an incomplete key (for example from a verification result) a subkey may be missing but this field may be set nevertheless. +@item unsigned long last_update +Reserved for the time of the last update of this key. + @end table @end deftp @@ -3133,6 +3165,12 @@ This is true if the subkey can be used for authentication. This is true if the subkey can be used for qualified signatures according to local government regulations. +@item 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. + @item 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 operation @@ -3223,6 +3261,13 @@ this user id. @item gpgme_key_sig_t signatures This is a linked list with the signatures on this user ID. + +@item unsigned int origin : 5 +Reserved for the origin of this user ID. + +@item unsigned long last_update +Reserved for the time of the last update of this user ID. + @end table @end deftp @@ -3313,6 +3358,7 @@ This is a linked list with the notation data and policy URLs. @cindex key ring, search @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}}) + The function @code{gpgme_op_keylist_start} initiates a key listing operation inside the context @var{ctx}. It sets everything up so that subsequent invocations of @code{gpgme_op_keylist_next} return the keys @@ -3340,6 +3386,7 @@ are reported by the crypto engine support routines. @end deftypefun @deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}}) + The function @code{gpgme_op_keylist_ext_start} initiates an extended key listing operation inside the context @var{ctx}. It sets everything up so that subsequent invocations of @@ -3370,7 +3417,36 @@ The function returns the error code @code{GPG_ERR_INV_VALUE} if are reported by the crypto engine support routines. @end deftypefun +@deftypefun gpgme_error_t gpgme_op_keylist_from_data @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_data_t @var{data}}, @ + @w{int @var{reserved}}) + +The function @code{gpgme_op_keylist_from_data_start} initiates a key +listing operation inside the context @var{ctx}. In contrast to the +other key listing operation the keys are read from the supplied +@var{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 @code{gpgme_op_keylist_next} return +the keys from @var{data}. + +The value of @var{reserved} must be @code{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 +@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or +@code{gpgme_op_keylist_end} is called to finish the operation. +While the context is busy @var{data} may not be released. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}}) + The function @code{gpgme_op_keylist_next} returns the next key in the list created by a previous @code{gpgme_op_keylist_start} operation in the context @var{ctx}. The key will have one reference for the user. @@ -3388,6 +3464,7 @@ The function returns the error code @code{GPG_ERR_INV_VALUE} if @end deftypefun @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}}) + The function @code{gpgme_op_keylist_end} ends a pending key list operation in the context @var{ctx}. @@ -3402,7 +3479,7 @@ time during the operation there was not enough memory available. The following example illustrates how all keys containing a certain string (@code{g10code}) can be listed with their key ID and the name -and e-mail address of the main user ID: +and email address of the main user ID: @example gpgme_ctx_t ctx; @@ -3589,13 +3666,14 @@ primary key plus a secondary key (subkey). @var{reserved} must be set to zero. -@var{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 @code{time_t} to avoid problems on systems which use a -signed 32 bit @code{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. +@var{expires} specifies the expiration time in seconds. If you supply +0, a reasonable expiration time is chosen. Use the flag +@code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire. Note +that this parameter takes an unsigned long value and not a +@code{time_t} to avoid problems on systems which use a signed 32 bit +@code{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. @var{extrakey} is currently not used and must be set to @code{NULL}. A future version of GPGME may use this parameter to create X.509 keys. @@ -3637,6 +3715,9 @@ The engine does not allow the creation of a key with a user ID already existing in the local key database. This flag can be used to override this check. +@item GPGME_CREATE_NOEXPIRE +Request generation of keys that do not expire. + @end table After the operation completed successfully, information about the @@ -3696,13 +3777,14 @@ able to already handle such future algorithms. @var{reserved} must be set to zero. -@var{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 @code{time_t} to avoid problems on systems which use a -signed 32 bit @code{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. +@var{expires} specifies the expiration time in seconds. If you supply +0, a reasonable expiration time is chosen. Use the flag +@code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire. Note +that this parameter takes an unsigned long value and not a +@code{time_t} to avoid problems on systems which use a signed 32 bit +@code{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. @var{flags} takes the same values as described above for @code{gpgme_op_createkey}. @@ -3828,6 +3910,61 @@ be completed by calling @code{gpgme_wait} on the context. @c +@c gpgme_op_set_uid_flag +@c +@deftypefun gpgme_error_t gpgme_op_set_ui_flag @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{cons char * @var{name}}, @ + @w{cons char * @var{value}}); + +The function @code{gpgme_op_set_uid_flag} is used to set flags on a +user ID from the OpenPGP key given by @var{KEY}. Setting flags on +user IDs after key creation is a feature of the OpenPGP protocol and +thus the protocol for the context @var{ctx} must be set to OpenPGP. + +@var{key} specifies the key to operate on. This parameters is required. + +@var{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 @code{uid} field from the user ID object +(@code{gpgme_user_id_t}) is to be used. This is a required parameter. + +@var{name} names the flag which is to be changed. The only currently +supported flag is: + +@table @code +@item primary +This sets the primary key flag on the given user ID. All other +primary key flag on other user IDs are removed. @var{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. + +@end table + +The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if +the engine does not support the command, or a bunch of other error +codes. + +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_set_uid_flag_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{cons char * @var{name}}, @ + @w{cons char * @var{value}}); + +The function @code{gpgme_op_set_uid_flag_start} initiates a +@code{gpgme_op_set_uid_flag} operation; see there for details. It must +be completed by calling @code{gpgme_wait} on the context. +@xref{Waiting For Completion}. + +@end deftypefun + +@c @c gpgme_op_genkey @c @deftypefun gpgme_error_t gpgme_op_genkey @ @@ -3851,11 +3988,18 @@ and return a certificate request in @var{public}, which then needs to be signed by the certification authority and imported before it can be used. GpgSM does not make the fingerprint available. -The argument @var{parms} specifies parameters for the key in an XML -string. The details about the format of @var{parms} are specific to -the crypto engine used by @var{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 @var{parms} specifies parameters for the key in an string +that looks something like XML. The details about the format of +@var{parms} are specific to the crypto engine used by @var{ctx}. The +first line of the parameters must be @code{<GnupgKeyParams +format="internal">} and the last line must be +@code{</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 @code{<}, +@code{>}, or @code{&}. + +Here is an example for GnuPG as the crypto engine (all parameters of +OpenPGP key generation are documented in the GPG manual): @example <GnupgKeyParms format="internal"> @@ -3891,9 +4035,10 @@ retrieved with @code{gpgme_op_genkey_result}. The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if -@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL} -if no key was created by the backend. +@var{parms} is not a well-formed string (e.g. does not have the +expected tag-like headers and footers), @code{GPG_ERR_NOT_SUPPORTED} +if @var{public} or @var{secret} is not valid, and +@code{GPG_ERR_GENERAL} if no key was created by the backend. @end deftypefun @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}}) @@ -4008,11 +4153,10 @@ object (@code{gpgme_user_id_t}) is to be used. To select more than one user ID put them all into one string separated by linefeeds characters (@code{\n}) and set the flag @code{GPGME_KEYSIGN_LFSEP}. -@var{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 +@var{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 @code{GPGME_KEYSIGN_NOEXPIRE} is used. Note that this parameter takes an unsigned long value and not a @code{time_t} to avoid problems on systems which use a signed 32 bit @code{time_t}. Note further that @@ -4454,7 +4598,7 @@ could not be started. @cindex validity, TOFU 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. @@ -4467,7 +4611,7 @@ policy values that are supported by @acronym{GPGME}: @item GPGME_TOFU_POLICY_AUTO Set the policy to ``auto''. @item GPGME_TOFU_POLICY_GOOD -Set the policy to ``goog''. +Set the policy to ``good''. @item GPGME_TOFU_POLICY_BAD Set the policy to ``bad''. @item GPGME_TOFU_POLICY_ASK @@ -4759,6 +4903,53 @@ operation could be started successfully, and @code{GPG_ERR_INV_VALUE} if @var{cipher} or @var{plain} is not a valid pointer. @end deftypefun + +@deftypefun gpgme_error_t gpgme_op_decrypt_ext ( @ + @w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_decrypt_flags_t @var{flags}}, @ + @w{gpgme_data_t @var{cipher}}, @ + @w{gpgme_data_t @var{plain}}) + +The function @code{gpgme_op_decrypt_ext} is the same as +@code{gpgme_op_decrypt_ext} but has an additional argument +@var{flags}. If @var{flags} is 0 both function behave identically. + +The value in @var{flags} is a bitwise-or combination of one or +multiple of the following bit values: + +@table @code +@item GPGME_DECRYPT_VERIFY +The @code{GPGME_DECRYPT_VERIFY} symbol specifies that this function +shall exacty act as @code{gpgme_op_decrypt_verify}. + +@item GPGME_DECRYPT_UNWRAP +The @code{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 @code{GPGME_ENCRYPT_WRAP}. + +@end table + +The function returns the error codes as descriped for +@code{gpgme_op_decrypt} respective @code{gpgme_op_encrypt}. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_decrypt_ext_start ( @ + @w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_decrypt_flags_t @var{flags}}, @ + @w{gpgme_data_t @var{cipher}}, @ + @w{gpgme_data_t @var{plain}}) + +The function @code{gpgme_op_decrypt_ext_start} initiates a +@code{gpgme_op_decrypt_ext} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{cipher} or @var{plain} is not a valid pointer. +@end deftypefun + + @deftp {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 @@ -4948,7 +5139,19 @@ list, or @code{NULL} if this is the last element. 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. +signature is valid without any restrictions. This means that +you can check for GPGME_SIGSUM_VALID like this: + +@example +if ((sig.summary & GPGME_SIGSUM_VALID)) +@{ + ..do stuff if valid.. +@} +else +@{ + ..do stuff if not fully valid.. +@} +@end example The defined bits are: @table @code @@ -5480,10 +5683,22 @@ also expect a sign command. @item GPGME_ENCRYPT_SYMMETRIC The @code{GPGME_ENCRYPT_SYMMETRIC} symbol specifies that the -output should be additionally encrypted symmetically even +output should be additionally encrypted symmetrically even if recipients are provided. This feature is only supported for for the OpenPGP crypto engine. +@item GPGME_ENCRYPT_THROW_KEYIDS +The @code{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. + +@item GPGME_ENCRYPT_WRAP +The @code{GPGME_ENCRYPT_WRAP} symbol specifies that the input is an +OpenPGP message and not a plain data. This is the counterpart to +@code{GPGME_DECRYPT_UNWRAP}. + @end table If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in @@ -5562,7 +5777,7 @@ The combined encrypt and sign operation is currently only available for the OpenPGP crypto engine. @end deftypefun -@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) +@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) The function @code{gpgme_op_encrypt_sign_start} initiates a @code{gpgme_op_encrypt_sign} operation. It can be completed by calling @code{gpgme_wait} on the context. @xref{Waiting For |