Adjust configure.ac for modern autoconf.
[gpgme.git] / doc / gpgme.texi
index 8cf7c4b..72b9e22 100644 (file)
@@ -13,7 +13,8 @@
 @syncodeindex pg fn
 
 @copying
-Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008 g10 Code GmbH.
+Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
+2008, 2010 g10 Code GmbH.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -1014,6 +1015,18 @@ This value indicates ElGamal.
 
 @item GPGME_PK_ELG_E
 This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ELG_E
+This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ECDSA
+This value indicates ECDSA, the Elliptic Curve Digital Signature
+Algorithm as defined by FIPS 186-2.
+
+@item GPGME_PK_ECDH
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption
+algorithm as defined by the ECC in OpenPGP draft.
+
 @end table
 @end deftp
 
@@ -2737,6 +2750,7 @@ in the list is the main (or primary) user ID.
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Changing Passphrases::          Change the passphrase of a key.
 * Advanced Key Editing::          Advanced key edit operation.
 @end menu
 
@@ -2825,7 +2839,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_next} ends a pending key list
+The function @code{gpgme_op_keylist_end} ends a pending key list
 operation in the context @var{ctx}.
 
 After the operation completed successfully, the result of the key
@@ -3280,14 +3294,13 @@ 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:
+the crypto engine (all parameters of OpenPGP key generation are
+documented in the GPG manual):
 
 @example
 <GnupgKeyParms format="internal">
-Key-Type: DSA
-Key-Length: 1024
-Subkey-Type: ELG-E
-Subkey-Length: 1024
+Key-Type: default
+Subkey-Type: default
 Name-Real: Joe Tester
 Name-Comment: with stupid passphrase
 Name-Email: joe@@foo.bar
@@ -3296,7 +3309,8 @@ Passphrase: abc
 </GnupgKeyParms>
 @end example
 
-Here is an example for GpgSM as the crypto engine:
+Here is an example for GpgSM as the crypto engine (all parameters of
+OpenPGP key generation are documented in the GPGSM manual):
 
 @example
 <GnupgKeyParms format="internal">
@@ -3388,6 +3402,12 @@ practise to not send more than a few dozens key to a keyserver at one
 time.  Using this flag requires that the @var{keydata} argument of the
 export function is set to @code{NULL}.
 
+@item GPGME_EXPORT_MODE_MINIMAL
+If this bit is set, the smallest possible key is exported.  For OpenPGP
+keys it removes all signatures except for the latest self-signatures.
+For X.509 keys it has no effect.
+
+
 @end table
 
 
@@ -3715,6 +3735,41 @@ operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
 @end deftypefun
 
 
+@node Changing Passphrases
+@subsection  Changing Passphrases
+@cindex passphrase, change
+
+@deftypefun gpgme_error_t gpgme_op_passwd      @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_passwd} changes the passphrase of the
+private key associated with @var{key}.  The only allowed value for
+@var{flags} is @code{0}.  The backend engine will usually popup a window
+to ask for the old and the new passphrase.  Thus this function is not
+useful in a server application (where passphrases are not required
+anyway).
+
+Note that old @code{gpg} engines (before version 2.0.15) do not support
+this command and will silently ignore it.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_passwd_start      @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_passwd_start} initiates a
+@code{gpgme_op_passwd} operation.    It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{0} if the operation was started successfully,
+and an error code if one of the arguments is not valid or the oepration
+could not be started.
+@end deftypefun
+
+
 @node Advanced Key Editing
 @subsection Advanced Key Editing
 @cindex key, edit
@@ -3859,7 +3914,7 @@ there is not enough memory for the operation.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
-The function @code{gpgme_op_trustlist_next} ends a pending key list
+The function @code{gpgme_op_trustlist_end} ends a pending trust list
 operation in the context @var{ctx}.
 
 The function returns the error code @code{GPG_ERR_INV_VALUE} if
@@ -5263,6 +5318,9 @@ structure because the number of file descriptors needed for a crypto
 operation in @acronym{GPGME} is not predictable.
 
 @example
+#include <assert.h>
+#include <errno.h>
+#include <stdlib.h>
 #include <pthread.h>
 #include <sys/types.h>
 #include <gpgme.h>
@@ -5282,6 +5340,7 @@ struct one_fd
   int dir;
   gpgme_io_cb_t fnc;
   void *fnc_data;
+  void *loop;
 @};
 
 struct event_loop
@@ -5313,6 +5372,7 @@ add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
          fds[i].dir = dir;
          fds[i].fnc = fnc;
          fds[i].fnc_data = fnc_data;
+         fds[i].loop = loop;
          break;
        @}
     @}
@@ -5327,6 +5387,7 @@ void
 remove_io_cb (void *tag)
 @{
   struct one_fd *fd = tag;
+  struct event_loop *loop = fd->loop;
 
   pthread_mutex_lock (&loop->lock);
   fd->fd = -1;
@@ -5358,11 +5419,12 @@ do_select (struct event_loop *loop)
   fd_set wfds;
   int i, n;
   int any = 0;
+  struct one_fd *fdlist = loop->fds;
 
   pthread_mutex_lock (&loop->lock);
   FD_ZERO (&rfds);
   FD_ZERO (&wfds);
-  for (i = 0; i < FDLIST_MAX; i++)
+  for (i = 0; i < MAX_FDS; i++)
     if (fdlist[i].fd != -1)
       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
   pthread_mutex_unlock (&loop->unlock);
@@ -5377,7 +5439,7 @@ do_select (struct event_loop *loop)
     return n;  /* Error or timeout.  */
 
   pthread_mutex_lock (&loop->lock);
-  for (i = 0; i < FDLIST_MAX && n; i++)
+  for (i = 0; i < MAX_FDS && n; i++)
     @{
       if (fdlist[i].fd != -1)
        @{
@@ -5408,7 +5470,6 @@ wait_for_op (struct event_loop *loop, struct op_result *result)
       ret = do_select (loop);
     @}
   while (ret >= 0 && !result->done);
-  return ret;
 @}
 @end example
 
@@ -5423,7 +5484,6 @@ main (int argc, char *argv[])
   gpgme_ctx_t ctx;
   gpgme_error_t err;
   gpgme_data_t sig, text;
-  gpgme_sig_stat_t status;
   int i;
   struct gpgme_io_cb_ts io_cbs =
   @{
@@ -5437,7 +5497,7 @@ main (int argc, char *argv[])
   init_gpgme (void);
 
   /* Initialize the loop structure.  */
-  loop.lock = PTHREAD_MUTEX_INITIALIZER;
+  pthread_mutex_init (&loop.lock, NULL);
   for (i = 0; i < MAX_FDS; i++)
     loop->fds[i].fd = -1;
 
@@ -5452,7 +5512,7 @@ main (int argc, char *argv[])
   if (!err)
     @{
        gpgme_set_io_cbs (ctx, &io_cbs);
-       err = gpgme_op_verify_start (ctx, sig, text, &status);
+       err = gpgme_op_verify_start (ctx, sig, text, NULL);
     @}
   if (err)
     @{
@@ -5473,7 +5533,7 @@ main (int argc, char *argv[])
                gpgme_strsource (result.err), gpgme_strerror (result.err));
       exit (1);
     @}
-  /* Evaluate STATUS.  */
+  /* Evaluate verify result.  */
   @dots{}
   return 0;
 @}