PageRenderTime 5ms CodeModel.GetById 6ms app.highlight 111ms RepoModel.GetById 1ms app.codeStats 1ms

/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.texi

https://bitbucket.org/lkalif/emerald-snowglobe
Unknown | 3756 lines | 2904 code | 852 blank | 0 comment | 0 complexity | 24b2b163fa8a26f44910b45e9aff279d MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1\input texinfo                  @c -*- Texinfo -*-
   2@c %**start of header
   3@setfilename gcrypt.info
   4@include version.texi
   5@settitle The Libgcrypt Reference Manual
   6@c Unify some of the indices.
   7@syncodeindex tp fn
   8@syncodeindex pg fn
   9@c %**end of header
  10@copying
  11This manual is for Libgcrypt
  12(version @value{VERSION}, @value{UPDATED}),
  13which is GNU's library of cryptographic building blocks.
  14
  15Copyright @copyright{} 2000, 2002, 2003, 2004 Free Software Foundation, Inc.
  16
  17@quotation
  18Permission is granted to copy, distribute and/or modify this document
  19under the terms of the GNU General Public License as published by the
  20Free Software Foundation; either version 2 of the License, or (at your
  21option) any later version. The text of the license can be found in the
  22section entitled ``Copying''.
  23@end quotation
  24@end copying
  25
  26@dircategory GNU Libraries
  27@direntry
  28* libgcrypt: (gcrypt).  Cryptographic function library.
  29@end direntry
  30
  31
  32
  33@c
  34@c Titlepage
  35@c
  36@setchapternewpage odd
  37@titlepage
  38@title The Libgcrypt Reference Manual
  39@subtitle Version @value{VERSION}
  40@subtitle @value{UPDATED}
  41@author Werner Koch (@email{wk@@gnupg.org})
  42@author Moritz Schulte (@email{mo@@g10code.com})
  43
  44@page
  45@vskip 0pt plus 1filll
  46@insertcopying
  47@end titlepage
  48
  49
  50@summarycontents
  51@contents
  52@page
  53
  54
  55@ifnottex
  56@node Top
  57@top The Libgcrypt Library
  58@insertcopying
  59@end ifnottex
  60
  61
  62@menu
  63* Introduction::                 What is @acronym{Libgcrypt}.
  64* Preparation::                  What you should do before using the library.
  65* Generalities::                 General library functions and data types.
  66* Handler Functions::            Working with handler functions.
  67* Symmetric cryptography::       How to use symmetric cryptography.
  68* Hashing::                      How to use hashing.
  69* Public Key cryptography (I)::  How to use public key cryptography.
  70* Public Key cryptography (II):: How to use public key cryptography, alternatively.
  71* Random Numbers::               How to work with random numbers.
  72* S-expressions::                How to manage S-expressions.
  73* MPI library::                  How to work with multi-precision-integers.
  74* Utilities::                    Utility functions.
  75
  76Appendices
  77
  78* Library Copying::             The GNU Lesser General Public License
  79                                says how you can copy and share `Libgcrypt'.
  80* Copying::                     The GNU General Public License says how you
  81                                can copy and share some parts of `Libgcrypt'.
  82
  83Indices
  84
  85* Concept Index::               Index of concepts and programs.
  86* Function and Data Index::     Index of functions, variables and data types.
  87
  88@detailmenu
  89 --- The Detailed Node Listing ---
  90
  91Introduction
  92* Getting Started::             How to use this manual.
  93* Features::                    A glance at @acronym{Libgcrypt}'s features.
  94* Overview::                    Overview about the library.
  95
  96Preparation
  97* Header::                              What header file you need to include.
  98* Building sources::                    How to build sources using the library.
  99* Building sources using Automake::     How to build sources with the help of Automake.
 100* Initializing the library::            How to initialize the library.
 101* Multi Threading::                     How @acronym{Libgcrypt} can be used in a MT environment.
 102
 103Generalities
 104* Controlling the library::     Controlling @acronym{Libgcrypt}'s behavior.
 105* Modules::                     Description of extension modules.
 106* Error Handling::              Error codes and such.
 107
 108Handler Functions
 109* Progress handler::            Using a progress handler function.
 110* Allocation handler::          Using special memory allocation functions.
 111* Error handler::               Using error handler functions.
 112* Logging handler::             Using a special logging function.
 113
 114Symmetric cryptography
 115* Available ciphers::           List of ciphers supported by the library.
 116* Cipher modules::              How to work with cipher modules.
 117* Available cipher modes::      List of cipher modes supported by the library.
 118* Working with cipher handles:: How to perform operations related to cipher handles.
 119* General cipher functions::    General cipher functions independent of cipher handles.
 120
 121Hashing
 122* Available hash algorithms::           List of hash algorithms supported by the library.
 123* Hash algorithm modules::              How to work with hash algorithm modules.
 124* Working with hash algorithms::        List of functions related to hashing.
 125
 126Public Key cryptography (I)
 127* Used S-expressions::                    Introduction into the used S-expression.
 128* Available algorithms::                  Algorithms supported by the library.
 129* Public key modules::                    How to work with public key modules.
 130* Cryptographic Functions::               Functions for performing the cryptographic actions.
 131* General public-key related Functions::  General functions, not implementing any cryptography.
 132
 133Public Key cryptography (II)
 134* Available asymmetric algorithms:: List of algorithms supported by the library.
 135* Working with sets of data::       How to work with sets of data.
 136* Working with handles::            How to use handles.
 137* Working with keys::               How to work with keys.
 138* Using cryptographic functions::   How to perform cryptographic operations.
 139* Handle-independent functions::    General functions independent of handles.
 140
 141Random Numbers
 142* Quality of random numbers::   @acronym{Libgcrypt} uses different quality levels.
 143* Retrieving random numbers::   How to retrieve random numbers.
 144
 145S-expressions
 146* Data types for S-expressions::   Data types related with S-expressions.
 147* Working with S-expressions::     How to work with S-expressions.
 148
 149MPI library
 150* Data types::                  MPI related data types.
 151* Basic functions::             First steps with MPI numbers.
 152* MPI formats::                 External representation of MPIs.
 153* Calculations::                Performing MPI calculations.
 154* Comparisons::                 How to compare MPI values.
 155* Bit manipulations::           How to access single bits of MPI values.
 156* Miscellaneous::               Miscellaneous MPI functions.
 157
 158Utilities
 159* Memory allocation::           Functions related with memory allocation.
 160
 161@end detailmenu
 162
 163@end menu
 164
 165
 166
 167@c **********************************************************
 168@c *******************  Introduction  ***********************
 169@c **********************************************************
 170@node Introduction
 171@chapter Introduction
 172`@acronym{Libgcrypt}' is a library providing cryptographic building blocks.
 173
 174@menu
 175* Getting Started::             How to use this manual.
 176* Features::                    A glance at @acronym{Libgcrypt}'s features.
 177* Overview::                    Overview about the library.
 178@end menu
 179
 180@node Getting Started
 181@section Getting Started
 182
 183This manual documents the `@acronym{Libgcrypt}' library application programming
 184interface (API).  All functions and data types provided by the library
 185are explained.
 186
 187@noindent
 188The reader is assumed to possess basic knowledge about applied
 189cryptography.
 190
 191This manual can be used in several ways.  If read from the beginning
 192to the end, it gives a good introduction into the library and how it
 193can be used in an application.  Forward references are included where
 194necessary.  Later on, the manual can be used as a reference manual to
 195get just the information needed about any particular interface of the
 196library.  Experienced programmers might want to start looking at the
 197examples at the end of the manual, and then only read up those parts
 198of the interface which are unclear.
 199
 200
 201@node Features
 202@section Features
 203
 204`Libgcrypt' might have a couple of advantages over other libraries doing
 205a similar job.
 206
 207@table @asis
 208@item It's Free Software
 209Anybody can use, modify, and redistribute it under the terms of the GNU
 210Lesser General Public License (@pxref{Library Copying}).  Note, that
 211some parts (which are not needed on a GNU or GNU/Linux system) are
 212subject to the terms of the GNU General Public License
 213(@pxref{Copying}); please see the README file of the distribution for of
 214list of these parts.
 215
 216@item It encapsulates the low level cryptography
 217`@acronym{Libgcrypt}' provides a high level interface to cryptographic building
 218blocks using an extendable and flexible API.
 219
 220@end table
 221
 222@node Overview
 223@section Overview
 224
 225@noindent
 226The `@acronym{Libgcrypt}' library is fully thread-safe, where it makes
 227sense to be thread-safe.  An exception for thread-safety are some
 228cryptographic functions that modify a certain context stored in
 229handles.  If the user really intents to use such functions from
 230different threads on the same handle, he has to take care of the
 231serialization of such functions himself.  If not described otherwise,
 232every function is thread-safe.
 233
 234@acronym{Libgcrypt} depends on the library `libgpg-error', which
 235contains common error handling related code for GnuPG components.
 236
 237@c **********************************************************
 238@c *******************  Preparation  ************************
 239@c **********************************************************
 240@node Preparation
 241@chapter Preparation
 242
 243To use `@acronym{Libgcrypt}', you have to perform some changes to your
 244sources and the build system.  The necessary changes are small and
 245explained in the following sections.  At the end of this chapter, it
 246is described how the library is initialized, and how the requirements
 247of the library are verified.
 248
 249@menu
 250* Header::                      What header file you need to include.
 251* Building sources::            How to build sources using the library.
 252* Building sources using Automake::  How to build sources with the help of Automake.
 253* Initializing the library::    How to initialize the library.
 254* Multi Threading::             How @acronym{Libgcrypt} can be used in a MT environment.
 255@end menu
 256
 257
 258@node Header
 259@section Header
 260
 261All interfaces (data types and functions) of the library are defined
 262in the header file `gcrypt.h'.  You must include this in all source
 263files using the library, either directly or through some other header
 264file, like this:
 265
 266@example
 267#include <gcrypt.h>
 268@end example
 269
 270The name space of `@acronym{Libgcrypt}' is @code{gcry_*} for function
 271and type names and @code{GCRY*} for other symbols.  In addition the
 272same name prefixes with one prepended underscore are reserved for
 273internal use and should never be used by an application.  Furthermore
 274`libgpg-error' defines functions prefixed with `gpg_' and preprocessor
 275symbols prefixed with `GPG_'.  Note that @acronym{Libgcrypt} uses
 276libgpg-error, which uses @code{gpg_err_*} as name space for function
 277and type names and @code{GPG_ERR_*} for other symbols, including all
 278the error codes.
 279
 280@node Building sources
 281@section Building sources
 282
 283If you want to compile a source file including the `gcrypt.h' header
 284file, you must make sure that the compiler can find it in the
 285directory hierarchy.  This is accomplished by adding the path to the
 286directory in which the header file is located to the compilers include
 287file search path (via the @option{-I} option).
 288
 289However, the path to the include file is determined at the time the
 290source is configured.  To solve this problem, `@acronym{Libgcrypt}' ships with a small
 291helper program @command{libgcrypt-config} that knows the path to the
 292include file and other configuration options.  The options that need
 293to be added to the compiler invocation at compile time are output by
 294the @option{--cflags} option to @command{libgcrypt-config}.  The following
 295example shows how it can be used at the command line:
 296
 297@example
 298gcc -c foo.c `libgcrypt-config --cflags`
 299@end example
 300
 301Adding the output of @samp{libgcrypt-config --cflags} to the compilers
 302command line will ensure that the compiler can find the `@acronym{Libgcrypt}' header
 303file.
 304
 305A similar problem occurs when linking the program with the library.
 306Again, the compiler has to find the library files.  For this to work,
 307the path to the library files has to be added to the library search path
 308(via the @option{-L} option).  For this, the option @option{--libs} to
 309@command{libgcrypt-config} can be used.  For convenience, this option
 310also outputs all other options that are required to link the program
 311with the `@acronym{Libgcrypt}' libraries (in particular, the @samp{-lgcrypt}
 312option).  The example shows how to link @file{foo.o} with the `@acronym{Libgcrypt}'
 313library to a program @command{foo}.
 314
 315@example
 316gcc -o foo foo.o `libgcrypt-config --libs`
 317@end example
 318
 319Of course you can also combine both examples to a single command by
 320specifying both options to @command{libgcrypt-config}:
 321
 322@example
 323gcc -o foo foo.c `libgcrypt-config --cflags --libs`
 324@end example
 325
 326@node Building sources using Automake
 327@section Building sources using Automake
 328
 329It is much easier if you use GNU Automake instead of writing your own
 330Makefiles.  If you do that you do not have to worry about finding and
 331invoking the @command{libgcrypt-config} script at all.
 332@acronym{Libgcrypt} provides an extension to Automake that does all
 333the work for you.
 334
 335@c A simple macro for optional variables.
 336@macro ovar{varname}
 337@r{[}@var{\varname\}@r{]}
 338@end macro
 339@defmac AM_PATH_LIBGCRYPT (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
 340Check whether @acronym{Libgcrypt} (at least version
 341@var{minimum-version}, if given) exists on the host system.  If it is
 342found, execute @var{action-if-found}, otherwise do
 343@var{action-if-not-found}, if given.
 344
 345Additionally, the function defines @code{LIBGCRYPT_CFLAGS} to the
 346flags needed for compilation of the program to find the
 347@file{gcrypt.h} header file, and @code{LIBGCRYPT_LIBS} to the linker
 348flags needed to link the program to the @acronym{Libgcrypt} library.
 349@end defmac
 350
 351You can use the defined Autoconf variables like this in your
 352@file{Makefile.am}:
 353
 354@example
 355AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS)
 356LDADD = $(LIBGCRYPT_LIBS)
 357@end example
 358
 359@node Initializing the library
 360@section Initializing the library
 361
 362It is often desirable to check that the version of `@acronym{Libgcrypt}' used is
 363indeed one which fits all requirements.  Even with binary compatibility
 364new features may have been introduced but due to problem with the
 365dynamic linker an old version is actually used.  So you may want to
 366check that the version is okay right after program startup.
 367
 368@deftypefun const char *gcry_check_version (const char *@var{req_version})
 369
 370The function @code{gcry_check_version} has three purposes.  It can be
 371used to retrieve the version number of the library.  In addition it
 372can verify that the version number is higher than a certain required
 373version number.
 374
 375In either case, the function initializes some sub-systems, and for
 376this reason alone it must be invoked early in your program, before you
 377make use of the other functions of @acronym{Libgcrypt}.
 378@end deftypefun
 379
 380@node Multi Threading
 381@section Multi Threading
 382
 383As mentioned earlier, the `@acronym{Libgcrypt}' library is 
 384thread-safe if you adhere to the following requirements:
 385
 386@itemize @bullet
 387@item
 388If your application is multi-threaded, you must set the thread support
 389callbacks with the @code{GCRYCTL_SET_THREAD_CBS} command
 390@strong{before} any other function in the library.
 391
 392This is easy enough if you are indeed writing an application using
 393Libgcrypt.  It is rather problematic if you are writing a library
 394instead.  Here are some tips what to do if you are writing a library:
 395
 396If your library requires a certain thread package, just initialize
 397Libgcrypt to use this thread package.  If your library supports multiple
 398thread packages, but needs to be configured, you will have to
 399implement a way to determine which thread package the application
 400wants to use with your library anyway.  Then configure Libgcrypt to use
 401this thread package.
 402
 403If your library is fully reentrant without any special support by a
 404thread package, then you are lucky indeed.  Unfortunately, this does
 405not relieve you from doing either of the two above, or use a third
 406option.  The third option is to let the application initialize Libgcrypt
 407for you.  Then you are not using Libgcrypt transparently, though.
 408
 409As if this was not difficult enough, a conflict may arise if two
 410libraries try to initialize Libgcrypt independently of each others, and
 411both such libraries are then linked into the same application.  To
 412make it a bit simpler for you, this will probably work, but only if
 413both libraries have the same requirement for the thread package.  This
 414is currently only supported for the non-threaded case, GNU Pth and
 415pthread.  Support for more thread packages is easy to add, so contact
 416us if you require it.
 417
 418@item
 419The function @code{gcry_check_version} must be called before any other
 420function in the library, except the @code{GCRYCTL_SET_THREAD_CBS}
 421command (called via the @code{gcry_control} function), because it
 422initializes the thread support subsystem in @acronym{Libgcrypt}.  To
 423achieve this in multi-threaded programs, you must synchronize the
 424memory with respect to other threads that also want to use
 425@acronym{Libgcrypt}.  For this, it is sufficient to call
 426@code{gcry_check_version} before creating the other threads using
 427@acronym{Libgcrypt}@footnote{At least this is true for POSIX threads,
 428as @code{pthread_create} is a function that synchronizes memory with
 429respects to other threads.  There are many functions which have this
 430property, a complete list can be found in POSIX, IEEE Std 1003.1-2003,
 431Base Definitions, Issue 6, in the definition of the term ``Memory
 432Synchronization''.  For other thread packages, more relaxed or more
 433strict rules may apply.}.
 434
 435@item
 436
 437As with the function @code{gpg_strerror}, @code{gcry_strerror} is not
 438thread safe.  You have to use @code{gpg_strerror_r} instead.
 439@end itemize
 440
 441
 442@acronym{Libgcrypt} contains convenient macros, which define the
 443necessary thread callbacks for PThread and for GNU Pth:
 444
 445@table @code
 446@item GCRY_THREAD_OPTION_PTH_IMPL
 447
 448This macro defines the following (static) symbols: gcry_pth_init,
 449gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,
 450gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select,
 451gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth.
 452
 453After including this macro, gcry_control() shall be used with a
 454command of GCRYCTL_SET_THREAD_CBS in order to register the thread
 455callback structure named ``gcry_threads_pth''.
 456
 457@item GCRY_THREAD_OPTION_PTHREAD_IMPL
 458
 459This macro defines the following (static) symbols:
 460gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, gcry_mutex_lock,
 461gcry_mutex_unlock, gcry_threads_pthread.
 462
 463After including this macro, gcry_control() shall be used with a
 464command of GCRYCTL_SET_THREAD_CBS in order to register the thread
 465callback structure named ``gcry_threads_pthread''.
 466@end table
 467
 468Note that these macros need to be terminated with a semicolon.  Keep
 469in mind that these are convenient macros for C programmers; C++
 470programmers might have to wrap these macros in an ``extern C'' body.
 471
 472@c **********************************************************
 473@c *******************  General  ****************************
 474@c **********************************************************
 475@node Generalities
 476@chapter Generalities
 477
 478@menu
 479* Controlling the library::     Controlling @acronym{Libgcrypt}'s behavior.
 480* Modules::                     Description of extension modules.
 481* Error Handling::              Error codes and such.
 482@end menu
 483
 484@node Controlling the library
 485@section Controlling the library
 486
 487@deftypefun gcry_error_t gcry_control (enum gcry_ctl_cmds @var{cmd}, ...)
 488
 489This function can be used to influence the general behavior of
 490@acronym{Libgcrypt} in several ways.  Depending on @var{cmd}, more
 491arguments can or have to be provided.
 492
 493@end deftypefun
 494
 495@node Modules
 496@section Modules
 497
 498@acronym{Libgcrypt} supports the use of `extension modules', which
 499implement algorithms in addition to those already built into the
 500library directly.
 501
 502@deftp {Data type} gcry_module_t
 503This data type represents a `module'.
 504@end deftp
 505
 506Functions registering modules provided by the user take a `module
 507specification structure' as input and return a value of
 508@code{gcry_module_t} and an ID that is unique in the modules'
 509category.  This ID can be used to reference the newly registered
 510module.  After registering a module successfully, the new functionality
 511should be able to be used through the normal functions provided by
 512@acronym{Libgcrypt} until it is unregistered again.
 513
 514@c **********************************************************
 515@c *******************  Errors  ****************************
 516@c **********************************************************
 517@node Error Handling
 518@section Error Handling
 519
 520Many functions in @acronym{Libgcrypt} can return an error if they
 521fail.  For this reason, the application should always catch the error
 522condition and take appropriate measures, for example by releasing the
 523resources and passing the error up to the caller, or by displaying a
 524descriptive message to the user and cancelling the operation.
 525
 526Some error values do not indicate a system error or an error in the
 527operation, but the result of an operation that failed properly.  For
 528example, if you try to decrypt a tempered message, the decryption will
 529fail.  Another error value actually means that the end of a data
 530buffer or list has been reached.  The following descriptions explain
 531for many error codes what they mean usually.  Some error values have
 532specific meanings if returned by a certain functions.  Such cases are
 533described in the documentation of those functions.
 534
 535@acronym{Libgcrypt} uses the @code{libgpg-error} library.  This allows
 536to share the error codes with other components of the GnuPG system,
 537and thus pass error values transparently from the crypto engine, or
 538some helper application of the crypto engine, to the user.  This way
 539no information is lost.  As a consequence, @acronym{Libgcrypt} does
 540not use its own identifiers for error codes, but uses those provided
 541by @code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
 542
 543However, @acronym{Libgcrypt} does provide aliases for the functions
 544defined in libgpg-error, which might be preferred for name space
 545consistency.
 546
 547
 548Most functions in @acronym{Libgcrypt} return an error code in the case
 549of failure.  For this reason, the application should always catch the
 550error condition and take appropriate measures, for example by
 551releasing the resources and passing the error up to the caller, or by
 552displaying a descriptive message to the user and canceling the
 553operation.
 554
 555Some error values do not indicate a system error or an error in the
 556operation, but the result of an operation that failed properly.
 557
 558GnuPG components, including Libgcrypt, use an extra library named
 559libgpg-error to provide a common error handling scheme.  For more
 560information on libgpg-error, see the according manual.
 561
 562@menu
 563* Error Values::                The error value and what it means.
 564* Error Sources::               A list of important error sources.
 565* Error Codes::                 A list of important error codes.
 566* Error Strings::               How to get a descriptive string from a value.
 567@end menu
 568
 569
 570@node Error Values
 571@subsection Error Values
 572@cindex error values
 573@cindex error codes
 574@cindex error sources
 575
 576@deftp {Data type} {gcry_err_code_t}
 577The @code{gcry_err_code_t} type is an alias for the
 578@code{libgpg-error} type @code{gpg_err_code_t}.  The error code
 579indicates the type of an error, or the reason why an operation failed.
 580
 581A list of important error codes can be found in the next section.
 582@end deftp
 583
 584@deftp {Data type} {gcry_err_source_t}
 585The @code{gcry_err_source_t} type is an alias for the
 586@code{libgpg-error} type @code{gpg_err_source_t}.  The error source
 587has not a precisely defined meaning.  Sometimes it is the place where
 588the error happened, sometimes it is the place where an error was
 589encoded into an error value.  Usually the error source will give an
 590indication to where to look for the problem.  This is not always true,
 591but it is attempted to achieve this goal.
 592
 593A list of important error sources can be found in the next section.
 594@end deftp
 595
 596@deftp {Data type} {gcry_error_t}
 597The @code{gcry_error_t} type is an alias for the @code{libgpg-error}
 598type @code{gpg_error_t}.  An error value like this has always two
 599components, an error code and an error source.  Both together form the
 600error value.
 601
 602Thus, the error value can not be directly compared against an error
 603code, but the accessor functions described below must be used.
 604However, it is guaranteed that only 0 is used to indicate success
 605(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
 606the error value are set to 0, too.
 607
 608Note that in @acronym{Libgcrypt}, the error source is used purely for
 609diagnostic purposes.  Only the error code should be checked to test
 610for a certain outcome of a function.  The manual only documents the
 611error code part of an error value.  The error source is left
 612unspecified and might be anything.
 613@end deftp
 614
 615@deftypefun {gcry_err_code_t} gcry_err_code (@w{gcry_error_t @var{err}})
 616The static inline function @code{gcry_err_code} returns the
 617@code{gcry_err_code_t} component of the error value @var{err}.  This
 618function must be used to extract the error code from an error value in
 619order to compare it with the @code{GPG_ERR_*} error code macros.
 620@end deftypefun
 621
 622@deftypefun {gcry_err_source_t} gcry_err_source (@w{gcry_error_t @var{err}})
 623The static inline function @code{gcry_err_source} returns the
 624@code{gcry_err_source_t} component of the error value @var{err}.  This
 625function must be used to extract the error source from an error value in
 626order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
 627@end deftypefun
 628
 629@deftypefun {gcry_error_t} gcry_err_make (@w{gcry_err_source_t @var{source}}, @w{gcry_err_code_t @var{code}})
 630The static inline function @code{gcry_err_make} returns the error
 631value consisting of the error source @var{source} and the error code
 632@var{code}.
 633
 634This function can be used in callback functions to construct an error
 635value to return it to the library.
 636@end deftypefun
 637
 638@deftypefun {gcry_error_t} gcry_error (@w{gcry_err_code_t @var{code}})
 639The static inline function @code{gcry_error} returns the error value
 640consisting of the default error source and the error code @var{code}.
 641
 642For @acronym{GCRY} applications, the default error source is
 643@code{GPG_ERR_SOURCE_USER_1}.  You can define
 644@code{GCRY_ERR_SOURCE_DEFAULT} before including @file{gcrypt.h} to
 645change this default.
 646
 647This function can be used in callback functions to construct an error
 648value to return it to the library.
 649@end deftypefun
 650
 651The @code{libgpg-error} library provides error codes for all system
 652error numbers it knows about.  If @var{err} is an unknown error
 653number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
 654following functions can be used to construct error values from system
 655errno numbers.
 656
 657@deftypefun {gcry_error_t} gcry_err_make_from_errno (@w{gcry_err_source_t @var{source}}, @w{int @var{err}})
 658The function @code{gcry_err_make_from_errno} is like
 659@code{gcry_err_make}, but it takes a system error like @code{errno}
 660instead of a @code{gcry_err_code_t} error code.
 661@end deftypefun
 662
 663@deftypefun {gcry_error_t} gcry_error_from_errno (@w{int @var{err}})
 664The function @code{gcry_error_from_errno} is like @code{gcry_error},
 665but it takes a system error like @code{errno} instead of a
 666@code{gcry_err_code_t} error code.
 667@end deftypefun
 668
 669Sometimes you might want to map system error numbers to error codes
 670directly, or map an error code representing a system error back to the
 671system error number.  The following functions can be used to do that.
 672
 673@deftypefun {gcry_err_code_t} gcry_err_code_from_errno (@w{int @var{err}})
 674The function @code{gcry_err_code_from_errno} returns the error code
 675for the system error @var{err}.  If @var{err} is not a known system
 676error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
 677@end deftypefun
 678
 679@deftypefun {int} gcry_err_code_to_errno (@w{gcry_err_code_t @var{err}})
 680The function @code{gcry_err_code_to_errno} returns the system error
 681for the error code @var{err}.  If @var{err} is not an error code
 682representing a system error, or if this system error is not defined on
 683this system, the function returns @code{0}.
 684@end deftypefun
 685
 686
 687@node Error Sources
 688@subsection Error Sources
 689@cindex error codes, list of
 690
 691The library @code{libgpg-error} defines an error source for every
 692component of the GnuPG system.  The error source part of an error
 693value is not well defined.  As such it is mainly useful to improve the
 694diagnostic error message for the user.
 695
 696If the error code part of an error value is @code{0}, the whole error
 697value will be @code{0}.  In this case the error source part is of
 698course @code{GPG_ERR_SOURCE_UNKNOWN}.
 699
 700The list of error sources that might occur in applications using
 701@acronym{Libgctypt} is:
 702
 703@table @code
 704@item GPG_ERR_SOURCE_UNKNOWN
 705The error source is not known.  The value of this error source is
 706@code{0}.
 707
 708@item GPG_ERR_SOURCE_GPGME
 709The error source is @acronym{GPGME} itself.
 710
 711@item GPG_ERR_SOURCE_GPG
 712The error source is GnuPG, which is the crypto engine used for the
 713OpenPGP protocol.
 714
 715@item GPG_ERR_SOURCE_GPGSM
 716The error source is GPGSM, which is the crypto engine used for the
 717OpenPGP protocol.
 718
 719@item GPG_ERR_SOURCE_GCRYPT
 720The error source is @code{libgcrypt}, which is used by crypto engines
 721to perform cryptographic operations.
 722
 723@item GPG_ERR_SOURCE_GPGAGENT
 724The error source is @command{gpg-agent}, which is used by crypto
 725engines to perform operations with the secret key.
 726
 727@item GPG_ERR_SOURCE_PINENTRY
 728The error source is @command{pinentry}, which is used by
 729@command{gpg-agent} to query the passphrase to unlock a secret key.
 730
 731@item GPG_ERR_SOURCE_SCD
 732The error source is the SmartCard Daemon, which is used by
 733@command{gpg-agent} to delegate operations with the secret key to a
 734SmartCard.
 735
 736@item GPG_ERR_SOURCE_KEYBOX
 737The error source is @code{libkbx}, a library used by the crypto
 738engines to manage local keyrings.
 739
 740@item GPG_ERR_SOURCE_USER_1
 741@item GPG_ERR_SOURCE_USER_2
 742@item GPG_ERR_SOURCE_USER_3
 743@item GPG_ERR_SOURCE_USER_4
 744These error sources are not used by any GnuPG component and can be
 745used by other software.  For example, applications using
 746@acronym{Libgcrypt} can use them to mark error values coming from callback
 747handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
 748created with @code{gcry_error} and @code{gcry_error_from_errno},
 749unless you define @code{GCRY_ERR_SOURCE_DEFAULT} before including
 750@file{gcrypt.h}.
 751@end table
 752
 753
 754@node Error Codes
 755@subsection Error Codes
 756@cindex error codes, list of
 757
 758The library @code{libgpg-error} defines many error values.  The
 759following list includes the most important error codes.
 760
 761@table @code
 762@item GPG_ERR_EOF
 763This value indicates the end of a list, buffer or file.
 764
 765@item GPG_ERR_NO_ERROR
 766This value indicates success.  The value of this error code is
 767@code{0}.  Also, it is guaranteed that an error value made from the
 768error code @code{0} will be @code{0} itself (as a whole).  This means
 769that the error source information is lost for this error code,
 770however, as this error code indicates that no error occured, this is
 771generally not a problem.
 772
 773@item GPG_ERR_GENERAL
 774This value means that something went wrong, but either there is not
 775enough information about the problem to return a more useful error
 776value, or there is no separate error value for this type of problem.
 777
 778@item GPG_ERR_ENOMEM
 779This value means that an out-of-memory condition occurred.
 780
 781@item GPG_ERR_E...
 782System errors are mapped to GPG_ERR_EFOO where FOO is the symbol for
 783the system error.
 784
 785@item GPG_ERR_INV_VALUE
 786This value means that some user provided data was out of range.
 787
 788@item GPG_ERR_UNUSABLE_PUBKEY
 789This value means that some recipients for a message were invalid.
 790
 791@item GPG_ERR_UNUSABLE_SECKEY
 792This value means that some signers were invalid.
 793
 794@item GPG_ERR_NO_DATA
 795This value means that data was expected where no data was found.
 796
 797@item GPG_ERR_CONFLICT
 798This value means that a conflict of some sort occurred.
 799
 800@item GPG_ERR_NOT_IMPLEMENTED
 801This value indicates that the specific function (or operation) is not
 802implemented.  This error should never happen.  It can only occur if
 803you use certain values or configuration options which do not work,
 804but for which we think that they should work at some later time.
 805
 806@item GPG_ERR_DECRYPT_FAILED
 807This value indicates that a decryption operation was unsuccessful.
 808
 809@item GPG_ERR_WRONG_KEY_USAGE
 810This value indicates that a key is not used appropriately.
 811
 812@item GPG_ERR_NO_SECKEY
 813This value indicates that no secret key for the user ID is available.
 814
 815@item GPG_ERR_UNSUPPORTED_ALGORITHM
 816This value means a verification failed because the cryptographic
 817algorithm is not supported by the crypto backend.
 818
 819@item GPG_ERR_BAD_SIGNATURE
 820This value means a verification failed because the signature is bad.
 821
 822@item GPG_ERR_NO_PUBKEY
 823This value means a verification failed because the public key is not
 824available.
 825
 826@item GPG_ERR_USER_1
 827@item GPG_ERR_USER_2
 828@item ...
 829@item GPG_ERR_USER_16
 830These error codes are not used by any GnuPG component and can be
 831freely used by other software.  Applications using @acronym{Libgcrypt}
 832might use them to mark specific errors returned by callback handlers
 833if no suitable error codes (including the system errors) for these
 834errors exist already.
 835@end table
 836
 837
 838@node Error Strings
 839@subsection Error Strings
 840@cindex error values, printing of
 841@cindex error codes, printing of
 842@cindex error sources, printing of
 843@cindex error strings
 844
 845@deftypefun {const char *} gcry_strerror (@w{gcry_error_t @var{err}})
 846The function @code{gcry_strerror} returns a pointer to a statically
 847allocated string containing a description of the error code contained
 848in the error value @var{err}.  This string can be used to output a
 849diagnostic message to the user.
 850@end deftypefun
 851
 852
 853@deftypefun {const char *} gcry_strsource (@w{gcry_error_t @var{err}})
 854The function @code{gcry_strerror} returns a pointer to a statically
 855allocated string containing a description of the error source
 856contained in the error value @var{err}.  This string can be used to
 857output a diagnostic message to the user.
 858@end deftypefun
 859
 860The following example illustrates the use of the functions described
 861above:
 862
 863@example
 864@{
 865  gcry_cipher_hd_t handle;
 866  gcry_error_t err = 0;
 867
 868  err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
 869  if (err)
 870    @{
 871      fprintf (stderr, "Failure: %s/%s\n",
 872               gcry_strsource (err),
 873               gcry_strerror (err));
 874    @}
 875@}
 876@end example
 877
 878@c **********************************************************
 879@c *******************  General  ****************************
 880@c **********************************************************
 881@node Handler Functions
 882@chapter Handler Functions
 883
 884@acronym{Libgcrypt} makes it possible to install so called `handler functions',
 885which get called by @acronym{Libgcrypt} in case of certain events.
 886
 887@menu
 888* Progress handler::            Using a progress handler function.
 889* Allocation handler::          Using special memory allocation functions.
 890* Error handler::               Using error handler functions.
 891* Logging handler::             Using a special logging function.
 892@end menu
 893
 894@node Progress handler
 895@section Progress handler
 896
 897It is often useful to retrieve some feedback while long running
 898operations are performed.
 899
 900@deftp {Data type} gcry_handler_progress_t
 901Progress handler functions have to be of the type
 902@code{gcry_handler_progress_t}, which is defined as:
 903
 904@code{void (*gcry_handler_progress_t) (void *, const char *, int, int, int)}
 905@end deftp
 906
 907The following function may be used to register a handler function for
 908this purpose.
 909
 910@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
 911
 912This function installs @var{cb} as the `Progress handler' function.
 913@var{cb} must be defined as follows:
 914
 915@example
 916void
 917my_progress_handler (void *@var{cb_data}, const char *@var{what},
 918                     int @var{printchar}, int @var{current}, int @var{total})
 919@{
 920  /* Do something.  */
 921@}
 922@end example
 923
 924A description of the arguments of the progress handler function follows.
 925
 926@table @var
 927@item cb_data
 928The argument provided in the call to @code{gcry_set_progress_handler}.
 929@item what
 930A string identifying the type of the progress output.  The following
 931values for @var{what} are defined:
 932
 933@table @code
 934@item need_entropy
 935Not enough entropy is available.  @var{total} holds the number of
 936required bytes.
 937
 938@item primegen
 939Values for @var{printchar}:
 940@table @code
 941@item \n
 942Prime generated.
 943@item !
 944Need to refresh the pool of prime numbers.
 945@item <, >
 946Number of bits adjusted.
 947@item ^
 948Searching for a generator.
 949@item .
 950Fermat test on 10 candidates failed.
 951@item :
 952Restart with a new random value.
 953@item +
 954Rabin Miller test passed.
 955@end table
 956
 957@end table
 958
 959@end table
 960@end deftypefun
 961
 962@node Allocation handler
 963@section Allocation handler
 964
 965It is possible to make @acronym{Libgcrypt} use special memory
 966allocation functions instead of the built-in ones.
 967
 968Memory allocation functions are of the following types:
 969@deftp {Data type} gcry_handler_alloc_t
 970This type is defined as: @code{void *(*gcry_handler_alloc_t) (size_t n)}.
 971@end deftp
 972@deftp {Data type} gcry_handler_secure_check_t
 973This type is defined as: @code{int *(*gcry_handler_secure_check_t) (const void *)}.
 974@end deftp
 975@deftp {Data type} gcry_handler_realloc_t
 976This type is defined as: @code{void *(*gcry_handler_realloc_t) (void *p, size_t n)}.
 977@end deftp
 978@deftp {Data type} gcry_handler_free_t
 979This type is defined as: @code{void *(*gcry_handler_free_t) (void *)}.
 980@end deftp
 981
 982Special memory allocation functions can be installed with the
 983following function:
 984
 985@deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
 986Install the provided functions and use them instead of the built-in
 987functions for doing memory allocation.
 988@end deftypefun
 989
 990@node Error handler
 991@section Error handler
 992
 993The following functions may be used to register handler functions that
 994are called by @acronym{Libgcrypt} in case certain error conditions
 995occur.
 996
 997@deftp {Data type} gcry_handler_no_mem_t
 998This type is defined as: @code{void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
 999@end deftp
1000@deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
1001This function registers @var{func_no_mem} as `out-of-core handler',
1002which means that it will be called in the case of not having enough
1003memory available.
1004@end deftypefun
1005
1006@deftp {Data type} gcry_handler_error_t
1007This type is defined as: @code{void (*gcry_handler_error_t) (void *, int, const char *)}
1008@end deftp
1009
1010@deftypefun void gcry_set_fatalerror_handler (gcry_handler_error_t @var{func_error}, void *@var{cb_data})
1011This function registers @var{func_error} as `error handler',
1012which means that it will be called in error conditions.
1013@end deftypefun
1014
1015@node Logging handler
1016@section Logging handler
1017
1018@deftp {Data type} gcry_handler_log_t
1019This type is defined as: @code{void (*gcry_handler_log_t) (void *, int, const char *, va_list)}
1020@end deftp
1021
1022@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
1023This function registers @var{func_log} as `logging handler', which
1024means that it will be called in case @acronym{Libgcrypt} wants to log
1025a message.
1026@end deftypefun
1027
1028@c **********************************************************
1029@c *******************  Ciphers  ****************************
1030@c **********************************************************
1031@c @include cipher-ref.texi
1032@node Symmetric cryptography
1033@chapter Symmetric cryptography
1034
1035The cipher functions are used for symmetrical cryptography,
1036i.e. cryptography using a shared key.  The programming model follows
1037an open/process/close paradigm and is in that similar to other
1038building blocks provided by @acronym{Libgcrypt}.
1039
1040@menu
1041* Available ciphers::           List of ciphers supported by the library.
1042* Cipher modules::              How to work with cipher modules.
1043* Available cipher modes::      List of cipher modes supported by the library.
1044* Working with cipher handles::  How to perform operations related to cipher handles.
1045* General cipher functions::    General cipher functions independent of cipher handles.
1046@end menu
1047
1048@node Available ciphers
1049@section Available ciphers
1050
1051@table @code
1052@item GCRY_CIPHER_NONE
1053This is not a real algorithm but used by some functions as error return.
1054The value always evaluates to false.
1055
1056@item GCRY_CIPHER_IDEA
1057This is the IDEA algorithm.  The constant is provided but there is
1058currently no implementation for it because the algorithm is patented.
1059
1060@item GCRY_CIPHER_3DES
1061Triple-DES with 3 Keys as EDE.  The key size of this algorithm is 168 but
1062you have to pass 192 bits because the most significant bits of each byte
1063are ignored.
1064
1065@item GCRY_CIPHER_CAST5
1066CAST128-5 block cipher algorithm.  The key size is 128 bits.
1067	
1068@item GCRY_CIPHER_BLOWFISH
1069The blowfish algorithm. The current implementation allows only for a key
1070size of 128 bits.
1071
1072@item GCRY_CIPHER_SAFER_SK128
1073Reserved and not currently implemented.
1074
1075@item GCRY_CIPHER_DES_SK	  
1076Reserved and not currently implemented.
1077 
1078@item  GCRY_CIPHER_AES        
1079@itemx GCRY_CIPHER_AES128
1080@itemx GCRY_CIPHER_RIJNDAEL
1081@itemx GCRY_CIPHER_RIJNDAEL128
1082AES (Rijndael) with a 128 bit key.
1083
1084@item  GCRY_CIPHER_AES192     
1085@itemx GCRY_CIPHER_RIJNDAEL128
1086AES (Rijndael) with a 192 bit key.
1087
1088@item  GCRY_CIPHER_AES256 
1089@itemx GCRY_CIPHER_RIJNDAEL256
1090AES (Rijndael) with a 256 bit key.
1091    
1092@item  GCRY_CIPHER_TWOFISH
1093The Twofish algorithm with a 256 bit key.
1094    
1095@item  GCRY_CIPHER_TWOFISH128
1096The Twofish algorithm with a 128 bit key.
1097    
1098@item  GCRY_CIPHER_ARCFOUR   
1099An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
1100Note that this is a stream cipher and must be used very carefully to
1101avoid a couple of weaknesses. 
1102
1103@item  GCRY_CIPHER_DES       
1104Standard DES with a 56 bit key. You need to pass 64 bit but the high
1105bits of each byte are ignored.  Note, that this is a weak algorithm
1106which can be broken in reasonable time using a brute force approach.
1107
1108@end table
1109
1110@node Cipher modules
1111@section Cipher modules
1112
1113@acronym{Libgcrypt} makes it possible to load additional `cipher
1114modules'; these cipher can be used just like the cipher algorithms
1115that are built into the library directly.  For an introduction into
1116extension modules, see @xref{Modules}.
1117
1118@deftp {Data type} gcry_cipher_spec_t
1119This is the `module specification structure' needed for registering
1120cipher modules, which has to be filled in by the user before it can be
1121used to register a module.  It contains the following members:
1122
1123@table @code
1124@item const char *name
1125The primary name of the algorithm.
1126@item const char **aliases
1127A list of strings that are `aliases' for the algorithm.  The list must
1128be terminated with a NULL element.
1129@item gcry_cipher_oid_spec_t *oids
1130A list of OIDs that are to be associated with the algorithm.  The
1131list's last element must have it's `oid' member set to NULL.  See
1132below for an explanation of this type.
1133@item size_t blocksize
1134The block size of the algorithm, in bytes.
1135@item size_t keylen
1136The length of the key, in bits.
1137@item size_t contextsize
1138The size of the algorithm-specific `context', that should be allocated
1139for each handle.
1140@item gcry_cipher_setkey_t setkey
1141The function responsible for initializing a handle with a provided
1142key.  See below for a description of this type.
1143@item gcry_cipher_encrypt_t encrypt
1144The function responsible for encrypting a single block.  See below for
1145a description of this type.
1146@item gcry_cipher_decrypt_t decrypt
1147The function responsible for decrypting a single block.  See below for
1148a description of this type.
1149@item gcry_cipher_stencrypt_t stencrypt
1150Like `encrypt', for stream ciphers.  See below for a description of
1151this type.
1152@item gcry_cipher_stdecrypt_t stdecrypt
1153Like `decrypt', for stream ciphers.  See below for a description of
1154this type.
1155@end table
1156@end deftp
1157
1158@deftp {Data type} gcry_cipher_oid_spec_t
1159This type is used for associating a user-provided algorithm
1160implementation with certain OIDs.  It contains the following members:
1161@table @code
1162@item const char *oid
1163Textual representation of the OID.
1164@item int mode
1165Cipher mode for which this OID is valid.
1166@end table
1167@end deftp
1168
1169@deftp {Data type} gcry_cipher_setkey_t
1170Type for the `setkey' function, defined as: gcry_err_code_t
1171(*gcry_cipher_setkey_t) (void *c, const unsigned char *key, unsigned
1172keylen)
1173@end deftp
1174
1175@deftp {Data type} gcry_cipher_encrypt_t
1176Type for the `encrypt' function, defined as: gcry_err_code_t
1177(*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, const
1178unsigned char *inbuf)
1179@end deftp
1180
1181@deftp {Data type} gcry_cipher_decrypt_t
1182Type for the `decrypt' function, defined as: gcry_err_code_t
1183(*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, const
1184unsigned char *inbuf)
1185@end deftp
1186
1187@deftp {Data type} gcry_cipher_stencrypt_t
1188Type for the `stencrypt' function, defined as: gcry_err_code_t
1189(*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const
1190unsigned char *, unsigned int n)
1191@end deftp
1192
1193@deftp {Data type} gcry_cipher_stdecrypt_t
1194Type for the `stdecrypt' function, defined as: gcry_err_code_t
1195(*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const
1196unsigned char *, unsigned int n)
1197@end deftp
1198
1199@deftypefun gcry_error_t gcry_cipher_register (gcry_cipher_spec_t *@var{cipher}, unsigned int *algorithm_id, gcry_module_t *@var{module})
1200
1201Register a new cipher module whose specification can be found in
1202@var{cipher}.  On success, a new algorithm ID is stored in
1203@var{algorithm_id} and a pointer representing this module is stored
1204in @var{module}.
1205@end deftypefun
1206
1207@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
1208Unregister the cipher identified by @var{module}, which must have been
1209registered with gcry_cipher_register.
1210@end deftypefun
1211
1212@deftypefun gcry_error_t gcry_cipher_list (int *@var{list}, int *@var{list_length})
1213Get a list consisting of the IDs of the loaded cipher modules.  If
1214@var{list} is zero, write the number of loaded cipher modules to
1215@var{list_length} and return.  If @var{list} is non-zero, the first
1216*@var{list_length} algorithm IDs are stored in @var{list}, which must
1217be of according size.  In case there are less cipher modules than
1218*@var{list_length}, *@var{list_length} is updated to the correct
1219number.
1220@end deftypefun
1221
1222@node Available cipher modes
1223@section Available cipher modes
1224
1225@table @code
1226@item GCRY_CIPHER_MODE_NONE
1227No mode specified, may be set later using other functions.  The value
1228of this constant is always 0.
1229
1230@item GCRY_CIPHER_MODE_ECB
1231Electronic Codebook mode.  
1232
1233@item GCRY_CIPHER_MODE_CFB
1234Cipher Feedback mode.
1235
1236@item  GCRY_CIPHER_MODE_CBC
1237Cipher Block Chaining mode.
1238
1239@item GCRY_CIPHER_MODE_STREAM
1240Stream mode, only to be used with stream cipher algorithms.
1241
1242@item GCRY_CIPHER_MODE_OFB
1243Outer Feedback mode.
1244
1245@item  GCRY_CIPHER_MODE_CTR
1246Counter mode.
1247
1248@end table
1249
1250@node Working with cipher handles
1251@section Working with cipher handles
1252
1253To use a cipher algorithm, you must first allocate an according
1254handle.  This is to be done using the open function:
1255
1256@deftypefun gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *@var{hd}, int @var{algo}, int @var{mode}, unsigned int @var{flags})
1257
1258This function creates the context handle required for most of the
1259other cipher functions and returns a handle to it in `hd'.  In case of
1260an error, an according error code is returned.
1261
1262The ID of algorithm to use must be specified via @var{algo}.  See
1263@xref{Available ciphers}, for a list of supported ciphers and the
1264according constants.
1265
1266Besides using the constants directly, the function
1267@code{gcry_cipher_map_name} may be used to convert the textual name of
1268an algorithm into the according numeric ID.
1269
1270The cipher mode to use must be specified via @var{mode}.  See
1271@xref{Available cipher modes}, for a list of supported cipher modes
1272and the according constants.  Note, that some modes do not work
1273together with all algorithms.
1274
1275The third argument @var{flags} can either be passed as @code{0} or as
1276the bit-wise OR of the following constants.
1277
1278@table @code
1279@item GCRY_CIPHER_SECURE
1280Make sure that all operations are allocated in secure memory.  This is
1281useful, when the key material is highly confidential.
1282@item GCRY_CIPHER_ENABLE_SYNC
1283This flag enables the CFB sync mode, which is a special feature of
1284@acronym{Libgcrypt}'s CFB mode implementation to allow for OpenPGP's CFB variant. 
1285See @code{gcry_cipher_sync}.
1286@i

Large files files are truncated, but you can click here to view the full file