The Libgcrypt Reference Manual Version 1.8.2 23 November 2017
Total Page:16
File Type:pdf, Size:1020Kb
The Libgcrypt Reference Manual Version 1.8.2 23 November 2017 Werner Koch ([email protected]) Moritz Schulte ([email protected]) This manual is for Libgcrypt (version 1.8.2, 23 November 2017), which is GNU's library of cryptographic building blocks. Copyright c 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012 Free Software Foundation, Inc. Copyright c 2012, 2013, 2016, 2017 g10 Code GmbH 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:::::::::::::::::::::::::::::::::::: 21 5 Symmetric cryptography :::::::::::::::::::::::::::::: 25 6 Public Key cryptography :::::::::::::::::::::::::::::: 35 7 Hashing :::::::::::::::::::::::::::::::::::::::::::: 49 8 Message Authentication Codes ::::::::::::::::::::::::: 57 9 Key Derivation :::::::::::::::::::::::::::::::::::::: 63 10 Random Numbers :::::::::::::::::::::::::::::::::::: 65 11 S-expressions :::::::::::::::::::::::::::::::::::::::: 67 12 MPI library ::::::::::::::::::::::::::::::::::::::::: 73 13 Prime numbers :::::::::::::::::::::::::::::::::::::: 83 14 Utilities :::::::::::::::::::::::::::::::::::::::::::: 85 15 Tools :::::::::::::::::::::::::::::::::::::::::::::: 87 16 Configuration files and environment variables:::::::::::::: 89 17 Architecture :::::::::::::::::::::::::::::::::::::::: 91 A Description of the Self-Tests:::::::::::::::::::::::::::: 99 B Description of the FIPS Mode ::::::::::::::::::::::::: 105 GNU Lesser General Public License :::::::::::::::::::::::: 111 GNU General Public License :::::::::::::::::::::::::::::: 121 List of Figures and Tables :::::::::::::::::::::::::::::::: 127 Concept Index ::::::::::::::::::::::::::::::::::::::::: 129 Function and Data Index ::::::::::::::::::::::::::::::::: 131 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 2.7 How to disable hardware features ::::::::::::::::::::::::::::::: 7 3 Generalities ::::::::::::::::::::::::::::::::::::: 9 3.1 Controlling the library ::::::::::::::::::::::::::::::::::::::::: 9 3.2 Error Handling:::::::::::::::::::::::::::::::::::::::::::::::: 15 3.2.1 Error Values ::::::::::::::::::::::::::::::::::::::::::::: 15 3.2.2 Error Sources :::::::::::::::::::::::::::::::::::::::::::: 17 3.2.3 Error Codes :::::::::::::::::::::::::::::::::::::::::::::: 18 3.2.4 Error Strings ::::::::::::::::::::::::::::::::::::::::::::: 20 4 Handler Functions ::::::::::::::::::::::::::::: 21 4.1 Progress handler :::::::::::::::::::::::::::::::::::::::::::::: 21 4.2 Allocation handler :::::::::::::::::::::::::::::::::::::::::::: 22 4.3 Error handler ::::::::::::::::::::::::::::::::::::::::::::::::: 22 4.4 Logging handler::::::::::::::::::::::::::::::::::::::::::::::: 23 5 Symmetric cryptography:::::::::::::::::::::: 25 5.1 Available ciphers :::::::::::::::::::::::::::::::::::::::::::::: 25 5.2 Available cipher modes :::::::::::::::::::::::::::::::::::::::: 26 5.3 Working with cipher handles :::::::::::::::::::::::::::::::::: 28 5.4 General cipher functions :::::::::::::::::::::::::::::::::::::: 32 6 Public Key cryptography ::::::::::::::::::::: 35 6.1 Available algorithms :::::::::::::::::::::::::::::::::::::::::: 35 6.2 Used S-expressions :::::::::::::::::::::::::::::::::::::::::::: 35 6.2.1 RSA key parameters ::::::::::::::::::::::::::::::::::::: 35 6.2.2 DSA key parameters ::::::::::::::::::::::::::::::::::::: 36 6.2.3 ECC key parameters ::::::::::::::::::::::::::::::::::::: 36 6.3 Cryptographic Functions :::::::::::::::::::::::::::::::::::::: 38 6.4 General public-key related Functions :::::::::::::::::::::::::: 42 iv The Libgcrypt Reference Manual 7 Hashing :::::::::::::::::::::::::::::::::::::::: 49 7.1 Available hash algorithms ::::::::::::::::::::::::::::::::::::: 49 7.2 Working with hash algorithms::::::::::::::::::::::::::::::::: 52 8 Message Authentication Codes ::::::::::::::: 57 8.1 Available MAC algorithms :::::::::::::::::::::::::::::::::::: 57 8.2 Working with MAC algorithms :::::::::::::::::::::::::::::::: 60 9 Key Derivation :::::::::::::::::::::::::::::::: 63 10 Random Numbers:::::::::::::::::::::::::::: 65 10.1 Quality of random numbers :::::::::::::::::::::::::::::::::: 65 10.2 Retrieving random numbers :::::::::::::::::::::::::::::::::: 65 11 S-expressions ::::::::::::::::::::::::::::::::: 67 11.1 Data types for S-expressions ::::::::::::::::::::::::::::::::: 67 11.2 Working with S-expressions :::::::::::::::::::::::::::::::::: 67 12 MPI library::::::::::::::::::::::::::::::::::: 73 12.1 Data types::::::::::::::::::::::::::::::::::::::::::::::::::: 73 12.2 Basic functions :::::::::::::::::::::::::::::::::::::::::::::: 73 12.3 MPI formats ::::::::::::::::::::::::::::::::::::::::::::::::: 74 12.4 Calculations ::::::::::::::::::::::::::::::::::::::::::::::::: 75 12.5 Comparisons ::::::::::::::::::::::::::::::::::::::::::::::::: 76 12.6 Bit manipulations:::::::::::::::::::::::::::::::::::::::::::: 77 12.7 EC functions::::::::::::::::::::::::::::::::::::::::::::::::: 77 12.8 Miscellaneous :::::::::::::::::::::::::::::::::::::::::::::::: 80 13 Prime numbers ::::::::::::::::::::::::::::::: 83 13.1 Generation::::::::::::::::::::::::::::::::::::::::::::::::::: 83 13.2 Checking :::::::::::::::::::::::::::::::::::::::::::::::::::: 83 14 Utilities ::::::::::::::::::::::::::::::::::::::: 85 14.1 Memory allocation ::::::::::::::::::::::::::::::::::::::::::: 85 14.2 Context management :::::::::::::::::::::::::::::::::::::::: 85 14.3 Buffer description :::::::::::::::::::::::::::::::::::::::::::: 85 14.4 How to return Libgcrypt's configuration. ::::::::::::::::::::: 86 15 Tools :::::::::::::::::::::::::::::::::::::::::: 87 15.1 A HMAC-SHA-256 tool :::::::::::::::::::::::::::::::::::::: 87 16 Configuration files and environment variables :::::::::::::::::::::::::::::::::::::::::::::::: 89 v 17 Architecture :::::::::::::::::::::::::::::::::: 91 17.1 Public-Key Architecture ::::::::::::::::::::::::::::::::::::: 92 17.2 Symmetric Encryption Subsystem Architecture ::::::::::::::: 92 17.3 Hashing and MACing Subsystem Architecture :::::::::::::::: 93 17.4 Multi-Precision-Integer Subsystem Architecture :::::::::::::: 94 17.5 Prime-Number-Generator Subsystem Architecture :::::::::::: 94 17.6 Random-Number Subsystem Architecture :::::::::::::::::::: 95 17.6.1 Description of the CSPRNG::::::::::::::::::::::::::::: 96 17.6.2 Description of the FIPS X9.31 PRNG ::::::::::::::::::: 96 Appendix A Description of the Self-Tests::::: 99 A.1 Power-Up Tests :::::::::::::::::::::::::::::::::::::::::::::: 99 A.1.1 Symmetric Cipher Algorithm Power-Up Tests :::::::::::: 99 A.1.2 Hash Algorithm Power-Up Tests ::::::::::::::::::::::::: 99 A.1.3 MAC Algorithm Power-Up Tests:::::::::::::::::::::::: 100 A.1.4 Random Number Power-Up Test:::::::::::::::::::::::: 100 A.1.5 Public Key Algorithm Power-Up Tests :::::::::::::::::: 100 A.1.6 Integrity Power-Up Tests ::::::::::::::::::::::::::::::: 101 A.1.7 Critical Functions Power-Up Tests :::::::::::::::::::::: 101 A.2 Conditional Tests:::::::::::::::::::::::::::::::::::::::::::: 101 A.2.1 Key-Pair Generation Tests :::::::::::::::::::::::::::::: 101 A.2.2 Software Load Tests :::::::::::::::::::::::::::::::::::: 102 A.2.3 Manual Key Entry Tests :::::::::::::::::::::::::::::::: 102 A.2.4 Continuous RNG Tests ::::::::::::::::::::::::::::::::: 102 A.3 Application Requested Tests ::::::::::::::::::::::::::::::::: 102 A.3.1 Symmetric Cipher Algorithm Tests ::::::::::::::::::::: 102 A.3.2 Hash Algorithm Tests :::::::::::::::::::::::::::::::::: 102 A.3.3 MAC Algorithm Tests :::::::::::::::::::::::::::::::::: 103 Appendix B Description of the FIPS Mode ::::::::::::::::::::::::::::::::::::::::::::::: 105 B.1 Restrictions in FIPS Mode::::::::::::::::::::::::::::::::::: 105 B.2 FIPS Finite State Machine :::::::::::::::::::::::::::::::::: 106 B.3 FIPS Miscellaneous Information ::::::::::::::::::::::::::::: 110 GNU Lesser General Public License:::::::::::: 111 GNU General Public License ::::::::::::::::::: 121 List of Figures and Tables ::::::::::::::::::::::: 127 Concept Index:::::::::::::::::::::::::::::::::::: 129 Function and Data Index :::::::::::::::::::::::: 131 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