[GPGME PATCH] doc: Document that gpgme_op_genkey() parms parameter is not XML.
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Fri Jan 27 00:39:12 CET 2017
* 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 <dkg at fifthhorseman.net>
---
doc/gpgme.texi | 24 ++++++++++++++++--------
1 file changed, 16 insertions(+), 8 deletions(-)
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index 511384f9..47ab71e9 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -3851,11 +3851,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
+ at 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
+ at 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{<},
+ at 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 +3898,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
- at var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
- at var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
-if no key was created by the backend.
+ at 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
+ at 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}})
--
2.11.0
More information about the Gnupg-devel
mailing list