2003-07-22 Moritz Schulte <moritz@g10code.com>
authorMoritz Schulte <mo@g10code.com>
Mon, 21 Jul 2003 22:48:13 +0000 (22:48 +0000)
committerMoritz Schulte <mo@g10code.com>
Mon, 21 Jul 2003 22:48:13 +0000 (22:48 +0000)
* gcrypt.texi: Added more documentation for the register
mechanism.

doc/ChangeLog
doc/gcrypt.texi

index 6a5fdf1..5750ba9 100644 (file)
@@ -1,3 +1,8 @@
+2003-07-22  Moritz Schulte  <moritz@g10code.com>
+
+       * gcrypt.texi: Added more documentation for the register
+       mechanism.
+
 2003-07-18  Werner Koch  <wk@gnupg.org>
 
        * gcrypt.texi (Misc): Add a warning on the use of opaque values.
index 78edd66..693a1c1 100644 (file)
@@ -241,17 +241,18 @@ blocks using an extendable and flexible API.
 
 @noindent
 The `@acronym{Libgcrypt}' library is fully thread-safe, where it makes
-sense to be thread-safe.  An exception are some cryptographic
-functions that modify a certain context stored in handles.  If the
-user really intents to use such functions from different threads on
-the same handle, he has to take care of the serialisation of such
-functions calls himself.
+sense to be thread-safe.  An exception for thread-safety are some
+cryptographic functions that modify a certain context stored in
+handles.  If the user really intents to use such functions from
+different threads on the same handle, he has to take care of the
+serialisation of such functions himself.  If not described otherwise,
+every function is thread-safe.
 
 The library automagically detects whether an applications uses no
 threading, pthreads or GNU Pth.
 
-@acronym{Libgcrypt} depends on the library `libgpg-error' [FIXME: REF?], which
-contains common error handling code for GnuPG components.
+@acronym{Libgcrypt} depends on the library `libgpg-error', which
+contains common error handling related code for GnuPG components.
 
 @c **********************************************************
 @c *******************  Preparation  ************************
@@ -286,14 +287,15 @@ file, like this:
 #include <gcrypt.h>
 @end example
 
-The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function and type
-names and @code{GCRY*} for other symbols.  In addition the same name
-prefixes with one prepended underscore are reserved for internal use
-and should never be used by an application.  Furthermore
+The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function
+and type names and @code{GCRY*} for other symbols.  In addition the
+same name prefixes with one prepended underscore are reserved for
+internal use and should never be used by an application.  Furthermore
 `libgpg-error' defines functions prefixed with `gpg_' and preprocessor
-symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses libgpg-error,
-which uses @code{gpg_err_*} as name space for function and type names
-and @code{GPG_ERR_*} for other symbols, including all the error codes.
+symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses
+libgpg-error, which uses @code{gpg_err_*} as name space for function
+and type names and @code{GPG_ERR_*} for other symbols, including all
+the error codes.
 
 @node Building sources
 @section Building sources
@@ -471,7 +473,7 @@ initialize_gcrypt (void)
 @node Controlling the library
 @section Controlling the library
 
-@deftypefun gpg_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
+@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
 
 This function can be used to influence the general behaviour of
 @acronym{Libgcrypt} in several ways.  Depending on @var{cmd}, more arguments can
@@ -844,7 +846,23 @@ contained in the error value @var{err}.  This string can be used to
 output a diagnostic message to the user.
 @end deftypefun
 
-The following example illustrates the use of @code{gcry_strerror}:
+The following example illustrates the use of the functions described
+above:
+
+@example
+@{
+  gcry_cipher_hd_t handle;
+  gcry_error_t err = 0;
+
+  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
+  if (err)
+    @{
+      fprintf (stderr, "Failure: %s/%s\n",
+               gcry_strsource (err),
+               gcry_strerror (err));
+    @}
+@}
+@end example
 
 @c **********************************************************
 @c *******************  General  ****************************
@@ -1088,11 +1106,86 @@ extension modules, see @xref{Modules}.
 
 @deftp {Data type} gcry_cipher_spec_t
 This is the `module specification structure' needed for registering
-cipher modules.  It has to be filled in by the user before it is used
-to register a module.
+cipher modules, which has to be filled in by the user before it can be
+used to register a module.  It contains the following members:
+
+@table @code
+@item const char *name
+The primary name of the algorithm.
+@item const char **aliases
+A list of strings that are `aliases' for the algorithm.  The list must
+be terminated with a NULL element.
+@item gcry_cipher_oid_spec_t *oids
+A list of OIDs that are to be associated with the algorithm.  The
+list's last element must have it's `oid' member set to NULL.  See
+below for an explanation of this type.
+@item size_t blocksize
+The block size of the algorithm, in bytes.
+@item size_t keylen
+The length of the key, in bits.
+@item size_t contextsize
+The size of the algorithm-specific `context', that should be allocated
+for each handle.
+@item gcry_cipher_setkey_t setkey
+The function responsible for initializing a handle with a provided
+key.  See below for a description of this type.
+@item gcry_cipher_encrypt_t encrypt
+The function responsible for encrypting a single block.  See below for
+a description of this type.
+@item gcry_cipher_decrypt_t decrypt
+The function responsible for decrypting a single block.  See below for
+a description of this type.
+@item gcry_cipher_stencrypt_t stencrypt
+Like `encrypt', for stream ciphers.  See below for a description of
+this type.
+@item gcry_cipher_stdecrypt_t stdecrypt
+Like `decrypt', for stream ciphers.  See below for a description of
+this type.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_cipher_oid_spec_t
+This type is used for associating a user-provided algorithm
+implementation with certain OIDs.  It contains the following members:
+@table @code
+@item const char *oid
+Textual representation of the OID.
+@item int mode
+Cipher mode for which this OID is valid.
+@end table
 @end deftp
 
-@deftypefun gpg_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
+@deftp {Data type} gcry_cipher_setkey_t
+Type for the `setkey' function, defined as: gcry_err_code_t
+(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
+keylen)
+@end deftp
+
+@deftp {Data type} gcry_cipher_encrypt_t
+Type for the `encrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *inbuf)
+@end deftp
+
+@deftp {Data type} gcry_cipher_decrypt_t
+Type for the `decrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *inbuf)
+@end deftp
+
+@deftp {Data type} gcry_cipher_stencrypt_t
+Type for the `stencrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *, unsigned int n)
+@end deftp
+
+@deftp {Data type} gcry_cipher_stdecrypt_t
+Type for the `stdecrypt' function, defined as: gcry_err_code_t
+(*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const
+unsigned char *, unsigned int n)
+@end deftp
+
+@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
 
 Register a new cipher module whose specification can be found in
 @var{cipher}.  On success, a new algorithm ID is stored in
@@ -1105,7 +1198,7 @@ Unregister the cipher identified by @var{module}, which must have been
 registered with gcry_cipher_register.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
+@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
 Get a list consisting of the IDs of the loaded cipher modules.  If
 @var{list} is zero, write the number of loaded cipher modules to
 @var{list_length} and return.  If @var{list} is non-zero, the first
@@ -1149,7 +1242,7 @@ Counter mode.
 To use a cipher algorithm, you must first allocate an according
 handle.  This is to be done using the open function:
 
-@deftypefun gpg_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd},
+@deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd},
 int @var{algo}, int @var{mode}, unsigned int @var{flags})
 
 This function creates the context handle required for most of the
@@ -1182,7 +1275,7 @@ This flag enables the CFB sync mode, which is a special feature of
 See @code{gcry_cipher_sync}.
 @item GCRY_CIPHER_CBC_CTS
 Enable cipher text stealing (CTS) for the CBC mode.  Cannot be used
-simultaneous as GCRY_CIPHER_CBC_MAC.
+simultaneous as GCRY_CIPHER_CBC_MAC
 @item GCRY_CIPHER_CBC_MAC
 Compute CBC-MAC keyed checksums.  This is the same as CBC mode, but
 only output the last block.  Cannot be used simultaneous as
@@ -1200,7 +1293,7 @@ This function releases the context created by @code{gcry_cipher_open}.
 In order to use a handle for performing cryptographic operations, a
 `key' has to be set first:
 
-@deftypefun gpg_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
+@deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
 
 Set the key @var{k} used for encryption or decryption in the context
 denoted by the handle @var{h}.  The length @var{l} of the key @var{k}
@@ -1218,7 +1311,7 @@ usually is a non-secret random string acting as a kind of salt value.
 The CTR mode requires a counter, which is also similar to a salt
 value.  To set the IV or CTR, use these functions:
 
-@deftypefun gpg_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
+@deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
 
 Set the initialization vector used for encryption or decryption. The
 vector is passed as the buffer @var{K} of length @var{l} and copied to
@@ -1227,7 +1320,7 @@ requirement of the selected algorithm and mode.  Note, that this is
 implemented as a macro.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})
+@deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})
 
 Set the counter vector used for encryption or decryption. The counter
 is passed as the buffer @var{c} of length @var{l} and copied to
@@ -1237,7 +1330,7 @@ the same size as the block size).  Note, that this is implemented as a
 macro.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
+@deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
 
 Set the given handle's context back to the state it had after the last
 call to gcry_cipher_setkey and clear the initialization vector.
@@ -1249,7 +1342,7 @@ The actual encryption and decryption is done by using one of the
 following functions.  They may be used as often as required to process
 all the data.
 
-@deftypefun gpg_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+@deftypefun gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
 
 @code{gcry_cipher_encrypt} is used to encrypt the data.  This function
 can either work in place or with two buffers.  It uses the cipher
@@ -1269,7 +1362,7 @@ The function returns @code{0} on success or an error code.
 @end deftypefun
 
 
-@deftypefun gpg_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
+@deftypefun gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t @var{h}, unsigned char *{out}, size_t @var{outsize}, const unsigned char *@var{in}, size_t @var{inlen})
 
 @code{gcry_cipher_decrypt} is used to decrypt the data.  This function
 can either work in place or with two buffers.  It uses the cipher
@@ -1292,7 +1385,7 @@ The function returns @code{0} on success or an error code.
 OpenPGP (as defined in RFC-2440) requires a special sync operation in
 some places, the following function is used for this:
 
-@deftypefun gpg_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
+@deftypefun gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t @var{h})
 
 Perform the OpenPGP sync operation on context @var{h}. Note, that this
 is a no-op unless the context was created with the flag
@@ -1303,7 +1396,7 @@ Some of the described functions are implemented as macros utilizing a
 catch-all control function.  This control function is rarely used
 directly but there is nothing which would inhibit it:
 
-@deftypefun gpg_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
+@deftypefun gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t @var{h}, int @var{cmd}, void *@var{buffer}, size_t @var{buflen})
 
 @code{gcry_cipher_ctl} controls various aspects of the cipher module and
 specific cipher contexts.  Usually some more specialized functions or
@@ -1313,7 +1406,7 @@ handle @var{h}.  Please see the comments in the source code
 (@code{src/global.c}) for details.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+@deftypefun gcry_error_t gcry_cipher_info (gcry_cipher_hd_t @var{h}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
 
 @code{gcry_cipher_info} is used to retrieve various
 information about a cipher context or the cipher module in general.
@@ -1328,7 +1421,7 @@ To work with the algorithms, several functions are available to map
 algorithm names to the internal identifiers, as well as ways to
 retrieve information about an algorithm or the current cipher context.
 
-@deftypefun gpg_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
+@deftypefun gcry_error_t gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
 
 This function is used to retrieve information on a specific algorithm.
 You pass the cipher algorithm ID as @var{algo} and the type of
@@ -1480,11 +1573,74 @@ introduction into extension modules, see @xref{Modules}.
 
 @deftp {Data type} gcry_md_spec_t
 This is the `module specification structure' needed for registering
-message digest modules.  It has to be filled in by the user before it
-is used to register a module.
+message digest modules, which has to be filled in by the user before
+it can be used to register a module.  It contains the following
+members:
+
+@table @code
+@item const char *name
+The primary name of this algorithm.
+@item unsigned char *asnoid
+Array of bytes that form the ASN OID.
+@item int asnlen
+Length of bytes in `asnoid'.
+@item gcry_md_oid_spec_t *oids
+A list of OIDs that are to be associated with the algorithm.  The
+list's last element must have it's `oid' member set to NULL.  See
+below for an explanation of this type.  See below for an explanation
+of this type.
+@item int mdlen
+Length of the message digest algorithm.  See below for an explanation
+of this type.
+@item gcry_md_init_t init
+The function responsible for initializing a handle.  See below for an
+explanation of this type.
+@item gcry_md_write_t write
+The function responsible for writing data into a message digest
+context.  See below for an explanation of this type.
+@item gcry_md_final_t final
+The function responsible for `finalizing' a message digest context.
+See below for an explanation of this type.
+@item gcry_md_read_t read
+The function reponsible for reading out a message digest result.  See
+below for an explanation of this type.
+@item size_t contextsize
+The size of the algorithm-specific `context', that should be
+allocated for each handle.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_md_oid_spec_t
+This type is used for associating a user-provided algorithm
+implementation with certain OIDs.  It contains the following members:
+
+@table @code
+@item const char *oidstring
+Textual representation of the OID.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_md_init_t
+Type for the `init' function, defined as: void (*gcry_md_init_t) (void
+*c)
+@end deftp
+
+@deftp {Data type} gcry_md_write_t
+Type for the `write' function, defined as: void (*gcry_md_write_t)
+(void *c, unsigned char *buf, size_t nbytes)
+@end deftp
+
+@deftp {Data type} gcry_md_final_t
+Type for the `final' function, defined as: void (*gcry_md_final_t)
+(void *c)
 @end deftp
 
-@deftypefun gpg_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
+@deftp {Data type} gcry_md_read_t
+Type for the `read' function, defined as: unsigned char
+*(*gcry_md_read_t) (void *c)
+@end deftp
+
+@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
 
 Register a new digest module whose specification can be found in
 @var{digest}.  On success, a new algorithm ID is stored in
@@ -1497,7 +1653,7 @@ Unregister the digest identified by @var{module}, which must have been
 registered with gcry_md_register.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
+@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
 Get a list consisting of the IDs of the loaded message digest modules.
 If @var{list} is zero, write the number of loaded message digest
 modules to @var{list_length} and return.  If @var{list} is non-zero,
@@ -1513,7 +1669,7 @@ to the correct number.
 To use most of these function it is necessary to create a context;
 this is done using:
 
-@deftypefun gpg_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
+@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
 
 Create a message digest object for algorithm @var{algo}.  @var{flags}
 may be given as an bitwise OR of constants described below.  @var{algo}
@@ -1550,7 +1706,7 @@ whether an algorithm has been enabled.
 If you want to calculate several hash algorithms at the same time, you
 have to use the following function right after the @code{gcry_md_open}:
 
-@deftypefun gpg_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
+@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
 
 Add the message digest algorithm @var{algo} to the digest object
 described by handle @var{h}.  Duplicated enabling of algorithms is
@@ -1560,7 +1716,7 @@ detected and ignored.
 If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
 be set using the function:
 
-@deftypefun gpg_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key},
+@deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key},
 size_t @var{keylen})
 
 For use with the HMAC feature, set the MAC key to the value of @var{key}
@@ -1597,7 +1753,7 @@ might not even be possible if the data is received from a pipe), a
 snapshot of the current hash context can be taken and turned into a new
 context:
 
-@deftypefun gpg_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
+@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
 
 Create a new digest object as an exact copy of the object described by
 handle @var{handle_src} and store it in @var{handle_dst}.  The context
@@ -1700,7 +1856,7 @@ or "@code{OID.}".  For a list of supported OIDs, see the source code at
 availability of an algorithm.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
+@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
 
 Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
 user allocated @var{buffer}. @var{length} must point to variable with
@@ -1717,7 +1873,7 @@ returns 0 on success.
 To test whether an algorithm is actually available for use, the
 following macro should be used:
 
-@deftypefun gpg_error_t gcry_md_test_algo (int @var{algo}) 
+@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo}) 
 
 The macro returns 0 if the algorithm @var{algo} is available for use.
 @end deftypefun
@@ -1921,11 +2077,104 @@ introduction into extension modules, see @xref{Modules}.
 
 @deftp {Data type} gcry_pk_spec_t
 This is the `module specification structure' needed for registering
-public key modules.  It has to be filled in by the user before it is
-used to register a module.
+public key modules, which has to be filled in by the user before it
+can be used to register a module.  It contains the following members:
+
+@table @code
+@item const char *name
+The primary name of this algorithm.
+@item char **aliases
+A list of strings that are `aliases' for the algorithm.  The list
+musdt be terminanted with a NULL element.
+@item const char *elements_pkey
+String containing the one-letter names of the MPI values contained in
+a public key.
+@item const char *element_skey
+String containing the one-letter names of the MPI values contained in
+a secret key.
+@item const char *elements_enc
+String containing the one-letter names of the MPI values that are the
+result of an encryption operation using this algorithm.
+@item const char *elements_sig
+String containing the one-letter names of the MPI values that are the
+result of a sign operation using this algorithm.
+@item const char *elements_grip
+String containing the one-letter names of the MPI values that are to
+be included in the `key grip'.
+@item int use
+The bitwise-OR of the following flags, depending on the abilities of
+the algortihm:
+@table @code
+@item GCRY_PK_USAGE_SIGN
+The algorithm supports signing and verifying of data.
+@item GCRY_PK_USAGE_ENCR
+The algorithm supports the encryption and decryption of data.
+@end table
+@item gcry_pk_generate_t generate
+The function responsible for generating a new key pair.  See below for
+a description of this type.
+@item gcry_pk_check_secret_key_t check_secret_key
+The function responsible for checking the sanity of a provided secret
+key.  See below for a description of this type.
+@item gcry_pk_encrypt_t encrypt
+The function responsible for encrypting data.  See below for a
+description of this type.
+@item gcry_pk_decrypt_t decrypt
+The function responsible for decrypting data.  See below for a
+description of this type.
+@item gcry_pk_sign_t sign
+The function reponsible for signing data.  See below for a description
+of this type.
+@item gcry_pk_verify_t verify
+The function responsible for verifying that the provided signature
+matches the provided data.  See below for a description of this type.
+@item gcry_pk_get_nbits_t get_nbits
+The function reponsible for returning the number of bits of a provided
+key.  See below for a description of this type.
+@end table
+@end deftp
+
+@deftp {Data type} gcry_pk_generate_t
+Type for the `generate' function, defined as: gcry_err_code_t
+(*gcry_pk_generate_t) (int algo, unsigned int nbits, unsigned long
+use_e, gcry_mpi_t *skey, gcry_mpi_t **retfactors)
+@end deftp
+
+@deftp {Data type} gcry_pk_check_secret_key_t
+Type for the `check_secret_key' function, defined as: gcry_err_code_t
+(*gcry_pk_check_secret_key_t) (int algo, gcry_mpi_t *skey)
+@end deftp
+
+@deftp {Data type} gcry_pk_encrypt_t
+Type for the `encrypt' function, defined as: gcry_err_code_t
+(*gcry_pk_encrypt_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
+gcry_mpi_t *pkey, int flags)
+@end deftp
+
+@deftp {Data type} gcry_pk_decrypt_t
+Type for the `decrypt' function, defined as: gcry_err_code_t
+(*gcry_pk_decrypt_t) (int algo, gcry_mpi_t *result, gcry_mpi_t *data,
+gcry_mpi_t *skey, int flags)
 @end deftp
 
-@deftypefun gpg_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
+@deftp {Data type} gcry_pk_sign_t
+Type for the `sign' function, defined as: gcry_err_code_t
+(*gcry_pk_sign_t) (int algo, gcry_mpi_t *resarr, gcry_mpi_t data,
+gcry_mpi_t *skey)
+@end deftp
+
+@deftp {Data type} gcry_pk_verify_t
+Type for the `verify' function, defined as: gcry_err_code_t
+(*gcry_pk_verify_t) (int algo, gcry_mpi_t hash, gcry_mpi_t *data,
+gcry_mpi_t *pkey, int (*cmp) (void *, gcry_mpi_t), void *opaquev)
+@end deftp
+
+@deftp {Data type} gcry_pk_get_nbits_t
+Type for the `get_nbits' function, defined as: unsigned
+(*gcry_pk_get_nbits_t) (int algo, gcry_mpi_t *pkey)
+@end deftp
+
+@deftypefun gcry_error_t gcry_pk_register (gcry_pk_spec_t *@var{pubkey}, unsigned int *algorithm_id, gcry_module_t *@var{module})
 
 Register a new public key module whose specification can be found in
 @var{pubkey}.  On success, a new algorithm ID is stored in
@@ -1938,7 +2187,7 @@ Unregister the public key module identified by @var{module}, which
 must have been registered with gcry_pk_register.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
+@deftypefun gcry_error_t gcry_pk_list (int *@var{list}, int *@var{list_length})
 Get a list consisting of the IDs of the loaded pubkey modules.  If
 @var{list} is zero, write the number of loaded pubkey modules to
 @var{list_length} and return.  If @var{list} is non-zero, the first
@@ -1978,7 +2227,7 @@ encrypt and decrypt data.  In almost all cases the data is a random
 session key which is in turn used for the actual encryption of the real
 data.  There are 2 functions to do this:
 
-@deftypefun gpg_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
+@deftypefun gcry_error_t gcry_pk_encrypt (@w{gcry_sexp_t *@var{r_ciph},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{pkey}})
 
 Obviously a public key must be provided for encryption.  It is
 expected as an appropriate S-expression (see above) in @var{pkey}.
@@ -2049,7 +2298,7 @@ ElGamal encryption operation.
 @end deftypefun
 @c end gcry_pk_encrypt
 
-@deftypefun gpg_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
+@deftypefun gcry_error_t gcry_pk_decrypt (@w{gcry_sexp_t *@var{r_plain},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
 
 Obviously a private key must be provided for decryption.  It is expected
 as an appropriate S-expression (see above) in @var{skey}.  The data to
@@ -2090,7 +2339,7 @@ encryption because digital signature are an important instrument for key
 management.  @acronym{Libgcrypt} support digital signatures using 2 functions,
 similar to the encryption functions:
 
-@deftypefun gpg_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
+@deftypefun gcry_error_t gcry_pk_sign (@w{gcry_sexp_t *@var{r_sig},} @w{gcry_sexp_t @var{data},} @w{gcry_sexp_t @var{skey}})
 
 This function creates a digital signature for @var{data} using the
 private key @var{skey} and place it into the variable at the address of
@@ -2158,7 +2407,7 @@ used with "elg" replacing "dsa".
 The operation most commonly used is definitely the verification of a
 signature.  @acronym{Libgcrypt} provides this function:
 
-@deftypefun gpg_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
+@deftypefun gcry_error_t gcry_pk_verify (@w{gcry_sexp_t @var{sig}}, @w{gcry_sexp_t @var{data}}, @w{gcry_sexp_t @var{pkey}})
 
 This is used to check whether the signature @var{sig} matches the
 @var{data}.  The public key @var{pkey} must be provided to perform this
@@ -2221,7 +2470,7 @@ algorithm or one where a "keygrip" has not yet been defined.
 The function accepts public or secret keys in @var{key}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
+@deftypefun gcry_error_t gcry_pk_testkey (gcry_sexp_t @var{key})
 
 Return 0 if @var{key} (either private or public) is sane.  NOTE: at
 the moment only the checking of secret keys is supported.
@@ -2283,7 +2532,7 @@ Please note that parameters not required should be passed as @code{NULL}.
 @c end gcry_pk_algo_info
 
 
-@deftypefun gpg_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
+@deftypefun gcry_error_t gcry_pk_ctl (@w{int @var{cmd}}, @w{void *@var{buffer}}, @w{size_t @var{buflen}})
 
 This is a general purpose function to perform certain control
 operations.  @var{cmd} controls what is to be done. The return value is
@@ -2301,9 +2550,10 @@ and @var{buflen} must have the value @code{sizeof (int)}.
 @c end gcry_pk_ctl
 
 @noindent
-@acronym{Libgcrypt} also provides a function to generate public key pairs:
+@acronym{Libgcrypt} also provides a function for generating public key
+pairs:
 
-@deftypefun gpg_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
+@deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
 
 This function create a new public key pair using information given in
 the S-expression @var{parms} and stores the private and the public key
@@ -2448,7 +2698,7 @@ for working with such data sets.
 A data set, that is simply a list of named MPI values.
 @end deftp
 
-@deftypefun gpg_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})
+@deftypefun gcry_error_t gcry_ac_data_new (gcry_ac_data_t *@var{data})
 Creates a new, empty data set and stores it in @var{data}.
 @end deftypefun
 
@@ -2456,14 +2706,14 @@ Creates a new, empty data set and stores it in @var{data}.
 Destroys the data set @var{data}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_set (gcry_ac_data_t @var{data},
+@deftypefun gcry_error_t gcry_ac_data_set (gcry_ac_data_t @var{data},
 char *@var{name}, gcry_mpi_t @var{mpi})
 Adds the value @var{mpi} to the data set @var{data} with the label
 @var{name}.  If there is already a value with that label, it is replaced,
 otherwise a new value is added.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
+@deftypefun gcry_error_t gcry_ac_data_copy (gcry_ac_data_t *@var{data_cp}, gcry_ac_data_t @var{data})
 Create a copy of the data set @var{data} and store it in @var{data_cp}.
 @end deftypefun
 
@@ -2472,7 +2722,7 @@ Returns the number of named MPI values inside of the data set
 @var{data}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data},
+@deftypefun gcry_error_t gcry_ac_data_get_name (gcry_ac_data_t @var{data},
 char *@var{name}, gcry_mpi_t *@var{mpi})
 
 Stores the value labelled with @var{name} found in data set @var{data}
@@ -2481,7 +2731,7 @@ gcry_ac_data_set is used to associate the label @var{name} with a
 different MPI value.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi})
+@deftypefun gcry_error_t gcry_ac_data_get_index (gcry_ac_data_t @var{data}, unsigned int @var{index}, const char **@var{name}, gcry_mpi_t *@var{mpi})
 
 Stores in @var{name} and @var{mpi} the named MPI value contained in
 the data set @var{data} with the index @var{index}.  @var{name} or
@@ -2500,7 +2750,7 @@ Destroys any values contained in the data set @var{data}.
 In order to use an algorithm, an according handle must be created.
 This is done using the following function:
 
-@deftypefun gpg_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle},
+@deftypefun gcry_error_t gcry_ac_open (gcry_ac_handle_t *@var{handle},
 int @var{algorithm}, int @var{flags})
 
 Creates a new handle for the algorithm @var{algorithm} and stores it
@@ -2544,18 +2794,56 @@ Key data structures can be created in two different ways; a new key
 pair can be generated, resulting in ready-to-use key.  Alternatively a
 key can be initialized from a given data set.
 
-@deftypefun gpg_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data})
+@deftypefun gcry_error_t gcry_ac_key_init (gcry_ac_key_t *@var{key}, gcry_ac_handle_t @var{handle}, gcry_ac_key_type_t @var{type}, gcry_ac_data_t @var{data})
 Creates a new key of type @var{type}, consisting of the MPI values
 contained in the data set @var{data} and stores it in @var{key}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, gcry_ac_key_pair_t *@var{key_pair}, unsigned int @var{nbits}, void *@var{key_spec})
+@deftypefun gcry_error_t gcry_ac_key_pair_generate (gcry_ac_handle_t @var{handle}, gcry_ac_key_pair_t *@var{key_pair}, unsigned int @var{nbits}, void *@var{key_spec})
 
 Generates a new key pair via the handle @var{handle} of @var{NBITS}
-bits and stores it in @var{key_pair}.  In case non-standard settings
-are wanted, a pointer to a structure of type
-@code{gcry_ac_key_spec_<algorithm>_t}, matching the selected
-algorithm, can be given as KEY_SPEC.
+bits and stores it in @var{key_pair}.
+
+In case non-standard settings are wanted, a pointer to a structure of
+type @code{gcry_ac_key_spec_<algorithm>_t}, matching the selected
+algorithm, can be given as KEY_SPEC.  Such a structure does only exist
+for RSA.  A descriptions of the members of the supported structures
+follows.
+
+@table @code
+@item gcry_ac_key_spec_rsa_t
+@table @code
+@item gcry_mpi_t e
+Generate the key pair using a special @code{e}.  The value of @code{e}
+has the following meanings:
+@table @code
+@item = 0
+Let @acronym{Libgcrypt} device what exponent should be used.
+@item = 1
+Request the use of a ``secure'' exponent; this is required by sosme
+specification to be 65537.
+@item > 2
+Try starting at this value until a working exponent is found.
+@end table
+@end table
+@end table
+
+Example code:
+@example
+@{
+  gcry_ac_key_pair_t key_pair;
+  gcry_ac_key_spec_rsa  rsa_spec;
+
+  rsa_spec.e = gcry_mpi_new (0);
+  gry_mpi_set_ui (rsa_spec.e, 1)
+
+  err = gcry_ac_open  (&handle, GCRY_AC_RSA, 0);
+  assert (! err);
+
+  err = gcry_ac_key_pair_generate (handle, &key_pair, 1024, (void *) &rsa_spec);
+  assert (! err);
+@}
+@end example
 @end deftypefun
 
 
@@ -2572,15 +2860,19 @@ Destroys the key @var{key}.
 Destroys the key pair @var{key_pair}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_key_test (gcry_ac_key_t @var{key})
+@deftypefun gcry_ac_data_t gcry_ac_key_data_get (gcry_ac_key_t @var{key})
+Returns the data set contained in the key @var{key}.
+@end deftypefun
+
+@deftypefun gcry_error_t gcry_ac_key_test (gcry_ac_key_t @var{key})
 Verifies that the key @var{key} is sane.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_key_get_nbits (gcry_ac_key_t @var{key}, unsigned int *@var{nbits})
+@deftypefun gcry_error_t gcry_ac_key_get_nbits (gcry_ac_key_t @var{key}, unsigned int *@var{nbits})
 Stores the number of bits of the key @var{key} in @var{nbits}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_key_get_grip (gcry_ac_key_t @var{key}, unsigned char *@var{key_grip})
+@deftypefun gcry_error_t gcry_ac_key_get_grip (gcry_ac_key_t @var{key}, unsigned char *@var{key_grip})
 Writes the 20 byte long key grip of the key @var{key} to
 @var{key_grip}.
 @end deftypefun
@@ -2588,26 +2880,26 @@ Writes the 20 byte long key grip of the key @var{key} to
 @node Using cryptographic functions
 @section Using cryptographic functions
 
-@deftypefun gpg_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t **@var{data_encrypted})
+@deftypefun gcry_error_t gcry_ac_data_encrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data_plain}, gcry_ac_data_t **@var{data_encrypted})
 Encrypts the plain text MPI value @var{data_plain} with the key public
 @var{key} under the control of the flags @var{flags} and stores the
 resulting data set into @var{data_encrypted}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted})
+@deftypefun gcry_error_t gcry_ac_data_decrypt (gcry_ac_handle_t @var{handle}, unsigned int @var{flags}, gcry_ac_key_t @var{key}, gcry_mpi_t *@var{data_plain}, gcry_ac_data_t @var{data_encrypted})
 Decrypts the encrypted data contained in the data set
 @var{data_encrypted} with the secret key KEY under the control of the
 flags @var{flags} and stores the resulting plain text MPI value in
 @var{DATA_PLAIN}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature})
+@deftypefun gcry_error_t gcry_ac_data_sign (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t *@var{data_signature})
 Signs the data contained in @var{data} with the secret key @var{key}
 and stores the resulting signature in the data set
 @var{data_signature}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature})
+@deftypefun gcry_error_t gcry_ac_data_verify (gcry_ac_handle_t @var{handle}, gcry_ac_key_t @var{key}, gcry_mpi_t @var{data}, gcry_ac_data_t @var{data_signature})
 Verifies that the signature contained in the data set
 @var{data_signature} is indeed the result of signing the data
 contained in @var{data} with the secret key belonging to the public
@@ -2617,12 +2909,12 @@ key @var{key}.
 @node Handle-independent functions
 @section Handle-independent functions
 
-@deftypefun gpg_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})
+@deftypefun gcry_error_t gcry_ac_id_to_name (gcry_ac_id_t @var{algorithm}, const char **@var{name})
 Stores the textual representation of the algorithm whose id is given
 in @var{algorithm} in @var{name}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})
+@deftypefun gcry_error_t gcry_ac_name_to_id (const char *@var{name}, gcry_ac_id_t *@var{algorithm})
 Stores the numeric ID of the algorithm whose textual representation is
 contained in @var{name} in @var{algorithm}.
 @end deftypefun
@@ -2717,7 +3009,7 @@ also a function to convert the internal representation back into one of
 the external formats:
 
 
-@deftypefun gpg_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
+@deftypefun gcry_error_t gcry_sexp_new (@w{gcry_sexp_t *@var{r_sexp}}, @w{const void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}})
 
 This is the generic function to create an new S-expression object from
 its external representation in @var{buffer} of @var{length} bytes.  On
@@ -2731,7 +3023,7 @@ Note, that the caller is responsible for releasing the newly allocated
 S-expression using @code{gcry_sexp_release}.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
+@deftypefun gcry_error_t gcry_sexp_create (@w{gcry_sexp_t *@var{r_sexp}}, @w{void *@var{buffer}}, @w{size_t @var{length}}, @w{int @var{autodetect}}, @w{void (*@var{freefnc})(void*)})
 
 This function is identical to @code{gcry_sexp_new} but has an extra
 argument @var{freefnc}, which, when not set to @code{NULL}, is expected
@@ -2743,14 +3035,14 @@ might decide to directly use the provided buffer and thus avoid extra
 copying.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
+@deftypefun gcry_error_t gcry_sexp_sscan (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
 
 This is another variant of the above functions.  It behaves nearly
 identical but provides an @var{erroff} argument which will receive the
 offset into the buffer where the parsing stopped on error.
 @end deftypefun
 
-@deftypefun gpg_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
+@deftypefun gcry_error_t gcry_sexp_build (@w{gcry_sexp_t *@var{r_sexp}}, @w{size_t *@var{erroff}}, @w{const char *@var{format}, ...})
 
 This function creates an internal S-expression from the string template
 @var{format} and stores it at the address of @var{r_sexp}. If there is a
@@ -3247,7 +3539,7 @@ math calculation and is only used to store an arbitrary bit pattern in
 @var{a}.
 
 WARNING: Never use an opaque MPI for actual math operations.  The only
-valid fucntions are gcry_mpi_get_opaque and gcry_mpi_release.  Use
+valid functions are gcry_mpi_get_opaque and gcry_mpi_release.  Use
 gcry_mpi_scan to convert a string of arbitrary bytes into an MPI.
 
 @end deftypefun