The Libgcrypt Reference Manual Version 1.9.0 18 January 2021 Werner Koch ([email protected]) Moritz Schulte ([email protected]) This manual is for Libgcrypt version 1.9.0 and was last updated 18 January 2021. Libgcrypt 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 :::::::::::::::::::::::::::::::::::::::::::: 51 8 Message Authentication Codes ::::::::::::::::::::::::: 59 9 Key Derivation :::::::::::::::::::::::::::::::::::::: 67 10 Random Numbers :::::::::::::::::::::::::::::::::::: 69 11 S-expressions :::::::::::::::::::::::::::::::::::::::: 71 12 MPI library ::::::::::::::::::::::::::::::::::::::::: 77 13 Prime numbers :::::::::::::::::::::::::::::::::::::: 87 14 Utilities :::::::::::::::::::::::::::::::::::::::::::: 89 15 Tools :::::::::::::::::::::::::::::::::::::::::::::: 91 16 Configuration files and environment variables:::::::::::::: 93 17 Architecture :::::::::::::::::::::::::::::::::::::::: 95 A Description of the Self-Tests::::::::::::::::::::::::::: 103 B Description of the FIPS Mode ::::::::::::::::::::::::: 109 GNU Lesser General Public License :::::::::::::::::::::::: 115 GNU General Public License :::::::::::::::::::::::::::::: 125 List of Figures and Tables :::::::::::::::::::::::::::::::: 131 Concept Index ::::::::::::::::::::::::::::::::::::::::: 133 Function and Data Index ::::::::::::::::::::::::::::::::: 135 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 :::::::::::::::::::::::::::::::::::::::: 27 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 :::::::::::::::::::::::::::::::::::::: 39 6.4 Dedicated functions for elliptic curves.::::::::::::::::::::::::: 43 6.5 General public-key related Functions :::::::::::::::::::::::::: 44 iv The Libgcrypt Reference Manual 7 Hashing :::::::::::::::::::::::::::::::::::::::: 51 7.1 Available hash algorithms ::::::::::::::::::::::::::::::::::::: 51 7.2 Working with hash algorithms::::::::::::::::::::::::::::::::: 54 8 Message Authentication Codes ::::::::::::::: 59 8.1 Available MAC algorithms :::::::::::::::::::::::::::::::::::: 59 8.2 Working with MAC algorithms :::::::::::::::::::::::::::::::: 63 9 Key Derivation :::::::::::::::::::::::::::::::: 67 10 Random Numbers:::::::::::::::::::::::::::: 69 10.1 Quality of random numbers :::::::::::::::::::::::::::::::::: 69 10.2 Retrieving random numbers :::::::::::::::::::::::::::::::::: 69 11 S-expressions ::::::::::::::::::::::::::::::::: 71 11.1 Data types for S-expressions ::::::::::::::::::::::::::::::::: 71 11.2 Working with S-expressions :::::::::::::::::::::::::::::::::: 71 12 MPI library::::::::::::::::::::::::::::::::::: 77 12.1 Data types::::::::::::::::::::::::::::::::::::::::::::::::::: 77 12.2 Basic functions :::::::::::::::::::::::::::::::::::::::::::::: 77 12.3 MPI formats ::::::::::::::::::::::::::::::::::::::::::::::::: 78 12.4 Calculations ::::::::::::::::::::::::::::::::::::::::::::::::: 79 12.5 Comparisons ::::::::::::::::::::::::::::::::::::::::::::::::: 80 12.6 Bit manipulations:::::::::::::::::::::::::::::::::::::::::::: 81 12.7 EC functions::::::::::::::::::::::::::::::::::::::::::::::::: 81 12.8 Miscellaneous :::::::::::::::::::::::::::::::::::::::::::::::: 84 13 Prime numbers ::::::::::::::::::::::::::::::: 87 13.1 Generation::::::::::::::::::::::::::::::::::::::::::::::::::: 87 13.2 Checking :::::::::::::::::::::::::::::::::::::::::::::::::::: 87 14 Utilities ::::::::::::::::::::::::::::::::::::::: 89 14.1 Memory allocation ::::::::::::::::::::::::::::::::::::::::::: 89 14.2 Context management :::::::::::::::::::::::::::::::::::::::: 89 14.3 Buffer description :::::::::::::::::::::::::::::::::::::::::::: 89 14.4 How to return Libgcrypt's configuration. ::::::::::::::::::::: 90 15 Tools :::::::::::::::::::::::::::::::::::::::::: 91 15.1 A HMAC-SHA-256 tool :::::::::::::::::::::::::::::::::::::: 91 16 Configuration files and environment variables :::::::::::::::::::::::::::::::::::::::::::::::: 93 v 17 Architecture :::::::::::::::::::::::::::::::::: 95 17.1 Public-Key Architecture ::::::::::::::::::::::::::::::::::::: 96 17.2 Symmetric Encryption Subsystem Architecture ::::::::::::::: 96 17.3 Hashing and MACing Subsystem Architecture :::::::::::::::: 97 17.4 Multi-Precision-Integer Subsystem Architecture :::::::::::::: 98 17.5 Prime-Number-Generator Subsystem Architecture :::::::::::: 98 17.6 Random-Number Subsystem Architecture :::::::::::::::::::: 99 17.6.1 Description of the CSPRNG:::::::::::::::::::::::::::: 100 17.6.2 Description of the FIPS X9.31 PRNG :::::::::::::::::: 100 Appendix A Description of the Self-Tests ::: 103 A.1 Power-Up Tests ::::::::::::::::::::::::::::::::::::::::::::: 103 A.1.1 Symmetric Cipher Algorithm Power-Up Tests ::::::::::: 103 A.1.2 Hash Algorithm Power-Up Tests :::::::::::::::::::::::: 103 A.1.3 MAC Algorithm Power-Up Tests:::::::::::::::::::::::: 104 A.1.4 Random Number Power-Up Test:::::::::::::::::::::::: 104 A.1.5 Public Key Algorithm Power-Up Tests :::::::::::::::::: 104 A.1.6 Integrity Power-Up Tests ::::::::::::::::::::::::::::::: 105 A.1.7 Critical Functions Power-Up Tests :::::::::::::::::::::: 105 A.2 Conditional Tests:::::::::::::::::::::::::::::::::::::::::::: 105 A.2.1 Key-Pair Generation Tests :::::::::::::::::::::::::::::: 105 A.2.2 Software Load Tests :::::::::::::::::::::::::::::::::::: 106 A.2.3 Manual Key Entry Tests :::::::::::::::::::::::::::::::: 106 A.2.4 Continuous RNG Tests ::::::::::::::::::::::::::::::::: 106 A.3 Application Requested Tests ::::::::::::::::::::::::::::::::: 106 A.3.1 Symmetric Cipher Algorithm Tests ::::::::::::::::::::: 106 A.3.2 Hash Algorithm Tests :::::::::::::::::::::::::::::::::: 106 A.3.3 MAC Algorithm Tests :::::::::::::::::::::::::::::::::: 107 Appendix B Description of the FIPS Mode ::::::::::::::::::::::::::::::::::::::::::::::: 109 B.1 Restrictions in FIPS Mode::::::::::::::::::::::::::::::::::: 109 B.2 FIPS Finite State Machine :::::::::::::::::::::::::::::::::: 110 B.3 FIPS Miscellaneous Information ::::::::::::::::::::::::::::: 114 GNU Lesser General Public License:::::::::::: 115 GNU General Public License ::::::::::::::::::: 125 List of Figures and Tables ::::::::::::::::::::::: 131 Concept Index:::::::::::::::::::::::::::::::::::: 133 Function and Data Index :::::::::::::::::::::::: 135 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