/indra/libgcrypt/libgcrypt-1.2.2/doc/gcrypt.info
Unknown | 4698 lines | 3737 code | 961 blank | 0 comment | 0 complexity | 20c855858e53f0cbed0617a6e61e1af9 MD5 | raw file
Possible License(s): LGPL-2.1, LGPL-2.0, BSD-3-Clause, GPL-2.0
Large files files are truncated, but you can click here to view the full file
1This is gcrypt.info, produced by makeinfo version 4.7 from gcrypt.texi. 2 3 This manual is for Libgcrypt (version 1.2.2, 29 July 2005), which is 4GNU's library of cryptographic building blocks. 5 6 Copyright (C) 2000, 2002, 2003, 2004 Free Software Foundation, Inc. 7 8 Permission is granted to copy, distribute and/or modify this 9 document under the terms of the GNU General Public License as 10 published by the Free Software Foundation; either version 2 of the 11 License, or (at your option) any later version. The text of the 12 license can be found in the section entitled "Copying". 13 14INFO-DIR-SECTION GNU Libraries 15START-INFO-DIR-ENTRY 16* libgcrypt: (gcrypt). Cryptographic function library. 17END-INFO-DIR-ENTRY 18 19 20File: gcrypt.info, Node: Top, Next: Introduction, Up: (dir) 21 22The Libgcrypt Library 23********************* 24 25This manual is for Libgcrypt (version 1.2.2, 29 July 2005), which is 26GNU's library of cryptographic building blocks. 27 28 Copyright (C) 2000, 2002, 2003, 2004 Free Software Foundation, Inc. 29 30 Permission is granted to copy, distribute and/or modify this 31 document under the terms of the GNU General Public License as 32 published by the Free Software Foundation; either version 2 of the 33 License, or (at your option) any later version. The text of the 34 license can be found in the section entitled "Copying". 35 36* Menu: 37 38* Introduction:: What is Libgcrypt. 39* Preparation:: What you should do before using the library. 40* Generalities:: General library functions and data types. 41* Handler Functions:: Working with handler functions. 42* Symmetric cryptography:: How to use symmetric cryptography. 43* Hashing:: How to use hashing. 44* Public Key cryptography (I):: How to use public key cryptography. 45* Public Key cryptography (II):: How to use public key cryptography, alternatively. 46* Random Numbers:: How to work with random numbers. 47* S-expressions:: How to manage S-expressions. 48* MPI library:: How to work with multi-precision-integers. 49* Utilities:: Utility functions. 50 51Appendices 52 53* Library Copying:: The GNU Lesser General Public License 54 says how you can copy and share `Libgcrypt'. 55* Copying:: The GNU General Public License says how you 56 can copy and share some parts of `Libgcrypt'. 57 58Indices 59 60* Concept Index:: Index of concepts and programs. 61* Function and Data Index:: Index of functions, variables and data types. 62 63 --- The Detailed Node Listing --- 64 65Introduction 66* Getting Started:: How to use this manual. 67* Features:: A glance at Libgcrypt's features. 68* Overview:: Overview about the library. 69 70Preparation 71* Header:: What header file you need to include. 72* Building sources:: How to build sources using the library. 73* Building sources using Automake:: How to build sources with the help of Automake. 74* Initializing the library:: How to initialize the library. 75* Multi Threading:: How Libgcrypt can be used in a MT environment. 76 77Generalities 78* Controlling the library:: Controlling Libgcrypt's behavior. 79* Modules:: Description of extension modules. 80* Error Handling:: Error codes and such. 81 82Handler Functions 83* Progress handler:: Using a progress handler function. 84* Allocation handler:: Using special memory allocation functions. 85* Error handler:: Using error handler functions. 86* Logging handler:: Using a special logging function. 87 88Symmetric cryptography 89* Available ciphers:: List of ciphers supported by the library. 90* Cipher modules:: How to work with cipher modules. 91* Available cipher modes:: List of cipher modes supported by the library. 92* Working with cipher handles:: How to perform operations related to cipher handles. 93* General cipher functions:: General cipher functions independent of cipher handles. 94 95Hashing 96* Available hash algorithms:: List of hash algorithms supported by the library. 97* Hash algorithm modules:: How to work with hash algorithm modules. 98* Working with hash algorithms:: List of functions related to hashing. 99 100Public Key cryptography (I) 101* Used S-expressions:: Introduction into the used S-expression. 102* Available algorithms:: Algorithms supported by the library. 103* Public key modules:: How to work with public key modules. 104* Cryptographic Functions:: Functions for performing the cryptographic actions. 105* General public-key related Functions:: General functions, not implementing any cryptography. 106 107Public Key cryptography (II) 108* Available asymmetric algorithms:: List of algorithms supported by the library. 109* Working with sets of data:: How to work with sets of data. 110* Working with handles:: How to use handles. 111* Working with keys:: How to work with keys. 112* Using cryptographic functions:: How to perform cryptographic operations. 113* Handle-independent functions:: General functions independent of handles. 114 115Random Numbers 116* Quality of random numbers:: Libgcrypt uses different quality levels. 117* Retrieving random numbers:: How to retrieve random numbers. 118 119S-expressions 120* Data types for S-expressions:: Data types related with S-expressions. 121* Working with S-expressions:: How to work with S-expressions. 122 123MPI library 124* Data types:: MPI related data types. 125* Basic functions:: First steps with MPI numbers. 126* MPI formats:: External representation of MPIs. 127* Calculations:: Performing MPI calculations. 128* Comparisons:: How to compare MPI values. 129* Bit manipulations:: How to access single bits of MPI values. 130* Miscellaneous:: Miscellaneous MPI functions. 131 132Utilities 133* Memory allocation:: Functions related with memory allocation. 134 135 136File: gcrypt.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top 137 1381 Introduction 139************** 140 141`Libgcrypt' is a library providing cryptographic building blocks. 142 143* Menu: 144 145* Getting Started:: How to use this manual. 146* Features:: A glance at Libgcrypt's features. 147* Overview:: Overview about the library. 148 149 150File: gcrypt.info, Node: Getting Started, Next: Features, Up: Introduction 151 1521.1 Getting Started 153=================== 154 155This manual documents the `Libgcrypt' library application programming 156interface (API). All functions and data types provided by the library 157are explained. 158 159The reader is assumed to possess basic knowledge about applied 160cryptography. 161 162 This manual can be used in several ways. If read from the beginning 163to the end, it gives a good introduction into the library and how it 164can be used in an application. Forward references are included where 165necessary. Later on, the manual can be used as a reference manual to 166get just the information needed about any particular interface of the 167library. Experienced programmers might want to start looking at the 168examples at the end of the manual, and then only read up those parts of 169the interface which are unclear. 170 171 172File: gcrypt.info, Node: Features, Next: Overview, Prev: Getting Started, Up: Introduction 173 1741.2 Features 175============ 176 177`Libgcrypt' might have a couple of advantages over other libraries doing 178a similar job. 179 180It's Free Software 181 Anybody can use, modify, and redistribute it under the terms of 182 the GNU Lesser General Public License (*note Library Copying::). 183 Note, that some parts (which are not needed on a GNU or GNU/Linux 184 system) are subject to the terms of the GNU General Public License 185 (*note Copying::); please see the README file of the distribution 186 for of list of these parts. 187 188It encapsulates the low level cryptography 189 `Libgcrypt' provides a high level interface to cryptographic 190 building blocks using an extendable and flexible API. 191 192 193 194File: gcrypt.info, Node: Overview, Prev: Features, Up: Introduction 195 1961.3 Overview 197============ 198 199The `Libgcrypt' library is fully thread-safe, where it makes sense to 200be thread-safe. An exception for thread-safety are some cryptographic 201functions that modify a certain context stored in handles. If the user 202really intents to use such functions from different threads on the same 203handle, he has to take care of the serialization of such functions 204himself. If not described otherwise, every function is thread-safe. 205 206 Libgcrypt depends on the library `libgpg-error', which contains 207common error handling related code for GnuPG components. 208 209 210File: gcrypt.info, Node: Preparation, Next: Generalities, Prev: Introduction, Up: Top 211 2122 Preparation 213************* 214 215To use `Libgcrypt', you have to perform some changes to your sources 216and the build system. The necessary changes are small and explained in 217the following sections. At the end of this chapter, it is described 218how the library is initialized, and how the requirements of the library 219are verified. 220 221* Menu: 222 223* Header:: What header file you need to include. 224* Building sources:: How to build sources using the library. 225* Building sources using Automake:: How to build sources with the help of Automake. 226* Initializing the library:: How to initialize the library. 227* Multi Threading:: How Libgcrypt can be used in a MT environment. 228 229 230File: gcrypt.info, Node: Header, Next: Building sources, Up: Preparation 231 2322.1 Header 233========== 234 235All interfaces (data types and functions) of the library are defined in 236the header file `gcrypt.h'. You must include this in all source files 237using the library, either directly or through some other header file, 238like this: 239 240 #include <gcrypt.h> 241 242 The name space of `Libgcrypt' is `gcry_*' for function and type 243names and `GCRY*' for other symbols. In addition the same name 244prefixes with one prepended underscore are reserved for internal use 245and should never be used by an application. Furthermore `libgpg-error' 246defines functions prefixed with `gpg_' and preprocessor symbols 247prefixed with `GPG_'. Note that Libgcrypt uses libgpg-error, which 248uses `gpg_err_*' as name space for function and type names and 249`GPG_ERR_*' for other symbols, including all the error codes. 250 251 252File: gcrypt.info, Node: Building sources, Next: Building sources using Automake, Prev: Header, Up: Preparation 253 2542.2 Building sources 255==================== 256 257If you want to compile a source file including the `gcrypt.h' header 258file, you must make sure that the compiler can find it in the directory 259hierarchy. This is accomplished by adding the path to the directory in 260which the header file is located to the compilers include file search 261path (via the `-I' option). 262 263 However, the path to the include file is determined at the time the 264source is configured. To solve this problem, `Libgcrypt' ships with a 265small helper program `libgcrypt-config' that knows the path to the 266include file and other configuration options. The options that need to 267be added to the compiler invocation at compile time are output by the 268`--cflags' option to `libgcrypt-config'. The following example shows 269how it can be used at the command line: 270 271 gcc -c foo.c `libgcrypt-config --cflags` 272 273 Adding the output of `libgcrypt-config --cflags' to the compilers 274command line will ensure that the compiler can find the `Libgcrypt' 275header file. 276 277 A similar problem occurs when linking the program with the library. 278Again, the compiler has to find the library files. For this to work, 279the path to the library files has to be added to the library search path 280(via the `-L' option). For this, the option `--libs' to 281`libgcrypt-config' can be used. For convenience, this option also 282outputs all other options that are required to link the program with 283the `Libgcrypt' libraries (in particular, the `-lgcrypt' option). The 284example shows how to link `foo.o' with the `Libgcrypt' library to a 285program `foo'. 286 287 gcc -o foo foo.o `libgcrypt-config --libs` 288 289 Of course you can also combine both examples to a single command by 290specifying both options to `libgcrypt-config': 291 292 gcc -o foo foo.c `libgcrypt-config --cflags --libs` 293 294 295File: gcrypt.info, Node: Building sources using Automake, Next: Initializing the library, Prev: Building sources, Up: Preparation 296 2972.3 Building sources using Automake 298=================================== 299 300It is much easier if you use GNU Automake instead of writing your own 301Makefiles. If you do that you do not have to worry about finding and 302invoking the `libgcrypt-config' script at all. Libgcrypt provides an 303extension to Automake that does all the work for you. 304 305 -- Macro: AM_PATH_LIBGCRYPT ([MINIMUM-VERSION], [ACTION-IF-FOUND], 306 [ACTION-IF-NOT-FOUND]) 307 Check whether Libgcrypt (at least version MINIMUM-VERSION, if 308 given) exists on the host system. If it is found, execute 309 ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. 310 311 Additionally, the function defines `LIBGCRYPT_CFLAGS' to the flags 312 needed for compilation of the program to find the `gcrypt.h' 313 header file, and `LIBGCRYPT_LIBS' to the linker flags needed to 314 link the program to the Libgcrypt library. 315 316 You can use the defined Autoconf variables like this in your 317`Makefile.am': 318 319 AM_CPPFLAGS = $(LIBGCRYPT_CFLAGS) 320 LDADD = $(LIBGCRYPT_LIBS) 321 322 323File: gcrypt.info, Node: Initializing the library, Next: Multi Threading, Prev: Building sources using Automake, Up: Preparation 324 3252.4 Initializing the library 326============================ 327 328It is often desirable to check that the version of `Libgcrypt' used is 329indeed one which fits all requirements. Even with binary compatibility 330new features may have been introduced but due to problem with the 331dynamic linker an old version is actually used. So you may want to 332check that the version is okay right after program startup. 333 334 -- Function: const char *gcry_check_version (const char *REQ_VERSION) 335 The function `gcry_check_version' has three purposes. It can be 336 used to retrieve the version number of the library. In addition it 337 can verify that the version number is higher than a certain 338 required version number. 339 340 In either case, the function initializes some sub-systems, and for 341 this reason alone it must be invoked early in your program, before 342 you make use of the other functions of Libgcrypt. 343 344 345File: gcrypt.info, Node: Multi Threading, Prev: Initializing the library, Up: Preparation 346 3472.5 Multi Threading 348=================== 349 350As mentioned earlier, the `Libgcrypt' library is thread-safe if you 351adhere to the following requirements: 352 353 * If your application is multi-threaded, you must set the thread 354 support callbacks with the `GCRYCTL_SET_THREAD_CBS' command 355 *before* any other function in the library. 356 357 This is easy enough if you are indeed writing an application using 358 Libgcrypt. It is rather problematic if you are writing a library 359 instead. Here are some tips what to do if you are writing a 360 library: 361 362 If your library requires a certain thread package, just initialize 363 Libgcrypt to use this thread package. If your library supports 364 multiple thread packages, but needs to be configured, you will 365 have to implement a way to determine which thread package the 366 application wants to use with your library anyway. Then configure 367 Libgcrypt to use this thread package. 368 369 If your library is fully reentrant without any special support by a 370 thread package, then you are lucky indeed. Unfortunately, this 371 does not relieve you from doing either of the two above, or use a 372 third option. The third option is to let the application 373 initialize Libgcrypt for you. Then you are not using Libgcrypt 374 transparently, though. 375 376 As if this was not difficult enough, a conflict may arise if two 377 libraries try to initialize Libgcrypt independently of each 378 others, and both such libraries are then linked into the same 379 application. To make it a bit simpler for you, this will probably 380 work, but only if both libraries have the same requirement for the 381 thread package. This is currently only supported for the 382 non-threaded case, GNU Pth and pthread. Support for more thread 383 packages is easy to add, so contact us if you require it. 384 385 * The function `gcry_check_version' must be called before any other 386 function in the library, except the `GCRYCTL_SET_THREAD_CBS' 387 command (called via the `gcry_control' function), because it 388 initializes the thread support subsystem in Libgcrypt. To achieve 389 this in multi-threaded programs, you must synchronize the memory 390 with respect to other threads that also want to use Libgcrypt. 391 For this, it is sufficient to call `gcry_check_version' before 392 creating the other threads using Libgcrypt(1). 393 394 * As with the function `gpg_strerror', `gcry_strerror' is not 395 thread safe. You have to use `gpg_strerror_r' instead. 396 397 Libgcrypt contains convenient macros, which define the necessary 398thread callbacks for PThread and for GNU Pth: 399 400`GCRY_THREAD_OPTION_PTH_IMPL' 401 This macro defines the following (static) symbols: gcry_pth_init, 402 gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock, 403 gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, 404 gcry_pth_select, gcry_pth_waitpid, gcry_pth_accept, 405 gcry_pth_connect, gcry_threads_pth. 406 407 After including this macro, gcry_control() shall be used with a 408 command of GCRYCTL_SET_THREAD_CBS in order to register the thread 409 callback structure named "gcry_threads_pth". 410 411`GCRY_THREAD_OPTION_PTHREAD_IMPL' 412 This macro defines the following (static) symbols: 413 gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, 414 gcry_mutex_lock, gcry_mutex_unlock, gcry_threads_pthread. 415 416 After including this macro, gcry_control() shall be used with a 417 command of GCRYCTL_SET_THREAD_CBS in order to register the thread 418 callback structure named "gcry_threads_pthread". 419 420 Note that these macros need to be terminated with a semicolon. Keep 421in mind that these are convenient macros for C programmers; C++ 422programmers might have to wrap these macros in an "extern C" body. 423 424 ---------- Footnotes ---------- 425 426 (1) At least this is true for POSIX threads, as `pthread_create' is 427a function that synchronizes memory with respects to other threads. 428There are many functions which have this property, a complete list can 429be found in POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in 430the definition of the term "Memory Synchronization". For other thread 431packages, more relaxed or more strict rules may apply. 432 433 434File: gcrypt.info, Node: Generalities, Next: Handler Functions, Prev: Preparation, Up: Top 435 4363 Generalities 437************** 438 439* Menu: 440 441* Controlling the library:: Controlling Libgcrypt's behavior. 442* Modules:: Description of extension modules. 443* Error Handling:: Error codes and such. 444 445 446File: gcrypt.info, Node: Controlling the library, Next: Modules, Up: Generalities 447 4483.1 Controlling the library 449=========================== 450 451 -- Function: gcry_error_t gcry_control (enum gcry_ctl_cmds CMD, ...) 452 This function can be used to influence the general behavior of 453 Libgcrypt in several ways. Depending on CMD, more arguments can 454 or have to be provided. 455 456 457 458File: gcrypt.info, Node: Modules, Next: Error Handling, Prev: Controlling the library, Up: Generalities 459 4603.2 Modules 461=========== 462 463Libgcrypt supports the use of `extension modules', which implement 464algorithms in addition to those already built into the library directly. 465 466 -- Data type: gcry_module_t 467 This data type represents a `module'. 468 469 Functions registering modules provided by the user take a `module 470specification structure' as input and return a value of `gcry_module_t' 471and an ID that is unique in the modules' category. This ID can be used 472to reference the newly registered module. After registering a module 473successfully, the new functionality should be able to be used through 474the normal functions provided by Libgcrypt until it is unregistered 475again. 476 477 478File: gcrypt.info, Node: Error Handling, Prev: Modules, Up: Generalities 479 4803.3 Error Handling 481================== 482 483Many functions in Libgcrypt can return an error if they fail. For this 484reason, the application should always catch the error condition and 485take appropriate measures, for example by releasing the resources and 486passing the error up to the caller, or by displaying a descriptive 487message to the user and cancelling the operation. 488 489 Some error values do not indicate a system error or an error in the 490operation, but the result of an operation that failed properly. For 491example, if you try to decrypt a tempered message, the decryption will 492fail. Another error value actually means that the end of a data buffer 493or list has been reached. The following descriptions explain for many 494error codes what they mean usually. Some error values have specific 495meanings if returned by a certain functions. Such cases are described 496in the documentation of those functions. 497 498 Libgcrypt uses the `libgpg-error' library. This allows to share the 499error codes with other components of the GnuPG system, and thus pass 500error values transparently from the crypto engine, or some helper 501application of the crypto engine, to the user. This way no information 502is lost. As a consequence, Libgcrypt does not use its own identifiers 503for error codes, but uses those provided by `libgpg-error'. They 504usually start with `GPG_ERR_'. 505 506 However, Libgcrypt does provide aliases for the functions defined in 507libgpg-error, which might be preferred for name space consistency. 508 509 Most functions in Libgcrypt return an error code in the case of 510failure. For this reason, the application should always catch the 511error condition and take appropriate measures, for example by releasing 512the resources and passing the error up to the caller, or by displaying 513a descriptive message to the user and canceling the operation. 514 515 Some error values do not indicate a system error or an error in the 516operation, but the result of an operation that failed properly. 517 518 GnuPG components, including Libgcrypt, use an extra library named 519libgpg-error to provide a common error handling scheme. For more 520information on libgpg-error, see the according manual. 521 522* Menu: 523 524* Error Values:: The error value and what it means. 525* Error Sources:: A list of important error sources. 526* Error Codes:: A list of important error codes. 527* Error Strings:: How to get a descriptive string from a value. 528 529 530File: gcrypt.info, Node: Error Values, Next: Error Sources, Up: Error Handling 531 5323.3.1 Error Values 533------------------ 534 535 -- Data type: gcry_err_code_t 536 The `gcry_err_code_t' type is an alias for the `libgpg-error' type 537 `gpg_err_code_t'. The error code indicates the type of an error, 538 or the reason why an operation failed. 539 540 A list of important error codes can be found in the next section. 541 542 -- Data type: gcry_err_source_t 543 The `gcry_err_source_t' type is an alias for the `libgpg-error' 544 type `gpg_err_source_t'. The error source has not a precisely 545 defined meaning. Sometimes it is the place where the error 546 happened, sometimes it is the place where an error was encoded 547 into an error value. Usually the error source will give an 548 indication to where to look for the problem. This is not always 549 true, but it is attempted to achieve this goal. 550 551 A list of important error sources can be found in the next section. 552 553 -- Data type: gcry_error_t 554 The `gcry_error_t' type is an alias for the `libgpg-error' type 555 `gpg_error_t'. An error value like this has always two 556 components, an error code and an error source. Both together form 557 the error value. 558 559 Thus, the error value can not be directly compared against an error 560 code, but the accessor functions described below must be used. 561 However, it is guaranteed that only 0 is used to indicate success 562 (`GPG_ERR_NO_ERROR'), and that in this case all other parts of the 563 error value are set to 0, too. 564 565 Note that in Libgcrypt, the error source is used purely for 566 diagnostic purposes. Only the error code should be checked to test 567 for a certain outcome of a function. The manual only documents the 568 error code part of an error value. The error source is left 569 unspecified and might be anything. 570 571 -- Function: gcry_err_code_t gcry_err_code (gcry_error_t ERR) 572 The static inline function `gcry_err_code' returns the 573 `gcry_err_code_t' component of the error value ERR. This function 574 must be used to extract the error code from an error value in 575 order to compare it with the `GPG_ERR_*' error code macros. 576 577 -- Function: gcry_err_source_t gcry_err_source (gcry_error_t ERR) 578 The static inline function `gcry_err_source' returns the 579 `gcry_err_source_t' component of the error value ERR. This 580 function must be used to extract the error source from an error 581 value in order to compare it with the `GPG_ERR_SOURCE_*' error 582 source macros. 583 584 -- Function: gcry_error_t gcry_err_make (gcry_err_source_t SOURCE, 585 gcry_err_code_t CODE) 586 The static inline function `gcry_err_make' returns the error value 587 consisting of the error source SOURCE and the error code CODE. 588 589 This function can be used in callback functions to construct an 590 error value to return it to the library. 591 592 -- Function: gcry_error_t gcry_error (gcry_err_code_t CODE) 593 The static inline function `gcry_error' returns the error value 594 consisting of the default error source and the error code CODE. 595 596 For GCRY applications, the default error source is 597 `GPG_ERR_SOURCE_USER_1'. You can define `GCRY_ERR_SOURCE_DEFAULT' 598 before including `gcrypt.h' to change this default. 599 600 This function can be used in callback functions to construct an 601 error value to return it to the library. 602 603 The `libgpg-error' library provides error codes for all system error 604numbers it knows about. If ERR is an unknown error number, the error 605code `GPG_ERR_UNKNOWN_ERRNO' is used. The following functions can be 606used to construct error values from system errno numbers. 607 608 -- Function: gcry_error_t gcry_err_make_from_errno 609 (gcry_err_source_t SOURCE, int ERR) 610 The function `gcry_err_make_from_errno' is like `gcry_err_make', 611 but it takes a system error like `errno' instead of a 612 `gcry_err_code_t' error code. 613 614 -- Function: gcry_error_t gcry_error_from_errno (int ERR) 615 The function `gcry_error_from_errno' is like `gcry_error', but it 616 takes a system error like `errno' instead of a `gcry_err_code_t' 617 error code. 618 619 Sometimes you might want to map system error numbers to error codes 620directly, or map an error code representing a system error back to the 621system error number. The following functions can be used to do that. 622 623 -- Function: gcry_err_code_t gcry_err_code_from_errno (int ERR) 624 The function `gcry_err_code_from_errno' returns the error code for 625 the system error ERR. If ERR is not a known system error, the 626 function returns `GPG_ERR_UNKNOWN_ERRNO'. 627 628 -- Function: int gcry_err_code_to_errno (gcry_err_code_t ERR) 629 The function `gcry_err_code_to_errno' returns the system error for 630 the error code ERR. If ERR is not an error code representing a 631 system error, or if this system error is not defined on this 632 system, the function returns `0'. 633 634 635File: gcrypt.info, Node: Error Sources, Next: Error Codes, Prev: Error Values, Up: Error Handling 636 6373.3.2 Error Sources 638------------------- 639 640The library `libgpg-error' defines an error source for every component 641of the GnuPG system. The error source part of an error value is not 642well defined. As such it is mainly useful to improve the diagnostic 643error message for the user. 644 645 If the error code part of an error value is `0', the whole error 646value will be `0'. In this case the error source part is of course 647`GPG_ERR_SOURCE_UNKNOWN'. 648 649 The list of error sources that might occur in applications using 650Libgctypt is: 651 652`GPG_ERR_SOURCE_UNKNOWN' 653 The error source is not known. The value of this error source is 654 `0'. 655 656`GPG_ERR_SOURCE_GPGME' 657 The error source is GPGME itself. 658 659`GPG_ERR_SOURCE_GPG' 660 The error source is GnuPG, which is the crypto engine used for the 661 OpenPGP protocol. 662 663`GPG_ERR_SOURCE_GPGSM' 664 The error source is GPGSM, which is the crypto engine used for the 665 OpenPGP protocol. 666 667`GPG_ERR_SOURCE_GCRYPT' 668 The error source is `libgcrypt', which is used by crypto engines 669 to perform cryptographic operations. 670 671`GPG_ERR_SOURCE_GPGAGENT' 672 The error source is `gpg-agent', which is used by crypto engines 673 to perform operations with the secret key. 674 675`GPG_ERR_SOURCE_PINENTRY' 676 The error source is `pinentry', which is used by `gpg-agent' to 677 query the passphrase to unlock a secret key. 678 679`GPG_ERR_SOURCE_SCD' 680 The error source is the SmartCard Daemon, which is used by 681 `gpg-agent' to delegate operations with the secret key to a 682 SmartCard. 683 684`GPG_ERR_SOURCE_KEYBOX' 685 The error source is `libkbx', a library used by the crypto engines 686 to manage local keyrings. 687 688`GPG_ERR_SOURCE_USER_1' 689 690`GPG_ERR_SOURCE_USER_2' 691 692`GPG_ERR_SOURCE_USER_3' 693 694`GPG_ERR_SOURCE_USER_4' 695 These error sources are not used by any GnuPG component and can be 696 used by other software. For example, applications using Libgcrypt 697 can use them to mark error values coming from callback handlers. 698 Thus `GPG_ERR_SOURCE_USER_1' is the default for errors created 699 with `gcry_error' and `gcry_error_from_errno', unless you define 700 `GCRY_ERR_SOURCE_DEFAULT' before including `gcrypt.h'. 701 702 703File: gcrypt.info, Node: Error Codes, Next: Error Strings, Prev: Error Sources, Up: Error Handling 704 7053.3.3 Error Codes 706----------------- 707 708The library `libgpg-error' defines many error values. The following 709list includes the most important error codes. 710 711`GPG_ERR_EOF' 712 This value indicates the end of a list, buffer or file. 713 714`GPG_ERR_NO_ERROR' 715 This value indicates success. The value of this error code is 716 `0'. Also, it is guaranteed that an error value made from the 717 error code `0' will be `0' itself (as a whole). This means that 718 the error source information is lost for this error code, however, 719 as this error code indicates that no error occured, this is 720 generally not a problem. 721 722`GPG_ERR_GENERAL' 723 This value means that something went wrong, but either there is not 724 enough information about the problem to return a more useful error 725 value, or there is no separate error value for this type of 726 problem. 727 728`GPG_ERR_ENOMEM' 729 This value means that an out-of-memory condition occurred. 730 731`GPG_ERR_E...' 732 System errors are mapped to GPG_ERR_EFOO where FOO is the symbol 733 for the system error. 734 735`GPG_ERR_INV_VALUE' 736 This value means that some user provided data was out of range. 737 738`GPG_ERR_UNUSABLE_PUBKEY' 739 This value means that some recipients for a message were invalid. 740 741`GPG_ERR_UNUSABLE_SECKEY' 742 This value means that some signers were invalid. 743 744`GPG_ERR_NO_DATA' 745 This value means that data was expected where no data was found. 746 747`GPG_ERR_CONFLICT' 748 This value means that a conflict of some sort occurred. 749 750`GPG_ERR_NOT_IMPLEMENTED' 751 This value indicates that the specific function (or operation) is 752 not implemented. This error should never happen. It can only 753 occur if you use certain values or configuration options which do 754 not work, but for which we think that they should work at some 755 later time. 756 757`GPG_ERR_DECRYPT_FAILED' 758 This value indicates that a decryption operation was unsuccessful. 759 760`GPG_ERR_WRONG_KEY_USAGE' 761 This value indicates that a key is not used appropriately. 762 763`GPG_ERR_NO_SECKEY' 764 This value indicates that no secret key for the user ID is 765 available. 766 767`GPG_ERR_UNSUPPORTED_ALGORITHM' 768 This value means a verification failed because the cryptographic 769 algorithm is not supported by the crypto backend. 770 771`GPG_ERR_BAD_SIGNATURE' 772 This value means a verification failed because the signature is 773 bad. 774 775`GPG_ERR_NO_PUBKEY' 776 This value means a verification failed because the public key is 777 not available. 778 779`GPG_ERR_USER_1' 780 781`GPG_ERR_USER_2' 782 783`...' 784 785`GPG_ERR_USER_16' 786 These error codes are not used by any GnuPG component and can be 787 freely used by other software. Applications using Libgcrypt might 788 use them to mark specific errors returned by callback handlers if 789 no suitable error codes (including the system errors) for these 790 errors exist already. 791 792 793File: gcrypt.info, Node: Error Strings, Prev: Error Codes, Up: Error Handling 794 7953.3.4 Error Strings 796------------------- 797 798 -- Function: const char * gcry_strerror (gcry_error_t ERR) 799 The function `gcry_strerror' returns a pointer to a statically 800 allocated string containing a description of the error code 801 contained in the error value ERR. This string can be used to 802 output a diagnostic message to the user. 803 804 -- Function: const char * gcry_strsource (gcry_error_t ERR) 805 The function `gcry_strerror' returns a pointer to a statically 806 allocated string containing a description of the error source 807 contained in the error value ERR. This string can be used to 808 output a diagnostic message to the user. 809 810 The following example illustrates the use of the functions described 811above: 812 813 { 814 gcry_cipher_hd_t handle; 815 gcry_error_t err = 0; 816 817 err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0); 818 if (err) 819 { 820 fprintf (stderr, "Failure: %s/%s\n", 821 gcry_strsource (err), 822 gcry_strerror (err)); 823 } 824 } 825 826 827File: gcrypt.info, Node: Handler Functions, Next: Symmetric cryptography, Prev: Generalities, Up: Top 828 8294 Handler Functions 830******************* 831 832Libgcrypt makes it possible to install so called `handler functions', 833which get called by Libgcrypt in case of certain events. 834 835* Menu: 836 837* Progress handler:: Using a progress handler function. 838* Allocation handler:: Using special memory allocation functions. 839* Error handler:: Using error handler functions. 840* Logging handler:: Using a special logging function. 841 842 843File: gcrypt.info, Node: Progress handler, Next: Allocation handler, Up: Handler Functions 844 8454.1 Progress handler 846==================== 847 848It is often useful to retrieve some feedback while long running 849operations are performed. 850 851 -- Data type: gcry_handler_progress_t 852 Progress handler functions have to be of the type 853 `gcry_handler_progress_t', which is defined as: 854 855 `void (*gcry_handler_progress_t) (void *, const char *, int, int, 856 int)' 857 858 The following function may be used to register a handler function for 859this purpose. 860 861 -- Function: void gcry_set_progress_handler (gcry_handler_progress_t 862 CB, void *CB_DATA) 863 This function installs CB as the `Progress handler' function. CB 864 must be defined as follows: 865 866 void 867 my_progress_handler (void *CB_DATA, const char *WHAT, 868 int PRINTCHAR, int CURRENT, int TOTAL) 869 { 870 /* Do something. */ 871 } 872 873 A description of the arguments of the progress handler function 874 follows. 875 876 CB_DATA 877 The argument provided in the call to 878 `gcry_set_progress_handler'. 879 880 WHAT 881 A string identifying the type of the progress output. The 882 following values for WHAT are defined: 883 884 `need_entropy' 885 Not enough entropy is available. TOTAL holds the number 886 of required bytes. 887 888 `primegen' 889 Values for PRINTCHAR: 890 `\n' 891 Prime generated. 892 893 `!' 894 Need to refresh the pool of prime numbers. 895 896 `<, >' 897 Number of bits adjusted. 898 899 `^' 900 Searching for a generator. 901 902 `.' 903 Fermat test on 10 candidates failed. 904 905 `:' 906 Restart with a new random value. 907 908 `+' 909 Rabin Miller test passed. 910 911 912 913 914File: gcrypt.info, Node: Allocation handler, Next: Error handler, Prev: Progress handler, Up: Handler Functions 915 9164.2 Allocation handler 917====================== 918 919It is possible to make Libgcrypt use special memory allocation 920functions instead of the built-in ones. 921 922 Memory allocation functions are of the following types: 923 924 -- Data type: gcry_handler_alloc_t 925 This type is defined as: `void *(*gcry_handler_alloc_t) (size_t 926 n)'. 927 928 -- Data type: gcry_handler_secure_check_t 929 This type is defined as: `int *(*gcry_handler_secure_check_t) 930 (const void *)'. 931 932 -- Data type: gcry_handler_realloc_t 933 This type is defined as: `void *(*gcry_handler_realloc_t) (void 934 *p, size_t n)'. 935 936 -- Data type: gcry_handler_free_t 937 This type is defined as: `void *(*gcry_handler_free_t) (void *)'. 938 939 Special memory allocation functions can be installed with the 940following function: 941 942 -- Function: void gcry_set_allocation_handler (gcry_handler_alloc_t 943 FUNC_ALLOC, gcry_handler_alloc_t FUNC_ALLOC_SECURE, 944 gcry_handler_secure_check_t FUNC_SECURE_CHECK, 945 gcry_handler_realloc_t FUNC_REALLOC, gcry_handler_free_t 946 FUNC_FREE) 947 Install the provided functions and use them instead of the built-in 948 functions for doing memory allocation. 949 950 951File: gcrypt.info, Node: Error handler, Next: Logging handler, Prev: Allocation handler, Up: Handler Functions 952 9534.3 Error handler 954================= 955 956The following functions may be used to register handler functions that 957are called by Libgcrypt in case certain error conditions occur. 958 959 -- Data type: gcry_handler_no_mem_t 960 This type is defined as: `void (*gcry_handler_no_mem_t) (void *, 961 size_t, unsigned int)' 962 963 -- Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t 964 FUNC_NO_MEM, void *CB_DATA) 965 This function registers FUNC_NO_MEM as `out-of-core handler', 966 which means that it will be called in the case of not having enough 967 memory available. 968 969 -- Data type: gcry_handler_error_t 970 This type is defined as: `void (*gcry_handler_error_t) (void *, 971 int, const char *)' 972 973 -- Function: void gcry_set_fatalerror_handler (gcry_handler_error_t 974 FUNC_ERROR, void *CB_DATA) 975 This function registers FUNC_ERROR as `error handler', which means 976 that it will be called in error conditions. 977 978 979File: gcrypt.info, Node: Logging handler, Prev: Error handler, Up: Handler Functions 980 9814.4 Logging handler 982=================== 983 984 -- Data type: gcry_handler_log_t 985 This type is defined as: `void (*gcry_handler_log_t) (void *, int, 986 const char *, va_list)' 987 988 -- Function: void gcry_set_log_handler (gcry_handler_log_t FUNC_LOG, 989 void *CB_DATA) 990 This function registers FUNC_LOG as `logging handler', which means 991 that it will be called in case Libgcrypt wants to log a message. 992 993 994File: gcrypt.info, Node: Symmetric cryptography, Next: Hashing, Prev: Handler Functions, Up: Top 995 9965 Symmetric cryptography 997************************ 998 999The cipher functions are used for symmetrical cryptography, i.e. 1000cryptography using a shared key. The programming model follows an 1001open/process/close paradigm and is in that similar to other building 1002blocks provided by Libgcrypt. 1003 1004* Menu: 1005 1006* Available ciphers:: List of ciphers supported by the library. 1007* Cipher modules:: How to work with cipher modules. 1008* Available cipher modes:: List of cipher modes supported by the library. 1009* Working with cipher handles:: How to perform operations related to cipher handles. 1010* General cipher functions:: General cipher functions independent of cipher handles. 1011 1012 1013File: gcrypt.info, Node: Available ciphers, Next: Cipher modules, Up: Symmetric cryptography 1014 10155.1 Available ciphers 1016===================== 1017 1018`GCRY_CIPHER_NONE' 1019 This is not a real algorithm but used by some functions as error 1020 return. The value always evaluates to false. 1021 1022`GCRY_CIPHER_IDEA' 1023 This is the IDEA algorithm. The constant is provided but there is 1024 currently no implementation for it because the algorithm is 1025 patented. 1026 1027`GCRY_CIPHER_3DES' 1028 Triple-DES with 3 Keys as EDE. The key size of this algorithm is 1029 168 but you have to pass 192 bits because the most significant 1030 bits of each byte are ignored. 1031 1032`GCRY_CIPHER_CAST5' 1033 CAST128-5 block cipher algorithm. The key size is 128 bits. 1034 1035`GCRY_CIPHER_BLOWFISH' 1036 The blowfish algorithm. The current implementation allows only for 1037 a key size of 128 bits. 1038 1039`GCRY_CIPHER_SAFER_SK128' 1040 Reserved and not currently implemented. 1041 1042`GCRY_CIPHER_DES_SK' 1043 Reserved and not currently implemented. 1044 1045`GCRY_CIPHER_AES' 1046`GCRY_CIPHER_AES128' 1047`GCRY_CIPHER_RIJNDAEL' 1048`GCRY_CIPHER_RIJNDAEL128' 1049 AES (Rijndael) with a 128 bit key. 1050 1051`GCRY_CIPHER_AES192' 1052`GCRY_CIPHER_RIJNDAEL128' 1053 AES (Rijndael) with a 192 bit key. 1054 1055`GCRY_CIPHER_AES256' 1056`GCRY_CIPHER_RIJNDAEL256' 1057 AES (Rijndael) with a 256 bit key. 1058 1059`GCRY_CIPHER_TWOFISH' 1060 The Twofish algorithm with a 256 bit key. 1061 1062`GCRY_CIPHER_TWOFISH128' 1063 The Twofish algorithm with a 128 bit key. 1064 1065`GCRY_CIPHER_ARCFOUR' 1066 An algorithm which is 100% compatible with RSA Inc.'s RC4 1067 algorithm. Note that this is a stream cipher and must be used 1068 very carefully to avoid a couple of weaknesses. 1069 1070`GCRY_CIPHER_DES' 1071 Standard DES with a 56 bit key. You need to pass 64 bit but the 1072 high bits of each byte are ignored. Note, that this is a weak 1073 algorithm which can be broken in reasonable time using a brute 1074 force approach. 1075 1076 1077 1078File: gcrypt.info, Node: Cipher modules, Next: Available cipher modes, Prev: Available ciphers, Up: Symmetric cryptography 1079 10805.2 Cipher modules 1081================== 1082 1083Libgcrypt makes it possible to load additional `cipher modules'; these 1084cipher can be used just like the cipher algorithms that are built into 1085the library directly. For an introduction into extension modules, see 1086*Note Modules::. 1087 1088 -- Data type: gcry_cipher_spec_t 1089 This is the `module specification structure' needed for registering 1090 cipher modules, which has to be filled in by the user before it 1091 can be used to register a module. It contains the following 1092 members: 1093 1094 `const char *name' 1095 The primary name of the algorithm. 1096 1097 `const char **aliases' 1098 A list of strings that are `aliases' for the algorithm. The 1099 list must be terminated with a NULL element. 1100 1101 `gcry_cipher_oid_spec_t *oids' 1102 A list of OIDs that are to be associated with the algorithm. 1103 The list's last element must have it's `oid' member set to 1104 NULL. See below for an explanation of this type. 1105 1106 `size_t blocksize' 1107 The block size of the algorithm, in bytes. 1108 1109 `size_t keylen' 1110 The length of the key, in bits. 1111 1112 `size_t contextsize' 1113 The size of the algorithm-specific `context', that should be 1114 allocated for each handle. 1115 1116 `gcry_cipher_setkey_t setkey' 1117 The function responsible for initializing a handle with a 1118 provided key. See below for a description of this type. 1119 1120 `gcry_cipher_encrypt_t encrypt' 1121 The function responsible for encrypting a single block. See 1122 below for a description of this type. 1123 1124 `gcry_cipher_decrypt_t decrypt' 1125 The function responsible for decrypting a single block. See 1126 below for a description of this type. 1127 1128 `gcry_cipher_stencrypt_t stencrypt' 1129 Like `encrypt', for stream ciphers. See below for a 1130 description of this type. 1131 1132 `gcry_cipher_stdecrypt_t stdecrypt' 1133 Like `decrypt', for stream ciphers. See below for a 1134 description of this type. 1135 1136 -- Data type: gcry_cipher_oid_spec_t 1137 This type is used for associating a user-provided algorithm 1138 implementation with certain OIDs. It contains the following 1139 members: 1140 `const char *oid' 1141 Textual representation of the OID. 1142 1143 `int mode' 1144 Cipher mode for which this OID is valid. 1145 1146 -- Data type: gcry_cipher_setkey_t 1147 Type for the `setkey' function, defined as: gcry_err_code_t 1148 (*gcry_cipher_setkey_t) (void *c, const unsigned char *key, 1149 unsigned keylen) 1150 1151 -- Data type: gcry_cipher_encrypt_t 1152 Type for the `encrypt' function, defined as: gcry_err_code_t 1153 (*gcry_cipher_encrypt_t) (void *c, const unsigned char *outbuf, 1154 const unsigned char *inbuf) 1155 1156 -- Data type: gcry_cipher_decrypt_t 1157 Type for the `decrypt' function, defined as: gcry_err_code_t 1158 (*gcry_cipher_decrypt_t) (void *c, const unsigned char *outbuf, 1159 const unsigned char *inbuf) 1160 1161 -- Data type: gcry_cipher_stencrypt_t 1162 Type for the `stencrypt' function, defined as: gcry_err_code_t 1163 (*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, 1164 const unsigned char *, unsigned int n) 1165 1166 -- Data type: gcry_cipher_stdecrypt_t 1167 Type for the `stdecrypt' function, defined as: gcry_err_code_t 1168 (*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, 1169 const unsigned char *, unsigned int n) 1170 1171 -- Function: gcry_error_t gcry_cipher_register (gcry_cipher_spec_t 1172 *CIPHER, unsigned int *algorithm_id, gcry_module_t *MODULE) 1173 Register a new cipher module whose specification can be found in 1174 CIPHER. On success, a new algorithm ID is stored in ALGORITHM_ID 1175 and a pointer representing this module is stored in MODULE. 1176 1177 -- Function: void gcry_cipher_unregister (gcry_module_t MODULE) 1178 Unregister the cipher identified by MODULE, which must have been 1179 registered with gcry_cipher_register. 1180 1181 -- Function: gcry_error_t gcry_cipher_list (int *LIST, int 1182 *LIST_LENGTH) 1183 Get a list consisting of the IDs of the loaded cipher modules. If 1184 LIST is zero, write the number of loaded cipher modules to 1185 LIST_LENGTH and return. If LIST is non-zero, the first 1186 *LIST_LENGTH algorithm IDs are stored in LIST, which must be of 1187 according size. In case there are less cipher modules than 1188 *LIST_LENGTH, *LIST_LENGTH is updated to the correct number. 1189 1190 1191File: gcrypt.info, Node: Available cipher modes, Next: Working with cipher handles, Prev: Cipher modules, Up: Symmetric cryptography 1192 11935.3 Available cipher modes 1194========================== 1195 1196`GCRY_CIPHER_MODE_NONE' 1197 No mode specified, may be set later using other functions. The 1198 value of this constant is always 0. 1199 1200`GCRY_CIPHER_MODE_ECB' 1201 Electronic Codebook mode. 1202 1203`GCRY_CIPHER_MODE_CFB' 1204 Cipher Feedback mode. 1205 1206`GCRY_CIPHER_MODE_CBC' 1207 Cipher Block Chaining mode. 1208 1209`GCRY_CIPHER_MODE_STREAM' 1210 Stream mode, only to be used with stream cipher algorithms. 1211 1212`GCRY_CIPHER_MODE_OFB' 1213 Outer Feedback mode. 1214 1215`GCRY_CIPHER_MODE_CTR' 1216 Counter mode. 1217 1218 1219 1220File: gcrypt.info, Node: Working with cipher handles, Next: General cipher functions, Prev: Available cipher modes, Up: Symmetric cryptography 1221 12225.4 Working with cipher handles 1223=============================== 1224 1225To use a cipher algorithm, you must first allocate an according handle. 1226This is to be done using the open function: 1227 1228 -- Function: gcry_error_t gcry_cipher_open (gcry_cipher_hd_t *HD, int 1229 ALGO, int MODE, unsigned int FLAGS) 1230 This function creates the context handle required for most of the 1231 other cipher functions and returns a handle to it in `hd'. In 1232 case of an error, an according error code is returned. 1233 1234 The ID of algorithm to use must be specified via ALGO. See *Note 1235 Available ciphers::, for a list of supported ciphers and the 1236 according constants. 1237 1238 Besides using the constants directly, the function 1239 `gcry_cipher_map_name' may be used to convert the textual name of 1240 an algorithm into the according numeric ID. 1241 1242 The cipher mode to use must be specified via MODE. See *Note 1243 Available cipher modes::, for a list of supported cipher m…
Large files files are truncated, but you can click here to view the full file