From ad22bee5387b1e9a40e8c822a081db3228bb9def Mon Sep 17 00:00:00 2001 From: Daniel Kahn Gillmor Date: Thu, 26 Jan 2017 18:36:39 -0500 Subject: [PATCH] doc: Document that gpgme_op_genkey() parms parameter is not XML. * doc/gpgme.texi (GnupgKeyParms): document that input format is not true XML. -- Please see discussion at https://lists.gnupg.org/pipermail/gnupg-devel/2017-January/032507.html Signed-off-by: Daniel Kahn Gillmor --- doc/gpgme.texi | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 99627c4b..e058fba6 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -3874,11 +3874,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{} and the last line must be +@code{}. 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 @@ -3914,9 +3921,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}})