summaryrefslogtreecommitdiff
path: root/doc/gpgme.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gpgme.texi')
-rw-r--r--doc/gpgme.texi283
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