X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fgpgme.info-1;h=bc822a403882feda9501197772a639eb00465318;hb=3a4efa5aa27f73c93a1b020b8b30f07f0b4e46c7;hp=f7503b3120524ca19de32a6a44bfdef33695148a;hpb=10e16af58579b2e22154d944d8cb4144924a8406;p=platform%2Fupstream%2Fgpgme.git 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 + + 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