1This is gcrypt.info, produced by makeinfo version 6.5 from gcrypt.texi. 2 3This manual is for Libgcrypt version 1.9.2 and was last updated 28 4January 2021. Libgcrypt is GNU's library of cryptographic building 5blocks. 6 7Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012 8Free Software Foundation, Inc. 9Copyright (C) 2012, 2013, 2016, 2017 g10 Code GmbH 10 11 Permission is granted to copy, distribute and/or modify this 12 document under the terms of the GNU General Public License as 13 published by the Free Software Foundation; either version 2 of the 14 License, or (at your option) any later version. The text of the 15 license can be found in the section entitled "GNU General Public 16 License". 17INFO-DIR-SECTION GNU Libraries 18START-INFO-DIR-ENTRY 19* libgcrypt: (gcrypt). Cryptographic function library. 20END-INFO-DIR-ENTRY 21 22 23File: gcrypt.info, Node: Top, Next: Introduction, Up: (dir) 24 25The Libgcrypt Library 26********************* 27 28This manual is for Libgcrypt version 1.9.2 and was last updated 28 29January 2021. Libgcrypt is GNU's library of cryptographic building 30blocks. 31 32Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2012 33Free Software Foundation, Inc. 34Copyright (C) 2012, 2013, 2016, 2017 g10 Code GmbH 35 36 Permission is granted to copy, distribute and/or modify this 37 document under the terms of the GNU General Public License as 38 published by the Free Software Foundation; either version 2 of the 39 License, or (at your option) any later version. The text of the 40 license can be found in the section entitled "GNU General Public 41 License". 42 43* Menu: 44 45* Introduction:: What is Libgcrypt. 46* Preparation:: What you should do before using the library. 47* Generalities:: General library functions and data types. 48* Handler Functions:: Working with handler functions. 49* Symmetric cryptography:: How to use symmetric cryptography. 50* Public Key cryptography:: How to use public key cryptography. 51* Hashing:: How to use hash algorithms. 52* Message Authentication Codes:: How to use MAC algorithms. 53* Key Derivation:: How to derive keys from strings 54* Random Numbers:: How to work with random numbers. 55* S-expressions:: How to manage S-expressions. 56* MPI library:: How to work with multi-precision-integers. 57* Prime numbers:: How to use the Prime number related functions. 58* Utilities:: Utility functions. 59* Tools:: Utility tools. 60* Configuration:: Configuration files and environment variables. 61* Architecture:: How Libgcrypt works internally. 62 63Appendices 64 65* Self-Tests:: Description of the self-tests. 66* FIPS Mode:: Description of the FIPS mode. 67* Library Copying:: The GNU Lesser General Public License 68 says how you can copy and share Libgcrypt. 69* Copying:: The GNU General Public License says how you 70 can copy and share some parts of Libgcrypt. 71 72Indices 73 74* Figures and Tables:: Index of figures and tables. 75* Concept Index:: Index of concepts and programs. 76* Function and Data Index:: Index of functions, variables and data types. 77 78 79File: gcrypt.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top 80 811 Introduction 82************** 83 84Libgcrypt is a library providing cryptographic building blocks. 85 86* Menu: 87 88* Getting Started:: How to use this manual. 89* Features:: A glance at Libgcrypt's features. 90* Overview:: Overview about the library. 91 92 93File: gcrypt.info, Node: Getting Started, Next: Features, Up: Introduction 94 951.1 Getting Started 96=================== 97 98This manual documents the Libgcrypt library application programming 99interface (API). All functions and data types provided by the library 100are explained. 101 102The reader is assumed to possess basic knowledge about applied 103cryptography. 104 105 This manual can be used in several ways. If read from the beginning 106to the end, it gives a good introduction into the library and how it can 107be used in an application. Forward references are included where 108necessary. Later on, the manual can be used as a reference manual to 109get just the information needed about any particular interface of the 110library. Experienced programmers might want to start looking at the 111examples at the end of the manual, and then only read up those parts of 112the interface which are unclear. 113 114 115File: gcrypt.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction 116 1171.2 Features 118============ 119 120Libgcrypt might have a couple of advantages over other libraries doing a 121similar job. 122 123It's Free Software 124 Anybody can use, modify, and redistribute it under the terms of the 125 GNU Lesser General Public License (*note Library Copying::). Note, 126 that some parts (which are in general not needed by applications) 127 are subject to the terms of the GNU General Public License (*note 128 Copying::); please see the README file of the distribution for of 129 list of these parts. 130 131It encapsulates the low level cryptography 132 Libgcrypt provides a high level interface to cryptographic building 133 blocks using an extensible and flexible API. 134 135 136File: gcrypt.info, Node: Overview, Prev: Features, Up: Introduction 137 1381.3 Overview 139============ 140 141The Libgcrypt library is fully thread-safe, where it makes sense to be 142thread-safe. Not thread-safe are some cryptographic functions that 143modify a certain context stored in handles. If the user really intents 144to use such functions from different threads on the same handle, he has 145to take care of the serialization of such functions himself. If not 146described otherwise, every function is thread-safe. 147 148 Libgcrypt depends on the library 'libgpg-error', which contains some 149common code used by other GnuPG components. 150 151 152File: gcrypt.info, Node: Preparation, Next: Generalities, Prev: Introduction, Up: Top 153 1542 Preparation 155************* 156 157To use Libgcrypt, you have to perform some changes to your sources and 158the build system. The necessary changes are small and explained in the 159following sections. At the end of this chapter, it is described how the 160library is initialized, and how the requirements of the library are 161verified. 162 163* Menu: 164 165* Header:: What header file you need to include. 166* Building sources:: How to build sources using the library. 167* Building sources using Automake:: How to build sources with the help of Automake. 168* Initializing the library:: How to initialize the library. 169* Multi-Threading:: How Libgcrypt can be used in a MT environment. 170* Enabling FIPS mode:: How to enable the FIPS mode. 171* Hardware features:: How to disable hardware features. 172 173 174File: gcrypt.info, Node: Header, Next: Building sources, Up: Preparation 175 1762.1 Header 177========== 178 179All interfaces (data types and functions) of the library are defined in 180the header file 'gcrypt.h'. You must include this in all source files 181using the library, either directly or through some other header file, 182like this: 183 184 #include <gcrypt.h> 185 186 The name space of Libgcrypt is 'gcry_*' for function and type names 187and 'GCRY*' for other symbols. In addition the same name prefixes with 188one prepended underscore are reserved for internal use and should never 189be used by an application. Note that Libgcrypt uses libgpg-error, which 190uses 'gpg_*' as name space for function and type names and 'GPG_*' for 191other symbols, including all the error codes. 192 193Certain parts of gcrypt.h may be excluded by defining these macros: 194 195'GCRYPT_NO_MPI_MACROS' 196 Do not define the shorthand macros 'mpi_*' for 'gcry_mpi_*'. 197 198'GCRYPT_NO_DEPRECATED' 199 Do not include definitions for deprecated features. This is useful 200 to make sure that no deprecated features are used. 201 202 203File: gcrypt.info, Node: Building sources, Next: Building sources using Automake, Prev: Header, Up: Preparation 204 2052.2 Building sources 206==================== 207 208If you want to compile a source file including the 'gcrypt.h' header 209file, you must make sure that the compiler can find it in the directory 210hierarchy. This is accomplished by adding the path to the directory in 211which the header file is located to the compilers include file search 212path (via the '-I' option). 213 214 However, the path to the include file is determined at the time the 215source is configured. To solve this problem, Libgcrypt ships with a 216small helper program 'libgcrypt-config' that knows the path to the 217include file and other configuration options. The options that need to 218be added to the compiler invocation at compile time are output by the 219'--cflags' option to 'libgcrypt-config'. The following example shows 220how it can be used at the command line: 221 222 gcc -c foo.c `libgcrypt-config --cflags` 223 224 Adding the output of 'libgcrypt-config --cflags' to the compiler’s 225command line will ensure that the compiler can find the Libgcrypt header 226file. 227 228 A similar problem occurs when linking the program with the library. 229Again, the compiler has to find the library files. For this to work, 230the path to the library files has to be added to the library search path 231(via the '-L' option). For this, the option '--libs' to 232'libgcrypt-config' can be used. For convenience, this option also 233outputs all other options that are required to link the program with the 234Libgcrypt libraries (in particular, the '-lgcrypt' option). The example 235shows how to link 'foo.o' with the Libgcrypt library to a program 'foo'. 236 237 gcc -o foo foo.o `libgcrypt-config --libs` 238 239 Of course you can also combine both examples to a single command by 240specifying both options to 'libgcrypt-config': 241 242 gcc -o foo foo.c `libgcrypt-config --cflags --libs` 243 244 245File: gcrypt.info, Node: Building sources using Automake, Next: Initializing the library, Prev: Building sources, Up: Preparation 246 2472.3 Building sources using Automake 248=================================== 249 250It is much easier if you use GNU Automake instead of writing your own 251Makefiles. If you do that, you do not have to worry about finding and 252invoking the 'libgcrypt-config' script at all. Libgcrypt provides an 253extension to Automake that does all the work for you. 254 255 -- Macro: AM_PATH_LIBGCRYPT ([MINIMUM-VERSION], [ACTION-IF-FOUND], 256 [ACTION-IF-NOT-FOUND]) 257 Check whether Libgcrypt (at least version MINIMUM-VERSION, if 258 given) exists on the host system. If it is found, execute 259 ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. 260 261 Additionally, the function defines 'LIBGCRYPT_CFLAGS' to the flags 262 needed for compilation of the program to find the 'gcrypt.h' header 263 file, and 'LIBGCRYPT_LIBS' to the linker flags needed to link the 264 program to the Libgcrypt library. If the used helper script does 265 not match the target type you are building for a warning is printed 266 and the string 'libgcrypt' is appended to the variable 267 'gpg_config_script_warn'. 268 269 This macro searches for 'libgcrypt-config' along the PATH. If you 270 are cross-compiling, it is useful to set the environment variable 271 'SYSROOT' to the top directory of your target. The macro will then 272 first look for the helper program in the 'bin' directory below that 273 top directory. An absolute directory name must be used for 274 'SYSROOT'. Finally, if the configure command line option 275 '--with-libgcrypt-prefix' is used, only its value is used for the 276 top directory below which the helper script is expected. 277 278 You can use the defined Autoconf variables like this in your 279'Makefile.am': 280 281 AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS) 282 LDADD = $(LIBGCRYPT_LIBS) 283 284 285File: gcrypt.info, Node: Initializing the library, Next: Multi-Threading, Prev: Building sources using Automake, Up: Preparation 286 2872.4 Initializing the library 288============================ 289 290Before the library can be used, it must initialize itself. This is 291achieved by invoking the function 'gcry_check_version' described below. 292 293 Also, it is often desirable to check that the version of Libgcrypt 294used is indeed one which fits all requirements. Even with binary 295compatibility, new features may have been introduced, but due to problem 296with the dynamic linker an old version may actually be used. So you may 297want to check that the version is okay right after program startup. 298 299 -- Function: const char * gcry_check_version (const char *REQ_VERSION) 300 301 The function 'gcry_check_version' initializes some subsystems used 302 by Libgcrypt and must be invoked before any other function in the 303 library. *Note Multi-Threading::. 304 305 Furthermore, this function returns the version number of the 306 library. It can also verify that the version number is higher than 307 a certain required version number REQ_VERSION, if this value is not 308 a null pointer. 309 310 Libgcrypt uses a concept known as secure memory, which is a region of 311memory set aside for storing sensitive data. Because such memory is a 312scarce resource, it needs to be setup in advanced to a fixed size. 313Further, most operating systems have special requirements on how that 314secure memory can be used. For example, it might be required to install 315an application as "setuid(root)" to allow allocating such memory. 316Libgcrypt requires a sequence of initialization steps to make sure that 317this works correctly. The following examples show the necessary steps. 318 319 If you don't have a need for secure memory, for example if your 320application does not use secret keys or other confidential data or it 321runs in a controlled environment where key material floating around in 322memory is not a problem, you should initialize Libgcrypt this way: 323 324 /* Version check should be the very first call because it 325 makes sure that important subsystems are initialized. 326 #define NEED_LIBGCRYPT_VERSION to the minimum required version. */ 327 if (!gcry_check_version (NEED_LIBGCRYPT_VERSION)) 328 { 329 fprintf (stderr, "libgcrypt is too old (need %s, have %s)\n", 330 NEED_LIBGCRYPT_VERSION, gcry_check_version (NULL)); 331 exit (2); 332 } 333 334 /* Disable secure memory. */ 335 gcry_control (GCRYCTL_DISABLE_SECMEM, 0); 336 337 /* ... If required, other initialization goes here. */ 338 339 /* Tell Libgcrypt that initialization has completed. */ 340 gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0); 341 342 If you have to protect your keys or other information in memory 343against being swapped out to disk and to enable an automatic overwrite 344of used and freed memory, you need to initialize Libgcrypt this way: 345 346 /* Version check should be the very first call because it 347 makes sure that important subsystems are initialized. 348 #define NEED_LIBGCRYPT_VERSION to the minimum required version. */ 349 if (!gcry_check_version (NEED_LIBGCRYPT_VERSION)) 350 { 351 fprintf (stderr, "libgcrypt is too old (need %s, have %s)\n", 352 NEED_LIBGCRYPT_VERSION, gcry_check_version (NULL)); 353 exit (2); 354 } 355 356 /* We don't want to see any warnings, e.g. because we have not yet 357 parsed program options which might be used to suppress such 358 warnings. */ 359 gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN); 360 361 /* ... If required, other initialization goes here. Note that the 362 process might still be running with increased privileges and that 363 the secure memory has not been initialized. */ 364 365 /* Allocate a pool of 16k secure memory. This makes the secure memory 366 available and also drops privileges where needed. Note that by 367 using functions like gcry_xmalloc_secure and gcry_mpi_snew Libgcrypt 368 may expand the secure memory pool with memory which lacks the 369 property of not being swapped out to disk. */ 370 gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0); 371 372 /* It is now okay to let Libgcrypt complain when there was/is 373 a problem with the secure memory. */ 374 gcry_control (GCRYCTL_RESUME_SECMEM_WARN); 375 376 /* ... If required, other initialization goes here. */ 377 378 /* Tell Libgcrypt that initialization has completed. */ 379 gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0); 380 381 It is important that these initialization steps are not done by a 382library but by the actual application. A library using Libgcrypt might 383want to check for finished initialization using: 384 385 if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P)) 386 { 387 fputs ("libgcrypt has not been initialized\n", stderr); 388 abort (); 389 } 390 391 Instead of terminating the process, the library may instead print a 392warning and try to initialize Libgcrypt itself. See also the section on 393multi-threading below for more pitfalls. 394 395 396File: gcrypt.info, Node: Multi-Threading, Next: Enabling FIPS mode, Prev: Initializing the library, Up: Preparation 397 3982.5 Multi-Threading 399=================== 400 401As mentioned earlier, the Libgcrypt library is thread-safe if you adhere 402to the following requirements: 403 404 * If you use pthread and your applications forks and does not 405 directly call exec (even calling stdio functions), all kind of 406 problems may occur. Future versions of Libgcrypt will try to 407 cleanup using pthread_atfork but even that may lead to problems. 408 This is a common problem with almost all applications using pthread 409 and fork. 410 411 * The function 'gcry_check_version' must be called before any other 412 function in the library. To achieve this in multi-threaded 413 programs, you must synchronize the memory with respect to other 414 threads that also want to use Libgcrypt. For this, it is 415 sufficient to call 'gcry_check_version' before creating the other 416 threads using Libgcrypt(1). 417 418 * Just like the function 'gpg_strerror', the function 'gcry_strerror' 419 is not thread safe. You have to use 'gpg_strerror_r' instead. 420 421 ---------- Footnotes ---------- 422 423 (1) At least this is true for POSIX threads, as 'pthread_create' is a 424function that synchronizes memory with respects to other threads. There 425are many functions which have this property, a complete list can be 426found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the 427definition of the term "Memory Synchronization". For other thread 428packages, more relaxed or more strict rules may apply. 429 430 431File: gcrypt.info, Node: Enabling FIPS mode, Next: Hardware features, Prev: Multi-Threading, Up: Preparation 432 4332.6 How to enable the FIPS mode 434=============================== 435 436Libgcrypt may be used in a FIPS 140-2 mode. Note, that this does not 437necessary mean that Libcgrypt is an appoved FIPS 140-2 module. Check 438the NIST database at <http://csrc.nist.gov/groups/STM/cmvp/> to see what 439versions of Libgcrypt are approved. 440 441 Because FIPS 140 has certain restrictions on the use of cryptography 442which are not always wanted, Libgcrypt needs to be put into FIPS mode 443explicitly. Three alternative mechanisms are provided to switch 444Libgcrypt into this mode: 445 446 * If the file '/proc/sys/crypto/fips_enabled' exists and contains a 447 numeric value other than '0', Libgcrypt is put into FIPS mode at 448 initialization time. Obviously this works only on systems with a 449 'proc' file system (i.e. GNU/Linux). 450 451 * If the file '/etc/gcrypt/fips_enabled' exists, Libgcrypt is put 452 into FIPS mode at initialization time. Note that this filename is 453 hardwired and does not depend on any configuration options. 454 455 * If the application requests FIPS mode using the control command 456 'GCRYCTL_FORCE_FIPS_MODE'. This must be done prior to any 457 initialization (i.e. before 'gcry_check_version'). 458 459 In addition to the standard FIPS mode, Libgcrypt may also be put into 460an Enforced FIPS mode by writing a non-zero value into the file 461'/etc/gcrypt/fips_enabled' or by using the control command 462'GCRYCTL_SET_ENFORCED_FIPS_FLAG' before any other calls to libgcrypt. 463The Enforced FIPS mode helps to detect applications which don't fulfill 464all requirements for using Libgcrypt in FIPS mode (*note FIPS Mode::). 465 466 Once Libgcrypt has been put into FIPS mode, it is not possible to 467switch back to standard mode without terminating the process first. If 468the logging verbosity level of Libgcrypt has been set to at least 2, the 469state transitions and the self-tests are logged. 470 471 472File: gcrypt.info, Node: Hardware features, Prev: Enabling FIPS mode, Up: Preparation 473 4742.7 How to disable hardware features 475==================================== 476 477Libgcrypt makes use of certain hardware features. If the use of a 478feature is not desired it may be either be disabled by a program or 479globally using a configuration file. The currently supported features 480are 481 482'padlock-rng' 483'padlock-aes' 484'padlock-sha' 485'padlock-mmul' 486'intel-cpu' 487'intel-fast-shld' 488'intel-bmi2' 489'intel-ssse3' 490'intel-sse4.1' 491'intel-pclmul' 492'intel-aesni' 493'intel-rdrand' 494'intel-avx' 495'intel-avx2' 496'intel-fast-vpgather' 497'intel-rdtsc' 498'intel-shaext' 499'arm-neon' 500'arm-aes' 501'arm-sha1' 502'arm-sha2' 503'arm-pmull' 504 505 To disable a feature for all processes using Libgcrypt 1.6 or newer, 506create the file '/etc/gcrypt/hwf.deny' and put each feature not to be 507used on a single line. Empty lines, white space, and lines prefixed 508with a hash mark are ignored. The file should be world readable. 509 510 To disable a feature specifically for a program that program must 511tell it Libgcrypt before before calling 'gcry_check_version'. 512Example:(1) 513 514 gcry_control (GCRYCTL_DISABLE_HWF, "intel-rdrand", NULL); 515 516To print the list of active features you may use this command: 517 518 mpicalc --print-config | grep ^hwflist: | tr : '\n' | tail -n +2 519 520 ---------- Footnotes ---------- 521 522 (1) NB. Libgcrypt uses the RDRAND feature only as one source of 523entropy. A CPU with a broken RDRAND will thus not compromise of the 524random number generator 525 526 527File: gcrypt.info, Node: Generalities, Next: Handler Functions, Prev: Preparation, Up: Top 528 5293 Generalities 530************** 531 532* Menu: 533 534* Controlling the library:: Controlling Libgcrypt's behavior. 535* Error Handling:: Error codes and such. 536 537 538File: gcrypt.info, Node: Controlling the library, Next: Error Handling, Up: Generalities 539 5403.1 Controlling the library 541=========================== 542 543 -- Function: gcry_error_t gcry_control (enum gcry_ctl_cmds CMD, ...) 544 545 This function can be used to influence the general behavior of 546 Libgcrypt in several ways. Depending on CMD, more arguments can or 547 have to be provided. 548 549 'GCRYCTL_ENABLE_M_GUARD; Arguments: none' 550 This command enables the built-in memory guard. It must not 551 be used to activate the memory guard after the memory 552 management has already been used; therefore it can ONLY be 553 used before 'gcry_check_version'. Note that the memory guard 554 is NOT used when the user of the library has set his own 555 memory management callbacks. 556 557 'GCRYCTL_ENABLE_QUICK_RANDOM; Arguments: none' 558 This command inhibits the use the very secure random quality 559 level ('GCRY_VERY_STRONG_RANDOM') and degrades all request 560 down to 'GCRY_STRONG_RANDOM'. In general this is not 561 recommended. However, for some applications the extra quality 562 random Libgcrypt tries to create is not justified and this 563 option may help to get better performance. Please check with 564 a crypto expert whether this option can be used for your 565 application. 566 567 This option can only be used at initialization time. 568 569 'GCRYCTL_DUMP_RANDOM_STATS; Arguments: none' 570 This command dumps random number generator related statistics 571 to the library's logging stream. 572 573 'GCRYCTL_DUMP_MEMORY_STATS; Arguments: none' 574 This command dumps memory management related statistics to the 575 library's logging stream. 576 577 'GCRYCTL_DUMP_SECMEM_STATS; Arguments: none' 578 This command dumps secure memory management related statistics 579 to the library's logging stream. 580 581 'GCRYCTL_DROP_PRIVS; Arguments: none' 582 This command disables the use of secure memory and drops the 583 privileges of the current process. This command has not much 584 use; the suggested way to disable secure memory is to use 585 'GCRYCTL_DISABLE_SECMEM' right after initialization. 586 587 'GCRYCTL_DISABLE_SECMEM; Arguments: none' 588 This command disables the use of secure memory. If this 589 command is used in FIPS mode, FIPS mode will be disabled and 590 the function 'gcry_fips_mode_active' returns false. However, 591 in Enforced FIPS mode this command has no effect at all. 592 593 Many applications do not require secure memory, so they should 594 disable it right away. This command should be executed right 595 after 'gcry_check_version'. 596 597 'GCRYCTL_DISABLE_LOCKED_SECMEM; Arguments: none' 598 This command disables the use of the mlock call for secure 599 memory. Disabling the use of mlock may for example be done if 600 an encrypted swap space is in use. This command should be 601 executed right after 'gcry_check_version'. Note that by using 602 functions like gcry_xmalloc_secure and gcry_mpi_snew Libgcrypt 603 may expand the secure memory pool with memory which lacks the 604 property of not being swapped out to disk (but will still be 605 zeroed out on free). 606 607 'GCRYCTL_DISABLE_PRIV_DROP; Arguments: none' 608 This command sets a global flag to tell the secure memory 609 subsystem that it shall not drop privileges after secure 610 memory has been allocated. This command is commonly used 611 right after 'gcry_check_version' but may also be used right 612 away at program startup. It won't have an effect after the 613 secure memory pool has been initialized. WARNING: A process 614 running setuid(root) is a severe security risk. Processes 615 making use of Libgcrypt or other complex code should drop 616 these extra privileges as soon as possible. If this command 617 has been used the caller is responsible for dropping the 618 privileges. 619 620 'GCRYCTL_INIT_SECMEM; Arguments: unsigned int nbytes' 621 This command is used to allocate a pool of secure memory and 622 thus enabling the use of secure memory. It also drops all 623 extra privileges the process has (i.e. if it is run as setuid 624 (root)). If the argument NBYTES is 0, secure memory will be 625 disabled. The minimum amount of secure memory allocated is 626 currently 16384 bytes; you may thus use a value of 1 to 627 request that default size. 628 629 'GCRYCTL_AUTO_EXPAND_SECMEM; Arguments: unsigned int chunksize' 630 This command enables on-the-fly expanding of the secure memory 631 area. Note that by using functions like 'gcry_xmalloc_secure' 632 and 'gcry_mpi_snew' will do this auto expanding anyway. The 633 argument to this option is the suggested size for new secure 634 memory areas. A larger size improves performance of all 635 memory allocation and releasing functions. The given 636 chunksize is rounded up to the next 32KiB. The drawback of 637 auto expanding is that memory might be swapped out to disk; 638 this can be fixed by configuring the system to use an 639 encrypted swap space. 640 641 'GCRYCTL_TERM_SECMEM; Arguments: none' 642 This command zeroises the secure memory and destroys the 643 handler. The secure memory pool may not be used anymore after 644 running this command. If the secure memory pool as already 645 been destroyed, this command has no effect. Applications 646 might want to run this command from their exit handler to make 647 sure that the secure memory gets properly destroyed. This 648 command is not necessarily thread-safe but that should not be 649 needed in cleanup code. It may be called from a signal 650 handler. 651 652 'GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none' 653 Disable warning messages about problems with the secure memory 654 subsystem. This command should be run right after 655 'gcry_check_version'. 656 657 'GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none' 658 Postpone warning messages from the secure memory subsystem. 659 *Note the initialization example: sample-use-suspend-secmem, 660 on how to use it. 661 662 'GCRYCTL_RESUME_SECMEM_WARN; Arguments: none' 663 Resume warning messages from the secure memory subsystem. 664 *Note the initialization example: sample-use-resume-secmem, on 665 how to use it. 666 667 'GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none' 668 This command tells the PRNG to store random numbers in secure 669 memory. This command should be run right after 670 'gcry_check_version' and not later than the command 671 GCRYCTL_INIT_SECMEM. Note that in FIPS mode the secure memory 672 is always used. 673 674 'GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename' 675 This command specifies the file, which is to be used as seed 676 file for the PRNG. If the seed file is registered prior to 677 initialization of the PRNG, the seed file's content (if it 678 exists and seems to be valid) is fed into the PRNG pool. 679 After the seed file has been registered, the PRNG can be 680 signalled to write out the PRNG pool's content into the seed 681 file with the following command. 682 683 'GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none' 684 Write out the PRNG pool's content into the registered seed 685 file. 686 687 Multiple instances of the applications sharing the same random 688 seed file can be started in parallel, in which case they will 689 read out the same pool and then race for updating it (the last 690 update overwrites earlier updates). They will differentiate 691 only by the weak entropy that is added in read_seed_file based 692 on the PID and clock, and up to 16 bytes of weak random 693 non-blockingly. The consequence is that the output of these 694 different instances is correlated to some extent. In a 695 perfect attack scenario, the attacker can control (or at least 696 guess) the PID and clock of the application, and drain the 697 system's entropy pool to reduce the "up to 16 bytes" above to 698 0. Then the dependencies of the initial states of the pools 699 are completely known. Note that this is not an issue if 700 random of 'GCRY_VERY_STRONG_RANDOM' quality is requested as in 701 this case enough extra entropy gets mixed. It is also not an 702 issue when using Linux (rndlinux driver), because this one 703 guarantees to read full 16 bytes from /dev/urandom and thus 704 there is no way for an attacker without kernel access to 705 control these 16 bytes. 706 707 'GCRYCTL_CLOSE_RANDOM_DEVICE; Arguments: none' 708 Try to close the random device. If on Unix system you call 709 fork(), the child process does no call exec(), and you do not 710 intend to use Libgcrypt in the child, it might be useful to 711 use this control code to close the inherited file descriptors 712 of the random device. If Libgcrypt is later used again by the 713 child, the device will be re-opened. On non-Unix systems this 714 control code is ignored. 715 716 'GCRYCTL_SET_VERBOSITY; Arguments: int level' 717 This command sets the verbosity of the logging. A level of 0 718 disables all extra logging whereas positive numbers enable 719 more verbose logging. The level may be changed at any time 720 but be aware that no memory synchronization is done so the 721 effect of this command might not immediately show up in other 722 threads. This command may even be used prior to 723 'gcry_check_version'. 724 725 'GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags' 726 Set the debug flag bits as given by the argument. Be aware 727 that no memory synchronization is done so the effect of this 728 command might not immediately show up in other threads. The 729 debug flags are not considered part of the API and thus may 730 change without notice. As of now bit 0 enables debugging of 731 cipher functions and bit 1 debugging of 732 multi-precision-integers. This command may even be used prior 733 to 'gcry_check_version'. 734 735 'GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags' 736 Set the debug flag bits as given by the argument. Be aware 737 that that no memory synchronization is done so the effect of 738 this command might not immediately show up in other threads. 739 This command may even be used prior to 'gcry_check_version'. 740 741 'GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none' 742 This command does nothing. It exists only for backward 743 compatibility. 744 745 'GCRYCTL_ANY_INITIALIZATION_P; Arguments: none' 746 This command returns true if the library has been basically 747 initialized. Such a basic initialization happens implicitly 748 with many commands to get certain internal subsystems running. 749 The common and suggested way to do this basic initialization 750 is by calling gcry_check_version. 751 752 'GCRYCTL_INITIALIZATION_FINISHED; Arguments: none' 753 This command tells the library that the application has 754 finished the initialization. 755 756 'GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none' 757 This command returns true if the command 758 GCRYCTL_INITIALIZATION_FINISHED has already been run. 759 760 'GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops' 761 This command is obsolete since version 1.6. 762 763 'GCRYCTL_FAST_POLL; Arguments: none' 764 Run a fast random poll. 765 766 'GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename' 767 This command may be used to override the default name of the 768 EGD socket to connect to. It may be used only during 769 initialization as it is not thread safe. Changing the socket 770 name again is not supported. The function may return an error 771 if the given filename is too long for a local socket name. 772 773 EGD is an alternative random gatherer, used only on systems 774 lacking a proper random device. 775 776 'GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream' 777 This command dumps information pertaining to the configuration 778 of the library to the given stream. If NULL is given for 779 STREAM, the log system is used. This command may be used 780 before the initialization has been finished but not before a 781 'gcry_check_version'. Note that the macro 'estream_t' can be 782 used instead of 'gpgrt_stream_t'. 783 784 'GCRYCTL_OPERATIONAL_P; Arguments: none' 785 This command returns true if the library is in an operational 786 state. This information makes only sense in FIPS mode. In 787 contrast to other functions, this is a pure test function and 788 won't put the library into FIPS mode or change the internal 789 state. This command may be used before the initialization has 790 been finished but not before a 'gcry_check_version'. 791 792 'GCRYCTL_FIPS_MODE_P; Arguments: none' 793 This command returns true if the library is in FIPS mode. 794 Note, that this is no indication about the current state of 795 the library. This command may be used before the 796 initialization has been finished but not before a 797 'gcry_check_version'. An application may use this command or 798 the convenience macro below to check whether FIPS mode is 799 actually active. 800 801 -- Function: int gcry_fips_mode_active (void) 802 803 Returns true if the FIPS mode is active. Note that this 804 is implemented as a macro. 805 806 'GCRYCTL_FORCE_FIPS_MODE; Arguments: none' 807 Running this command puts the library into FIPS mode. If the 808 library is already in FIPS mode, a self-test is triggered and 809 thus the library will be put into operational state. This 810 command may be used before a call to 'gcry_check_version' and 811 that is actually the recommended way to let an application 812 switch the library into FIPS mode. Note that Libgcrypt will 813 reject an attempt to switch to fips mode during or after the 814 initialization. 815 816 'GCRYCTL_SET_ENFORCED_FIPS_FLAG; Arguments: none' 817 Running this command sets the internal flag that puts the 818 library into the enforced FIPS mode during the FIPS mode 819 initialization. This command does not affect the library if 820 the library is not put into the FIPS mode and it must be used 821 before any other libgcrypt library calls that initialize the 822 library such as 'gcry_check_version'. Note that Libgcrypt 823 will reject an attempt to switch to the enforced fips mode 824 during or after the initialization. 825 826 'GCRYCTL_SET_PREFERRED_RNG_TYPE; Arguments: int' 827 These are advisory commands to select a certain random number 828 generator. They are only advisory because libraries may not 829 know what an application actually wants or vice versa. Thus 830 Libgcrypt employs a priority check to select the actually used 831 RNG. If an applications selects a lower priority RNG but a 832 library requests a higher priority RNG Libgcrypt will switch 833 to the higher priority RNG. Applications and libraries should 834 use these control codes before 'gcry_check_version'. The 835 available generators are: 836 'GCRY_RNG_TYPE_STANDARD' 837 A conservative standard generator based on the 838 "Continuously Seeded Pseudo Random Number Generator" 839 designed by Peter Gutmann. 840 'GCRY_RNG_TYPE_FIPS' 841 A deterministic random number generator conforming to he 842 document "NIST-Recommended Random Number Generator Based 843 on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES 844 and AES Algorithms" (2005-01-31). This implementation 845 uses the AES variant. 846 'GCRY_RNG_TYPE_SYSTEM' 847 A wrapper around the system's native RNG. On Unix system 848 these are usually the /dev/random and /dev/urandom 849 devices. 850 The default is 'GCRY_RNG_TYPE_STANDARD' unless FIPS mode as 851 been enabled; in which case 'GCRY_RNG_TYPE_FIPS' is used and 852 locked against further changes. 853 854 'GCRYCTL_GET_CURRENT_RNG_TYPE; Arguments: int *' 855 This command stores the type of the currently used RNG as an 856 integer value at the provided address. 857 858 'GCRYCTL_SELFTEST; Arguments: none' 859 This may be used at anytime to have the library run all 860 implemented self-tests. It works in standard and in FIPS 861 mode. Returns 0 on success or an error code on failure. 862 863 'GCRYCTL_DISABLE_HWF; Arguments: const char *name' 864 865 Libgcrypt detects certain features of the CPU at startup time. 866 For performance tests it is sometimes required not to use such 867 a feature. This option may be used to disable a certain 868 feature; i.e. Libgcrypt behaves as if this feature has not 869 been detected. This call can be used several times to disable 870 a set of features, or features may be given as a colon or 871 comma delimited string. The special feature "all" can be used 872 to disable all available features. 873 874 Note that the detection code might be run if the feature has 875 been disabled. This command must be used at initialization 876 time; i.e. before calling 'gcry_check_version'. 877 878 'GCRYCTL_REINIT_SYSCALL_CLAMP; Arguments: none' 879 880 Libgcrypt wraps blocking system calls with two functions calls 881 ("system call clamp") to give user land threading libraries a 882 hook for re-scheduling. This works by reading the system call 883 clamp from Libgpg-error at initialization time. However 884 sometimes Libgcrypt needs to be initialized before the user 885 land threading systems and at that point the system call clamp 886 has not been registered with Libgpg-error and in turn 887 Libgcrypt would not use them. The control code can be used to 888 tell Libgcrypt that a system call clamp has now been 889 registered with Libgpg-error and advise Libgcrypt to read the 890 clamp again. Obviously this control code may only be used 891 before a second thread is started in a process. 892 893 894File: gcrypt.info, Node: Error Handling, Prev: Controlling the library, Up: Generalities 895 8963.2 Error Handling 897================== 898 899Many functions in Libgcrypt can return an error if they fail. For this 900reason, the application should always catch the error condition and take 901appropriate measures, for example by releasing the resources and passing 902the error up to the caller, or by displaying a descriptive message to 903the user and cancelling the operation. 904 905 Some error values do not indicate a system error or an error in the 906operation, but the result of an operation that failed properly. For 907example, if you try to decrypt a tempered message, the decryption will 908fail. Another error value actually means that the end of a data buffer 909or list has been reached. The following descriptions explain for many 910error codes what they mean usually. Some error values have specific 911meanings if returned by a certain functions. Such cases are described 912in the documentation of those functions. 913 914 Libgcrypt uses the 'libgpg-error' library. This allows to share the 915error codes with other components of the GnuPG system, and to pass error 916values transparently from the crypto engine, or some helper application 917of the crypto engine, to the user. This way no information is lost. As 918a consequence, Libgcrypt does not use its own identifiers for error 919codes, but uses those provided by 'libgpg-error'. They usually start 920with 'GPG_ERR_'. 921 922 However, Libgcrypt does provide aliases for the functions defined in 923libgpg-error, which might be preferred for name space consistency. 924 925 Most functions in Libgcrypt return an error code in the case of 926failure. For this reason, the application should always catch the error 927condition and take appropriate measures, for example by releasing the 928resources and passing the error up to the caller, or by displaying a 929descriptive message to the user and canceling the operation. 930 931 Some error values do not indicate a system error or an error in the 932operation, but the result of an operation that failed properly. 933 934 GnuPG components, including Libgcrypt, use an extra library named 935libgpg-error to provide a common error handling scheme. For more 936information on libgpg-error, see the according manual. 937 938* Menu: 939 940* Error Values:: The error value and what it means. 941* Error Sources:: A list of important error sources. 942* Error Codes:: A list of important error codes. 943* Error Strings:: How to get a descriptive string from a value. 944 945 946File: gcrypt.info, Node: Error Values, Next: Error Sources, Up: Error Handling 947 9483.2.1 Error Values 949------------------ 950 951 -- Data type: gcry_err_code_t 952 The 'gcry_err_code_t' type is an alias for the 'libgpg-error' type 953 'gpg_err_code_t'. The error code indicates the type of an error, 954 or the reason why an operation failed. 955 956 A list of important error codes can be found in the next section. 957 958 -- Data type: gcry_err_source_t 959 The 'gcry_err_source_t' type is an alias for the 'libgpg-error' 960 type 'gpg_err_source_t'. The error source has not a precisely 961 defined meaning. Sometimes it is the place where the error 962 happened, sometimes it is the place where an error was encoded into 963 an error value. Usually the error source will give an indication 964 to where to look for the problem. This is not always true, but it 965 is attempted to achieve this goal. 966 967 A list of important error sources can be found in the next section. 968 969 -- Data type: gcry_error_t 970 The 'gcry_error_t' type is an alias for the 'libgpg-error' type 971 'gpg_error_t'. An error value like this has always two components, 972 an error code and an error source. Both together form the error 973 value. 974 975 Thus, the error value can not be directly compared against an error 976 code, but the accessor functions described below must be used. 977 However, it is guaranteed that only 0 is used to indicate success 978 ('GPG_ERR_NO_ERROR'), and that in this case all other parts of the 979 error value are set to 0, too. 980 981 Note that in Libgcrypt, the error source is used purely for 982 diagnostic purposes. Only the error code should be checked to test 983 for a certain outcome of a function. The manual only documents the 984 error code part of an error value. The error source is left 985 unspecified and might be anything. 986 987 -- Function: gcry_err_code_t gcry_err_code (gcry_error_t ERR) 988 The static inline function 'gcry_err_code' returns the 989 'gcry_err_code_t' component of the error value ERR. This function 990 must be used to extract the error code from an error value in order 991 to compare it with the 'GPG_ERR_*' error code macros. 992 993 -- Function: gcry_err_source_t gcry_err_source (gcry_error_t ERR) 994 The static inline function 'gcry_err_source' returns the 995 'gcry_err_source_t' component of the error value ERR. This 996 function must be used to extract the error source from an error 997 value in order to compare it with the 'GPG_ERR_SOURCE_*' error 998 source macros. 999 1000 -- Function: gcry_error_t gcry_err_make (gcry_err_source_t SOURCE, 1001 gcry_err_code_t CODE) 1002 The static inline function 'gcry_err_make' returns the error value 1003 consisting of the error source SOURCE and the error code CODE. 1004 1005 This function can be used in callback functions to construct an 1006 error value to return it to the library. 1007 1008 -- Function: gcry_error_t gcry_error (gcry_err_code_t CODE) 1009 The static inline function 'gcry_error' returns the error value 1010 consisting of the default error source and the error code CODE. 1011 1012 For GCRY applications, the default error source is 1013 'GPG_ERR_SOURCE_USER_1'. You can define 'GCRY_ERR_SOURCE_DEFAULT' 1014 before including 'gcrypt.h' to change this default. 1015 1016 This function can be used in callback functions to construct an 1017 error value to return it to the library. 1018 1019 The 'libgpg-error' library provides error codes for all system error 1020numbers it knows about. If ERR is an unknown error number, the error 1021code 'GPG_ERR_UNKNOWN_ERRNO' is used. The following functions can be 1022used to construct error values from system errno numbers. 1023 1024 -- Function: gcry_error_t gcry_err_make_from_errno 1025 (gcry_err_source_t SOURCE, int ERR) 1026 The function 'gcry_err_make_from_errno' is like 'gcry_err_make', 1027 but it takes a system error like 'errno' instead of a 1028 'gcry_err_code_t' error code. 1029 1030 -- Function: gcry_error_t gcry_error_from_errno (int ERR) 1031 The function 'gcry_error_from_errno' is like 'gcry_error', but it 1032 takes a system error like 'errno' instead of a 'gcry_err_code_t' 1033 error code. 1034 1035 Sometimes you might want to map system error numbers to error codes 1036directly, or map an error code representing a system error back to the 1037system error number. The following functions can be used to do that. 1038 1039 -- Function: gcry_err_code_t gcry_err_code_from_errno (int ERR) 1040 The function 'gcry_err_code_from_errno' returns the error code for 1041 the system error ERR. If ERR is not a known system error, the 1042 function returns 'GPG_ERR_UNKNOWN_ERRNO'. 1043 1044 -- Function: int gcry_err_code_to_errno (gcry_err_code_t ERR) 1045 The function 'gcry_err_code_to_errno' returns the system error for 1046 the error code ERR. If ERR is not an error code representing a 1047 system error, or if this system error is not defined on this 1048 system, the function returns '0'. 1049 1050 1051File: gcrypt.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling 1052 10533.2.2 Error Sources 1054------------------- 1055 1056The library 'libgpg-error' defines an error source for every component 1057of the GnuPG system. The error source part of an error value is not 1058well defined. As such it is mainly useful to improve the diagnostic 1059error message for the user. 1060 1061 If the error code part of an error value is '0', the whole error 1062value will be '0'. In this case the error source part is of course 1063'GPG_ERR_SOURCE_UNKNOWN'. 1064 1065 The list of error sources that might occur in applications using 1066Libgcrypt is: 1067 1068'GPG_ERR_SOURCE_UNKNOWN' 1069 The error source is not known. The value of this error source is 1070 '0'. 1071 1072'GPG_ERR_SOURCE_GPGME' 1073 The error source is GPGME itself. 1074 1075'GPG_ERR_SOURCE_GPG' 1076 The error source is GnuPG, which is the crypto engine used for the 1077 OpenPGP protocol. 1078 1079'GPG_ERR_SOURCE_GPGSM' 1080 The error source is GPGSM, which is the crypto engine used for the 1081 OpenPGP protocol. 1082 1083'GPG_ERR_SOURCE_GCRYPT' 1084 The error source is 'libgcrypt', which is used by crypto engines to 1085 perform cryptographic operations. 1086 1087'GPG_ERR_SOURCE_GPGAGENT' 1088 The error source is 'gpg-agent', which is used by crypto engines to 1089 perform operations with the secret key. 1090 1091'GPG_ERR_SOURCE_PINENTRY' 1092 The error source is 'pinentry', which is used by 'gpg-agent' to 1093 query the passphrase to unlock a secret key. 1094 1095'GPG_ERR_SOURCE_SCD' 1096 The error source is the SmartCard Daemon, which is used by 1097 'gpg-agent' to delegate operations with the secret key to a 1098 SmartCard. 1099 1100'GPG_ERR_SOURCE_KEYBOX' 1101 The error source is 'libkbx', a library used by the crypto engines 1102 to manage local keyrings. 1103 1104'GPG_ERR_SOURCE_USER_1' 1105'GPG_ERR_SOURCE_USER_2' 1106'GPG_ERR_SOURCE_USER_3' 1107'GPG_ERR_SOURCE_USER_4' 1108 These error sources are not used by any GnuPG component and can be 1109 used by other software. For example, applications using Libgcrypt 1110 can use them to mark error values coming from callback handlers. 1111 Thus 'GPG_ERR_SOURCE_USER_1' is the default for errors created with 1112 'gcry_error' and 'gcry_error_from_errno', unless you define 1113 'GCRY_ERR_SOURCE_DEFAULT' before including 'gcrypt.h'. 1114 1115 1116File: gcrypt.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling 1117 11183.2.3 Error Codes 1119----------------- 1120 1121The library 'libgpg-error' defines many error values. The following 1122list includes the most important error codes. 1123 1124'GPG_ERR_EOF' 1125 This value indicates the end of a list, buffer or file. 1126 1127'GPG_ERR_NO_ERROR' 1128 This value indicates success. The value of this error code is '0'. 1129 Also, it is guaranteed that an error value made from the error code 1130 '0' will be '0' itself (as a whole). This means that the error 1131 source information is lost for this error code, however, as this 1132 error code indicates that no error occurred, this is generally not 1133 a problem. 1134 1135'GPG_ERR_GENERAL' 1136 This value means that something went wrong, but either there is not 1137 enough information about the problem to return a more useful error 1138 value, or there is no separate error value for this type of 1139 problem. 1140 1141'GPG_ERR_ENOMEM' 1142 This value means that an out-of-memory condition occurred. 1143 1144'GPG_ERR_E...' 1145 System errors are mapped to GPG_ERR_EFOO where FOO is the symbol 1146 for the system error. 1147 1148'GPG_ERR_INV_VALUE' 1149 This value means that some user provided data was out of range. 1150 1151'GPG_ERR_UNUSABLE_PUBKEY' 1152 This value means that some recipients for a message were invalid. 1153 1154'GPG_ERR_UNUSABLE_SECKEY' 1155 This value means that some signers were invalid. 1156 1157'GPG_ERR_NO_DATA' 1158 This value means that data was expected where no data was found. 1159 1160'GPG_ERR_CONFLICT' 1161 This value means that a conflict of some sort occurred. 1162 1163'GPG_ERR_NOT_IMPLEMENTED' 1164 This value indicates that the specific function (or operation) is 1165 not implemented. This error should never happen. It can only 1166 occur if you use certain values or configuration options which do 1167 not work, but for which we think that they should work at some 1168 later time. 1169 1170'GPG_ERR_DECRYPT_FAILED' 1171 This value indicates that a decryption operation was unsuccessful. 1172 1173'GPG_ERR_WRONG_KEY_USAGE' 1174 This value indicates that a key is not used appropriately. 1175 1176'GPG_ERR_NO_SECKEY' 1177 This value indicates that no secret key for the user ID is 1178 available. 1179 1180'GPG_ERR_UNSUPPORTED_ALGORITHM' 1181 This value means a verification failed because the cryptographic 1182 algorithm is not supported by the crypto backend. 1183 1184'GPG_ERR_BAD_SIGNATURE' 1185 This value means a verification failed because the signature is 1186 bad. 1187 1188'GPG_ERR_NO_PUBKEY' 1189 This value means a verification failed because the public key is 1190 not available. 1191 1192'GPG_ERR_NOT_OPERATIONAL' 1193 This value means that the library is not yet in state which allows 1194 to use this function. This error code is in particular returned if 1195 Libgcrypt is operated in FIPS mode and the internal state of the 1196 library does not yet or not anymore allow the use of a service. 1197 1198 This error code is only available with newer libgpg-error versions, 1199 thus you might see "invalid error code" when passing this to 1200 'gpg_strerror'. The numeric value of this error code is 176. 1201 1202'GPG_ERR_USER_1' 1203'GPG_ERR_USER_2' 1204'...' 1205'GPG_ERR_USER_16' 1206 These error codes are not used by any GnuPG component and can be 1207 freely used by other software. Applications using Libgcrypt might 1208 use them to mark specific errors returned by callback handlers if 1209 no suitable error codes (including the system errors) for these 1210 errors exist already. 1211 1212 1213File: gcrypt.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling 1214 12153.2.4 Error Strings 1216------------------- 1217 1218 -- Function: const char * gcry_strerror (gcry_error_t ERR) 1219 The function 'gcry_strerror' returns a pointer to a statically 1220 allocated string containing a description of the error code 1221 contained in the error value ERR. This string can be used to 1222 output a diagnostic message to the user. 1223 1224 -- Function: const char * gcry_strsource (gcry_error_t ERR) 1225 The function 'gcry_strsource' returns a pointer to a statically 1226 allocated string containing a description of the error source 1227 contained in the error value ERR. This string can be used to 1228 output a diagnostic message to the user. 1229 1230 The following example illustrates the use of the functions described 1231above: 1232 1233 { 1234 gcry_cipher_hd_t handle; 1235 gcry_error_t err = 0; 1236 1237 err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, 1238 GCRY_CIPHER_MODE_CBC, 0); 1239 if (err) 1240 { 1241 fprintf (stderr, "Failure: %s/%s\n", 1242 gcry_strsource (err), 1243 gcry_strerror (err)); 1244 } 1245 } 1246 1247 1248File: gcrypt.info, Node: Handler Functions, Next: Symmetric cryptography, Prev: Generalities, Up: Top 1249 12504 Handler Functions 1251******************* 1252 1253Libgcrypt makes it possible to install so called 'handler functions', 1254which get called by Libgcrypt in case of certain events. 1255 1256* Menu: 1257 1258* Progress handler:: Using a progress handler function. 1259* Allocation handler:: Using special memory allocation functions. 1260* Error handler:: Using error handler functions. 1261* Logging handler:: Using a special logging function. 1262 1263 1264File: gcrypt.info, Node: Progress handler, Next: Allocation handler, Up: Handler Functions 1265 12664.1 Progress handler 1267==================== 1268 1269It is often useful to retrieve some feedback while long running 1270operations are performed. 1271 1272 -- Data type: gcry_handler_progress_t 1273 Progress handler functions have to be of the type 1274 'gcry_handler_progress_t', which is defined as: 1275 1276 'void (*gcry_handler_progress_t) (void *, const char *, int, int, 1277 int)' 1278 1279 The following function may be used to register a handler function for 1280this purpose. 1281 1282 -- Function: void gcry_set_progress_handler (gcry_handler_progress_t 1283 CB, void *CB_DATA) 1284 1285 This function installs CB as the 'Progress handler' function. It 1286 may be used only during initialization. CB must be defined as 1287 follows: 1288 1289 void 1290 my_progress_handler (void *CB_DATA, const char *WHAT, 1291 int PRINTCHAR, int CURRENT, int TOTAL) 1292 { 1293 /* Do something. */ 1294 } 1295 1296 A description of the arguments of the progress handler function 1297 follows. 1298 1299 CB_DATA 1300 The argument provided in the call to 1301 'gcry_set_progress_handler'. 1302 WHAT 1303 A string identifying the type of the progress output. The 1304 following values for WHAT are defined: 1305 1306 'need_entropy' 1307 Not enough entropy is available. TOTAL holds the number 1308 of required bytes. 1309 1310 'wait_dev_random' 1311 Waiting to re-open a random device. TOTAL gives the 1312 number of seconds until the next try. 1313 1314 'primegen' 1315 Values for PRINTCHAR: 1316 '\n' 1317 Prime generated. 1318 '!' 1319 Need to refresh the pool of prime numbers. 1320 '<, >' 1321 Number of bits adjusted. 1322 '^' 1323 Searching for a generator. 1324 '.' 1325 Fermat test on 10 candidates failed. 1326 ':' 1327 Restart with a new random value. 1328 '+' 1329 Rabin Miller test passed. 1330 1331 1332File: gcrypt.info, Node: Allocation handler, Next: Error handler, Prev: Progress handler, Up: Handler Functions 1333 13344.2 Allocation handler 1335====================== 1336 1337It is possible to make Libgcrypt use special memory allocation functions 1338instead of the built-in ones. 1339 1340 Memory allocation functions are of the following types: 1341 -- Data type: gcry_handler_alloc_t 1342 This type is defined as: 'void *(*gcry_handler_alloc_t) (size_t 1343 n)'. 1344 -- Data type: gcry_handler_secure_check_t 1345 This type is defined as: 'int *(*gcry_handler_secure_check_t) 1346 (const void *)'. 1347 -- Data type: gcry_handler_realloc_t 1348 This type is defined as: 'void *(*gcry_handler_realloc_t) (void *p, 1349 size_t n)'. 1350 -- Data type: gcry_handler_free_t 1351 This type is defined as: 'void *(*gcry_handler_free_t) (void *)'. 1352 1353 Special memory allocation functions can be installed with the 1354following function: 1355 1356 -- Function: void gcry_set_allocation_handler (gcry_handler_alloc_t 1357 FUNC_ALLOC, gcry_handler_alloc_t FUNC_ALLOC_SECURE, 1358 gcry_handler_secure_check_t FUNC_SECURE_CHECK, 1359 gcry_handler_realloc_t FUNC_REALLOC, gcry_handler_free_t 1360 FUNC_FREE) 1361 Install the provided functions and use them instead of the built-in 1362 functions for doing memory allocation. Using this function is in 1363 general not recommended because the standard Libgcrypt allocation 1364 functions are guaranteed to zeroize memory if needed. 1365 1366 This function may be used only during initialization and may not be 1367 used in fips mode. 1368 1369 1370File: gcrypt.info, Node: Error handler, Next: Logging handler, Prev: Allocation handler, Up: Handler Functions 1371 13724.3 Error handler 1373================= 1374 1375The following functions may be used to register handler functions that 1376are called by Libgcrypt in case certain error conditions occur. They 1377may and should be registered prior to calling 'gcry_check_version'. 1378 1379 -- Data type: gcry_handler_no_mem_t 1380 This type is defined as: 'int (*gcry_handler_no_mem_t) (void *, 1381 size_t, unsigned int)' 1382 -- Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t 1383 FUNC_NO_MEM, void *CB_DATA) 1384 This function registers FUNC_NO_MEM as 'out-of-core handler', which 1385 means that it will be called in the case of not having enough 1386 memory available. The handler is called with 3 arguments: The 1387 first one is the pointer CB_DATA as set with this function, the 1388 second is the requested memory size and the last being a flag. If 1389 bit 0 of the flag is set, secure memory has been requested. The 1390 handler should either return true to indicate that Libgcrypt should 1391 try again allocating memory or return false to let Libgcrypt use 1392 its default fatal error handler. 1393 1394 -- Data type: gcry_handler_error_t 1395 This type is defined as: 'void (*gcry_handler_error_t) (void *, 1396 int, const char *)' 1397 1398 -- Function: void gcry_set_fatalerror_handler (gcry_handler_error_t 1399 FUNC_ERROR, void *CB_DATA) 1400 This function registers FUNC_ERROR as 'error handler', which means 1401 that it will be called in error conditions. 1402 1403 1404File: gcrypt.info, Node: Logging handler, Prev: Error handler, Up: Handler Functions 1405 14064.4 Logging handler 1407=================== 1408 1409 -- Data type: gcry_handler_log_t 1410 This type is defined as: 'void (*gcry_handler_log_t) (void *, int, 1411 const char *, va_list)' 1412 1413 -- Function: void gcry_set_log_handler (gcry_handler_log_t FUNC_LOG, 1414 void *CB_DATA) 1415 This function registers FUNC_LOG as 'logging handler', which means 1416 that it will be called in case Libgcrypt wants to log a message. 1417 This function may and should be used prior to calling 1418 'gcry_check_version'. 1419 1420 1421File: gcrypt.info, Node: Symmetric cryptography, Next: Public Key cryptography, Prev: Handler Functions, Up: Top 1422 14235 Symmetric cryptography 1424************************ 1425 1426The cipher functions are used for symmetrical cryptography, i.e. 1427cryptography using a shared key. The programming model follows an 1428open/process/close paradigm and is in that similar to other building 1429blocks provided by Libgcrypt. 1430 1431* Menu: 1432 1433* Available ciphers:: List of ciphers supported by the library. 1434* Available cipher modes:: List of cipher modes supported by the library. 1435* Working with cipher handles:: How to perform operations related to cipher handles. 1436* General cipher functions:: General cipher functions independent of cipher handles. 1437 1438 1439File: gcrypt.info, Node: Available ciphers, Next: Available cipher modes, Up: Symmetric cryptography 1440 14415.1 Available ciphers 1442===================== 1443 1444'GCRY_CIPHER_NONE' 1445 This is not a real algorithm but used by some functions as error 1446 return. The value always evaluates to false. 1447 1448'GCRY_CIPHER_IDEA' 1449 This is the IDEA algorithm. 1450 1451'GCRY_CIPHER_3DES' 1452 Triple-DES with 3 Keys as EDE. The key size of this algorithm is 1453 168 bits but you have to pass 192 bits because the most significant 1454 bits of each byte are ignored. 1455 1456'GCRY_CIPHER_CAST5' 1457 CAST128-5 block cipher algorithm. The key size is 128 bits. 1458 1459'GCRY_CIPHER_BLOWFISH' 1460 The blowfish algorithm. The supported key sizes are 8 to 576 bits 1461 in 8 bit increments. 1462 1463'GCRY_CIPHER_SAFER_SK128' 1464 Reserved and not currently implemented. 1465 1466'GCRY_CIPHER_DES_SK' 1467 Reserved and not currently implemented. 1468 1469'GCRY_CIPHER_AES' 1470'GCRY_CIPHER_AES128' 1471'GCRY_CIPHER_RIJNDAEL' 1472'GCRY_CIPHER_RIJNDAEL128' 1473 AES (Rijndael) with a 128 bit key. 1474 1475'GCRY_CIPHER_AES192' 1476'GCRY_CIPHER_RIJNDAEL192' 1477 AES (Rijndael) with a 192 bit key. 1478 1479'GCRY_CIPHER_AES256' 1480'GCRY_CIPHER_RIJNDAEL256' 1481 AES (Rijndael) with a 256 bit key. 1482 1483'GCRY_CIPHER_TWOFISH' 1484 The Twofish algorithm with a 256 bit key. 1485 1486'GCRY_CIPHER_TWOFISH128' 1487 The Twofish algorithm with a 128 bit key. 1488 1489'GCRY_CIPHER_ARCFOUR' 1490 An algorithm which is 100% compatible with RSA Inc.'s RC4 1491 algorithm. Note that this is a stream cipher and must be used very 1492 carefully to avoid a couple of weaknesses. 1493 1494'GCRY_CIPHER_DES' 1495 Standard DES with a 56 bit key. You need to pass 64 bit but the 1496 high bits of each byte are ignored. Note, that this is a weak 1497 algorithm which can be broken in reasonable time using a brute 1498 force approach. 1499 1500'GCRY_CIPHER_SERPENT128' 1501'GCRY_CIPHER_SERPENT192' 1502'GCRY_CIPHER_SERPENT256' 1503 The Serpent cipher from the AES contest. 1504 1505'GCRY_CIPHER_RFC2268_40' 1506'GCRY_CIPHER_RFC2268_128' 1507 Ron's Cipher 2 in the 40 and 128 bit variants. 1508 1509'GCRY_CIPHER_SEED' 1510 A 128 bit cipher as described by RFC4269. 1511 1512'GCRY_CIPHER_CAMELLIA128' 1513'GCRY_CIPHER_CAMELLIA192' 1514'GCRY_CIPHER_CAMELLIA256' 1515 The Camellia cipher by NTT. See 1516 <http://info.isl.ntt.co.jp/crypt/eng/camellia/specifications.html>. 1517 1518'GCRY_CIPHER_SALSA20' 1519 This is the Salsa20 stream cipher. 1520 1521'GCRY_CIPHER_SALSA20R12' 1522 This is the Salsa20/12 - reduced round version of Salsa20 stream 1523 cipher. 1524 1525'GCRY_CIPHER_GOST28147' 1526 The GOST 28147-89 cipher, defined in the respective GOST standard. 1527 Translation of this GOST into English is provided in the RFC-5830. 1528 1529'GCRY_CIPHER_GOST28147_MESH' 1530 The GOST 28147-89 cipher, defined in the respective GOST standard. 1531 Translation of this GOST into English is provided in the RFC-5830. 1532 This cipher will use CryptoPro keymeshing as defined in RFC 4357 if 1533 it has to be used for the selected parameter set. 1534 1535'GCRY_CIPHER_CHACHA20' 1536 This is the ChaCha20 stream cipher. 1537 1538'GCRY_CIPHER_SM4' 1539 A 128 bit cipher by the State Cryptography Administration of China 1540 (SCA). See <https://tools.ietf.org/html/draft-ribose-cfrg-sm4-10>. 1541 1542 1543File: gcrypt.info, Node: Available cipher modes, Next: Working with cipher handles, Prev: Available ciphers, Up: Symmetric cryptography 1544 15455.2 Available cipher modes 1546========================== 1547 1548'GCRY_CIPHER_MODE_NONE' 1549 No mode specified. This should not be used. The only exception is 1550 that if Libgcrypt is not used in FIPS mode and if any debug flag 1551 has been set, this mode may be used to bypass the actual 1552 encryption. 1553 1554'GCRY_CIPHER_MODE_ECB' 1555 Electronic Codebook mode. 1556 1557'GCRY_CIPHER_MODE_CFB' 1558'GCRY_CIPHER_MODE_CFB8' 1559 Cipher Feedback mode. For GCRY_CIPHER_MODE_CFB the shift size 1560 equals the block size of the cipher (e.g. for AES it is CFB-128). 1561 For GCRY_CIPHER_MODE_CFB8 the shift size is 8 bit but that variant 1562 is not yet available. 1563 1564'GCRY_CIPHER_MODE_CBC' 1565 Cipher Block Chaining mode. 1566 1567'GCRY_CIPHER_MODE_STREAM' 1568 Stream mode, only to be used with stream cipher algorithms. 1569 1570'GCRY_CIPHER_MODE_OFB' 1571 Output Feedback mode. 1572 1573'GCRY_CIPHER_MODE_CTR' 1574 Counter mode. 1575 1576'GCRY_CIPHER_MODE_AESWRAP' 1577 This mode is used to implement the AES-Wrap algorithm according to 1578 RFC-3394. It may be used with any 128 bit block length algorithm, 1579 however the specs require one of the 3 AES algorithms. These 1580 special conditions apply: If 'gcry_cipher_setiv' has not been used 1581 the standard IV is used; if it has been used the lower 64 bit of 1582 the IV are used as the Alternative Initial Value. On encryption 1583 the provided output buffer must be 64 bit (8 byte) larger than the 1584 input buffer; in-place encryption is still allowed. On decryption 1585 the output buffer may be specified 64 bit (8 byte) shorter than 1586 then input buffer. As per specs the input length must be at least 1587 128 bits and the length must be a multiple of 64 bits. 1588 1589'GCRY_CIPHER_MODE_CCM' 1590 Counter with CBC-MAC mode is an Authenticated Encryption with 1591 Associated Data (AEAD) block cipher mode, which is specified in 1592 'NIST Special Publication 800-38C' and RFC 3610. 1593 1594'GCRY_CIPHER_MODE_GCM' 1595 Galois/Counter Mode (GCM) is an Authenticated Encryption with 1596 Associated Data (AEAD) block cipher mode, which is specified in 1597 'NIST Special Publication 800-38D'. 1598 1599'GCRY_CIPHER_MODE_POLY1305' 1600 This mode implements the Poly1305 Authenticated Encryption with 1601 Associated Data (AEAD) mode according to RFC-8439. This mode can 1602 be used with ChaCha20 stream cipher. 1603 1604'GCRY_CIPHER_MODE_OCB' 1605 OCB is an Authenticated Encryption with Associated Data (AEAD) 1606 block cipher mode, which is specified in RFC-7253. Supported tag 1607 lengths are 128, 96, and 64 bit with the default being 128 bit. To 1608 switch to a different tag length 'gcry_cipher_ctl' using the 1609 command 'GCRYCTL_SET_TAGLEN' and the address of an 'int' variable 1610 set to 12 (for 96 bit) or 8 (for 64 bit) provided for the 'buffer' 1611 argument and 'sizeof(int)' for 'buflen'. 1612 1613 Note that the use of 'gcry_cipher_final' is required. 1614 1615'GCRY_CIPHER_MODE_XTS' 1616 XEX-based tweaked-codebook mode with ciphertext stealing (XTS) mode 1617 is used to implement the AES-XTS as specified in IEEE 1619 Standard 1618 Architecture for Encrypted Shared Storage Media and NIST SP800-38E. 1619 1620 The XTS mode requires doubling key-length, for example, using 1621 512-bit key with AES-256 ('GCRY_CIPHER_AES256'). The 128-bit tweak 1622 value is feed to XTS mode as little-endian byte array using 1623 'gcry_cipher_setiv' function. When encrypting or decrypting, 1624 full-sized data unit buffers needs to be passed to 1625 'gcry_cipher_encrypt' or 'gcry_cipher_decrypt'. The tweak value is 1626 automatically incremented after each call of 'gcry_cipher_encrypt' 1627 and 'gcry_cipher_decrypt'. Auto-increment allows avoiding need of 1628 setting IV between processing of sequential data units. 1629 1630'GCRY_CIPHER_MODE_EAX' 1631 EAX is an Authenticated Encryption with Associated Data (AEAD) 1632 block cipher mode by Bellare, Rogaway, and Wagner (see 1633 <http://web.cs.ucdavis.edu/~rogaway/papers/eax.html>). 1634 1635 1636File: gcrypt.info, Node: Working with cipher handles, Next: General cipher functions, Prev: Available cipher modes, Up: Symmetric cryptography 1637 16385.3 Working with cipher handles 1639=============================== 1640 1641To use a cipher algorithm, you must first allocate an according handle. 1642This is to be done using the open function: 1643 1644 -- Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *HD, int 1645 ALGO, int MODE, unsigned int FLAGS) 1646 1647 This function creates the context handle required for most of the 1648 other cipher functions and returns a handle to it in 'hd'. In case 1649 of an error, an according error code is returned. 1650 1651 The ID of algorithm to use must be specified via ALGO. See *note 1652 Available ciphers::, for a list of supported ciphers and the 1653 according constants. 1654 1655 Besides using the constants directly, the function 1656 'gcry_cipher_map_name' may be used to convert the textual name of 1657 an algorithm into the according numeric ID. 1658 1659 The cipher mode to use must be specified via MODE. See *note 1660 Available cipher modes::, for a list of supported cipher modes and 1661 the according constants. Note that some modes are incompatible 1662 with some algorithms - in particular, stream mode 1663 ('GCRY_CIPHER_MODE_STREAM') only works with stream ciphers. 1664 Poly1305 AEAD mode ('GCRY_CIPHER_MODE_POLY1305') only works with 1665 ChaCha20 stream cipher. The block cipher modes 1666 ('GCRY_CIPHER_MODE_ECB', 'GCRY_CIPHER_MODE_CBC', 1667 'GCRY_CIPHER_MODE_CFB', 'GCRY_CIPHER_MODE_OFB', 1668 'GCRY_CIPHER_MODE_CTR' and 'GCRY_CIPHER_MODE_EAX') will work with 1669 any block cipher algorithm. GCM mode ('GCRY_CIPHER_MODE_CCM'), CCM 1670 mode ('GCRY_CIPHER_MODE_GCM'), OCB mode ('GCRY_CIPHER_MODE_OCB'), 1671 and XTS mode ('GCRY_CIPHER_MODE_XTS') will only work with block 1672 cipher algorithms which have the block size of 16 bytes. 1673 1674 The third argument FLAGS can either be passed as '0' or as the 1675 bit-wise OR of the following constants. 1676 1677 'GCRY_CIPHER_SECURE' 1678 Make sure that all operations are allocated in secure memory. 1679 This is useful when the key material is highly confidential. 1680 'GCRY_CIPHER_ENABLE_SYNC' 1681 This flag enables the CFB sync mode, which is a special 1682 feature of Libgcrypt's CFB mode implementation to allow for 1683 OpenPGP's CFB variant. See 'gcry_cipher_sync'. 1684 'GCRY_CIPHER_CBC_CTS' 1685 Enable cipher text stealing (CTS) for the CBC mode. Cannot be 1686 used simultaneous as GCRY_CIPHER_CBC_MAC. CTS mode makes it 1687 possible to transform data of almost arbitrary size (only 1688 limitation is that it must be greater than the algorithm's 1689 block size). 1690 'GCRY_CIPHER_CBC_MAC' 1691 Compute CBC-MAC keyed checksums. This is the same as CBC 1692 mode, but only output the last block. Cannot be used 1693 simultaneous as GCRY_CIPHER_CBC_CTS. 1694 1695 Use the following function to release an existing handle: 1696 1697 -- Function: void gcry_cipher_close (gcry_cipher_hd_t H) 1698 1699 This function releases the context created by 'gcry_cipher_open'. 1700 It also zeroises all sensitive information associated with this 1701 cipher handle. 1702 1703 In order to use a handle for performing cryptographic operations, a 1704'key' has to be set first: 1705 1706 -- Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H, const 1707 void *K, size_t L) 1708 1709 Set the key K used for encryption or decryption in the context 1710 denoted by the handle H. The length L (in bytes) of the key K must 1711 match the required length of the algorithm set for this context or 1712 be in the allowed range for algorithms with variable key size. The 1713 function checks this and returns an error if there is a problem. A 1714 caller should always check for an error. 1715 1716 Most crypto modes requires an initialization vector (IV), which 1717usually is a non-secret random string acting as a kind of salt value. 1718The CTR mode requires a counter, which is also similar to a salt value. 1719To set the IV or CTR, use these functions: 1720 1721 -- Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, const 1722 void *K, size_t L) 1723 1724 Set the initialization vector used for encryption or decryption. 1725 The vector is passed as the buffer K of length L bytes and copied 1726 to internal data structures. The function checks that the IV 1727 matches the requirement of the selected algorithm and mode. 1728 1729 This function is also used by AEAD modes and with Salsa20 and 1730 ChaCha20 stream ciphers to set or update the required nonce. In 1731 these cases it needs to be called after setting the key. 1732 1733 -- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H, const 1734 void *C, size_t L) 1735 1736 Set the counter vector used for encryption or decryption. The 1737 counter is passed as the buffer C of length L bytes and copied to 1738 internal data structures. The function checks that the counter 1739 matches the requirement of the selected algorithm (i.e., it must be 1740 the same size as the block size). 1741 1742 -- Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t H) 1743 1744 Set the given handle's context back to the state it had after the 1745 last call to gcry_cipher_setkey and clear the initialization 1746 vector. 1747 1748 Note that gcry_cipher_reset is implemented as a macro. 1749 1750 Authenticated Encryption with Associated Data (AEAD) block cipher 1751modes require the handling of the authentication tag and the additional 1752authenticated data, which can be done by using the following functions: 1753 1754 -- Function: gcry_error_t gcry_cipher_authenticate (gcry_cipher_hd_t H, 1755 const void *ABUF, size_t ABUFLEN) 1756 1757 Process the buffer ABUF of length ABUFLEN as the additional 1758 authenticated data (AAD) for AEAD cipher modes. 1759 1760 -- Function: gcry_error_t gcry_cipher_gettag (gcry_cipher_hd_t H, 1761 void *TAG, size_t TAGLEN) 1762 1763 This function is used to read the authentication tag after 1764 encryption. The function finalizes and outputs the authentication 1765 tag to the buffer TAG of length TAGLEN bytes. 1766 1767 Depending on the used mode certain restrictions for TAGLEN are 1768 enforced: For GCM TAGLEN must be at least 16 or one of the allowed 1769 truncated lengths (4, 8, 12, 13, 14, or 15). 1770 1771 -- Function: gcry_error_t gcry_cipher_checktag (gcry_cipher_hd_t H, 1772 const void *TAG, size_t TAGLEN) 1773 1774 Check the authentication tag after decryption. The authentication 1775 tag is passed as the buffer TAG of length TAGLEN bytes and compared 1776 to internal authentication tag computed during decryption. Error 1777 code 'GPG_ERR_CHECKSUM' is returned if the authentication tag in 1778 the buffer TAG does not match the authentication tag calculated 1779 during decryption. 1780 1781 Depending on the used mode certain restrictions for TAGLEN are 1782 enforced: For GCM TAGLEN must either be 16 or one of the allowed 1783 truncated lengths (4, 8, 12, 13, 14, or 15). 1784 1785 The actual encryption and decryption is done by using one of the 1786following functions. They may be used as often as required to process 1787all the data. 1788 1789 -- Function: gcry_error_t gcry_cipher_encrypt (gcry_cipher_hd_t H, 1790 unsigned char *out, size_t OUTSIZE, const unsigned char *IN, 1791 size_t INLEN) 1792 1793 'gcry_cipher_encrypt' is used to encrypt the data. This function 1794 can either work in place or with two buffers. It uses the cipher 1795 context already setup and described by the handle H. There are 2 1796 ways to use the function: If IN is passed as 'NULL' and INLEN is 1797 '0', in-place encryption of the data in OUT of length OUTSIZE takes 1798 place. With IN being not 'NULL', INLEN bytes are encrypted to the 1799 buffer OUT which must have at least a size of INLEN. OUTSIZE must 1800 be set to the allocated size of OUT, so that the function can check 1801 that there is sufficient space. Note that overlapping buffers are 1802 not allowed. 1803 1804 Depending on the selected algorithms and encryption mode, the 1805 length of the buffers must be a multiple of the block size. 1806 1807 Some encryption modes require that 'gcry_cipher_final' is used 1808 before the final data chunk is passed to this function. 1809 1810 The function returns '0' on success or an error code. 1811 1812 -- Function: gcry_error_t gcry_cipher_decrypt (gcry_cipher_hd_t H, 1813 unsigned char *out, size_t OUTSIZE, const unsigned char *IN, 1814 size_t INLEN) 1815 1816 'gcry_cipher_decrypt' is used to decrypt the data. This function 1817 can either work in place or with two buffers. It uses the cipher 1818 context already setup and described by the handle H. There are 2 1819 ways to use the function: If IN is passed as 'NULL' and INLEN is 1820 '0', in-place decryption of the data in OUT or length OUTSIZE takes 1821 place. With IN being not 'NULL', INLEN bytes are decrypted to the 1822 buffer OUT which must have at least a size of INLEN. OUTSIZE must 1823 be set to the allocated size of OUT, so that the function can check 1824 that there is sufficient space. Note that overlapping buffers are 1825 not allowed. 1826 1827 Depending on the selected algorithms and encryption mode, the 1828 length of the buffers must be a multiple of the block size. 1829 1830 Some encryption modes require that 'gcry_cipher_final' is used 1831 before the final data chunk is passed to this function. 1832 1833 The function returns '0' on success or an error code. 1834 1835 The OCB mode features integrated padding and must thus be told about 1836the end of the input data. This is done with: 1837 1838 -- Function: gcry_error_t gcry_cipher_final (gcry_cipher_hd_t H) 1839 1840 Set a flag in the context to tell the encrypt and decrypt functions 1841 that their next call will provide the last chunk of data. Only the 1842 first call to this function has an effect and only for modes which 1843 support it. Checking the error is in general not necessary. This 1844 is implemented as a macro. 1845 1846 OpenPGP (as defined in RFC-4880) requires a special sync operation in 1847some places. The following function is used for this: 1848 1849 -- Function: gcry_error_t gcry_cipher_sync (gcry_cipher_hd_t H) 1850 1851 Perform the OpenPGP sync operation on context H. Note that this is 1852 a no-op unless the context was created with the flag 1853 'GCRY_CIPHER_ENABLE_SYNC' 1854 1855 Some of the described functions are implemented as macros utilizing a 1856catch-all control function. This control function is rarely used 1857directly but there is nothing which would inhibit it: 1858 1859 -- Function: gcry_error_t gcry_cipher_ctl (gcry_cipher_hd_t H, int CMD, 1860 void *BUFFER, size_t BUFLEN) 1861 1862 'gcry_cipher_ctl' controls various aspects of the cipher module and 1863 specific cipher contexts. Usually some more specialized functions 1864 or macros are used for this purpose. The semantics of the function 1865 and its parameters depends on the the command CMD and the passed 1866 context handle H. Please see the comments in the source code 1867 ('src/global.c') for details. 1868 1869 -- Function: gcry_error_t gcry_cipher_info (gcry_cipher_hd_t H, int 1870 WHAT, void *BUFFER, size_t *NBYTES) 1871 1872 'gcry_cipher_info' is used to retrieve various information about a 1873 cipher context or the cipher module in general. 1874 1875 'GCRYCTL_GET_TAGLEN:' 1876 Return the length of the tag for an AE algorithm mode. An 1877 error is returned for modes which do not support a tag. 1878 BUFFER must be given as NULL. On success the result is stored 1879 NBYTES. The taglen is returned in bytes. 1880 1881 1882File: gcrypt.info, Node: General cipher functions, Prev: Working with cipher handles, Up: Symmetric cryptography 1883 18845.4 General cipher functions 1885============================ 1886 1887To work with the algorithms, several functions are available to map 1888algorithm names to the internal identifiers, as well as ways to retrieve 1889information about an algorithm or the current cipher context. 1890 1891 -- Function: gcry_error_t gcry_cipher_algo_info (int ALGO, int WHAT, 1892 void *BUFFER, size_t *NBYTES) 1893 1894 This function is used to retrieve information on a specific 1895 algorithm. You pass the cipher algorithm ID as ALGO and the type 1896 of information requested as WHAT. The result is either returned as 1897 the return code of the function or copied to the provided BUFFER 1898 whose allocated length must be available in an integer variable 1899 with the address passed in NBYTES. This variable will also receive 1900 the actual used length of the buffer. 1901 1902 Here is a list of supported codes for WHAT: 1903 1904 'GCRYCTL_GET_KEYLEN:' 1905 Return the length of the key. If the algorithm supports 1906 multiple key lengths, the maximum supported value is returned. 1907 The length is returned as number of octets (bytes) and not as 1908 number of bits in NBYTES; BUFFER must be zero. Note that it 1909 is usually better to use the convenience function 1910 'gcry_cipher_get_algo_keylen'. 1911 1912 'GCRYCTL_GET_BLKLEN:' 1913 Return the block length of the algorithm. The length is 1914 returned as a number of octets in NBYTES; BUFFER must be zero. 1915 Note that it is usually better to use the convenience function 1916 'gcry_cipher_get_algo_blklen'. 1917 1918 'GCRYCTL_TEST_ALGO:' 1919 Returns '0' when the specified algorithm is available for use. 1920 BUFFER and NBYTES must be zero. 1921 1922 -- Function: size_t gcry_cipher_get_algo_keylen (ALGO) 1923 1924 This function returns length of the key for algorithm ALGO. If the 1925 algorithm supports multiple key lengths, the maximum supported key 1926 length is returned. On error '0' is returned. The key length is 1927 returned as number of octets. 1928 1929 This is a convenience functions which should be preferred over 1930 'gcry_cipher_algo_info' because it allows for proper type checking. 1931 1932 -- Function: size_t gcry_cipher_get_algo_blklen (int ALGO) 1933 1934 This functions returns the block-length of the algorithm ALGO 1935 counted in octets. On error '0' is returned. 1936 1937 This is a convenience functions which should be preferred over 1938 'gcry_cipher_algo_info' because it allows for proper type checking. 1939 1940 -- Function: const char * gcry_cipher_algo_name (int ALGO) 1941 1942 'gcry_cipher_algo_name' returns a string with the name of the 1943 cipher algorithm ALGO. If the algorithm is not known or another 1944 error occurred, the string '"?"' is returned. This function should 1945 not be used to test for the availability of an algorithm. 1946 1947 -- Function: int gcry_cipher_map_name (const char *NAME) 1948 1949 'gcry_cipher_map_name' returns the algorithm identifier for the 1950 cipher algorithm described by the string NAME. If this algorithm 1951 is not available '0' is returned. 1952 1953 -- Function: int gcry_cipher_mode_from_oid (const char *STRING) 1954 1955 Return the cipher mode associated with an ASN.1 object identifier. 1956 The object identifier is expected to be in the IETF-style dotted 1957 decimal notation. The function returns '0' for an unknown object 1958 identifier or when no mode is associated with it. 1959 1960 1961File: gcrypt.info, Node: Public Key cryptography, Next: Hashing, Prev: Symmetric cryptography, Up: Top 1962 19636 Public Key cryptography 1964************************* 1965 1966Public key cryptography, also known as asymmetric cryptography, is an 1967easy way for key management and to provide digital signatures. 1968Libgcrypt provides two completely different interfaces to public key 1969cryptography, this chapter explains the one based on S-expressions. 1970 1971* Menu: 1972 1973* Available algorithms:: Algorithms supported by the library. 1974* Used S-expressions:: Introduction into the used S-expression. 1975* Cryptographic Functions:: Functions for performing the cryptographic actions. 1976* Dedicated ECC Functions:: Dedicated functions for elliptic curves. 1977* General public-key related Functions:: General functions, not implementing any cryptography. 1978 1979 1980File: gcrypt.info, Node: Available algorithms, Next: Used S-expressions, Up: Public Key cryptography 1981 19826.1 Available algorithms 1983======================== 1984 1985Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well as 1986DSA (Digital Signature Algorithm), Elgamal, ECDSA, ECDH, and EdDSA. 1987 1988 1989File: gcrypt.info, Node: Used S-expressions, Next: Cryptographic Functions, Prev: Available algorithms, Up: Public Key cryptography 1990 19916.2 Used S-expressions 1992====================== 1993 1994Libgcrypt's API for asymmetric cryptography is based on data structures 1995called S-expressions (see 1996<http://people.csail.mit.edu/rivest/sexp.html>) and does not work with 1997contexts/handles as most of the other building blocks of Libgcrypt do. 1998 1999The following information are stored in S-expressions: 2000 2001 * keys 2002 2003 * plain text data 2004 2005 * encrypted data 2006 2007 * signatures 2008 2009To describe how Libgcrypt expect keys, we use examples. Note that words 2010in uppercase indicate parameters whereas lowercase words are literals. 2011 2012 Note that all MPI (multi-precision-integers) values are expected to 2013be in 'GCRYMPI_FMT_USG' format. An easy way to create S-expressions is 2014by using 'gcry_sexp_build' which allows to pass a string with 2015printf-like escapes to insert MPI values. 2016 2017* Menu: 2018 2019* RSA key parameters:: Parameters used with an RSA key. 2020* DSA key parameters:: Parameters used with a DSA key. 2021* ECC key parameters:: Parameters used with ECC keys. 2022 2023 2024File: gcrypt.info, Node: RSA key parameters, Next: DSA key parameters, Up: Used S-expressions 2025 20266.2.1 RSA key parameters 2027------------------------ 2028 2029An RSA private key is described by this S-expression: 2030 2031 (private-key 2032 (rsa 2033 (n N-MPI) 2034 (e E-MPI) 2035 (d D-MPI) 2036 (p P-MPI) 2037 (q Q-MPI) 2038 (u U-MPI))) 2039 2040An RSA public key is described by this S-expression: 2041 2042 (public-key 2043 (rsa 2044 (n N-MPI) 2045 (e E-MPI))) 2046 2047N-MPI 2048 RSA public modulus n. 2049E-MPI 2050 RSA public exponent e. 2051D-MPI 2052 RSA secret exponent d = e^{-1} \bmod (p-1)(q-1). 2053P-MPI 2054 RSA secret prime p. 2055Q-MPI 2056 RSA secret prime q with p < q. 2057U-MPI 2058 Multiplicative inverse u = p^{-1} \bmod q. 2059 2060 For signing and decryption the parameters (p, q, u) are optional but 2061greatly improve the performance. Either all of these optional 2062parameters must be given or none of them. They are mandatory for 2063gcry_pk_testkey. 2064 2065 Note that OpenSSL uses slighly different parameters: q < p and u = 2066q^{-1} \bmod p. To use these parameters you will need to swap the 2067values and recompute u. Here is example code to do this: 2068 2069 if (gcry_mpi_cmp (p, q) > 0) 2070 { 2071 gcry_mpi_swap (p, q); 2072 gcry_mpi_invm (u, p, q); 2073 } 2074 2075 2076File: gcrypt.info, Node: DSA key parameters, Next: ECC key parameters, Prev: RSA key parameters, Up: Used S-expressions 2077 20786.2.2 DSA key parameters 2079------------------------ 2080 2081A DSA private key is described by this S-expression: 2082 2083 (private-key 2084 (dsa 2085 (p P-MPI) 2086 (q Q-MPI) 2087 (g G-MPI) 2088 (y Y-MPI) 2089 (x X-MPI))) 2090 2091P-MPI 2092 DSA prime p. 2093Q-MPI 2094 DSA group order q (which is a prime divisor of p-1). 2095G-MPI 2096 DSA group generator g. 2097Y-MPI 2098 DSA public key value y = g^x \bmod p. 2099X-MPI 2100 DSA secret exponent x. 2101 2102 The public key is similar with "private-key" replaced by "public-key" 2103and no X-MPI. 2104 2105 2106File: gcrypt.info, Node: ECC key parameters, Prev: DSA key parameters, Up: Used S-expressions 2107 21086.2.3 ECC key parameters 2109------------------------ 2110 2111An ECC private key is described by this S-expression: 2112 2113 (private-key 2114 (ecc 2115 (p P-MPI) 2116 (a A-MPI) 2117 (b B-MPI) 2118 (g G-POINT) 2119 (n N-MPI) 2120 (q Q-POINT) 2121 (d D-MPI))) 2122 2123P-MPI 2124 Prime specifying the field GF(p). 2125A-MPI 2126B-MPI 2127 The two coefficients of the Weierstrass equation y^2 = x^3 + ax + b 2128G-POINT 2129 Base point g. 2130N-MPI 2131 Order of g 2132Q-POINT 2133 The point representing the public key Q = dG. 2134D-MPI 2135 The private key d 2136 2137 All point values are encoded in standard format; Libgcrypt does in 2138general only support uncompressed points, thus the first byte needs to 2139be '0x04'. However "EdDSA" describes its own compression scheme which 2140is used by default; the non-standard first byte '0x40' may optionally be 2141used to explicit flag the use of the algorithm’s native compression 2142method. 2143 2144 The public key is similar with "private-key" replaced by "public-key" 2145and no D-MPI. 2146 2147 If the domain parameters are well-known, the name of this curve may 2148be used. For example 2149 2150 (private-key 2151 (ecc 2152 (curve "NIST P-192") 2153 (q Q-POINT) 2154 (d D-MPI))) 2155 2156 Note that Q-POINT is optional for a private key. The 'curve' 2157parameter may be given in any case and is used to replace missing 2158parameters. 2159 2160Currently implemented curves are: 2161 2162'Curve25519' 2163'X25519' 2164'1.3.6.1.4.1.3029.1.5.1' 2165'1.3.101.110' 2166 The RFC-8410 255 bit curve, its RFC name, OpenPGP and RFC OIDs. 2167 2168'X448' 2169'1.3.101.111' 2170 The RFC-8410 448 bit curve and its RFC OID. 2171 2172'Ed25519' 2173'1.3.6.1.4.1.11591.15.1' 2174'1.3.101.112' 2175 The signing variant of the RFC-8410 255 bit curve, its OpenPGP and 2176 RFC OIDs. 2177 2178'Ed448' 2179'1.3.101.113' 2180 The signing variant of the RFC-8410 448 bit curve and its RFC OID. 2181 2182'NIST P-192' 2183'1.2.840.10045.3.1.1' 2184'nistp192' 2185'prime192v1' 2186'secp192r1' 2187 The NIST 192 bit curve, its OID and aliases. 2188 2189'NIST P-224' 2190'1.3.132.0.33' 2191'nistp224' 2192'secp224r1' 2193 The NIST 224 bit curve, its OID and aliases. 2194 2195'NIST P-256' 2196'1.2.840.10045.3.1.7' 2197'nistp256' 2198'prime256v1' 2199'secp256r1' 2200 The NIST 256 bit curve, its OID and aliases. 2201 2202'NIST P-384' 2203'1.3.132.0.34' 2204'nistp384' 2205'secp384r1' 2206 The NIST 384 bit curve, its OID and aliases. 2207 2208'NIST P-521' 2209'1.3.132.0.35' 2210'nistp521' 2211'secp521r1' 2212 The NIST 521 bit curve, its OID and aliases. 2213 2214'brainpoolP160r1' 2215'1.3.36.3.3.2.8.1.1.1' 2216 The Brainpool 160 bit curve and its OID. 2217 2218'brainpoolP192r1' 2219'1.3.36.3.3.2.8.1.1.3' 2220 The Brainpool 192 bit curve and its OID. 2221 2222'brainpoolP224r1' 2223'1.3.36.3.3.2.8.1.1.5' 2224 The Brainpool 224 bit curve and its OID. 2225 2226'brainpoolP256r1' 2227'1.3.36.3.3.2.8.1.1.7' 2228 The Brainpool 256 bit curve and its OID. 2229 2230'brainpoolP320r1' 2231'1.3.36.3.3.2.8.1.1.9' 2232 The Brainpool 320 bit curve and its OID. 2233 2234'brainpoolP384r1' 2235'1.3.36.3.3.2.8.1.1.11' 2236 The Brainpool 384 bit curve and its OID. 2237 2238'brainpoolP512r1' 2239'1.3.36.3.3.2.8.1.1.13' 2240 The Brainpool 512 bit curve and its OID. 2241 2242 As usual the OIDs may optionally be prefixed with the string 'OID.' 2243or 'oid.'. 2244 2245 2246File: gcrypt.info, Node: Cryptographic Functions, Next: Dedicated ECC Functions, Prev: Used S-expressions, Up: Public Key cryptography 2247 22486.3 Cryptographic Functions 2249=========================== 2250 2251Some functions operating on S-expressions support 'flags' to influence 2252the operation. These flags have to be listed in a sub-S-expression 2253named 'flags'. Flag names are case-sensitive. The following flags are 2254known: 2255 2256'comp' 2257'nocomp' 2258 If supported by the algorithm and curve the 'comp' flag requests 2259 that points are returned in compact (compressed) representation. 2260 The 'nocomp' flag requests that points are returned with full 2261 coordinates. The default depends on the the algorithm and curve. 2262 The compact representation requires a small overhead before a point 2263 can be used but halves the size of a to be conveyed public key. If 2264 'comp' is used with the "EdDSA" algorithm the key generation prefix 2265 the public key with a '0x40' byte. 2266 2267'pkcs1' 2268 Use PKCS#1 block type 2 padding for encryption, block type 1 2269 padding for signing. 2270 2271'oaep' 2272 Use RSA-OAEP padding for encryption. 2273 2274'pss' 2275 Use RSA-PSS padding for signing. 2276 2277'eddsa' 2278 Use the EdDSA scheme signing instead of the default ECDSA 2279 algorithm. Note that the EdDSA uses a special form of the public 2280 key. 2281 2282'rfc6979' 2283 For DSA and ECDSA use a deterministic scheme for the k parameter. 2284 2285'no-blinding' 2286 Do not use a technique called 'blinding', which is used by default 2287 in order to prevent leaking of secret information. Blinding is 2288 only implemented by RSA, but it might be implemented by other 2289 algorithms in the future as well, when necessary. 2290 2291'param' 2292 For ECC key generation also return the domain parameters. For ECC 2293 signing and verification override default parameters by provided 2294 domain parameters of the public or private key. 2295 2296'transient-key' 2297 This flag is only meaningful for RSA, DSA, and ECC key generation. 2298 If given the key is created using a faster and a somewhat less 2299 secure random number generator. This flag may be used for keys 2300 which are only used for a short time or per-message and do not 2301 require full cryptographic strength. 2302 2303'no-keytest' 2304 This flag skips internal failsafe tests to assert that a generated 2305 key is properly working. It currently has an effect only for 2306 standard ECC key generation. It is mostly useful along with 2307 transient-key to achieve fastest ECC key generation. 2308 2309'use-x931' 2310 Force the use of the ANSI X9.31 key generation algorithm instead of 2311 the default algorithm. This flag is only meaningful for RSA key 2312 generation and usually not required. Note that this algorithm is 2313 implicitly used if either 'derive-parms' is given or Libgcrypt is 2314 in FIPS mode. 2315 2316'use-fips186' 2317 Force the use of the FIPS 186 key generation algorithm instead of 2318 the default algorithm. This flag is only meaningful for DSA and 2319 usually not required. Note that this algorithm is implicitly used 2320 if either 'derive-parms' is given or Libgcrypt is in FIPS mode. As 2321 of now FIPS 186-2 is implemented; after the approval of FIPS 186-3 2322 the code will be changed to implement 186-3. 2323 2324'use-fips186-2' 2325 Force the use of the FIPS 186-2 key generation algorithm instead of 2326 the default algorithm. This algorithm is slightly different from 2327 FIPS 186-3 and allows only 1024 bit keys. This flag is only 2328 meaningful for DSA and only required for FIPS testing backward 2329 compatibility. 2330 2331Now that we know the key basics, we can carry on and explain how to 2332encrypt and decrypt data. In almost all cases the data is a random 2333session key which is in turn used for the actual encryption of the real 2334data. There are 2 functions to do this: 2335 2336 -- Function: gcry_error_t gcry_pk_encrypt (gcry_sexp_t *R_CIPH, 2337 gcry_sexp_t DATA, gcry_sexp_t PKEY) 2338 2339 Obviously a public key must be provided for encryption. It is 2340 expected as an appropriate S-expression (see above) in PKEY. The 2341 data to be encrypted can either be in the simple old format, which 2342 is a very simple S-expression consisting only of one MPI, or it may 2343 be a more complex S-expression which also allows to specify flags 2344 for operation, like e.g. padding rules. 2345 2346 If you don't want to let Libgcrypt handle the padding, you must 2347 pass an appropriate MPI using this expression for DATA: 2348 2349 (data 2350 (flags raw) 2351 (value MPI)) 2352 2353 This has the same semantics as the old style MPI only way. MPI is 2354 the actual data, already padded appropriate for your protocol. 2355 Most RSA based systems however use PKCS#1 padding and so you can 2356 use this S-expression for DATA: 2357 2358 (data 2359 (flags pkcs1) 2360 (value BLOCK)) 2361 2362 Here, the "flags" list has the "pkcs1" flag which let the function 2363 know that it should provide PKCS#1 block type 2 padding. The 2364 actual data to be encrypted is passed as a string of octets in 2365 BLOCK. The function checks that this data actually can be used 2366 with the given key, does the padding and encrypts it. 2367 2368 If the function could successfully perform the encryption, the 2369 return value will be 0 and a new S-expression with the encrypted 2370 result is allocated and assigned to the variable at the address of 2371 R_CIPH. The caller is responsible to release this value using 2372 'gcry_sexp_release'. In case of an error, an error code is 2373 returned and R_CIPH will be set to 'NULL'. 2374 2375 The returned S-expression has this format when used with RSA: 2376 2377 (enc-val 2378 (rsa 2379 (a A-MPI))) 2380 2381 Where A-MPI is an MPI with the result of the RSA operation. When 2382 using the Elgamal algorithm, the return value will have this 2383 format: 2384 2385 (enc-val 2386 (elg 2387 (a A-MPI) 2388 (b B-MPI))) 2389 2390 Where A-MPI and B-MPI are MPIs with the result of the Elgamal 2391 encryption operation. 2392 2393 -- Function: gcry_error_t gcry_pk_decrypt (gcry_sexp_t *R_PLAIN, 2394 gcry_sexp_t DATA, gcry_sexp_t SKEY) 2395 2396 Obviously a private key must be provided for decryption. It is 2397 expected as an appropriate S-expression (see above) in SKEY. The 2398 data to be decrypted must match the format of the result as 2399 returned by 'gcry_pk_encrypt', but should be enlarged with a 2400 'flags' element: 2401 2402 (enc-val 2403 (flags) 2404 (elg 2405 (a A-MPI) 2406 (b B-MPI))) 2407 2408 This function does not remove padding from the data by default. To 2409 let Libgcrypt remove padding, give a hint in 'flags' telling which 2410 padding method was used when encrypting: 2411 2412 (flags PADDING-METHOD) 2413 2414 Currently PADDING-METHOD is either 'pkcs1' for PKCS#1 block type 2 2415 padding, or 'oaep' for RSA-OAEP padding. 2416 2417 The function returns 0 on success or an error code. The variable 2418 at the address of R_PLAIN will be set to NULL on error or receive 2419 the decrypted value on success. The format of R_PLAIN is a simple 2420 S-expression part (i.e. not a valid one) with just one MPI if 2421 there was no 'flags' element in DATA; if at least an empty 'flags' 2422 is passed in DATA, the format is: 2423 2424 (value PLAINTEXT) 2425 2426 Another operation commonly performed using public key cryptography is 2427signing data. In some sense this is even more important than encryption 2428because digital signatures are an important instrument for key 2429management. Libgcrypt supports digital signatures using 2 functions, 2430similar to the encryption functions: 2431 2432 -- Function: gcry_error_t gcry_pk_sign (gcry_sexp_t *R_SIG, 2433 gcry_sexp_t DATA, gcry_sexp_t SKEY) 2434 2435 This function creates a digital signature for DATA using the 2436 private key SKEY and place it into the variable at the address of 2437 R_SIG. DATA may either be the simple old style S-expression with 2438 just one MPI or a modern and more versatile S-expression which 2439 allows to let Libgcrypt handle padding: 2440 2441 (data 2442 (flags pkcs1) 2443 (hash HASH-ALGO BLOCK)) 2444 2445 This example requests to sign the data in BLOCK after applying 2446 PKCS#1 block type 1 style padding. HASH-ALGO is a string with the 2447 hash algorithm to be encoded into the signature, this may be any 2448 hash algorithm name as supported by Libgcrypt. Most likely, this 2449 will be "sha256" or "sha1". It is obvious that the length of BLOCK 2450 must match the size of that message digests; the function checks 2451 that this and other constraints are valid. 2452 2453 If PKCS#1 padding is not required (because the caller does already 2454 provide a padded value), either the old format or better the 2455 following format should be used: 2456 2457 (data 2458 (flags raw) 2459 (value MPI)) 2460 2461 Here, the data to be signed is directly given as an MPI. 2462 2463 For DSA the input data is expected in this format: 2464 2465 (data 2466 (flags raw) 2467 (value MPI)) 2468 2469 Here, the data to be signed is directly given as an MPI. It is 2470 expect that this MPI is the the hash value. For the standard DSA 2471 using a MPI is not a problem in regard to leading zeroes because 2472 the hash value is directly used as an MPI. For better standard 2473 conformance it would be better to explicit use a memory string 2474 (like with pkcs1) but that is currently not supported. However, 2475 for deterministic DSA as specified in RFC6979 this can't be used. 2476 Instead the following input is expected. 2477 2478 (data 2479 (flags rfc6979) 2480 (hash HASH-ALGO BLOCK)) 2481 2482 Note that the provided hash-algo is used for the internal HMAC; it 2483 should match the hash-algo used to create BLOCK. 2484 2485 The signature is returned as a newly allocated S-expression in 2486 R_SIG using this format for RSA: 2487 2488 (sig-val 2489 (rsa 2490 (s S-MPI))) 2491 2492 Where S-MPI is the result of the RSA sign operation. For DSA the 2493 S-expression returned is: 2494 2495 (sig-val 2496 (dsa 2497 (r R-MPI) 2498 (s S-MPI))) 2499 2500 Where R-MPI and S-MPI are the result of the DSA sign operation. 2501 2502 For Elgamal signing (which is slow, yields large numbers and 2503 probably is not as secure as the other algorithms), the same format 2504 is used with "elg" replacing "dsa"; for ECDSA signing, the same 2505 format is used with "ecdsa" replacing "dsa". 2506 2507 For the EdDSA algorithm (cf. Ed25515) the required input 2508 parameters are: 2509 2510 (data 2511 (flags eddsa) 2512 (hash-algo sha512) 2513 (value MESSAGE)) 2514 2515 Note that the MESSAGE may be of any length; hashing is part of the 2516 algorithm. Using a large data block for MESSAGE is in general not 2517 suggested; in that case the used protocol should better require 2518 that a hash of the message is used as input to the EdDSA algorithm. 2519 Note that for X.509 certificates MESSAGE is the 'tbsCertificate' 2520 part and in CMS MESSAGE is the 'signedAttrs' part; see RFC-8410 and 2521 RFC-8419. 2522 2523The operation most commonly used is definitely the verification of a 2524signature. Libgcrypt provides this function: 2525 2526 -- Function: gcry_error_t gcry_pk_verify (gcry_sexp_t SIG, 2527 gcry_sexp_t DATA, gcry_sexp_t PKEY) 2528 2529 This is used to check whether the signature SIG matches the DATA. 2530 The public key PKEY must be provided to perform this verification. 2531 This function is similar in its parameters to 'gcry_pk_sign' with 2532 the exceptions that the public key is used instead of the private 2533 key and that no signature is created but a signature, in a format 2534 as created by 'gcry_pk_sign', is passed to the function in SIG. 2535 2536 The result is 0 for success (i.e. the data matches the signature), 2537 or an error code where the most relevant code is 2538 'GCRY_ERR_BAD_SIGNATURE' to indicate that the signature does not 2539 match the provided data. 2540 2541 2542File: gcrypt.info, Node: Dedicated ECC Functions, Next: General public-key related Functions, Prev: Cryptographic Functions, Up: Public Key cryptography 2543 25446.4 Dedicated functions for elliptic curves. 2545============================================ 2546 2547The S-expression based interface is for certain operations on elliptic 2548curves not optimal. Thus a few special functions are implemented to 2549support common operations on curves with one of these assigned curve 2550ids: 2551 2552'GCRY_ECC_CURVE25519' 2553'GCRY_ECC_CURVE448' 2554 2555 -- Function: unsigned int gcry_ecc_get_algo_keylen (int CURVEID); 2556 2557 Returns the length in bytes of a point on the curve with the id 2558 CURVEID. 0 is returned for curves which have no assigned id. 2559 2560 -- Function: gpg_error_t gcry_ecc_mul_point (int CURVEID, 2561 unsigned char *RESULT, const unsigned char *SCALAR, 2562 const unsigned char *POINT) 2563 2564 This function computes the scalar multiplication on the Montgomery 2565 form of the curve with id CURVEID. If POINT is NULL the base point 2566 of the curve is used. The caller needs to provide a large enough 2567 buffer for RESULT and a valid SCALAR and POINT. 2568 2569 2570File: gcrypt.info, Node: General public-key related Functions, Prev: Dedicated ECC Functions, Up: Public Key cryptography 2571 25726.5 General public-key related Functions 2573======================================== 2574 2575A couple of utility functions are available to retrieve the length of 2576the key, map algorithm identifiers and perform sanity checks: 2577 2578 -- Function: const char * gcry_pk_algo_name (int ALGO) 2579 2580 Map the public key algorithm id ALGO to a string representation of 2581 the algorithm name. For unknown algorithms this functions returns 2582 the string '"?"'. This function should not be used to test for the 2583 availability of an algorithm. 2584 2585 -- Function: int gcry_pk_map_name (const char *NAME) 2586 2587 Map the algorithm NAME to a public key algorithm Id. Returns 0 if 2588 the algorithm name is not known. 2589 2590 -- Function: int gcry_pk_test_algo (int ALGO) 2591 2592 Return 0 if the public key algorithm ALGO is available for use. 2593 Note that this is implemented as a macro. 2594 2595 -- Function: unsigned int gcry_pk_get_nbits (gcry_sexp_t KEY) 2596 2597 Return what is commonly referred as the key length for the given 2598 public or private in KEY. 2599 2600 -- Function: unsigned char * gcry_pk_get_keygrip (gcry_sexp_t KEY, 2601 unsigned char *ARRAY) 2602 2603 Return the so called "keygrip" which is the SHA-1 hash of the 2604 public key parameters expressed in a way depended on the algorithm. 2605 ARRAY must either provide space for 20 bytes or be 'NULL'. In the 2606 latter case a newly allocated array of that size is returned. On 2607 success a pointer to the newly allocated space or to ARRAY is 2608 returned. 'NULL' is returned to indicate an error which is most 2609 likely an unknown algorithm or one where a "keygrip" has not yet 2610 been defined. The function accepts public or secret keys in KEY. 2611 2612 -- Function: gcry_error_t gcry_pk_testkey (gcry_sexp_t KEY) 2613 2614 Return zero if the private key KEY is 'sane', an error code 2615 otherwise. Note that it is not possible to check the 'saneness' of 2616 a public key. 2617 2618 -- Function: gcry_error_t gcry_pk_algo_info (int ALGO, int WHAT, 2619 void *BUFFER, size_t *NBYTES) 2620 2621 Depending on the value of WHAT return various information about the 2622 public key algorithm with the id ALGO. Note that the function 2623 returns '-1' on error and the actual error code must be retrieved 2624 using the function 'gcry_errno'. The currently defined values for 2625 WHAT are: 2626 2627 'GCRYCTL_TEST_ALGO:' 2628 Return 0 if the specified algorithm is available for use. 2629 BUFFER must be 'NULL', NBYTES may be passed as 'NULL' or point 2630 to a variable with the required usage of the algorithm. This 2631 may be 0 for "don't care" or the bit-wise OR of these flags: 2632 2633 'GCRY_PK_USAGE_SIGN' 2634 Algorithm is usable for signing. 2635 'GCRY_PK_USAGE_ENCR' 2636 Algorithm is usable for encryption. 2637 2638 Unless you need to test for the allowed usage, it is in 2639 general better to use the macro gcry_pk_test_algo instead. 2640 2641 'GCRYCTL_GET_ALGO_USAGE:' 2642 Return the usage flags for the given algorithm. An invalid 2643 algorithm return 0. Disabled algorithms are ignored here 2644 because we want to know whether the algorithm is at all 2645 capable of a certain usage. 2646 2647 'GCRYCTL_GET_ALGO_NPKEY' 2648 Return the number of elements the public key for algorithm 2649 ALGO consist of. Return 0 for an unknown algorithm. 2650 2651 'GCRYCTL_GET_ALGO_NSKEY' 2652 Return the number of elements the private key for algorithm 2653 ALGO consist of. Note that this value is always larger than 2654 that of the public key. Return 0 for an unknown algorithm. 2655 2656 'GCRYCTL_GET_ALGO_NSIGN' 2657 Return the number of elements a signature created with the 2658 algorithm ALGO consists of. Return 0 for an unknown algorithm 2659 or for an algorithm not capable of creating signatures. 2660 2661 'GCRYCTL_GET_ALGO_NENCR' 2662 Return the number of elements a encrypted message created with 2663 the algorithm ALGO consists of. Return 0 for an unknown 2664 algorithm or for an algorithm not capable of encryption. 2665 2666 Please note that parameters not required should be passed as 2667 'NULL'. 2668 2669 -- Function: gcry_error_t gcry_pk_ctl (int CMD, void *BUFFER, 2670 size_t BUFLEN) 2671 2672 This is a general purpose function to perform certain control 2673 operations. CMD controls what is to be done. The return value is 2674 0 for success or an error code. Currently supported values for CMD 2675 are: 2676 2677 'GCRYCTL_DISABLE_ALGO' 2678 Disable the algorithm given as an algorithm id in BUFFER. 2679 BUFFER must point to an 'int' variable with the algorithm id 2680 and BUFLEN must have the value 'sizeof (int)'. This function 2681 is not thread safe and should thus be used before any other 2682 threads are started. 2683 2684Libgcrypt also provides a function to generate public key pairs: 2685 2686 -- Function: gcry_error_t gcry_pk_genkey (gcry_sexp_t *R_KEY, 2687 gcry_sexp_t PARMS) 2688 2689 This function create a new public key pair using information given 2690 in the S-expression PARMS and stores the private and the public key 2691 in one new S-expression at the address given by R_KEY. In case of 2692 an error, R_KEY is set to 'NULL'. The return code is 0 for success 2693 or an error code otherwise. 2694 2695 Here is an example for PARMS to create an 2048 bit RSA key: 2696 2697 (genkey 2698 (rsa 2699 (nbits 4:2048))) 2700 2701 To create an Elgamal key, substitute "elg" for "rsa" and to create 2702 a DSA key use "dsa". Valid ranges for the key length depend on the 2703 algorithms; all commonly used key lengths are supported. Currently 2704 supported parameters are: 2705 2706 'nbits' 2707 This is always required to specify the length of the key. The 2708 argument is a string with a number in C-notation. The value 2709 should be a multiple of 8. Note that the S-expression syntax 2710 requires that a number is prefixed with its string length; 2711 thus the '4:' in the above example. 2712 2713 'curve NAME' 2714 For ECC a named curve may be used instead of giving the number 2715 of requested bits. This allows to request a specific curve to 2716 override a default selection Libgcrypt would have taken if 2717 'nbits' has been given. The available names are listed with 2718 the description of the ECC public key parameters. 2719 2720 'rsa-use-e VALUE' 2721 This is only used with RSA to give a hint for the public 2722 exponent. The VALUE will be used as a base to test for a 2723 usable exponent. Some values are special: 2724 2725 '0' 2726 Use a secure and fast value. This is currently the 2727 number 41. 2728 '1' 2729 Use a value as required by some crypto policies. This is 2730 currently the number 65537. 2731 '2' 2732 Reserved 2733 '> 2' 2734 Use the given value. 2735 2736 If this parameter is not used, Libgcrypt uses for historic 2737 reasons 65537. Note that the value must fit into a 32 bit 2738 unsigned variable and that the usual C prefixes are considered 2739 (e.g. 017 gives 15). 2740 2741 'qbits N' 2742 This is only meanigful for DSA keys. If it is given the DSA 2743 key is generated with a Q parameyer of size N bits. If it is 2744 not given or zero Q is deduced from NBITS in this way: 2745 '512 <= N <= 1024' 2746 Q = 160 2747 'N = 2048' 2748 Q = 224 2749 'N = 3072' 2750 Q = 256 2751 'N = 7680' 2752 Q = 384 2753 'N = 15360' 2754 Q = 512 2755 Note that in this case only the values for N, as given in the 2756 table, are allowed. When specifying Q all values of N in the 2757 range 512 to 15680 are valid as long as they are multiples of 2758 8. 2759 2760 'domain LIST' 2761 This is only meaningful for DLP algorithms. If specified keys 2762 are generated with domain parameters taken from this list. 2763 The exact format of this parameter depends on the actual 2764 algorithm. It is currently only implemented for DSA using 2765 this format: 2766 2767 (genkey 2768 (dsa 2769 (domain 2770 (p P-MPI) 2771 (q Q-MPI) 2772 (g Q-MPI)))) 2773 2774 'nbits' and 'qbits' may not be specified because they are 2775 derived from the domain parameters. 2776 2777 'derive-parms LIST' 2778 This is currently only implemented for RSA and DSA keys. It 2779 is not allowed to use this together with a 'domain' 2780 specification. If given, it is used to derive the keys using 2781 the given parameters. 2782 2783 If given for an RSA key the X9.31 key generation algorithm is 2784 used even if libgcrypt is not in FIPS mode. If given for a 2785 DSA key, the FIPS 186 algorithm is used even if libgcrypt is 2786 not in FIPS mode. 2787 2788 (genkey 2789 (rsa 2790 (nbits 4:1024) 2791 (rsa-use-e 1:3) 2792 (derive-parms 2793 (Xp1 #1A1916DDB29B4EB7EB6732E128#) 2794 (Xp2 #192E8AAC41C576C822D93EA433#) 2795 (Xp #D8CD81F035EC57EFE822955149D3BFF70C53520D 2796 769D6D76646C7A792E16EBD89FE6FC5B605A6493 2797 39DFC925A86A4C6D150B71B9EEA02D68885F5009 2798 B98BD984#) 2799 (Xq1 #1A5CF72EE770DE50CB09ACCEA9#) 2800 (Xq2 #134E4CAA16D2350A21D775C404#) 2801 (Xq #CC1092495D867E64065DEE3E7955F2EBC7D47A2D 2802 7C9953388F97DDDC3E1CA19C35CA659EDC2FC325 2803 6D29C2627479C086A699A49C4C9CEE7EF7BD1B34 2804 321DE34A#)))) 2805 2806 (genkey 2807 (dsa 2808 (nbits 4:1024) 2809 (derive-parms 2810 (seed SEED-MPI)))) 2811 2812 'flags FLAGLIST' 2813 This is preferred way to define flags. FLAGLIST may contain 2814 any number of flags. See above for a specification of these 2815 flags. 2816 2817 Here is an example on how to create a key using curve Ed25519 2818 with the ECDSA signature algorithm. Note that the use of 2819 ECDSA with that curve is in general not recommended. 2820 (genkey 2821 (ecc 2822 (flags transient-key))) 2823 2824 'transient-key' 2825 'use-x931' 2826 'use-fips186' 2827 'use-fips186-2' 2828 These are deprecated ways to set a flag with that name; see 2829 above for a description of each flag. 2830 2831 The key pair is returned in a format depending on the algorithm. 2832 Both private and public keys are returned in one container and may 2833 be accompanied by some miscellaneous information. 2834 2835 Here are two examples; the first for Elgamal and the second for 2836 elliptic curve key generation: 2837 2838 (key-data 2839 (public-key 2840 (elg 2841 (p P-MPI) 2842 (g G-MPI) 2843 (y Y-MPI))) 2844 (private-key 2845 (elg 2846 (p P-MPI) 2847 (g G-MPI) 2848 (y Y-MPI) 2849 (x X-MPI))) 2850 (misc-key-info 2851 (pm1-factors N1 N2 ... NN)) 2852 2853 (key-data 2854 (public-key 2855 (ecc 2856 (curve Ed25519) 2857 (flags eddsa) 2858 (q Q-VALUE))) 2859 (private-key 2860 (ecc 2861 (curve Ed25519) 2862 (flags eddsa) 2863 (q Q-VALUE) 2864 (d D-VALUE)))) 2865 2866 As you can see, some of the information is duplicated, but this 2867 provides an easy way to extract either the public or the private 2868 key. Note that the order of the elements is not defined, e.g. the 2869 private key may be stored before the public key. N1 N2 ... NN is a 2870 list of prime numbers used to composite P-MPI; this is in general 2871 not a very useful information and only available if the key 2872 generation algorithm provides them. 2873 2874Future versions of Libgcrypt will have extended versions of the public 2875key interfaced which will take an additional context to allow for 2876pre-computations, special operations, and other optimization. As a 2877first step a new function is introduced to help using the ECC algorithms 2878in new ways: 2879 2880 -- Function: gcry_error_t gcry_pubkey_get_sexp (gcry_sexp_t *R_SEXP, 2881 int MODE, gcry_ctx_t CTX) 2882 2883 Return an S-expression representing the context CTX. Depending on 2884 the state of that context, the S-expression may either be a public 2885 key, a private key or any other object used with public key 2886 operations. On success 0 is returned and a new S-expression is 2887 stored at R_SEXP; on error an error code is returned and NULL is 2888 stored at R_SEXP. MODE must be one of: 2889 2890 '0' 2891 Decide what to return depending on the context. For example 2892 if the private key parameter is available a private key is 2893 returned, if not a public key is returned. 2894 2895 'GCRY_PK_GET_PUBKEY' 2896 Return the public key even if the context has the private key 2897 parameter. 2898 2899 'GCRY_PK_GET_SECKEY' 2900 Return the private key or the error 'GPG_ERR_NO_SECKEY' if it 2901 is not possible. 2902 2903 As of now this function supports only certain ECC operations 2904 because a context object is right now only defined for ECC. Over 2905 time this function will be extended to cover more algorithms. 2906 2907 2908File: gcrypt.info, Node: Hashing, Next: Message Authentication Codes, Prev: Public Key cryptography, Up: Top 2909 29107 Hashing 2911********* 2912 2913Libgcrypt provides an easy and consistent to use interface for hashing. 2914Hashing is buffered and several hash algorithms can be updated at once. 2915It is possible to compute a HMAC using the same routines. The 2916programming model follows an open/process/close paradigm and is in that 2917similar to other building blocks provided by Libgcrypt. 2918 2919 For convenience reasons, a few cyclic redundancy check value 2920operations are also supported. 2921 2922* Menu: 2923 2924* Available hash algorithms:: List of hash algorithms supported by the library. 2925* Working with hash algorithms:: List of functions related to hashing. 2926 2927 2928File: gcrypt.info, Node: Available hash algorithms, Next: Working with hash algorithms, Up: Hashing 2929 29307.1 Available hash algorithms 2931============================= 2932 2933'GCRY_MD_NONE' 2934 This is not a real algorithm but used by some functions as an error 2935 return value. This constant is guaranteed to have the value '0'. 2936 2937'GCRY_MD_SHA1' 2938 This is the SHA-1 algorithm which yields a message digest of 20 2939 bytes. Note that SHA-1 begins to show some weaknesses and it is 2940 suggested to fade out its use if strong cryptographic properties 2941 are required. 2942 2943'GCRY_MD_RMD160' 2944 This is the 160 bit version of the RIPE message digest 2945 (RIPE-MD-160). Like SHA-1 it also yields a digest of 20 bytes. 2946 This algorithm share a lot of design properties with SHA-1 and thus 2947 it is advisable not to use it for new protocols. 2948 2949'GCRY_MD_MD5' 2950 This is the well known MD5 algorithm, which yields a message digest 2951 of 16 bytes. Note that the MD5 algorithm has severe weaknesses, 2952 for example it is easy to compute two messages yielding the same 2953 hash (collision attack). The use of this algorithm is only 2954 justified for non-cryptographic application. 2955 2956'GCRY_MD_MD4' 2957 This is the MD4 algorithm, which yields a message digest of 16 2958 bytes. This algorithm has severe weaknesses and should not be 2959 used. 2960 2961'GCRY_MD_MD2' 2962 This is an reserved identifier for MD-2; there is no implementation 2963 yet. This algorithm has severe weaknesses and should not be used. 2964 2965'GCRY_MD_TIGER' 2966 This is the TIGER/192 algorithm which yields a message digest of 24 2967 bytes. Actually this is a variant of TIGER with a different output 2968 print order as used by GnuPG up to version 1.3.2. 2969 2970'GCRY_MD_TIGER1' 2971 This is the TIGER variant as used by the NESSIE project. It uses 2972 the most commonly used output print order. 2973 2974'GCRY_MD_TIGER2' 2975 This is another variant of TIGER with a different padding scheme. 2976 2977'GCRY_MD_HAVAL' 2978 This is an reserved value for the HAVAL algorithm with 5 passes and 2979 160 bit. It yields a message digest of 20 bytes. Note that there 2980 is no implementation yet available. 2981 2982'GCRY_MD_SHA224' 2983 This is the SHA-224 algorithm which yields a message digest of 28 2984 bytes. See Change Notice 1 for FIPS 180-2 for the specification. 2985 2986'GCRY_MD_SHA256' 2987 This is the SHA-256 algorithm which yields a message digest of 32 2988 bytes. See FIPS 180-2 for the specification. 2989 2990'GCRY_MD_SHA384' 2991 This is the SHA-384 algorithm which yields a message digest of 48 2992 bytes. See FIPS 180-2 for the specification. 2993 2994'GCRY_MD_SHA512' 2995 This is the SHA-512 algorithm which yields a message digest of 64 2996 bytes. See FIPS 180-2 for the specification. 2997 2998'GCRY_MD_SHA512_224' 2999 This is the SHA-512/224 algorithm which yields a message digest of 3000 28 bytes. See FIPS 180-4 for the specification. 3001 3002'GCRY_MD_SHA512_256' 3003 This is the SHA-512/256 algorithm which yields a message digest of 3004 32 bytes. See FIPS 180-4 for the specification. 3005 3006'GCRY_MD_SHA3_224' 3007 This is the SHA3-224 algorithm which yields a message digest of 28 3008 bytes. See FIPS 202 for the specification. 3009 3010'GCRY_MD_SHA3_256' 3011 This is the SHA3-256 algorithm which yields a message digest of 32 3012 bytes. See FIPS 202 for the specification. 3013 3014'GCRY_MD_SHA3_384' 3015 This is the SHA3-384 algorithm which yields a message digest of 48 3016 bytes. See FIPS 202 for the specification. 3017 3018'GCRY_MD_SHA3_512' 3019 This is the SHA3-512 algorithm which yields a message digest of 64 3020 bytes. See FIPS 202 for the specification. 3021 3022'GCRY_MD_SHAKE128' 3023 This is the SHAKE128 extendable-output function (XOF) algorithm 3024 with 128 bit security strength. See FIPS 202 for the 3025 specification. 3026 3027'GCRY_MD_SHAKE256' 3028 This is the SHAKE256 extendable-output function (XOF) algorithm 3029 with 256 bit security strength. See FIPS 202 for the 3030 specification. 3031 3032'GCRY_MD_CRC32' 3033 This is the ISO 3309 and ITU-T V.42 cyclic redundancy check. It 3034 yields an output of 4 bytes. Note that this is not a hash 3035 algorithm in the cryptographic sense. 3036 3037'GCRY_MD_CRC32_RFC1510' 3038 This is the above cyclic redundancy check function, as modified by 3039 RFC 1510. It yields an output of 4 bytes. Note that this is not a 3040 hash algorithm in the cryptographic sense. 3041 3042'GCRY_MD_CRC24_RFC2440' 3043 This is the OpenPGP cyclic redundancy check function. It yields an 3044 output of 3 bytes. Note that this is not a hash algorithm in the 3045 cryptographic sense. 3046 3047'GCRY_MD_WHIRLPOOL' 3048 This is the Whirlpool algorithm which yields a message digest of 64 3049 bytes. 3050 3051'GCRY_MD_GOSTR3411_94' 3052 This is the hash algorithm described in GOST R 34.11-94 which 3053 yields a message digest of 32 bytes. 3054 3055'GCRY_MD_STRIBOG256' 3056 This is the 256-bit version of hash algorithm described in GOST R 3057 34.11-2012 which yields a message digest of 32 bytes. 3058 3059'GCRY_MD_STRIBOG512' 3060 This is the 512-bit version of hash algorithm described in GOST R 3061 34.11-2012 which yields a message digest of 64 bytes. 3062 3063'GCRY_MD_BLAKE2B_512' 3064 This is the BLAKE2b-512 algorithm which yields a message digest of 3065 64 bytes. See RFC 7693 for the specification. 3066 3067'GCRY_MD_BLAKE2B_384' 3068 This is the BLAKE2b-384 algorithm which yields a message digest of 3069 48 bytes. See RFC 7693 for the specification. 3070 3071'GCRY_MD_BLAKE2B_256' 3072 This is the BLAKE2b-256 algorithm which yields a message digest of 3073 32 bytes. See RFC 7693 for the specification. 3074 3075'GCRY_MD_BLAKE2B_160' 3076 This is the BLAKE2b-160 algorithm which yields a message digest of 3077 20 bytes. See RFC 7693 for the specification. 3078 3079'GCRY_MD_BLAKE2S_256' 3080 This is the BLAKE2s-256 algorithm which yields a message digest of 3081 32 bytes. See RFC 7693 for the specification. 3082 3083'GCRY_MD_BLAKE2S_224' 3084 This is the BLAKE2s-224 algorithm which yields a message digest of 3085 28 bytes. See RFC 7693 for the specification. 3086 3087'GCRY_MD_BLAKE2S_160' 3088 This is the BLAKE2s-160 algorithm which yields a message digest of 3089 20 bytes. See RFC 7693 for the specification. 3090 3091'GCRY_MD_BLAKE2S_128' 3092 This is the BLAKE2s-128 algorithm which yields a message digest of 3093 16 bytes. See RFC 7693 for the specification. 3094 3095'GCRY_MD_SM3' 3096 This is the SM3 algorithm which yields a message digest of 32 3097 bytes. 3098 3099 3100File: gcrypt.info, Node: Working with hash algorithms, Prev: Available hash algorithms, Up: Hashing 3101 31027.2 Working with hash algorithms 3103================================ 3104 3105To use most of these function it is necessary to create a context; this 3106is done using: 3107 3108 -- Function: gcry_error_t gcry_md_open (gcry_md_hd_t *HD, int ALGO, 3109 unsigned int FLAGS) 3110 3111 Create a message digest object for algorithm ALGO. FLAGS may be 3112 given as an bitwise OR of constants described below. ALGO may be 3113 given as '0' if the algorithms to use are later set using 3114 'gcry_md_enable'. HD is guaranteed to either receive a valid 3115 handle or NULL. 3116 3117 For a list of supported algorithms, see *note Available hash 3118 algorithms::. 3119 3120 The flags allowed for MODE are: 3121 3122 'GCRY_MD_FLAG_SECURE' 3123 Allocate all buffers and the resulting digest in "secure 3124 memory". Use this is the hashed data is highly confidential. 3125 3126 'GCRY_MD_FLAG_HMAC' 3127 Turn the algorithm into a HMAC message authentication 3128 algorithm. This only works if just one algorithm is enabled 3129 for the handle and that algorithm is not an extendable-output 3130 function. Note that the function 'gcry_md_setkey' must be 3131 used to set the MAC key. The size of the MAC is equal to the 3132 message digest of the underlying hash algorithm. If you want 3133 CBC message authentication codes based on a cipher, see *note 3134 Working with cipher handles::. 3135 3136 'GCRY_MD_FLAG_BUGEMU1' 3137 Versions of Libgcrypt before 1.6.0 had a bug in the Whirlpool 3138 code which led to a wrong result for certain input sizes and 3139 write patterns. Using this flag emulates that bug. This may 3140 for example be useful for applications which use Whirlpool as 3141 part of their key generation. It is strongly suggested to use 3142 this flag only if really needed and if possible to the data 3143 should be re-processed using the regular Whirlpool algorithm. 3144 3145 Note that this flag works for the entire hash context. If 3146 needed arises it may be used to enable bug emulation for other 3147 hash algorithms. Thus you should not use this flag for a 3148 multi-algorithm hash context. 3149 3150 You may use the function 'gcry_md_is_enabled' to later check 3151 whether an algorithm has been enabled. 3152 3153 If you want to calculate several hash algorithms at the same time, 3154you have to use the following function right after the 'gcry_md_open': 3155 3156 -- Function: gcry_error_t gcry_md_enable (gcry_md_hd_t H, int ALGO) 3157 3158 Add the message digest algorithm ALGO to the digest object 3159 described by handle H. Duplicated enabling of algorithms is 3160 detected and ignored. 3161 3162 If the flag 'GCRY_MD_FLAG_HMAC' was used, the key for the MAC must be 3163set using the function: 3164 3165 -- Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t H, const void 3166 *KEY, size_t KEYLEN) 3167 3168 For use with the HMAC feature or BLAKE2 keyed hash, set the MAC key 3169 to the value of KEY of length KEYLEN bytes. For HMAC, there is no 3170 restriction on the length of the key. For keyed BLAKE2b hash, 3171 length of the key must be 64 bytes or less. For keyed BLAKE2s 3172 hash, length of the key must be 32 bytes or less. 3173 3174 After you are done with the hash calculation, you should release the 3175resources by using: 3176 3177 -- Function: void gcry_md_close (gcry_md_hd_t H) 3178 3179 Release all resources of hash context H. H should not be used 3180 after a call to this function. A 'NULL' passed as H is ignored. 3181 The function also zeroises all sensitive information associated 3182 with this handle. 3183 3184 Often you have to do several hash operations using the same 3185algorithm. To avoid the overhead of creating and releasing context, a 3186reset function is provided: 3187 3188 -- Function: void gcry_md_reset (gcry_md_hd_t H) 3189 3190 Reset the current context to its initial state. This is 3191 effectively identical to a close followed by an open and enabling 3192 all currently active algorithms. 3193 3194 Often it is necessary to start hashing some data and then continue to 3195hash different data. To avoid hashing the same data several times 3196(which might not even be possible if the data is received from a pipe), 3197a snapshot of the current hash context can be taken and turned into a 3198new context: 3199 3200 -- Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *HANDLE_DST, 3201 gcry_md_hd_t HANDLE_SRC) 3202 3203 Create a new digest object as an exact copy of the object described 3204 by handle HANDLE_SRC and store it in HANDLE_DST. The context is 3205 not reset and you can continue to hash data using this context and 3206 independently using the original context. 3207 3208 Now that we have prepared everything to calculate hashes, it is time 3209to see how it is actually done. There are two ways for this, one to 3210update the hash with a block of memory and one macro to update the hash 3211by just one character. Both methods can be used on the same hash 3212context. 3213 3214 -- Function: void gcry_md_write (gcry_md_hd_t H, const void *BUFFER, 3215 size_t LENGTH) 3216 3217 Pass LENGTH bytes of the data in BUFFER to the digest object with 3218 handle H to update the digest values. This function should be used 3219 for large blocks of data. If this function is used after the 3220 context has been finalized, it will keep on pushing the data 3221 through the algorithm specific transform function and change the 3222 context; however the results are not meaningful and this feature is 3223 only available to mitigate timing attacks. 3224 3225 -- Function: void gcry_md_putc (gcry_md_hd_t H, int C) 3226 3227 Pass the byte in C to the digest object with handle H to update the 3228 digest value. This is an efficient function, implemented as a 3229 macro to buffer the data before an actual update. 3230 3231 The semantics of the hash functions do not provide for reading out 3232intermediate message digests because the calculation must be finalized 3233first. This finalization may for example include the number of bytes 3234hashed in the message digest or some padding. 3235 3236 -- Function: void gcry_md_final (gcry_md_hd_t H) 3237 3238 Finalize the message digest calculation. This is not really needed 3239 because 'gcry_md_read' and 'gcry_md_extract' do this implicitly. 3240 After this has been done no further updates (by means of 3241 'gcry_md_write' or 'gcry_md_putc' should be done; However, to 3242 mitigate timing attacks it is sometimes useful to keep on updating 3243 the context after having stored away the actual digest. Only the 3244 first call to this function has an effect. It is implemented as a 3245 macro. 3246 3247 The way to read out the calculated message digest is by using the 3248function: 3249 3250 -- Function: unsigned char * gcry_md_read (gcry_md_hd_t H, int ALGO) 3251 3252 'gcry_md_read' returns the message digest after finalizing the 3253 calculation. This function may be used as often as required but it 3254 will always return the same value for one handle. The returned 3255 message digest is allocated within the message context and 3256 therefore valid until the handle is released or reset-ed (using 3257 'gcry_md_close' or 'gcry_md_reset' or it has been updated as a 3258 mitigation measure against timing attacks. ALGO may be given as 0 3259 to return the only enabled message digest or it may specify one of 3260 the enabled algorithms. The function does return 'NULL' if the 3261 requested algorithm has not been enabled. 3262 3263 The way to read output of extendable-output function is by using the 3264function: 3265 3266 -- Function: gpg_err_code_t gcry_md_extract (gcry_md_hd_t H, int ALGO, 3267 void *BUFFER, size_t LENGTH) 3268 3269 'gcry_mac_read' returns output from extendable-output function. 3270 This function may be used as often as required to generate more 3271 output byte stream from the algorithm. Function extracts the new 3272 output bytes to BUFFER of the length LENGTH. Buffer will be fully 3273 populated with new output. ALGO may be given as 0 to return the 3274 only enabled message digest or it may specify one of the enabled 3275 algorithms. The function does return non-zero value if the 3276 requested algorithm has not been enabled. 3277 3278 Because it is often necessary to get the message digest of blocks of 3279memory, two fast convenience function are available for this task: 3280 3281 -- Function: gpg_err_code_t gcry_md_hash_buffers ( int ALGO, 3282 unsigned int FLAGS, void *DIGEST, const gcry_buffer_t *IOV, 3283 int IOVCNT ) 3284 3285 'gcry_md_hash_buffers' is a shortcut function to calculate a 3286 message digest from several buffers. This function does not 3287 require a context and immediately returns the message digest of the 3288 data described by IOV and IOVCNT. DIGEST must be allocated by the 3289 caller, large enough to hold the message digest yielded by the the 3290 specified algorithm ALGO. This required size may be obtained by 3291 using the function 'gcry_md_get_algo_dlen'. 3292 3293 IOV is an array of buffer descriptions with IOVCNT items. The 3294 caller should zero out the structures in this array and for each 3295 array item set the fields '.data' to the address of the data to be 3296 hashed, '.len' to number of bytes to be hashed. If .OFF is also 3297 set, the data is taken starting at .OFF bytes from the begin of the 3298 buffer. The field '.size' is not used. 3299 3300 The only supported flag value for FLAGS is GCRY_MD_FLAG_HMAC which 3301 turns this function into a HMAC function; the first item in IOV is 3302 then used as the key. 3303 3304 On success the function returns 0 and stores the resulting hash or 3305 MAC at DIGEST. 3306 3307 -- Function: void gcry_md_hash_buffer (int ALGO, void *DIGEST, const 3308 void *BUFFER, size_t LENGTH); 3309 3310 'gcry_md_hash_buffer' is a shortcut function to calculate a message 3311 digest of a buffer. This function does not require a context and 3312 immediately returns the message digest of the LENGTH bytes at 3313 BUFFER. DIGEST must be allocated by the caller, large enough to 3314 hold the message digest yielded by the the specified algorithm 3315 ALGO. This required size may be obtained by using the function 3316 'gcry_md_get_algo_dlen'. 3317 3318 Note that in contrast to 'gcry_md_hash_buffers' this function will 3319 abort the process if an unavailable algorithm is used. 3320 3321 Hash algorithms are identified by internal algorithm numbers (see 3322'gcry_md_open' for a list). However, in most applications they are used 3323by names, so two functions are available to map between string 3324representations and hash algorithm identifiers. 3325 3326 -- Function: const char * gcry_md_algo_name (int ALGO) 3327 3328 Map the digest algorithm id ALGO to a string representation of the 3329 algorithm name. For unknown algorithms this function returns the 3330 string '"?"'. This function should not be used to test for the 3331 availability of an algorithm. 3332 3333 -- Function: int gcry_md_map_name (const char *NAME) 3334 3335 Map the algorithm with NAME to a digest algorithm identifier. 3336 Returns 0 if the algorithm name is not known. Names representing 3337 ASN.1 object identifiers are recognized if the IETF dotted format 3338 is used and the OID is prefixed with either "'oid.'" or "'OID.'". 3339 For a list of supported OIDs, see the source code at 'cipher/md.c'. 3340 This function should not be used to test for the availability of an 3341 algorithm. 3342 3343 -- Function: gcry_error_t gcry_md_get_asnoid (int ALGO, void *BUFFER, 3344 size_t *LENGTH) 3345 3346 Return an DER encoded ASN.1 OID for the algorithm ALGO in the user 3347 allocated BUFFER. LENGTH must point to variable with the available 3348 size of BUFFER and receives after return the actual size of the 3349 returned OID. The returned error code may be 'GPG_ERR_TOO_SHORT' if 3350 the provided buffer is to short to receive the OID; it is possible 3351 to call the function with 'NULL' for BUFFER to have it only return 3352 the required size. The function returns 0 on success. 3353 3354 To test whether an algorithm is actually available for use, the 3355following macro should be used: 3356 3357 -- Function: gcry_error_t gcry_md_test_algo (int ALGO) 3358 3359 The macro returns 0 if the algorithm ALGO is available for use. 3360 3361 If the length of a message digest is not known, it can be retrieved 3362using the following function: 3363 3364 -- Function: unsigned int gcry_md_get_algo_dlen (int ALGO) 3365 3366 Retrieve the length in bytes of the digest yielded by algorithm 3367 ALGO. This is often used prior to 'gcry_md_read' to allocate 3368 sufficient memory for the digest. 3369 3370 In some situations it might be hard to remember the algorithm used 3371for the ongoing hashing. The following function might be used to get 3372that information: 3373 3374 -- Function: int gcry_md_get_algo (gcry_md_hd_t H) 3375 3376 Retrieve the algorithm used with the handle H. Note that this does 3377 not work reliable if more than one algorithm is enabled in H. 3378 3379 The following macro might also be useful: 3380 3381 -- Function: int gcry_md_is_secure (gcry_md_hd_t H) 3382 3383 This function returns true when the digest object H is allocated in 3384 "secure memory"; i.e. H was created with the 3385 'GCRY_MD_FLAG_SECURE'. 3386 3387 -- Function: int gcry_md_is_enabled (gcry_md_hd_t H, int ALGO) 3388 3389 This function returns true when the algorithm ALGO has been enabled 3390 for the digest object H. 3391 3392 Tracking bugs related to hashing is often a cumbersome task which 3393requires to add a lot of printf statements into the code. Libgcrypt 3394provides an easy way to avoid this. The actual data hashed can be 3395written to files on request. 3396 3397 -- Function: void gcry_md_debug (gcry_md_hd_t H, const char *SUFFIX) 3398 3399 Enable debugging for the digest object with handle H. This creates 3400 files named 'dbgmd-<n>.<string>' while doing the actual hashing. 3401 SUFFIX is the string part in the filename. The number is a counter 3402 incremented for each new hashing. The data in the file is the raw 3403 data as passed to 'gcry_md_write' or 'gcry_md_putc'. If 'NULL' is 3404 used for SUFFIX, the debugging is stopped and the file closed. 3405 This is only rarely required because 'gcry_md_close' implicitly 3406 stops debugging. 3407 3408 3409File: gcrypt.info, Node: Message Authentication Codes, Next: Key Derivation, Prev: Hashing, Up: Top 3410 34118 Message Authentication Codes 3412****************************** 3413 3414Libgcrypt provides an easy and consistent to use interface for 3415generating Message Authentication Codes (MAC). MAC generation is 3416buffered and interface similar to the one used with hash algorithms. 3417The programming model follows an open/process/close paradigm and is in 3418that similar to other building blocks provided by Libgcrypt. 3419 3420* Menu: 3421 3422* Available MAC algorithms:: List of MAC algorithms supported by the library. 3423* Working with MAC algorithms:: List of functions related to MAC algorithms. 3424 3425 3426File: gcrypt.info, Node: Available MAC algorithms, Next: Working with MAC algorithms, Up: Message Authentication Codes 3427 34288.1 Available MAC algorithms 3429============================ 3430 3431'GCRY_MAC_NONE' 3432 This is not a real algorithm but used by some functions as an error 3433 return value. This constant is guaranteed to have the value '0'. 3434 3435'GCRY_MAC_HMAC_SHA256' 3436 This is keyed-hash message authentication code (HMAC) message 3437 authentication algorithm based on the SHA-256 hash algorithm. 3438 3439'GCRY_MAC_HMAC_SHA224' 3440 This is HMAC message authentication algorithm based on the SHA-224 3441 hash algorithm. 3442 3443'GCRY_MAC_HMAC_SHA512' 3444 This is HMAC message authentication algorithm based on the SHA-512 3445 hash algorithm. 3446 3447'GCRY_MAC_HMAC_SHA384' 3448 This is HMAC message authentication algorithm based on the SHA-384 3449 hash algorithm. 3450 3451'GCRY_MAC_HMAC_SHA3_256' 3452 This is HMAC message authentication algorithm based on the SHA3-256 3453 hash algorithm. 3454 3455'GCRY_MAC_HMAC_SHA3_224' 3456 This is HMAC message authentication algorithm based on the SHA3-224 3457 hash algorithm. 3458 3459'GCRY_MAC_HMAC_SHA3_512' 3460 This is HMAC message authentication algorithm based on the SHA3-512 3461 hash algorithm. 3462 3463'GCRY_MAC_HMAC_SHA3_384' 3464 This is HMAC message authentication algorithm based on the SHA3-384 3465 hash algorithm. 3466 3467'GCRY_MAC_HMAC_SHA512_224' 3468 This is HMAC message authentication algorithm based on the 3469 SHA-512/224 hash algorithm. 3470 3471'GCRY_MAC_HMAC_SHA512_256' 3472 This is HMAC message authentication algorithm based on the 3473 SHA-512/256 hash algorithm. 3474 3475'GCRY_MAC_HMAC_SHA1' 3476 This is HMAC message authentication algorithm based on the SHA-1 3477 hash algorithm. 3478 3479'GCRY_MAC_HMAC_MD5' 3480 This is HMAC message authentication algorithm based on the MD5 hash 3481 algorithm. 3482 3483'GCRY_MAC_HMAC_MD4' 3484 This is HMAC message authentication algorithm based on the MD4 hash 3485 algorithm. 3486 3487'GCRY_MAC_HMAC_RMD160' 3488 This is HMAC message authentication algorithm based on the 3489 RIPE-MD-160 hash algorithm. 3490 3491'GCRY_MAC_HMAC_WHIRLPOOL' 3492 This is HMAC message authentication algorithm based on the 3493 WHIRLPOOL hash algorithm. 3494 3495'GCRY_MAC_HMAC_GOSTR3411_94' 3496 This is HMAC message authentication algorithm based on the GOST R 3497 34.11-94 hash algorithm. 3498 3499'GCRY_MAC_HMAC_STRIBOG256' 3500 This is HMAC message authentication algorithm based on the 256-bit 3501 hash algorithm described in GOST R 34.11-2012. 3502 3503'GCRY_MAC_HMAC_STRIBOG512' 3504 This is HMAC message authentication algorithm based on the 512-bit 3505 hash algorithm described in GOST R 34.11-2012. 3506 3507'GCRY_MAC_HMAC_BLAKE2B_512' 3508 This is HMAC message authentication algorithm based on the 3509 BLAKE2b-512 hash algorithm. 3510 3511'GCRY_MAC_HMAC_BLAKE2B_384' 3512 This is HMAC message authentication algorithm based on the 3513 BLAKE2b-384 hash algorithm. 3514 3515'GCRY_MAC_HMAC_BLAKE2B_256' 3516 This is HMAC message authentication algorithm based on the 3517 BLAKE2b-256 hash algorithm. 3518 3519'GCRY_MAC_HMAC_BLAKE2B_160' 3520 This is HMAC message authentication algorithm based on the 3521 BLAKE2b-160 hash algorithm. 3522 3523'GCRY_MAC_HMAC_BLAKE2S_256' 3524 This is HMAC message authentication algorithm based on the 3525 BLAKE2s-256 hash algorithm. 3526 3527'GCRY_MAC_HMAC_BLAKE2S_224' 3528 This is HMAC message authentication algorithm based on the 3529 BLAKE2s-224 hash algorithm. 3530 3531'GCRY_MAC_HMAC_BLAKE2S_160' 3532 This is HMAC message authentication algorithm based on the 3533 BLAKE2s-160 hash algorithm. 3534 3535'GCRY_MAC_HMAC_BLAKE2S_128' 3536 This is HMAC message authentication algorithm based on the 3537 BLAKE2s-128 hash algorithm. 3538 3539'GCRY_MAC_HMAC_SM3' 3540 This is HMAC message authentication algorithm based on the SM3 hash 3541 algorithm. 3542 3543'GCRY_MAC_CMAC_AES' 3544 This is CMAC (Cipher-based MAC) message authentication algorithm 3545 based on the AES block cipher algorithm. 3546 3547'GCRY_MAC_CMAC_3DES' 3548 This is CMAC message authentication algorithm based on the 3549 three-key EDE Triple-DES block cipher algorithm. 3550 3551'GCRY_MAC_CMAC_CAMELLIA' 3552 This is CMAC message authentication algorithm based on the Camellia 3553 block cipher algorithm. 3554 3555'GCRY_MAC_CMAC_CAST5' 3556 This is CMAC message authentication algorithm based on the 3557 CAST128-5 block cipher algorithm. 3558 3559'GCRY_MAC_CMAC_BLOWFISH' 3560 This is CMAC message authentication algorithm based on the Blowfish 3561 block cipher algorithm. 3562 3563'GCRY_MAC_CMAC_TWOFISH' 3564 This is CMAC message authentication algorithm based on the Twofish 3565 block cipher algorithm. 3566 3567'GCRY_MAC_CMAC_SERPENT' 3568 This is CMAC message authentication algorithm based on the Serpent 3569 block cipher algorithm. 3570 3571'GCRY_MAC_CMAC_SEED' 3572 This is CMAC message authentication algorithm based on the SEED 3573 block cipher algorithm. 3574 3575'GCRY_MAC_CMAC_RFC2268' 3576 This is CMAC message authentication algorithm based on the Ron's 3577 Cipher 2 block cipher algorithm. 3578 3579'GCRY_MAC_CMAC_IDEA' 3580 This is CMAC message authentication algorithm based on the IDEA 3581 block cipher algorithm. 3582 3583'GCRY_MAC_CMAC_GOST28147' 3584 This is CMAC message authentication algorithm based on the GOST 3585 28147-89 block cipher algorithm. 3586 3587'GCRY_MAC_CMAC_SM4' 3588 This is CMAC message authentication algorithm based on the SM4 3589 block cipher algorithm. 3590 3591'GCRY_MAC_GMAC_AES' 3592 This is GMAC (GCM mode based MAC) message authentication algorithm 3593 based on the AES block cipher algorithm. 3594 3595'GCRY_MAC_GMAC_CAMELLIA' 3596 This is GMAC message authentication algorithm based on the Camellia 3597 block cipher algorithm. 3598 3599'GCRY_MAC_GMAC_TWOFISH' 3600 This is GMAC message authentication algorithm based on the Twofish 3601 block cipher algorithm. 3602 3603'GCRY_MAC_GMAC_SERPENT' 3604 This is GMAC message authentication algorithm based on the Serpent 3605 block cipher algorithm. 3606 3607'GCRY_MAC_GMAC_SEED' 3608 This is GMAC message authentication algorithm based on the SEED 3609 block cipher algorithm. 3610 3611'GCRY_MAC_POLY1305' 3612 This is plain Poly1305 message authentication algorithm, used with 3613 one-time key. 3614 3615'GCRY_MAC_POLY1305_AES' 3616 This is Poly1305-AES message authentication algorithm, used with 3617 key and one-time nonce. 3618 3619'GCRY_MAC_POLY1305_CAMELLIA' 3620 This is Poly1305-Camellia message authentication algorithm, used 3621 with key and one-time nonce. 3622 3623'GCRY_MAC_POLY1305_TWOFISH' 3624 This is Poly1305-Twofish message authentication algorithm, used 3625 with key and one-time nonce. 3626 3627'GCRY_MAC_POLY1305_SERPENT' 3628 This is Poly1305-Serpent message authentication algorithm, used 3629 with key and one-time nonce. 3630 3631'GCRY_MAC_POLY1305_SEED' 3632 This is Poly1305-SEED message authentication algorithm, used with 3633 key and one-time nonce. 3634 3635'GCRY_MAC_GOST28147_IMIT' 3636 This is MAC construction defined in GOST 28147-89 (see RFC 5830 3637 Section 8). 3638 3639 3640File: gcrypt.info, Node: Working with MAC algorithms, Prev: Available MAC algorithms, Up: Message Authentication Codes 3641 36428.2 Working with MAC algorithms 3643=============================== 3644 3645To use most of these function it is necessary to create a context; this 3646is done using: 3647 3648 -- Function: gcry_error_t gcry_mac_open (gcry_mac_hd_t *HD, int ALGO, 3649 unsigned int FLAGS, gcry_ctx_t CTX) 3650 3651 Create a MAC object for algorithm ALGO. FLAGS may be given as an 3652 bitwise OR of constants described below. HD is guaranteed to 3653 either receive a valid handle or NULL. CTX is context object to 3654 associate MAC object with. CTX maybe set to NULL. 3655 3656 For a list of supported algorithms, see *note Available MAC 3657 algorithms::. 3658 3659 The flags allowed for MODE are: 3660 3661 'GCRY_MAC_FLAG_SECURE' 3662 Allocate all buffers and the resulting MAC in "secure memory". 3663 Use this if the MAC data is highly confidential. 3664 3665 In order to use a handle for performing MAC algorithm operations, a 3666'key' has to be set first: 3667 3668 -- Function: gcry_error_t gcry_mac_setkey (gcry_mac_hd_t H, const void 3669 *KEY, size_t KEYLEN) 3670 3671 Set the MAC key to the value of KEY of length KEYLEN bytes. With 3672 HMAC algorithms, there is no restriction on the length of the key. 3673 With CMAC algorithms, the length of the key is restricted to those 3674 supported by the underlying block cipher. 3675 3676 GMAC algorithms and Poly1305-with-cipher algorithms need 3677initialization vector to be set, which can be performed with function: 3678 3679 -- Function: gcry_error_t gcry_mac_setiv (gcry_mac_hd_t H, const void 3680 *IV, size_t IVLEN) 3681 3682 Set the IV to the value of IV of length IVLEN bytes. 3683 3684 After you are done with the MAC calculation, you should release the 3685resources by using: 3686 3687 -- Function: void gcry_mac_close (gcry_mac_hd_t H) 3688 3689 Release all resources of MAC context H. H should not be used after 3690 a call to this function. A 'NULL' passed as H is ignored. The 3691 function also clears all sensitive information associated with this 3692 handle. 3693 3694 Often you have to do several MAC operations using the same algorithm. 3695To avoid the overhead of creating and releasing context, a reset 3696function is provided: 3697 3698 -- Function: gcry_error_t gcry_mac_reset (gcry_mac_hd_t H) 3699 3700 Reset the current context to its initial state. This is 3701 effectively identical to a close followed by an open and setting 3702 same key. 3703 3704 Note that gcry_mac_reset is implemented as a macro. 3705 3706 Now that we have prepared everything to calculate MAC, it is time to 3707see how it is actually done. 3708 3709 -- Function: gcry_error_t gcry_mac_write (gcry_mac_hd_t H, const void 3710 *BUFFER, size_t LENGTH) 3711 3712 Pass LENGTH bytes of the data in BUFFER to the MAC object with 3713 handle H to update the MAC values. If this function is used after 3714 the context has been finalized, it will keep on pushing the data 3715 through the algorithm specific transform function and thereby 3716 change the context; however the results are not meaningful and this 3717 feature is only available to mitigate timing attacks. 3718 3719 The way to read out the calculated MAC is by using the function: 3720 3721 -- Function: gcry_error_t gcry_mac_read (gcry_mac_hd_t H, void *BUFFER, 3722 size_t *LENGTH) 3723 3724 'gcry_mac_read' returns the MAC after finalizing the calculation. 3725 Function copies the resulting MAC value to BUFFER of the length 3726 LENGTH. If LENGTH is larger than length of resulting MAC value, 3727 then length of MAC is returned through LENGTH. 3728 3729 To compare existing MAC value with recalculated MAC, one is to use 3730the function: 3731 3732 -- Function: gcry_error_t gcry_mac_verify (gcry_mac_hd_t H, void 3733 *BUFFER, size_t LENGTH) 3734 3735 'gcry_mac_verify' finalizes MAC calculation and compares result 3736 with LENGTH bytes of data in BUFFER. Error code 'GPG_ERR_CHECKSUM' 3737 is returned if the MAC value in the buffer BUFFER does not match 3738 the MAC calculated in object H. 3739 3740 In some situations it might be hard to remember the algorithm used 3741for the MAC calculation. The following function might be used to get 3742that information: 3743 3744 -- Function: int gcry_mac_get_algo (gcry_mac_hd_t H) 3745 3746 Retrieve the algorithm used with the handle H. 3747 3748 MAC algorithms are identified by internal algorithm numbers (see 3749'gcry_mac_open' for a list). However, in most applications they are 3750used by names, so two functions are available to map between string 3751representations and MAC algorithm identifiers. 3752 3753 -- Function: const char * gcry_mac_algo_name (int ALGO) 3754 3755 Map the MAC algorithm id ALGO to a string representation of the 3756 algorithm name. For unknown algorithms this function returns the 3757 string '"?"'. This function should not be used to test for the 3758 availability of an algorithm. 3759 3760 -- Function: int gcry_mac_map_name (const char *NAME) 3761 3762 Map the algorithm with NAME to a MAC algorithm identifier. Returns 3763 0 if the algorithm name is not known. This function should not be 3764 used to test for the availability of an algorithm. 3765 3766 To test whether an algorithm is actually available for use, the 3767following macro should be used: 3768 3769 -- Function: gcry_error_t gcry_mac_test_algo (int ALGO) 3770 3771 The macro returns 0 if the MAC algorithm ALGO is available for use. 3772 3773 If the length of a message digest is not known, it can be retrieved 3774using the following function: 3775 3776 -- Function: unsigned int gcry_mac_get_algo_maclen (int ALGO) 3777 3778 Retrieve the length in bytes of the MAC yielded by algorithm ALGO. 3779 This is often used prior to 'gcry_mac_read' to allocate sufficient 3780 memory for the MAC value. On error '0' is returned. 3781 3782 -- Function: unsigned int gcry_mac_get_algo_keylen (ALGO) 3783 3784 This function returns length of the key for MAC algorithm ALGO. If 3785 the algorithm supports multiple key lengths, the default supported 3786 key length is returned. On error '0' is returned. The key length 3787 is returned as number of octets. 3788 3789 3790File: gcrypt.info, Node: Key Derivation, Next: Random Numbers, Prev: Message Authentication Codes, Up: Top 3791 37929 Key Derivation 3793**************** 3794 3795Libgcypt provides a general purpose function to derive keys from 3796strings. 3797 3798 -- Function: gpg_error_t gcry_kdf_derive ( const void *PASSPHRASE, 3799 size_t PASSPHRASELEN, int ALGO, int SUBALGO, const void *SALT, 3800 size_t SALTLEN, unsigned long ITERATIONS, size_t KEYSIZE, 3801 void *KEYBUFFER ) 3802 3803 Derive a key from a passphrase. KEYSIZE gives the requested size 3804 of the keys in octets. KEYBUFFER is a caller provided buffer 3805 filled on success with the derived key. The input passphrase is 3806 taken from PASSPHRASE which is an arbitrary memory buffer of 3807 PASSPHRASELEN octets. ALGO specifies the KDF algorithm to use; see 3808 below. SUBALGO specifies an algorithm used internally by the KDF 3809 algorithms; this is usually a hash algorithm but certain KDF 3810 algorithms may use it differently. SALT is a salt of length 3811 SALTLEN octets, as needed by most KDF algorithms. ITERATIONS is a 3812 positive integer parameter to most KDFs. 3813 3814 On success 0 is returned; on failure an error code. 3815 3816 Currently supported KDFs (parameter ALGO): 3817 3818 'GCRY_KDF_SIMPLE_S2K' 3819 The OpenPGP simple S2K algorithm (cf. RFC4880). Its use is 3820 strongly deprecated. SALT and ITERATIONS are not needed and 3821 may be passed as 'NULL'/'0'. 3822 3823 'GCRY_KDF_SALTED_S2K' 3824 The OpenPGP salted S2K algorithm (cf. RFC4880). Usually not 3825 used. ITERATIONS is not needed and may be passed as '0'. 3826 SALTLEN must be given as 8. 3827 3828 'GCRY_KDF_ITERSALTED_S2K' 3829 The OpenPGP iterated+salted S2K algorithm (cf. RFC4880). 3830 This is the default for most OpenPGP applications. SALTLEN 3831 must be given as 8. Note that OpenPGP defines a special 3832 encoding of the ITERATIONS; however this function takes the 3833 plain decoded iteration count. 3834 3835 'GCRY_KDF_PBKDF2' 3836 The PKCS#5 Passphrase Based Key Derivation Function number 2. 3837 3838 'GCRY_KDF_SCRYPT' 3839 The SCRYPT Key Derivation Function. The subalgorithm is used 3840 to specify the CPU/memory cost parameter N, and the number of 3841 iterations is used for the parallelization parameter p. The 3842 block size is fixed at 8 in the current implementation. 3843 3844 3845File: gcrypt.info, Node: Random Numbers, Next: S-expressions, Prev: Key Derivation, Up: Top 3846 384710 Random Numbers 3848***************** 3849 3850* Menu: 3851 3852* Quality of random numbers:: Libgcrypt uses different quality levels. 3853* Retrieving random numbers:: How to retrieve random numbers. 3854 3855 3856File: gcrypt.info, Node: Quality of random numbers, Next: Retrieving random numbers, Up: Random Numbers 3857 385810.1 Quality of random numbers 3859============================== 3860 3861Libgcypt offers random numbers of different quality levels: 3862 3863 -- Data type: gcry_random_level_t 3864 The constants for the random quality levels are of this enum type. 3865 3866'GCRY_WEAK_RANDOM' 3867 For all functions, except for 'gcry_mpi_randomize', this level maps 3868 to GCRY_STRONG_RANDOM. If you do not want this, consider using 3869 'gcry_create_nonce'. 3870'GCRY_STRONG_RANDOM' 3871 Use this level for session keys and similar purposes. 3872'GCRY_VERY_STRONG_RANDOM' 3873 Use this level for long term key material. 3874 3875 3876File: gcrypt.info, Node: Retrieving random numbers, Prev: Quality of random numbers, Up: Random Numbers 3877 387810.2 Retrieving random numbers 3879============================== 3880 3881 -- Function: void gcry_randomize (unsigned char *BUFFER, size_t LENGTH, 3882 enum gcry_random_level LEVEL) 3883 3884 Fill BUFFER with LENGTH random bytes using a random quality as 3885 defined by LEVEL. 3886 3887 -- Function: void * gcry_random_bytes (size_t NBYTES, enum 3888 gcry_random_level LEVEL) 3889 3890 Convenience function to allocate a memory block consisting of 3891 NBYTES fresh random bytes using a random quality as defined by 3892 LEVEL. 3893 3894 -- Function: void * gcry_random_bytes_secure (size_t NBYTES, enum 3895 gcry_random_level LEVEL) 3896 3897 Convenience function to allocate a memory block consisting of 3898 NBYTES fresh random bytes using a random quality as defined by 3899 LEVEL. This function differs from 'gcry_random_bytes' in that the 3900 returned buffer is allocated in a "secure" area of the memory. 3901 3902 -- Function: void gcry_create_nonce (unsigned char *BUFFER, size_t 3903 LENGTH) 3904 3905 Fill BUFFER with LENGTH unpredictable bytes. This is commonly 3906 called a nonce and may also be used for initialization vectors and 3907 padding. This is an extra function nearly independent of the other 3908 random function for 3 reasons: It better protects the regular 3909 random generator's internal state, provides better performance and 3910 does not drain the precious entropy pool. 3911 3912 3913File: gcrypt.info, Node: S-expressions, Next: MPI library, Prev: Random Numbers, Up: Top 3914 391511 S-expressions 3916**************** 3917 3918S-expressions are used by the public key functions to pass complex data 3919structures around. These LISP like objects are used by some 3920cryptographic protocols (cf. RFC-2692) and Libgcrypt provides functions 3921to parse and construct them. For detailed information, see 'Ron Rivest, 3922code and description of S-expressions, 3923<http://theory.lcs.mit.edu/~rivest/sexp.html>'. 3924 3925* Menu: 3926 3927* Data types for S-expressions:: Data types related with S-expressions. 3928* Working with S-expressions:: How to work with S-expressions. 3929 3930 3931File: gcrypt.info, Node: Data types for S-expressions, Next: Working with S-expressions, Up: S-expressions 3932 393311.1 Data types for S-expressions 3934================================= 3935 3936 -- Data type: gcry_sexp_t 3937 The 'gcry_sexp_t' type describes an object with the Libgcrypt 3938 internal representation of an S-expression. 3939 3940 3941File: gcrypt.info, Node: Working with S-expressions, Prev: Data types for S-expressions, Up: S-expressions 3942 394311.2 Working with S-expressions 3944=============================== 3945 3946There are several functions to create an Libgcrypt S-expression object 3947from its external representation or from a string template. There is 3948also a function to convert the internal representation back into one of 3949the external formats: 3950 3951 -- Function: gcry_error_t gcry_sexp_new (gcry_sexp_t *R_SEXP, 3952 const void *BUFFER, size_t LENGTH, int AUTODETECT) 3953 3954 This is the generic function to create an new S-expression object 3955 from its external representation in BUFFER of LENGTH bytes. On 3956 success the result is stored at the address given by R_SEXP. With 3957 AUTODETECT set to 0, the data in BUFFER is expected to be in 3958 canonized format, with AUTODETECT set to 1 the parses any of the 3959 defined external formats. If BUFFER does not hold a valid 3960 S-expression an error code is returned and R_SEXP set to 'NULL'. 3961 Note that the caller is responsible for releasing the newly 3962 allocated S-expression using 'gcry_sexp_release'. 3963 3964 -- Function: gcry_error_t gcry_sexp_create (gcry_sexp_t *R_SEXP, 3965 void *BUFFER, size_t LENGTH, int AUTODETECT, 3966 void (*FREEFNC)(void*)) 3967 3968 This function is identical to 'gcry_sexp_new' but has an extra 3969 argument FREEFNC, which, when not set to 'NULL', is expected to be 3970 a function to release the BUFFER; most likely the standard 'free' 3971 function is used for this argument. This has the effect of 3972 transferring the ownership of BUFFER to the created object in 3973 R_SEXP. The advantage of using this function is that Libgcrypt 3974 might decide to directly use the provided buffer and thus avoid 3975 extra copying. 3976 3977 -- Function: gcry_error_t gcry_sexp_sscan (gcry_sexp_t *R_SEXP, 3978 size_t *ERROFF, const char *BUFFER, size_t LENGTH) 3979 3980 This is another variant of the above functions. It behaves nearly 3981 identical but provides an ERROFF argument which will receive the 3982 offset into the buffer where the parsing stopped on error. 3983 3984 -- Function: gcry_error_t gcry_sexp_build (gcry_sexp_t *R_SEXP, 3985 size_t *ERROFF, const char *FORMAT, ...) 3986 3987 This function creates an internal S-expression from the string 3988 template FORMAT and stores it at the address of R_SEXP. If there 3989 is a parsing error, the function returns an appropriate error code 3990 and stores the offset into FORMAT where the parsing stopped in 3991 ERROFF. The function supports a couple of printf-like formatting 3992 characters and expects arguments for some of these escape sequences 3993 right after FORMAT. The following format characters are defined: 3994 3995 '%m' 3996 The next argument is expected to be of type 'gcry_mpi_t' and a 3997 copy of its value is inserted into the resulting S-expression. 3998 The MPI is stored as a signed integer. 3999 '%M' 4000 The next argument is expected to be of type 'gcry_mpi_t' and a 4001 copy of its value is inserted into the resulting S-expression. 4002 The MPI is stored as an unsigned integer. 4003 '%s' 4004 The next argument is expected to be of type 'char *' and that 4005 string is inserted into the resulting S-expression. 4006 '%d' 4007 The next argument is expected to be of type 'int' and its 4008 value is inserted into the resulting S-expression. 4009 '%u' 4010 The next argument is expected to be of type 'unsigned int' and 4011 its value is inserted into the resulting S-expression. 4012 '%b' 4013 The next argument is expected to be of type 'int' directly 4014 followed by an argument of type 'char *'. This represents a 4015 buffer of given length to be inserted into the resulting 4016 S-expression. 4017 '%S' 4018 The next argument is expected to be of type 'gcry_sexp_t' and 4019 a copy of that S-expression is embedded in the resulting 4020 S-expression. The argument needs to be a regular 4021 S-expression, starting with a parenthesis. 4022 4023 No other format characters are defined and would return an error. 4024 Note that the format character '%%' does not exists, because a 4025 percent sign is not a valid character in an S-expression. 4026 4027 -- Function: void gcry_sexp_release (gcry_sexp_t SEXP) 4028 4029 Release the S-expression object SEXP. If the S-expression is 4030 stored in secure memory it explicitly zeroises that memory; note 4031 that this is done in addition to the zeroisation always done when 4032 freeing secure memory. 4033 4034The next 2 functions are used to convert the internal representation 4035back into a regular external S-expression format and to show the 4036structure for debugging. 4037 4038 -- Function: size_t gcry_sexp_sprint (gcry_sexp_t SEXP, int MODE, 4039 char *BUFFER, size_t MAXLENGTH) 4040 4041 Copies the S-expression object SEXP into BUFFER using the format 4042 specified in MODE. MAXLENGTH must be set to the allocated length 4043 of BUFFER. The function returns the actual length of valid bytes 4044 put into BUFFER or 0 if the provided buffer is too short. Passing 4045 'NULL' for BUFFER returns the required length for BUFFER. For 4046 convenience reasons an extra byte with value 0 is appended to the 4047 buffer. 4048 4049 The following formats are supported: 4050 4051 'GCRYSEXP_FMT_DEFAULT' 4052 Returns a convenient external S-expression representation. 4053 4054 'GCRYSEXP_FMT_CANON' 4055 Return the S-expression in canonical format. 4056 4057 'GCRYSEXP_FMT_BASE64' 4058 Not currently supported. 4059 4060 'GCRYSEXP_FMT_ADVANCED' 4061 Returns the S-expression in advanced format. 4062 4063 -- Function: void gcry_sexp_dump (gcry_sexp_t SEXP) 4064 4065 Dumps SEXP in a format suitable for debugging to Libgcrypt's 4066 logging stream. 4067 4068Often canonical encoding is used in the external representation. The 4069following function can be used to check for valid encoding and to learn 4070the length of the S-expression. 4071 4072 -- Function: size_t gcry_sexp_canon_len (const unsigned char *BUFFER, 4073 size_t LENGTH, size_t *ERROFF, int *ERRCODE) 4074 4075 Scan the canonical encoded BUFFER with implicit length values and 4076 return the actual length this S-expression uses. For a valid 4077 S-expression it should never return 0. If LENGTH is not 0, the 4078 maximum length to scan is given; this can be used for syntax checks 4079 of data passed from outside. ERRCODE and ERROFF may both be passed 4080 as 'NULL'. 4081 4082There are functions to parse S-expressions and retrieve elements: 4083 4084 -- Function: gcry_sexp_t gcry_sexp_find_token (const gcry_sexp_t LIST, 4085 const char *TOKEN, size_t TOKLEN) 4086 4087 Scan the S-expression for a sublist with a type (the car of the 4088 list) matching the string TOKEN. If TOKLEN is not 0, the token is 4089 assumed to be raw memory of this length. The function returns a 4090 newly allocated S-expression consisting of the found sublist or 4091 'NULL' when not found. 4092 4093 -- Function: int gcry_sexp_length (const gcry_sexp_t LIST) 4094 4095 Return the length of the LIST. For a valid S-expression this 4096 should be at least 1. 4097 4098 -- Function: gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t LIST, 4099 int NUMBER) 4100 4101 Create and return a new S-expression from the element with index 4102 NUMBER in LIST. Note that the first element has the index 0. If 4103 there is no such element, 'NULL' is returned. 4104 4105 -- Function: gcry_sexp_t gcry_sexp_car (const gcry_sexp_t LIST) 4106 4107 Create and return a new S-expression from the first element in 4108 LIST; this is called the "type" and should always exist per 4109 S-expression specification and in general be a string. 'NULL' is 4110 returned in case of a problem. 4111 4112 -- Function: gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t LIST) 4113 4114 Create and return a new list form all elements except for the first 4115 one. Note that this function may return an invalid S-expression 4116 because it is not guaranteed, that the type exists and is a string. 4117 However, for parsing a complex S-expression it might be useful for 4118 intermediate lists. Returns 'NULL' on error. 4119 4120 -- Function: const char * gcry_sexp_nth_data (const gcry_sexp_t LIST, 4121 int NUMBER, size_t *DATALEN) 4122 4123 This function is used to get data from a LIST. A pointer to the 4124 actual data with index NUMBER is returned and the length of this 4125 data will be stored to DATALEN. If there is no data at the given 4126 index or the index represents another list, 'NULL' is returned. 4127 *Caution:* The returned pointer is valid as long as LIST is not 4128 modified or released. 4129 4130 Here is an example on how to extract and print the surname (Meier) 4131 from the S-expression '(Name Otto Meier (address Burgplatz 3))': 4132 4133 size_t len; 4134 const char *name; 4135 4136 name = gcry_sexp_nth_data (list, 2, &len); 4137 printf ("my name is %.*s\n", (int)len, name); 4138 4139 -- Function: void * gcry_sexp_nth_buffer (const gcry_sexp_t LIST, 4140 int NUMBER, size_t *RLENGTH) 4141 4142 This function is used to get data from a LIST. A malloced buffer 4143 with the actual data at list index NUMBER is returned and the 4144 length of this buffer will be stored to RLENGTH. If there is no 4145 data at the given index or the index represents another list, 4146 'NULL' is returned. The caller must release the result using 4147 'gcry_free'. 4148 4149 Here is an example on how to extract and print the CRC value from 4150 the S-expression '(hash crc32 #23ed00d7)': 4151 4152 size_t len; 4153 char *value; 4154 4155 value = gcry_sexp_nth_buffer (list, 2, &len); 4156 if (value) 4157 fwrite (value, len, 1, stdout); 4158 gcry_free (value); 4159 4160 -- Function: char * gcry_sexp_nth_string (gcry_sexp_t LIST, int NUMBER) 4161 4162 This function is used to get and convert data from a LIST. The 4163 data is assumed to be a Nul terminated string. The caller must 4164 release this returned value using 'gcry_free'. If there is no data 4165 at the given index, the index represents a list or the value can't 4166 be converted to a string, 'NULL' is returned. 4167 4168 -- Function: gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t LIST, 4169 int NUMBER, int MPIFMT) 4170 4171 This function is used to get and convert data from a LIST. This 4172 data is assumed to be an MPI stored in the format described by 4173 MPIFMT and returned as a standard Libgcrypt MPI. The caller must 4174 release this returned value using 'gcry_mpi_release'. If there is 4175 no data at the given index, the index represents a list or the 4176 value can't be converted to an MPI, 'NULL' is returned. If you use 4177 this function to parse results of a public key function, you most 4178 likely want to use 'GCRYMPI_FMT_USG'. 4179 4180 -- Function: gpg_error_t gcry_sexp_extract_param ( gcry_sexp_t SEXP, 4181 const char *PATH, const char *LIST, ...) 4182 4183 Extract parameters from an S-expression using a list of parameter 4184 names. The names of these parameters are specified in LIST. White 4185 space between the parameter names are ignored. Some special 4186 characters and character sequences may be given to control the 4187 conversion: 4188 4189 '+' 4190 Switch to unsigned integer format (GCRYMPI_FMT_USG). This is 4191 the default mode. 4192 '-' 4193 Switch to standard signed format (GCRYMPI_FMT_STD). 4194 '/' 4195 Switch to opaque MPI format. The resulting MPIs may not be 4196 used for computations; see 'gcry_mpi_get_opaque' for details. 4197 '&' 4198 Switch to buffer descriptor mode. See below for details. 4199 '%s' 4200 Switch to string mode. The expected argument is the address 4201 of a 'char *' variable; the caller must release that value. 4202 If the parameter was marked optional and is not found, NULL is 4203 stored. 4204 '%#s' 4205 Switch to multi string mode. The expected argument is the 4206 address of a 'char *' variable; the caller must release that 4207 value. If the parameter was marked optional and is not found, 4208 NULL is stored. A multi string takes all values, assumes they 4209 are strings and concatenates them using a space as delimiter. 4210 In case a value is actually another list this is not further 4211 parsed but a '()' is inserted in place of that sublist. 4212 '%u' 4213 Switch to unsigned integer mode. The expected argument is 4214 address of a 'unsigned int' variable. 4215 '%lu' 4216 Switch to unsigned long integer mode. The expected argument 4217 is address of a 'unsigned long' variable. 4218 '%d' 4219 Switch to signed integer mode. The expected argument is 4220 address of a 'int' variable. 4221 '%ld' 4222 Switch to signed long integer mode. The expected argument is 4223 address of a 'long' variable. 4224 '%zu' 4225 Switch to size_t mode. The expected argument is address of a 4226 'size_t' variable. 4227 '?' 4228 If immediately following a parameter letter (no white space 4229 allowed), that parameter is considered optional. 4230 4231 In general parameter names are single letters. To use a string for 4232 a parameter name, enclose the name in single quotes. 4233 4234 Unless in buffer descriptor mode for each parameter name a pointer 4235 to an 'gcry_mpi_t' variable is expected that must be set to 'NULL' 4236 prior to invoking this function, and finally a 'NULL' is expected. 4237 For example 4238 4239 gcry_sexp_extract_param (key, NULL, "n/x+e d-'foo'", 4240 &mpi_n, &mpi_x, &mpi_e, &mpi_d, &mpi_foo, NULL) 4241 4242 stores the parameter 'n' from KEY as an unsigned MPI into MPI_N, 4243 the parameter 'x' as an opaque MPI into MPI_X, the parameters 'e' 4244 and 'd' again as an unsigned MPI into MPI_E and MPI_D and finally 4245 the parameter 'foo' as a signed MPI into MPI_FOO. 4246 4247 PATH is an optional string used to locate a token. The exclamation 4248 mark separated tokens are used via 'gcry_sexp_find_token' to find a 4249 start point inside the S-expression. 4250 4251 In buffer descriptor mode a pointer to a 'gcry_buffer_t' descriptor 4252 is expected instead of a pointer to an MPI. The caller may use two 4253 different operation modes here: If the DATA field of the provided 4254 descriptor is 'NULL', the function allocates a new buffer and 4255 stores it at DATA; the other fields are set accordingly with OFF 4256 set to 0. If DATA is not 'NULL', the function assumes that the 4257 DATA, SIZE, and OFF fields specify a buffer where to but the value 4258 of the respective parameter; on return the LEN field receives the 4259 number of bytes copied to that buffer; in case the buffer is too 4260 small, the function immediately returns with an error code (and LEN 4261 is set to 0). 4262 4263 The function returns 0 on success. On error an error code is 4264 returned, all passed MPIs that might have been allocated up to this 4265 point are deallocated and set to 'NULL', and all passed buffers are 4266 either truncated if the caller supplied the buffer, or deallocated 4267 if the function allocated the buffer. 4268 4269 4270File: gcrypt.info, Node: MPI library, Next: Prime numbers, Prev: S-expressions, Up: Top 4271 427212 MPI library 4273************** 4274 4275* Menu: 4276 4277* Data types:: MPI related data types. 4278* Basic functions:: First steps with MPI numbers. 4279* MPI formats:: External representation of MPIs. 4280* Calculations:: Performing MPI calculations. 4281* Comparisons:: How to compare MPI values. 4282* Bit manipulations:: How to access single bits of MPI values. 4283* EC functions:: Elliptic curve related functions. 4284* Miscellaneous:: Miscellaneous MPI functions. 4285 4286Public key cryptography is based on mathematics with large numbers. To 4287implement the public key functions, a library for handling these large 4288numbers is required. Because of the general usefulness of such a 4289library, its interface is exposed by Libgcrypt. In the context of 4290Libgcrypt and in most other applications, these large numbers are called 4291MPIs (multi-precision-integers). 4292 4293 4294File: gcrypt.info, Node: Data types, Next: Basic functions, Up: MPI library 4295 429612.1 Data types 4297=============== 4298 4299 -- Data type: gcry_mpi_t 4300 This type represents an object to hold an MPI. 4301 4302 -- Data type: gcry_mpi_point_t 4303 This type represents an object to hold a point for elliptic curve 4304 math. 4305 4306 4307File: gcrypt.info, Node: Basic functions, Next: MPI formats, Prev: Data types, Up: MPI library 4308 430912.2 Basic functions 4310==================== 4311 4312To work with MPIs, storage must be allocated and released for the 4313numbers. This can be done with one of these functions: 4314 4315 -- Function: gcry_mpi_t gcry_mpi_new (unsigned int NBITS) 4316 4317 Allocate a new MPI object, initialize it to 0 and initially 4318 allocate enough memory for a number of at least NBITS. This 4319 pre-allocation is only a small performance issue and not actually 4320 necessary because Libgcrypt automatically re-allocates the required 4321 memory. 4322 4323 -- Function: gcry_mpi_t gcry_mpi_snew (unsigned int NBITS) 4324 4325 This is identical to 'gcry_mpi_new' but allocates the MPI in the so 4326 called "secure memory" which in turn will take care that all 4327 derived values will also be stored in this "secure memory". Use 4328 this for highly confidential data like private key parameters. 4329 4330 -- Function: gcry_mpi_t gcry_mpi_copy (const gcry_mpi_t A) 4331 4332 Create a new MPI as the exact copy of A but with the constant and 4333 immutable flags cleared. 4334 4335 -- Function: void gcry_mpi_release (gcry_mpi_t A) 4336 4337 Release the MPI A and free all associated resources. Passing 4338 'NULL' is allowed and ignored. When a MPI stored in the "secure 4339 memory" is released, that memory gets wiped out immediately. 4340 4341The simplest operations are used to assign a new value to an MPI: 4342 4343 -- Function: gcry_mpi_t gcry_mpi_set (gcry_mpi_t W, const gcry_mpi_t U) 4344 4345 Assign the value of U to W and return W. If 'NULL' is passed for 4346 W, a new MPI is allocated, set to the value of U and returned. 4347 4348 -- Function: gcry_mpi_t gcry_mpi_set_ui (gcry_mpi_t W, unsigned long U) 4349 4350 Assign the value of U to W and return W. If 'NULL' is passed for 4351 W, a new MPI is allocated, set to the value of U and returned. 4352 This function takes an 'unsigned int' as type for U and thus it is 4353 only possible to set W to small values (usually up to the word size 4354 of the CPU). 4355 4356 -- Function: gcry_error_t gcry_mpi_get_ui (unsigned int *W, 4357 gcry_mpi_t U) 4358 4359 If U is not negative and small enough to be stored in an 'unsigned 4360 int' variable, store its value at W. If the value does not fit or 4361 is negative return GPG_ERR_ERANGE and do not change the value 4362 stored at W. Note that this function returns an 'unsigned int' so 4363 that this value can immediately be used with the bit test 4364 functions. This is in contrast to the other "_ui" functions which 4365 allow for values up to an 'unsigned long'. 4366 4367 -- Function: void gcry_mpi_swap (gcry_mpi_t A, gcry_mpi_t B) 4368 4369 Swap the values of A and B. 4370 4371 -- Function: void gcry_mpi_snatch (gcry_mpi_t W, const gcry_mpi_t U) 4372 4373 Set U into W and release U. If W is 'NULL' only U will be 4374 released. 4375 4376 -- Function: void gcry_mpi_neg (gcry_mpi_t W, gcry_mpi_t U) 4377 4378 Set the sign of W to the negative of U. 4379 4380 -- Function: void gcry_mpi_abs (gcry_mpi_t W) 4381 4382 Clear the sign of W. 4383 4384 4385File: gcrypt.info, Node: MPI formats, Next: Calculations, Prev: Basic functions, Up: MPI library 4386 438712.3 MPI formats 4388================ 4389 4390The following functions are used to convert between an external 4391representation of an MPI and the internal one of Libgcrypt. 4392 4393 -- Function: gcry_error_t gcry_mpi_scan (gcry_mpi_t *R_MPI, 4394 enum gcry_mpi_format FORMAT, const unsigned char *BUFFER, 4395 size_t BUFLEN, size_t *NSCANNED) 4396 4397 Convert the external representation of an integer stored in BUFFER 4398 with a length of BUFLEN into a newly created MPI returned which 4399 will be stored at the address of R_MPI. For certain formats the 4400 length argument is not required and should be passed as '0'. A 4401 BUFLEN larger than 16 MiByte will be rejected. After a successful 4402 operation the variable NSCANNED receives the number of bytes 4403 actually scanned unless NSCANNED was given as 'NULL'. FORMAT 4404 describes the format of the MPI as stored in BUFFER: 4405 4406 'GCRYMPI_FMT_STD' 4407 2-complement stored without a length header. Note that 4408 'gcry_mpi_print' stores a '0' as a string of zero length. 4409 4410 'GCRYMPI_FMT_PGP' 4411 As used by OpenPGP (only defined as unsigned). This is 4412 basically 'GCRYMPI_FMT_STD' with a 2 byte big endian length 4413 header. A length header indicating a length of more than 4414 16384 is not allowed. 4415 4416 'GCRYMPI_FMT_SSH' 4417 As used in the Secure Shell protocol. This is 4418 'GCRYMPI_FMT_STD' with a 4 byte big endian header. 4419 4420 'GCRYMPI_FMT_HEX' 4421 Stored as a string with each byte of the MPI encoded as 2 hex 4422 digits. Negative numbers are prefix with a minus sign and in 4423 addition the high bit is always zero to make clear that an 4424 explicit sign ist used. When using this format, BUFLEN must 4425 be zero. 4426 4427 'GCRYMPI_FMT_USG' 4428 Simple unsigned integer. 4429 4430 Note that all of the above formats store the integer in big-endian 4431 format (MSB first). 4432 4433 -- Function: gcry_error_t gcry_mpi_print (enum gcry_mpi_format FORMAT, 4434 unsigned char *BUFFER, size_t BUFLEN, size_t *NWRITTEN, 4435 const gcry_mpi_t A) 4436 4437 Convert the MPI A into an external representation described by 4438 FORMAT (see above) and store it in the provided BUFFER which has a 4439 usable length of at least the BUFLEN bytes. If NWRITTEN is not 4440 NULL, it will receive the number of bytes actually stored in BUFFER 4441 after a successful operation. 4442 4443 -- Function: gcry_error_t gcry_mpi_aprint (enum gcry_mpi_format FORMAT, 4444 unsigned char **BUFFER, size_t *NBYTES, const gcry_mpi_t A) 4445 4446 Convert the MPI A into an external representation described by 4447 FORMAT (see above) and store it in a newly allocated buffer which 4448 address will be stored in the variable BUFFER points to. The 4449 number of bytes stored in this buffer will be stored in the 4450 variable NBYTES points to, unless NBYTES is 'NULL'. 4451 4452 Even if NBYTES is zero, the function allocates at least one byte 4453 and store a zero there. Thus with formats 'GCRYMPI_FMT_STD' and 4454 'GCRYMPI_FMT_USG' the caller may safely set a returned length of 0 4455 to 1 to represent a zero as a 1 byte string. 4456 4457 -- Function: void gcry_mpi_dump (const gcry_mpi_t A) 4458 4459 Dump the value of A in a format suitable for debugging to 4460 Libgcrypt's logging stream. Note that one leading space but no 4461 trailing space or linefeed will be printed. It is okay to pass 4462 'NULL' for A. 4463 4464 4465File: gcrypt.info, Node: Calculations, Next: Comparisons, Prev: MPI formats, Up: MPI library 4466 446712.4 Calculations 4468================= 4469 4470Basic arithmetic operations: 4471 4472 -- Function: void gcry_mpi_add (gcry_mpi_t W, gcry_mpi_t U, 4473 gcry_mpi_t V) 4474 4475 W = U + V. 4476 4477 -- Function: void gcry_mpi_add_ui (gcry_mpi_t W, gcry_mpi_t U, 4478 unsigned long V) 4479 4480 W = U + V. Note that V is an unsigned integer. 4481 4482 -- Function: void gcry_mpi_addm (gcry_mpi_t W, gcry_mpi_t U, 4483 gcry_mpi_t V, gcry_mpi_t M) 4484 4485 W = U + V \bmod M. 4486 4487 -- Function: void gcry_mpi_sub (gcry_mpi_t W, gcry_mpi_t U, 4488 gcry_mpi_t V) 4489 4490 W = U - V. 4491 4492 -- Function: void gcry_mpi_sub_ui (gcry_mpi_t W, gcry_mpi_t U, 4493 unsigned long V) 4494 4495 W = U - V. V is an unsigned integer. 4496 4497 -- Function: void gcry_mpi_subm (gcry_mpi_t W, gcry_mpi_t U, 4498 gcry_mpi_t V, gcry_mpi_t M) 4499 4500 W = U - V \bmod M. 4501 4502 -- Function: void gcry_mpi_mul (gcry_mpi_t W, gcry_mpi_t U, 4503 gcry_mpi_t V) 4504 4505 W = U * V. 4506 4507 -- Function: void gcry_mpi_mul_ui (gcry_mpi_t W, gcry_mpi_t U, 4508 unsigned long V) 4509 4510 W = U * V. V is an unsigned integer. 4511 4512 -- Function: void gcry_mpi_mulm (gcry_mpi_t W, gcry_mpi_t U, 4513 gcry_mpi_t V, gcry_mpi_t M) 4514 4515 W = U * V \bmod M. 4516 4517 -- Function: void gcry_mpi_mul_2exp (gcry_mpi_t W, gcry_mpi_t U, 4518 unsigned long E) 4519 4520 W = U * 2^e. 4521 4522 -- Function: void gcry_mpi_div (gcry_mpi_t Q, gcry_mpi_t R, 4523 gcry_mpi_t DIVIDEND, gcry_mpi_t DIVISOR, int ROUND) 4524 4525 Q = DIVIDEND / DIVISOR, R = DIVIDEND \bmod DIVISOR. Q and R may be 4526 passed as 'NULL'. ROUND is either negative for floored division 4527 (rounds towards the next lower integer) or zero for truncated 4528 division (rounds towards zero). 4529 4530 -- Function: void gcry_mpi_mod (gcry_mpi_t R, gcry_mpi_t DIVIDEND, 4531 gcry_mpi_t DIVISOR) 4532 4533 R = DIVIDEND \bmod DIVISOR. 4534 4535 -- Function: void gcry_mpi_powm (gcry_mpi_t W, const gcry_mpi_t B, 4536 const gcry_mpi_t E, const gcry_mpi_t M) 4537 4538 W = B^e \bmod M. 4539 4540 -- Function: int gcry_mpi_gcd (gcry_mpi_t G, gcry_mpi_t A, 4541 gcry_mpi_t B) 4542 4543 Set G to the greatest common divisor of A and B. Return true if 4544 the G is 1. 4545 4546 -- Function: int gcry_mpi_invm (gcry_mpi_t X, gcry_mpi_t A, 4547 gcry_mpi_t M) 4548 4549 Set X to the multiplicative inverse of A \bmod M. Return true if 4550 the inverse exists. 4551 4552 4553File: gcrypt.info, Node: Comparisons, Next: Bit manipulations, Prev: Calculations, Up: MPI library 4554 455512.5 Comparisons 4556================ 4557 4558The next 2 functions are used to compare MPIs: 4559 4560 -- Function: int gcry_mpi_cmp (const gcry_mpi_t U, const gcry_mpi_t V) 4561 4562 Compare the multi-precision-integers number U and V returning 0 for 4563 equality, a positive value for U > V and a negative for U < V. If 4564 both numbers are opaque values (cf, gcry_mpi_set_opaque) the 4565 comparison is done by checking the bit sizes using memcmp. If only 4566 one number is an opaque value, the opaque value is less than the 4567 other number. 4568 4569 -- Function: int gcry_mpi_cmp_ui (const gcry_mpi_t U, unsigned long V) 4570 4571 Compare the multi-precision-integers number U with the unsigned 4572 integer V returning 0 for equality, a positive value for U > V and 4573 a negative for U < V. 4574 4575 -- Function: int gcry_mpi_is_neg (const gcry_mpi_t A) 4576 4577 Return 1 if A is less than zero; return 0 if zero or positive. 4578 4579 4580File: gcrypt.info, Node: Bit manipulations, Next: EC functions, Prev: Comparisons, Up: MPI library 4581 458212.6 Bit manipulations 4583====================== 4584 4585There are a couple of functions to get information on arbitrary bits in 4586an MPI and to set or clear them: 4587 4588 -- Function: unsigned int gcry_mpi_get_nbits (gcry_mpi_t A) 4589 4590 Return the number of bits required to represent A. 4591 4592 -- Function: int gcry_mpi_test_bit (gcry_mpi_t A, unsigned int N) 4593 4594 Return true if bit number N (counting from 0) is set in A. 4595 4596 -- Function: void gcry_mpi_set_bit (gcry_mpi_t A, unsigned int N) 4597 4598 Set bit number N in A. 4599 4600 -- Function: void gcry_mpi_clear_bit (gcry_mpi_t A, unsigned int N) 4601 4602 Clear bit number N in A. 4603 4604 -- Function: void gcry_mpi_set_highbit (gcry_mpi_t A, unsigned int N) 4605 4606 Set bit number N in A and clear all bits greater than N. 4607 4608 -- Function: void gcry_mpi_clear_highbit (gcry_mpi_t A, unsigned int N) 4609 4610 Clear bit number N in A and all bits greater than N. 4611 4612 -- Function: void gcry_mpi_rshift (gcry_mpi_t X, gcry_mpi_t A, 4613 unsigned int N) 4614 4615 Shift the value of A by N bits to the right and store the result in 4616 X. 4617 4618 -- Function: void gcry_mpi_lshift (gcry_mpi_t X, gcry_mpi_t A, 4619 unsigned int N) 4620 4621 Shift the value of A by N bits to the left and store the result in 4622 X. 4623 4624 4625File: gcrypt.info, Node: EC functions, Next: Miscellaneous, Prev: Bit manipulations, Up: MPI library 4626 462712.7 EC functions 4628================= 4629 4630Libgcrypt provides an API to access low level functions used by its 4631elliptic curve implementation. These functions allow to implement 4632elliptic curve methods for which no explicit support is available. 4633 4634 -- Function: gcry_mpi_point_t gcry_mpi_point_new (unsigned int NBITS) 4635 4636 Allocate a new point object, initialize it to 0, and allocate 4637 enough memory for a points of at least NBITS. This pre-allocation 4638 yields only a small performance win and is not really necessary 4639 because Libgcrypt automatically re-allocates the required memory. 4640 Using 0 for NBITS is usually the right thing to do. 4641 4642 -- Function: void gcry_mpi_point_release (gcry_mpi_point_t POINT) 4643 4644 Release POINT and free all associated resources. Passing 'NULL' is 4645 allowed and ignored. 4646 4647 -- Function: gcry_mpi_point_t gcry_mpi_point_copy 4648 (gcry_mpi_point_t POINT) 4649 4650 Allocate and return a new point object and initialize it with 4651 POINT. If POINT is NULL the function is identical to 4652 'gcry_mpi_point_new(0)'. 4653 4654 -- Function: void gcry_mpi_point_get (gcry_mpi_t X, gcry_mpi_t Y, 4655 gcry_mpi_t Z, gcry_mpi_point_t POINT) 4656 4657 Store the projective coordinates from POINT into the MPIs X, Y, and 4658 Z. If a coordinate is not required, 'NULL' may be used for X, Y, 4659 or Z. 4660 4661 -- Function: void gcry_mpi_point_snatch_get (gcry_mpi_t X, 4662 gcry_mpi_t Y, gcry_mpi_t Z, gcry_mpi_point_t POINT) 4663 4664 Store the projective coordinates from POINT into the MPIs X, Y, and 4665 Z. If a coordinate is not required, 'NULL' may be used for X, Y, 4666 or Z. The object POINT is then released. Using this function 4667 instead of 'gcry_mpi_point_get' and 'gcry_mpi_point_release' has 4668 the advantage of avoiding some extra memory allocations and copies. 4669 4670 -- Function: gcry_mpi_point_t gcry_mpi_point_set ( 4671 gcry_mpi_point_t POINT, gcry_mpi_t X, gcry_mpi_t Y, 4672 gcry_mpi_t Z) 4673 4674 Store the projective coordinates from X, Y, and Z into POINT. If a 4675 coordinate is given as 'NULL', the value 0 is used. If 'NULL' is 4676 used for POINT a new point object is allocated and returned. 4677 Returns POINT or the newly allocated point object. 4678 4679 -- Function: gcry_mpi_point_t gcry_mpi_point_snatch_set ( 4680 gcry_mpi_point_t POINT, gcry_mpi_t X, gcry_mpi_t Y, 4681 gcry_mpi_t Z) 4682 4683 Store the projective coordinates from X, Y, and Z into POINT. If a 4684 coordinate is given as 'NULL', the value 0 is used. If 'NULL' is 4685 used for POINT a new point object is allocated and returned. The 4686 MPIs X, Y, and Z are released. Using this function instead of 4687 'gcry_mpi_point_set' and 3 calls to 'gcry_mpi_release' has the 4688 advantage of avoiding some extra memory allocations and copies. 4689 Returns POINT or the newly allocated point object. 4690 4691 -- Function: gpg_error_t gcry_mpi_ec_new (gcry_ctx_t *R_CTX, 4692 gcry_sexp_t KEYPARAM, const char *CURVENAME) 4693 4694 Allocate a new context for elliptic curve operations. If KEYPARAM 4695 is given it specifies the parameters of the curve (*note 4696 ecc_keyparam::). If CURVENAME is given in addition to KEYPARAM and 4697 the key parameters do not include a named curve reference, the 4698 string CURVENAME is used to fill in missing parameters. If only 4699 CURVENAME is given, the context is initialized for this named 4700 curve. 4701 4702 If a parameter specifying a point (e.g. 'g' or 'q') is not found, 4703 the parser looks for a non-encoded point by appending '.x', '.y', 4704 and '.z' to the parameter name and looking them all up to create a 4705 point. A parameter with the suffix '.z' is optional and defaults 4706 to 1. 4707 4708 On success the function returns 0 and stores the new context object 4709 at R_CTX; this object eventually needs to be released (*note 4710 gcry_ctx_release::). On error the function stores 'NULL' at R_CTX 4711 and returns an error code. 4712 4713 -- Function: gcry_mpi_t gcry_mpi_ec_get_mpi ( const char *NAME, 4714 gcry_ctx_t CTX, int COPY) 4715 4716 Return the MPI with NAME from the context CTX. If not found 'NULL' 4717 is returned. If the returned MPI may later be modified, it is 4718 suggested to pass '1' to COPY, so that the function guarantees that 4719 a modifiable copy of the MPI is returned. If '0' is used for COPY, 4720 this function may return a constant flagged MPI. In any case 4721 'gcry_mpi_release' needs to be called to release the result. For 4722 valid names *note ecc_keyparam::. If the public key 'q' is 4723 requested but only the private key 'd' is available, 'q' will be 4724 recomputed on the fly. If a point parameter is requested it is 4725 returned as an uncompressed encoded point unless these special 4726 names are used: 4727 Q@EDDSA 4728 Return an EdDSA style compressed point. This is only 4729 supported for Twisted Edwards curves. 4730 4731 -- Function: gcry_mpi_point_t gcry_mpi_ec_get_point ( const char *NAME, 4732 gcry_ctx_t CTX, int COPY) 4733 4734 Return the point with NAME from the context CTX. If not found 4735 'NULL' is returned. If the returned MPI may later be modified, it 4736 is suggested to pass '1' to COPY, so that the function guarantees 4737 that a modifiable copy of the MPI is returned. If '0' is used for 4738 COPY, this function may return a constant flagged point. In any 4739 case 'gcry_mpi_point_release' needs to be called to release the 4740 result. If the public key 'q' is requested but only the private 4741 key 'd' is available, 'q' will be recomputed on the fly. 4742 4743 -- Function: gpg_error_t gcry_mpi_ec_set_mpi ( const char *NAME, 4744 gcry_mpi_t NEWVALUE, gcry_ctx_t CTX) 4745 4746 Store the MPI NEWVALUE at NAME into the context CTX. On success 4747 '0' is returned; on error an error code. Valid names are the MPI 4748 parameters of an elliptic curve (*note ecc_keyparam::). 4749 4750 -- Function: gpg_error_t gcry_mpi_ec_set_point ( const char *NAME, 4751 gcry_mpi_point_t NEWVALUE, gcry_ctx_t CTX) 4752 4753 Store the point NEWVALUE at NAME into the context CTX. On success 4754 '0' is returned; on error an error code. Valid names are the point 4755 parameters of an elliptic curve (*note ecc_keyparam::). 4756 4757 -- Function: gpg_err_code_t gcry_mpi_ec_decode_point ( 4758 mpi_point_t RESULT, gcry_mpi_t VALUE, gcry_ctx_t CTX) 4759 4760 Decode the point given as an MPI in VALUE and store at RESULT. To 4761 decide which encoding is used the function takes a context CTX 4762 which can be created with 'gcry_mpi_ec_new'. If 'NULL' is given 4763 for the context the function assumes a 0x04 prefixed uncompressed 4764 encoding. On error an error code is returned and RESULT might be 4765 changed. 4766 4767 -- Function: int gcry_mpi_ec_get_affine ( gcry_mpi_t X, gcry_mpi_t Y, 4768 gcry_mpi_point_t POINT, gcry_ctx_t CTX) 4769 4770 Compute the affine coordinates from the projective coordinates in 4771 POINT and store them into X and Y. If one coordinate is not 4772 required, 'NULL' may be passed to X or Y. CTX is the context 4773 object which has been created using 'gcry_mpi_ec_new'. Returns 0 4774 on success or not 0 if POINT is at infinity. 4775 4776 Note that you can use 'gcry_mpi_ec_set_point' with the value 4777 'GCRYMPI_CONST_ONE' for Z to convert affine coordinates back into 4778 projective coordinates. 4779 4780 -- Function: void gcry_mpi_ec_dup ( gcry_mpi_point_t W, 4781 gcry_mpi_point_t U, gcry_ctx_t CTX) 4782 4783 Double the point U of the elliptic curve described by CTX and store 4784 the result into W. 4785 4786 -- Function: void gcry_mpi_ec_add ( gcry_mpi_point_t W, 4787 gcry_mpi_point_t U, gcry_mpi_point_t V, gcry_ctx_t CTX) 4788 4789 Add the points U and V of the elliptic curve described by CTX and 4790 store the result into W. 4791 4792 -- Function: void gcry_mpi_ec_sub ( gcry_mpi_point_t W, 4793 gcry_mpi_point_t U, gcry_mpi_point_t V, gcry_ctx_t CTX) 4794 4795 Subtracts the point V from the point U of the elliptic curve 4796 described by CTX and store the result into W. Only Twisted Edwards 4797 curves are supported for now. 4798 4799 -- Function: void gcry_mpi_ec_mul ( gcry_mpi_point_t W, gcry_mpi_t N, 4800 gcry_mpi_point_t U, gcry_ctx_t CTX) 4801 4802 Multiply the point U of the elliptic curve described by CTX by N 4803 and store the result into W. 4804 4805 -- Function: int gcry_mpi_ec_curve_point ( gcry_mpi_point_t POINT, 4806 gcry_ctx_t CTX) 4807 4808 Return true if POINT is on the elliptic curve described by CTX. 4809 4810 4811File: gcrypt.info, Node: Miscellaneous, Prev: EC functions, Up: MPI library 4812 481312.8 Miscellaneous 4814================== 4815 4816An MPI data type is allowed to be "misused" to store an arbitrary value. 4817Two functions implement this kludge: 4818 4819 -- Function: gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t A, void *P, 4820 unsigned int NBITS) 4821 4822 Store NBITS of the value P points to in A and mark A as an opaque 4823 value (i.e. an value that can't be used for any math calculation 4824 and is only used to store an arbitrary bit pattern in A). 4825 Ownership of P is taken by this function and thus the user may not 4826 use dereference the passed value anymore. It is required that them 4827 memory referenced by P has been allocated in a way that 'gcry_free' 4828 is able to release it. 4829 4830 WARNING: Never use an opaque MPI for actual math operations. The 4831 only valid functions are gcry_mpi_get_opaque and gcry_mpi_release. 4832 Use gcry_mpi_scan to convert a string of arbitrary bytes into an 4833 MPI. 4834 4835 -- Function: gcry_mpi_t gcry_mpi_set_opaque_copy (gcry_mpi_t A, 4836 const void *P, unsigned int NBITS) 4837 4838 Same as 'gcry_mpi_set_opaque' but ownership of P is not taken 4839 instead a copy of P is used. 4840 4841 -- Function: void * gcry_mpi_get_opaque (gcry_mpi_t A, 4842 unsigned int *NBITS) 4843 4844 Return a pointer to an opaque value stored in A and return its size 4845 in NBITS. Note that the returned pointer is still owned by A and 4846 that the function should never be used for an non-opaque MPI. 4847 4848 Each MPI has an associated set of flags for special purposes. The 4849currently defined flags are: 4850 4851'GCRYMPI_FLAG_SECURE' 4852 Setting this flag converts A into an MPI stored in "secure memory". 4853 Clearing this flag is not allowed. 4854'GCRYMPI_FLAG_OPAQUE' 4855 This is an internal flag, indicating the an opaque valuue and not 4856 an integer is stored. This is an read-only flag; it may not be set 4857 or cleared. 4858'GCRYMPI_FLAG_IMMUTABLE' 4859 If this flag is set, the MPI is marked as immutable. Setting or 4860 changing the value of that MPI is ignored and an error message is 4861 logged. The flag is sometimes useful for debugging. 4862'GCRYMPI_FLAG_CONST' 4863 If this flag is set, the MPI is marked as a constant and as 4864 immutable Setting or changing the value of that MPI is ignored and 4865 an error message is logged. Such an MPI will never be deallocated 4866 and may thus be used without copying. Note that using 4867 gcry_mpi_copy will return a copy of that constant with this and the 4868 immutable flag cleared. A few commonly used constants are 4869 pre-defined and accessible using the macros 'GCRYMPI_CONST_ONE', 4870 'GCRYMPI_CONST_TWO', 'GCRYMPI_CONST_THREE', 'GCRYMPI_CONST_FOUR', 4871 and 'GCRYMPI_CONST_EIGHT'. 4872'GCRYMPI_FLAG_USER1' 4873'GCRYMPI_FLAG_USER2' 4874'GCRYMPI_FLAG_USER3' 4875'GCRYMPI_FLAG_USER4' 4876 These flags are reserved for use by the application. 4877 4878 -- Function: void gcry_mpi_set_flag (gcry_mpi_t A, 4879 enum gcry_mpi_flag FLAG) 4880 4881 Set the FLAG for the MPI A. The only allowed flags are 4882 'GCRYMPI_FLAG_SECURE', 'GCRYMPI_FLAG_IMMUTABLE', and 4883 'GCRYMPI_FLAG_CONST'. 4884 4885 -- Function: void gcry_mpi_clear_flag (gcry_mpi_t A, 4886 enum gcry_mpi_flag FLAG) 4887 4888 Clear FLAG for the multi-precision-integers A. The only allowed 4889 flag is 'GCRYMPI_FLAG_IMMUTABLE' but only if 'GCRYMPI_FLAG_CONST' 4890 is not set. If 'GCRYMPI_FLAG_CONST' is set, clearing 4891 'GCRYMPI_FLAG_IMMUTABLE' will simply be ignored. 4892 o 4893 -- Function: int gcry_mpi_get_flag (gcry_mpi_t A, 4894 enum gcry_mpi_flag FLAG) 4895 4896 Return true if FLAG is set for A. 4897 4898 To put a random value into an MPI, the following convenience function 4899may be used: 4900 4901 -- Function: void gcry_mpi_randomize (gcry_mpi_t W, unsigned int NBITS, 4902 enum gcry_random_level LEVEL) 4903 4904 Set the multi-precision-integers W to a random non-negative number 4905 of NBITS, using random data quality of level LEVEL. In case NBITS 4906 is not a multiple of a byte, NBITS is rounded up to the next byte 4907 boundary. When using a LEVEL of 'GCRY_WEAK_RANDOM' this function 4908 makes use of 'gcry_create_nonce'. 4909 4910 4911File: gcrypt.info, Node: Prime numbers, Next: Utilities, Prev: MPI library, Up: Top 4912 491313 Prime numbers 4914**************** 4915 4916* Menu: 4917 4918* Generation:: Generation of new prime numbers. 4919* Checking:: Checking if a given number is prime. 4920 4921 4922File: gcrypt.info, Node: Generation, Next: Checking, Up: Prime numbers 4923 492413.1 Generation 4925=============== 4926 4927 -- Function: gcry_error_t gcry_prime_generate (gcry_mpi_t 4928 *PRIME,unsigned int PRIME_BITS, unsigned int FACTOR_BITS, 4929 gcry_mpi_t **FACTORS, gcry_prime_check_func_t CB_FUNC, void 4930 *CB_ARG, gcry_random_level_t RANDOM_LEVEL, unsigned int FLAGS) 4931 4932 Generate a new prime number of PRIME_BITS bits and store it in 4933 PRIME. If FACTOR_BITS is non-zero, one of the prime factors of 4934 (PRIME - 1) / 2 must be FACTOR_BITS bits long. If FACTORS is 4935 non-zero, allocate a new, 'NULL'-terminated array holding the prime 4936 factors and store it in FACTORS. FLAGS might be used to influence 4937 the prime number generation process. 4938 4939 -- Function: gcry_error_t gcry_prime_group_generator (gcry_mpi_t *R_G, 4940 gcry_mpi_t PRIME, gcry_mpi_t *FACTORS, gcry_mpi_t START_G) 4941 4942 Find a generator for PRIME where the factorization of (PRIME-1) is 4943 in the 'NULL' terminated array FACTORS. Return the generator as a 4944 newly allocated MPI in R_G. If START_G is not NULL, use this as 4945 the start for the search. 4946 4947 -- Function: void gcry_prime_release_factors (gcry_mpi_t *FACTORS) 4948 4949 Convenience function to release the FACTORS array. 4950 4951 4952File: gcrypt.info, Node: Checking, Prev: Generation, Up: Prime numbers 4953 495413.2 Checking 4955============= 4956 4957 -- Function: gcry_error_t gcry_prime_check (gcry_mpi_t P, unsigned int 4958 FLAGS) 4959 4960 Check whether the number P is prime. Returns zero in case P is 4961 indeed a prime, returns 'GPG_ERR_NO_PRIME' in case P is not a prime 4962 and a different error code in case something went horribly wrong. 4963 4964 4965File: gcrypt.info, Node: Utilities, Next: Tools, Prev: Prime numbers, Up: Top 4966 496714 Utilities 4968************ 4969 4970* Menu: 4971 4972* Memory allocation:: Functions related with memory allocation. 4973* Context management:: Functions related with context management. 4974* Buffer description:: A data type to describe buffers. 4975* Config reporting:: How to return Libgcrypt's configuration. 4976 4977 4978File: gcrypt.info, Node: Memory allocation, Next: Context management, Up: Utilities 4979 498014.1 Memory allocation 4981====================== 4982 4983 -- Function: void * gcry_malloc (size_t N) 4984 4985 This function tries to allocate N bytes of memory. On success it 4986 returns a pointer to the memory area, in an out-of-core condition, 4987 it returns NULL. 4988 4989 -- Function: void * gcry_malloc_secure (size_t N) 4990 Like 'gcry_malloc', but uses secure memory. 4991 4992 -- Function: void * gcry_calloc (size_t N, size_t M) 4993 4994 This function allocates a cleared block of memory (i.e. 4995 initialized with zero bytes) long enough to contain a vector of N 4996 elements, each of size M bytes. On success it returns a pointer to 4997 the memory block; in an out-of-core condition, it returns NULL. 4998 4999 -- Function: void * gcry_calloc_secure (size_t N, size_t M) 5000 Like 'gcry_calloc', but uses secure memory. 5001 5002 -- Function: void * gcry_realloc (void *P, size_t N) 5003 5004 This function tries to resize the memory area pointed to by P to N 5005 bytes. On success it returns a pointer to the new memory area, in 5006 an out-of-core condition, it returns NULL. Depending on whether the 5007 memory pointed to by P is secure memory or not, gcry_realloc tries 5008 to use secure memory as well. 5009 5010 -- Function: void gcry_free (void *P) 5011 Release the memory area pointed to by P. 5012 5013 5014File: gcrypt.info, Node: Context management, Next: Buffer description, Prev: Memory allocation, Up: Utilities 5015 501614.2 Context management 5017======================= 5018 5019Some function make use of a context object. As of now there are only a 5020few math functions. However, future versions of Libgcrypt may make more 5021use of this context object. 5022 5023 -- Data type: gcry_ctx_t 5024 This type is used to refer to the general purpose context object. 5025 5026 -- Function: void gcry_ctx_release (gcry_ctx_t CTX) 5027 Release the context object CTX and all associated resources. A 5028 'NULL' passed as CTX is ignored. 5029 5030 5031File: gcrypt.info, Node: Buffer description, Next: Config reporting, Prev: Context management, Up: Utilities 5032 503314.3 Buffer description 5034======================= 5035 5036To help hashing non-contiguous areas of memory a general purpose data 5037type is defined: 5038 5039 -- Data type: gcry_buffer_t 5040 This type is a structure to describe a buffer. The user should 5041 make sure that this structure is initialized to zero. The 5042 available fields of this structure are: 5043 5044 '.size' 5045 This is either 0 for no information available or indicates the 5046 allocated length of the buffer. 5047 '.off' 5048 This is the offset into the buffer. 5049 '.len' 5050 This is the valid length of the buffer starting at '.off'. 5051 '.data' 5052 This is the address of the buffer. 5053 5054 5055File: gcrypt.info, Node: Config reporting, Prev: Buffer description, Up: Utilities 5056 505714.4 How to return Libgcrypt's configuration. 5058============================================= 5059 5060Although 'GCRYCTL_PRINT_CONFIG' can be used to print configuration 5061options, it is sometimes necessary to check them in a program. This can 5062be accomplished by using this function: 5063 5064 -- Function: char * gcry_get_config (int MODE, const char *WHAT) 5065 5066 This function returns a malloced string with colon delimited 5067 configure options. With a value of 0 for MODE this string 5068 resembles the output of 'GCRYCTL_PRINT_CONFIG'. However, if WHAT 5069 is not NULL, only the line where the first field (e.g. "cpu-arch") 5070 matches WHAT is returned. 5071 5072 Other values than 0 for MODE are not defined. The caller shall 5073 free the string using 'gcry_free'. On error NULL is returned and 5074 ERRNO is set; if a value for WHAT is unknow ERRNO will be set to 0. 5075 5076 5077File: gcrypt.info, Node: Tools, Next: Configuration, Prev: Utilities, Up: Top 5078 507915 Tools 5080******** 5081 5082* Menu: 5083 5084* hmac256:: A standalone HMAC-SHA-256 implementation 5085 5086 5087File: gcrypt.info, Node: hmac256, Up: Tools 5088 508915.1 A HMAC-SHA-256 tool 5090======================== 5091 5092This is a standalone HMAC-SHA-256 implementation used to compute an 5093HMAC-SHA-256 message authentication code. The tool has originally been 5094developed as a second implementation for Libgcrypt to allow comparing 5095against the primary implementation and to be used for internal 5096consistency checks. It should not be used for sensitive data because no 5097mechanisms to clear the stack etc are used. 5098 5099 The code has been written in a highly portable manner and requires 5100only a few standard definitions to be provided in a config.h file. 5101 5102'hmac256' is commonly invoked as 5103 5104 hmac256 "This is my key" foo.txt 5105 5106This compute the MAC on the file 'foo.txt' using the key given on the 5107command line. 5108 5109'hmac256' understands these options: 5110 5111'--binary' 5112 Print the MAC as a binary string. The default is to print the MAC 5113 encoded has lower case hex digits. 5114 5115'--version' 5116 Print version of the program and exit. 5117 5118 5119File: gcrypt.info, Node: Configuration, Next: Architecture, Prev: Tools, Up: Top 5120 512116 Configuration files and environment variables 5122************************************************ 5123 5124This chapter describes which files and environment variables can be used 5125to change the behaviour of Libgcrypt. 5126 5127The environment variables considered by Libgcrypt are: 5128 5129'GCRYPT_BARRETT' 5130 By setting this variable to any value a different algorithm for 5131 modular reduction is used for ECC. 5132 5133'GCRYPT_RNDUNIX_DBG' 5134'GCRYPT_RNDUNIX_DBGALL' 5135 These two environment variables are used to enable debug output for 5136 the rndunix entropy gatherer, which is used on systems lacking a 5137 /dev/random device. The value of 'GCRYPT_RNDUNIX_DBG' is a file 5138 name or '-' for stdout. Debug output is the written to this file. 5139 By setting 'GCRYPT_RNDUNIX_DBGALL' to any value the debug output 5140 will be more verbose. 5141 5142'GCRYPT_RNDW32_NOPERF' 5143 Setting this environment variable on Windows to any value disables 5144 the use of performance data ('HKEY_PERFORMANCE_DATA') as source for 5145 entropy. On some older Windows systems this could help to speed up 5146 the creation of random numbers but also decreases the amount of 5147 data used to init the random number generator. 5148 5149'GCRYPT_RNDW32_DBG' 5150 Setting the value of this variable to a positive integer logs 5151 information about the Windows entropy gatherer using the standard 5152 log interface. 5153 5154'HOME' 5155 This is used to locate the socket to connect to the EGD random 5156 daemon. The EGD can be used on system without a /dev/random to 5157 speed up the random number generator. It is not needed on the 5158 majority of today's operating systems and support for EGD requires 5159 the use of a configure option at build time. 5160 5161The files which Libgcrypt uses to retrieve system information and the 5162files which can be created by the user to modify Libgcrypt's behavior 5163are: 5164 5165'/etc/gcrypt/hwf.deny' 5166 This file can be used to disable the use of hardware based 5167 optimizations, *note hardware features::. 5168 5169'/etc/gcrypt/random.conf' 5170 This file can be used to globally change parameters of the random 5171 generator. The file is a simple text file where empty lines and 5172 lines with the first non white-space character being '#' are 5173 ignored. Supported options are 5174 5175 'disable-jent' 5176 Disable the use of the jitter based entropy generator. 5177 5178 'only-urandom' 5179 Always use the non-blocking /dev/urandom or the respective 5180 system call instead of the blocking /dev/random. If Libgcrypt 5181 is used early in the boot process of the system, this option 5182 should only be used if the system also supports the getrandom 5183 system call. 5184 5185'/etc/gcrypt/fips_enabled' 5186'/proc/sys/crypto/fips_enabled' 5187 On Linux these files are used to enable FIPS mode, *note enabling 5188 fips mode::. 5189 5190'/proc/cpuinfo' 5191'/proc/self/auxv' 5192 On Linux running on the ARM architecture, these files are used to 5193 read hardware capabilities of the CPU. 5194 5195 5196File: gcrypt.info, Node: Architecture, Next: Self-Tests, Prev: Configuration, Up: Top 5197 519817 Architecture 5199*************** 5200 5201This chapter describes the internal architecture of Libgcrypt. 5202 5203 Libgcrypt is a function library written in ISO C-90. Any compliant 5204compiler should be able to build Libgcrypt as long as the target is 5205either a POSIX platform or compatible to the API used by Windows NT. 5206Provisions have been take so that the library can be directly used from 5207C++ applications; however building with a C++ compiler is not supported. 5208 5209 Building Libgcrypt is done by using the common './configure && make' 5210approach. The configure command is included in the source distribution 5211and as a portable shell script it works on any Unix-alike system. The 5212result of running the configure script are a C header file ('config.h'), 5213customized Makefiles, the setup of symbolic links and a few other 5214things. After that the make tool builds and optionally installs the 5215library and the documentation. See the files 'INSTALL' and 'README' in 5216the source distribution on how to do this. 5217 5218 Libgcrypt is developed using a Subversion(1) repository. Although 5219all released versions are tagged in this repository, they should not be 5220used to build production versions of Libgcrypt. Instead released 5221tarballs should be used. These tarballs are available from several 5222places with the master copy at 'ftp://ftp.gnupg.org/gcrypt/libgcrypt/'. 5223Announcements of new releases are posted to the 5224'gnupg-announce@gnupg.org' mailing list(2). 5225 5226 �[image src="libgcrypt-modules.png" alt="Libgcrypt subsystems"�] 5227 5228Figure 17.1: Libgcrypt subsystems 5229 5230 Libgcrypt consists of several subsystems (*note Figure 17.1: 5231fig:subsystems.) and all these subsystems provide a public API; this 5232includes the helper subsystems like the one for S-expressions. The API 5233style depends on the subsystem; in general an open-use-close approach is 5234implemented. The open returns a handle to a context used for all 5235further operations on this handle, several functions may then be used on 5236this handle and a final close function releases all resources associated 5237with the handle. 5238 5239* Menu: 5240 5241* Public-Key Subsystem Architecture:: About public keys. 5242* Symmetric Encryption Subsystem Architecture:: About standard ciphers. 5243* Hashing and MACing Subsystem Architecture:: About hashing. 5244* Multi-Precision-Integer Subsystem Architecture:: About big integers. 5245* Prime-Number-Generator Subsystem Architecture:: About prime numbers. 5246* Random-Number Subsystem Architecture:: About random stuff. 5247 5248 ---------- Footnotes ---------- 5249 5250 (1) A version control system available for many platforms 5251 5252 (2) See <http://www.gnupg.org/documentation/mailing-lists.en.html> 5253for details. 5254 5255 5256File: gcrypt.info, Node: Public-Key Subsystem Architecture, Next: Symmetric Encryption Subsystem Architecture, Up: Architecture 5257 525817.1 Public-Key Architecture 5259============================ 5260 5261Because public key cryptography is almost always used to process small 5262amounts of data (hash values or session keys), the interface is not 5263implemented using the open-use-close paradigm, but with single 5264self-contained functions. Due to the wide variety of parameters 5265required by different algorithms S-expressions, as flexible way to 5266convey these parameters, are used. There is a set of helper functions 5267to work with these S-expressions. 5268 5269 Aside of functions to register new algorithms, map algorithms names 5270to algorithms identifiers and to lookup properties of a key, the 5271following main functions are available: 5272 5273'gcry_pk_encrypt' 5274 Encrypt data using a public key. 5275 5276'gcry_pk_decrypt' 5277 Decrypt data using a private key. 5278 5279'gcry_pk_sign' 5280 Sign data using a private key. 5281 5282'gcry_pk_verify' 5283 Verify that a signature matches the data. 5284 5285'gcry_pk_testkey' 5286 Perform a consistency over a public or private key. 5287 5288'gcry_pk_genkey' 5289 Create a new public/private key pair. 5290 5291 All these functions lookup the module implementing the algorithm and 5292pass the actual work to that module. The parsing of the S-expression 5293input and the construction of S-expression for the return values is done 5294by the high level code ('cipher/pubkey.c'). Thus the internal interface 5295between the algorithm modules and the high level functions passes data 5296in a custom format. 5297 5298 By default Libgcrypt uses a blinding technique for RSA decryption to 5299mitigate real world timing attacks over a network: Instead of using the 5300RSA decryption directly, a blinded value y = x r^{e} \bmod n is 5301decrypted and the unblinded value x' = y' r^{-1} \bmod n returned. The 5302blinding value r is a random value with the size of the modulus n and 5303generated with 'GCRY_WEAK_RANDOM' random level. 5304 5305 The algorithm used for RSA and DSA key generation depends on whether 5306Libgcrypt is operated in standard or in FIPS mode. In standard mode an 5307algorithm based on the Lim-Lee prime number generator is used. In FIPS 5308mode RSA keys are generated as specified in ANSI X9.31 (1998) and DSA 5309keys as specified in FIPS 186-2. 5310 5311 5312File: gcrypt.info, Node: Symmetric Encryption Subsystem Architecture, Next: Hashing and MACing Subsystem Architecture, Prev: Public-Key Subsystem Architecture, Up: Architecture 5313 531417.2 Symmetric Encryption Subsystem Architecture 5315================================================ 5316 5317The interface to work with symmetric encryption algorithms is made up of 5318functions from the 'gcry_cipher_' name space. The implementation 5319follows the open-use-close paradigm and uses registered algorithm 5320modules for the actual work. Unless a module implements optimized 5321cipher mode implementations, the high level code ('cipher/cipher.c') 5322implements the modes and calls the core algorithm functions to process 5323each block. 5324 5325 The most important functions are: 5326 5327'gcry_cipher_open' 5328 Create a new instance to encrypt or decrypt using a specified 5329 algorithm and mode. 5330 5331'gcry_cipher_close' 5332 Release an instance. 5333 5334'gcry_cipher_setkey' 5335 Set a key to be used for encryption or decryption. 5336 5337'gcry_cipher_setiv' 5338 Set an initialization vector to be used for encryption or 5339 decryption. 5340 5341'gcry_cipher_encrypt' 5342'gcry_cipher_decrypt' 5343 Encrypt or decrypt data. These functions may be called with 5344 arbitrary amounts of data and as often as needed to encrypt or 5345 decrypt all data. 5346 5347 There is no strict alignment requirements for data, but the best 5348 performance can be archived if data is aligned to cacheline 5349 boundary. 5350 5351 There are also functions to query properties of algorithms or 5352context, like block length, key length, map names or to enable features 5353like padding methods. 5354 5355 5356File: gcrypt.info, Node: Hashing and MACing Subsystem Architecture, Next: Multi-Precision-Integer Subsystem Architecture, Prev: Symmetric Encryption Subsystem Architecture, Up: Architecture 5357 535817.3 Hashing and MACing Subsystem Architecture 5359============================================== 5360 5361The interface to work with message digests and CRC algorithms is made up 5362of functions from the 'gcry_md_' name space. The implementation follows 5363the open-use-close paradigm and uses registered algorithm modules for 5364the actual work. Although CRC algorithms are not considered 5365cryptographic hash algorithms, they share enough properties so that it 5366makes sense to handle them in the same way. It is possible to use 5367several algorithms at once with one context and thus compute them all on 5368the same data. 5369 5370 The most important functions are: 5371 5372'gcry_md_open' 5373 Create a new message digest instance and optionally enable one 5374 algorithm. A flag may be used to turn the message digest algorithm 5375 into a HMAC algorithm. 5376 5377'gcry_md_enable' 5378 Enable an additional algorithm for the instance. 5379 5380'gcry_md_setkey' 5381 Set the key for the MAC. 5382 5383'gcry_md_write' 5384 Pass more data for computing the message digest to an instance. 5385 5386 There is no strict alignment requirements for data, but the best 5387 performance can be archived if data is aligned to cacheline 5388 boundary. 5389 5390'gcry_md_putc' 5391 Buffered version of 'gcry_md_write' implemented as a macro. 5392 5393'gcry_md_read' 5394 Finalize the computation of the message digest or HMAC and return 5395 the result. 5396 5397'gcry_md_close' 5398 Release an instance 5399 5400'gcry_md_hash_buffer' 5401 Convenience function to directly compute a message digest over a 5402 memory buffer without the need to create an instance first. 5403 5404 There are also functions to query properties of algorithms or the 5405instance, like enabled algorithms, digest length, map algorithm names. 5406it is also possible to reset an instance or to copy the current state of 5407an instance at any time. Debug functions to write the hashed data to 5408files are available as well. 5409 5410 5411File: gcrypt.info, Node: Multi-Precision-Integer Subsystem Architecture, Next: Prime-Number-Generator Subsystem Architecture, Prev: Hashing and MACing Subsystem Architecture, Up: Architecture 5412 541317.4 Multi-Precision-Integer Subsystem Architecture 5414=================================================== 5415 5416The implementation of Libgcrypt's big integer computation code is based 5417on an old release of GNU Multi-Precision Library (GMP). The decision not 5418to use the GMP library directly was due to stalled development at that 5419time and due to security requirements which could not be provided by the 5420code in GMP. As GMP does, Libgcrypt provides high performance assembler 5421implementations of low level code for several CPUS to gain much better 5422performance than with a generic C implementation. 5423 5424Major features of Libgcrypt's multi-precision-integer code compared to 5425GMP are: 5426 5427 * Avoidance of stack based allocations to allow protection against 5428 swapping out of sensitive data and for easy zeroing of sensitive 5429 intermediate results. 5430 5431 * Optional use of secure memory and tracking of its use so that 5432 results are also put into secure memory. 5433 5434 * MPIs are identified by a handle (implemented as a pointer) to give 5435 better control over allocations and to augment them with extra 5436 properties like opaque data. 5437 5438 * Removal of unnecessary code to reduce complexity. 5439 5440 * Functions specialized for public key cryptography. 5441 5442 5443File: gcrypt.info, Node: Prime-Number-Generator Subsystem Architecture, Next: Random-Number Subsystem Architecture, Prev: Multi-Precision-Integer Subsystem Architecture, Up: Architecture 5444 544517.5 Prime-Number-Generator Subsystem Architecture 5446================================================== 5447 5448Libgcrypt provides an interface to its prime number generator. These 5449functions make use of the internal prime number generator which is 5450required for the generation for public key key pairs. The plain prime 5451checking function is exported as well. 5452 5453 The generation of random prime numbers is based on the Lim and Lee 5454algorithm to create practically save primes.(1) This algorithm creates 5455a pool of smaller primes, select a few of them to create candidate 5456primes of the form 2 * p_0 * p_1 * ... * p_n + 1, tests the candidate 5457for primality and permutates the pool until a prime has been found. It 5458is possible to clamp one of the small primes to a certain size to help 5459DSA style algorithms. Because most of the small primes in the pool are 5460not used for the resulting prime number, they are saved for later use 5461(see 'save_pool_prime' and 'get_pool_prime' in 'cipher/primegen.c'). 5462The prime generator optionally supports the finding of an appropriate 5463generator. 5464 5465The primality test works in three steps: 5466 5467 1. The standard sieve algorithm using the primes up to 4999 is used as 5468 a quick first check. 5469 5470 2. A Fermat test filters out almost all non-primes. 5471 5472 3. A 5 round Rabin-Miller test is finally used. The first round uses 5473 a witness of 2, whereas the next rounds use a random witness. 5474 5475 To support the generation of RSA and DSA keys in FIPS mode according 5476to X9.31 and FIPS 186-2, Libgcrypt implements two additional prime 5477generation functions: '_gcry_derive_x931_prime' and 5478'_gcry_generate_fips186_2_prime'. These functions are internal and not 5479available through the public API. 5480 5481 ---------- Footnotes ---------- 5482 5483 (1) Chae Hoon Lim and Pil Joong Lee. A key recovery attack on 5484discrete log-based schemes using a prime order subgroup. In Burton S. 5485Kaliski Jr., editor, Advances in Cryptology: Crypto '97, pages 5486249-263, Berlin / Heidelberg / New York, 1997. Springer-Verlag. 5487Described on page 260. 5488 5489 5490File: gcrypt.info, Node: Random-Number Subsystem Architecture, Prev: Prime-Number-Generator Subsystem Architecture, Up: Architecture 5491 549217.6 Random-Number Subsystem Architecture 5493========================================= 5494 5495Libgcrypt provides 3 levels or random quality: The level 5496'GCRY_VERY_STRONG_RANDOM' usually used for key generation, the level 5497'GCRY_STRONG_RANDOM' for all other strong random requirements and the 5498function 'gcry_create_nonce' which is used for weaker usages like 5499nonces. There is also a level 'GCRY_WEAK_RANDOM' which in general maps 5500to 'GCRY_STRONG_RANDOM' except when used with the function 5501'gcry_mpi_randomize', where it randomizes an multi-precision-integer 5502using the 'gcry_create_nonce' function. 5503 5504There are two distinct random generators available: 5505 5506 * The Continuously Seeded Pseudo Random Number Generator (CSPRNG), 5507 which is based on the classic GnuPG derived big pool 5508 implementation. Implemented in 'random/random-csprng.c' and used 5509 by default. 5510 * A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key. 5511 Implemented in 'random/random-fips.c' and used if Libgcrypt is in 5512 FIPS mode. 5513 5514Both generators make use of so-called entropy gathering modules: 5515 5516rndlinux 5517 Uses the operating system provided '/dev/random' and '/dev/urandom' 5518 devices. The '/dev/gcrypt/random.conf' config option 5519 'only-urandom' can be used to inhibit the use of the blocking 5520 '/dev/random' device. 5521 5522rndunix 5523 Runs several operating system commands to collect entropy from 5524 sources like virtual machine and process statistics. It is a kind 5525 of poor-man's '/dev/random' implementation. It is not available in 5526 FIPS mode. 5527 5528rndegd 5529 Uses the operating system provided Entropy Gathering Daemon (EGD). 5530 The EGD basically uses the same algorithms as rndunix does. 5531 However as a system daemon it keeps on running and thus can serve 5532 several processes requiring entropy input and does not waste 5533 collected entropy if the application does not need all the 5534 collected entropy. It is not available in FIPS mode. 5535 5536rndw32 5537 Targeted for the Microsoft Windows OS. It uses certain properties 5538 of that system and is the only gathering module available for that 5539 OS. 5540 5541rndhw 5542 Extra module to collect additional entropy by utilizing a hardware 5543 random number generator. As of now the supported hardware RNG is 5544 the Padlock engine of VIA (Centaur) CPUs and x86 CPUs with the 5545 RDRAND instruction. It is not available in FIPS mode. 5546 5547rndjent 5548 Extra module to collect additional entropy using a CPU jitter based 5549 approach. This is only used on X86 hardware where the RDTSC opcode 5550 is available. The '/dev/gcrypt/random.conf' config option 5551 'disable-jent' can be used to inhibit the use of this module. 5552 5553* Menu: 5554 5555* CSPRNG Description:: Description of the CSPRNG. 5556* FIPS PRNG Description:: Description of the FIPS X9.31 PRNG. 5557 5558 5559File: gcrypt.info, Node: CSPRNG Description, Next: FIPS PRNG Description, Up: Random-Number Subsystem Architecture 5560 556117.6.1 Description of the CSPRNG 5562-------------------------------- 5563 5564This random number generator is loosely modelled after the one described 5565in Peter Gutmann's paper: "Software Generation of Practically Strong 5566Random Numbers".(1) 5567 5568 A pool of 600 bytes is used and mixed using the core SHA-1 hash 5569transform function. Several extra features are used to make the robust 5570against a wide variety of attacks and to protect against failures of 5571subsystems. The state of the generator may be saved to a file and 5572initially seed form a file. 5573 5574 Depending on how Libgcrypt was build the generator is able to select 5575the best working entropy gathering module. It makes use of the slow and 5576fast collection methods and requires the pool to initially seeded form 5577the slow gatherer or a seed file. An entropy estimation is used to mix 5578in enough data from the gather modules before returning the actual 5579random output. Process fork detection and protection is implemented. 5580 5581 The implementation of the nonce generator (for 'gcry_create_nonce') 5582is a straightforward repeated hash design: A 28 byte buffer is initially 5583seeded with the PID and the time in seconds in the first 20 bytes and 5584with 8 bytes of random taken from the 'GCRY_STRONG_RANDOM' generator. 5585Random numbers are then created by hashing all the 28 bytes with SHA-1 5586and saving that again in the first 20 bytes. The hash is also returned 5587as result. 5588 5589 ---------- Footnotes ---------- 5590 5591 (1) Also described in chapter 6 of his book "Cryptographic Security 5592Architecture", New York, 2004, ISBN 0-387-95387-6. 5593 5594 5595File: gcrypt.info, Node: FIPS PRNG Description, Prev: CSPRNG Description, Up: Random-Number Subsystem Architecture 5596 559717.6.2 Description of the FIPS X9.31 PRNG 5598----------------------------------------- 5599 5600The core of this deterministic random number generator is implemented 5601according to the document "NIST-Recommended Random Number Generator 5602Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES 5603Algorithms", dated 2005-01-31. This implementation uses the AES 5604variant. 5605 5606 The generator is based on contexts to utilize the same core functions 5607for all random levels as required by the high-level interface. All 5608random generators return their data in 128 bit blocks. If the caller 5609requests less bits, the extra bits are not used. The key for each 5610generator is only set once at the first time a generator context is 5611used. The seed value is set along with the key and again after 1000 5612output blocks. 5613 5614 On Unix like systems the 'GCRY_VERY_STRONG_RANDOM' and 5615'GCRY_STRONG_RANDOM' generators are keyed and seeded using the rndlinux 5616module with the '/dev/random' device. Thus these generators may block 5617until the OS kernel has collected enough entropy. When used with 5618Microsoft Windows the rndw32 module is used instead. 5619 5620 The generator used for 'gcry_create_nonce' is keyed and seeded from 5621the 'GCRY_STRONG_RANDOM' generator. Thus is may also block if the 5622'GCRY_STRONG_RANDOM' generator has not yet been used before and thus 5623gets initialized on the first use by 'gcry_create_nonce'. This special 5624treatment is justified by the weaker requirements for a nonce generator 5625and to save precious kernel entropy for use by the "real" random 5626generators. 5627 5628 A self-test facility uses a separate context to check the 5629functionality of the core X9.31 functions using a known answers test. 5630During runtime each output block is compared to the previous one to 5631detect a stuck generator. 5632 5633 The DT value for the generator is made up of the current time down to 5634microseconds (if available) and a free running 64 bit counter. When 5635used with the test context the DT value is taken from the context and 5636incremented on each use. 5637 5638 5639File: gcrypt.info, Node: Self-Tests, Next: FIPS Mode, Prev: Architecture, Up: Top 5640 5641Appendix A Description of the Self-Tests 5642**************************************** 5643 5644In addition to the build time regression test suite, Libgcrypt 5645implements self-tests to be performed at runtime. Which self-tests are 5646actually used depends on the mode Libgcrypt is used in. In standard 5647mode a limited set of self-tests is run at the time an algorithm is 5648first used. Note that not all algorithms feature a self-test in 5649standard mode. The 'GCRYCTL_SELFTEST' control command may be used to 5650run all implemented self-tests at any time; this will even run more 5651tests than those run in FIPS mode. 5652 5653 If any of the self-tests fails, the library immediately returns an 5654error code to the caller. If Libgcrypt is in FIPS mode the self-tests 5655will be performed within the "Self-Test" state and any failure puts the 5656library into the "Error" state. 5657 5658A.1 Power-Up Tests 5659================== 5660 5661Power-up tests are only performed if Libgcrypt is in FIPS mode. 5662 5663A.1.1 Symmetric Cipher Algorithm Power-Up Tests 5664----------------------------------------------- 5665 5666The following symmetric encryption algorithm tests are run during 5667power-up: 5668 56693DES 5670 To test the 3DES 3-key EDE encryption in ECB mode these tests are 5671 run: 5672 1. A known answer test is run on a 64 bit test vector processed 5673 by 64 rounds of Single-DES block encryption and decryption 5674 using a key changed with each round. 5675 2. A known answer test is run on a 64 bit test vector processed 5676 by 16 rounds of 2-key and 3-key Triple-DES block encryption 5677 and decryptions using a key changed with each round. 5678 3. 10 known answer tests using 3-key Triple-DES EDE encryption, 5679 comparing the ciphertext to the known value, then running a 5680 decryption and comparing it to the initial plaintext. 5681 ('cipher/des.c:selftest') 5682 5683AES-128 5684 A known answer tests is run using one test vector and one test key 5685 with AES in ECB mode. ('cipher/rijndael.c:selftest_basic_128') 5686 5687AES-192 5688 A known answer tests is run using one test vector and one test key 5689 with AES in ECB mode. ('cipher/rijndael.c:selftest_basic_192') 5690 5691AES-256 5692 A known answer tests is run using one test vector and one test key 5693 with AES in ECB mode. ('cipher/rijndael.c:selftest_basic_256') 5694 5695A.1.2 Hash Algorithm Power-Up Tests 5696----------------------------------- 5697 5698The following hash algorithm tests are run during power-up: 5699 5700SHA-1 5701 A known answer test using the string '"abc"' is run. 5702 ('cipher/sha1.c:selftests_sha1') 5703SHA-224 5704 A known answer test using the string '"abc"' is run. 5705 ('cipher/sha256.c:selftests_sha224') 5706SHA-256 5707 A known answer test using the string '"abc"' is run. 5708 ('cipher/sha256.c:selftests_sha256') 5709SHA-384 5710 A known answer test using the string '"abc"' is run. 5711 ('cipher/sha512.c:selftests_sha384') 5712SHA-512 5713 A known answer test using the string '"abc"' is run. 5714 ('cipher/sha512.c:selftests_sha512') 5715 5716A.1.3 MAC Algorithm Power-Up Tests 5717---------------------------------- 5718 5719The following MAC algorithm tests are run during power-up: 5720 5721HMAC SHA-1 5722 A known answer test using 9 byte of data and a 64 byte key is run. 5723 ('cipher/hmac-tests.c:selftests_sha1') 5724HMAC SHA-224 5725 A known answer test using 28 byte of data and a 4 byte key is run. 5726 ('cipher/hmac-tests.c:selftests_sha224') 5727HMAC SHA-256 5728 A known answer test using 28 byte of data and a 4 byte key is run. 5729 ('cipher/hmac-tests.c:selftests_sha256') 5730HMAC SHA-384 5731 A known answer test using 28 byte of data and a 4 byte key is run. 5732 ('cipher/hmac-tests.c:selftests_sha384') 5733HMAC SHA-512 5734 A known answer test using 28 byte of data and a 4 byte key is run. 5735 ('cipher/hmac-tests.c:selftests_sha512') 5736 5737A.1.4 Random Number Power-Up Test 5738--------------------------------- 5739 5740The DRNG is tested during power-up this way: 5741 5742 1. Requesting one block of random using the public interface to check 5743 general working and the duplicated block detection. 5744 2. 3 know answer tests using pre-defined keys, seed and initial DT 5745 values. For each test 3 blocks of 16 bytes are requested and 5746 compared to the expected result. The DT value is incremented for 5747 each block. 5748 5749A.1.5 Public Key Algorithm Power-Up Tests 5750----------------------------------------- 5751 5752The public key algorithms are tested during power-up: 5753 5754RSA 5755 A pre-defined 1024 bit RSA key is used and these tests are run in 5756 turn: 5757 1. Conversion of S-expression to internal format. 5758 ('cipher/rsa.c:selftests_rsa') 5759 2. Private key consistency check. ('cipher/rsa.c:selftests_rsa') 5760 3. A pre-defined 20 byte value is signed with PKCS#1 padding for 5761 SHA-1. The result is verified using the public key against 5762 the original data and against modified data. 5763 ('cipher/rsa.c:selftest_sign_1024') 5764 4. A 1000 bit random value is encrypted and checked that it does 5765 not match the original random value. The encrypted result is 5766 then decrypted and checked that it matches the original random 5767 value. ('cipher/rsa.c:selftest_encr_1024') 5768 5769DSA 5770 A pre-defined 1024 bit DSA key is used and these tests are run in 5771 turn: 5772 1. Conversion of S-expression to internal format. 5773 ('cipher/dsa.c:selftests_dsa') 5774 2. Private key consistency check. ('cipher/dsa.c:selftests_dsa') 5775 3. A pre-defined 20 byte value is signed with PKCS#1 padding for 5776 SHA-1. The result is verified using the public key against 5777 the original data and against modified data. 5778 ('cipher/dsa.c:selftest_sign_1024') 5779 5780A.1.6 Integrity Power-Up Tests 5781------------------------------ 5782 5783The integrity of the Libgcrypt is tested during power-up but only if 5784checking has been enabled at build time. The check works by computing a 5785HMAC SHA-256 checksum over the file used to load Libgcrypt into memory. 5786That checksum is compared against a checksum stored in a file of the 5787same name but with a single dot as a prefix and a suffix of '.hmac'. 5788 5789A.1.7 Critical Functions Power-Up Tests 5790--------------------------------------- 5791 5792The 3DES weak key detection is tested during power-up by calling the 5793detection function with keys taken from a table listening all weak keys. 5794The table itself is protected using a SHA-1 hash. 5795('cipher/des.c:selftest') 5796 5797A.2 Conditional Tests 5798===================== 5799 5800The conditional tests are performed if a certain condition is met. This 5801may occur at any time; the library does not necessary enter the 5802"Self-Test" state to run these tests but will transit to the "Error" 5803state if a test failed. 5804 5805A.2.1 Key-Pair Generation Tests 5806------------------------------- 5807 5808After an asymmetric key-pair has been generated, Libgcrypt runs a 5809pair-wise consistency tests on the generated key. On failure the 5810generated key is not used, an error code is returned and, if in FIPS 5811mode, the library is put into the "Error" state. 5812 5813RSA 5814 The test uses a random number 64 bits less the size of the modulus 5815 as plaintext and runs an encryption and decryption operation in 5816 turn. The encrypted value is checked to not match the plaintext 5817 and the result of the decryption is checked to match the plaintext. 5818 5819 A new random number of the same size is generated, signed and 5820 verified to test the correctness of the signing operation. As a 5821 second signing test, the signature is modified by incrementing its 5822 value and then verified with the expected result that the 5823 verification fails. ('cipher/rsa.c:test_keys') 5824DSA 5825 The test uses a random number of the size of the Q parameter to 5826 create a signature and then checks that the signature verifies. As 5827 a second signing test, the data is modified by incrementing its 5828 value and then verified against the signature with the expected 5829 result that the verification fails. ('cipher/dsa.c:test_keys') 5830 5831A.2.2 Software Load Tests 5832------------------------- 5833 5834No code is loaded at runtime. 5835 5836A.2.3 Manual Key Entry Tests 5837---------------------------- 5838 5839A manual key entry feature is not implemented in Libgcrypt. 5840 5841A.2.4 Continuous RNG Tests 5842-------------------------- 5843 5844The continuous random number test is only used in FIPS mode. The RNG 5845generates blocks of 128 bit size; the first block generated per context 5846is saved in the context and another block is generated to be returned to 5847the caller. Each block is compared against the saved block and then 5848stored in the context. If a duplicated block is detected an error is 5849signaled and the library is put into the "Fatal-Error" state. 5850('random/random-fips.c:x931_aes_driver') 5851 5852A.3 Application Requested Tests 5853=============================== 5854 5855The application may requests tests at any time by means of the 5856'GCRYCTL_SELFTEST' control command. Note that using these tests is not 5857FIPS conform: Although Libgcrypt rejects all application requests for 5858services while running self-tests, it does not ensure that no other 5859operations of Libgcrypt are still being executed. Thus, in FIPS mode an 5860application requesting self-tests needs to power-cycle Libgcrypt 5861instead. 5862 5863 When self-tests are requested, Libgcrypt runs all the tests it does 5864during power-up as well as a few extra checks as described below. 5865 5866A.3.1 Symmetric Cipher Algorithm Tests 5867-------------------------------------- 5868 5869The following symmetric encryption algorithm tests are run in addition 5870to the power-up tests: 5871 5872AES-128 5873 A known answer tests with test vectors taken from NIST SP800-38a 5874 and using the high level functions is run for block modes CFB and 5875 OFB. 5876 5877A.3.2 Hash Algorithm Tests 5878-------------------------- 5879 5880The following hash algorithm tests are run in addition to the power-up 5881tests: 5882 5883SHA-1 5884SHA-224 5885SHA-256 5886 1. A known answer test using a 56 byte string is run. 5887 2. A known answer test using a string of one million letters "a" 5888 is run. 5889 ('cipher/sha1.c:selftests_sha1', 5890 'cipher/sha256.c:selftests_sha224', 5891 'cipher/sha256.c:selftests_sha256') 5892SHA-384 5893SHA-512 5894 1. A known answer test using a 112 byte string is run. 5895 2. A known answer test using a string of one million letters "a" 5896 is run. 5897 ('cipher/sha512.c:selftests_sha384', 5898 'cipher/sha512.c:selftests_sha512') 5899 5900A.3.3 MAC Algorithm Tests 5901------------------------- 5902 5903The following MAC algorithm tests are run in addition to the power-up 5904tests: 5905 5906HMAC SHA-1 5907 1. A known answer test using 9 byte of data and a 20 byte key is 5908 run. 5909 2. A known answer test using 9 byte of data and a 100 byte key is 5910 run. 5911 3. A known answer test using 9 byte of data and a 49 byte key is 5912 run. 5913 ('cipher/hmac-tests.c:selftests_sha1') 5914HMAC SHA-224 5915HMAC SHA-256 5916HMAC SHA-384 5917HMAC SHA-512 5918 1. A known answer test using 9 byte of data and a 20 byte key is 5919 run. 5920 2. A known answer test using 50 byte of data and a 20 byte key is 5921 run. 5922 3. A known answer test using 50 byte of data and a 26 byte key is 5923 run. 5924 4. A known answer test using 54 byte of data and a 131 byte key 5925 is run. 5926 5. A known answer test using 152 byte of data and a 131 byte key 5927 is run. 5928 ('cipher/hmac-tests.c:selftests_sha224', 5929 'cipher/hmac-tests.c:selftests_sha256', 5930 'cipher/hmac-tests.c:selftests_sha384', 5931 'cipher/hmac-tests.c:selftests_sha512') 5932 5933 5934File: gcrypt.info, Node: FIPS Mode, Next: Library Copying, Prev: Self-Tests, Up: Top 5935 5936Appendix B Description of the FIPS Mode 5937*************************************** 5938 5939This appendix gives detailed information pertaining to the FIPS mode. 5940In particular, the changes to the standard mode and the finite state 5941machine are described. The self-tests required in this mode are 5942described in the appendix on self-tests. 5943 5944B.1 Restrictions in FIPS Mode 5945============================= 5946 5947If Libgcrypt is used in FIPS mode these restrictions are effective: 5948 5949 * The cryptographic algorithms are restricted to this list: 5950 5951 GCRY_CIPHER_3DES 5952 3 key EDE Triple-DES symmetric encryption. 5953 GCRY_CIPHER_AES128 5954 AES 128 bit symmetric encryption. 5955 GCRY_CIPHER_AES192 5956 AES 192 bit symmetric encryption. 5957 GCRY_CIPHER_AES256 5958 AES 256 bit symmetric encryption. 5959 GCRY_MD_SHA1 5960 SHA-1 message digest. 5961 GCRY_MD_SHA224 5962 SHA-224 message digest. 5963 GCRY_MD_SHA256 5964 SHA-256 message digest. 5965 GCRY_MD_SHA384 5966 SHA-384 message digest. 5967 GCRY_MD_SHA512 5968 SHA-512 message digest. 5969 GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC 5970 HMAC using a SHA-1 message digest. 5971 GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC 5972 HMAC using a SHA-224 message digest. 5973 GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC 5974 HMAC using a SHA-256 message digest. 5975 GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC 5976 HMAC using a SHA-384 message digest. 5977 GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC 5978 HMAC using a SHA-512 message digest. 5979 GCRY_PK_RSA 5980 RSA encryption and signing. 5981 GCRY_PK_DSA 5982 DSA signing. 5983 5984 Note that the CRC algorithms are not considered cryptographic 5985 algorithms and thus are in addition available. 5986 5987 * RSA key generation refuses to create a key with a keysize of less 5988 than 1024 bits. 5989 5990 * DSA key generation refuses to create a key with a keysize other 5991 than 1024 bits. 5992 5993 * The 'transient-key' flag for RSA and DSA key generation is ignored. 5994 5995 * Support for the VIA Padlock engine is disabled. 5996 5997 * FIPS mode may only be used on systems with a /dev/random device. 5998 Switching into FIPS mode on other systems will fail at runtime. 5999 6000 * Saving and loading a random seed file is ignored. 6001 6002 * An X9.31 style random number generator is used in place of the 6003 large-pool-CSPRNG generator. 6004 6005 * The command 'GCRYCTL_ENABLE_QUICK_RANDOM' is ignored. 6006 6007 * Message digest debugging is disabled. 6008 6009 * All debug output related to cryptographic data is suppressed. 6010 6011 * On-the-fly self-tests are not performed, instead self-tests are run 6012 before entering operational state. 6013 6014 * The function 'gcry_set_allocation_handler' may not be used. If it 6015 is used Libgcrypt disables FIPS mode unless Enforced FIPS mode is 6016 enabled, in which case Libgcrypt will enter the error state. 6017 6018 * The digest algorithm MD5 may not be used. If it is used Libgcrypt 6019 disables FIPS mode unless Enforced FIPS mode is enabled, in which 6020 case Libgcrypt will enter the error state. 6021 6022 * In Enforced FIPS mode the command 'GCRYCTL_DISABLE_SECMEM' is 6023 ignored. In standard FIPS mode it disables FIPS mode. 6024 6025 * A handler set by 'gcry_set_outofcore_handler' is ignored. 6026 * A handler set by 'gcry_set_fatalerror_handler' is ignored. 6027 6028 Note that when we speak about disabling FIPS mode, it merely means 6029that the function 'gcry_fips_mode_active' returns false; it does not 6030mean that any non FIPS algorithms are allowed. 6031 6032B.2 FIPS Finite State Machine 6033============================= 6034 6035The FIPS mode of libgcrypt implements a finite state machine (FSM) using 60368 states (*note Table B.1: tbl:fips-states.) and checks at runtime that 6037only valid transitions (*note Table B.2: tbl:fips-state-transitions.) 6038may happen. 6039 6040 �[image src="fips-fsm.png" alt="FIPS FSM Diagram"�] 6041 6042Figure B.1: FIPS mode state diagram 6043 6044States used by the FIPS FSM: 6045 6046Power-Off 6047 Libgcrypt is not runtime linked to another application. This 6048 usually means that the library is not loaded into main memory. 6049 This state is documentation only. 6050 6051Power-On 6052 Libgcrypt is loaded into memory and API calls may be made. 6053 Compiler introduced constructor functions may be run. Note that 6054 Libgcrypt does not implement any arbitrary constructor functions to 6055 be called by the operating system 6056 6057Init 6058 The Libgcrypt initialization functions are performed and the 6059 library has not yet run any self-test. 6060 6061Self-Test 6062 Libgcrypt is performing self-tests. 6063 6064Operational 6065 Libgcrypt is in the operational state and all interfaces may be 6066 used. 6067 6068Error 6069 Libgrypt is in the error state. When calling any FIPS relevant 6070 interfaces they either return an error ('GPG_ERR_NOT_OPERATIONAL') 6071 or put Libgcrypt into the Fatal-Error state and won't return. 6072 6073Fatal-Error 6074 Libgcrypt is in a non-recoverable error state and will 6075 automatically transit into the Shutdown state. 6076 6077Shutdown 6078 Libgcrypt is about to be terminated and removed from the memory. 6079 The application may at this point still running cleanup handlers. 6080 6081Table B.1: FIPS mode states 6082 6083The valid state transitions (*note Figure B.1: fig:fips-fsm.) are: 6084'1' 6085 Power-Off to Power-On is implicitly done by the OS loading 6086 Libgcrypt as a shared library and having it linked to an 6087 application. 6088 6089'2' 6090 Power-On to Init is triggered by the application calling the 6091 Libgcrypt initialization function 'gcry_check_version'. 6092 6093'3' 6094 Init to Self-Test is either triggered by a dedicated API call or 6095 implicit by invoking a libgrypt service controlled by the FSM. 6096 6097'4' 6098 Self-Test to Operational is triggered after all self-tests passed 6099 successfully. 6100 6101'5' 6102 Operational to Shutdown is an artificial state without any direct 6103 action in Libgcrypt. When reaching the Shutdown state the library 6104 is deinitialized and can't return to any other state again. 6105 6106'6' 6107 Shutdown to Power-off is the process of removing Libgcrypt from the 6108 computer's memory. For obvious reasons the Power-Off state can't 6109 be represented within Libgcrypt and thus this transition is for 6110 documentation only. 6111 6112'7' 6113 Operational to Error is triggered if Libgcrypt detected an 6114 application error which can't be returned to the caller but still 6115 allows Libgcrypt to properly run. In the Error state all FIPS 6116 relevant interfaces return an error code. 6117 6118'8' 6119 Error to Shutdown is similar to the Operational to Shutdown 6120 transition (5). 6121 6122'9' 6123 Error to Fatal-Error is triggered if Libgrypt detects an fatal 6124 error while already being in Error state. 6125 6126'10' 6127 Fatal-Error to Shutdown is automatically entered by Libgcrypt after 6128 having reported the error. 6129 6130'11' 6131 Power-On to Shutdown is an artificial state to document that 6132 Libgcrypt has not ye been initialized but the process is about to 6133 terminate. 6134 6135'12' 6136 Power-On to Fatal-Error will be triggered if certain Libgcrypt 6137 functions are used without having reached the Init state. 6138 6139'13' 6140 Self-Test to Fatal-Error is triggered by severe errors in Libgcrypt 6141 while running self-tests. 6142 6143'14' 6144 Self-Test to Error is triggered by a failed self-test. 6145 6146'15' 6147 Operational to Fatal-Error is triggered if Libcrypt encountered a 6148 non-recoverable error. 6149 6150'16' 6151 Operational to Self-Test is triggered if the application requested 6152 to run the self-tests again. 6153 6154'17' 6155 Error to Self-Test is triggered if the application has requested to 6156 run self-tests to get to get back into operational state after an 6157 error. 6158 6159'18' 6160 Init to Error is triggered by errors in the initialization code. 6161 6162'19' 6163 Init to Fatal-Error is triggered by non-recoverable errors in the 6164 initialization code. 6165 6166'20' 6167 Error to Error is triggered by errors while already in the Error 6168 state. 6169 6170Table B.2: FIPS mode state transitions 6171 6172B.3 FIPS Miscellaneous Information 6173================================== 6174 6175Libgcrypt does not do any key management on itself; the application 6176needs to care about it. Keys which are passed to Libgcrypt should be 6177allocated in secure memory as available with the functions 6178'gcry_malloc_secure' and 'gcry_calloc_secure'. By calling 'gcry_free' 6179on this memory, the memory and thus the keys are overwritten with zero 6180bytes before releasing the memory. 6181 6182 For use with the random number generator, Libgcrypt generates 3 6183internal keys which are stored in the encryption contexts used by the 6184RNG. These keys are stored in secure memory for the lifetime of the 6185process. Application are required to use 'GCRYCTL_TERM_SECMEM' before 6186process termination. This will zero out the entire secure memory and 6187thus also the encryption contexts with these keys. 6188 6189 6190File: gcrypt.info, Node: Library Copying, Next: Copying, Prev: FIPS Mode, Up: Top 6191 6192GNU Lesser General Public License 6193********************************* 6194 6195 Version 2.1, February 1999 6196 6197 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 6198 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 6199 6200 Everyone is permitted to copy and distribute verbatim copies 6201 of this license document, but changing it is not allowed. 6202 6203 [This is the first released version of the Lesser GPL. It also counts 6204 as the successor of the GNU Library Public License, version 2, hence the 6205 version number 2.1.] 6206 6207Preamble 6208======== 6209 6210The licenses for most software are designed to take away your freedom to 6211share and change it. By contrast, the GNU General Public Licenses are 6212intended to guarantee your freedom to share and change free software--to 6213make sure the software is free for all its users. 6214 6215 This license, the Lesser General Public License, applies to some 6216specially designated software--typically libraries--of the Free Software 6217Foundation and other authors who decide to use it. You can use it too, 6218but we suggest you first think carefully about whether this license or 6219the ordinary General Public License is the better strategy to use in any 6220particular case, based on the explanations below. 6221 6222 When we speak of free software, we are referring to freedom of use, 6223not price. Our General Public Licenses are designed to make sure that 6224you have the freedom to distribute copies of free software (and charge 6225for this service if you wish); that you receive source code or can get 6226it if you want it; that you can change the software and use pieces of it 6227in new free programs; and that you are informed that you can do these 6228things. 6229 6230 To protect your rights, we need to make restrictions that forbid 6231distributors to deny you these rights or to ask you to surrender these 6232rights. These restrictions translate to certain responsibilities for 6233you if you distribute copies of the library or if you modify it. 6234 6235 For example, if you distribute copies of the library, whether gratis 6236or for a fee, you must give the recipients all the rights that we gave 6237you. You must make sure that they, too, receive or can get the source 6238code. If you link other code with the library, you must provide 6239complete object files to the recipients, so that they can relink them 6240with the library after making changes to the library and recompiling it. 6241And you must show them these terms so they know their rights. 6242 6243 We protect your rights with a two-step method: (1) we copyright the 6244library, and (2) we offer you this license, which gives you legal 6245permission to copy, distribute and/or modify the library. 6246 6247 To protect each distributor, we want to make it very clear that there 6248is no warranty for the free library. Also, if the library is modified 6249by someone else and passed on, the recipients should know that what they 6250have is not the original version, so that the original author's 6251reputation will not be affected by problems that might be introduced by 6252others. 6253 6254 Finally, software patents pose a constant threat to the existence of 6255any free program. We wish to make sure that a company cannot 6256effectively restrict the users of a free program by obtaining a 6257restrictive license from a patent holder. Therefore, we insist that any 6258patent license obtained for a version of the library must be consistent 6259with the full freedom of use specified in this license. 6260 6261 Most GNU software, including some libraries, is covered by the 6262ordinary GNU General Public License. This license, the GNU Lesser 6263General Public License, applies to certain designated libraries, and is 6264quite different from the ordinary General Public License. We use this 6265license for certain libraries in order to permit linking those libraries 6266into non-free programs. 6267 6268 When a program is linked with a library, whether statically or using 6269a shared library, the combination of the two is legally speaking a 6270combined work, a derivative of the original library. The ordinary 6271General Public License therefore permits such linking only if the entire 6272combination fits its criteria of freedom. The Lesser General Public 6273License permits more lax criteria for linking other code with the 6274library. 6275 6276 We call this license the "Lesser" General Public License because it 6277does _Less_ to protect the user's freedom than the ordinary General 6278Public License. It also provides other free software developers Less of 6279an advantage over competing non-free programs. These disadvantages are 6280the reason we use the ordinary General Public License for many 6281libraries. However, the Lesser license provides advantages in certain 6282special circumstances. 6283 6284 For example, on rare occasions, there may be a special need to 6285encourage the widest possible use of a certain library, so that it 6286becomes a de-facto standard. To achieve this, non-free programs must be 6287allowed to use the library. A more frequent case is that a free library 6288does the same job as widely used non-free libraries. In this case, 6289there is little to gain by limiting the free library to free software 6290only, so we use the Lesser General Public License. 6291 6292 In other cases, permission to use a particular library in non-free 6293programs enables a greater number of people to use a large body of free 6294software. For example, permission to use the GNU C Library in non-free 6295programs enables many more people to use the whole GNU operating system, 6296as well as its variant, the GNU/Linux operating system. 6297 6298 Although the Lesser General Public License is Less protective of the 6299users' freedom, it does ensure that the user of a program that is linked 6300with the Library has the freedom and the wherewithal to run that program 6301using a modified version of the Library. 6302 6303 The precise terms and conditions for copying, distribution and 6304modification follow. Pay close attention to the difference between a 6305"work based on the library" and a "work that uses the library". The 6306former contains code derived from the library, whereas the latter must 6307be combined with the library in order to run. 6308 6309 GNU LESSER GENERAL PUBLIC LICENSE 6310 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 6311 6312 0. This License Agreement applies to any software library or other 6313 program which contains a notice placed by the copyright holder or 6314 other authorized party saying it may be distributed under the terms 6315 of this Lesser General Public License (also called "this License"). 6316 Each licensee is addressed as "you". 6317 6318 A "library" means a collection of software functions and/or data 6319 prepared so as to be conveniently linked with application programs 6320 (which use some of those functions and data) to form executables. 6321 6322 The "Library", below, refers to any such software library or work 6323 which has been distributed under these terms. A "work based on the 6324 Library" means either the Library or any derivative work under 6325 copyright law: that is to say, a work containing the Library or a 6326 portion of it, either verbatim or with modifications and/or 6327 translated straightforwardly into another language. (Hereinafter, 6328 translation is included without limitation in the term 6329 "modification".) 6330 6331 "Source code" for a work means the preferred form of the work for 6332 making modifications to it. For a library, complete source code 6333 means all the source code for all modules it contains, plus any 6334 associated interface definition files, plus the scripts used to 6335 control compilation and installation of the library. 6336 6337 Activities other than copying, distribution and modification are 6338 not covered by this License; they are outside its scope. The act 6339 of running a program using the Library is not restricted, and 6340 output from such a program is covered only if its contents 6341 constitute a work based on the Library (independent of the use of 6342 the Library in a tool for writing it). Whether that is true 6343 depends on what the Library does and what the program that uses the 6344 Library does. 6345 6346 1. You may copy and distribute verbatim copies of the Library's 6347 complete source code as you receive it, in any medium, provided 6348 that you conspicuously and appropriately publish on each copy an 6349 appropriate copyright notice and disclaimer of warranty; keep 6350 intact all the notices that refer to this License and to the 6351 absence of any warranty; and distribute a copy of this License 6352 along with the Library. 6353 6354 You may charge a fee for the physical act of transferring a copy, 6355 and you may at your option offer warranty protection in exchange 6356 for a fee. 6357 6358 2. You may modify your copy or copies of the Library or any portion of 6359 it, thus forming a work based on the Library, and copy and 6360 distribute such modifications or work under the terms of Section 1 6361 above, provided that you also meet all of these conditions: 6362 6363 a. The modified work must itself be a software library. 6364 6365 b. You must cause the files modified to carry prominent notices 6366 stating that you changed the files and the date of any change. 6367 6368 c. You must cause the whole of the work to be licensed at no 6369 charge to all third parties under the terms of this License. 6370 6371 d. If a facility in the modified Library refers to a function or 6372 a table of data to be supplied by an application program that 6373 uses the facility, other than as an argument passed when the 6374 facility is invoked, then you must make a good faith effort to 6375 ensure that, in the event an application does not supply such 6376 function or table, the facility still operates, and performs 6377 whatever part of its purpose remains meaningful. 6378 6379 (For example, a function in a library to compute square roots 6380 has a purpose that is entirely well-defined independent of the 6381 application. Therefore, Subsection 2d requires that any 6382 application-supplied function or table used by this function 6383 must be optional: if the application does not supply it, the 6384 square root function must still compute square roots.) 6385 6386 These requirements apply to the modified work as a whole. If 6387 identifiable sections of that work are not derived from the 6388 Library, and can be reasonably considered independent and separate 6389 works in themselves, then this License, and its terms, do not apply 6390 to those sections when you distribute them as separate works. But 6391 when you distribute the same sections as part of a whole which is a 6392 work based on the Library, the distribution of the whole must be on 6393 the terms of this License, whose permissions for other licensees 6394 extend to the entire whole, and thus to each and every part 6395 regardless of who wrote it. 6396 6397 Thus, it is not the intent of this section to claim rights or 6398 contest your rights to work written entirely by you; rather, the 6399 intent is to exercise the right to control the distribution of 6400 derivative or collective works based on the Library. 6401 6402 In addition, mere aggregation of another work not based on the 6403 Library with the Library (or with a work based on the Library) on a 6404 volume of a storage or distribution medium does not bring the other 6405 work under the scope of this License. 6406 6407 3. You may opt to apply the terms of the ordinary GNU General Public 6408 License instead of this License to a given copy of the Library. To 6409 do this, you must alter all the notices that refer to this License, 6410 so that they refer to the ordinary GNU General Public License, 6411 version 2, instead of to this License. (If a newer version than 6412 version 2 of the ordinary GNU General Public License has appeared, 6413 then you can specify that version instead if you wish.) Do not 6414 make any other change in these notices. 6415 6416 Once this change is made in a given copy, it is irreversible for 6417 that copy, so the ordinary GNU General Public License applies to 6418 all subsequent copies and derivative works made from that copy. 6419 6420 This option is useful when you wish to copy part of the code of the 6421 Library into a program that is not a library. 6422 6423 4. You may copy and distribute the Library (or a portion or derivative 6424 of it, under Section 2) in object code or executable form under the 6425 terms of Sections 1 and 2 above provided that you accompany it with 6426 the complete corresponding machine-readable source code, which must 6427 be distributed under the terms of Sections 1 and 2 above on a 6428 medium customarily used for software interchange. 6429 6430 If distribution of object code is made by offering access to copy 6431 from a designated place, then offering equivalent access to copy 6432 the source code from the same place satisfies the requirement to 6433 distribute the source code, even though third parties are not 6434 compelled to copy the source along with the object code. 6435 6436 5. A program that contains no derivative of any portion of the 6437 Library, but is designed to work with the Library by being compiled 6438 or linked with it, is called a "work that uses the Library". Such 6439 a work, in isolation, is not a derivative work of the Library, and 6440 therefore falls outside the scope of this License. 6441 6442 However, linking a "work that uses the Library" with the Library 6443 creates an executable that is a derivative of the Library (because 6444 it contains portions of the Library), rather than a "work that uses 6445 the library". The executable is therefore covered by this License. 6446 Section 6 states terms for distribution of such executables. 6447 6448 When a "work that uses the Library" uses material from a header 6449 file that is part of the Library, the object code for the work may 6450 be a derivative work of the Library even though the source code is 6451 not. Whether this is true is especially significant if the work 6452 can be linked without the Library, or if the work is itself a 6453 library. The threshold for this to be true is not precisely 6454 defined by law. 6455 6456 If such an object file uses only numerical parameters, data 6457 structure layouts and accessors, and small macros and small inline 6458 functions (ten lines or less in length), then the use of the object 6459 file is unrestricted, regardless of whether it is legally a 6460 derivative work. (Executables containing this object code plus 6461 portions of the Library will still fall under Section 6.) 6462 6463 Otherwise, if the work is a derivative of the Library, you may 6464 distribute the object code for the work under the terms of Section 6465 6. Any executables containing that work also fall under Section 6, 6466 whether or not they are linked directly with the Library itself. 6467 6468 6. As an exception to the Sections above, you may also combine or link 6469 a "work that uses the Library" with the Library to produce a work 6470 containing portions of the Library, and distribute that work under 6471 terms of your choice, provided that the terms permit modification 6472 of the work for the customer's own use and reverse engineering for 6473 debugging such modifications. 6474 6475 You must give prominent notice with each copy of the work that the 6476 Library is used in it and that the Library and its use are covered 6477 by this License. You must supply a copy of this License. If the 6478 work during execution displays copyright notices, you must include 6479 the copyright notice for the Library among them, as well as a 6480 reference directing the user to the copy of this License. Also, 6481 you must do one of these things: 6482 6483 a. Accompany the work with the complete corresponding 6484 machine-readable source code for the Library including 6485 whatever changes were used in the work (which must be 6486 distributed under Sections 1 and 2 above); and, if the work is 6487 an executable linked with the Library, with the complete 6488 machine-readable "work that uses the Library", as object code 6489 and/or source code, so that the user can modify the Library 6490 and then relink to produce a modified executable containing 6491 the modified Library. (It is understood that the user who 6492 changes the contents of definitions files in the Library will 6493 not necessarily be able to recompile the application to use 6494 the modified definitions.) 6495 6496 b. Use a suitable shared library mechanism for linking with the 6497 Library. A suitable mechanism is one that (1) uses at run 6498 time a copy of the library already present on the user's 6499 computer system, rather than copying library functions into 6500 the executable, and (2) will operate properly with a modified 6501 version of the library, if the user installs one, as long as 6502 the modified version is interface-compatible with the version 6503 that the work was made with. 6504 6505 c. Accompany the work with a written offer, valid for at least 6506 three years, to give the same user the materials specified in 6507 Subsection 6a, above, for a charge no more than the cost of 6508 performing this distribution. 6509 6510 d. If distribution of the work is made by offering access to copy 6511 from a designated place, offer equivalent access to copy the 6512 above specified materials from the same place. 6513 6514 e. Verify that the user has already received a copy of these 6515 materials or that you have already sent this user a copy. 6516 6517 For an executable, the required form of the "work that uses the 6518 Library" must include any data and utility programs needed for 6519 reproducing the executable from it. However, as a special 6520 exception, the materials to be distributed need not include 6521 anything that is normally distributed (in either source or binary 6522 form) with the major components (compiler, kernel, and so on) of 6523 the operating system on which the executable runs, unless that 6524 component itself accompanies the executable. 6525 6526 It may happen that this requirement contradicts the license 6527 restrictions of other proprietary libraries that do not normally 6528 accompany the operating system. Such a contradiction means you 6529 cannot use both them and the Library together in an executable that 6530 you distribute. 6531 6532 7. You may place library facilities that are a work based on the 6533 Library side-by-side in a single library together with other 6534 library facilities not covered by this License, and distribute such 6535 a combined library, provided that the separate distribution of the 6536 work based on the Library and of the other library facilities is 6537 otherwise permitted, and provided that you do these two things: 6538 6539 a. Accompany the combined library with a copy of the same work 6540 based on the Library, uncombined with any other library 6541 facilities. This must be distributed under the terms of the 6542 Sections above. 6543 6544 b. Give prominent notice with the combined library of the fact 6545 that part of it is a work based on the Library, and explaining 6546 where to find the accompanying uncombined form of the same 6547 work. 6548 6549 8. You may not copy, modify, sublicense, link with, or distribute the 6550 Library except as expressly provided under this License. Any 6551 attempt otherwise to copy, modify, sublicense, link with, or 6552 distribute the Library is void, and will automatically terminate 6553 your rights under this License. However, parties who have received 6554 copies, or rights, from you under this License will not have their 6555 licenses terminated so long as such parties remain in full 6556 compliance. 6557 6558 9. You are not required to accept this License, since you have not 6559 signed it. However, nothing else grants you permission to modify 6560 or distribute the Library or its derivative works. These actions 6561 are prohibited by law if you do not accept this License. 6562 Therefore, by modifying or distributing the Library (or any work 6563 based on the Library), you indicate your acceptance of this License 6564 to do so, and all its terms and conditions for copying, 6565 distributing or modifying the Library or works based on it. 6566 6567 10. Each time you redistribute the Library (or any work based on the 6568 Library), the recipient automatically receives a license from the 6569 original licensor to copy, distribute, link with or modify the 6570 Library subject to these terms and conditions. You may not impose 6571 any further restrictions on the recipients' exercise of the rights 6572 granted herein. You are not responsible for enforcing compliance 6573 by third parties with this License. 6574 6575 11. If, as a consequence of a court judgment or allegation of patent 6576 infringement or for any other reason (not limited to patent 6577 issues), conditions are imposed on you (whether by court order, 6578 agreement or otherwise) that contradict the conditions of this 6579 License, they do not excuse you from the conditions of this 6580 License. If you cannot distribute so as to satisfy simultaneously 6581 your obligations under this License and any other pertinent 6582 obligations, then as a consequence you may not distribute the 6583 Library at all. For example, if a patent license would not permit 6584 royalty-free redistribution of the Library by all those who receive 6585 copies directly or indirectly through you, then the only way you 6586 could satisfy both it and this License would be to refrain entirely 6587 from distribution of the Library. 6588 6589 If any portion of this section is held invalid or unenforceable 6590 under any particular circumstance, the balance of the section is 6591 intended to apply, and the section as a whole is intended to apply 6592 in other circumstances. 6593 6594 It is not the purpose of this section to induce you to infringe any 6595 patents or other property right claims or to contest validity of 6596 any such claims; this section has the sole purpose of protecting 6597 the integrity of the free software distribution system which is 6598 implemented by public license practices. Many people have made 6599 generous contributions to the wide range of software distributed 6600 through that system in reliance on consistent application of that 6601 system; it is up to the author/donor to decide if he or she is 6602 willing to distribute software through any other system and a 6603 licensee cannot impose that choice. 6604 6605 This section is intended to make thoroughly clear what is believed 6606 to be a consequence of the rest of this License. 6607 6608 12. If the distribution and/or use of the Library is restricted in 6609 certain countries either by patents or by copyrighted interfaces, 6610 the original copyright holder who places the Library under this 6611 License may add an explicit geographical distribution limitation 6612 excluding those countries, so that distribution is permitted only 6613 in or among countries not thus excluded. In such case, this 6614 License incorporates the limitation as if written in the body of 6615 this License. 6616 6617 13. The Free Software Foundation may publish revised and/or new 6618 versions of the Lesser General Public License from time to time. 6619 Such new versions will be similar in spirit to the present version, 6620 but may differ in detail to address new problems or concerns. 6621 6622 Each version is given a distinguishing version number. If the 6623 Library specifies a version number of this License which applies to 6624 it and "any later version", you have the option of following the 6625 terms and conditions either of that version or of any later version 6626 published by the Free Software Foundation. If the Library does not 6627 specify a license version number, you may choose any version ever 6628 published by the Free Software Foundation. 6629 6630 14. If you wish to incorporate parts of the Library into other free 6631 programs whose distribution conditions are incompatible with these, 6632 write to the author to ask for permission. For software which is 6633 copyrighted by the Free Software Foundation, write to the Free 6634 Software Foundation; we sometimes make exceptions for this. Our 6635 decision will be guided by the two goals of preserving the free 6636 status of all derivatives of our free software and of promoting the 6637 sharing and reuse of software generally. 6638 6639 NO WARRANTY 6640 6641 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO 6642 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE 6643 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS 6644 AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY 6645 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT 6646 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 6647 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 6648 PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE 6649 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR 6650 OR CORRECTION. 6651 6652 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 6653 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 6654 MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE 6655 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 6656 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 6657 INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF 6658 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 6659 OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY 6660 OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 6661 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 6662 6663 END OF TERMS AND CONDITIONS 6664 6665How to Apply These Terms to Your New Libraries 6666============================================== 6667 6668If you develop a new library, and you want it to be of the greatest 6669possible use to the public, we recommend making it free software that 6670everyone can redistribute and change. You can do so by permitting 6671redistribution under these terms (or, alternatively, under the terms of 6672the ordinary General Public License). 6673 6674 To apply these terms, attach the following notices to the library. 6675It is safest to attach them to the start of each source file to most 6676effectively convey the exclusion of warranty; and each file should have 6677at least the "copyright" line and a pointer to where the full notice is 6678found. 6679 6680 ONE LINE TO GIVE THE LIBRARY'S NAME AND AN IDEA OF WHAT IT DOES. 6681 Copyright (C) YEAR NAME OF AUTHOR 6682 6683 This library is free software; you can redistribute it and/or modify it 6684 under the terms of the GNU Lesser General Public License as published by 6685 the Free Software Foundation; either version 2.1 of the License, or (at 6686 your option) any later version. 6687 6688 This library is distributed in the hope that it will be useful, but 6689 WITHOUT ANY WARRANTY; without even the implied warranty of 6690 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 6691 Lesser General Public License for more details. 6692 6693 You should have received a copy of the GNU Lesser General Public 6694 License along with this library; if not, write to the Free Software 6695 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, 6696 USA. 6697 6698 Also add information on how to contact you by electronic and paper 6699mail. 6700 6701 You should also get your employer (if you work as a programmer) or 6702your school, if any, to sign a "copyright disclaimer" for the library, 6703if necessary. Here is a sample; alter the names: 6704 6705 Yoyodyne, Inc., hereby disclaims all copyright interest in the library 6706 `Frob' (a library for tweaking knobs) written by James Random Hacker. 6707 6708 SIGNATURE OF TY COON, 1 April 1990 6709 Ty Coon, President of Vice 6710 6711 That's all there is to it! 6712 6713 6714File: gcrypt.info, Node: Copying, Next: Figures and Tables, Prev: Library Copying, Up: Top 6715 6716GNU General Public License 6717************************** 6718 6719 Version 2, June 1991 6720 6721 Copyright (C) 1989, 1991 Free Software Foundation, Inc. 6722 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 6723 6724 Everyone is permitted to copy and distribute verbatim copies 6725 of this license document, but changing it is not allowed. 6726 6727Preamble 6728======== 6729 6730The licenses for most software are designed to take away your freedom to 6731share and change it. By contrast, the GNU General Public License is 6732intended to guarantee your freedom to share and change free software--to 6733make sure the software is free for all its users. This General Public 6734License applies to most of the Free Software Foundation's software and 6735to any other program whose authors commit to using it. (Some other Free 6736Software Foundation software is covered by the GNU Library General 6737Public License instead.) You can apply it to your programs, too. 6738 6739 When we speak of free software, we are referring to freedom, not 6740price. Our General Public Licenses are designed to make sure that you 6741have the freedom to distribute copies of free software (and charge for 6742this service if you wish), that you receive source code or can get it if 6743you want it, that you can change the software or use pieces of it in new 6744free programs; and that you know you can do these things. 6745 6746 To protect your rights, we need to make restrictions that forbid 6747anyone to deny you these rights or to ask you to surrender the rights. 6748These restrictions translate to certain responsibilities for you if you 6749distribute copies of the software, or if you modify it. 6750 6751 For example, if you distribute copies of such a program, whether 6752gratis or for a fee, you must give the recipients all the rights that 6753you have. You must make sure that they, too, receive or can get the 6754source code. And you must show them these terms so they know their 6755rights. 6756 6757 We protect your rights with two steps: (1) copyright the software, 6758and (2) offer you this license which gives you legal permission to copy, 6759distribute and/or modify the software. 6760 6761 Also, for each author's protection and ours, we want to make certain 6762that everyone understands that there is no warranty for this free 6763software. If the software is modified by someone else and passed on, we 6764want its recipients to know that what they have is not the original, so 6765that any problems introduced by others will not reflect on the original 6766authors' reputations. 6767 6768 Finally, any free program is threatened constantly by software 6769patents. We wish to avoid the danger that redistributors of a free 6770program will individually obtain patent licenses, in effect making the 6771program proprietary. To prevent this, we have made it clear that any 6772patent must be licensed for everyone's free use or not licensed at all. 6773 6774 The precise terms and conditions for copying, distribution and 6775modification follow. 6776 6777 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 6778 6779 1. This License applies to any program or other work which contains a 6780 notice placed by the copyright holder saying it may be distributed 6781 under the terms of this General Public License. The "Program", 6782 below, refers to any such program or work, and a "work based on the 6783 Program" means either the Program or any derivative work under 6784 copyright law: that is to say, a work containing the Program or a 6785 portion of it, either verbatim or with modifications and/or 6786 translated into another language. (Hereinafter, translation is 6787 included without limitation in the term "modification".) Each 6788 licensee is addressed as "you". 6789 6790 Activities other than copying, distribution and modification are 6791 not covered by this License; they are outside its scope. The act 6792 of running the Program is not restricted, and the output from the 6793 Program is covered only if its contents constitute a work based on 6794 the Program (independent of having been made by running the 6795 Program). Whether that is true depends on what the Program does. 6796 6797 2. You may copy and distribute verbatim copies of the Program's source 6798 code as you receive it, in any medium, provided that you 6799 conspicuously and appropriately publish on each copy an appropriate 6800 copyright notice and disclaimer of warranty; keep intact all the 6801 notices that refer to this License and to the absence of any 6802 warranty; and give any other recipients of the Program a copy of 6803 this License along with the Program. 6804 6805 You may charge a fee for the physical act of transferring a copy, 6806 and you may at your option offer warranty protection in exchange 6807 for a fee. 6808 6809 3. You may modify your copy or copies of the Program or any portion of 6810 it, thus forming a work based on the Program, and copy and 6811 distribute such modifications or work under the terms of Section 1 6812 above, provided that you also meet all of these conditions: 6813 6814 a. You must cause the modified files to carry prominent notices 6815 stating that you changed the files and the date of any change. 6816 6817 b. You must cause any work that you distribute or publish, that 6818 in whole or in part contains or is derived from the Program or 6819 any part thereof, to be licensed as a whole at no charge to 6820 all third parties under the terms of this License. 6821 6822 c. If the modified program normally reads commands interactively 6823 when run, you must cause it, when started running for such 6824 interactive use in the most ordinary way, to print or display 6825 an announcement including an appropriate copyright notice and 6826 a notice that there is no warranty (or else, saying that you 6827 provide a warranty) and that users may redistribute the 6828 program under these conditions, and telling the user how to 6829 view a copy of this License. (Exception: if the Program 6830 itself is interactive but does not normally print such an 6831 announcement, your work based on the Program is not required 6832 to print an announcement.) 6833 6834 These requirements apply to the modified work as a whole. If 6835 identifiable sections of that work are not derived from the 6836 Program, and can be reasonably considered independent and separate 6837 works in themselves, then this License, and its terms, do not apply 6838 to those sections when you distribute them as separate works. But 6839 when you distribute the same sections as part of a whole which is a 6840 work based on the Program, the distribution of the whole must be on 6841 the terms of this License, whose permissions for other licensees 6842 extend to the entire whole, and thus to each and every part 6843 regardless of who wrote it. 6844 6845 Thus, it is not the intent of this section to claim rights or 6846 contest your rights to work written entirely by you; rather, the 6847 intent is to exercise the right to control the distribution of 6848 derivative or collective works based on the Program. 6849 6850 In addition, mere aggregation of another work not based on the 6851 Program with the Program (or with a work based on the Program) on a 6852 volume of a storage or distribution medium does not bring the other 6853 work under the scope of this License. 6854 6855 4. You may copy and distribute the Program (or a work based on it, 6856 under Section 2) in object code or executable form under the terms 6857 of Sections 1 and 2 above provided that you also do one of the 6858 following: 6859 6860 a. Accompany it with the complete corresponding machine-readable 6861 source code, which must be distributed under the terms of 6862 Sections 1 and 2 above on a medium customarily used for 6863 software interchange; or, 6864 6865 b. Accompany it with a written offer, valid for at least three 6866 years, to give any third party, for a charge no more than your 6867 cost of physically performing source distribution, a complete 6868 machine-readable copy of the corresponding source code, to be 6869 distributed under the terms of Sections 1 and 2 above on a 6870 medium customarily used for software interchange; or, 6871 6872 c. Accompany it with the information you received as to the offer 6873 to distribute corresponding source code. (This alternative is 6874 allowed only for noncommercial distribution and only if you 6875 received the program in object code or executable form with 6876 such an offer, in accord with Subsection b above.) 6877 6878 The source code for a work means the preferred form of the work for 6879 making modifications to it. For an executable work, complete 6880 source code means all the source code for all modules it contains, 6881 plus any associated interface definition files, plus the scripts 6882 used to control compilation and installation of the executable. 6883 However, as a special exception, the source code distributed need 6884 not include anything that is normally distributed (in either source 6885 or binary form) with the major components (compiler, kernel, and so 6886 on) of the operating system on which the executable runs, unless 6887 that component itself accompanies the executable. 6888 6889 If distribution of executable or object code is made by offering 6890 access to copy from a designated place, then offering equivalent 6891 access to copy the source code from the same place counts as 6892 distribution of the source code, even though third parties are not 6893 compelled to copy the source along with the object code. 6894 6895 5. You may not copy, modify, sublicense, or distribute the Program 6896 except as expressly provided under this License. Any attempt 6897 otherwise to copy, modify, sublicense or distribute the Program is 6898 void, and will automatically terminate your rights under this 6899 License. However, parties who have received copies, or rights, 6900 from you under this License will not have their licenses terminated 6901 so long as such parties remain in full compliance. 6902 6903 6. You are not required to accept this License, since you have not 6904 signed it. However, nothing else grants you permission to modify 6905 or distribute the Program or its derivative works. These actions 6906 are prohibited by law if you do not accept this License. 6907 Therefore, by modifying or distributing the Program (or any work 6908 based on the Program), you indicate your acceptance of this License 6909 to do so, and all its terms and conditions for copying, 6910 distributing or modifying the Program or works based on it. 6911 6912 7. Each time you redistribute the Program (or any work based on the 6913 Program), the recipient automatically receives a license from the 6914 original licensor to copy, distribute or modify the Program subject 6915 to these terms and conditions. You may not impose any further 6916 restrictions on the recipients' exercise of the rights granted 6917 herein. You are not responsible for enforcing compliance by third 6918 parties to this License. 6919 6920 8. If, as a consequence of a court judgment or allegation of patent 6921 infringement or for any other reason (not limited to patent 6922 issues), conditions are imposed on you (whether by court order, 6923 agreement or otherwise) that contradict the conditions of this 6924 License, they do not excuse you from the conditions of this 6925 License. If you cannot distribute so as to satisfy simultaneously 6926 your obligations under this License and any other pertinent 6927 obligations, then as a consequence you may not distribute the 6928 Program at all. For example, if a patent license would not permit 6929 royalty-free redistribution of the Program by all those who receive 6930 copies directly or indirectly through you, then the only way you 6931 could satisfy both it and this License would be to refrain entirely 6932 from distribution of the Program. 6933 6934 If any portion of this section is held invalid or unenforceable 6935 under any particular circumstance, the balance of the section is 6936 intended to apply and the section as a whole is intended to apply 6937 in other circumstances. 6938 6939 It is not the purpose of this section to induce you to infringe any 6940 patents or other property right claims or to contest validity of 6941 any such claims; this section has the sole purpose of protecting 6942 the integrity of the free software distribution system, which is 6943 implemented by public license practices. Many people have made 6944 generous contributions to the wide range of software distributed 6945 through that system in reliance on consistent application of that 6946 system; it is up to the author/donor to decide if he or she is 6947 willing to distribute software through any other system and a 6948 licensee cannot impose that choice. 6949 6950 This section is intended to make thoroughly clear what is believed 6951 to be a consequence of the rest of this License. 6952 6953 9. If the distribution and/or use of the Program is restricted in 6954 certain countries either by patents or by copyrighted interfaces, 6955 the original copyright holder who places the Program under this 6956 License may add an explicit geographical distribution limitation 6957 excluding those countries, so that distribution is permitted only 6958 in or among countries not thus excluded. In such case, this 6959 License incorporates the limitation as if written in the body of 6960 this License. 6961 6962 10. The Free Software Foundation may publish revised and/or new 6963 versions of the General Public License from time to time. Such new 6964 versions will be similar in spirit to the present version, but may 6965 differ in detail to address new problems or concerns. 6966 6967 Each version is given a distinguishing version number. If the 6968 Program specifies a version number of this License which applies to 6969 it and "any later version", you have the option of following the 6970 terms and conditions either of that version or of any later version 6971 published by the Free Software Foundation. If the Program does not 6972 specify a version number of this License, you may choose any 6973 version ever published by the Free Software Foundation. 6974 6975 11. If you wish to incorporate parts of the Program into other free 6976 programs whose distribution conditions are different, write to the 6977 author to ask for permission. For software which is copyrighted by 6978 the Free Software Foundation, write to the Free Software 6979 Foundation; we sometimes make exceptions for this. Our decision 6980 will be guided by the two goals of preserving the free status of 6981 all derivatives of our free software and of promoting the sharing 6982 and reuse of software generally. 6983 6984 NO WARRANTY 6985 6986 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO 6987 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE 6988 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS 6989 AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 6990 OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT 6991 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 6992 FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 6993 PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE 6994 DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR 6995 OR CORRECTION. 6996 6997 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN 6998 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY 6999 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE 7000 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 7001 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR 7002 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 7003 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU 7004 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY 7005 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 7006 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 7007 7008 END OF TERMS AND CONDITIONS 7009 7010How to Apply These Terms to Your New Programs 7011============================================= 7012 7013If you develop a new program, and you want it to be of the greatest 7014possible use to the public, the best way to achieve this is to make it 7015free software which everyone can redistribute and change under these 7016terms. 7017 7018 To do so, attach the following notices to the program. It is safest 7019to attach them to the start of each source file to most effectively 7020convey the exclusion of warranty; and each file should have at least the 7021"copyright" line and a pointer to where the full notice is found. 7022 7023 ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES. 7024 Copyright (C) 19YY NAME OF AUTHOR 7025 7026 This program is free software; you can redistribute it and/or 7027 modify it under the terms of the GNU General Public License 7028 as published by the Free Software Foundation; either version 2 7029 of the License, or (at your option) any later version. 7030 7031 This program is distributed in the hope that it will be useful, 7032 but WITHOUT ANY WARRANTY; without even the implied warranty of 7033 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 7034 GNU General Public License for more details. 7035 7036 You should have received a copy of the GNU General Public License along 7037 with this program; if not, write to the Free Software Foundation, Inc., 7038 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. 7039 7040 Also add information on how to contact you by electronic and paper 7041mail. 7042 7043 If the program is interactive, make it output a short notice like 7044this when it starts in an interactive mode: 7045 7046 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR 7047 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details 7048 type `show w'. This is free software, and you are welcome 7049 to redistribute it under certain conditions; type `show c' 7050 for details. 7051 7052 The hypothetical commands 'show w' and 'show c' should show the 7053appropriate parts of the General Public License. Of course, the 7054commands you use may be called something other than 'show w' and 'show 7055c'; they could even be mouse-clicks or menu items--whatever suits your 7056program. 7057 7058 You should also get your employer (if you work as a programmer) or 7059your school, if any, to sign a "copyright disclaimer" for the program, 7060if necessary. Here is a sample; alter the names: 7061 7062 Yoyodyne, Inc., hereby disclaims all copyright 7063 interest in the program `Gnomovision' 7064 (which makes passes at compilers) written 7065 by James Hacker. 7066 7067 SIGNATURE OF TY COON, 1 April 1989 7068 Ty Coon, President of Vice 7069 7070 This General Public License does not permit incorporating your 7071program into proprietary programs. If your program is a subroutine 7072library, you may consider it more useful to permit linking proprietary 7073applications with the library. If this is what you want to do, use the 7074GNU Library General Public License instead of this License. 7075 7076 7077File: gcrypt.info, Node: Figures and Tables, Next: Concept Index, Prev: Copying, Up: Top 7078 7079List of Figures and Tables 7080************************** 7081 7082* Menu: 7083 7084* Figure 17.1: fig:subsystems. Libgcrypt subsystems 7085* Figure B.1: fig:fips-fsm. FIPS mode state diagram 7086 7087* Menu: 7088 7089* Table B.1: tbl:fips-states. FIPS mode states 7090* Table B.2: tbl:fips-state-transitions. FIPS mode state transitions 7091 7092 7093File: gcrypt.info, Node: Concept Index, Next: Function and Data Index, Prev: Figures and Tables, Up: Top 7094 7095Concept Index 7096************* 7097 7098�[index�] 7099* Menu: 7100 7101* /etc/gcrypt/fips_enabled: Configuration. (line 69) 7102* /etc/gcrypt/hwf.deny: Configuration. (line 48) 7103* /etc/gcrypt/random.conf: Configuration. (line 52) 7104* /proc/cpuinfo: Configuration. (line 74) 7105* /proc/self/auxv: Configuration. (line 74) 7106* 3DES: Available ciphers. (line 14) 7107* Advanced Encryption Standard: Available ciphers. (line 35) 7108* AES: Available ciphers. (line 35) 7109* AES-Wrap mode: Available cipher modes. 7110 (line 35) 7111* Arcfour: Available ciphers. (line 52) 7112* BLAKE2b-512, BLAKE2b-384, BLAKE2b-256, BLAKE2b-160: Available hash algorithms. 7113 (line 6) 7114* BLAKE2s-256, BLAKE2s-224, BLAKE2s-160, BLAKE2s-128: Available hash algorithms. 7115 (line 6) 7116* Blowfish: Available ciphers. (line 22) 7117* bug emulation: Working with hash algorithms. 7118 (line 38) 7119* Camellia: Available ciphers. (line 77) 7120* CAST5: Available ciphers. (line 19) 7121* CBC, Cipher Block Chaining mode: Available cipher modes. 7122 (line 23) 7123* CBC-MAC: Working with cipher handles. 7124 (line 56) 7125* CCM, Counter with CBC-MAC mode: Available cipher modes. 7126 (line 48) 7127* CFB, Cipher Feedback mode: Available cipher modes. 7128 (line 17) 7129* ChaCha20: Available ciphers. (line 98) 7130* cipher text stealing: Working with cipher handles. 7131 (line 50) 7132* comp: Cryptographic Functions. 7133 (line 13) 7134* CRC32: Available hash algorithms. 7135 (line 6) 7136* CTR, Counter mode: Available cipher modes. 7137 (line 32) 7138* DES: Available ciphers. (line 57) 7139* DES-EDE: Available ciphers. (line 14) 7140* Digital Encryption Standard: Available ciphers. (line 14) 7141* disable-jent: Configuration. (line 58) 7142* EAX, EAX mode: Available cipher modes. 7143 (line 89) 7144* ECB, Electronic Codebook mode: Available cipher modes. 7145 (line 13) 7146* EdDSA: Cryptographic Functions. 7147 (line 33) 7148* Enforced FIPS mode: Enabling FIPS mode. (line 29) 7149* error codes: Error Values. (line 6) 7150* error codes, list of: Error Sources. (line 6) 7151* error codes, list of <1>: Error Codes. (line 6) 7152* error codes, printing of: Error Strings. (line 6) 7153* error sources: Error Values. (line 6) 7154* error sources, printing of: Error Strings. (line 6) 7155* error strings: Error Strings. (line 6) 7156* error values: Error Values. (line 6) 7157* error values, printing of: Error Strings. (line 6) 7158* FIPS 140: Enabling FIPS mode. (line 6) 7159* FIPS 186: Cryptographic Functions. 7160 (line 72) 7161* FIPS 186 <1>: Public-Key Subsystem Architecture. 7162 (line 50) 7163* FIPS 186-2: Cryptographic Functions. 7164 (line 80) 7165* FIPS mode: Enabling FIPS mode. (line 6) 7166* fips_enabled: Configuration. (line 69) 7167* GCM, Galois/Counter Mode: Available cipher modes. 7168 (line 53) 7169* GCRYPT_BARRETT: Configuration. (line 12) 7170* GCRYPT_RNDUNIX_DBG: Configuration. (line 17) 7171* GCRYPT_RNDUNIX_DBGALL: Configuration. (line 17) 7172* GCRYPT_RNDW32_DBG: Configuration. (line 32) 7173* GCRYPT_RNDW32_NOPERF: Configuration. (line 25) 7174* GOST 28147-89: Available ciphers. (line 88) 7175* GOST 28147-89 CryptoPro keymeshing: Available ciphers. (line 92) 7176* GPL, GNU General Public License: Copying. (line 6) 7177* hardware features: Hardware features. (line 6) 7178* HAVAL: Available hash algorithms. 7179 (line 6) 7180* HMAC: Working with hash algorithms. 7181 (line 28) 7182* HMAC-BLAKE2s, HMAC-BLAKE2b: Available MAC algorithms. 7183 (line 6) 7184* HMAC-GOSTR-3411-94: Available MAC algorithms. 7185 (line 6) 7186* HMAC-MD2, HMAC-MD4, HMAC-MD5: Available MAC algorithms. 7187 (line 6) 7188* HMAC-RIPE-MD-160: Available MAC algorithms. 7189 (line 6) 7190* HMAC-SHA-1: Available MAC algorithms. 7191 (line 6) 7192* HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, HMAC-SHA-512: Available MAC algorithms. 7193 (line 6) 7194* HMAC-SHA-512/224, HMAC-SHA-512/256: Available MAC algorithms. 7195 (line 6) 7196* HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, HMAC-SHA3-512: Available MAC algorithms. 7197 (line 6) 7198* HMAC-SM3: Available MAC algorithms. 7199 (line 6) 7200* HMAC-Stribog-256, HMAC-Stribog-512: Available MAC algorithms. 7201 (line 6) 7202* HMAC-TIGER1: Available MAC algorithms. 7203 (line 6) 7204* HMAC-Whirlpool: Available MAC algorithms. 7205 (line 6) 7206* HOME: Configuration. (line 37) 7207* IDEA: Available ciphers. (line 11) 7208* LGPL, GNU Lesser General Public License: Library Copying. (line 6) 7209* MD2, MD4, MD5: Available hash algorithms. 7210 (line 6) 7211* no-blinding: Cryptographic Functions. 7212 (line 41) 7213* no-keytest: Cryptographic Functions. 7214 (line 59) 7215* nocomp: Cryptographic Functions. 7216 (line 13) 7217* OAEP: Cryptographic Functions. 7218 (line 27) 7219* OCB, OCB3: Available cipher modes. 7220 (line 63) 7221* OFB, Output Feedback mode: Available cipher modes. 7222 (line 29) 7223* only-urandom: Configuration. (line 61) 7224* param: Cryptographic Functions. 7225 (line 47) 7226* PKCS1: Cryptographic Functions. 7227 (line 23) 7228* Poly1305 based AEAD mode with ChaCha20: Available cipher modes. 7229 (line 58) 7230* PSS: Cryptographic Functions. 7231 (line 30) 7232* RC2: Available ciphers. (line 69) 7233* RC4: Available ciphers. (line 52) 7234* rfc-2268: Available ciphers. (line 69) 7235* RFC6979: Cryptographic Functions. 7236 (line 38) 7237* Rijndael: Available ciphers. (line 35) 7238* RIPE-MD-160: Available hash algorithms. 7239 (line 6) 7240* Salsa20: Available ciphers. (line 81) 7241* Salsa20/12: Available ciphers. (line 84) 7242* Seed (cipher): Available ciphers. (line 72) 7243* Serpent: Available ciphers. (line 65) 7244* SHA-1: Available hash algorithms. 7245 (line 6) 7246* SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256: Available hash algorithms. 7247 (line 6) 7248* SHA3-224, SHA3-256, SHA3-384, SHA3-512, SHAKE128, SHAKE256: Available hash algorithms. 7249 (line 6) 7250* SM3: Available hash algorithms. 7251 (line 6) 7252* SM4 (cipher): Available ciphers. (line 101) 7253* sync mode (OpenPGP): Working with cipher handles. 7254 (line 46) 7255* TIGER, TIGER1, TIGER2: Available hash algorithms. 7256 (line 6) 7257* transient-key: Cryptographic Functions. 7258 (line 52) 7259* Triple-DES: Available ciphers. (line 14) 7260* Twofish: Available ciphers. (line 46) 7261* Whirlpool: Available hash algorithms. 7262 (line 6) 7263* X9.31: Cryptographic Functions. 7264 (line 65) 7265* X9.31 <1>: Public-Key Subsystem Architecture. 7266 (line 50) 7267* XTS, XTS mode: Available cipher modes. 7268 (line 74) 7269 7270
