python: Initialize GPGME for the user.
[gpgme.git] / doc / gpgme.texi
index 027e1ef..8d666c3 100644 (file)
@@ -189,10 +189,12 @@ Context Attributes
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Offline Mode::                  Choosing offline mode.
 * Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 
 Key Management
@@ -391,8 +393,8 @@ to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
 
 Because @acronym{GPGME} makes use of the GPG Error library, using
 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
-directly, and the @code{gpg_err*} and @code{gpg_str*} name space
-indirectly.
+directly, and the @code{gpg_err*}, @code{gpg_str*}, and @code{gpgrt_*}
+name space indirectly.
 
 
 @node Building the Source
@@ -575,7 +577,10 @@ given.
 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
 needed for compilation of the program to find the @file{gpgme.h}
 header file, and @code{GPGME_LIBS} to the linker flags needed to link
-the program to the @acronym{GPGME} library.
+the program to the @acronym{GPGME} library.  If the used helper script
+does not match the target type you are building for a warning is
+printed and the string @code{libgcrypt} is appended to the variable
+@code{gpg_config_script_warn}.
 
 @code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
 that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
@@ -584,6 +589,16 @@ 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}.
+
+This macro searches for @command{gpgme-config} along the PATH.  If
+you are cross-compiling, it is useful to set the environment variable
+@code{SYSROOT} to the top directory of your target.  The macro will
+then first look for the helper program in the @file{bin} directory
+below that top directory.  An absolute directory name must be used for
+@code{SYSROOT}.  Finally, if the configure command line option
+@code{--with-gpgme-prefix} is used, only its value is used for the top
+directory below which the helper script is expected.
+
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -686,6 +701,16 @@ directory part is used as the default installation directory; the
 @code{.exe} suffix is added by GPGME.  Use forward slashed even under
 Windows.
 
+@item "w32-inst-dir"
+On Windows GPGME needs to know its installation directory to find its
+spawn helper.  This is in general no problem because a DLL has this
+information.  Some applications however link statically to GPGME and
+thus GPGME can only figure out the installation directory of this
+application which may be wrong in certain cases.  By supplying an
+installation directory as value to this flag, GPGME will assume that
+that directory is the installation directory.  This flag has no effect
+on non-Windows platforms.
+
 @end table
 
 This function returns @code{0} on success.  In contrast to other
@@ -1135,16 +1160,19 @@ This value indicates ElGamal.
 @item GPGME_PK_ELG_E
 This value also indicates ElGamal and is used specifically in GnuPG.
 
-@item GPGME_PK_ELG_E
-This value also indicates ElGamal and is used specifically in GnuPG.
+@item GPGME_PK_ECC
+This value is a generic indicator for ellipic curve algorithms.
 
 @item GPGME_PK_ECDSA
 This value indicates ECDSA, the Elliptic Curve Digital Signature
-Algorithm as defined by FIPS 186-2.
+Algorithm as defined by FIPS 186-2 and RFC-6637.
 
 @item GPGME_PK_ECDH
-This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption
-algorithm as defined by the ECC in OpenPGP draft.
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann
+encryption algorithm as defined by RFC-6637.
+
+@item GPGME_PK_EDDSA
+This value indicates the EdDSA algorithm.
 
 @end table
 @end deftp
@@ -1159,6 +1187,14 @@ If @var{algo} is not a valid public key algorithm, @code{NULL} is
 returned.
 @end deftypefun
 
+@deftypefun {char *} gpgme_pubkey_algo_string (@w{gpgme_subkey_t @var{key}})
+The function @code{gpgme_pubkey_algo_string} is a convenience function
+to build and return an algorithm string in the same way GnuPG does
+(e.g. ``rsa2048'' or ``ed25519'').  The caller must free the result
+using @code{gpgme_free}.  On error (e.g. invalid argument or memory
+exhausted), the function returns NULL and sets @code{ERRNO}.
+@end deftypefun
+
 
 @node Hash Algorithms
 @section Hash Algorithms
@@ -1185,6 +1221,7 @@ that are supported by @acronym{GPGME}.  Possible values are:
 @item GPGME_MD_SHA256
 @item GPGME_MD_SHA384
 @item GPGME_MD_SHA512
+@item GPGME_MD_SHA224
 @item GPGME_MD_MD4
 @item GPGME_MD_CRC32
 @item GPGME_MD_CRC32_RFC1510
@@ -1938,9 +1975,11 @@ case, the data object @var{dh} is destroyed.
 
 @deftypefun void gpgme_free (@w{void *@var{buffer}})
 The function @code{gpgme_free} releases the memory returned by
-@code{gpgme_data_release_and_get_mem}.  It should be used instead of
-the system libraries @code{free} function in case different allocators
-are used in a single program.
+@code{gpgme_data_release_and_get_mem} and
+@code{gpgme_pubkey_algo_string}.  It should be used instead of the
+system libraries @code{free} function in case different allocators are
+used by a program.  This is often the case if gpgme is used under
+Windows as a DLL.
 @end deftypefun
 
 
@@ -2271,10 +2310,12 @@ started.  In fact, these references are accessed through the
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Offline Mode::                  Choosing offline mode.
 * Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 @end menu
 
@@ -2399,6 +2440,37 @@ valid pointer.
 @end deftypefun
 
 
+@node Offline Mode
+@subsection Offline Mode
+@cindex context, offline mode
+@cindex offline mode
+
+@deftypefun void gpgme_set_offline (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
+The function @code{gpgme_set_offline} specifies if offline mode
+should be used.  By default, offline mode is not used.
+
+The offline mode specifies if dirmngr should be used to do additional
+validation that might require connections to external services.
+(e.g. CRL / OCSP checks).
+
+Offline mode only affects the keylist mode @code{GPGME_KEYLIST_MODE_VALIDATE}
+and is only relevant to the CMS crypto engine. Offline mode
+is ignored otherwise.
+
+This option may be extended in the future to completely disable
+the use of dirmngr for any engine.
+
+Offline mode is disabled if @var{yes} is zero, and enabled
+otherwise.
+@end deftypefun
+
+@deftypefun int gpgme_get_offline (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_get_offline} returns 1 if offline
+mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
+valid pointer.
+@end deftypefun
+
+
 @node Included Certificates
 @subsection Included Certificates
 @cindex certificates, included
@@ -2471,6 +2543,13 @@ signature notations on key signatures should be included in the listed
 keys.  This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
 enabled.
 
+@item GPGME_KEYLIST_MODE_WITH_SECRET
+The @code{GPGME_KEYLIST_MODE_WITH_SECRET} returns information about
+the presence of a corresponding secret key in a public key listing.  A
+public key listing with this mode is slower than a standard listing
+but can be used instead of a second run to list the secret keys.  This
+is only supported for GnuPG versions >= 2.1.
+
 @item GPGME_KEYLIST_MODE_EPHEMERAL
 The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys
 flagged as ephemeral are included in the listing.
@@ -2621,6 +2700,70 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Status Message Callback
+@subsection Status Message Callback
+@cindex callback, status message
+@cindex status message callback
+
+@deftp {Data type} {gpgme_error_t (*gpgme_status_cb_t)(void *@var{hook}, const char *@var{keyword}, const char *@var{args})}
+@tindex gpgme_status_cb_t
+The @code{gpgme_status_cb_t} type is the type of function usable as
+a status message callback function.
+
+The argument @var{keyword} is the name of the status message while the
+@var{args} argument contains any arguments for the status message.
+
+If an error occurs, return the corresponding @code{gpgme_error_t}
+value. Otherwise, return @code{0}.
+@end deftp
+
+@deftypefun void gpgme_set_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t @var{statusfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_status_cb} sets the function that is used when a
+status message is received from gpg to @var{statusfunc}. The function
+@var{statusfunc} needs to be implemented by the user, and whenever it is
+called, it is called with its first argument being @var{hook_value}.  By
+default, no status message callback function is set.
+
+The user can disable the use of a status message callback function by calling
+@code{gpgme_set_status_cb} with @var{statusfunc} being @code{NULL}.
+@end deftypefun
+
+@deftypefun void gpgme_get_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t *@var{statusfunc}}, @w{void **@var{hook_value}})
+The function @code{gpgme_get_status_cb} returns the function that is used to
+process status messages from gpg in @var{*statusfunc}, and the first argument
+for this function in @var{*hook_value}.  If no status message callback is set,
+or @var{ctx} is not a valid pointer, @code{NULL} is returned in both
+variables.
+@end deftypefun
+
+@deftypefun {gpgme_error_t} gpgme_set_ctx_flag  @
+            (@w{gpgme_ctx_t @var{ctx}}, @
+            @w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+Some minor properties of the context can be controlled with flags set
+by this function.  The properties are identified by the following
+values for @var{name}:
+
+@table @code
+@item "full-status"
+Using a @var{value} of "1" the status callback set by
+gpgme_set_status_cb returns all status lines with the exception of
+PROGRESS lines.  With the default of "0" the status callback is only
+called in certain situations.
+
+@item "raw-description"
+Setting the @var{value} to "1" returns human readable strings in a raw
+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.
+
+@end table
+
+This function returns @code{0} on success.
+@end deftypefun
+
+
 @node Locale
 @subsection Locale
 @cindex locale, default
@@ -2711,9 +2854,11 @@ This is true if the subkey can be used for qualified signatures
 according to local government regulations.
 
 @item unsigned int secret : 1
-This is true if the subkey is a secret key.  Note that it will be false
-if the key is actually a stub key; i.e. a secret key operation is
-currently not possible (offline-key).
+This is true if the subkey is a secret key.  Note that it will be
+false if the key is actually a stub key; i.e. a secret key operation
+is currently not possible (offline-key).  This is only set if a
+listing of secret keys has been requested or if
+@code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_pubkey_algo_t pubkey_algo
 This is the public key algorithm supported by this subkey.
@@ -2741,6 +2886,10 @@ True if the secret key is stored on a smart card.
 
 @item char *card_number
 The serial number of a smart card holding this key or @code{NULL}.
+
+@item char *curve
+For ECC algorithms the name of the curve.
+
 @end table
 @end deftp
 
@@ -2900,9 +3049,10 @@ This is true if the key can be used for qualified signatures according
 to local government regulations.
 
 @item unsigned int secret : 1
-This is true if the key is a secret key.  Note, that this will always be
-true even if the corresponding subkey flag may be false (offline/stub
-keys).
+This is true if the key is a secret key.  Note, that this will always
+be true even if the corresponding subkey flag may be false
+(offline/stub keys).  This is only set if a listing of secret keys has
+been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_protocol_t protocol
 This is the protocol supported by this key.
@@ -3600,6 +3750,21 @@ keys it removes all signatures except for the latest self-signatures.
 For X.509 keys it has no effect.
 
 
+@item GPGME_EXPORT_MODE_SECRET
+Instead of exporting the public key, the secret key is exported.  This
+may not be combined with @code{GPGME_EXPORT_MODE_EXTERN}.  For X.509
+the export format is PKCS#8.
+
+@item GPGME_EXPORT_MODE_RAW
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#1.  This flag may not be
+used with OpenPGP.
+
+@item GPGME_EXPORT_MODE_PKCS12
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#12 which also includes
+the certificate.  This flag may not be used with OpenPGP.
+
 @end table
 
 
@@ -3672,7 +3837,7 @@ for the context @var{ctx}, or, if that is not set, by the encoding
 specified for @var{keydata}.
 
 The keys to export are taken form the @code{NULL} terminated array
-@var{keys}.  Only keys of the the currently selected protocol of
+@var{keys}.  Only keys of the currently selected protocol of
 @var{ctx} which do have a fingerprint set are considered for export.
 Other keys specified by the @var{keys} are ignored.  In particular
 OpenPGP keys retrieved via an external key listing are not included.
@@ -3745,7 +3910,7 @@ permanent which have been retrieved from an external source (i.e. using
 for the usual workaround of exporting and then importing a key to make
 an X.509 key permanent.}
 
-Only keys of the the currently selected protocol of @var{ctx} are
+Only keys of the currently selected protocol of @var{ctx} are
 considered for import.  Other keys specified by the @var{keys} are
 ignored.  As of now all considered keys must have been retrieved using
 the same method, that is the used key listing mode must be identical.
@@ -3832,34 +3997,34 @@ The number of keys without user ID.
 @item int imported
 The total number of imported keys.
 
-@item imported_rsa
+@item int imported_rsa
 The number of imported RSA keys.
 
-@item unchanged
+@item int unchanged
 The number of unchanged keys.
 
-@item new_user_ids
+@item int new_user_ids
 The number of new user IDs.
 
-@item new_sub_keys
+@item int new_sub_keys
 The number of new sub keys.
 
-@item new_signatures
+@item int new_signatures
 The number of new signatures.
 
-@item new_revocations
+@item int new_revocations
 The number of new revocations.
 
-@item secret_read
+@item int secret_read
 The total number of secret keys read.
 
-@item secret_imported
+@item int secret_imported
 The number of imported secret keys.
 
-@item secret_unchanged
+@item int secret_unchanged
 The number of unchanged secret keys.
 
-@item not_imported
+@item int not_imported
 The number of keys not imported.
 
 @item gpgme_import_status_t imports
@@ -5141,6 +5306,21 @@ The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
 default or hidden default recipients as configured in the crypto
 backend should be included.  This can be useful for managing different
 user profiles.
+
+@item GPGME_ENCRYPT_NO_COMPRESS
+The @code{GPGME_ENCRYPT_NO_COMPRESS} symbol specifies that the
+plaintext shall not be compressed before it is encrypted.  This is
+in some cases useful if the length of the encrypted message
+may reveal information about the plaintext.
+
+@item GPGME_ENCRYPT_PREPARE
+@itemx GPGME_ENCRYPT_EXPECT_SIGN
+The @code{GPGME_ENCRYPT_PREPARE} symbol is used with the UI Server
+protocol to prepare an encryption (i.e. sending the
+@code{PREP_ENCRYPT} command).  With the
+@code{GPGME_ENCRYPT_EXPECT_SIGN} symbol the UI Server is advised to
+also expect a sign command.
+
 @end table
 
 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
@@ -5261,12 +5441,13 @@ with the GPGME API.
 
 The function @code{gpgme_op_spawn} runs the program @var{file} with
 the arguments taken from the NULL terminated array @var{argv}.  If no
-arguments are required @var{argv} may be given as @code{NULL} (in that
-case GPGME uses the basename of @var{file} for @code{argv[0]}).  The
-file descriptors @code{stdin}, @code{stdout}, and @code{stderr} are
-connected to the data objects @var{datain}, @var{dataout}, and
-@var{dataerr}.  If NULL is passed for one of these data objects the
-corresponding file descriptor is connected to @file{/dev/null}.
+arguments are required @var{argv} may be given as @code{NULL}.  In the
+latter case or if @code{argv[0]} is the empty string, GPGME uses the
+basename of @var{file} for @code{argv[0]}.  The file descriptors
+@code{stdin}, @code{stdout}, and @code{stderr} are connected to the
+data objects @var{datain}, @var{dataout}, and @var{dataerr}.  If NULL
+is passed for one of these data objects the corresponding file
+descriptor is connected to @file{/dev/null}.
 
 The value in @var{flags} is a bitwise-or combination of one or
 multiple of the following bit values:
@@ -5993,16 +6174,16 @@ operation in the context @var{ctx}.  This only works if you use the
 global event loop or your own event loop.
 
 If you use the global event loop, you must not call @code{gpgme_wait}
-or @code{gpgme_wait} during cancellation.  After successful
+during cancellation.  After successful
 cancellation, you can call @code{gpgme_wait} (optionally waiting on
 @var{ctx}), and the context @var{ctx} will appear as if it had
 finished with the error code @code{GPG_ERR_CANCEL}.
 
-If you use your an external event loop, you must ensure that no I/O
+If you use an external event loop, you must ensure that no I/O
 callbacks are invoked for this context (for example by halting the
 event loop).  On successful cancellation, all registered I/O callbacks
 for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
-event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+event with the error code @code{GPG_ERR_CANCEL} will be signalled.
 
 The function returns an error code if the cancellation failed (in this
 case the state of @var{ctx} is not modified).
@@ -6045,7 +6226,8 @@ may use @acronym{GPGME}'s built in trace feature.  This feature is
 either enabled using the environment variable @code{GPGME_DEBUG} or,
 if this is not possible, by calling the function
 @code{gpgme_set_global_flag}.  The value is the trace level and
-an optional file name.
+an optional file name.  If no file name is given the trace output is
+printed to @code{stderr}.
 
 @noindent
 For example
@@ -6071,15 +6253,15 @@ you run your tests only with play data.
 
 @include gpl.texi
 
-@node Function and Data Index
-@unnumbered Function and Data Index
-
-@printindex fn
-
 @node Concept Index
 @unnumbered Concept Index
 
 @printindex cp
 
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
 
 @bye