\input texinfo @c -*- Texinfo -*-
@c Copyright (C) 2000, 2002 Free Software Foundation, Inc.
@c
@c This file is part of the libgcrypt.
@c
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.1 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, with no the Front-Cover texts, and with no
@c Back-Cover Texts.
@c A copy of the license is included in the file 'fdl.texi'.
@c
@setfilename gcrypt.info
@settitle The `Libgcrypt' Reference Manual
@dircategory GNU Libraries
@direntry
* libgcrypt: (gcrypt) Cryptographic function library.
@end direntry
@include version.texi
@c Unify some of the indices.
@syncodeindex tp fn
@syncodeindex pg fn
@ifinfo
This file documents the `Libgcrypt' library.
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
@cite{The `Libgcrypt' Reference Manual}, for Version
@value{VERSION}.
Copyright @copyright{} 2000, 2002 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''.
@end ifinfo
@iftex
@shorttitlepage The `Libgcrypt' Reference Manual
@end iftex
@titlepage
@center @titlefont{The `Libgcrypt'}
@sp 1
@center @titlefont{Reference Manual}
@sp 6
@center Edition @value{EDITION}
@sp 1
@center last updated @value{UPDATED}
@sp 1
@center for version @value{VERSION}
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2000, 2002 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''.
@end titlepage
@page
@ifnottex
@node Top
@top Main Menu
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
@cite{The `Libgcrypt' Reference Manual}, for Version
@value{VERSION} of the @acronym{GPGME} library.
@end ifnottex
@menu
* Introduction:: How to use this manual.
* Preparation:: What you should do before using the library.
* Cipher Functions:: All about ciphers.
* Hash Functions:: How to use cryptographic hash functions.
* Public Key Functions:: How to use asymmetric encryption.
* Random Numbers:: How to create random.
* Utilities:: Helper functions.
* Error Handling:: Error codes and such.
Appendices
* Library Copying:: The GNU Lesser General Public License
says how you can copy and share `Libgcrypt'.
* Copying:: The GNU General Public License says how you
can copy and share some parts of `Libgcrypt'.
* Free Documentation License:: This manual is under the GNU Free
Documentation License.
Indices
* Concept Index:: Index of concepts and programs.
* Function and Data Index:: Index of functions, variables and data types.
@detailmenu
@end detailmenu
@end menu
@c **********************************************************
@c ******************* Introduction ***********************
@c **********************************************************
@node Introduction
@chapter Introduction
`Libgcrypt' is a library to provide cryptographic building blocks.
@menu
* Getting Started::
* Features::
* Overview::
@end menu
@node Getting Started
@section Getting Started
This manual documents the `Libgcrypt' library programming interface.
All functions and data types provided by the library are explained.
The reader is assumed to possess basic knowledge about applied
cryptography.
This manual can be used in several ways. If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application. Forward references are included where
necessary. Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library. Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up those parts
of the interface which are unclear.
@node Features
@section Features
`Libgcrypt' might have a couple of advantages over other libraries doing
a similar job.
@table @asis
@item It's Free Software
Anybody can use, modify, and redistribute it under the terms of the GNU
Lesser General Public License (@pxref{Library Copying}). Note, that
some parts (which are not needed on a GNU or GNU/Linux system) are
subject to the terms of the GNU General Public License
(@pxref{Copying}); please see the README file of the distribution for of
list of these parts.
@item It encapsulates the low level cryptography
`Libgcrypt' a high level interface to cryptographic building blocks
using an extendable and flexible API.
@end table
@node Overview
@section Overview
Blurb
The `Libgcrypt' library is thread-safe. Well, we hope so ;-)
@c **********************************************************
@c ******************* Preparation ************************
@c **********************************************************
@node Preparation
@chapter Preparation
To use `Libgcrypt', you have to perform some changes to your sources and
the build system. The necessary changes are small and explained in the
following sections. At the end of this chapter, it is described how the
library is initialized, and how the requirements of the library are
verified.
@menu
* Header::
* Version Check::
* Building the source::
@end menu
@node Header
@section Header
All interfaces (data types and functions) of the library are defined
in the header file `gcrypt.h'. You must include this in all programs
using the library, either directly or through some other header file,
like this:
@example
#include <gcrypt.h>
@end example
The name space of `Libgcrypt' is @code{gcry_*} for function names,
@code{Gcry*} for data types 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.
@node Version Check
@section Version Check
It is often desirable to check that the version of `Libgcrypt' used is
indeed one which fits all requirements. Even with binary compatibility
new features may have been introduced but due to problem with the
dynamic linker an old version is actually used. So you may want to
check that the version is okay right after program startup.
@deftypefun const char *gcry_check_version (const char *@var{req_version})
Check that the the version of the library is at minimum the one given as
a string in @var{req_version} and return the actual version string of
the library; return NULL if the condition is not met. If @code{NULL} is
passed to this function no check is done and only the version string is
returned. It is a pretty good idea to run this function as soon as
possible, because it may also intializes some subsystems. In a
multithreaded environment if should be called before any more threads
are created.
@end deftypefun
@node Building the source
@section Building the source
If you want to compile a source file including the `gcrypt.h' header
file, you must make sure that the compiler can find it in the
directory hierarchy. This is accomplished by adding the path to the
directory in which the header file is located to the compilers include
file search path (via the @option{-I} option).
However, the path to the include file is determined at the time the
source is configured. To solve this problem, `Libgrypt' ships with a small
helper program @command{libgcrypt-config} that knows the path to the
include file and other configuration options. The options that need
to be added to the compiler invocation at compile time are output by
the @option{--cflags} option to @command{libgcrypt-config}. The following
example shows how it can be used at the command line:
@example
gcc -c foo.c `libgcrypt-config --cflags`
@end example
Adding the output of @samp{libgcrypt-config --cflags} to the compilers
command line will ensure that the compiler can find the `Libgcrypt' header
file.
A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files. For this to work,
the path to the library files has to be added to the library search path
(via the @option{-L} option). For this, the option @option{--libs} to
@command{libgcrypt-config} can be used. For convenience, this option
also outputs all other options that are required to link the program
with the `Libgcrypt' libararies (in particular, the @samp{-lgcrypt}
option). The example shows how to link @file{foo.o} with the `Libgcrypt'
library to a program @command{foo}.
@example
gcc -o foo foo.o `libgcrypt-config --libs`
@end example
Of course you can also combine both examples to a single command by
specifying both options to @command{libgcrypt-config}:
@example
gcc -o foo foo.c `libgcrypt-config --cflags --libs`
@end example
@c **********************************************************
@c ******************* Ciphers ****************************
@c **********************************************************
@c @include cipher-ref.texi
@node Cipher Functions
@chapter Cipher Functions
@deftypefun GCRY_CIPHER_HD gcry_cipher_open (int @var{algo}, int @var{mode}, unsigned int @var{flags})
This function creates the context required for most of the othercipher
functions. In case of an error @code{NULL} is returned.
@end deftypefun
@deftypefun void gcry_cipher_close (GCRY_CIPHER_HD @var{h})
This function releases the context created by @code{gcry_cipher_open}.
@end deftypefun
@deftypefun int gcry_cipher_ctl (GCRY_CIPHER_HD @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 specialzed functions are
used for this purpose.
@end deftypefun
@deftypefun int gcry_cipher_setkey (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
Set the key used for encryption or decryption. Note, that this is
implemented as a macro.
@end deftypefun
@deftypefun int gcry_cipher_setiv (GCRY_CIPHER_HD @var{h}, void *@var{k}, size_t @var{l})
Set the initialization vector used for encryption or decryption. Note,
that this is implemented as a macro.
@end deftypefun
@deftypefun int gcry_cipher_sync (GCRY_CIPHER_HD @var{h})
Peform the a ``sync'' operation which is only used with certain modes.
@end deftypefun
@c ***********************************************
@c *********** cipher info ********************
@c ***********************************************
@deftypefun int gcry_cipher_info (GCRY_CIPHER_HD @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.
Currently no information is available.
@end deftypefun
@deftypefun int gcry_cipher_algo_info (int @var{algo}, int @var{what}, void *@var{buffer}, size_t *@var{nbytes})
fixme
@end deftypefun
@deftypefun const char *gcry_cipher_algo_name (int @var{algo})
@code{gcry_cipher_algo_name} returns a string with the name of the
cipher algorithm @var{algo}. If the algorithm s not known or an other
error occured, an empty string is return. This function will never
return @code{NULL}.
@end deftypefun
@deftypefun int gcry_cipher_map_name (const char *@var{name})
@code{gcry_cipher_map_name} returns the algorithm identifier for the
cipher algorithm described by the string @var{name}. If this algorithm
is not available @code{0} is returned.
@end deftypefun
@deftypefun int gcry_cipher_mode_from_oid (const char *@var{string})
Return the cipher mode associated with an @acronym{ASN.1} object
identifier. The object identifier is expected to be in the
@acronym{IETF}-style dotted decimal notation. The function returns
@code{0} for an unknown object identifier or when no mode is associated
with it.
@end deftypefun
@c ******************************************
@c ******* cipher en/decrypt **************
@c ******************************************
@deftypefun int gcry_cipher_encrypt (GCRY_CIPHER_HD @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.
Overlapping buffers are not allowed.
@end deftypefun
@deftypefun int gcry_cipher_decrypt (GCRY_CIPHER_HD @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 decrypt the data.
This function can either work in place or with two buffers.
Overlapping buffers are not allowed.
@end deftypefun
@c **********************************************************
@c ******************* Hash Functions *********************
@c **********************************************************
@node Hash Functions
@chapter Hash Functions
How to use cryptographic hash functions.
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_open</refname>
@c <refname>gcry_md_enable</refname>
@c <refname>gcry_md_close</refname>
@c <refpurpose>create and destroy a message digest context</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>GCRY_MD_HD <function>gcry_md_open</function></funcdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c <paramdef>unsigned int <parameter>flags</parameter></paramdef>
@c </funcprototype>
@c <funcprototype>
@c <funcdef>void <function>gcry_md_enable</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c </funcprototype>
@c <funcprototype>
@c <funcdef>void <function>gcry_md_close</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_open</secondary>
@c </indexterm>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_enable</secondary>
@c </indexterm>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_close</secondary>
@c </indexterm>
@c <function>gcry_md_open</function> creates the context required for
@c the message digest functions. The hash algorithm may optionally be
@c specified. It is possible to use these functions as MAC functons; therefore
@c the flag <literal/GCRY_MD_FLAG_HMAC/ must be given along with the
@c hash functions. Other MAC algorithms than HMAC are currently not
@c supported. The key for the MAC must be set using
@c the <function>gcry_md_setkey</> function.
@c <function>gcry_md_close</function> releases all resources associated
@c with the context.
@c <function>gcry_md_enable</function> may be used to enable hash
@c algorithms. This function may be used multiple times to create
@c a hash context for multiple algorithms. Adding an already enabled algorithm
@c has no effect. A algorithm must be enabled prios to calculate hash
@c algorithms.
@c </para>
@c </refentry>
@c
@c <!--**********************************************
@c *********** md_copy *****************************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_copy</refname>
@c <refpurpose>create and copy of a message digest context</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>GCRY_MD_HD <function>gcry_md_copy</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_copy</secondary>
@c </indexterm>
@c <function>gcry_md_copy</function> creates an excat copy of the given context.
@c This is useful to calculate hashes with a common initial part of the
@c plaintext.
@c </para>
@c </refentry>
@c
@c <!--**********************************************
@c *********** md_reset ***************************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_reset</refname>
@c <refpurpose>reset a message digest context</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>void <function>gcry_md_reset</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_reset</secondary>
@c </indexterm>
@c <function>gcry_md_reset</function> is used to reuse a message context
@c without the overhead of an open and close operation.
@c </para>
@c </refentry>
@c
@c
@c <!--**********************************************
@c *********** md_ctl *****************************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_ctl</refname>
@c <refname>gcry_md_final</refname>
@c <refname>gcry_md_setkey</refname>
@c <refpurpose>perform special operations on a digest context</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_ctl</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c <paramdef>int <parameter>cmd</parameter></paramdef>
@c <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
@c <paramdef>size_t <parameter>buflen</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_ctl</secondary>
@c </indexterm>
@c <function>gcry_md_ctl</function> is a multi-purpose function
@c to control the behaviour of all gcry_md functions or one instance
@c of it.
@c </para>
@c <para>
@c Currently defined values for <parameter>cmd</> are:
@c </para>
@c <para>
@c <literal>GCRYCTL_FINALIZE</> and the convenience macro
@c <function>gcry_md_final(a)</>
@c </para>
@c <para>
@c <literal>GCRYCTL_SET_KEY</> and the convenience macro
@c <function>gcry_md_setkey(a)</>. This is used to turn these
@c hash functions into MAC functions. The key may be any string
@c of the speicified length. The type of the MAC is determined
@c by special flags set with the open function.
@c NEW: There is now a function to do this
@c </para>
@c </refentry>
@c
@c <!--**********************************************
@c *********** md_write, putc *********************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_write</refname>
@c <refname>gcry_md_putc</refname>
@c <refpurpose>calculate the message digest of a buffer</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_write</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c <paramdef>unsigned char * <parameter>buffer</parameter></paramdef>
@c <paramdef>size_t <parameter>buflen</parameter></paramdef>
@c </funcprototype>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_putc</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c <paramdef>int <parameter>c</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_write</secondary></indexterm>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_putc</secondary></indexterm>
@c <function>gcry_md_write</function> is used to actually calulate the message
@c digest of a buffer. This function updates the internal state of the message
@c digest.
@c </para>
@c <para>
@c <function>gcry_md_putc</function> is a macro which is used to update
@c the message digest by one byte. this is the preferred way to calculate
@c a digest if only a few bytes at a time are available.
@c </para>
@c </refentry>
@c
@c <!--**********************************************
@c *********** md_read *****************************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_read</refname>
@c <refpurpose>read out the message digest</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>unsigned char * <function>gcry_md_read</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_read</secondary>
@c </indexterm>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_putc</secondary>
@c </indexterm>
@c <function>gcry_md_read</function> returns the message digest after finalizing
@c the calculation. This function may be used as often as required but it
@c will alwas return the same value for one handle. The returned message
@c digest is allocated within the message context and therefore valid until
@c the conext is released. <parameter>algo</> may be given as 0 to return the
@c only enbaled message digest or it may specify one of the enabled algorithms.
@c The function will return NULL if the algorithm has not been enabled.
@c </para>
@c </refentry>
@c
@c
@c <!--**********************************************
@c *********** md_info ****************************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_info</refname>
@c <refpurpose>get information about a handle</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_info</function></funcdef>
@c <paramdef>GCRY_MD_HD <parameter>h</parameter></paramdef>
@c <paramdef>int <parameter>what</parameter></paramdef>
@c <paramdef>void * <parameter>buffer</parameter></paramdef>
@c <paramdef>size_t <parameter>buflen</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_info</secondary>
@c </indexterm>
@c <function>gcry_md_info</function> returns some information about the
@c handle or an global parameter.
@c </para>
@c <para>
@c The only defined value for <parameter>what</> is
@c <literal>GCRYCTL_IS_SECURE</literal> to return whether the handle
@c has been allocated in secure memory. Buffer and buflen are not needed
@c in this cases. The convenience macro <function>gcry_md_is_secure(a)</>
@c may be also used for this purpose.
@c </para>
@c </refentry>
@c
@c
@c <!--**********************************************
@c *********** md_algo_info ***********************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_algo_info</refname>
@c <refname>gcry_md_test_algo</refname>
@c <refname>gcry_md_get_algo_dlen</refname>
@c <refpurpose>get information about an algorithm</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_algo_info</function></funcdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c <paramdef>int <parameter>what</parameter></paramdef>
@c <paramdef>void * <parameter>buffer</parameter></paramdef>
@c <paramdef>size_t <parameter>buflen</parameter></paramdef>
@c </funcprototype>
@c <funcprototype>
@c <funcdef>unsigned int <function>gcry_md_get_algo_dlen</function></funcdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_algo_info</secondary>
@c </indexterm>
@c <function>gcry_md_algo_info</function> returns some information about an
@c algorithm. On error the value -1 is return and a more detailed error
@c description is available with <function>gcry_errno</>.
@c </para>
@c <para>
@c The defined values for <parameter>what</> are
@c <literal>GCRYCTL_TEST_ALGO</literal> to return whether the algorithm
@c is supported. Buffer and buflen are not needed
@c in this cases. The convenience macro <function>gcry_md_test_algo(a)</>
@c may be used for this purpose.
@c </para>
@c <para>
@c <literal>GCRYCTL_GET_ASNOID</literal> to return whether the ASN.1
@c object identifier. IF buffer is specified as NULL, only the required
@c length for the buffer is returned.
@c </para>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_get_algo_dlen</secondary>
@c </indexterm>
@c <function>gcry_md_get_algo_dlen</function> returns the length of the
@c digest for a given algorithm in bytes.
@c </para>
@c </refentry>
@c
@c
@c <!--**********************************************
@c *********** md_algo_name, map_name *************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_algo_name</refname>
@c <refname>gcry_md_map_name</refname>
@c <refpurpose>map algorithm to string</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>const char * <function>gcry_md_algo_name</function></funcdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c </funcprototype>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_map_name</function></funcdef>
@c <paramdef>const char*<parameter>name</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_algo_name</secondary>
@c </indexterm>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_map_name</secondary>
@c </indexterm>
@c These both functions are used to map a string with the algorithm name to
@c the internal algorithm identifier value and vice versa.
@c </para>
@c <para>
@c <function>gcry_md_algo_name</> never returns NULL even in cases where the
@c algorithm string is not available. Instead a string consisting of a
@c single question mark is returned. Do not use this function to test
@c for the existence of an algorithm.
@c </para>
@c <para>
@c <function>gcry_md_map_name</> returns 0 if the algorithm is not known
@c to &libgcrypt;.
@c </para>
@c </refentry>
@c
@c
@c
@c <!--**********************************************
@c *********** md_hash_buffer *********************
@c ***********************************************-->
@c <refentry>
@c <refnamediv>
@c <refname>gcry_md_hash_buffer</refname>
@c <refpurpose>fast message calculation</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>int <function>gcry_md_hash_buffer</function></funcdef>
@c <paramdef>int <parameter>algo</parameter></paramdef>
@c <paramdef>char * <parameter>digest</parameter></paramdef>
@c <paramdef>const char * <parameter>buffer</parameter></paramdef>
@c <paramdef>size_t <parameter>buflen</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>hash functions</primary>
@c <secondary>gcry_md_hash_buffer</secondary>
@c </indexterm>
@c <function>gcry_md_hash_buffer</function> is a shortcut function
@c to calculate a message digest of a buffer. This function does not require
@c a context and immediatley returns the message digest.
@c <parameter>digest</> must be string large enough to hold the digest
@c given by algo. This length may be obtained by using the function
@c <function>gcry_md_get_algo_dlen</> but in most cases it will be a statically
@c allocated buffer.
@c </para>
@c </refentry>
@c
@c
@c **********************************************************
@c ******************* Public Key *************************
@c **********************************************************
@node Public Key Functions
@chapter Public Key Functions
How to use asymmetric encryption.
@c <refentry>
@c <refnamediv>
@c <refname>gcry_pk_encrypt</refname>
@c <refpurpose>do a public key encryption</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>int <function>gcry_pk_encrypt</function></funcdef>
@c <paramdef>GCRY_SEXP *<parameter>result</parameter></paramdef>
@c <paramdef>GCRY_SEXP <parameter>data</parameter></paramdef>
@c <paramdef>GCRY_SEXP <parameter>pkey</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>public key functions</primary>
@c <secondary>gcry_pk_encrypt</secondary>
@c </indexterm>
@c <function>gcry_pk_encrypt</function> performs public key encryption
@c operations. The caller has to provide a public key as the &sexp;
@c <parameter>pkey</> and <parameter>data</> as a &sexp;
@c with just one MPI in it. The function returns a &sexp; which may
@c be passed tp to pk_decrypt.
@c Later versions of this functions may take more complex input data.
@c
@c Returns: 0 or an errorcode.
@c </para>
@c <literallayout>
@c s_data = (<replaceable/mpi/)
@c s_pkey = <replaceable/key-as-defined-in-sexp_to_key/
@c r_ciph = (enc-val
@c (<replaceable/algo/
@c (<replaceable/param_name1/ <replaceable/mpi/)
@c ...
@c (<replaceable/param_namen/ <replaceable/mpi/)
@c ))
@c </literallayout>
@c </refentry>
@c
@c
@c <!--
@c int gcry_pk_decrypt( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
@c
@c
@c
@c int gcry_pk_sign( GCRY_SEXP *result, GCRY_SEXP data, GCRY_SEXP skey );
@c int gcry_pk_verify( GCRY_SEXP sigval, GCRY_SEXP data, GCRY_SEXP pkey );
@c int gcry_pk_testkey( GCRY_SEXP key );
@c int gcry_pk_genkey( GCRY_SEXP *r_key, GCRY_SEXP s_parms );
@c
@c int gcry_pk_ctl( int cmd, void *buffer, size_t buflen);
@c int gcry_pk_algo_info( int algo, int what, void *buffer, size_t *nbytes);
@c #define gcry_pk_test_algo(a) \
@c gcry_pk_algo_info( (a), GCRYCTL_TEST_ALGO, NULL, NULL )
@c
@c const char *gcry_pk_algo_name( int algo );
@c int gcry_pk_map_name( const char* name );
@c unsigned int gcry_pk_get_nbits( GCRY_SEXP key );
@c -->
@c
@c **********************************************************
@c ******************* Random *****************************
@c **********************************************************
@node Random Numbers
@chapter Random Numbers
@deftypefun void gcry_randomize (unsigned char *@var{buffer}, size_t @var{length}, enum gcry_random_level @var{level})
Fill @var{buffer} with @var{length} random bytes using a random quality
as defined by @var{level}.
@end deftypefun
@deftypefun void *gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
Allocate a memory block consisting of @var{nbytes} fresh random bytes
using a random quality as defined by @var{level}.
@end deftypefun
@deftypefun void *gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
Allocate a memory block consisting of @var{nbytes} fresh random bytes
using a random quality as defined by @var{level}. This fuinction
differs from @code{gcry_random_bytes} in that the returned buffer is
allcated in a ``secure'' area of the memory.
@end deftypefun
@c **********************************************************
@c ******************* Utilities **************************
@c **********************************************************
@node Utilities
@chapter Utilities
Helper functions.
@c <funcprototype>
@c <funcdef>int <function>gcry_control</function></funcdef>
@c <paramdef>enum gcry_ctl_cmds<parameter>cmd</parameter></paramdef>
@c <paramdef><parameter>...</parameter></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>gcry_control</primary></indexterm>
@c This function is used to control various aspects of &libgcrypt;
@c FIXME: Explain all commands here.
@c </para>
@c </refentry>
@c
@c
@c
@c
@c
@c <refentry>
@c <refnamediv>
@c <refname>gcry_set_allocation_handler</refname>
@c <refname>gcry_set_outofcore_handler</refname>
@c <refpurpose>Use application defined malloc functions</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>void <function>gcry_set_allocation_handler</></funcdef>
@c <paramdef>void *(*<parameter>alloc_func</>)(size_t n)</paramdef>
@c <paramdef>void *(*<parameter>alloc_secure_func</>)(size_t n)</paramdef>
@c <paramdef>int (*<parameter>is_secure_func</>)(const void *p)</paramdef>
@c <paramdef>void *(*<parameter>realloc_func</>)(void *p, size_t n)</paramdef>
@c <paramdef>void (*<parameter>free_func</>)(void *p)</paramdef>
@c </funcprototype>
@c <funcprototype>
@c <funcdef>void <function>gcry_set_outofcore_handler</></funcdef>
@c
@c <paramdef>int (*<parameter>h</>)( void*, size_t, unsigned int ),
@c void *opaque )</paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>gcry_set_allocation_handler</primary></indexterm>
@c <indexterm><primary>gcry_set_outofcore_handler</primary></indexterm>
@c
@c FIXME
@c </para>
@c </refentry>
@c
@c
@c <refentry>
@c <refnamediv>
@c <refname>gcry_set_fatalerror_handler</refname>
@c <refpurpose>change the default fatal error handler</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>void <function>gcry_set_fatalerror_handler</></funcdef>
@c <paramdef>void (*<parameter>func</>)(
@c void *, int, const char*)</paramdef>
@c <paramdef>void *<parameter>opaque</></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>gcry_set_fatalerror_handler</primary></indexterm>
@c At certain places the &libgcrypt; may need to call a fatal error fucntion
@c which does terminate the process. To allow an application to do
@c some emergency cleanup, it may register a fatal error handler with
@c the library. This handler is assumed to terminate the application;
@c however if it returns &libgcrypt; will abort anyway.
@c </para>
@c <para>
@c The handler is called with the opaque value registered here, an
@c errorcode from &libgcrypt; and some descriptive text string.
@c </para>
@c </refentry>
@c
@c
@c <refentry>
@c <refnamediv>
@c <refname>gcry_set_gettext_handler</refname>
@c <refpurpose>Change the default gettext function</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>void <function>gcry_set_gettext_handler</></funcdef>
@c <paramdef>const char *(*<parameter>func</>)(const char*)</paramdef>
@c <paramdef>void *<parameter>opaque</></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>gcry_set_log_handler</primary></indexterm>
@c FIXME!!
@c </para>
@c </refentry>
@c
@c
@c
@c <!--
@c void gcry_set_log_handler( void (*f)(void*,int, const char*, va_list ),
@c void
@c *opaque
@c );
@c -->
@c
@c <refentry>
@c <refnamediv>
@c <refname>gcry_set_log_handler</refname>
@c <refpurpose>Change the default logging function</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>void <function>gcry_set_log_handler</></funcdef>
@c <paramdef>void (*<parameter>func</>)
@c (void*, int, const char*, va_list)</paramdef>
@c <paramdef>void *<parameter>opaque</></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>gcry_set_log_handler</primary></indexterm>
@c &libgcrypt; has it;s own logging functions. Applications which
@c need to use their own, should provide a log function to &libgcrypt;
@c so that it will use this function instead.
@c
@c Fixme: Describe how this is intended to work.
@c </para>
@c </refentry>
@c
@c <!--
@c void *gcry_malloc( size_t n );
@c void *gcry_calloc( size_t n, size_t m );
@c void *gcry_malloc_secure( size_t n );
@c void *gcry_calloc_secure( size_t n, size_t m );
@c void *gcry_realloc( void *a, size_t n );
@c void *gcry_xmalloc( size_t n );
@c void *gcry_xcalloc( size_t n, size_t m );
@c void *gcry_xmalloc_secure( size_t n );
@c void *gcry_xcalloc_secure( size_t n, size_t m );
@c void *gcry_xrealloc( void *a, size_t n );
@c char *gcry_xstrdup( const char * a);
@c void gcry_free( void *a );
@c int gcry_is_secure( const void *a );
@c -->
@c
@c <refentry>
@c <refnamediv>
@c <refname>gcry_malloc</refname>
@c <refname>gcry_calloc</refname>
@c <refname>gcry_malloc_secure</refname>
@c <refname>gcry_calloc_secure</refname>
@c <refname>gcry_realloc</refname>
@c <refname>gcry_xmalloc</refname>
@c <refname>gcry_xcalloc</refname>
@c <refname>gcry_xmalloc_secure</refname>
@c <refname>gcry_xcalloc_secure</refname>
@c <refname>gcry_xrealloc</refname>
@c <refname>gcry_xstrdup</refname>
@c
@c <!-- WORk WORK -->
@c <refname>gcry_malloc</refname>
@c <refname>gcry_malloc</refname>
@c
@c <refpurpose>Change the default logging function</refpurpose>
@c </refnamediv>
@c
@c <refsynopsisdiv>
@c <funcsynopsis>
@c <funcsynopsisinfo>
@c #include <gcrypt.h>
@c </funcsynopsisinfo>
@c <funcprototype>
@c <funcdef>void <function>gcry_set_log_handler</></funcdef>
@c <paramdef>void (*<parameter>func</>)
@c (void*, int, const char*, va_list)</paramdef>
@c <paramdef>void *<parameter>opaque</></paramdef>
@c </funcprototype>
@c </funcsynopsis>
@c </refsynopsisdiv>
@c
@c <refsect1><title>Description</title>
@c <para>
@c <indexterm><primary>gcry_set_log_handler</primary></indexterm>
@c &libgcrypt; has it;s own logging functions. Applications which
@c need to use their own, should provide a log function to &libgcrypt;
@c so that it will use this function instead.
@c
@c Fixme: Describe how this is intended to work.
@c </para>
@c </refentry>
@c
@c
@c **********************************************************
@c ******************* Errors ****************************
@c **********************************************************
@node Error Handling
@chapter 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 cancelling 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.
@end menu
@node Error values
@section Error values
Errors are return as an @code{int}
Except for the EOF and No_Error cases an application should always
use the constants. Possible values are:
@table @code
@item GCRYERR_EOF
This value indicates the end of a list, buffer or file and is defined to have
the value @code{-1}.
@item GCRYERR_SUCCESS
This value indicates success. The value of this error is @code{0}.
@item 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 seperate error value for this type of problem.
@end table
@node Error strings
@section Error strings
@deftypefun {const char *} gcry_strerror (@w{int @var{err}})
The function @code{gcry_strerror} returns a pointer to a statically
allocated string containing a description of the error with the error
value @var{err}. This string can be used to output a diagnostic
message to the user.
@end deftypefun
@c **********************************************************
@c ******************* Appendices *************************
@c **********************************************************
@include lgpl.texi
@include gpl.texi
@include fdl.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function and Data Index
@unnumbered Function and Data Index
@printindex fn
@summarycontents
@contents
@bye
