This is gcrypt.info, produced by makeinfo version 4.2 from
../../doc/gcrypt.texi.

INFO-DIR-SECTION GNU Libraries
START-INFO-DIR-ENTRY
* libgcrypt: (gcrypt) Cryptographic function library.
END-INFO-DIR-ENTRY

   This file documents the `Libgcrypt' library.

   This is Edition 1.1.12, last updated 19 January 2003, of `The
`Libgcrypt' Reference Manual', for Version 1.1.12.

   Copyright (C) 2000, 2002, 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no the Front-Cover texts, and with no
Back-Cover Texts.  A copy of the license is included in the section
entitled "GNU Free Documentation License".


File: gcrypt.info,  Node: S-expressions,  Next: MPI Functions,  Prev: Random Numbers,  Up: Top

S-expressions
*************

   S-expressions are used by the public key functions to pass complex
data structures around.  These LISP like objects are used by some
cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions
to parse and construct them.  For detailed information, see `Ron
Rivest, code and description of S-expressions,
`http://theory.lcs.mit.edu/~rivest/sexp.html''.

 - Data type: GcrySexp
     The `GcrySexp' type describes an object with the Libgcrypt internal
     representation of an S-expression.

There are several functions to create an Libgcrypt S-expression object
from its external representation or from a string template.  There is
also a function to convert the internal representation back into one of
the external formats:

 - Function: int gcry_sexp_new (GcrySexp *R_SEXP, const void *BUFFER,
          size_t LENGTH, int AUTODETECT)
     This is the generic function to create an new S-expression object
     from its external representation in BUFFER of LENGTH bytes.  On
     success the result is stored at the address given by R_SEXP.  With
     AUTODETECT set to 0, the data in BUFFER is expected to be in
     canonized format, with AUTODETECT set to 1 the parses any of the
     defined external formats.  If BUFFER does not hold a valid
     S-expression an error code is returned and R_SEXP set to `NULL'.
     Note, that the caller is responsible for releasing the newly
     allocated S-expression using `gcry_sexp_release'.

 - Function: int gcry_sexp_create (GcrySexp *R_SEXP, void *BUFFER,
          size_t LENGTH, int AUTODETECT, void (*FREEFNC)(void*))
     This function is identical to `gcry_sexp_new' but has an extra
     argument FREEFNC, which, when not set to `NULL', is expected to be
     a function to release the BUFFER; most likely the standard `free'
     function is used for this argument.  This has the effect of
     transferring the ownership of BUFFER to the created object in
     R_SEXP.  The advantage of using this function is that Libgcrypt
     might decide to directly use the provided buffer and thus avoid
     extra copying.

 - Function: int gcry_sexp_sscan (GcrySexp *R_SEXP, size_t *ERROFF,
          const char *BUFFER, size_t LENGTH)
     This is another variant of the above functions.  It behaves nearly
     identical but provides an ERROFF argument which will receive the
     offset into the buffer where the parsing stopped on error.

 - Function: int gcry_sexp_build (GcrySexp *R_SEXP, size_t *ERROFF,
          const char *FORMAT, ...)
     This function creates an internal S-expression from the string
     template FORMAT and stores it at the address of R_SEXP. If there
     is a parsing error, the function returns an appropriate error code
     and stores the offset into FORMAT where the parsing stopped in
     ERROFF.  The function supports a couple of printf-like formatting
     characters and expects arguments for some of these escape
     sequences right after FORMAT.  The following format characters are
     defined:

    `%m'
          The next argument is expected to be of type `GcryMPI' and a
          copy of its value is inserted into the resulting S-expression.

    `%s'
          The next argument is expected to be of type `char *' and that
          string is inserted into the resulting S-expression.

    `%d'
          The next argument is expected to be of type `int' and its
          value ist inserted into the resulting S-expression.

     No other format characters are defined and would return an error.
     Note, that the format character `%%' does not exists, because a
     percent sign is not a valid character in an S-expression.

 - Function: void gcry_sexp_release (GcrySexp SEXP)
     Release the S-expression object SEXP.

The next 2 functions are used to convert the internal representation
back into a regular external S-expression format and to show the
structure for debugging.

 - Function: size_t gcry_sexp_sprint (GcrySexp SEXP, int MODE,
          char *BUFFER, size_t MAXLENGTH)
     Copies the S-expression object SEXP into BUFFER using the format
     specified in MODE.  MAXLENGTH must be set to the allocated length
     of BUFFER.  The function returns the actual length of valid bytes
     put into BUFFER or 0 if the provided buffer is too short.  Passing
     `NULL' for BUFFER returns the required length for BUFFER.  For
     convenience reasons an extra byte with value 0 is appended to the
     buffer.

     The following formats are supported:

    `GCRYSEXP_FMT_DEFAULT'
          Returns a convenient external S-expression representation.

    `GCRYSEXP_FMT_CANON'
          Return the S-expression in canonical format.

    `GCRYSEXP_FMT_BASE64'
          Not currently supported.

    `GCRYSEXP_FMT_ADVANCED'
          Returns the S-expression in advanced format.

 - Function: void gcry_sexp_dump (GcrySexp SEXP)
     Dumps SEXP in a format suitable for debugging to Libgcrypt's
     logging stream.

Often canonical encoding is used in the external representation.  The
following function can be used to check for valid encoding and to learn
the length of the S-expression"

 - Function: size_t gcry_sexp_canon_len (const unsigned char *BUFFER,
          size_t LENGTH, size_t *ERROFF, int *ERRCODE)
     Scan the canonical encoded BUFFER with implicit length values and
     return the actual length this S-expression uses.  For a valid
     S-expression it should never return 0.  If LENGTH is not 0, the
     maximum length to scan is given; this can be used for syntax
     checks of data passed from outside.  ERRCODE and ERROFF may both be
     passed as `NULL'.

     *Warning:* For historical reasons the error codes returned in
     ERRCODE are negative numbers and don't match the regular error
     codes.  To convert to regular error codes, use the simple formula
     `rc = 200 - errcode'.

There are a couple of functions to parse S-expressions and retrieve
elements:

 - Function: GcrySexp gcry_sexp_find_token (const GcrySexp LIST,
          const char *TOKEN, size_t TOKLEN)
     Scan the S-expression for a sublist with a type (the car of the
     list) matching the string TOKEN.  If TOKLEN is not 0, the token is
     assumed to be raw memory of this length.  The function returns a
     newly allocated S-expression consisting of the found sublist or
     `NULL' when not found.

 - Function: int gcry_sexp_length (const GcrySexp LIST)
     Return the length of the LIST.  For a valid S-expression this
     should be at least 1.

 - Function: GcrySexp gcry_sexp_nth (const GcrySexp LIST, int NUMBER)
     Create and return a new S-expression from the element with index
     NUMBER in LIST.  Note that the first element has the index 0.  If
     there is no such element, `NULL' is returned.

 - Function: GcrySexp gcry_sexp_car (const GcrySexp LIST)
     Create and return a new S-expression from the first element in
     LIST; this called the "type" and should always exist and be a
     string. `NULL' is returned in case of a problem.

 - Function: GcrySexp gcry_sexp_cdr (const GcrySexp LIST)
     Create and return a new list form all elements except for the
     first one.  Note, that this function may return an invalid
     S-expression because it is not guaranteed, that the type exists
     and is a string.  However, for parsing a complex S-expression it
     might be useful for intermediate lists.  Returns `NULL' on error.

 - Function: const char * gcry_sexp_nth_data (const GcrySexp LIST,
          int NUMBER, size_t *DATALEN)
     This function is used to get data from a LIST.  A pointer to the
     actual data with index NUMBER is returned and the length of this
     data will be stored to DATALEN.  If there is no data at the given
     index or the index represents another list, `NULL' is returned.
     *Note:* The returned pointer is valid as long as LIST is not
     modified or released.

     Here is an example on how to extract and print the surname (Meier)
     from the S-expression `(Name Otto Meier (address Burgplatz 3))':

          size_t len;
          const char *name;
          
          name = gcry_sexp_nth_data (list, 2, &len);
          printf ("my name is %.*s\n", (int)len, name);

 - Function: GcryMPI gcry_sexp_nth_mpi (GcrySexp LIST, int NUMBER,
          int MPIFMT)
     This function is used to get and convert data from a LIST. This
     data is assumed to be an MPI stored in the format described by
     MPIFMT and returned as a standard Libgcrypt MPI.  The caller must
     release this returned value using `gcry_mpi_release'.  If there is
     no data at the given index, the index represents a list or the
     value can't be converted to an MPI, `NULL' is returned.


File: gcrypt.info,  Node: MPI Functions,  Next: Utilities,  Prev: S-expressions,  Up: Top

MPI Functions
*************

   Public key cryptography is based on mathematics with large numbers.
To implement the public key functions, a library for handling these
large numbers is required.  Because of the general usefulness of such a
library, its interface is exposed by Libgcrypt.  The implementation is
based on an old release of GNU Multi-Precision Library (GMP) but in the
meantime heavily modified and stripped down to what is required for
cryptography. For a lot of CPUs, high performance assembler
implementations of some very low level functions are used to gain much
better performance than with the standard C implementation.

In the context of Libgcrypt and in most other applications, these large
numbers are called MPIs (multi-precision-integers).

 - Data type: GcryMPI
     The `GcryMPI' type represents an object to hold an MPI.

To work with MPIs, storage must be allocated and released for the
numbers.  This can be done with one of these functions:

 - Function: GcryMPI gcry_mpi_new (unsigned int NBITS)
     Allocate a new MPI object, initialize it to 0 and initially
     allocate enough memory for a number of at least NBITS.  This
     pre-allocation is only a small performance issue and not actually
     necessary because Libgcrypt automatically re-allocates the
     required memory.

 - Function: GcryMPI gcry_mpi_snew (unsigned int NBITS)
     This is identical to `gcry_mpi_new' but allocates the MPI in the so
     called "secure memory" which in turn will take care that all
     derived values will also be stored in this "secure memory".  Use
     this for highly confidential data like private key parameters.

 - Function: GcryMPI gcry_mpi_copy (const GcryMPI A)
     Create a new MPI as the exact copy of A.

 - Function: void gcry_mpi_release (GcryMPI A)
     Release the MPI A and free all associated resources.  Passing
     `NULL' is allowed and ignored.  When a MPI stored in the "secure
     memory" is released, that memory gets wiped out immediately.

The simplest operations are used to assign a new value to an MPI:

 - Function: GcryMPI gcry_mpi_set (GcryMPI W, const GcryMPI U)
     Assign the value of U to W and return W.  If `NULL' is passed for
     W, a new MPI is allocated, set to the value of U and returned.

 - Function: GcryMPI gcry_mpi_set_ui (GcryMPI W, unsigned long U)
     Assign the value of U to W and return W.  If `NULL' is passed for
     W, a new MPI is allocated, set to the value of U and returned.
     This function takes an `unsigned int' as type for U and thus it is
     only possible to set W to small values (usually up to the word
     size of the CPU).

 - Function: void gcry_mpi_swap (GcryMPI A, GcryMPI B)
     Swap the values of A and B.

The following functions are used to convert between an external
representation of an MPI and the internal one of Libgcrypt.

 - Function: int gcry_mpi_scan (GcryMPI *R_MPI,
          enum gcry_mpi_format FORMAT, const char *BUFFER,
          size_t *NBYTES)
     Convert the external representation of an integer stored in BUFFER
     with a length stored at the address of NBYTES into a newly created
     MPI returned which will be stored at the address of R_MPI.  For
     certain formats the length argument is not required and may be
     passed as `NULL'.  After a successful operation the variable NBYTES
     points to, receives the number of bytes actually scanned. FORMAT
     describes the format of the MPI as stored in BUFFER:

    `GCRYMPI_FMT_STD'
          2-complement stored without a length header.

    `GCRYMPI_FMT_PGP'
          As used by OpenPGP (only defined as unsigned). This is
          basically `GCRYMPI_FMT_STD' with a 2 byte big endian length
          header.

    `GCRYMPI_FMT_SSH'
          As used in the Secure Shell protocol.  This is
          `GCRYMPI_FMT_STD' with a 4 byte big endian header.

    `GCRYMPI_FMT_HEX'
          Stored as a C style string with each byte of the MPI encoded
          as 2 hex digits.

    `GCRYMPI_FMT_USG'
          Simple unsigned integer.

     Note, that all of the above formats store the integer in big-endian
     format (MSB first).

 - Function: int gcry_mpi_print (enum gcry_mpi_format FORMAT,
          char *BUFFER, size_t *NBYTES, const GcryMPI A)
     Convert the MPI A into an external representation described by
     FORMAT (see above) and store it in the provided BUFFER which which
     has a usable length of at least the number of bytes stored in the
     variable NBYTES points to; this variable will receive the actual
     number of bytes stored after a successful operation.

 - Function: int gcry_mpi_aprint (enum gcry_mpi_format FORMAT,
          void **BUFFER, size_t *NBYTES, const GcryMPI A)
     Convert the MPI A into an external representation described by
     FORMAT (see above) and store it in a newly allocated buffer which
     address will be stored in the variable BUFFER points to.  The
     number of bytes stored in this buffer will be stored in the
     variable NBYTES points to, unless NBYTES is `NULL'.

Basic arithmetic operations:

 - Function: void gcry_mpi_add (GcryMPI W, GcryMPI U, GcryMPI V)
     W = U + V.

 - Function: void gcry_mpi_add_ui (GcryMPI W, GcryMPI U,
          unsigned long V)
     W = U + V.  Note, that V is an unsigned integer.

 - Function: void gcry_mpi_addm (GcryMPI W, GcryMPI U, GcryMPI V,
          GcryMPI M)
     varw = U + V \bmod M.

 - Function: void gcry_mpi_sub (GcryMPI W, GcryMPI U, GcryMPI V)
     W = U - V.

 - Function: void gcry_mpi_sub_ui (GcryMPI W, GcryMPI U,
          unsigned long V)
     W = U - V.  V is an unsigned integer.

 - Function: void gcry_mpi_subm (GcryMPI W, GcryMPI U, GcryMPI V,
          GcryMPI M)
     W = U - V \bmod M.

 - Function: void gcry_mpi_mul (GcryMPI W, GcryMPI U, GcryMPI V)
     W = U * V.

 - Function: void gcry_mpi_mul_ui (GcryMPI W, GcryMPI U,
          unsigned long V)
     W = U * V.  V is an unsigned integer.

 - Function: void gcry_mpi_mulm (GcryMPI W, GcryMPI U, GcryMPI V,
          GcryMPI M)
     W = U * V \bmod M.

 - Function: void gcry_mpi_mul_2exp (GcryMPI W, GcryMPI U,
          unsigned long E)
     W = U * 2^e.

 - Function: void gcry_mpi_div (GcryMPI Q, GcryMPI R, GcryMPI DIVIDEND,
          GcryMPI DIVISOR, int ROUND)
     Q = DIVIDEND / DIVISOR, R = DIVIDEND \bmod DIVISOR.  Q and R may
     be passed as `NULL'.  ROUND should be negative or 0.

 - Function: void gcry_mpi_mod (GcryMPI R, GcryMPI DIVIDEND,
          GcryMPI DIVISOR)
     R = DIVIDEND \bmod DIVISOR.

 - Function: void gcry_mpi_powm (GcryMPI W, const GcryMPI B,
          const GcryMPI E, const GcryMPI M)
     W = B^e \bmod M.

 - Function: int gcry_mpi_gcd (GcryMPI G, GcryMPI A, GcryMPI B)
     Set G to the greatest common divisor of A and B.  Return true if
     the G is 1.

 - Function: int gcry_mpi_invm (GcryMPI X, GcryMPI A, GcryMPI M)
     Set X to the multiplicative inverse of A \bmod M.  Return true if
     the inverse exists.

The next 2 functions are used to compare MPIs:

 - Function: int gcry_mpi_cmp (const GcryMPI U, const GcryMPI V)
     Compare the big integer number U and V returning 0 for equality, a
     positive value for U > V and a negative for U < V.

 - Function: int gcry_mpi_cmp_ui (const GcryMPI U, unsigned long V)
     Compare the big integer number U with the unsigned integer V
     returning 0 for equality, a positive value for U > V and a
     negative for U < V.

There are a couple of functions to get information on arbitrary bits in
an MPI and to set or clear them:

 - Function: unsigned int gcry_mpi_get_nbits (GcryMPI A)
     Return the number of bits required to represent A.

 - Function: int gcry_mpi_test_bit (GcryMPI A, unsigned int N)
     Return true if bit number N (counting from 0) is set in A.

 - Function: void gcry_mpi_set_bit (GcryMPI A, unsigned int N)
     Set bit number N in A.

 - Function: void gcry_mpi_clear_bit (GcryMPI A, unsigned int N)
     Clear bit number N in A.

 - Function: void gcry_mpi_set_highbit (GcryMPI A, unsigned int N)
     Set bit number N in A and clear all bits greater than N.

 - Function: void gcry_mpi_clear_highbit (GcryMPI A, unsigned int N)
     Clear bit number N in A and all bits greater than N.

 - Function: void gcry_mpi_rshift (GcryMPI X, GcryMPI A, unsigned int N)
     Shift the value of A by N bits to the right and store the result
     in X.

The remaining MPI functions take care of very special properties of the
implementation:

 - Function: GcryMPI gcry_mpi_set_opaque (GcryMPI A, void *P,
          unsigned int NBITS)
     Store NBITS of the value P points to in A and mark A as an opaque
     value (i.e. an value that can't be used for any math calculation
     and is only used to store an arbitrary bit pattern in A.

 - Function: void * gcry_mpi_get_opaque (GcryMPI A, unsigned int *NBITS)
     Return a pointer to an opaque value stored in A and return its
     size in NBITS.  Note, that the returned pointer is still owned by
     A and that the function should never be used for an non-opaque MPI.

 - Function: void gcry_mpi_set_flag (GcryMPI A, enum gcry_mpi_flag FLAG)
     Set the FLAG for the MPI A.  Currently only the flag
     `GCRYMPI_FLAG_SECURE' is allowed to convert A into an MPI stored
     in "secure memory".

 - Function: void gcry_mpi_clear_flag (GcryMPI A,
          enum gcry_mpi_flag FLAG)
     Clear FLAG for the big integer A.  Note, that this function is
     currently useless as no flags are allowed.

 - Function: int gcry_mpi_get_flag (GcryMPI A, enum gcry_mpi_flag FLAG)
     Return true when the FLAG is set for A.


File: gcrypt.info,  Node: Utilities,  Next: Error Handling,  Prev: MPI Functions,  Up: Top

Utilities
*********

   Helper functions.


File: gcrypt.info,  Node: Error Handling,  Next: Library Copying,  Prev: Utilities,  Up: Top

Error Handling
**************

   Most functions in Libgcrypt are returning an error if they fail.  For
this reason, the application should always catch the error condition and
take appropriate measures, for example by releasing the resources and
passing the error up to the caller, or by displaying a descriptive
message to the user and canceling the operation.

   Some error values do not indicate a system error or an error in the
operation, but the result of an operation that failed properly.

* Menu:

* Error values::                A list of all error values used.
* Error strings::               How to get a descriptive string from a value.


File: gcrypt.info,  Node: Error values,  Next: Error strings,  Up: Error Handling

Error values
============

   Errors are return as an `int' Except for the EOF and No_Error cases
an application should always use the constants.  Possible values are:

`GCRYERR_EOF'
     This value indicates the end of a list, buffer or file and is
     defined to have the value `-1'.

`GCRYERR_SUCCESS'
     This value indicates success.  The value of this error code is
     guaranteed to be `0'.

`GCRYERR_GENERAL'
     This value means that something went wrong, but either there is not
     enough information about the problem to return a more useful error
     value, or there is no separate error value for this type of
     problem.

`GCRYERR_INV_PK_ALGO'
     Invalid public key algorithm.

`GCRYERR_INV_MD_ALGO'
     Invalid message digest algorithm.

`GCRYERR_BAD_PUBLIC_KEY'
     Bad public key.

`GCRYERR_BAD_SECRET_KEY'
     Bad secret key.

`GCRYERR_BAD_SIGNATURE'
     Bad signature.

`GCRYERR_INV_CIPHER_ALGO'
     Invalid cipher algorithm.

`GCRYERR_BAD_MPI'
     Problem with an MPI's value.

`GCRYERR_WRONG_PK_ALGO'
     Wrong public key algorithm.

`GCRYERR_WEAK_KEY'
     Weak encryption key detected.

`GCRYERR_INV_KEYLEN'
     Invalid length of a key.

`GCRYERR_INV_ARG'
     Invalid argument.

`GCRYERR_SELFTEST'
     A self test failed.

`GCRYERR_INV_OP'
     Invalid operation code or control command.

`GCRYERR_NO_MEM'
     Out of core; not enough memory available to perform operation.

`GCRYERR_INTERNAL'
     Internal error.  This is most likely a bug in Libgcrypt or due to
     an incomplete build or installation.

`GCRYERR_EOF = 64'
     End-of-file condition. Note, that some functions usually return
     `-1' to indicate this; Libgcrypt error function maps this to this
     value.

`GCRYERR_INV_OBJ'
     An object is not valid.

`GCRYERR_TOO_SHORT'
     Provided buffer or object too short.

`GCRYERR_TOO_LARGE'
     Object is too large.

`GCRYERR_NO_OBJ'
     Missing item in an object.

`GCRYERR_NOT_IMPL'
     Not implemented.

`GCRYERR_CONFLICT'
     Conflicting use of function or values.

`GCRYERR_INV_CIPHER_MODE'
     Invalid or unsupported cipher mode.

`GCRYERR_INV_FLAG'
     Invalid flag.

`GCRYERR_SEXP_INV_LEN_SPEC'
     The S-expression has an invalid length specification.

`GCRYERR_SEXP_STRING_TOO_LONG'
     The encoded length of an S-expression is longer than the entire
     object.

`GCRYERR_SEXP_UNMATCHED_PAREN'
     There are unmatched parenthesis in the S-expression.

`GCRYERR_SEXP_NOT_CANONICAL'
     Not a canonical encoded S-expression.

`GCRYERR_SEXP_BAD_CHARACTER'
     Bad character detected in an S-expression.

`GCRYERR_SEXP_BAD_QUOTATION'
     Bad quotation in an S-expression.  Might also indicate an invalid
     hex or octal value.

`GCRYERR_SEXP_ZERO_PREFIX'
     The length field of an S-expression element is prefixed with a 0.

`GCRYERR_SEXP_NESTED_DH'
     Nested display hints found in an S-expression.

`GCRYERR_SEXP_UNMATCHED_DH'
     Unmatched display hint found in an S-expression.

`GCRYERR_SEXP_UNEXPECTED_PUNC'
     Unexpected reserved punctuation found in an S-expression.

`GCRYERR_SEXP_BAD_HEX_CHAR'
     A bad hexadecimal character was found in an S-expression

`GCRYERR_SEXP_ODD_HEX_NUMBERS'
     An odd number of hexadecimal characters was found in an
     S-expression.

`GCRYERR_SEXP_BAD_OCT_CHAR'
     A bad octal character was found in an S-expression.


File: gcrypt.info,  Node: Error strings,  Prev: Error values,  Up: Error Handling

Error strings
=============

 - Function: const char * gcry_strerror (int ERR)
     The function `gcry_strerror' returns a pointer to a statically
     allocated string containing a description of the error with the
     error value ERR.  This string can be used to output a diagnostic
     message to the user.