From a6c92323b6195b1b5162900d6d78e85868c58c71 Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Fri, 25 Apr 2003 12:48:48 +0000 Subject: [PATCH] 2003-04-25 Marcus Brinkmann * gpgme.texi (Generating Keys): Fix documentation of ppublic and secret arguments. --- doc/ChangeLog | 5 +++++ doc/gpgme.texi | 46 ++++++++++++++++++++++------------------------ 2 files changed, 27 insertions(+), 24 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index a387471..9886a0b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2003-04-25 Marcus Brinkmann + + * gpgme.texi (Generating Keys): Fix documentation of ppublic and + secret arguments. + 2003-04-24 Marcus Brinkmann * gpgme.texi (Generating Keys): Document changed gpgme_op_genkey diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 105e031..c318f97 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -2115,24 +2115,21 @@ The function @code{gpgme_key_release} is an alias for @cindex key, creation @cindex key ring, add -@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) +@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{public}}, @w{GpgmeData @var{secret}}) The function @code{gpgme_op_genkey} generates a new key pair in the -context @var{ctx} and puts it into the standard key ring if both -@var{pubkey} and @var{seckey} are @code{NULL}. In this case the -function returns immediately after starting the operation, and does -not wait for it to complete. If @var{pubkey} is not @code{NULL} it -should be the handle for an empty (newly created) data object, and -upon successful completion the data object will contain the public -key. If @var{seckey} is not @code{NULL} it should be the handle for -an empty (newly created) data object, and upon successful completion -the data object will contain the secret key. - -Note that not all crypto engines support this interface equally. -GnuPG does not support @var{pubkey} and @var{subkey}, they should be -both @code{NULL}, and the key pair will be added to the standard key -ring. GpgSM only supports @var{pubkey}, the secret key will be stored -by @command{gpg-agent}. GpgSM expects @var{pubkey} being not -@code{NULL}. +context @var{ctx}. The meaning of @var{public} and @var{secret} +depends on the crypto backend. + +GnuPG does not support @var{public} and @var{secret}, they should be +@code{NULL}. GnuPG will generate a key pair and add it to the +standard key ring. The fingerprint of the generated key is available +with @code{gpgme_op_genkey_result}. + +GpgSM requires @var{public} to be a writable data object. GpgSM will +generate a secret key (which will be stored by @command{gpg-agent}, +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 @@ -2154,6 +2151,7 @@ Passphrase: abc @end example Here is an example for GpgSM as the crypto engine: + @example Key-Type: RSA @@ -2165,28 +2163,28 @@ Name-Email: joe@@foo.bar Strings should be given in UTF-8 encoding. The only format supported for now is ``internal''. The content of the @code{GnupgKeyParms} -container is passed verbatim to GnuPG. Control statements are not -allowed. +container is passed verbatim to the crypto backend. Control +statements are not allowed. After the operation completed successfully, the result can be retrieved with @code{gpgme_op_genkey_result}. The function returns @code{GPGME_No_Error} if the operation could be started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not -a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or -@var{seckey} is not valid, and @code{GPGME_General_Error} if no key +a valid XML string, @code{GPGME_Not_Supported} if @var{public} or +@var{secret} is not valid, and @code{GPGME_General_Error} if no key was created by the backend. @end deftypefun -@deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) +@deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{public}}, @w{GpgmeData @var{secret}}) The function @code{gpgme_op_genkey_start} initiates a @code{gpgme_op_genkey} operation. It can be completed by calling @code{gpgme_wait} on the context. @xref{Waiting For Completion}. The function returns @code{GPGME_No_Error} if the operation could be started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not -a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or -@var{seckey} is not @code{NULL}. +a valid XML string, and @code{GPGME_Not_Supported} if @var{public} or +@var{secret} is not @code{NULL}. @end deftypefun @deftp {Data type} {GpgmeGenKeyResult} -- 2.26.2