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.
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:
* 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
* 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.
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
* 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.
\1f
File: gpgme.info, Node: Header, Next: Building the Source, Up: Preparation
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:
‘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
portability to W32 systems.
\1f
-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
===================
either before ‘gpgme_check_version’ is called or afterwards.
\1f
-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
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
* 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.
use with the context CTX.
\1f
-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
-------------------
successful, or an eror code on failure.
\1f
-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.
+
+\1f
+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)
\1f
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)
\1f
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)
\1f
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,
\1f
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,
\1f
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,
\1f
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,
\1f
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,
\1f
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
("~") 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.
+
\1f
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
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
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
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
* Running other Programs:: Running other Programs
* Using the Assuan protocol:: Using the Assuan protocol
+* Checking for updates:: How to check for software updates
\1f
File: gpgme.info, Node: Running other Programs, Next: Using the Assuan protocol, Up: Miscellaneous
This is the asynchronous variant of ‘gpgme_op_spawn’.
\1f
-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
-------------------------------
Synchronous variant.
\1f
+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;
+ }
+
+\1f
File: gpgme.info, Node: Run Control, Prev: Miscellaneous, Up: Contexts
7.9 Run Control
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).
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
\1f
File: gpgme.info, Node: UI Server Sign, Next: UI Server Decrypt, Prev: UI Server Encrypt, Up: UI Server Protocol
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
\1f
File: gpgme.info, Node: UI Server Verify, Next: UI Server Set Input Files, Prev: UI Server Decrypt, Up: UI Server Protocol
projects / platform / upstream / gpgme.git / blobdiff