Transcription
The Libgcrypt Reference ManualVersion 1.4.14 January 2008Werner Koch (wk@gnupg.org)Moritz Schulte (mo@g10code.com)
This manual is for Libgcrypt (version 1.4.1, 4 January 2008), which is GNU’s library ofcryptographic building blocks.Copyright c 2000, 2002, 2003, 2004, 2006, 2007 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this document underthe terms of the GNU General Public License as published by the Free SoftwareFoundation; either version 2 of the License, or (at your option) any later version.The text of the license can be found in the section entitled “Copying”.
iShort Contents1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Generalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Handler Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Symmetric cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 Public Key cryptography (I) . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Public Key cryptography (II) . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5710 S-expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5911 MPI library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6312 Prime numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6913 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71A GNU LESSER GENERAL PUBLIC LICENSE . . . . . . . . . . . . 73B GNU GENERAL PUBLIC LICENSE . . . . . . . . . . . . . . . . . . . . 83Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Function and Data Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
iiThe Libgcrypt Reference Manual
iiiTable of Contents1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.11.21.32Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.12.22.32.42.53Controlling the library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3.1 Error Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.3.2 Error Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.3.3 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.3.4 Error Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Progress handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Allocation handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Error handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Logging handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15161617Symmetric cryptography. . . . . . . . . . . . . . . . . . . . . . 195.15.25.35.45.5633444Handler Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.14.24.34.45Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Building sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Building sources using Automake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Initializing the library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Multi-Threading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Generalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.13.23.34Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Available ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Cipher modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Available cipher modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Working with cipher handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .General cipher functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1920222225Hashing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276.16.26.3Available hash algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Hash algorithm modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Working with hash algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
ivThe Libgcrypt Reference Manual7Public Key cryptography (I) . . . . . . . . . . . . . . . . . 357.17.2Available algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Used S-expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.2.1 RSA key parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.2.2 DSA key parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.2.3 ECC key parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.3 Public key modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.4 Cryptographic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7.5 General public-key related Functions . . . . . . . . . . . . . . . . . . . . . . . . . .83535353636384043Public Key cryptography (II) . . . . . . . . . . . . . . . . 478.18.28.38.48.58.68.79Available asymmetric algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Working with sets of data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Working with IO objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Working with handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Working with keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Using cryptographic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Handle-independent functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47474950505255Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579.19.210Quality of random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Retrieving random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57S-expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5910.110.211MPI library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6311.111.211.311.411.511.611.712Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Basic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .MPI formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Bit manipulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63636465666667Prime numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6912.112.213Data types for S-expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Working with S-expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7113.1Memory allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
vAppendix A GNU LESSER GENERALPUBLIC LICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . 73A.0.1 Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73A.0.2 TERMS AND CONDITIONS FOR COPYING,DISTRIBUTION AND MODIFICATION . . . . . . . . . . . . . . . . . . . 74A.0.3 How to Apply These Terms to Your New Libraries . . . . . . . 81Appendix B GNU GENERAL PUBLICLICENSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83B.0.1 Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83B.0.2 TERMS AND CONDITIONS FOR COPYING,DISTRIBUTION AND MODIFICATION . . . . . . . . . . . . . . . . . . . 83How to Apply These Terms to Your New Programs . . . . . . . . . . . . . . . . . 88Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Function and Data Index . . . . . . . . . . . . . . . . . . . . . . . . . 91
viThe Libgcrypt Reference Manual
Chapter 1: Introduction11 IntroductionLibgcrypt is a library providing cryptographic building blocks.1.1 Getting StartedThis manual documents the Libgcrypt library application programming interface (API). Allfunctions 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 givesa good introduction into the library and how it can be used in an application. Forwardreferences are included where necessary. Later on, the manual can be used as a referencemanual 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 themanual, and then only read up those parts of the interface which are unclear.1.2 FeaturesLibgcrypt might have a couple of advantages over other libraries doing a similar job.It’s Free SoftwareAnybody can use, modify, and redistribute it under the terms of the GNULesser General Public License (see Appendix A [Library Copying], page 73).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 (see Appendix B[Copying], page 83); please see the README file of the distribution for of listof these parts.It encapsulates the low level cryptographyLibgcrypt provides a high level interface to cryptographic building blocks usingan extensible and flexible API.1.3 OverviewThe Libgcrypt library is fully thread-safe, where it makes sense to be thread-safe. Notthread-safe are some cryptographic functions that modify a certain context stored in handles. If the user really intents to use such functions from different threads on the samehandle, he has to take care of the serialization of such functions himself. If not describedotherwise, every function is thread-safe.Libgcrypt depends on the library ‘libgpg-error’, which contains common error handlingrelated code for GnuPG components.
2The Libgcrypt Reference Manual
Chapter 2: Preparation32 PreparationTo 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 ofthis chapter, it is described how the library is initialized, and how the requirements of thelibrary are verified.2.1 HeaderAll interfaces (data types and functions) of the library are defined in the header file‘gcrypt.h’. You must include this in all source files using the library, either directly orthrough some other header file, like this:#include gcrypt.h The name space of Libgcrypt is gcry * for function and type names and GCRY* for othersymbols. In addition the same name prefixes with one prepended underscore are reservedfor internal use and should never be used by an application. Note that Libgcrypt useslibgpg-error, which uses gpg * as name space for function and type names and GPG * forother symbols, including all the error codes.Certain parts of gcrypt.h may be excluded by defining these macros:GCRYPT NO MPI MACROSDo not define the shorthand macros mpi * for gcry mpi *.GCRYPT NO DEPRECATEDDo not include defintions for deprecated features.2.2 Building sourcesIf you want to compile a source file including the ‘gcrypt.h’ header file, you must make surethat the compiler can find it in the directory hierarchy. This is accomplished by adding thepath to the directory in which the
The Libgcrypt Reference Manual Version 1.4.1 4 January 2008 Werner Koch (wk@gnupg.org) Moritz Schulte (mo@g10code.com)
