The Libgcrypt Reference Manual Version 1.4.6 9 July 2009
Total Page:16
File Type:pdf, Size:1020Kb
The Libgcrypt Reference Manual Version 1.4.6 9 July 2009 Werner Koch ([email protected]) Moritz Schulte ([email protected]) This manual is for Libgcrypt (version 1.4.6, 9 July 2009), which is GNU's library of cryp- tographic building blocks. Copyright c 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; 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 \GNU General Public License". i Short Contents 1 Introduction ::::::::::::::::::::::::::::::::::::::::: 1 2 Preparation :::::::::::::::::::::::::::::::::::::::::: 3 3 Generalities :::::::::::::::::::::::::::::::::::::::::: 9 4 Handler Functions:::::::::::::::::::::::::::::::::::: 19 5 Symmetric cryptography :::::::::::::::::::::::::::::: 23 6 Public Key cryptography :::::::::::::::::::::::::::::: 31 7 Hashing :::::::::::::::::::::::::::::::::::::::::::: 53 8 Random Numbers :::::::::::::::::::::::::::::::::::: 61 9 S-expressions :::::::::::::::::::::::::::::::::::::::: 63 10 MPI library ::::::::::::::::::::::::::::::::::::::::: 67 11 Prime numbers :::::::::::::::::::::::::::::::::::::: 73 12 Utilities :::::::::::::::::::::::::::::::::::::::::::: 75 13 Architecture :::::::::::::::::::::::::::::::::::::::: 77 A Description of the Self-Tests:::::::::::::::::::::::::::: 85 B Description of the FIPS Mode :::::::::::::::::::::::::: 91 GNU Lesser General Public License ::::::::::::::::::::::::: 97 GNU General Public License :::::::::::::::::::::::::::::: 107 List of Figures and Tables :::::::::::::::::::::::::::::::: 113 Concept Index ::::::::::::::::::::::::::::::::::::::::: 115 Function and Data Index ::::::::::::::::::::::::::::::::: 117 ii The Libgcrypt Reference Manual iii Table of Contents 1 Introduction::::::::::::::::::::::::::::::::::::: 1 1.1 Getting Started :::::::::::::::::::::::::::::::::::::::::::::::: 1 1.2 Features ::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 1.3 Overview :::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 2 Preparation ::::::::::::::::::::::::::::::::::::: 3 2.1 Header ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 3 2.2 Building sources:::::::::::::::::::::::::::::::::::::::::::::::: 3 2.3 Building sources using Automake ::::::::::::::::::::::::::::::: 4 2.4 Initializing the library :::::::::::::::::::::::::::::::::::::::::: 4 2.5 Multi-Threading ::::::::::::::::::::::::::::::::::::::::::::::: 6 2.6 How to enable the FIPS mode :::::::::::::::::::::::::::::::::: 7 3 Generalities ::::::::::::::::::::::::::::::::::::: 9 3.1 Controlling the library ::::::::::::::::::::::::::::::::::::::::: 9 3.2 Modules :::::::::::::::::::::::::::::::::::::::::::::::::::::: 13 3.3 Error Handling:::::::::::::::::::::::::::::::::::::::::::::::: 13 3.3.1 Error Values ::::::::::::::::::::::::::::::::::::::::::::: 13 3.3.2 Error Sources :::::::::::::::::::::::::::::::::::::::::::: 15 3.3.3 Error Codes :::::::::::::::::::::::::::::::::::::::::::::: 16 3.3.4 Error Strings ::::::::::::::::::::::::::::::::::::::::::::: 18 4 Handler Functions ::::::::::::::::::::::::::::: 19 4.1 Progress handler :::::::::::::::::::::::::::::::::::::::::::::: 19 4.2 Allocation handler :::::::::::::::::::::::::::::::::::::::::::: 20 4.3 Error handler ::::::::::::::::::::::::::::::::::::::::::::::::: 20 4.4 Logging handler::::::::::::::::::::::::::::::::::::::::::::::: 21 5 Symmetric cryptography:::::::::::::::::::::: 23 5.1 Available ciphers :::::::::::::::::::::::::::::::::::::::::::::: 23 5.2 Cipher modules ::::::::::::::::::::::::::::::::::::::::::::::: 24 5.3 Available cipher modes :::::::::::::::::::::::::::::::::::::::: 26 5.4 Working with cipher handles :::::::::::::::::::::::::::::::::: 26 5.5 General cipher functions :::::::::::::::::::::::::::::::::::::: 29 6 Public Key cryptography ::::::::::::::::::::: 31 6.1 Available algorithms :::::::::::::::::::::::::::::::::::::::::: 31 6.2 Used S-expressions :::::::::::::::::::::::::::::::::::::::::::: 31 6.2.1 RSA key parameters ::::::::::::::::::::::::::::::::::::: 31 6.2.2 DSA key parameters ::::::::::::::::::::::::::::::::::::: 32 6.2.3 ECC key parameters ::::::::::::::::::::::::::::::::::::: 32 iv The Libgcrypt Reference Manual 6.3 Public key modules ::::::::::::::::::::::::::::::::::::::::::: 34 6.4 Cryptographic Functions :::::::::::::::::::::::::::::::::::::: 36 6.5 General public-key related Functions :::::::::::::::::::::::::: 39 6.6 Alternative Public Key Interface :::::::::::::::::::::::::::::: 44 6.6.1 Available asymmetric algorithms ::::::::::::::::::::::::: 44 6.6.2 Working with sets of data :::::::::::::::::::::::::::::::: 44 6.6.3 Working with IO objects ::::::::::::::::::::::::::::::::: 46 6.6.4 Working with handles :::::::::::::::::::::::::::::::::::: 47 6.6.5 Working with keys ::::::::::::::::::::::::::::::::::::::: 47 6.6.6 Using cryptographic functions :::::::::::::::::::::::::::: 49 6.6.7 Handle-independent functions :::::::::::::::::::::::::::: 52 7 Hashing :::::::::::::::::::::::::::::::::::::::: 53 7.1 Available hash algorithms ::::::::::::::::::::::::::::::::::::: 53 7.2 Hash algorithm modules::::::::::::::::::::::::::::::::::::::: 54 7.3 Working with hash algorithms::::::::::::::::::::::::::::::::: 56 8 Random Numbers ::::::::::::::::::::::::::::: 61 8.1 Quality of random numbers ::::::::::::::::::::::::::::::::::: 61 8.2 Retrieving random numbers ::::::::::::::::::::::::::::::::::: 61 9 S-expressions::::::::::::::::::::::::::::::::::: 63 9.1 Data types for S-expressions::::::::::::::::::::::::::::::::::: 63 9.2 Working with S-expressions ::::::::::::::::::::::::::::::::::: 63 10 MPI library::::::::::::::::::::::::::::::::::: 67 10.1 Data types::::::::::::::::::::::::::::::::::::::::::::::::::: 67 10.2 Basic functions :::::::::::::::::::::::::::::::::::::::::::::: 67 10.3 MPI formats ::::::::::::::::::::::::::::::::::::::::::::::::: 68 10.4 Calculations ::::::::::::::::::::::::::::::::::::::::::::::::: 69 10.5 Comparisons ::::::::::::::::::::::::::::::::::::::::::::::::: 70 10.6 Bit manipulations:::::::::::::::::::::::::::::::::::::::::::: 70 10.7 Miscellaneous :::::::::::::::::::::::::::::::::::::::::::::::: 71 11 Prime numbers ::::::::::::::::::::::::::::::: 73 11.1 Generation::::::::::::::::::::::::::::::::::::::::::::::::::: 73 11.2 Checking :::::::::::::::::::::::::::::::::::::::::::::::::::: 73 12 Utilities ::::::::::::::::::::::::::::::::::::::: 75 12.1 Memory allocation ::::::::::::::::::::::::::::::::::::::::::: 75 v 13 Architecture :::::::::::::::::::::::::::::::::: 77 13.1 Public-Key Architecture ::::::::::::::::::::::::::::::::::::: 78 13.2 Symmetric Encryption Subsystem Architecture ::::::::::::::: 79 13.3 Hashing and MACing Subsystem Architecture :::::::::::::::: 79 13.4 Multi-Precision-Integer Subsystem Architecture :::::::::::::: 80 13.5 Prime-Number-Generator Subsystem Architecture :::::::::::: 80 13.6 Random-Number Subsystem Architecture :::::::::::::::::::: 81 13.6.1 Description of the CSPRNG::::::::::::::::::::::::::::: 82 13.6.2 Description of the FIPS X9.31 PRNG ::::::::::::::::::: 82 Appendix A Description of the Self-Tests::::: 85 A.1 Power-Up Tests :::::::::::::::::::::::::::::::::::::::::::::: 85 A.1.1 Symmetric Cipher Algorithm Power-Up Tests :::::::::::: 85 A.1.2 Hash Algorithm Power-Up Tests ::::::::::::::::::::::::: 85 A.1.3 MAC Algorithm Power-Up Tests ::::::::::::::::::::::::: 86 A.1.4 Random Number Power-Up Test ::::::::::::::::::::::::: 86 A.1.5 Public Key Algorithm Power-Up Tests ::::::::::::::::::: 86 A.1.6 Integrity Power-Up Tests :::::::::::::::::::::::::::::::: 87 A.1.7 Critical Functions Power-Up Tests ::::::::::::::::::::::: 87 A.2 Conditional Tests::::::::::::::::::::::::::::::::::::::::::::: 87 A.2.1 Key-Pair Generation Tests ::::::::::::::::::::::::::::::: 87 A.2.2 Software Load Tests ::::::::::::::::::::::::::::::::::::: 88 A.2.3 Manual Key Entry Tests ::::::::::::::::::::::::::::::::: 88 A.2.4 Continuous RNG Tests :::::::::::::::::::::::::::::::::: 88 A.3 Application Requested Tests :::::::::::::::::::::::::::::::::: 88 A.3.1 Symmetric Cipher Algorithm Tests::::::::::::::::::::::: 88 A.3.2 Hash Algorithm Tests:::::::::::::::::::::::::::::::::::: 88 A.3.3 MAC Algorithm Tests ::::::::::::::::::::::::::::::::::: 89 Appendix B Description of the FIPS Mode :: 91 B.1 Restrictions in FIPS Mode:::::::::::::::::::::::::::::::::::: 91 B.2 FIPS Finite State Machine:::::::::::::::::::::::::::::::::::: 92 B.3 FIPS Miscellaneous Information :::::::::::::::::::::::::::::: 96 GNU Lesser General Public License ::::::::::::: 97 GNU General Public License ::::::::::::::::::: 107 List of Figures and Tables ::::::::::::::::::::::: 113 Concept Index:::::::::::::::::::::::::::::::::::: 115 Function and Data Index :::::::::::::::::::::::: 117 vi The Libgcrypt Reference Manual Chapter 1: Introduction 1 1 Introduction Libgcrypt is a library providing cryptographic building blocks. 1.1 Getting Started This manual documents the Libgcrypt library application programming interface (API). 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