diff options
Diffstat (limited to 'doc/gpgme.texi')
-rw-r--r-- | doc/gpgme.texi | 283 |
1 files changed, 249 insertions, 34 deletions
diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 32e0861..40423cf 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -14,7 +14,7 @@ @syncodeindex pg fn @copying -Copyright @copyright{} 2002--2008, 2010, 2012--2016 g10 Code GmbH. +Copyright @copyright{} 2002--2008, 2010, 2012--2017 g10 Code GmbH. @quotation Permission is granted to copy, distribute and/or modify this document @@ -979,6 +979,9 @@ Return the file name of the CMS engine. @item g13-name Return the name of the file container encryption engine. +@item gpg-wks-client-name +Return the name of the Web Key Service tool. + @end table @end deftypefun @@ -2888,6 +2891,29 @@ by this function. The properties are identified by the following values for @var{name}: @table @code +@item "redraw" +This flag is normally not changed by the caller because GPGME sets and +clears it automatically: The flag is cleared before an operation and +set if an operation noticed that the engine has launched a Pinentry. +A Curses based application may use this information to redraw the +screen; for example: + +@example + err = gpgme_op_keylist_start (ctx, "foo@@example.org", 0); + while (!err) + @{ + err = gpgme_op_keylist_next (ctx, &key); + if (err) + break; + show_key (key); + gpgme_key_release (key); + @} + if ((s = gpgme_get_ctx_flag (ctx, "redraw")) && *s) + redraw_screen (); + gpgme_release (ctx); +@end example + + @item "full-status" Using a @var{value} of "1" the status callback set by gpgme_set_status_cb returns all status lines with the exception of @@ -3052,6 +3078,9 @@ be true even if the corresponding subkey flag may be false (offline/stub keys). This is only set if a listing of secret keys has been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active. +@item unsigned int origin : 5 +Reserved for the origin of this key. + @item gpgme_protocol_t protocol This is the protocol supported by this key. @@ -3085,6 +3114,9 @@ this is a copy of the fingerprint of the first subkey. For an incomplete key (for example from a verification result) a subkey may be missing but this field may be set nevertheless. +@item unsigned long last_update +Reserved for the time of the last update of this key. + @end table @end deftp @@ -3133,6 +3165,12 @@ This is true if the subkey can be used for authentication. This is true if the subkey can be used for qualified signatures according to local government regulations. +@item unsigned int is_de_vs : 1 +This is true if the subkey complies with the rules for classified +information in Germany at the restricted level (VS-NfD). This are +currently RSA keys of at least 2048 bits or ECDH/ECDSA keys using a +Brainpool curve. + @item unsigned int secret : 1 This is true if the subkey is a secret key. Note that it will be false if the key is actually a stub key; i.e. a secret key operation @@ -3223,6 +3261,13 @@ this user id. @item gpgme_key_sig_t signatures This is a linked list with the signatures on this user ID. + +@item unsigned int origin : 5 +Reserved for the origin of this user ID. + +@item unsigned long last_update +Reserved for the time of the last update of this user ID. + @end table @end deftp @@ -3313,6 +3358,7 @@ This is a linked list with the notation data and policy URLs. @cindex key ring, search @deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}}) + The function @code{gpgme_op_keylist_start} initiates a key listing operation inside the context @var{ctx}. It sets everything up so that subsequent invocations of @code{gpgme_op_keylist_next} return the keys @@ -3340,6 +3386,7 @@ are reported by the crypto engine support routines. @end deftypefun @deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}}) + The function @code{gpgme_op_keylist_ext_start} initiates an extended key listing operation inside the context @var{ctx}. It sets everything up so that subsequent invocations of @@ -3370,7 +3417,36 @@ The function returns the error code @code{GPG_ERR_INV_VALUE} if are reported by the crypto engine support routines. @end deftypefun +@deftypefun gpgme_error_t gpgme_op_keylist_from_data @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_data_t @var{data}}, @ + @w{int @var{reserved}}) + +The function @code{gpgme_op_keylist_from_data_start} initiates a key +listing operation inside the context @var{ctx}. In contrast to the +other key listing operation the keys are read from the supplied +@var{data} and not from the local key database. The keys are also not +imported into the local key database. The function sets everything up +so that subsequent invocations of @code{gpgme_op_keylist_next} return +the keys from @var{data}. + +The value of @var{reserved} must be @code{0}. + +This function requires at least GnuPG version 2.1.14 and currently +works only with OpenPGP keys. + +The context will be busy until either all keys are received (and +@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or +@code{gpgme_op_keylist_end} is called to finish the operation. +While the context is busy @var{data} may not be released. + +The function returns the error code @code{GPG_ERR_INV_VALUE} if +@var{ctx} is not a valid pointer, and passes through any errors that +are reported by the crypto engine support routines. +@end deftypefun + @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}}) + The function @code{gpgme_op_keylist_next} returns the next key in the list created by a previous @code{gpgme_op_keylist_start} operation in the context @var{ctx}. The key will have one reference for the user. @@ -3388,6 +3464,7 @@ The function returns the error code @code{GPG_ERR_INV_VALUE} if @end deftypefun @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}}) + The function @code{gpgme_op_keylist_end} ends a pending key list operation in the context @var{ctx}. @@ -3402,7 +3479,7 @@ time during the operation there was not enough memory available. The following example illustrates how all keys containing a certain string (@code{g10code}) can be listed with their key ID and the name -and e-mail address of the main user ID: +and email address of the main user ID: @example gpgme_ctx_t ctx; @@ -3589,13 +3666,14 @@ primary key plus a secondary key (subkey). @var{reserved} must be set to zero. -@var{expires} can be set to the number of seconds since Epoch of the -desired expiration date in UTC for the new key. Using 0 does not -set an expiration date. Note that this parameter takes an unsigned long -value and not a @code{time_t} to avoid problems on systems which use a -signed 32 bit @code{time_t}. Note further that the OpenPGP protocol -uses 32 bit values for timestamps and thus can only encode dates up to -the year 2106. +@var{expires} specifies the expiration time in seconds. If you supply +0, a reasonable expiration time is chosen. Use the flag +@code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire. Note +that this parameter takes an unsigned long value and not a +@code{time_t} to avoid problems on systems which use a signed 32 bit +@code{time_t}. Note further that the OpenPGP protocol uses 32 bit +values for timestamps and thus can only encode dates up to the year +2106. @var{extrakey} is currently not used and must be set to @code{NULL}. A future version of GPGME may use this parameter to create X.509 keys. @@ -3637,6 +3715,9 @@ The engine does not allow the creation of a key with a user ID already existing in the local key database. This flag can be used to override this check. +@item GPGME_CREATE_NOEXPIRE +Request generation of keys that do not expire. + @end table After the operation completed successfully, information about the @@ -3696,13 +3777,14 @@ able to already handle such future algorithms. @var{reserved} must be set to zero. -@var{expires} can be set to the number of seconds since Epoch of the -desired expiration date in UTC for the new subkey. Using 0 does not -set an expiration date. Note that this parameter takes an unsigned long -value and not a @code{time_t} to avoid problems on systems which use a -signed 32 bit @code{time_t}. Note further that the OpenPGP protocol -uses 32 bit values for timestamps and thus can only encode dates up to -the year 2106. +@var{expires} specifies the expiration time in seconds. If you supply +0, a reasonable expiration time is chosen. Use the flag +@code{GPGME_CREATE_NOEXPIRE} to create keys that do not expire. Note +that this parameter takes an unsigned long value and not a +@code{time_t} to avoid problems on systems which use a signed 32 bit +@code{time_t}. Note further that the OpenPGP protocol uses 32 bit +values for timestamps and thus can only encode dates up to the year +2106. @var{flags} takes the same values as described above for @code{gpgme_op_createkey}. @@ -3828,6 +3910,61 @@ be completed by calling @code{gpgme_wait} on the context. @c +@c gpgme_op_set_uid_flag +@c +@deftypefun gpgme_error_t gpgme_op_set_ui_flag @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{cons char * @var{name}}, @ + @w{cons char * @var{value}}); + +The function @code{gpgme_op_set_uid_flag} is used to set flags on a +user ID from the OpenPGP key given by @var{KEY}. Setting flags on +user IDs after key creation is a feature of the OpenPGP protocol and +thus the protocol for the context @var{ctx} must be set to OpenPGP. + +@var{key} specifies the key to operate on. This parameters is required. + +@var{userid} is the user ID of the key to be manipulated. This user ID +must be given verbatim because the engine does an exact and case +sensitive match. Thus the @code{uid} field from the user ID object +(@code{gpgme_user_id_t}) is to be used. This is a required parameter. + +@var{name} names the flag which is to be changed. The only currently +supported flag is: + +@table @code +@item primary +This sets the primary key flag on the given user ID. All other +primary key flag on other user IDs are removed. @var{value} must be +given as NULL. For technical reasons this functions bumps the +creation timestamp of all affected self-signatures up by one second. +At least GnuPG version 2.1.20 is required. + +@end table + +The function returns zero on success, @code{GPG_ERR_NOT_SUPPORTED} if +the engine does not support the command, or a bunch of other error +codes. + +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_set_uid_flag_start @ + (@w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_key_t @var{key}}, @ + @w{const char *@var{userid}}, @ + @w{cons char * @var{name}}, @ + @w{cons char * @var{value}}); + +The function @code{gpgme_op_set_uid_flag_start} initiates a +@code{gpgme_op_set_uid_flag} operation; see there for details. It must +be completed by calling @code{gpgme_wait} on the context. +@xref{Waiting For Completion}. + +@end deftypefun + +@c @c gpgme_op_genkey @c @deftypefun gpgme_error_t gpgme_op_genkey @ @@ -3851,11 +3988,18 @@ and return a certificate request in @var{public}, which then needs to be signed by the certification authority and imported before it can be used. GpgSM does not make the fingerprint available. -The argument @var{parms} specifies parameters for the key in an XML -string. The details about the format of @var{parms} are specific to -the crypto engine used by @var{ctx}. Here is an example for GnuPG as -the crypto engine (all parameters of OpenPGP key generation are -documented in the GPG manual): +The argument @var{parms} specifies parameters for the key in an string +that looks something like XML. The details about the format of +@var{parms} are specific to the crypto engine used by @var{ctx}. The +first line of the parameters must be @code{<GnupgKeyParams +format="internal">} and the last line must be +@code{</GnupgKeyParams>}. Every line in between the first and last +lines is treated as a Header: Value pair. In particular, no XML +escaping is necessary if you need to include the characters @code{<}, +@code{>}, or @code{&}. + +Here is an example for GnuPG as the crypto engine (all parameters of +OpenPGP key generation are documented in the GPG manual): @example <GnupgKeyParms format="internal"> @@ -3891,9 +4035,10 @@ retrieved with @code{gpgme_op_genkey_result}. The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be started successfully, @code{GPG_ERR_INV_VALUE} if -@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if -@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL} -if no key was created by the backend. +@var{parms} is not a well-formed string (e.g. does not have the +expected tag-like headers and footers), @code{GPG_ERR_NOT_SUPPORTED} +if @var{public} or @var{secret} is not valid, and +@code{GPG_ERR_GENERAL} if no key was created by the backend. @end deftypefun @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}}) @@ -4008,11 +4153,10 @@ object (@code{gpgme_user_id_t}) is to be used. To select more than one user ID put them all into one string separated by linefeeds characters (@code{\n}) and set the flag @code{GPGME_KEYSIGN_LFSEP}. -@var{expires} can be set to the number of seconds since Epoch of the -desired expiration date in UTC for the new signature. The common case -is to use 0 to not set an expiration date. However, if the -configuration of the engine defines a default expiration for key -signatures, that is still used unless the flag +@var{expires} specifies the expiration time of the new signature in +seconds. The common case is to use 0 to not set an expiration date. +However, if the configuration of the engine defines a default +expiration for key signatures, that is still used unless the flag @code{GPGME_KEYSIGN_NOEXPIRE} is used. Note that this parameter takes an unsigned long value and not a @code{time_t} to avoid problems on systems which use a signed 32 bit @code{time_t}. Note further that @@ -4454,7 +4598,7 @@ could not be started. @cindex validity, TOFU The OpenPGP engine features a Trust-On-First-Use (TOFU) key validation -model. For resolving clonflics it is necessary to declare the policy +model. For resolving conflicts it is necessary to declare the policy for a key. See the GnuPG manual for details on the TOFU implementation. @@ -4467,7 +4611,7 @@ policy values that are supported by @acronym{GPGME}: @item GPGME_TOFU_POLICY_AUTO Set the policy to ``auto''. @item GPGME_TOFU_POLICY_GOOD -Set the policy to ``goog''. +Set the policy to ``good''. @item GPGME_TOFU_POLICY_BAD Set the policy to ``bad''. @item GPGME_TOFU_POLICY_ASK @@ -4759,6 +4903,53 @@ operation could be started successfully, and @code{GPG_ERR_INV_VALUE} if @var{cipher} or @var{plain} is not a valid pointer. @end deftypefun + +@deftypefun gpgme_error_t gpgme_op_decrypt_ext ( @ + @w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_decrypt_flags_t @var{flags}}, @ + @w{gpgme_data_t @var{cipher}}, @ + @w{gpgme_data_t @var{plain}}) + +The function @code{gpgme_op_decrypt_ext} is the same as +@code{gpgme_op_decrypt_ext} but has an additional argument +@var{flags}. If @var{flags} is 0 both function behave identically. + +The value in @var{flags} is a bitwise-or combination of one or +multiple of the following bit values: + +@table @code +@item GPGME_DECRYPT_VERIFY +The @code{GPGME_DECRYPT_VERIFY} symbol specifies that this function +shall exacty act as @code{gpgme_op_decrypt_verify}. + +@item GPGME_DECRYPT_UNWRAP +The @code{GPGME_DECRYPT_UNWRAP} symbol specifies that the output shall +be an OpenPGP message with only the encryption layer removed. This +requires GnuPG 2.1.12 and works only for OpenPGP. This is the +counterpart to @code{GPGME_ENCRYPT_WRAP}. + +@end table + +The function returns the error codes as descriped for +@code{gpgme_op_decrypt} respective @code{gpgme_op_encrypt}. +@end deftypefun + +@deftypefun gpgme_error_t gpgme_op_decrypt_ext_start ( @ + @w{gpgme_ctx_t @var{ctx}}, @ + @w{gpgme_decrypt_flags_t @var{flags}}, @ + @w{gpgme_data_t @var{cipher}}, @ + @w{gpgme_data_t @var{plain}}) + +The function @code{gpgme_op_decrypt_ext_start} initiates a +@code{gpgme_op_decrypt_ext} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns the error code @code{GPG_ERR_NO_ERROR} if the +operation could be started successfully, and @code{GPG_ERR_INV_VALUE} +if @var{cipher} or @var{plain} is not a valid pointer. +@end deftypefun + + @deftp {Data type} {gpgme_recipient_t} This is a pointer to a structure used to store information about the recipient of an encrypted text which is decrypted in a @@ -4948,7 +5139,19 @@ list, or @code{NULL} if this is the last element. This is a bit vector giving a summary of the signature status. It provides an easy interface to a defined semantic of the signature status. Checking just one bit is sufficient to see whether a -signature is valid without any restrictions. +signature is valid without any restrictions. This means that +you can check for GPGME_SIGSUM_VALID like this: + +@example +if ((sig.summary & GPGME_SIGSUM_VALID)) +@{ + ..do stuff if valid.. +@} +else +@{ + ..do stuff if not fully valid.. +@} +@end example The defined bits are: @table @code @@ -5480,10 +5683,22 @@ also expect a sign command. @item GPGME_ENCRYPT_SYMMETRIC The @code{GPGME_ENCRYPT_SYMMETRIC} symbol specifies that the -output should be additionally encrypted symmetically even +output should be additionally encrypted symmetrically even if recipients are provided. This feature is only supported for for the OpenPGP crypto engine. +@item GPGME_ENCRYPT_THROW_KEYIDS +The @code{GPGME_ENCRYPT_THROW_KEYIDS} symbols requests that the +identifiers for the decrption keys are not included in the ciphertext. +On the receiving side, the use of this flag may slow down the +decryption process because all available secret keys must be tried. +This flag is only honored for OpenPGP encryption. + +@item GPGME_ENCRYPT_WRAP +The @code{GPGME_ENCRYPT_WRAP} symbol specifies that the input is an +OpenPGP message and not a plain data. This is the counterpart to +@code{GPGME_DECRYPT_UNWRAP}. + @end table If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in @@ -5562,7 +5777,7 @@ The combined encrypt and sign operation is currently only available for the OpenPGP crypto engine. @end deftypefun -@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) +@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}}) The function @code{gpgme_op_encrypt_sign_start} initiates a @code{gpgme_op_encrypt_sign} operation. It can be completed by calling @code{gpgme_wait} on the context. @xref{Waiting For |