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