diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 3 | ||||
| -rw-r--r-- | doc/defsincdate | 2 | ||||
| -rw-r--r-- | doc/gpgme.info | 244 | ||||
| -rw-r--r-- | doc/gpgme.info-1 | 331 | ||||
| -rw-r--r-- | doc/gpgme.info-2 | 37 | ||||
| -rw-r--r-- | doc/gpgme.texi | 296 | ||||
| -rw-r--r-- | doc/gpl.texi | 8 | ||||
| -rw-r--r-- | doc/texinfo.tex | 124 | ||||
| -rw-r--r-- | doc/uiserver.texi | 40 |
9 files changed, 757 insertions, 328 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index 90fa2b8..1fd44b6 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -339,6 +339,9 @@ SWIG = @SWIG@ SWIG_LIB = @SWIG_LIB@ SYSROOT = @SYSROOT@ VERSION = @VERSION@ +VERSION_MAJOR = @VERSION_MAJOR@ +VERSION_MICRO = @VERSION_MICRO@ +VERSION_MINOR = @VERSION_MINOR@ VERSION_NUMBER = @VERSION_NUMBER@ abs_builddir = @abs_builddir@ abs_srcdir = @abs_srcdir@ diff --git a/doc/defsincdate b/doc/defsincdate index 0df13bf..33f93d6 100644 --- a/doc/defsincdate +++ b/doc/defsincdate @@ -1 +1 @@ -1440576360 +1479299220 diff --git a/doc/gpgme.info b/doc/gpgme.info index 8df2a71..801e07a 100644 --- a/doc/gpgme.info +++ b/doc/gpgme.info @@ -19,8 +19,8 @@ END-INFO-DIR-ENTRY This file documents the GPGME library. - This is Edition 1.7.1, last updated 26 August 2015, of ‘The ‘GnuPG -Made Easy’ Reference Manual’, for Version 1.7.1. + 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. Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH. @@ -37,128 +37,130 @@ Public License for more details. Indirect: -gpgme.info-1: 1670 -gpgme.info-2: 305786 +gpgme.info-1: 1686 +gpgme.info-2: 314031 Tag Table: (Indirect) -Node: Top1670 -Node: Introduction9061 -Node: Getting Started9851 -Node: Features11312 -Node: Overview12624 -Node: Preparation13733 -Node: Header14730 -Node: Building the Source15477 -Node: Largefile Support (LFS)17887 -Node: Using Automake23301 -Node: Using Libtool25747 -Node: Library Version Check26109 -Node: Signal Handling32121 -Node: Multi Threading33391 -Ref: Multi Threading-Footnote-135625 -Node: Protocols and Engines36048 -Node: Engine Version Check38693 -Node: Engine Information41110 -Node: Engine Configuration44970 -Node: OpenPGP46254 -Node: Cryptographic Message Syntax46594 -Node: Assuan46907 -Node: Algorithms47281 -Ref: Algorithms-Footnote-147760 -Node: Public Key Algorithms47888 -Node: Hash Algorithms50375 -Node: Error Handling51565 -Node: Error Values53439 -Node: Error Sources58642 -Node: Error Codes61082 -Node: Error Strings65873 -Node: Exchanging Data67680 -Node: Creating Data Buffers69546 -Node: Memory Based Data Buffers70062 -Node: File Based Data Buffers73495 -Node: Callback Based Data Buffers75697 -Node: Destroying Data Buffers79888 -Node: Manipulating Data Buffers81376 -Node: Data Buffer I/O Operations81868 -Node: Data Buffer Meta-Data84241 -Node: Data Buffer Convenience88607 -Node: Contexts90584 -Node: Creating Contexts91770 -Node: Destroying Contexts92617 -Node: Result Management92956 -Node: Context Attributes94385 -Node: Protocol Selection95353 -Node: Crypto Engine96385 -Node: ASCII Armor98228 -Node: Text Mode98852 -Node: Offline Mode99786 -Node: Pinentry Mode100858 -Node: Included Certificates102543 -Node: Key Listing Mode103965 -Node: Passphrase Callback108057 -Node: Progress Meter Callback111442 -Node: Status Message Callback113427 -Node: Locale116045 -Node: Key Management117604 -Node: Key objects118832 -Node: Listing Keys129832 -Node: Information About Keys137278 -Node: Manipulating Keys138586 -Node: Generating Keys139156 -Node: Signing Keys154630 -Node: Exporting Keys158228 -Node: Importing Keys164921 -Ref: Importing Keys-Footnote-1171826 -Node: Deleting Keys171954 -Node: Changing Passphrases173399 -Node: Changing TOFU Data174688 -Node: Advanced Key Editing176739 -Node: Trust Item Management179388 -Node: Listing Trust Items180424 -Node: Manipulating Trust Items182785 -Node: Crypto Operations183428 -Node: Decrypt184692 -Node: Verify188562 -Node: Decrypt and Verify200522 -Node: Sign203352 -Node: Selecting Signers203916 -Node: Creating a Signature205303 -Node: Signature Notation Data210073 -Node: Encrypt212301 -Node: Encrypting a Plaintext212657 -Node: Miscellaneous219620 -Node: Running other Programs219966 -Node: Using the Assuan protocol222042 -Node: Run Control224735 -Node: Waiting For Completion225479 -Node: Using External Event Loops227597 -Node: I/O Callback Interface229569 -Node: Registering I/O Callbacks234807 -Node: I/O Callback Example236845 -Node: I/O Callback Example GTK+243470 -Node: I/O Callback Example GDK245259 -Node: I/O Callback Example Qt246901 -Node: Cancellation249189 -Node: UI Server Protocol251453 -Ref: UI Server Protocol-Footnote-1252888 -Node: UI Server Encrypt253007 -Node: UI Server Sign258152 -Node: UI Server Decrypt260505 -Node: UI Server Verify261971 -Node: UI Server Set Input Files265543 -Node: UI Server Sign/Encrypt Files266613 -Node: UI Server Verify/Decrypt Files268421 -Node: UI Server Import/Export Keys270297 -Node: UI Server Checksum Files271359 -Node: Miscellaneous UI Server Commands273575 -Ref: command SENDER275506 -Node: Debugging277208 -Node: Deprecated Functions278957 -Node: Library Copying305786 -Node: Copying334002 -Node: Concept Index371748 -Node: Function and Data Index386308 +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 End Tag Table diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1 index f7503b3..bc822a4 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.7.1, last updated 26 August 2015, of ‘The ‘GnuPG -Made Easy’ Reference Manual’, for Version 1.7.1. + 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. Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH. @@ -41,8 +41,9 @@ File: gpgme.info, Node: Top, Next: Introduction, Up: (dir) Main Menu ********* -This is Edition 1.7.1, last updated 26 August 2015, of ‘The ‘GnuPG Made -Easy’ Reference Manual’, for Version 1.7.1 of 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 of the +GPGME library. * Menu: @@ -87,7 +88,7 @@ Preparation * Using Libtool:: Avoiding compiler options entirely. * Library Version Check:: Getting and verifying the library version. * Signal Handling:: How GPGME affects signal handling. -* Multi Threading:: How GPGME can be used in an MT environment. +* Multi-Threading:: How GPGME can be used in an MT environment. Protocols and Engines @@ -143,6 +144,7 @@ Context Attributes * Protocol Selection:: Selecting the protocol used by a context. * Crypto Engine:: Configuring the crypto engine. +* Setting the Sender:: How to tell the engine the sender. * ASCII Armor:: Requesting ASCII armored output. * Text Mode:: Choosing canonical text mode. * Offline Mode:: Choosing offline mode. @@ -193,7 +195,9 @@ Encrypt Miscellaneous -* Running other Programs:: Running other Programs +* Running other Programs:: Running other Programs. +* Using the Assuan protocol:: Using the Assuan protocol. +* Checking for updates:: How to check for software updates. Run Control @@ -342,7 +346,7 @@ verified. * Using Libtool:: Avoiding compiler options entirely. * Library Version Check:: Getting and verifying the library version. * Signal Handling:: How GPGME affects signal handling. -* Multi Threading:: How GPGME can be used in an MT environment. +* Multi-Threading:: How GPGME can be used in an MT environment. File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation @@ -406,11 +410,6 @@ specifying both options to ‘gpgme-config’: gcc -o foo foo.c `gpgme-config --cflags --libs` - If you want to link to one of the thread-safe versions of GPGME, you -must specify the ‘--thread’ option before any other option to select the -thread package you want to link with. Supported thread packages are -‘--thread=pth’ and ‘--thread=pthread’. - If you need to detect the installed language bindings you can use list them using: @@ -551,7 +550,9 @@ to Automake that does all the work for you. ‘AM_PATH_GPGME_PTHREAD’ checks for the version of GPGME that can be used with the native pthread implementation, and defines - ‘GPGME_PTHREAD_CFLAGS’ and ‘GPGME_PTHREAD_LIBS’. + ‘GPGME_PTHREAD_CFLAGS’ and ‘GPGME_PTHREAD_LIBS’. Since version + 1.8.0 this is no longer required to GPGME_PTHREAD as GPGME itself + is thread safe. This macro searches for ‘gpgme-config’ along the PATH. If you are cross-compiling, it is useful to set the environment variable @@ -706,7 +707,7 @@ be thread safe. The conditional on LC_MESSAGES is only necessary for portability to W32 systems. -File: gpgme.info, Node: Signal Handling, Next: Multi Threading, Prev: Library Version Check, Up: Preparation +File: gpgme.info, Node: Signal Handling, Next: Multi-Threading, Prev: Library Version Check, Up: Preparation 2.7 Signal Handling =================== @@ -731,28 +732,14 @@ install a signal action for ‘SIGPIPE’, you must make sure you do this either before ‘gpgme_check_version’ is called or afterwards. -File: gpgme.info, Node: Multi Threading, Prev: Signal Handling, Up: Preparation +File: gpgme.info, Node: Multi-Threading, Prev: Signal Handling, Up: Preparation -2.8 Multi Threading +2.8 Multi-Threading =================== -The GPGME library is not entirely thread-safe, but it can still be used -in a multi-threaded environment if some care is taken. If the following -requirements are met, there should be no race conditions to worry about: - - • GPGME supports the thread libraries pthread and GNU Pth. The - support for this has to be enabled at compile time. GPGME will - automatically detect the location in which the thread libraries are - installed and activate the support for them at build time. - - Support for other thread libraries is very easy to add. Please - contact us if you have the need. - - • If you want to use GPGME with threads, you must link to the right - version of the library. The name of the right library is - ‘libgpgme-’ followed by the name of the thread package you use. - For example, if you use GNU Pth, the right name is ‘libgpgme-pth’. - Use the Automake macros or ‘gpgme-config’ program for simplicity. +The GPGME library is mostly thread-safe, and can be used in a +multi-threaded environment but there are some requirements for +multi-threaded use: • The function ‘gpgme_check_version’ must be called before any other function in the library, because it initializes the thread support @@ -2166,10 +2153,11 @@ File: gpgme.info, Node: Result Management, Next: Context Attributes, Prev: De The detailed result of an operation is returned in operation-specific structures such as ‘gpgme_decrypt_result_t’. The corresponding retrieval functions such as ‘gpgme_op_decrypt_result’ provide static -access to the results after an operation completes. The following -interfaces make it possible to detach a result structure from its -associated context and give it a lifetime beyond that of the current -operation or context. +access to the results after an operation completes. Those structures +shall be considered read-only and an application must not allocate such +a structure on its own. The following interfaces make it possible to +detach a result structure from its associated context and give it a +lifetime beyond that of the current operation or context. -- Function: void gpgme_result_ref (void *RESULT) The function ‘gpgme_result_ref’ acquires an additional reference @@ -2198,6 +2186,7 @@ File: gpgme.info, Node: Context Attributes, Next: Key Management, Prev: Resul * Protocol Selection:: Selecting the protocol used by a context. * Crypto Engine:: Configuring the crypto engine. +* Setting the Sender:: How to tell the engine the sender. * ASCII Armor:: Requesting ASCII armored output. * Text Mode:: Choosing canonical text mode. * Offline Mode:: Choosing offline mode. @@ -2235,7 +2224,7 @@ File: gpgme.info, Node: Protocol Selection, Next: Crypto Engine, Up: Context use with the context CTX. -File: gpgme.info, Node: Crypto Engine, Next: ASCII Armor, Prev: Protocol Selection, Up: Context Attributes +File: gpgme.info, Node: Crypto Engine, Next: Setting the Sender, Prev: Protocol Selection, Up: Context Attributes 7.4.2 Crypto Engine ------------------- @@ -2279,9 +2268,42 @@ Configuration::. successful, or an eror code on failure. -File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Crypto Engine, Up: Context Attributes +File: gpgme.info, Node: Setting the Sender, Next: ASCII Armor, Prev: Crypto Engine, Up: Context Attributes + +7.4.3 How to tell the engine the sender. +---------------------------------------- + +Some engines can make use of the sender’s address, for example to figure +out the best user id in certain trust models. For verification and +signing of mails, it is thus suggested to let the engine know the sender +("From:") address. GPGME provides two functions to accomplish that. +Note that the esoteric use of multiple "From:" addresses is not +supported. + + -- Function: gpgme_error_t gpgme_set_sender (gpgme_ctx_t CTX, + int ADDRESS) + + The function ‘gpgme_set_sender’ specifies the sender address for + use in sign and verify operations. ADDRESS is expected to be the + “addr-spec” part of an address but my also be a complete mailbox + address, in which case this function extracts the “addr-spec” from + it. Using ‘NULL’ for ADDRESS clears the sender address. + + The function returns 0 on success or an error code on failure. The + most likely failure is that no valid “addr-spec” was found in + ADDRESS. + + -- Function: const char * gpgme_get_sender (gpgme_ctx_t CTX) + + The function ‘gpgme_get_sender’ returns the current sender address + from the context, or NULL if none was set. The returned value is + valid as long as the CTX is valid and ‘gpgme_set_sender’ has not + been called again. + + +File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Setting the Sender, Up: Context Attributes -7.4.3 ASCII Armor +7.4.4 ASCII Armor ----------------- -- Function: void gpgme_set_armor (gpgme_ctx_t CTX, int YES) @@ -2298,7 +2320,7 @@ File: gpgme.info, Node: ASCII Armor, Next: Text Mode, Prev: Crypto Engine, U File: gpgme.info, Node: Text Mode, Next: Offline Mode, Prev: ASCII Armor, Up: Context Attributes -7.4.4 Text Mode +7.4.5 Text Mode --------------- -- Function: void gpgme_set_textmode (gpgme_ctx_t CTX, int YES) @@ -2322,7 +2344,7 @@ File: gpgme.info, Node: Text Mode, Next: Offline Mode, Prev: ASCII Armor, Up File: gpgme.info, Node: Offline Mode, Next: Pinentry Mode, Prev: Text Mode, Up: Context Attributes -7.4.5 Offline Mode +7.4.6 Offline Mode ------------------ -- Function: void gpgme_set_offline (gpgme_ctx_t CTX, int YES) @@ -2349,7 +2371,7 @@ File: gpgme.info, Node: Offline Mode, Next: Pinentry Mode, Prev: Text Mode, File: gpgme.info, Node: Pinentry Mode, Next: Included Certificates, Prev: Offline Mode, Up: Context Attributes -7.4.6 Pinentry Mode +7.4.7 Pinentry Mode ------------------- -- Function: gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t CTX, @@ -2394,7 +2416,7 @@ File: gpgme.info, Node: Pinentry Mode, Next: Included Certificates, Prev: Off File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: Pinentry Mode, Up: Context Attributes -7.4.7 Included Certificates +7.4.8 Included Certificates --------------------------- -- Function: void gpgme_set_include_certs (gpgme_ctx_t CTX, @@ -2432,7 +2454,7 @@ File: gpgme.info, Node: Included Certificates, Next: Key Listing Mode, Prev: File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: Included Certificates, Up: Context Attributes -7.4.8 Key Listing Mode +7.4.9 Key Listing Mode ---------------------- -- Function: gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t CTX, @@ -2515,8 +2537,8 @@ File: gpgme.info, Node: Key Listing Mode, Next: Passphrase Callback, Prev: In File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, Prev: Key Listing Mode, Up: Context Attributes -7.4.9 Passphrase Callback -------------------------- +7.4.10 Passphrase Callback +-------------------------- -- Data type: gpgme_error_t (*gpgme_passphrase_cb_t)(void *HOOK, const char *UID_HINT, const char *PASSPHRASE_INFO, int PREV_WAS_BAD, @@ -2584,7 +2606,7 @@ File: gpgme.info, Node: Passphrase Callback, Next: Progress Meter Callback, P File: gpgme.info, Node: Progress Meter Callback, Next: Status Message Callback, Prev: Passphrase Callback, Up: Context Attributes -7.4.10 Progress Meter Callback +7.4.11 Progress Meter Callback ------------------------------ -- Data type: void (*gpgme_progress_cb_t)(void *HOOK, const char *WHAT, @@ -2626,7 +2648,7 @@ File: gpgme.info, Node: Progress Meter Callback, Next: Status Message Callback File: gpgme.info, Node: Status Message Callback, Next: Locale, Prev: Progress Meter Callback, Up: Context Attributes -7.4.11 Status Message Callback +7.4.12 Status Message Callback ------------------------------ -- Data type: gpgme_error_t (*gpgme_status_cb_t)(void *HOOK, const char @@ -2679,12 +2701,36 @@ File: gpgme.info, Node: Status Message Callback, Next: Locale, Prev: Progress ("~") will not be removed from the ‘description’ field of the ‘gpgme_tofu_info_t’ object. + ‘"export-session-key"’ + Using a VALUE of "1" specifies that the context should try to + export the symmetric session key when decrypting data. By + default, or when using an empty string or "0" for VALUE, + session keys are not exported. + + ‘"override-session-key"’ + The string given in VALUE is passed to the GnuPG engine to + override the session key for decryption. The format of that + session key is specific to GnuPG and can be retrieved during a + decrypt operation when the context flag "export-session-key" + is enabled. Please be aware that using this feature with + GnuPG < 2.1.16 will leak the session key on many platforms via + ps(1). + This function returns ‘0’ on success. + -- Function: const char * gpgme_get_ctx_flag (gpgme_ctx_t CTX, + const char *NAME) + + The value of flags settable by ‘gpgme_set_ctx_flag’ can be + retrieved by this function. If NAME is unknown the function + returns ‘NULL’. For boolean flags an empty string is returned for + False and the string "1" is returned for True; either atoi(3) or a + test for an empty string can be used to get the boolean value. + File: gpgme.info, Node: Locale, Prev: Status Message Callback, Up: Context Attributes -7.4.12 Locale +7.4.13 Locale ------------- A locale setting can be associated with a context. This locale is @@ -4348,8 +4394,10 @@ File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations This is a pointer to a structure used to store the result of a ‘gpgme_op_decrypt’ operation. After successfully decrypting data, you can retrieve the pointer to the result with - ‘gpgme_op_decrypt_result’. The structure contains the following - members: + ‘gpgme_op_decrypt_result’. As with all result structures, it this + structure shall be considered read-only and an application must not + allocated such a strucure on its own. The structure contains the + following members: ‘char *unsupported_algorithm’ If an unsupported algorithm was encountered, this string @@ -4366,6 +4414,19 @@ File: gpgme.info, Node: Decrypt, Next: Verify, Up: Crypto Operations This is the filename of the original plaintext message file if it is known, otherwise this is a null pointer. + ‘char *session_key’ + A textual representation (nul-terminated string) of the + session key used in symmetric encryption of the message, if + the context has been set to export session keys (see + ‘gpgme_set_ctx_flag, "export-session-key"’), and a session key + was available for the most recent decryption operation. + Otherwise, this is a null pointer. + + You must not try to access this member of the struct unless + ‘gpgme_set_ctx_flag (ctx, "export-session-key")’ returns + success or ‘gpgme_get_ctx_flag (ctx, "export-session-key")’ + returns true (non-empty string). + -- Function: gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t CTX) The function ‘gpgme_op_decrypt_result’ returns a @@ -4681,8 +4742,8 @@ File: gpgme.info, Node: Decrypt and Verify, Next: Sign, Prev: Verify, Up: Cr not be retrieved, and passes through any errors that are reported by the crypto engine support routines. - -- Function: gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t CTX, - gpgme_data_t CIPHER, gpgme_data_t PLAIN) + -- Function: gpgme_error_t gpgme_op_decrypt_verify_start + (gpgme_ctx_t CTX, gpgme_data_t CIPHER, gpgme_data_t PLAIN) The function ‘gpgme_op_decrypt_verify_start’ initiates a ‘gpgme_op_decrypt_verify’ operation. It can be completed by calling ‘gpgme_wait’ on the context. *Note Waiting For @@ -5083,6 +5144,7 @@ Here are some support functions which are sometimes useful. * Running other Programs:: Running other Programs * Using the Assuan protocol:: Using the Assuan protocol +* Checking for updates:: How to check for software updates File: gpgme.info, Node: Running other Programs, Next: Using the Assuan protocol, Up: Miscellaneous @@ -5130,7 +5192,7 @@ GPGME API. This is the asynchronous variant of ‘gpgme_op_spawn’. -File: gpgme.info, Node: Using the Assuan protocol, Prev: Running other Programs, Up: Miscellaneous +File: gpgme.info, Node: Using the Assuan protocol, Next: Checking for updates, Prev: Running other Programs, Up: Miscellaneous 7.8.2 Using the Assuan protocol ------------------------------- @@ -5194,6 +5256,134 @@ transfer data: Synchronous variant. +File: gpgme.info, Node: Checking for updates, Prev: Using the Assuan protocol, Up: Miscellaneous + +7.8.3 How to check for software updates +--------------------------------------- + +The GnuPG Project operates a server to query the current versions of +software packages related to GnuPG. GPGME can be used to access this +online database and check whether a new version of a software package is +available. + + -- Data type: gpgme_query_swdb_result_t + This is a pointer to a structure used to store the result of a + ‘gpgme_op_query_swdb’ operation. After success full call to that + function, you can retrieve the pointer to the result with + ‘gpgme_op_query_swdb_result’. The structure contains the following + member: + + ‘name’ + This is the name of the package. + + ‘iversion’ + The currently installed version or an empty string. This + value is either a copy of the argument given to + ‘gpgme_op_query_swdb’ or the version of the installed software + as figured out by GPGME or GnuPG. + + ‘created’ + This gives the date the file with the list of version numbers + has originally be created by the GnuPG project. + + ‘retrieved’ + This gives the date the file was downloaded. + + ‘warning’ + If this flag is set either an error has occurred or some of + the information in this structure are not properly set. For + example if the version number of the installed software could + not be figured out, the ‘update’ flag may not reflect a + required update status. + + ‘update’ + If this flag is set an update of the software is available. + + ‘urgent’ + If this flag is set an available update is important. + + ‘noinfo’ + If this flag is set, no valid information could be retrieved. + + ‘unknown’ + If this flag is set the given ‘name’ is not known. + + ‘tooold’ + If this flag is set the available information is not fresh + enough. + + ‘error’ + If this flag is set some other error has occured. + + ‘version’ + The version string of the latest released version. + + ‘reldate’ + The release date of the latest released version. + + -- Function: gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t CTX, + const char *NAME, const char *IVERSION, gpgme_data_t RESERVED) + + Query the software version database for software package NAME and + check against the installed version given by IVERSION. If IVERSION + is given as ‘NULL’ a check is only done if GPGME can figure out the + version by itself (for example when using "gpgme" or "gnupg"). If + ‘NULL’ is used for NAME the current gpgme version is checked. + RESERVED must be set to 0. + + -- Function: gpgme_query_swdb_result_t gpgme_op_query_swdb_result + (gpgme_ctx_t CTX) + + The function ‘gpgme_op_query_swdb_result’ returns a + ‘gpgme_query_swdb_result_t’ pointer to a structure holding the + result of a ‘gpgme_op_query_swdb’ operation. The pointer is only + valid if the last operation on the context was a sucessful call to + ‘gpgme_op_query_swdb’. If that call failed, the result might be a + ‘NULL’ pointer. The returned pointer is only valid until the next + operation is started on the context CTX. + +Here is an example on how to check whether GnuPG is current: + + #include <gpgme.h> + + int + main (void) + { + gpg_error_t err; + gpgme_ctx_t ctx; + gpgme_query_swdb_result_t result; + + gpgme_check_version (NULL); + err = gpgme_new (&ctx); + if (err) + fprintf (stderr, "error creating context: %s\n", gpg_strerror (err)); + else + { + gpgme_set_protocol (ctx, GPGME_PROTOCOL_GPGCONF); + + err = gpgme_op_query_swdb (ctx, "gnupg", NULL, 0); + if (err) + fprintf (stderr, "error querying swdb: %s\n", gpg_strerror (err)); + else + { + result = gpgme_op_query_swdb_result (ctx); + if (!result) + fprintf (stderr, "error querying swdb\n"); + if (!result->warning && !result->update) + printf ("GnuPG version %s is current\n", + result->iversion); + else if (!result->warning && result->update) + printf ("GnuPG version %s can be updated to %s\n", + result->iversion, result->version); + else + fprintf (stderr, "error finding the update status\n"); + } + gpgme_release (ctx); + } + return 0; + } + + File: gpgme.info, Node: Run Control, Prev: Miscellaneous, Up: Contexts 7.9 Run Control @@ -5900,11 +6090,11 @@ I/O occurs in the target context). this case the state of CTX is not modified). -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX) - The function ‘gpgme_cancel’ attempts to cancel a pending operation - in the context CTX. This can be called by any thread at any time - after starting an operation on the context, but will not take - effect immediately. The actual cancellation happens at the next - time GPGME processes I/O in that context. + The function ‘gpgme_cancel_async’ attempts to cancel a pending + operation in the context CTX. This can be called by any thread at + any time after starting an operation on the context, but will not + take effect immediately. The actual cancellation happens at the + next time GPGME processes I/O in that context. The function returns an error code if the cancellation failed (in this case the state of CTX is not modified). @@ -6051,7 +6241,21 @@ selected keys, the server MAY implement the command: Here is an example of a complete encryption sequence; client lines are indicated by a C:, server responses by C:: - C: S: C: S: C: S: C: S: S: C: S: C: S: C: S: + C: RESET + S: OK + C: RECIPIENT foo@example.net + S: OK + C: RECIPIENT bar@example.com + S: OK + C: PREP_ENCRYPT + S: S PROTOCOL OpenPGP + S: OK + C: INPUT FD=17 + S: OK + C: OUTPUT FD=18 + S: OK + C: ENCRYPT + S: OK File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol @@ -6131,11 +6335,14 @@ and output file descriptors: The decryption is started with the command: -- Command: DECRYPT --protocol=NAME [--no-verify] + [--export-session-key] NAME is the encryption protocol used for the message. For a description of the allowed protocols see the ‘ENCRYPT’ command. This argument is mandatory. If the option ‘--no-verify’ is given, the server should not try to verify a signature, in case the input - data is an OpenPGP combined message. + data is an OpenPGP combined message. If the option + ‘--export-session-key’ is given and the underlying engine knows how + to export the session key, it will appear on a status line File: gpgme.info, Node: UI Server Verify, Next: UI Server Set Input Files, Prev: UI Server Decrypt, Up: UI Server Protocol diff --git a/doc/gpgme.info-2 b/doc/gpgme.info-2 index 23f874c..7c32470 100644 --- a/doc/gpgme.info-2 +++ b/doc/gpgme.info-2 @@ -19,8 +19,8 @@ END-INFO-DIR-ENTRY This file documents the GPGME library. - This is Edition 1.7.1, last updated 26 August 2015, of ‘The ‘GnuPG -Made Easy’ Reference Manual’, for Version 1.7.1. + 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. Copyright © 2002–2008, 2010, 2012–2016 g10 Code GmbH. @@ -567,7 +567,7 @@ GNU General Public License Version 3, 29 June 2007 - Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/> + Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -1243,7 +1243,7 @@ state the exclusion of warranty; and each file should have at least the General Public License for more details. You should have received a copy of the GNU General Public License - along with this program. If not, see <http://www.gnu.org/licenses/>. + along with this program. If not, see <https://www.gnu.org/licenses/>. Also add information on how to contact you by electronic and paper mail. @@ -1264,14 +1264,14 @@ use an “about box”. You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow -the GNU GPL, see <http://www.gnu.org/licenses/>. +the GNU GPL, see <https://www.gnu.org/licenses/>. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, -please read <http://www.gnu.org/philosophy/why-not-lgpl.html>. +please read <https://www.gnu.org/philosophy/why-not-lgpl.html>. File: gpgme.info, Node: Concept Index, Next: Function and Data Index, Prev: Copying, Up: Top @@ -1318,6 +1318,7 @@ Concept Index * context, pinentry mode: Pinentry Mode. (line 6) * context, result of operation: Result Management. (line 6) * context, selecting protocol: Protocol Selection. (line 6) +* context, sender: Setting the Sender. (line 6) * context, text mode: Text Mode. (line 6) * crypto backend: Protocols and Engines. (line 6) * crypto engine: Protocols and Engines. (line 6) @@ -1380,6 +1381,7 @@ Concept Index * error values, printing of: Error Strings. (line 6) * event loop, external: Using External Event Loops. (line 6) +* From:: Setting the Sender. (line 6) * GDK, using GPGME with: I/O Callback Example GDK. (line 6) * GnuPG: OpenPGP. (line 6) @@ -1425,7 +1427,7 @@ Concept Index * locale, default: Locale. (line 6) * locale, of a context: Locale. (line 6) * message digest algorithms: Hash Algorithms. (line 6) -* multi-threading: Multi Threading. (line 6) +* multi-threading: Multi-Threading. (line 6) * notation data: Verify. (line 6) * notation data <1>: Signature Notation Data. (line 6) @@ -1452,6 +1454,7 @@ Concept Index * run control: Run Control. (line 6) * S/MIME: Cryptographic Message Syntax. (line 6) +* sender: Setting the Sender. (line 6) * sign: Sign. (line 6) * signal handling: Signal Handling. (line 6) * signals: Signal Handling. (line 6) @@ -1466,7 +1469,7 @@ Concept Index * status message callback: Status Message Callback. (line 6) * text mode: Text Mode. (line 6) -* thread-safeness: Multi Threading. (line 6) +* thread-safeness: Multi-Threading. (line 6) * trust item: Trust Item Management. (line 6) * trust item list: Listing Trust Items. (line 6) * trust item, manipulation: Manipulating Trust Items. @@ -1640,6 +1643,8 @@ Function and Data Index (line 25) * gpgme_genkey_result_t: Generating Keys. (line 295) * gpgme_get_armor: ASCII Armor. (line 13) +* gpgme_get_ctx_flag: Status Message Callback. + (line 73) * gpgme_get_dirinfo: Engine Version Check. (line 6) * gpgme_get_engine_info: Engine Information. (line 46) @@ -1657,6 +1662,7 @@ 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_sig_key: Deprecated Functions. (line 626) * gpgme_get_sig_status: Deprecated Functions. @@ -1711,10 +1717,10 @@ Function and Data Index * gpgme_op_createsubkey: Generating Keys. (line 109) * gpgme_op_createsubkey_start: Generating Keys. (line 151) * gpgme_op_decrypt: Decrypt. (line 6) -* gpgme_op_decrypt_result: Decrypt. (line 76) +* gpgme_op_decrypt_result: Decrypt. (line 91) * gpgme_op_decrypt_start: Decrypt. (line 20) * gpgme_op_decrypt_verify: Decrypt and Verify. (line 6) -* gpgme_op_decrypt_verify <1>: Decrypt and Verify. (line 30) +* 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. @@ -1762,6 +1768,10 @@ Function and Data Index (line 6) * gpgme_op_passwd_start: Changing Passphrases. (line 19) +* gpgme_op_query_swdb: Checking for updates. + (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_sign: Creating a Signature. @@ -1795,12 +1805,14 @@ Function and Data Index (line 59) * 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_register_io_cb_t: I/O Callback Interface. (line 23) * gpgme_release: Destroying Contexts. (line 6) -* gpgme_result_ref: Result Management. (line 14) -* gpgme_result_unref: Result Management. (line 20) +* gpgme_result_ref: Result Management. (line 15) +* gpgme_result_unref: Result Management. (line 21) * gpgme_set_armor: ASCII Armor. (line 6) * gpgme_set_ctx_flag: Status Message Callback. (line 37) @@ -1820,6 +1832,7 @@ Function and Data Index * gpgme_set_progress_cb: Progress Meter Callback. (line 16) * gpgme_set_protocol: Protocol Selection. (line 6) +* gpgme_set_sender: Setting the Sender. (line 13) * gpgme_set_status_cb: Status Message Callback. (line 17) * gpgme_set_textmode: Text Mode. (line 6) diff --git a/doc/gpgme.texi b/doc/gpgme.texi index cc59888..32e0861 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -31,11 +31,11 @@ General Public License for more details. @end copying @c Macros used by the description of the UI server protocol -@macro clnt - @sc{c:} @c +@macro clnt{string} + @sc{c:} \string\ @end macro -@macro srvr - @sc{s:} @c +@macro srvr{string} + @sc{s:} \string\ @end macro @@ -130,7 +130,7 @@ Preparation * Using Libtool:: Avoiding compiler options entirely. * Library Version Check:: Getting and verifying the library version. * Signal Handling:: How @acronym{GPGME} affects signal handling. -* Multi Threading:: How @acronym{GPGME} can be used in an MT environment. +* Multi-Threading:: How @acronym{GPGME} can be used in an MT environment. Protocols and Engines @@ -186,6 +186,7 @@ Context Attributes * Protocol Selection:: Selecting the protocol used by a context. * Crypto Engine:: Configuring the crypto engine. +* Setting the Sender:: How to tell the engine the sender. * ASCII Armor:: Requesting @acronym{ASCII} armored output. * Text Mode:: Choosing canonical text mode. * Offline Mode:: Choosing offline mode. @@ -236,7 +237,9 @@ Encrypt Miscellaneous -* Running other Programs:: Running other Programs +* Running other Programs:: Running other Programs. +* Using the Assuan protocol:: Using the Assuan protocol. +* Checking for updates:: How to check for software updates. Run Control @@ -379,7 +382,7 @@ of the library are verified. * Using Libtool:: Avoiding compiler options entirely. * Library Version Check:: Getting and verifying the library version. * Signal Handling:: How @acronym{GPGME} affects signal handling. -* Multi Threading:: How @acronym{GPGME} can be used in an MT environment. +* Multi-Threading:: How @acronym{GPGME} can be used in an MT environment. @end menu @@ -455,12 +458,6 @@ specifying both options to @command{gpgme-config}: gcc -o foo foo.c `gpgme-config --cflags --libs` @end example -If you want to link to one of the thread-safe versions of -@acronym{GPGME}, you must specify the @option{--thread} option before -any other option to select the thread package you want to link with. -Supported thread packages are @option{--thread=pth} and -@option{--thread=pthread}. - If you need to detect the installed language bindings you can use list them using: @@ -611,7 +608,9 @@ that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME} that can be used with the native pthread implementation, and defines -@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}. +@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}. Since +version 1.8.0 this is no longer required to GPGME_PTHREAD as +@acronym{GPGME} itself is thread safe. This macro searches for @command{gpgme-config} along the PATH. If you are cross-compiling, it is useful to set the environment variable @@ -806,37 +805,17 @@ application is multi-threaded, and you install a signal action for @code{gpgme_check_version} is called or afterwards. -@node Multi Threading -@section Multi Threading +@node Multi-Threading +@section Multi-Threading @cindex thread-safeness @cindex multi-threading -The @acronym{GPGME} library is not entirely thread-safe, but it can -still be used in a multi-threaded environment if some care is taken. -If the following requirements are met, there should be no race -conditions to worry about: +The @acronym{GPGME} library is mostly thread-safe, and can be used +in a multi-threaded environment but there are some requirements +for multi-threaded use: @itemize @bullet @item -@acronym{GPGME} supports the thread libraries pthread and GNU Pth. -The support for this has to be enabled at compile time. -@acronym{GPGME} will automatically detect the location in which the -thread libraries are installed and activate the support for them at -build time. - -Support for other thread libraries is very easy to add. Please -contact us if you have the need. - -@item -If you want to use @acronym{GPGME} with threads, you must link to the -right version of the library. The name of the right library is -@code{libgpgme-} followed by the name of the thread package you use. -For example, if you use GNU Pth, the right name is -@code{libgpgme-pth}. Use the Automake macros or -@command{gpgme-config} program for simplicity. - - -@item The function @code{gpgme_check_version} must be called before any other function in the library, because it initializes the thread support subsystem in @acronym{GPGME}. To achieve this in @@ -2334,10 +2313,12 @@ The function @code{gpgme_release} destroys the context with the handle The detailed result of an operation is returned in operation-specific structures such as @code{gpgme_decrypt_result_t}. The corresponding retrieval functions such as @code{gpgme_op_decrypt_result} provide -static access to the results after an operation completes. The -following interfaces make it possible to detach a result structure -from its associated context and give it a lifetime beyond that of the -current operation or context. +static access to the results after an operation completes. Those +structures shall be considered read-only and an application must not +allocate such a structure on its own. The following interfaces make +it possible to detach a result structure from its associated context +and give it a lifetime beyond that of the current operation or +context. @deftypefun void gpgme_result_ref (@w{void *@var{result}}) The function @code{gpgme_result_ref} acquires an additional reference @@ -2366,6 +2347,7 @@ started. In fact, these references are accessed through the @menu * Protocol Selection:: Selecting the protocol used by a context. * Crypto Engine:: Configuring the crypto engine. +* Setting the Sender:: How to tell the engine the sender. * ASCII Armor:: Requesting @acronym{ASCII} armored output. * Text Mode:: Choosing canonical text mode. * Offline Mode:: Choosing offline mode. @@ -2448,6 +2430,47 @@ successful, or an eror code on failure. @end deftypefun +@node Setting the Sender +@subsection How to tell the engine the sender. +@cindex context, sender +@cindex sender +@cindex From: + +Some engines can make use of the sender’s address, for example to +figure out the best user id in certain trust models. For verification +and signing of mails, it is thus suggested to let the engine know the +sender ("From:") address. @acronym{GPGME} provides two functions to +accomplish that. Note that the esoteric use of multiple "From:" +addresses is not supported. + +@deftypefun gpgme_error_t gpgme_set_sender @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{int @var{address}}) + +The function @code{gpgme_set_sender} specifies the sender address for +use in sign and verify operations. @var{address} is expected to be +the ``addr-spec'' part of an address but my also be a complete mailbox +address, in which case this function extracts the ``addr-spec'' from +it. Using @code{NULL} for @var{address} clears the sender address. + +The function returns 0 on success or an error code on failure. The +most likely failure is that no valid ``addr-spec'' was found in +@var{address}. + +@end deftypefun + +@deftypefun @w{const char *} gpgme_get_sender @ + (@w{gpgme_ctx_t @var{ctx}}) + +The function @code{gpgme_get_sender} returns the current sender +address from the context, or NULL if none was set. The returned +value is valid as long as the @var{ctx} is valid and +@code{gpgme_set_sender} has not been called again. + +@end deftypefun + + + @c FIXME: Unfortunately, using @acronym here breaks texi2dvi. @node ASCII Armor @subsection @acronym{ASCII} Armor @@ -2877,12 +2900,39 @@ format. For example the non breaking space characters ("~") will not be removed from the @code{description} field of the @code{gpgme_tofu_info_t} object. +@item "export-session-key" +Using a @var{value} of "1" specifies that the context should try to +export the symmetric session key when decrypting data. By default, or +when using an empty string or "0" for @var{value}, session keys are +not exported. + +@item "override-session-key" +The string given in @var{value} is passed to the GnuPG engine to override +the session key for decryption. The format of that session key is +specific to GnuPG and can be retrieved during a decrypt operation when +the context flag "export-session-key" is enabled. Please be aware that +using this feature with GnuPG < 2.1.16 will leak the session key on +many platforms via ps(1). + @end table This function returns @code{0} on success. @end deftypefun +@deftypefun {const char *} gpgme_get_ctx_flag @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{const char *@var{name}}) + +The value of flags settable by @code{gpgme_set_ctx_flag} can be +retrieved by this function. If @var{name} is unknown the function +returns @code{NULL}. For boolean flags an empty string is returned +for False and the string "1" is returned for True; either atoi(3) or a +test for an empty string can be used to get the boolean value. + +@end deftypefun + + @node Locale @subsection Locale @cindex locale, default @@ -4739,8 +4789,10 @@ secret key for this recipient is not available, and 0 otherwise. This is a pointer to a structure used to store the result of a @code{gpgme_op_decrypt} operation. After successfully decrypting data, you can retrieve the pointer to the result with -@code{gpgme_op_decrypt_result}. The structure contains the following -members: +@code{gpgme_op_decrypt_result}. As with all result structures, it +this structure shall be considered read-only and an application must +not allocated such a strucure on its own. The structure contains the +following members: @table @code @item char *unsupported_algorithm @@ -4756,6 +4808,19 @@ This is a linked list of recipients to which this message was encrypted. @item char *file_name This is the filename of the original plaintext message file if it is known, otherwise this is a null pointer. + +@item char *session_key +A textual representation (nul-terminated string) of the session key +used in symmetric encryption of the message, if the context has been +set to export session keys (see @code{gpgme_set_ctx_flag, +"export-session-key"}), and a session key was available for the most +recent decryption operation. Otherwise, this is a null pointer. + +You must not try to access this member of the struct unless +@code{gpgme_set_ctx_flag (ctx, "export-session-key")} returns success +or @code{gpgme_get_ctx_flag (ctx, "export-session-key")} returns true +(non-empty string). + @end table @end deftp @@ -5096,7 +5161,7 @@ secret key could not be retrieved, and passes through any errors that are reported by the crypto engine support routines. @end deftypefun -@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) +@deftypefun gpgme_error_t gpgme_op_decrypt_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}}) The function @code{gpgme_op_decrypt_verify_start} initiates a @code{gpgme_op_decrypt_verify} operation. It can be completed by calling @code{gpgme_wait} on the context. @xref{Waiting For @@ -5518,6 +5583,7 @@ Here are some support functions which are sometimes useful. @menu * Running other Programs:: Running other Programs * Using the Assuan protocol:: Using the Assuan protocol +* Checking for updates:: How to check for software updates @end menu @@ -5649,6 +5715,142 @@ Synchronous variant. @end deftypefun +@node Checking for updates +@subsection How to check for software updates + +The GnuPG Project operates a server to query the current versions of +software packages related to GnuPG. GPGME can be used to +access this online database and check whether a new version of a +software package is available. + +@deftp {Data type} {gpgme_query_swdb_result_t} +This is a pointer to a structure used to store the result of a +@code{gpgme_op_query_swdb} operation. After success full call to that +function, you can retrieve the pointer to the result with +@code{gpgme_op_query_swdb_result}. The structure contains the +following member: + +@table @code +@item name +This is the name of the package. + +@item iversion +The currently installed version or an empty string. This value is +either a copy of the argument given to @code{gpgme_op_query_swdb} or +the version of the installed software as figured out by GPGME or GnuPG. + +@item created +This gives the date the file with the list of version numbers has +originally be created by the GnuPG project. + +@item retrieved +This gives the date the file was downloaded. + +@item warning +If this flag is set either an error has occurred or some of the +information in this structure are not properly set. For example if +the version number of the installed software could not be figured out, +the @code{update} flag may not reflect a required update status. + +@item update +If this flag is set an update of the software is available. + +@item urgent +If this flag is set an available update is important. + +@item noinfo +If this flag is set, no valid information could be retrieved. + +@item unknown +If this flag is set the given @code{name} is not known. + +@item tooold +If this flag is set the available information is not fresh enough. + +@item error +If this flag is set some other error has occured. + +@item version +The version string of the latest released version. + +@item reldate +The release date of the latest released version. + +@end table +@end deftp + +@deftypefun gpgme_error_t gpgme_op_query_swdb @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{const char *@var{name}}, @ + @w{const char *@var{iversion}}, @ + @w{gpgme_data_t @var{reserved}}) + +Query the software version database for software package @var{name} +and check against the installed version given by @var{iversion}. If +@var{iversion} is given as @code{NULL} a check is only done if GPGME +can figure out the version by itself (for example when using +"gpgme" or "gnupg"). If @code{NULL} is used for @var{name} the +current gpgme version is checked. @var{reserved} must be set to 0. + +@end deftypefun + +@deftypefun gpgme_query_swdb_result_t gpgme_op_query_swdb_result @ + (@w{gpgme_ctx_t @var{ctx}}) + +The function @code{gpgme_op_query_swdb_result} returns a +@code{gpgme_query_swdb_result_t} pointer to a structure holding the +result of a @code{gpgme_op_query_swdb} operation. The pointer is only +valid if the last operation on the context was a sucessful call to +@code{gpgme_op_query_swdb}. If that call failed, the result might +be a @code{NULL} pointer. The returned pointer is only valid until +the next operation is started on the context @var{ctx}. +@end deftypefun + +@noindent +Here is an example on how to check whether GnuPG is current: + +@example +#include <gpgme.h> + +int +main (void) +@{ + gpg_error_t err; + gpgme_ctx_t ctx; + gpgme_query_swdb_result_t result; + + gpgme_check_version (NULL); + err = gpgme_new (&ctx); + if (err) + fprintf (stderr, "error creating context: %s\n", gpg_strerror (err)); + else + @{ + gpgme_set_protocol (ctx, GPGME_PROTOCOL_GPGCONF); + + err = gpgme_op_query_swdb (ctx, "gnupg", NULL, 0); + if (err) + fprintf (stderr, "error querying swdb: %s\n", gpg_strerror (err)); + else + @{ + result = gpgme_op_query_swdb_result (ctx); + if (!result) + fprintf (stderr, "error querying swdb\n"); + if (!result->warning && !result->update) + printf ("GnuPG version %s is current\n", + result->iversion); + else if (!result->warning && result->update) + printf ("GnuPG version %s can be updated to %s\n", + result->iversion, result->version); + else + fprintf (stderr, "error finding the update status\n"); + @} + gpgme_release (ctx); + @} + return 0; +@} +@end example + + @node Run Control @section Run Control @cindex run control @@ -6379,7 +6581,7 @@ case the state of @var{ctx} is not modified). @deftypefun gpgme_ctx_t gpgme_cancel_async (@w{gpgme_ctx_t @var{ctx}}) -The function @code{gpgme_cancel} attempts to cancel a pending +The function @code{gpgme_cancel_async} attempts to cancel a pending operation in the context @var{ctx}. This can be called by any thread at any time after starting an operation on the context, but will not take effect immediately. The actual cancellation happens at the next diff --git a/doc/gpl.texi b/doc/gpl.texi index d13e9e4..931a93d 100644 --- a/doc/gpl.texi +++ b/doc/gpl.texi @@ -6,7 +6,7 @@ @c This file is intended to be included in another file. @display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} +Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{https://fsf.org/} Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. @@ -696,7 +696,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. +along with this program. If not, see @url{https://www.gnu.org/licenses/}. @end example @noindent @@ -722,11 +722,11 @@ use an ``about box''. You should also get your employer (if you work as a programmer) or school, if any, to sign a ``copyright disclaimer'' for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. +@url{https://www.gnu.org/licenses/}. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. +first, please read @url{https://www.gnu.org/philosophy/why-not-lgpl.html}. diff --git a/doc/texinfo.tex b/doc/texinfo.tex index d2b264d..2c274a2 100644 --- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -20,7 +20,7 @@ % General Public License for more details. % % You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. +% along with this program. If not, see <https://www.gnu.org/licenses/>. % % As a special exception, when this file is read by TeX when processing % a Texinfo source document, you may use the result without @@ -28,7 +28,7 @@ % % Please try the latest version of texinfo.tex before submitting bug % reports; you can get the latest version from: -% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or +% https://www.gnu.org/software/texinfo/ (the Texinfo home page), or % ftp://tug.org/tex/texinfo.tex % (and all CTAN mirrors, see http://www.ctan.org). % The texinfo.tex in any given distribution could well be out @@ -54,7 +54,7 @@ % extent. You can get the existing language-specific files from the % full Texinfo distribution. % -% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. +% The GNU Texinfo home page is https://www.gnu.org/software/texinfo. \message{Loading texinfo [version \texinfoversion]:} @@ -354,7 +354,7 @@ % We don't want .vr (or whatever) entries like this: % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} % "\acronym" won't work when it's read back in; - % it needs to be + % it needs to be % {\code {{\tt \backslashcurfont }acronym} \shipout\vbox{% % Do this early so pdf references go to the beginning of the page. @@ -705,7 +705,7 @@ \def\?{?\spacefactor=\endofsentencespacefactor\space} % @frenchspacing on|off says whether to put extra space after punctuation. -% +% \def\onword{on} \def\offword{off} % @@ -1260,7 +1260,7 @@ where each line of input produces a line of output.} % that's what we do). % double active backslashes. -% +% {\catcode`\@=0 \catcode`\\=\active @gdef@activebackslashdouble{% @catcode`@\=@active @@ -1272,11 +1272,11 @@ where each line of input produces a line of output.} % us) handles it with this amazing macro to replace tokens, with minor % changes for Texinfo. It is included here under the GPL by permission % from the author, Heiko Oberdiek. -% +% % #1 is the tokens to replace. % #2 is the replacement. % #3 is the control sequence with the string. -% +% \def\HyPsdSubst#1#2#3{% \def\HyPsdReplace##1#1##2\END{% ##1% @@ -1542,7 +1542,7 @@ output) for that.)} % tried to figure out what each command should do in the context % of @url. for now, just make @/ a no-op, that's the only one % people have actually reported a problem with. - % + % \normalturnoffactive \def\@{@}% \let\/=\empty @@ -1941,7 +1941,7 @@ end % Definitions for a main text size of 11pt. This is the default in % Texinfo. -% +% \def\definetextfontsizexi{% % Text fonts (11.2pt, magstep1). \def\textnominalsize{11pt} @@ -2074,7 +2074,7 @@ end % section, chapter, etc., sizes following suit. This is for the GNU % Press printing of the Emacs 22 manual. Maybe other manuals in the % future. Used with @smallbook, which sets the leading to 12pt. -% +% \def\definetextfontsizex{% % Text fonts (10pt). \def\textnominalsize{10pt} @@ -2165,7 +2165,7 @@ end \setfont\secsf\sfbshape{12}{1000}{OT1} \let\secbf\secrm \setfont\secsc\scbshape{10}{\magstep1}{OT1} -\font\seci=cmmi12 +\font\seci=cmmi12 \font\secsy=cmsy10 scaled \magstep1 \def\sececsize{1200} @@ -2209,7 +2209,7 @@ end % We provide the user-level command % @fonttextsize 10 % (or 11) to redefine the text font size. pt is assumed. -% +% \def\xword{10} \def\xiword{11} % @@ -2219,7 +2219,7 @@ end % % Set \globaldefs so that documents can use this inside @tex, since % makeinfo 4.8 does not support it, but we need it nonetheless. - % + % \begingroup \globaldefs=1 \ifx\textsizearg\xword \definetextfontsizex \else \ifx\textsizearg\xiword \definetextfontsizexi @@ -2505,7 +2505,7 @@ end % each of the four underscores in __typeof__. This is undesirable in % some manuals, especially if they don't have long identifiers in % general. @allowcodebreaks provides a way to control this. -% +% \newif\ifallowcodebreaks \allowcodebreakstrue \def\keywordtrue{true} @@ -2636,7 +2636,7 @@ end % @acronym for "FBI", "NATO", and the like. % We print this one point size smaller, since it's intended for % all-uppercase. -% +% \def\acronym#1{\doacronym #1,,\finish} \def\doacronym#1,#2,#3\finish{% {\selectfonts\lsize #1}% @@ -2648,7 +2648,7 @@ end % @abbr for "Comput. J." and the like. % No font change, but don't do end-of-sentence spacing. -% +% \def\abbr#1{\doabbr #1,,\finish} \def\doabbr#1,#2,#3\finish{% {\plainfrenchspacing #1}% @@ -2667,43 +2667,43 @@ end % Theiling, which support regular, slanted, bold and bold slanted (and % "outlined" (blackboard board, sort of) versions, which we don't need). % It is available from http://www.ctan.org/tex-archive/fonts/eurosym. -% +% % Although only regular is the truly official Euro symbol, we ignore % that. The Euro is designed to be slightly taller than the regular % font height. -% +% % feymr - regular % feymo - slanted % feybr - bold % feybo - bold slanted -% +% % There is no good (free) typewriter version, to my knowledge. % A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. % Hmm. -% +% % Also doesn't work in math. Do we need to do math with euro symbols? % Hope not. -% -% +% +% \def\euro{{\eurofont e}} \def\eurofont{% % We set the font at each command, rather than predefining it in % \textfonts and the other font-switching commands, so that % installations which never need the symbol don't have to have the % font installed. - % + % % There is only one designed size (nominal 10pt), so we always scale % that to the current nominal size. - % + % % By the way, simply using "at 1em" works for cmr10 and the like, but % does not work for cmbx10 and other extended/shrunken fonts. - % + % \def\eurosize{\csname\curfontsize nominalsize\endcsname}% % - \ifx\curfontstyle\bfstylename + \ifx\curfontstyle\bfstylename % bold: \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize - \else + \else % regular: \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize \fi @@ -2756,7 +2756,7 @@ end % Laurent Siebenmann reports \Orb undefined with: % Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 % so we'll define it if necessary. -% +% \ifx\Orb\undefined \def\Orb{\mathhexbox20D} \fi @@ -3105,7 +3105,7 @@ end % cause the example and the item to crash together. So we use this % bizarre value of 10001 as a signal to \aboveenvbreak to insert % \parskip glue after all. Section titles are handled this way also. - % + % \penalty 10001 \endgroup \itemxneedsnegativevskipfalse @@ -3901,7 +3901,7 @@ end % processing continues to some further point. On the other hand, it % seems \endinput does not hurt in the printed index arg, since that % is still getting written without apparent harm. - % + % % Sample source (mac-idx3.tex, reported by Graham Percival to % help-texinfo, 22may06): % @macro funindex {WORD} @@ -3909,12 +3909,12 @@ end % @end macro % ... % @funindex commtest - % + % % The above is not enough to reproduce the bug, but it gives the flavor. - % + % % Sample whatsit resulting: % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} - % + % % So: \let\endinput = \empty % @@ -4170,11 +4170,11 @@ end % makeinfo does not expand macros in the argument to @deffn, which ends up % writing an index entry, and texindex isn't prepared for an index sort entry % that starts with \. - % + % % Since macro invocations are followed by braces, we can just redefine them % to take a single TeX argument. The case of a macro invocation that % goes to end-of-line is not handled. - % + % \macrolist } @@ -4302,7 +4302,7 @@ end % to re-insert the same penalty (values >10000 are used for various % signals); since we just inserted a non-discardable item, any % following glue (such as a \parskip) would be a breakpoint. For example: - % + % % @deffn deffn-whatever % @vindex index-whatever % Description. @@ -5368,11 +5368,11 @@ end % glue accumulate. (Not a breakpoint because it's preceded by a % discardable item.) \vskip-\parskip - % + % % This is purely so the last item on the list is a known \penalty > % 10000. This is so \startdefun can avoid allowing breakpoints after % section headings. Otherwise, it would insert a valid breakpoint between: - % + % % @section sec-whatever % @deffn def-whatever \penalty 10001 @@ -5430,7 +5430,7 @@ end % These characters do not print properly in the Computer Modern roman % fonts, so we must take special care. This is more or less redundant % with the Texinfo input format setup at the end of this file. -% +% \def\activecatcodes{% \catcode`\"=\active \catcode`\$=\active @@ -5480,7 +5480,7 @@ end % redefined for the two-volume lispref. We always output on % \jobname.toc even if this is redefined. -% +% \def\tocreadfilename{\jobname.toc} % Normal (long) toc. @@ -6035,8 +6035,8 @@ end % from cmtt (char 0x0d). The undirected quote is ugly, so don't make it % the default, but it works for pasting with more pdf viewers (at least % evince), the lilypond developers report. xpdf does work with the -% regular 0x27. -% +% regular 0x27. +% \def\codequoteright{% \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax @@ -6048,7 +6048,7 @@ end % and a similar option for the left quote char vs. a grave accent. % Modern fonts display ASCII 0x60 as a grave accent, so some people like % the code environments to do likewise. -% +% \def\codequoteleft{% \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax @@ -6579,7 +6579,7 @@ end % This does \let #1 = #2, with \csnames; that is, % \let \csname#1\endcsname = \csname#2\endcsname % (except of course we have to play expansion games). -% +% \def\cslet#1#2{% \expandafter\let \csname#1\expandafter\endcsname @@ -7737,7 +7737,7 @@ end % % If they passed de_DE, and txi-de_DE.tex doesn't exist, % try txi-de.tex. -% +% \def\documentlanguagetrywithoutunderscore#1_#2\finish{% \openin 1 txi-#1.tex \ifeof 1 @@ -7793,7 +7793,7 @@ should work if nowhere else does.} \setnonasciicharscatcode\active \lattwochardefs % - \else \ifx \declaredencoding \latone + \else \ifx \declaredencoding \latone \setnonasciicharscatcode\active \latonechardefs % @@ -7805,7 +7805,7 @@ should work if nowhere else does.} \setnonasciicharscatcode\active \utfeightchardefs % - \else + \else \message{Unknown document encoding #1, ignoring.}% % \fi % utfeight @@ -7817,7 +7817,7 @@ should work if nowhere else does.} % A message to be logged when using a character that isn't available % the default font encoding (OT1). -% +% \def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} % Take account of \c (plain) vs. \, (Texinfo) difference. @@ -7830,21 +7830,21 @@ should work if nowhere else does.} % % Latin1 (ISO-8859-1) character definitions. \def\latonechardefs{% - \gdef^^a0{~} + \gdef^^a0{~} \gdef^^a1{\exclamdown} - \gdef^^a2{\missingcharmsg{CENT SIGN}} + \gdef^^a2{\missingcharmsg{CENT SIGN}} \gdef^^a3{{\pounds}} \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} \gdef^^a5{\missingcharmsg{YEN SIGN}} - \gdef^^a6{\missingcharmsg{BROKEN BAR}} + \gdef^^a6{\missingcharmsg{BROKEN BAR}} \gdef^^a7{\S} - \gdef^^a8{\"{}} - \gdef^^a9{\copyright} + \gdef^^a8{\"{}} + \gdef^^a9{\copyright} \gdef^^aa{\ordf} - \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}} + \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}} \gdef^^ac{$\lnot$} - \gdef^^ad{\-} - \gdef^^ae{\registeredsymbol} + \gdef^^ad{\-} + \gdef^^ae{\registeredsymbol} \gdef^^af{\={}} % \gdef^^b0{\textdegree} @@ -7871,7 +7871,7 @@ should work if nowhere else does.} \gdef^^c2{\^A} \gdef^^c3{\~A} \gdef^^c4{\"A} - \gdef^^c5{\ringaccent A} + \gdef^^c5{\ringaccent A} \gdef^^c6{\AE} \gdef^^c7{\cedilla C} \gdef^^c8{\`E} @@ -8012,7 +8012,7 @@ should work if nowhere else does.} \gdef^^d6{\"O} \gdef^^d7{$\times$} \gdef^^d8{\v R} - \gdef^^d9{\ringaccent U} + \gdef^^d9{\ringaccent U} \gdef^^da{\'U} \gdef^^db{\H U} \gdef^^dc{\"U} @@ -8056,11 +8056,11 @@ should work if nowhere else does.} } % UTF-8 character definitions. -% +% % This code to support UTF-8 is based on LaTeX's utf8.def, with some % changes for Texinfo conventions. It is included here under the GPL by % permission from Frank Mittelbach and the LaTeX team. -% +% \newcount\countUTFx \newcount\countUTFy \newcount\countUTFz @@ -8900,7 +8900,7 @@ should work if nowhere else does.} % Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of % the literal character `\'. -% +% @def@normalturnoffactive{% @let\=@normalbackslash @let"=@normaldoublequote diff --git a/doc/uiserver.texi b/doc/uiserver.texi index 16e8f85..f10db01 100644 --- a/doc/uiserver.texi +++ b/doc/uiserver.texi @@ -158,21 +158,21 @@ indicated by a @sc{c:}, server responses by @sc{c:}: @smallexample @group - @clnt RESET - @srvr OK - @clnt RECIPIENT foo@@example.net - @srvr OK - @clnt RECIPIENT bar@@example.com - @srvr OK - @clnt PREP_ENCRYPT - @srvr S PROTOCOL OpenPGP - @srvr OK - @clnt INPUT FD=17 - @srvr OK - @clnt OUTPUT FD=18 - @srvr OK - @clnt ENCRYPT - @srvr OK + @clnt{RESET} + @srvr{OK} + @clnt{RECIPIENT foo@@example.net} + @srvr{OK} + @clnt{RECIPIENT bar@@example.com} + @srvr{OK} + @clnt{PREP_ENCRYPT} + @srvr{S PROTOCOL OpenPGP} + @srvr{OK} + @clnt{INPUT FD=17} + @srvr{OK} + @clnt{OUTPUT FD=18} + @srvr{OK} + @clnt{ENCRYPT} + @srvr{OK} @end group @end smallexample @@ -260,12 +260,14 @@ encoded. For details on the file descriptor, see the description of @noindent The decryption is started with the command: -@deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify] +@deffn Command DECRYPT -@w{}-protocol=@var{name} [-@w{}-no-verify] [-@w{}-export-session-key] @var{name} is the encryption protocol used for the message. For a description of the allowed protocols see the @code{ENCRYPT} command. -This argument is mandatory. If the option @option{--no-verify} is given, -the server should not try to verify a signature, in case the input data -is an OpenPGP combined message. +This argument is mandatory. If the option @option{--no-verify} is +given, the server should not try to verify a signature, in case the +input data is an OpenPGP combined message. If the option +@option{--export-session-key} is given and the underlying engine knows +how to export the session key, it will appear on a status line @end deffn |