« back to all changes in this revision
Viewing changes to doc/gcrypt.info
- browse files at revision 18
- compare with another revision
- download diff
- download tarball
- view history from revision 18
- Committer: Bazaar Package Importer
- Author(s): Bhavani Shankar
- Date: 2009-05-16 20:13:32 UTC
- mfrom: (1.1.6 upstream) (2.1.3 squeeze)
- Revision ID: james.westby@ubuntu.com-20090516201332-czkobpu32w318i16
Tags: 1.4.4-2ubuntu1
* Merge from Debian unstable (LP: #364535), remaining changes:
- Add libgcrypt11-udeb for use by cryptsetup-udeb.
- Add clean-la.mk, and add a symlink for the .la
- Install to /lib.
- Add libgcrypt11-udeb for use by cryptsetup-udeb.
- Add clean-la.mk, and add a symlink for the .la
- Install to /lib.
- files added:
- cipher/hash-common.c
- random
- files removed:
- BUGS
- files modified:
- AUTHORS
added
removed
doc/gcrypt.info
1
This is gcrypt.info, produced by makeinfo version 4.8 from gcrypt.texi.
2
3
This manual is for Libgcrypt (version 1.4.1, 4 January 2008), which
4
is GNU's library of cryptographic building blocks.
5
6
Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007 Free Software
1
This is gcrypt.info, produced by makeinfo version 4.11 from gcrypt.texi.
2
3
This manual is for Libgcrypt (version 1.4.4, 22 January 2009), which is
4
GNU's library of cryptographic building blocks.
5
6
Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008 Free Software
7
7
Foundation, Inc.
8
8
9
9
Permission is granted to copy, distribute and/or modify this
10
10
document under the terms of the GNU General Public License as
11
11
published by the Free Software Foundation; either version 2 of the
12
12
License, or (at your option) any later version. The text of the
13
license can be found in the section entitled "Copying".
13
license can be found in the section entitled "GNU General Public
14
License".
14
15
15
16
INFO-DIR-SECTION GNU Libraries
16
17
START-INFO-DIR-ENTRY
23
24
The Libgcrypt Library
24
25
*********************
25
26
26
This manual is for Libgcrypt (version 1.4.1, 4 January 2008), which is
27
This manual is for Libgcrypt (version 1.4.4, 22 January 2009), which is
27
28
GNU's library of cryptographic building blocks.
28
29
29
Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007 Free Software
30
Copyright (C) 2000, 2002, 2003, 2004, 2006, 2007, 2008 Free Software
30
31
Foundation, Inc.
31
32
32
33
Permission is granted to copy, distribute and/or modify this
33
34
document under the terms of the GNU General Public License as
34
35
published by the Free Software Foundation; either version 2 of the
35
36
License, or (at your option) any later version. The text of the
36
license can be found in the section entitled "Copying".
37
license can be found in the section entitled "GNU General Public
38
License".
37
39
38
40
* Menu:
39
41
42
44
* Generalities:: General library functions and data types.
43
45
* Handler Functions:: Working with handler functions.
44
46
* Symmetric cryptography:: How to use symmetric cryptography.
45
* Hashing:: How to use hashing.
46
* Public Key cryptography (I):: How to use public key cryptography.
47
* Public Key cryptography (II):: How to use public key cryptography, alternatively.
47
* Public Key cryptography:: How to use public key cryptography.
48
* Hashing:: How to use hash and MAC algorithms.
48
49
* Random Numbers:: How to work with random numbers.
49
50
* S-expressions:: How to manage S-expressions.
50
51
* MPI library:: How to work with multi-precision-integers.
51
52
* Prime numbers:: How to use the Prime number related functions.
52
53
* Utilities:: Utility functions.
54
* Architecture:: How Libgcrypt works internally.
53
55
54
56
Appendices
55
57
58
* Self-Tests:: Description of the self-tests.
59
* FIPS Mode:: Description of the FIPS mode.
56
60
* Library Copying:: The GNU Lesser General Public License
57
61
says how you can copy and share Libgcrypt.
58
62
* Copying:: The GNU General Public License says how you
60
64
61
65
Indices
62
66
67
* Figures and Tables:: Index of figures and tables.
63
68
* Concept Index:: Index of concepts and programs.
64
69
* Function and Data Index:: Index of functions, variables and data types.
65
70
66
--- The Detailed Node Listing ---
67
68
Introduction
69
* Getting Started:: How to use this manual.
70
* Features:: A glance at Libgcrypt's features.
71
* Overview:: Overview about the library.
72
73
Preparation
74
* Header:: What header file you need to include.
75
* Building sources:: How to build sources using the library.
76
* Building sources using Automake:: How to build sources with the help of Automake.
77
* Initializing the library:: How to initialize the library.
78
* Multi-Threading:: How Libgcrypt can be used in a MT environment.
79
80
Generalities
81
* Controlling the library:: Controlling Libgcrypt's behavior.
82
* Modules:: Description of extension modules.
83
* Error Handling:: Error codes and such.
84
85
Handler Functions
86
* Progress handler:: Using a progress handler function.
87
* Allocation handler:: Using special memory allocation functions.
88
* Error handler:: Using error handler functions.
89
* Logging handler:: Using a special logging function.
90
91
Symmetric cryptography
92
* Available ciphers:: List of ciphers supported by the library.
93
* Cipher modules:: How to work with cipher modules.
94
* Available cipher modes:: List of cipher modes supported by the library.
95
* Working with cipher handles:: How to perform operations related to cipher handles.
96
* General cipher functions:: General cipher functions independent of cipher handles.
97
98
Hashing
99
* Available hash algorithms:: List of hash algorithms supported by the library.
100
* Hash algorithm modules:: How to work with hash algorithm modules.
101
* Working with hash algorithms:: List of functions related to hashing.
102
103
Public Key cryptography (I)
104
* Used S-expressions:: Introduction into the used S-expression.
105
* Available algorithms:: Algorithms supported by the library.
106
* Public key modules:: How to work with public key modules.
107
* Cryptographic Functions:: Functions for performing the cryptographic actions.
108
* General public-key related Functions:: General functions, not implementing any cryptography.
109
110
Public Key cryptography (II)
111
* Available asymmetric algorithms:: List of algorithms supported by the library.
112
* Working with sets of data:: How to work with sets of data.
113
* Working with handles:: How to use handles.
114
* Working with keys:: How to work with keys.
115
* Using cryptographic functions:: How to perform cryptographic operations.
116
* Handle-independent functions:: General functions independent of handles.
117
118
Random Numbers
119
* Quality of random numbers:: Libgcrypt uses different quality levels.
120
* Retrieving random numbers:: How to retrieve random numbers.
121
122
S-expressions
123
* Data types for S-expressions:: Data types related with S-expressions.
124
* Working with S-expressions:: How to work with S-expressions.
125
126
MPI library
127
* Data types:: MPI related data types.
128
* Basic functions:: First steps with MPI numbers.
129
* MPI formats:: External representation of MPIs.
130
* Calculations:: Performing MPI calculations.
131
* Comparisons:: How to compare MPI values.
132
* Bit manipulations:: How to access single bits of MPI values.
133
* Miscellaneous:: Miscellaneous MPI functions.
134
135
Prime numbers
136
* Generation:: Generation of new prime numbers.
137
* Checking:: Checking if a given number is prime.
138
139
Utilities
140
* Memory allocation:: Functions related with memory allocation.
141
142
71
143
72
File: gcrypt.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top
144
73
187
116
It's Free Software
188
117
Anybody can use, modify, and redistribute it under the terms of
189
118
the GNU Lesser General Public License (*note Library Copying::).
190
Note, that some parts (which are not needed on a GNU or GNU/Linux
191
system) are subject to the terms of the GNU General Public License
192
(*note Copying::); please see the README file of the distribution
193
for of list of these parts.
119
Note, that some parts (which are in general not needed by
120
applications) are subject to the terms of the GNU General Public
121
License (*note Copying::); please see the README file of the
122
distribution for of list of these parts.
194
123
195
124
It encapsulates the low level cryptography
196
125
Libgcrypt provides a high level interface to cryptographic
232
161
* Building sources using Automake:: How to build sources with the help of Automake.
233
162
* Initializing the library:: How to initialize the library.
234
163
* Multi-Threading:: How Libgcrypt can be used in a MT environment.
164
* Enabling FIPS mode:: How to enable the FIPS mode.
235
165
236
166
237
167
File: gcrypt.info, Node: Header, Next: Building sources, Up: Preparation
259
189
Do not define the shorthand macros `mpi_*' for `gcry_mpi_*'.
260
190
261
191
`GCRYPT_NO_DEPRECATED'
262
Do not include defintions for deprecated features.
192
Do not include defintions for deprecated features. This is useful
193
to make sure that no deprecated features are used.
263
194
264
195
265
196
File: gcrypt.info, Node: Building sources, Next: Building sources using Automake, Prev: Header, Up: Preparation
348
279
So you may want to check that the version is okay right after program
349
280
startup.
350
281
351
-- Function: const char *gcry_check_version (const char *REQ_VERSION)
352
The function `gcry_check_version' initializes the sub-systems used
282
-- Function: const char * gcry_check_version (const char *REQ_VERSION)
283
The function `gcry_check_version' initializes some subsystems used
353
284
by Libgcrypt and must be invoked before any other function in the
354
library, with the exception of the `GCRYCTL_SET_THREAD_CBS'
355
command (called via the `gcry_control' function), see *Note
356
Multi-Threading::.
285
library, with the exception of the `GCRYCTL_SET_THREAD_CBS' command
286
(called via the `gcry_control' function). *Note Multi-Threading::.
357
287
358
288
Furthermore, this function returns the version number of the
359
289
library. It can also verify that the version number is higher
360
290
than a certain required version number REQ_VERSION, if this value
361
291
is not a null pointer.
362
292
293
Libgcrypt uses a concept known as secure memory, which is a region of
294
memory set aside for storing sensitive data. Because such memory is a
295
scarce resource, it needs to be setup in advanced to a fixed size.
296
Further, most operating systems have special requirements on how that
297
secure memory can be used. For example, it might be required to install
298
an application as "setuid(root)" to allow allocating such memory.
299
Libgcrypt requires a sequence of initialization steps to make sure that
300
this works correctly. The following examples show the necessary steps.
301
302
If you don't have a need for secure memory, for example if your
303
application does not use secret keys or other confidential data or it
304
runs in a controlled environment where key material floating around in
305
memory is not a problem, you should initialize Libgcrypt this way:
306
307
/* Version check should be the very first call because it
308
makes sure that important subsystems are intialized. */
309
if (!gcry_check_version (GCRYPT_VERSION))
310
{
311
fputs ("libgcrypt version mismatch\n", stderr);
312
exit (2);
313
}
314
315
/* Disable secure memory. */
316
gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
317
318
/* ... If required, other initialization goes here. */
319
320
/* Tell Libgcrypt that initialization has completed. */
321
gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
322
323
If you have to protect your keys or other information in memory
324
against being swapped out to disk and to enable an automatic overwrite
325
of used and freed memory, you need to initialize Libgcrypt this way:
326
327
/* Version check should be the very first call because it
328
makes sure that important subsystems are intialized. */
329
if (!gcry_check_version (GCRYPT_VERSION))
330
{
331
fputs ("libgcrypt version mismatch\n", stderr);
332
exit (2);
333
}
334
335
/* We don't want to see any warnings, e.g. because we have not yet
336
parsed program options which might be used to suppress such
337
warnings. */
338
gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
339
340
/* ... If required, other initialization goes here. Note that the
341
process might still be running with increased privileges and that
342
the secure memory has not been intialized. */
343
344
/* Allocate a pool of 16k secure memory. This make the secure memory
345
available and also drops privileges where needed. */
346
gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
347
348
/* It is now okay to let Libgcrypt complain when there was/is
349
a problem with the secure memory. */
350
gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
351
352
/* ... If required, other initialization goes here. */
353
354
/* Tell Libgcrypt that initialization has completed. */
355
gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
356
357
It is important that these initialization steps are not done by a
358
library but by the actual application. A library using Libgcrypt might
359
want to check for finished initialization using:
360
361
if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
362
{
363
fputs ("libgcrypt has not been initialized\n", stderr);
364
abort ();
365
}
366
367
Instead of terminating the process, the library may instead print a
368
warning and try to initialize Libgcrypt itself. See also the section on
369
multi-threading below for more pitfalls.
370
363
371
364
File: gcrypt.info, Node: Multi-Threading, Prev: Initializing the library, Up: Preparation
372
File: gcrypt.info, Node: Multi-Threading, Next: Enabling FIPS mode, Prev: Initializing the library, Up: Preparation
365
373
366
374
2.5 Multi-Threading
367
375
===================
410
418
For this, it is sufficient to call `gcry_check_version' before
411
419
creating the other threads using Libgcrypt(1).
412
420
413
* Just like the function `gpg_strerror', the function
421
* Just like the function `gpg_strerror', the function
414
422
`gcry_strerror' is not thread safe. You have to use
415
423
`gpg_strerror_r' instead.
416
424
425
417
426
Libgcrypt contains convenient macros, which define the necessary
418
427
thread callbacks for PThread and for GNU Pth:
419
428
420
429
`GCRY_THREAD_OPTION_PTH_IMPL'
421
This macro defines the following (static) symbols: gcry_pth_init,
422
gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,
423
gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write,
424
gcry_pth_select, gcry_pth_waitpid, gcry_pth_accept,
425
gcry_pth_connect, gcry_threads_pth.
430
This macro defines the following (static) symbols:
431
`gcry_pth_init', `gcry_pth_mutex_init', `gcry_pth_mutex_destroy',
432
`gcry_pth_mutex_lock', `gcry_pth_mutex_unlock', `gcry_pth_read',
433
`gcry_pth_write', `gcry_pth_select', `gcry_pth_waitpid',
434
`gcry_pth_accept', `gcry_pth_connect', `gcry_threads_pth'.
426
435
427
After including this macro, gcry_control() shall be used with a
428
command of GCRYCTL_SET_THREAD_CBS in order to register the thread
429
callback structure named "gcry_threads_pth".
436
After including this macro, `gcry_control()' shall be used with a
437
command of `GCRYCTL_SET_THREAD_CBS' in order to register the
438
thread callback structure named "gcry_threads_pth".
430
439
431
440
`GCRY_THREAD_OPTION_PTHREAD_IMPL'
432
441
This macro defines the following (static) symbols:
433
gcry_pthread_mutex_init, gcry_pthread_mutex_destroy,
434
gcry_mutex_lock, gcry_mutex_unlock, gcry_threads_pthread.
442
`gcry_pthread_mutex_init', `gcry_pthread_mutex_destroy',
443
`gcry_pthread_mutex_lock', `gcry_pthread_mutex_unlock',
444
`gcry_threads_pthread'.
435
445
436
After including this macro, gcry_control() shall be used with a
437
command of GCRYCTL_SET_THREAD_CBS in order to register the thread
438
callback structure named "gcry_threads_pthread".
446
After including this macro, `gcry_control()' shall be used with a
447
command of `GCRYCTL_SET_THREAD_CBS' in order to register the
448
thread callback structure named "gcry_threads_pthread".
439
449
440
450
Note that these macros need to be terminated with a semicolon. Keep
441
451
in mind that these are convenient macros for C programmers; C++
451
461
packages, more relaxed or more strict rules may apply.
452
462
453
463
464
File: gcrypt.info, Node: Enabling FIPS mode, Prev: Multi-Threading, Up: Preparation
465
466
2.6 How to enable the FIPS mode
467
===============================
468
469
Libgcrypt may be used in a FIPS 140-2 mode. Note, that this does not
470
necessary mean that Libcgrypt is an appoved FIPS 140-2 module. Check
471
the NIST database at `http://csrc.nist.gov/groups/STM/cmvp/' to see what
472
versions of Libgcrypt are approved.
473
474
Because FIPS 140 has certain restrictions on the use of cryptography
475
which are not always wanted, Libgcrypt needs to be put into FIPS mode
476
explicitly. Three alternative mechanisms are provided to switch
477
Libgcrypt into this mode:
478
479
* If the file `/proc/sys/crypto/fips_enabled' exists and contains a
480
numeric value other than `0', Libgcrypt is put into FIPS mode at
481
initialization time. Obviously this works only on systems with a
482
`proc' file system (i.e. GNU/Linux).
483
484
* If the file `/etc/gcrypt/fips_enabled' exists, Libgcrypt is put
485
into FIPS mode at initialization time. Note that this filename is
486
hardwired and does not depend on any configuration options.
487
488
* If the application requests FIPS mode using the control command
489
`GCRYCTL_FORCE_FIPS_MODE'. This must be done prior to any
490
initialization (i.e. before `gcry_check_version').
491
492
493
In addition to the standard FIPS mode, Libgcrypt may also be put into
494
an Enforced FIPS mode by writing a non-zero value into the file
495
`/etc/gcrypt/fips_enabled'. The Enforced FIPS mode helps to detect
496
applications which don't fulfill all requirements for using Libgcrypt
497
in FIPS mode (*note FIPS Mode::).
498
499
Once Libgcrypt has been put into FIPS mode, it is not possible to
500
switch back to standard mode without terminating the process first. If
501
the logging verbosity level of Libgcrypt has been set to at least 2,
502
the state transitions and the self-tests are logged.
503
504
454
505
File: gcrypt.info, Node: Generalities, Next: Handler Functions, Prev: Preparation, Up: Top
455
506
456
507
3 Generalities
493
544
494
545
This option can only be used at initialization time.
495
546
496
`GCRYCTL_DUMP_RANDOM_STATS'
497
This command dumps PRNG related statistics to the librarys
498
logging stream.
499
500
`GCRYCTL_DUMP_MEMORY_STATS'
501
This command dumps memory manamgent related statistics to the
502
librarys logging stream.
503
504
`GCRYCTL_DUMP_SECMEM_STATS'
547
`GCRYCTL_DUMP_RANDOM_STATS; Arguments: none'
548
This command dumps randum number generator related statistics
549
to the library's logging stream.
550
551
`GCRYCTL_DUMP_MEMORY_STATS; Arguments: none'
552
This command dumps memory managment related statistics to the
553
library's logging stream.
554
555
`GCRYCTL_DUMP_SECMEM_STATS; Arguments: none'
505
556
This command dumps secure memory manamgent related statistics
506
to the librarys logging stream.
507
508
`GCRYCTL_DUMP_CONFIG; Arguments: none'
509
This command dumps information pertaining to the
510
configuration of libgcrypt to the logging stream. It may be
511
used before the intialization has been finished but not
512
before a gcry_version_check.
513
514
`GCRYCTL_DROP_PRIVS'
557
to the library's logging stream.
558
559
`GCRYCTL_DROP_PRIVS; Arguments: none'
515
560
This command disables the use of secure memory and drops the
516
priviliges of the current process. FIXME.
561
priviliges of the current process. This command has not much
562
use; the suggested way to disable secure memory is to use
563
`GCRYCTL_DISABLE_SECMEM' right after initialization.
517
564
518
`GCRYCTL_DISABLE_SECMEM'
519
This command disables the use of secure memory.
565
`GCRYCTL_DISABLE_SECMEM; Arguments: none'
566
This command disables the use of secure memory. If this
567
command is used in FIPS mode, FIPS mode will be disabled and
568
the function `gcry_fips_mode_active' returns false. However,
569
in Enforced FIPS mode this command has no effect at all.
520
570
521
571
Many applications do not require secure memory, so they
522
should disable it right away. There won't be a problem if
523
not disabling it unless one makes use of a feature which
524
requires secure memory - in that case the process will abort
525
because the secmem is not initialized.
526
527
`GCRYCTL_INIT_SECMEM'
528
529
`GCRYCTL_TERM_SECMEM'
530
531
`GCRYCTL_DISABLE_SECMEM_WARN'
532
533
`GCRYCTL_SUSPEND_SECMEM_WARN'
534
535
`GCRYCTL_RESUME_SECMEM_WARN'
572
should disable it right away. This command should be
573
executed right after `gcry_check_version'.
574
575
`GCRYCTL_INIT_SECMEM; Arguments: int nbytes'
576
This command is used to allocate a pool of secure memory and
577
thus enabling the use of secure memory. It also drops all
578
extra privileges the process has (i.e. if it is run as setuid
579
(root)). If the argument NBYTES is 0, secure memory will be
580
disabled. The minimum amount of secure memory allocated is
581
currently 16384 bytes; you may thus use a value of 1 to
582
request that default size.
583
584
`GCRYCTL_TERM_SECMEM; Arguments: none'
585
This command zeroises the secure memory and destroys the
586
handler. The secure memory pool may not be used anymore
587
after running this command. If the secure memory pool as
588
already been destroyed, this command has no effect.
589
Applications might want to run this command from their exit
590
handler to make sure that the secure memory gets properly
591
destroyed. This command is not necessarily thread-safe but
592
that should not be needed in cleanup code. It may be called
593
from a signal handler.
594
595
`GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none'
596
Disable warning messages about problems with the secure memory
597
subsystem. This command should be run right after
598
`gcry_check_version'.
599
600
`GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none'
601
Postpone warning messages from the secure memory subsystem.
602
*Note the initialization example: sample-use-suspend-secmem,
603
on how to use it.
604
605
`GCRYCTL_RESUME_SECMEM_WARN; Arguments: none'
606
Resume warning messages from the secure memory subsystem.
607
*Note the initialization example: sample-use-resume-secmem,
608
on how to use it.
536
609
537
610
`GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none'
538
611
This command tells the PRNG to store random numbers in secure
539
memory. FIXME: what about initialization time?
612
memory. This command should be run right after
613
`gcry_check_version' and not later than the command
614
GCRYCTL_INIT_SECMEM. Note that in FIPS mode the secure
615
memory is always used.
540
616
541
617
`GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename'
542
618
This command specifies the file, which is to be used as seed
569
645
gets mixed. It is also not an issue when using Linux
570
646
(rndlinux driver), because this one guarantees to read full
571
647
16 bytes from /dev/urandom and thus there is no way for an
572
attacker without kernel access to conrol these 16 bytes.
573
574
`GCRYCTL_SET_VERBOSITY'
575
576
`GCRYCTL_SET_DEBUG_FLAGS'
577
578
`GCRYCTL_CLEAR_DEBUG_FLAGS'
579
580
`GCRYCTL_DISABLE_INTERNAL_LOCKING'
581
582
`GCRYCTL_ANY_INITIALIZATION_P'
583
584
`GCRYCTL_INITIALIZATION_FINISHED_P'
585
586
`GCRYCTL_INITIALIZATION_FINISHED'
648
attacker without kernel access to control these 16 bytes.
649
650
`GCRYCTL_SET_VERBOSITY; Arguments: int level'
651
This command sets the verbosity of the logging. A level of 0
652
disables all extra logging whereas positive numbers enable
653
more verbose logging. The level may be changed at any time
654
but be aware that no memory synchronization is done so the
655
effect of this command might not immediately show up in other
656
threads. This command may even be used prior to
657
`gcry_check_version'.
658
659
`GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags'
660
Set the debug flag bits as given by the argument. Be aware
661
that that no memory synchronization is done so the effect of
662
this command might not immediately show up in other threads.
663
The debug flags are not considered part of the API and thus
664
may change without notice. As of now bit 0 enables debugging
665
of cipher functions and bit 1 debugging of
666
multi-precision-integers. This command may even be used
667
prior to `gcry_check_version'.
668
669
`GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags'
670
Set the debug flag bits as given by the argument. Be aware
671
that that no memory synchronization is done so the effect of
672
this command might not immediately show up in other threads.
673
This command may even be used prior to `gcry_check_version'.
674
675
`GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none'
676
This command does nothing. It exists only for backward
677
compatibility.
678
679
`GCRYCTL_ANY_INITIALIZATION_P; Arguments: none'
680
This command returns true if the library has been basically
681
initialized. Such a basic initialization happens implicitly
682
with many commands to get certain internal subsystems
683
running. The common and suggested way to do this basic
684
intialization is by calling gcry_check_version.
685
686
`GCRYCTL_INITIALIZATION_FINISHED; Arguments: none'
687
This command tells the libray that the application has
688
finished the intialization.
689
690
`GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none'
691
This command returns true if the command
692
GCRYCTL_INITIALIZATION_FINISHED has already been run.
587
693
588
694
`GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops'
589
This command registers a thread-callback structure. See
590
section "multi threading" for more information on this
591
command.
695
This command registers a thread-callback structure. *Note
696
Multi-Threading::.
592
697
593
`GCRYCTL_FAST_POLL'
698
`GCRYCTL_FAST_POLL; Arguments: none'
594
699
Run a fast random poll.
595
700
596
701
`GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename'
601
706
error if the given filename is too long for a local socket
602
707
name.
603
708
604
EGD is an alternative random gatherer, used only on a few
605
systems.
709
EGD is an alternative random gatherer, used only on systems
710
lacking a proper random device.
711
712
`GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream'
713
This command dumps information pertaining to the
714
configuration of the library to the given stream. If NULL is
715
given for STREAM, the log system is used. This command may
716
be used before the intialization has been finished but not
717
before a gcry_version_check.
718
719
`GCRYCTL_OPERATIONAL_P; Arguments: none'
720
This command returns true if the library is in an operational
721
state. This information makes only sense in FIPS mode. In
722
contrast to other functions, this is a pure test function and
723
won't put the library into FIPS mode or change the internal
724
state. This command may be used before the intialization has
725
been finished but not before a gcry_version_check.
726
727
`GCRYCTL_FIPS_MODE_P; Arguments: none'
728
This command returns true if the library is in FIPS mode.
729
Note, that this is no indication about the current state of
730
the library. This command may be used before the
731
intialization has been finished but not before a
732
gcry_version_check. An application may use this command or
733
the convenience macro below to check whether FIPS mode is
734
actually active.
735
736
-- Function: int gcry_fips_mode_active (void)
737
Returns true if the FIPS mode is active. Note that this
738
is implemented as a macro.
739
740
`GCRYCTL_FORCE_FIPS_MODE; Arguments: none'
741
Running this command puts the library into FIPS mode. If the
742
library is already in FIPS mode, a self-test is triggered and
743
thus the library will be put into operational state. This
744
command may be used before a call to gcry_check_version and
745
that is actually the recommended way to let an application
746
switch the library into FIPS mode. Note that Libgcrypt will
747
reject an attempt to switch to fips mode during or after the
748
intialization.
749
750
`GCRYCTL_SELFTEST; Arguments: none'
751
This may be used at anytime to have the library run all
752
implemented self-tests. It works in standard and in FIPS
753
mode. Returns 0 on success or an error code on failure.
606
754
607
755
608
756
799
947
`GPG_ERR_SOURCE_UNKNOWN'.
800
948
801
949
The list of error sources that might occur in applications using
802
Libgctypt is:
950
Libgcrypt is:
803
951
804
952
`GPG_ERR_SOURCE_UNKNOWN'
805
953
The error source is not known. The value of this error source is
928
1076
This value means a verification failed because the public key is
929
1077
not available.
930
1078
1079
`GPG_ERR_NOT_OPERATIONAL'
1080
This value means that the library is not yet in state which allows
1081
to use this function. This error code is in particular returned if
1082
Libgcrypt is operated in FIPS mode and the internal state of the
1083
library does not yet or not anymore allow the use of a service.
1084
1085
This error code is only available with newer libgpg-error
1086
versions, thus you might see "invalid error code" when passing
1087
this to `gpg_strerror'. The numeric value of this error code is
1088
176.
1089
931
1090
`GPG_ERR_USER_1'
932
1091
933
1092
`GPG_ERR_USER_2'
966
1125
gcry_cipher_hd_t handle;
967
1126
gcry_error_t err = 0;
968
1127
969
err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
1128
err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
1129
GCRY_CIPHER_MODE_CBC, 0);
970
1130
if (err)
971
1131
{
972
1132
fprintf (stderr, "Failure: %s/%s\n",
1012
1172
1013
1173
-- Function: void gcry_set_progress_handler (gcry_handler_progress_t
1014
1174
CB, void *CB_DATA)
1015
This function installs CB as the `Progress handler' function. CB
1016
must be defined as follows:
1175
This function installs CB as the `Progress handler' function. It
1176
may be used only during initialization. CB must be defined as
1177
follows:
1017
1178
1018
1179
void
1019
1180
my_progress_handler (void *CB_DATA, const char *WHAT,
1097
1258
gcry_handler_realloc_t FUNC_REALLOC, gcry_handler_free_t
1098
1259
FUNC_FREE)
1099
1260
Install the provided functions and use them instead of the built-in
1100
functions for doing memory allocation.
1261
functions for doing memory allocation. Using this function is in
1262
general not recommended because the standard Libgcrypt allocation
1263
functions are guaranteed to zeroize memory if needed.
1264
1265
This function may be used only during initialization and may not be
1266
used in fips mode.
1267
1101
1268
1102
1269
1103
1270
File: gcrypt.info, Node: Error handler, Next: Logging handler, Prev: Allocation handler, Up: Handler Functions
1106
1273
=================
1107
1274
1108
1275
The following functions may be used to register handler functions that
1109
are called by Libgcrypt in case certain error conditions occur.
1276
are called by Libgcrypt in case certain error conditions occur. They
1277
may and should be registered prior to calling `gcry_check_version'.
1110
1278
1111
1279
-- Data type: gcry_handler_no_mem_t
1112
This type is defined as: `void (*gcry_handler_no_mem_t) (void *,
1280
This type is defined as: `int (*gcry_handler_no_mem_t) (void *,
1113
1281
size_t, unsigned int)'
1114
1282
1115
1283
-- Function: void gcry_set_outofcore_handler (gcry_handler_no_mem_t
1116
1284
FUNC_NO_MEM, void *CB_DATA)
1117
1285
This function registers FUNC_NO_MEM as `out-of-core handler',
1118
1286
which means that it will be called in the case of not having enough
1119
memory available.
1287
memory available. The handler is called with 3 arguments: The
1288
first one is the pointer CB_DATA as set with this function, the
1289
second is the requested memory size and the last being a flag. If
1290
bit 0 of the flag is set, secure memory has been requested. The
1291
handler should either return true to indicate that Libgcrypt
1292
should try again allocating memory or return false to let
1293
Libgcrypt use its default fatal error handler.
1120
1294
1121
1295
-- Data type: gcry_handler_error_t
1122
1296
This type is defined as: `void (*gcry_handler_error_t) (void *,
1141
1315
void *CB_DATA)
1142
1316
This function registers FUNC_LOG as `logging handler', which means
1143
1317
that it will be called in case Libgcrypt wants to log a message.
1318
This function may and should be used prior to calling
1319
`gcry_check_version'.
1144
1320
1145
1321
1146
File: gcrypt.info, Node: Symmetric cryptography, Next: Hashing, Prev: Handler Functions, Up: Top
1322
File: gcrypt.info, Node: Symmetric cryptography, Next: Public Key cryptography, Prev: Handler Functions, Up: Top
1147
1323
1148
1324
5 Symmetric cryptography
1149
1325
************************
1366
1542
==========================
1367
1543
1368
1544
`GCRY_CIPHER_MODE_NONE'
1369
No mode specified, may be set later using other functions. The
1370
value of this constant is always 0.
1545
No mode specified. This should not be used. The only exception
1546
is that if Libgcrypt is not used in FIPS mode and if any debug
1547
flag has been set, this mode may be used to bypass the actual
1548
encryption.
1371
1549
1372
1550
`GCRY_CIPHER_MODE_ECB'
1373
1551
Electronic Codebook mode.
1374
1552
1375
1553
`GCRY_CIPHER_MODE_CFB'
1376
Cipher Feedback mode.
1554
Cipher Feedback mode. The shift size equals the block size of the
1555
cipher (e.g. for AES it is CFB-128).
1377
1556
1378
1557
`GCRY_CIPHER_MODE_CBC'
1379
1558
Cipher Block Chaining mode.
1415
1594
Available cipher modes::, for a list of supported cipher modes and
1416
1595
the according constants. Note that some modes are incompatible
1417
1596
with some algorithms - in particular, stream mode
1418
(GCRY_CIPHER_MODE_STREAM) only works with stream ciphers. Any block
1419
cipher mode (GCRY_CIPHER_MODE_ECB, GCRY_CIPHER_MODE_CBC,
1420
GCRY_CIPHER_MODE_CFB, GCRY_CIPHER_MODE_OFB or GCRY_CIPHER_MODE_CTR)
1421
will work with any block cipher algorithm.
1597
(`GCRY_CIPHER_MODE_STREAM') only works with stream ciphers. Any
1598
block cipher mode (`GCRY_CIPHER_MODE_ECB', `GCRY_CIPHER_MODE_CBC',
1599
`GCRY_CIPHER_MODE_CFB', `GCRY_CIPHER_MODE_OFB' or
1600
`GCRY_CIPHER_MODE_CTR') will work with any block cipher algorithm.
1422
1601
1423
1602
The third argument FLAGS can either be passed as `0' or as the
1424
1603
bit-wise OR of the following constants.
1452
1631
In order to use a handle for performing cryptographic operations, a
1453
1632
`key' has to be set first:
1454
1633
1455
-- Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H, void
1456
*K, size_t L)
1634
-- Function: gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t H,
1635
const void *K, size_t L)
1457
1636
Set the key K used for encryption or decryption in the context
1458
1637
denoted by the handle H. The length L of the key K must match the
1459
1638
required length of the algorithm set for this context or be in the
1461
1640
checks this and returns an error if there is a problem. A caller
1462
1641
should always check for an error.
1463
1642
1464
Note that this is currently implemented as a macro but may be
1465
changed to a function in the future.
1466
1643
1467
1644
Most crypto modes requires an initialization vector (IV), which
1468
1645
usually is a non-secret random string acting as a kind of salt value.
1469
1646
The CTR mode requires a counter, which is also similar to a salt value.
1470
1647
To set the IV or CTR, use these functions:
1471
1648
1472
-- Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, void
1473
*K, size_t L)
1649
-- Function: gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t H, const
1650
void *K, size_t L)
1474
1651
Set the initialization vector used for encryption or decryption.
1475
1652
The vector is passed as the buffer K of length L and copied to
1476
1653
internal data structures. The function checks that the IV matches
1477
the requirement of the selected algorithm and mode. Note that
1478
this is implemented as a macro.
1654
the requirement of the selected algorithm and mode.
1479
1655
1480
-- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H, void
1481
*C, size_t L)
1656
-- Function: gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t H,
1657
const void *C, size_t L)
1482
1658
Set the counter vector used for encryption or decryption. The
1483
1659
counter is passed as the buffer C of length L and copied to
1484
1660
internal data structures. The function checks that the counter
1485
1661
matches the requirement of the selected algorithm (i.e., it must be
1486
the same size as the block size). Note that this is implemented
1487
as a macro.
1662
the same size as the block size).
1488
1663
1489
1664
-- Function: gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t H)
1490
1665
Set the given handle's context back to the state it had after the
1601
1776
1602
1777
1603
1778
1604
-- Function: const char *gcry_cipher_algo_name (int ALGO)
1779
-- Function: const char * gcry_cipher_algo_name (int ALGO)
1605
1780
`gcry_cipher_algo_name' returns a string with the name of the
1606
1781
cipher algorithm ALGO. If the algorithm is not known or another
1607
1782
error occurred, the string `"?"' is returned. This function should
1619
1794
identifier or when no mode is associated with it.
1620
1795
1621
1796
1622
File: gcrypt.info, Node: Hashing, Next: Public Key cryptography (I), Prev: Symmetric cryptography, Up: Top
1623
1624
6 Hashing
1625
*********
1626
1627
Libgcrypt provides an easy and consistent to use interface for hashing.
1628
Hashing is buffered and several hash algorithms can be updated at
1629
once. It is possible to calculate a MAC using the same routines. The
1630
programming model follows an open/process/close paradigm and is in that
1631
similar to other building blocks provided by Libgcrypt.
1632
1633
For convenience reasons, a few cyclic redundancy check value
1634
operations are also supported.
1635
1636
* Menu:
1637
1638
* Available hash algorithms:: List of hash algorithms supported by the library.
1639
* Hash algorithm modules:: How to work with hash algorithm modules.
1640
* Working with hash algorithms:: List of functions related to hashing.
1641
1642
1643
File: gcrypt.info, Node: Available hash algorithms, Next: Hash algorithm modules, Up: Hashing
1644
1645
6.1 Available hash algorithms
1646
=============================
1647
1648
`GCRY_MD_NONE'
1649
This is not a real algorithm but used by some functions as an error
1650
return value. This constant is guaranteed to have the value `0'.
1651
1652
`GCRY_MD_SHA1'
1653
This is the SHA-1 algorithm which yields a message digest of 20
1654
bytes.
1655
1656
`GCRY_MD_RMD160'
1657
This is the 160 bit version of the RIPE message digest
1658
(RIPE-MD-160). Like SHA-1 it also yields a digest of 20 bytes.
1659
1660
`GCRY_MD_MD5'
1661
This is the well known MD5 algorithm, which yields a message
1662
digest of 16 bytes.
1663
1664
`GCRY_MD_MD4'
1665
This is the MD4 algorithm, which yields a message digest of 16
1666
bytes.
1667
1668
`GCRY_MD_MD2'
1669
This is an reserved identifier for MD-2; there is no
1670
implementation yet.
1671
1672
`GCRY_MD_TIGER'
1673
This is the TIGER/192 algorithm which yields a message digest of
1674
24 bytes.
1675
1676
`GCRY_MD_HAVAL'
1677
This is an reserved for the HAVAL algorithm with 5 passes and 160
1678
bit. It yields a message digest of 20 bytes. Note that there is no
1679
implementation yet available.
1680
1681
`GCRY_MD_SHA224'
1682
This is the SHA-224 algorithm which yields a message digest of 28
1683
bytes. See Change Notice 1 for FIPS 180-2 for the specification.
1684
1685
`GCRY_MD_SHA256'
1686
This is the SHA-256 algorithm which yields a message digest of 32
1687
bytes. See FIPS 180-2 for the specification.
1688
1689
`GCRY_MD_SHA384'
1690
This is the SHA-384 algorithm which yields a message digest of 48
1691
bytes. See FIPS 180-2 for the specification.
1692
1693
`GCRY_MD_SHA512'
1694
This is the SHA-384 algorithm which yields a message digest of 64
1695
bytes. See FIPS 180-2 for the specification.
1696
1697
`GCRY_MD_CRC32'
1698
This is the ISO 3309 and ITU-T V.42 cyclic redundancy check. It
1699
yields an output of 4 bytes.
1700
1701
`GCRY_MD_CRC32_RFC1510'
1702
This is the above cyclic redundancy check function, as modified by
1703
RFC 1510. It yields an output of 4 bytes.
1704
1705
`GCRY_MD_CRC24_RFC2440'
1706
This is the OpenPGP cyclic redundancy check function. It yields an
1707
output of 3 bytes.
1708
1709
`GCRY_MD_WHIRLPOOL'
1710
This is the Whirlpool algorithm which yields a message digest of 64
1711
bytes.
1712
1713
1714
1715
File: gcrypt.info, Node: Hash algorithm modules, Next: Working with hash algorithms, Prev: Available hash algorithms, Up: Hashing
1716
1717
6.2 Hash algorithm modules
1718
==========================
1719
1720
Libgcrypt makes it possible to load additional `message digest
1721
modules'; these digests can be used just like the message digest
1722
algorithms that are built into the library directly. For an
1723
introduction into extension modules, see *Note Modules::.
1724
1725
-- Data type: gcry_md_spec_t
1726
This is the `module specification structure' needed for registering
1727
message digest modules, which has to be filled in by the user
1728
before it can be used to register a module. It contains the
1729
following members:
1730
1731
`const char *name'
1732
The primary name of this algorithm.
1733
1734
`unsigned char *asnoid'
1735
Array of bytes that form the ASN OID.
1736
1737
`int asnlen'
1738
Length of bytes in `asnoid'.
1739
1740
`gcry_md_oid_spec_t *oids'
1741
A list of OIDs that are to be associated with the algorithm.
1742
The list's last element must have it's `oid' member set to
1743
NULL. See below for an explanation of this type. See below
1744
for an explanation of this type.
1745
1746
`int mdlen'
1747
Length of the message digest algorithm. See below for an
1748
explanation of this type.
1749
1750
`gcry_md_init_t init'
1751
The function responsible for initializing a handle. See
1752
below for an explanation of this type.
1753
1754
`gcry_md_write_t write'
1755
The function responsible for writing data into a message
1756
digest context. See below for an explanation of this type.
1757
1758
`gcry_md_final_t final'
1759
The function responsible for `finalizing' a message digest
1760
context. See below for an explanation of this type.
1761
1762
`gcry_md_read_t read'
1763
The function responsible for reading out a message digest
1764
result. See below for an explanation of this type.
1765
1766
`size_t contextsize'
1767
The size of the algorithm-specific `context', that should be
1768
allocated for each handle.
1769
1770
-- Data type: gcry_md_oid_spec_t
1771
This type is used for associating a user-provided algorithm
1772
implementation with certain OIDs. It contains the following
1773
members:
1774
1775
`const char *oidstring'
1776
Textual representation of the OID.
1777
1778
-- Data type: gcry_md_init_t
1779
Type for the `init' function, defined as: void (*gcry_md_init_t)
1780
(void *c)
1781
1782
-- Data type: gcry_md_write_t
1783
Type for the `write' function, defined as: void (*gcry_md_write_t)
1784
(void *c, unsigned char *buf, size_t nbytes)
1785
1786
-- Data type: gcry_md_final_t
1787
Type for the `final' function, defined as: void (*gcry_md_final_t)
1788
(void *c)
1789
1790
-- Data type: gcry_md_read_t
1791
Type for the `read' function, defined as: unsigned char
1792
*(*gcry_md_read_t) (void *c)
1793
1794
-- Function: gcry_error_t gcry_md_register (gcry_md_spec_t *DIGEST,
1795
unsigned int *algorithm_id, gcry_module_t *MODULE)
1796
Register a new digest module whose specification can be found in
1797
DIGEST. On success, a new algorithm ID is stored in ALGORITHM_ID
1798
and a pointer representing this module is stored in MODULE.
1799
1800
-- Function: void gcry_md_unregister (gcry_module_t MODULE)
1801
Unregister the digest identified by MODULE, which must have been
1802
registered with gcry_md_register.
1803
1804
-- Function: gcry_error_t gcry_md_list (int *LIST, int *LIST_LENGTH)
1805
Get a list consisting of the IDs of the loaded message digest
1806
modules. If LIST is zero, write the number of loaded message
1807
digest modules to LIST_LENGTH and return. If LIST is non-zero,
1808
the first *LIST_LENGTH algorithm IDs are stored in LIST, which
1809
must be of according size. In case there are less message digests
1810
modules than *LIST_LENGTH, *LIST_LENGTH is updated to the correct
1811
number.
1812
1813
1814
File: gcrypt.info, Node: Working with hash algorithms, Prev: Hash algorithm modules, Up: Hashing
1815
1816
6.3 Working with hash algorithms
1817
================================
1818
1819
To use most of these function it is necessary to create a context; this
1820
is done using:
1821
1822
-- Function: gcry_error_t gcry_md_open (gcry_md_hd_t *HD, int ALGO,
1823
unsigned int FLAGS)
1824
Create a message digest object for algorithm ALGO. FLAGS may be
1825
given as an bitwise OR of constants described below. ALGO may be
1826
given as `0' if the algorithms to use are later set using
1827
`gcry_md_enable'. HD is guaranteed to either receive a valid
1828
handle or NULL.
1829
1830
For a list of supported algorithms, see *Note Available hash
1831
algorithms::.
1832
1833
The flags allowed for MODE are:
1834
1835
`GCRY_MD_FLAG_SECURE'
1836
Allocate all buffers and the resulting digest in "secure
1837
memory". Use this is the hashed data is highly confidential.
1838
1839
`GCRY_MD_FLAG_HMAC'
1840
Turn the algorithm into a HMAC message authentication
1841
algorithm. This only works if just one algorithm is enabled
1842
for the handle. Note that the function `gcry_md_setkey' must
1843
be used to set the MAC key. If you want CBC message
1844
authentication codes based on a cipher, see *Note Working
1845
with cipher handles::.
1846
1847
1848
You may use the function `gcry_md_is_enabled' to later check
1849
whether an algorithm has been enabled.
1850
1851
1852
If you want to calculate several hash algorithms at the same time,
1853
you have to use the following function right after the `gcry_md_open':
1854
1855
-- Function: gcry_error_t gcry_md_enable (gcry_md_hd_t H, int ALGO)
1856
Add the message digest algorithm ALGO to the digest object
1857
described by handle H. Duplicated enabling of algorithms is
1858
detected and ignored.
1859
1860
If the flag `GCRY_MD_FLAG_HMAC' was used, the key for the MAC must
1861
be set using the function:
1862
1863
-- Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t H, const void
1864
*KEY, size_t KEYLEN)
1865
For use with the HMAC feature, set the MAC key to the value of KEY
1866
of length KEYLEN.
1867
1868
After you are done with the hash calculation, you should release the
1869
resources by using:
1870
1871
-- Function: void gcry_md_close (gcry_md_hd_t H)
1872
Release all resources of hash context H. H should not be used
1873
after a call to this function. A `NULL' passed as H is ignored.
1874
1875
1876
Often you have to do several hash operations using the same
1877
algorithm. To avoid the overhead of creating and releasing context, a
1878
reset function is provided:
1879
1880
-- Function: void gcry_md_reset (gcry_md_hd_t H)
1881
Reset the current context to its initial state. This is
1882
effectively identical to a close followed by an open and enabling
1883
all currently active algorithms.
1884
1885
Often it is necessary to start hashing some data and then continue to
1886
hash different data. To avoid hashing the same data several times
1887
(which might not even be possible if the data is received from a pipe),
1888
a snapshot of the current hash context can be taken and turned into a
1889
new context:
1890
1891
-- Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *HANDLE_DST,
1892
gcry_md_hd_t HANDLE_SRC)
1893
Create a new digest object as an exact copy of the object
1894
described by handle HANDLE_SRC and store it in HANDLE_DST. The
1895
context is not reset and you can continue to hash data using this
1896
context and independently using the original context.
1897
1898
Now that we have prepared everything to calculate hashes, it is time
1899
to see how it is actually done. There are two ways for this, one to
1900
update the hash with a block of memory and one macro to update the hash
1901
by just one character. Both methods can be used on the same hash
1902
context.
1903
1904
-- Function: void gcry_md_write (gcry_md_hd_t H, const void *BUFFER,
1905
size_t LENGTH)
1906
Pass LENGTH bytes of the data in BUFFER to the digest object with
1907
handle H to update the digest values. This function should be used
1908
for large blocks of data.
1909
1910
-- Function: void gcry_md_putc (gcry_md_hd_t H, int C)
1911
Pass the byte in C to the digest object with handle H to update
1912
the digest value. This is an efficient function, implemented as a
1913
macro to buffer the data before an actual update.
1914
1915
The semantics of the hash functions do not provide for reading out
1916
intermediate message digests because the calculation must be finalized
1917
first. This finalization may for example include the number of bytes
1918
hashed in the message digest or some padding.
1919
1920
-- Function: void gcry_md_final (gcry_md_hd_t H)
1921
Finalize the message digest calculation. This is not really needed
1922
because `gcry_md_read' does this implicitly. After this has been
1923
done no further updates (by means of `gcry_md_write' or
1924
`gcry_md_putc' are allowed. Only the first call to this function
1925
has an effect. It is implemented as a macro.
1926
1927
The way to read out the calculated message digest is by using the
1928
function:
1929
1930
-- Function: unsigned char *gcry_md_read (gcry_md_hd_t H, int ALGO)
1931
`gcry_md_read' returns the message digest after finalizing the
1932
calculation. This function may be used as often as required but
1933
it will always return the same value for one handle. The returned
1934
message digest is allocated within the message context and
1935
therefore valid until the handle is released or reseted (using
1936
`gcry_md_close' or `gcry_md_reset'. ALGO may be given as 0 to
1937
return the only enabled message digest or it may specify one of
1938
the enabled algorithms. The function does return `NULL' if the
1939
requested algorithm has not been enabled.
1940
1941
Because it is often necessary to get the message digest of one block
1942
of memory, a fast convenience function is available for this task:
1943
1944
-- Function: void gcry_md_hash_buffer (int ALGO, void *DIGEST, const
1945
void *BUFFER, size_t LENGTH);
1946
`gcry_md_hash_buffer' is a shortcut function to calculate a message
1947
digest of a buffer. This function does not require a context and
1948
immediately returns the message digest of the LENGTH bytes at
1949
BUFFER. DIGEST must be allocated by the caller, large enough to
1950
hold the message digest yielded by the the specified algorithm
1951
ALGO. This required size may be obtained by using the function
1952
`gcry_md_get_algo_dlen'.
1953
1954
Note that this function will abort the process if an unavailable
1955
algorithm is used.
1956
1957
Hash algorithms are identified by internal algorithm numbers (see
1958
`gcry_md_open' for a list). However, in most applications they are
1959
used by names, so two functions are available to map between string
1960
representations and hash algorithm identifiers.
1961
1962
-- Function: const char *gcry_md_algo_name (int ALGO)
1963
Map the digest algorithm id ALGO to a string representation of the
1964
algorithm name. For unknown algorithms this function returns the
1965
string `"?"'. This function should not be used to test for the
1966
availability of an algorithm.
1967
1968
-- Function: int gcry_md_map_name (const char *NAME)
1969
Map the algorithm with NAME to a digest algorithm identifier.
1970
Returns 0 if the algorithm name is not known. Names representing
1971
ASN.1 object identifiers are recognized if the IETF dotted format
1972
is used and the OID is prefixed with either "`oid.'" or "`OID.'".
1973
For a list of supported OIDs, see the source code at
1974
`cipher/md.c'. This function should not be used to test for the
1975
availability of an algorithm.
1976
1977
-- Function: gcry_error_t gcry_md_get_asnoid (int ALGO, void *BUFFER,
1978
size_t *LENGTH)
1979
Return an DER encoded ASN.1 OID for the algorithm ALGO in the user
1980
allocated BUFFER. LENGTH must point to variable with the available
1981
size of BUFFER and receives after return the actual size of the
1982
returned OID. The returned error code may be `GPG_ERR_TOO_SHORT'
1983
if the provided buffer is to short to receive the OID; it is
1984
possible to call the function with `NULL' for BUFFER to have it
1985
only return the required size. The function returns 0 on success.
1986
1987
1988
To test whether an algorithm is actually available for use, the
1989
following macro should be used:
1990
1991
-- Function: gcry_error_t gcry_md_test_algo (int ALGO)
1992
The macro returns 0 if the algorithm ALGO is available for use.
1993
1994
If the length of a message digest is not known, it can be retrieved
1995
using the following function:
1996
1997
-- Function: unsigned int gcry_md_get_algo_dlen (int ALGO)
1998
Retrieve the length in bytes of the digest yielded by algorithm
1999
ALGO. This is often used prior to `gcry_md_read' to allocate
2000
sufficient memory for the digest.
2001
2002
In some situations it might be hard to remember the algorithm used
2003
for the ongoing hashing. The following function might be used to get
2004
that information:
2005
2006
-- Function: int gcry_md_get_algo (gcry_md_hd_t H)
2007
Retrieve the algorithm used with the handle H. Note that this
2008
does not work reliable if more than one algorithm is enabled in H.
2009
2010
The following macro might also be useful:
2011
2012
-- Function: int gcry_md_is_secure (gcry_md_hd_t H)
2013
This function returns true when the digest object H is allocated
2014
in "secure memory"; i.e. H was created with the
2015
`GCRY_MD_FLAG_SECURE'.
2016
2017
-- Function: int gcry_md_is_enabled (gcry_md_hd_t H, int ALGO)
2018
This function returns true when the algorithm ALGO has been
2019
enabled for the digest object H.
2020
2021
Tracking bugs related to hashing is often a cumbersome task which
2022
requires to add a lot of printf statements into the code. Libgcrypt
2023
provides an easy way to avoid this. The actual data hashed can be
2024
written to files on request.
2025
2026
-- Function: void gcry_md_debug (gcry_md_hd_t H, const char *SUFFIX)
2027
Enable debugging for the digest object with handle H. This
2028
creates create files named `dbgmd-<n>.<string>' while doing the
2029
actual hashing. SUFFIX is the string part in the filename. The
2030
number is a counter incremented for each new hashing. The data in
2031
the file is the raw data as passed to `gcry_md_write' or
2032
`gcry_md_putc'. If `NULL' is used for SUFFIX, the debugging is
2033
stopped and the file closed. This is only rarely required because
2034
`gcry_md_close' implicitly stops debugging.
2035
2036
The following two deprecated macros are used for debugging by old
2037
code. They shopuld be replaced by `gcry_md_debug'.
2038
2039
-- Function: void gcry_md_start_debug (gcry_md_hd_t H, const char
2040
*SUFFIX)
2041
Enable debugging for the digest object with handle H. This
2042
creates create files named `dbgmd-<n>.<string>' while doing the
2043
actual hashing. SUFFIX is the string part in the filename. The
2044
number is a counter incremented for each new hashing. The data in
2045
the file is the raw data as passed to `gcry_md_write' or
2046
`gcry_md_putc'.
2047
2048
-- Function: void gcry_md_stop_debug (gcry_md_hd_t H, int RESERVED)
2049
Stop debugging on handle H. RESERVED should be specified as 0.
2050
This function is usually not required because `gcry_md_close' does
2051
implicitly stop debugging.
2052
2053
2054
File: gcrypt.info, Node: Public Key cryptography (I), Next: Public Key cryptography (II), Prev: Hashing, Up: Top
2055
2056
7 Public Key cryptography (I)
2057
*****************************
1797
File: gcrypt.info, Node: Public Key cryptography, Next: Hashing, Prev: Symmetric cryptography, Up: Top
1798
1799
6 Public Key cryptography
1800
*************************
2058
1801
2059
1802
Public key cryptography, also known as asymmetric cryptography, is an
2060
1803
easy way for key management and to provide digital signatures.
2069
1812
* Cryptographic Functions:: Functions for performing the cryptographic actions.
2070
1813
* General public-key related Functions:: General functions, not implementing any cryptography.
2071
1814
1815
* AC Interface:: Alternative interface to public key functions.
1816
2072
1817
2073
File: gcrypt.info, Node: Available algorithms, Next: Used S-expressions, Up: Public Key cryptography (I)
1818
File: gcrypt.info, Node: Available algorithms, Next: Used S-expressions, Up: Public Key cryptography
2074
1819
2075
7.1 Available algorithms
1820
6.1 Available algorithms
2076
1821
========================
2077
1822
2078
1823
Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
2080
1825
interface allows to add more algorithms in the future.
2081
1826
2082
1827
2083
File: gcrypt.info, Node: Used S-expressions, Next: Public key modules, Prev: Available algorithms, Up: Public Key cryptography (I)
1828
File: gcrypt.info, Node: Used S-expressions, Next: Public key modules, Prev: Available algorithms, Up: Public Key cryptography
2084
1829
2085
7.2 Used S-expressions
1830
6.2 Used S-expressions
2086
1831
======================
2087
1832
2088
1833
Libgcrypt's API for asymmetric cryptography is based on data structures
2090
1835
`http://people.csail.mit.edu/rivest/sexp.html') and does not work with
2091
1836
contexts as most of the other building blocks of Libgcrypt do.
2092
1837
2093
The following information are stored in S-expressions:
2094
2095
keys
2096
2097
plain text data
2098
2099
encrypted data
2100
2101
signatures
1838
The following information are stored in S-expressions:
1839
1840
keys
1841
1842
plain text data
1843
1844
encrypted data
1845
1846
signatures
1847
2102
1848
2103
1849
To describe how Libgcrypt expect keys, we use examples. Note that words
2104
1850
in uppercase indicate parameters whereas lowercase words are literals.
2105
1851
2106
Note that all MPI (big integer) values are expected to be in
2107
`GCRYMPI_FMT_USG' format. An easy way to create S-expressions is by
2108
using `gcry_sexp_build' which allows to pass a string with printf-like
2109
escapes to insert MPI values.
1852
Note that all MPI (multi-precision-integers) values are expected to
1853
be in `GCRYMPI_FMT_USG' format. An easy way to create S-expressions is
1854
by using `gcry_sexp_build' which allows to pass a string with
1855
printf-like escapes to insert MPI values.
2110
1856
2111
1857
* Menu:
2112
1858
2117
1863
2118
1864
File: gcrypt.info, Node: RSA key parameters, Next: DSA key parameters, Up: Used S-expressions
2119
1865
2120
7.2.1 RSA key parameters
1866
6.2.1 RSA key parameters
2121
1867
------------------------
2122
1868
2123
1869
An RSA private key is described by this S-expression:
2174
1920
2175
1921
File: gcrypt.info, Node: DSA key parameters, Next: ECC key parameters, Prev: RSA key parameters, Up: Used S-expressions
2176
1922
2177
7.2.2 DSA key parameters
1923
6.2.2 DSA key parameters
2178
1924
------------------------
2179
1925
2180
1926
A DSA private key is described by this S-expression:
2208
1954
2209
1955
File: gcrypt.info, Node: ECC key parameters, Prev: DSA key parameters, Up: Used S-expressions
2210
1956
2211
7.2.3 ECC key parameters
1957
6.2.3 ECC key parameters
2212
1958
------------------------
2213
1959
2214
1960
An ECC private key is described by this S-expression:
2290
2036
or `oid.'.
2291
2037
2292
2038
2293
File: gcrypt.info, Node: Public key modules, Next: Cryptographic Functions, Prev: Used S-expressions, Up: Public Key cryptography (I)
2039
File: gcrypt.info, Node: Public key modules, Next: Cryptographic Functions, Prev: Used S-expressions, Up: Public Key cryptography
2294
2040
2295
7.3 Public key modules
2041
6.3 Public key modules
2296
2042
======================
2297
2043
2298
2044
Libgcrypt makes it possible to load additional `public key modules';
2428
2174
*LIST_LENGTH, *LIST_LENGTH is updated to the correct number.
2429
2175
2430
2176
2431
File: gcrypt.info, Node: Cryptographic Functions, Next: General public-key related Functions, Prev: Public key modules, Up: Public Key cryptography (I)
2177
File: gcrypt.info, Node: Cryptographic Functions, Next: General public-key related Functions, Prev: Public key modules, Up: Public Key cryptography
2432
2178
2433
7.4 Cryptographic Functions
2179
6.4 Cryptographic Functions
2434
2180
===========================
2435
2181
2436
2182
Note that we will in future allow to use keys without p,q and u
2486
2232
with the given key, does the padding and encrypts it.
2487
2233
2488
2234
If the function could successfully perform the encryption, the
2489
return value will be 0 and a a new S-expression with the encrypted
2235
return value will be 0 and a new S-expression with the encrypted
2490
2236
result is allocated and assigned to the variable at the address of
2491
2237
R_CIPH. The caller is responsible to release this value using
2492
2238
`gcry_sexp_release'. In case of an error, an error code is
2611
2357
2612
2358
2613
2359
2614
File: gcrypt.info, Node: General public-key related Functions, Prev: Cryptographic Functions, Up: Public Key cryptography (I)
2360
File: gcrypt.info, Node: General public-key related Functions, Next: AC Interface, Prev: Cryptographic Functions, Up: Public Key cryptography
2615
2361
2616
7.5 General public-key related Functions
2362
6.5 General public-key related Functions
2617
2363
========================================
2618
2364
2619
2365
A couple of utility functions are available to retrieve the length of
2664
2410
WHAT are:
2665
2411
2666
2412
`GCRYCTL_TEST_ALGO:'
2667
Return 0 when the specified algorithm is available for use.
2413
Return 0 if the specified algorithm is available for use.
2668
2414
BUFFER must be `NULL', NBYTES may be passed as `NULL' or
2669
2415
point to a variable with the required usage of the algorithm.
2670
2416
This may be 0 for "don't care" or the bit-wise OR of these
2676
2422
`GCRY_PK_USAGE_ENCR'
2677
2423
Algorithm is usable for encryption.
2678
2424
2425
Unless you need to test for the allowed usage, it is in
2426
general better to use the macro gcry_pk_test_algo instead.
2427
2679
2428
`GCRYCTL_GET_ALGO_USAGE:'
2680
2429
Return the usage flags for the given algorithm. An invalid
2681
2430
algorithm return 0. Disabled algorithms are ignored here
2718
2467
and BUFLEN must have the value `sizeof (int)'.
2719
2468
2720
2469
2721
Libgcrypt also provides a function for generating public key pairs:
2470
Libgcrypt also provides a function to generate public key pairs:
2722
2471
2723
2472
-- Function: gcry_error_t gcry_pk_genkey (gcry_sexp_t *R_KEY,
2724
2473
gcry_sexp_t PARMS)
2728
2477
an error, R_KEY is set to `NULL'. The return code is 0 for
2729
2478
success or an error code otherwise.
2730
2479
2731
Here is an example for PARMS for creating a 1024 bit RSA key:
2480
Here is an example for PARMS to create an 2048 bit RSA key:
2732
2481
2733
2482
(genkey
2734
2483
(rsa
2735
(nbits 4:1024)))
2484
(nbits 4:2048)))
2736
2485
2737
2486
To create an Elgamal key, substitute "elg" for "rsa" and to create
2738
2487
a DSA key use "dsa". Valid ranges for the key length depend on the
2761
2510
number 41.
2762
2511
2763
2512
`1'
2764
Use a secure value as required by some specification.
2765
This is currently the number 65537.
2513
Use a value as required by some crypto policies. This
2514
is currently the number 65537.
2766
2515
2767
2516
`2'
2768
2517
Reserved
2769
2518
2519
`> 2'
2520
Use the given value.
2521
2770
2522
If this parameter is not used, Libgcrypt uses for historic
2771
2523
reasons 65537.
2772
2524
2793
2545
range 512 to 15680 are valid as long as they are multiples of
2794
2546
8.
2795
2547
2548
`transient-key'
2549
This is only meaningful for RSA and DSA keys. This is a flag
2550
with no value. If given the RSA or DSA key is created using
2551
a faster and a somewhat less secure random number generator.
2552
This flag may be used for keys which are only used for a
2553
short time and do not require full cryptographic strength.
2554
2555
`domain'
2556
This is only meaningful for DLP algorithms. If specified
2557
keys are generated with domain parameters taken from this
2558
list. The exact format of this parameter depends on the
2559
actual algorithm. It is currently only implemented for DSA
2560
using this format:
2561
2562
(genkey
2563
(dsa
2564
(domain
2565
(p P-MPI)
2566
(q Q-MPI)
2567
(g Q-MPI))))
2568
2569
`nbits' and `qbits' may not be specified because they are
2570
derived from the domain parameters.
2571
2572
`derive-parms'
2573
This is currently only implemented for RSA and DSA keys. It
2574
is not allowed to use this together with a `domain'
2575
specification. If given, it is used to derive the keys using
2576
the given parameters.
2577
2578
If given for an RSA key the X9.31 key generation algorithm is
2579
used even if libgcrypt is not in FIPS mode. If given for a
2580
DSA key, the FIPS 186 algorithm is used even if libgcrypt is
2581
not in FIPS mode.
2582
2583
(genkey
2584
(rsa
2585
(nbits 4:1024)
2586
(rsa-use-e 1:3)
2587
(derive-parms
2588
(Xp1 #1A1916DDB29B4EB7EB6732E128#)
2589
(Xp2 #192E8AAC41C576C822D93EA433#)
2590
(Xp #D8CD81F035EC57EFE822955149D3BFF70C53520D
2591
769D6D76646C7A792E16EBD89FE6FC5B605A6493
2592
39DFC925A86A4C6D150B71B9EEA02D68885F5009
2593
B98BD984#)
2594
(Xq1 #1A5CF72EE770DE50CB09ACCEA9#)
2595
(Xq2 #134E4CAA16D2350A21D775C404#)
2596
(Xq #CC1092495D867E64065DEE3E7955F2EBC7D47A2D
2597
7C9953388F97DDDC3E1CA19C35CA659EDC2FC325
2598
6D29C2627479C086A699A49C4C9CEE7EF7BD1B34
2599
321DE34A#))))
2600
2601
(genkey
2602
(dsa
2603
(nbits 4:1024)
2604
(derive-parms
2605
(seed SEED-MPI))))
2606
2607
`use-x931'
2608
Force the use of the ANSI X9.31 key generation algorithm
2609
instead of the default algorithm. This flag is only
2610
meaningful for RSA and usually not required. Note that this
2611
algorithm is implicitly used if either `derive-parms' is
2612
given or Libgcrypt is in FIPS mode.
2613
2614
`use-fips186'
2615
Force the use of the FIPS 186 key generation algorithm
2616
instead of the default algorithm. This flag is only
2617
meaningful for DSA and usually not required. Note that this
2618
algorithm is implicitly used if either `derive-parms' is
2619
given or Libgcrypt is in FIPS mode. As of now FIPS 186-2 is
2620
implemented; after the approval of FIPS 186-3 the code will
2621
be changed to implement 186-3.
2622
2623
`use-fips186-2'
2624
Force the use of the FIPS 186-2 key generation algorithm
2625
instead of the default algorithm. This algorithm is slighlty
2626
different from FIPS 186-3 and allows only 1024 bit keys.
2627
This flag is only meaningful for DSA and only required for
2628
FIPS testing backward compatibility.
2629
2796
2630
2797
2631
The key pair is returned in a format depending on the algorithm.
2798
2632
Both private and public keys are returned in one container and may
2813
2647
(y Y-MPI)
2814
2648
(x X-MPI)))
2815
2649
(misc-key-info
2816
(pm1-factors N1 N2 ... NN)))
2650
(pm1-factors N1 N2 ... NN))
2817
2651
2818
2652
As you can see, some of the information is duplicated, but this
2819
2653
provides an easy way to extract either the public or the private
2820
2654
key. Note that the order of the elements is not defined, e.g. the
2821
2655
private key may be stored before the public key. N1 N2 ... NN is a
2822
2656
list of prime numbers used to composite P-MPI; this is in general
2823
not a very useful information.
2657
not a very useful information and only available if the key
2658
generation algorithm provides them.
2824
2659
2825
2660
2826
File: gcrypt.info, Node: Public Key cryptography (II), Next: Random Numbers, Prev: Public Key cryptography (I), Up: Top
2827
2828
8 Public Key cryptography (II)
2829
******************************
2830
2831
This chapter documents the alternative interface to asymmetric
2661
File: gcrypt.info, Node: AC Interface, Prev: General public-key related Functions, Up: Public Key cryptography
2662
2663
6.6 Alternative Public Key Interface
2664
====================================
2665
2666
This section documents the alternative interface to asymmetric
2832
2667
cryptography (ac) that is not based on S-expressions, but on native C
2833
2668
data structures. As opposed to the pk interface described in the
2834
2669
former chapter, this one follows an open/use/close paradigm like other
2836
2671
2837
2672
*This interface has a few known problems; most noteworthy an
2838
2673
inherent tendency to leak memory. It might not be available in
2839
forthcoming versions Libgcrypt.*
2674
forthcoming versions of Libgcrypt.*
2840
2675
2841
2676
* Menu:
2842
2677
2849
2684
* Handle-independent functions:: General functions independent of handles.
2850
2685
2851
2686
2852
File: gcrypt.info, Node: Available asymmetric algorithms, Next: Working with sets of data, Up: Public Key cryptography (II)
2687
File: gcrypt.info, Node: Available asymmetric algorithms, Next: Working with sets of data, Up: AC Interface
2853
2688
2854
8.1 Available asymmetric algorithms
2855
===================================
2689
6.6.1 Available asymmetric algorithms
2690
-------------------------------------
2856
2691
2857
2692
Libgcrypt supports the RSA (Rivest-Shamir-Adleman) algorithms as well
2858
2693
as DSA (Digital Signature Algorithm) and Elgamal. The versatile
2874
2709
Elgamal, encryption only.
2875
2710
2876
2711
2877
File: gcrypt.info, Node: Working with sets of data, Next: Working with IO objects, Prev: Available asymmetric algorithms, Up: Public Key cryptography (II)
2712
File: gcrypt.info, Node: Working with sets of data, Next: Working with IO objects, Prev: Available asymmetric algorithms, Up: AC Interface
2878
2713
2879
8.2 Working with sets of data
2880
=============================
2714
6.6.2 Working with sets of data
2715
-------------------------------
2881
2716
2882
2717
In the context of this interface the term `data set' refers to a list
2883
2718
of `named MPI values' that is used by functions performing
2973
2808
structure of the S-Expression, the function fails.
2974
2809
2975
2810
2976
File: gcrypt.info, Node: Working with IO objects, Next: Working with handles, Prev: Working with sets of data, Up: Public Key cryptography (II)
2811
File: gcrypt.info, Node: Working with IO objects, Next: Working with handles, Prev: Working with sets of data, Up: AC Interface
2977
2812
2978
8.3 Working with IO objects
2979
===========================
2813
6.6.3 Working with IO objects
2814
-----------------------------
2980
2815
2981
2816
Note: IO objects are currently only used in the context of message
2982
2817
encoding/decoding and encryption/signature schemes.
3044
2879
Opaque argument to provide to the callback function
3045
2880
3046
2881
3047
File: gcrypt.info, Node: Working with handles, Next: Working with keys, Prev: Working with IO objects, Up: Public Key cryptography (II)
2882
File: gcrypt.info, Node: Working with handles, Next: Working with keys, Prev: Working with IO objects, Up: AC Interface
3048
2883
3049
8.4 Working with handles
3050
========================
2884
6.6.4 Working with handles
2885
--------------------------
3051
2886
3052
2887
In order to use an algorithm, an according handle must be created.
3053
2888
This is done using the following function:
3067
2902
Destroys the handle HANDLE.
3068
2903
3069
2904
3070
File: gcrypt.info, Node: Working with keys, Next: Using cryptographic functions, Prev: Working with handles, Up: Public Key cryptography (II)
2905
File: gcrypt.info, Node: Working with keys, Next: Using cryptographic functions, Prev: Working with handles, Up: AC Interface
3071
2906
3072
8.5 Working with keys
3073
=====================
2907
6.6.5 Working with keys
2908
-----------------------
3074
2909
3075
2910
-- Data type: gcry_ac_key_type_t
3076
2911
Defined constants:
3142
2977
err = gcry_ac_open (&handle, GCRY_AC_RSA, 0);
3143
2978
assert (! err);
3144
2979
3145
err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, &key_pair, NULL);
2980
err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec,
2981
&key_pair, NULL);
3146
2982
assert (! err);
3147
2983
}
3148
2984
3174
3010
HANDLE.
3175
3011
3176
3012
3177
File: gcrypt.info, Node: Using cryptographic functions, Next: Handle-independent functions, Prev: Working with keys, Up: Public Key cryptography (II)
3013
File: gcrypt.info, Node: Using cryptographic functions, Next: Handle-independent functions, Prev: Working with keys, Up: AC Interface
3178
3014
3179
8.6 Using cryptographic functions
3180
=================================
3015
6.6.6 Using cryptographic functions
3016
-----------------------------------
3181
3017
3182
3018
The following flags might be relevant:
3183
3019
3338
3174
scheme.
3339
3175
3340
3176
3341
File: gcrypt.info, Node: Handle-independent functions, Prev: Using cryptographic functions, Up: Public Key cryptography (II)
3177
File: gcrypt.info, Node: Handle-independent functions, Prev: Using cryptographic functions, Up: AC Interface
3342
3178
3343
8.7 Handle-independent functions
3344
================================
3179
6.6.7 Handle-independent functions
3180
----------------------------------
3345
3181
3346
3182
These two functions are deprecated; do not use them for new code.
3347
3183
3357
3193
`gcry_pk_map_name'.
3358
3194
3359
3195
3360
File: gcrypt.info, Node: Random Numbers, Next: S-expressions, Prev: Public Key cryptography (II), Up: Top
3361
3362
9 Random Numbers
3196
File: gcrypt.info, Node: Hashing, Next: Random Numbers, Prev: Public Key cryptography, Up: Top
3197
3198
7 Hashing
3199
*********
3200
3201
Libgcrypt provides an easy and consistent to use interface for hashing.
3202
Hashing is buffered and several hash algorithms can be updated at once.
3203
It is possible to compute a MAC using the same routines. The
3204
programming model follows an open/process/close paradigm and is in that
3205
similar to other building blocks provided by Libgcrypt.
3206
3207
For convenience reasons, a few cyclic redundancy check value
3208
operations are also supported.
3209
3210
* Menu:
3211
3212
* Available hash algorithms:: List of hash algorithms supported by the library.
3213
* Hash algorithm modules:: How to work with hash algorithm modules.
3214
* Working with hash algorithms:: List of functions related to hashing.
3215
3216
3217
File: gcrypt.info, Node: Available hash algorithms, Next: Hash algorithm modules, Up: Hashing
3218
3219
7.1 Available hash algorithms
3220
=============================
3221
3222
`GCRY_MD_NONE'
3223
This is not a real algorithm but used by some functions as an error
3224
return value. This constant is guaranteed to have the value `0'.
3225
3226
`GCRY_MD_SHA1'
3227
This is the SHA-1 algorithm which yields a message digest of 20
3228
bytes.
3229
3230
`GCRY_MD_RMD160'
3231
This is the 160 bit version of the RIPE message digest
3232
(RIPE-MD-160). Like SHA-1 it also yields a digest of 20 bytes.
3233
3234
`GCRY_MD_MD5'
3235
This is the well known MD5 algorithm, which yields a message
3236
digest of 16 bytes.
3237
3238
`GCRY_MD_MD4'
3239
This is the MD4 algorithm, which yields a message digest of 16
3240
bytes.
3241
3242
`GCRY_MD_MD2'
3243
This is an reserved identifier for MD-2; there is no
3244
implementation yet.
3245
3246
`GCRY_MD_TIGER'
3247
This is the TIGER/192 algorithm which yields a message digest of
3248
24 bytes.
3249
3250
`GCRY_MD_HAVAL'
3251
This is an reserved for the HAVAL algorithm with 5 passes and 160
3252
bit. It yields a message digest of 20 bytes. Note that there is no
3253
implementation yet available.
3254
3255
`GCRY_MD_SHA224'
3256
This is the SHA-224 algorithm which yields a message digest of 28
3257
bytes. See Change Notice 1 for FIPS 180-2 for the specification.
3258
3259
`GCRY_MD_SHA256'
3260
This is the SHA-256 algorithm which yields a message digest of 32
3261
bytes. See FIPS 180-2 for the specification.
3262
3263
`GCRY_MD_SHA384'
3264
This is the SHA-384 algorithm which yields a message digest of 48
3265
bytes. See FIPS 180-2 for the specification.
3266
3267
`GCRY_MD_SHA512'
3268
This is the SHA-384 algorithm which yields a message digest of 64
3269
bytes. See FIPS 180-2 for the specification.
3270
3271
`GCRY_MD_CRC32'
3272
This is the ISO 3309 and ITU-T V.42 cyclic redundancy check. It
3273
yields an output of 4 bytes.
3274
3275
`GCRY_MD_CRC32_RFC1510'
3276
This is the above cyclic redundancy check function, as modified by
3277
RFC 1510. It yields an output of 4 bytes.
3278
3279
`GCRY_MD_CRC24_RFC2440'
3280
This is the OpenPGP cyclic redundancy check function. It yields an
3281
output of 3 bytes.
3282
3283
`GCRY_MD_WHIRLPOOL'
3284
This is the Whirlpool algorithm which yields a message digest of 64
3285
bytes.
3286
3287
3288
3289
File: gcrypt.info, Node: Hash algorithm modules, Next: Working with hash algorithms, Prev: Available hash algorithms, Up: Hashing
3290
3291
7.2 Hash algorithm modules
3292
==========================
3293
3294
Libgcrypt makes it possible to load additional `message digest
3295
modules'; these digests can be used just like the message digest
3296
algorithms that are built into the library directly. For an
3297
introduction into extension modules, see *Note Modules::.
3298
3299
-- Data type: gcry_md_spec_t
3300
This is the `module specification structure' needed for registering
3301
message digest modules, which has to be filled in by the user
3302
before it can be used to register a module. It contains the
3303
following members:
3304
3305
`const char *name'
3306
The primary name of this algorithm.
3307
3308
`unsigned char *asnoid'
3309
Array of bytes that form the ASN OID.
3310
3311
`int asnlen'
3312
Length of bytes in `asnoid'.
3313
3314
`gcry_md_oid_spec_t *oids'
3315
A list of OIDs that are to be associated with the algorithm.
3316
The list's last element must have it's `oid' member set to
3317
NULL. See below for an explanation of this type. See below
3318
for an explanation of this type.
3319
3320
`int mdlen'
3321
Length of the message digest algorithm. See below for an
3322
explanation of this type.
3323
3324
`gcry_md_init_t init'
3325
The function responsible for initializing a handle. See
3326
below for an explanation of this type.
3327
3328
`gcry_md_write_t write'
3329
The function responsible for writing data into a message
3330
digest context. See below for an explanation of this type.
3331
3332
`gcry_md_final_t final'
3333
The function responsible for `finalizing' a message digest
3334
context. See below for an explanation of this type.
3335
3336
`gcry_md_read_t read'
3337
The function responsible for reading out a message digest
3338
result. See below for an explanation of this type.
3339
3340
`size_t contextsize'
3341
The size of the algorithm-specific `context', that should be
3342
allocated for each handle.
3343
3344
-- Data type: gcry_md_oid_spec_t
3345
This type is used for associating a user-provided algorithm
3346
implementation with certain OIDs. It contains the following
3347
members:
3348
3349
`const char *oidstring'
3350
Textual representation of the OID.
3351
3352
-- Data type: gcry_md_init_t
3353
Type for the `init' function, defined as: void (*gcry_md_init_t)
3354
(void *c)
3355
3356
-- Data type: gcry_md_write_t
3357
Type for the `write' function, defined as: void (*gcry_md_write_t)
3358
(void *c, unsigned char *buf, size_t nbytes)
3359
3360
-- Data type: gcry_md_final_t
3361
Type for the `final' function, defined as: void (*gcry_md_final_t)
3362
(void *c)
3363
3364
-- Data type: gcry_md_read_t
3365
Type for the `read' function, defined as: unsigned char
3366
*(*gcry_md_read_t) (void *c)
3367
3368
-- Function: gcry_error_t gcry_md_register (gcry_md_spec_t *DIGEST,
3369
unsigned int *algorithm_id, gcry_module_t *MODULE)
3370
Register a new digest module whose specification can be found in
3371
DIGEST. On success, a new algorithm ID is stored in ALGORITHM_ID
3372
and a pointer representing this module is stored in MODULE.
3373
3374
-- Function: void gcry_md_unregister (gcry_module_t MODULE)
3375
Unregister the digest identified by MODULE, which must have been
3376
registered with gcry_md_register.
3377
3378
-- Function: gcry_error_t gcry_md_list (int *LIST, int *LIST_LENGTH)
3379
Get a list consisting of the IDs of the loaded message digest
3380
modules. If LIST is zero, write the number of loaded message
3381
digest modules to LIST_LENGTH and return. If LIST is non-zero,
3382
the first *LIST_LENGTH algorithm IDs are stored in LIST, which
3383
must be of according size. In case there are less message digests
3384
modules than *LIST_LENGTH, *LIST_LENGTH is updated to the correct
3385
number.
3386
3387
3388
File: gcrypt.info, Node: Working with hash algorithms, Prev: Hash algorithm modules, Up: Hashing
3389
3390
7.3 Working with hash algorithms
3391
================================
3392
3393
To use most of these function it is necessary to create a context; this
3394
is done using:
3395
3396
-- Function: gcry_error_t gcry_md_open (gcry_md_hd_t *HD, int ALGO,
3397
unsigned int FLAGS)
3398
Create a message digest object for algorithm ALGO. FLAGS may be
3399
given as an bitwise OR of constants described below. ALGO may be
3400
given as `0' if the algorithms to use are later set using
3401
`gcry_md_enable'. HD is guaranteed to either receive a valid
3402
handle or NULL.
3403
3404
For a list of supported algorithms, see *Note Available hash
3405
algorithms::.
3406
3407
The flags allowed for MODE are:
3408
3409
`GCRY_MD_FLAG_SECURE'
3410
Allocate all buffers and the resulting digest in "secure
3411
memory". Use this is the hashed data is highly confidential.
3412
3413
`GCRY_MD_FLAG_HMAC'
3414
Turn the algorithm into a HMAC message authentication
3415
algorithm. This only works if just one algorithm is enabled
3416
for the handle. Note that the function `gcry_md_setkey' must
3417
be used to set the MAC key. The size of the MAC is equal to
3418
the message digest of the underlying hash algorithm. If you
3419
want CBC message authentication codes based on a cipher, see
3420
*Note Working with cipher handles::.
3421
3422
3423
You may use the function `gcry_md_is_enabled' to later check
3424
whether an algorithm has been enabled.
3425
3426
3427
If you want to calculate several hash algorithms at the same time,
3428
you have to use the following function right after the `gcry_md_open':
3429
3430
-- Function: gcry_error_t gcry_md_enable (gcry_md_hd_t H, int ALGO)
3431
Add the message digest algorithm ALGO to the digest object
3432
described by handle H. Duplicated enabling of algorithms is
3433
detected and ignored.
3434
3435
If the flag `GCRY_MD_FLAG_HMAC' was used, the key for the MAC must
3436
be set using the function:
3437
3438
-- Function: gcry_error_t gcry_md_setkey (gcry_md_hd_t H, const void
3439
*KEY, size_t KEYLEN)
3440
For use with the HMAC feature, set the MAC key to the value of KEY
3441
of length KEYLEN. There is no restriction on the length of the
3442
key.
3443
3444
After you are done with the hash calculation, you should release the
3445
resources by using:
3446
3447
-- Function: void gcry_md_close (gcry_md_hd_t H)
3448
Release all resources of hash context H. H should not be used
3449
after a call to this function. A `NULL' passed as H is ignored.
3450
3451
3452
Often you have to do several hash operations using the same
3453
algorithm. To avoid the overhead of creating and releasing context, a
3454
reset function is provided:
3455
3456
-- Function: void gcry_md_reset (gcry_md_hd_t H)
3457
Reset the current context to its initial state. This is
3458
effectively identical to a close followed by an open and enabling
3459
all currently active algorithms.
3460
3461
Often it is necessary to start hashing some data and then continue to
3462
hash different data. To avoid hashing the same data several times
3463
(which might not even be possible if the data is received from a pipe),
3464
a snapshot of the current hash context can be taken and turned into a
3465
new context:
3466
3467
-- Function: gcry_error_t gcry_md_copy (gcry_md_hd_t *HANDLE_DST,
3468
gcry_md_hd_t HANDLE_SRC)
3469
Create a new digest object as an exact copy of the object
3470
described by handle HANDLE_SRC and store it in HANDLE_DST. The
3471
context is not reset and you can continue to hash data using this
3472
context and independently using the original context.
3473
3474
Now that we have prepared everything to calculate hashes, it is time
3475
to see how it is actually done. There are two ways for this, one to
3476
update the hash with a block of memory and one macro to update the hash
3477
by just one character. Both methods can be used on the same hash
3478
context.
3479
3480
-- Function: void gcry_md_write (gcry_md_hd_t H, const void *BUFFER,
3481
size_t LENGTH)
3482
Pass LENGTH bytes of the data in BUFFER to the digest object with
3483
handle H to update the digest values. This function should be used
3484
for large blocks of data.
3485
3486
-- Function: void gcry_md_putc (gcry_md_hd_t H, int C)
3487
Pass the byte in C to the digest object with handle H to update
3488
the digest value. This is an efficient function, implemented as a
3489
macro to buffer the data before an actual update.
3490
3491
The semantics of the hash functions do not provide for reading out
3492
intermediate message digests because the calculation must be finalized
3493
first. This finalization may for example include the number of bytes
3494
hashed in the message digest or some padding.
3495
3496
-- Function: void gcry_md_final (gcry_md_hd_t H)
3497
Finalize the message digest calculation. This is not really needed
3498
because `gcry_md_read' does this implicitly. After this has been
3499
done no further updates (by means of `gcry_md_write' or
3500
`gcry_md_putc' are allowed. Only the first call to this function
3501
has an effect. It is implemented as a macro.
3502
3503
The way to read out the calculated message digest is by using the
3504
function:
3505
3506
-- Function: unsigned char * gcry_md_read (gcry_md_hd_t H, int ALGO)
3507
`gcry_md_read' returns the message digest after finalizing the
3508
calculation. This function may be used as often as required but
3509
it will always return the same value for one handle. The returned
3510
message digest is allocated within the message context and
3511
therefore valid until the handle is released or reseted (using
3512
`gcry_md_close' or `gcry_md_reset'. ALGO may be given as 0 to
3513
return the only enabled message digest or it may specify one of
3514
the enabled algorithms. The function does return `NULL' if the
3515
requested algorithm has not been enabled.
3516
3517
Because it is often necessary to get the message digest of one block
3518
of memory, a fast convenience function is available for this task:
3519
3520
-- Function: void gcry_md_hash_buffer (int ALGO, void *DIGEST, const
3521
void *BUFFER, size_t LENGTH);
3522
`gcry_md_hash_buffer' is a shortcut function to calculate a message
3523
digest of a buffer. This function does not require a context and
3524
immediately returns the message digest of the LENGTH bytes at
3525
BUFFER. DIGEST must be allocated by the caller, large enough to
3526
hold the message digest yielded by the the specified algorithm
3527
ALGO. This required size may be obtained by using the function
3528
`gcry_md_get_algo_dlen'.
3529
3530
Note that this function will abort the process if an unavailable
3531
algorithm is used.
3532
3533
Hash algorithms are identified by internal algorithm numbers (see
3534
`gcry_md_open' for a list). However, in most applications they are
3535
used by names, so two functions are available to map between string
3536
representations and hash algorithm identifiers.
3537
3538
-- Function: const char * gcry_md_algo_name (int ALGO)
3539
Map the digest algorithm id ALGO to a string representation of the
3540
algorithm name. For unknown algorithms this function returns the
3541
string `"?"'. This function should not be used to test for the
3542
availability of an algorithm.
3543
3544
-- Function: int gcry_md_map_name (const char *NAME)
3545
Map the algorithm with NAME to a digest algorithm identifier.
3546
Returns 0 if the algorithm name is not known. Names representing
3547
ASN.1 object identifiers are recognized if the IETF dotted format
3548
is used and the OID is prefixed with either "`oid.'" or "`OID.'".
3549
For a list of supported OIDs, see the source code at
3550
`cipher/md.c'. This function should not be used to test for the
3551
availability of an algorithm.
3552
3553
-- Function: gcry_error_t gcry_md_get_asnoid (int ALGO, void *BUFFER,
3554
size_t *LENGTH)
3555
Return an DER encoded ASN.1 OID for the algorithm ALGO in the user
3556
allocated BUFFER. LENGTH must point to variable with the available
3557
size of BUFFER and receives after return the actual size of the
3558
returned OID. The returned error code may be `GPG_ERR_TOO_SHORT'
3559
if the provided buffer is to short to receive the OID; it is
3560
possible to call the function with `NULL' for BUFFER to have it
3561
only return the required size. The function returns 0 on success.
3562
3563
3564
To test whether an algorithm is actually available for use, the
3565
following macro should be used:
3566
3567
-- Function: gcry_error_t gcry_md_test_algo (int ALGO)
3568
The macro returns 0 if the algorithm ALGO is available for use.
3569
3570
If the length of a message digest is not known, it can be retrieved
3571
using the following function:
3572
3573
-- Function: unsigned int gcry_md_get_algo_dlen (int ALGO)
3574
Retrieve the length in bytes of the digest yielded by algorithm
3575
ALGO. This is often used prior to `gcry_md_read' to allocate
3576
sufficient memory for the digest.
3577
3578
In some situations it might be hard to remember the algorithm used
3579
for the ongoing hashing. The following function might be used to get
3580
that information:
3581
3582
-- Function: int gcry_md_get_algo (gcry_md_hd_t H)
3583
Retrieve the algorithm used with the handle H. Note that this
3584
does not work reliable if more than one algorithm is enabled in H.
3585
3586
The following macro might also be useful:
3587
3588
-- Function: int gcry_md_is_secure (gcry_md_hd_t H)
3589
This function returns true when the digest object H is allocated
3590
in "secure memory"; i.e. H was created with the
3591
`GCRY_MD_FLAG_SECURE'.
3592
3593
-- Function: int gcry_md_is_enabled (gcry_md_hd_t H, int ALGO)
3594
This function returns true when the algorithm ALGO has been
3595
enabled for the digest object H.
3596
3597
Tracking bugs related to hashing is often a cumbersome task which
3598
requires to add a lot of printf statements into the code. Libgcrypt
3599
provides an easy way to avoid this. The actual data hashed can be
3600
written to files on request.
3601
3602
-- Function: void gcry_md_debug (gcry_md_hd_t H, const char *SUFFIX)
3603
Enable debugging for the digest object with handle H. This
3604
creates create files named `dbgmd-<n>.<string>' while doing the
3605
actual hashing. SUFFIX is the string part in the filename. The
3606
number is a counter incremented for each new hashing. The data in
3607
the file is the raw data as passed to `gcry_md_write' or
3608
`gcry_md_putc'. If `NULL' is used for SUFFIX, the debugging is
3609
stopped and the file closed. This is only rarely required because
3610
`gcry_md_close' implicitly stops debugging.
3611
3612
The following two deprecated macros are used for debugging by old
3613
code. They shopuld be replaced by `gcry_md_debug'.
3614
3615
-- Function: void gcry_md_start_debug (gcry_md_hd_t H, const char
3616
*SUFFIX)
3617
Enable debugging for the digest object with handle H. This
3618
creates create files named `dbgmd-<n>.<string>' while doing the
3619
actual hashing. SUFFIX is the string part in the filename. The
3620
number is a counter incremented for each new hashing. The data in
3621
the file is the raw data as passed to `gcry_md_write' or
3622
`gcry_md_putc'.
3623
3624
-- Function: void gcry_md_stop_debug (gcry_md_hd_t H, int RESERVED)
3625
Stop debugging on handle H. RESERVED should be specified as 0.
3626
This function is usually not required because `gcry_md_close' does
3627
implicitly stop debugging.
3628
3629
3630
File: gcrypt.info, Node: Random Numbers, Next: S-expressions, Prev: Hashing, Up: Top
3631
3632
8 Random Numbers
3363
3633
****************
3364
3634
3365
3635
* Menu:
3370
3640
3371
3641
File: gcrypt.info, Node: Quality of random numbers, Next: Retrieving random numbers, Up: Random Numbers
3372
3642
3373
9.1 Quality of random numbers
3643
8.1 Quality of random numbers
3374
3644
=============================
3375
3645
3376
3646
Libgcypt offers random numbers of different quality levels:
3377
3647
3378
-- Data type: enum gcry_random_level
3379
The constants for the random quality levels are of this type.
3648
-- Data type: gcry_random_level_t
3649
The constants for the random quality levels are of this enum type.
3380
3650
3381
3651
`GCRY_WEAK_RANDOM'
3382
This should not anymore be used. It has recently been changed to
3383
an alias of GCRY_STRONG_RANDOM. Use `gcry_create_nonce' instead.
3652
For all functions, except for `gcry_mpi_randomize', this level maps
3653
to GCRY_STRONG_RANDOM. If you do not want this, consider using
3654
`gcry_create_nonce'.
3384
3655
3385
3656
`GCRY_STRONG_RANDOM'
3386
Use this level for e.g. session keys and similar purposes.
3657
Use this level for session keys and similar purposes.
3387
3658
3388
3659
`GCRY_VERY_STRONG_RANDOM'
3389
Use this level for e.g. key material.
3660
Use this level for long term key material.
3390
3661
3391
3662
3392
3663
File: gcrypt.info, Node: Retrieving random numbers, Prev: Quality of random numbers, Up: Random Numbers
3393
3664
3394
9.2 Retrieving random numbers
3665
8.2 Retrieving random numbers
3395
3666
=============================
3396
3667
3397
3668
-- Function: void gcry_randomize (unsigned char *BUFFER, size_t
3401
3672
3402
3673
-- Function: void * gcry_random_bytes (size_t NBYTES, enum
3403
3674
gcry_random_level LEVEL)
3404
Allocate a memory block consisting of NBYTES fresh random bytes
3405
using a random quality as defined by LEVEL.
3675
Convenience function to allocate a memory block consisting of
3676
NBYTES fresh random bytes using a random quality as defined by
3677
LEVEL.
3406
3678
3407
3679
-- Function: void * gcry_random_bytes_secure (size_t NBYTES, enum
3408
3680
gcry_random_level LEVEL)
3409
Allocate a memory block consisting of NBYTES fresh random bytes
3410
using a random quality as defined by LEVEL. This function differs
3411
from `gcry_random_bytes' in that the returned buffer is allocated
3412
in a "secure" area of the memory.
3681
Convenience function to allocate a memory block consisting of
3682
NBYTES fresh random bytes using a random quality as defined by
3683
LEVEL. This function differs from `gcry_random_bytes' in that the
3684
returned buffer is allocated in a "secure" area of the memory.
3413
3685
3414
3686
-- Function: void gcry_create_nonce (unsigned char *BUFFER, size_t
3415
3687
LENGTH)
3424
3696
3425
3697
File: gcrypt.info, Node: S-expressions, Next: MPI library, Prev: Random Numbers, Up: Top
3426
3698
3427
10 S-expressions
3428
****************
3699
9 S-expressions
3700
***************
3429
3701
3430
3702
S-expressions are used by the public key functions to pass complex data
3431
3703
structures around. These LISP like objects are used by some
3442
3714
3443
3715
File: gcrypt.info, Node: Data types for S-expressions, Next: Working with S-expressions, Up: S-expressions
3444
3716
3445
10.1 Data types for S-expressions
3446
=================================
3717
9.1 Data types for S-expressions
3718
================================
3447
3719
3448
3720
-- Data type: gcry_sexp_t
3449
3721
The `gcry_sexp_t' type describes an object with the Libgcrypt
3452
3724
3453
3725
File: gcrypt.info, Node: Working with S-expressions, Prev: Data types for S-expressions, Up: S-expressions
3454
3726
3455
10.2 Working with S-expressions
3456
===============================
3727
9.2 Working with S-expressions
3728
==============================
3457
3729
3458
3730
There are several functions to create an Libgcrypt S-expression object
3459
3731
from its external representation or from a string template. There is
3624
3896
name = gcry_sexp_nth_data (list, 2, &len);
3625
3897
printf ("my name is %.*s\n", (int)len, name);
3626
3898
3627
-- Function: char *gcry_sexp_nth_string (gcry_sexp_t LIST, int NUMBER)
3899
-- Function: char * gcry_sexp_nth_string (gcry_sexp_t LIST, int NUMBER)
3628
3900
This function is used to get and convert data from a LIST. The
3629
3901
data is assumed to be a Nul terminated string. The caller must
3630
3902
release this returned value using `gcry_free'. If there is no
3643
3915
3644
3916
File: gcrypt.info, Node: MPI library, Next: Prime numbers, Prev: S-expressions, Up: Top
3645
3917
3646
11 MPI library
3918
10 MPI library
3647
3919
**************
3648
3920
3649
3921
* Menu:
3659
3931
Public key cryptography is based on mathematics with large numbers.
3660
3932
To implement the public key functions, a library for handling these
3661
3933
large numbers is required. Because of the general usefulness of such a
3662
library, its interface is exposed by Libgcrypt. The implementation is
3663
based on an old release of GNU Multi-Precision Library (GMP) but in the
3664
meantime heavily modified and stripped down to what is required for
3665
cryptography. For a lot of CPUs, high performance assembler
3666
implementations of some very low level functions are used to gain much
3667
better performance than with the standard C implementation.
3668
3669
In the context of Libgcrypt and in most other applications, these large
3670
numbers are called MPIs (multi-precision-integers).
3934
library, its interface is exposed by Libgcrypt. In the context of
3935
Libgcrypt and in most other applications, these large numbers are
3936
called MPIs (multi-precision-integers).
3671
3937
3672
3938
3673
3939
File: gcrypt.info, Node: Data types, Next: Basic functions, Up: MPI library
3674
3940
3675
11.1 Data types
3941
10.1 Data types
3676
3942
===============
3677
3943
3678
3944
-- Data type: gcry_mpi_t
3679
The `gcry_mpi_t' type represents an object to hold an MPI.
3945
This type represents an object to hold an MPI.
3680
3946
3681
3947
3682
3948
File: gcrypt.info, Node: Basic functions, Next: MPI formats, Prev: Data types, Up: MPI library
3683
3949
3684
11.2 Basic functions
3950
10.2 Basic functions
3685
3951
====================
3686
3952
3687
3953
To work with MPIs, storage must be allocated and released for the
3727
3993
3728
3994
File: gcrypt.info, Node: MPI formats, Next: Calculations, Prev: Basic functions, Up: MPI library
3729
3995
3730
11.3 MPI formats
3996
10.3 MPI formats
3731
3997
================
3732
3998
3733
3999
The following functions are used to convert between an external
3793
4059
3794
4060
File: gcrypt.info, Node: Calculations, Next: Comparisons, Prev: MPI formats, Up: MPI library
3795
4061
3796
11.4 Calculations
4062
10.4 Calculations
3797
4063
=================
3798
4064
3799
4065
Basic arithmetic operations:
3864
4130
3865
4131
File: gcrypt.info, Node: Comparisons, Next: Bit manipulations, Prev: Calculations, Up: MPI library
3866
4132
3867
11.5 Comparisons
4133
10.5 Comparisons
3868
4134
================
3869
4135
3870
4136
The next 2 functions are used to compare MPIs:
3871
4137
3872
4138
-- Function: int gcry_mpi_cmp (const gcry_mpi_t U, const gcry_mpi_t V)
3873
Compare the big integer number U and V returning 0 for equality, a
3874
positive value for U > V and a negative for U < V.
4139
Compare the multi-precision-integers number U and V returning 0
4140
for equality, a positive value for U > V and a negative for U < V.
3875
4141
3876
4142
-- Function: int gcry_mpi_cmp_ui (const gcry_mpi_t U, unsigned long V)
3877
Compare the big integer number U with the unsigned integer V
3878
returning 0 for equality, a positive value for U > V and a
3879
negative for U < V.
4143
Compare the multi-precision-integers number U with the unsigned
4144
integer V returning 0 for equality, a positive value for U > V and
4145
a negative for U < V.
3880
4146
3881
4147
3882
4148
File: gcrypt.info, Node: Bit manipulations, Next: Miscellaneous, Prev: Comparisons, Up: MPI library
3883
4149
3884
11.6 Bit manipulations
4150
10.6 Bit manipulations
3885
4151
======================
3886
4152
3887
4153
There are a couple of functions to get information on arbitrary bits in
3910
4176
Shift the value of A by N bits to the right and store the result
3911
4177
in X.
3912
4178
4179
-- Function: void gcry_mpi_lshift (gcry_mpi_t X, gcry_mpi_t A,
4180
unsigned int N)
4181
Shift the value of A by N bits to the left and store the result in
4182
X.
4183
3913
4184
3914
4185
File: gcrypt.info, Node: Miscellaneous, Prev: Bit manipulations, Up: MPI library
3915
4186
3916
11.7 Miscellaneous
4187
10.7 Miscellaneous
3917
4188
==================
3918
4189
3919
4190
-- Function: gcry_mpi_t gcry_mpi_set_opaque (gcry_mpi_t A, void *P,
3942
4213
3943
4214
-- Function: void gcry_mpi_clear_flag (gcry_mpi_t A,
3944
4215
enum gcry_mpi_flag FLAG)
3945
Clear FLAG for the big integer A. Note that this function is
3946
currently useless as no flags are allowed.
4216
Clear FLAG for the multi-precision-integers A. Note that this
4217
function is currently useless as no flags are allowed.
3947
4218
3948
4219
-- Function: int gcry_mpi_get_flag (gcry_mpi_t A,
3949
4220
enum gcry_mpi_flag FLAG)
3951
4222
3952
4223
-- Function: void gcry_mpi_randomize (gcry_mpi_t W,
3953
4224
unsigned int NBITS, enum gcry_random_level LEVEL)
3954
Set the big integer W to a random value of NBITS, using random
3955
data quality of level LEVEL. In case NBITS is not a multiple of a
3956
byte, NBITS is rounded up to the next byte boundary.
4225
Set the multi-precision-integers W to a random value of NBITS,
4226
using random data quality of level LEVEL. In case NBITS is not a
4227
multiple of a byte, NBITS is rounded up to the next byte boundary.
4228
When using a LEVEL of `GCRY_WEAK_RANDOM' this function makes use of
4229
`gcry_create_nonce'.
3957
4230
3958
4231
3959
4232
File: gcrypt.info, Node: Prime numbers, Next: Utilities, Prev: MPI library, Up: Top
3960
4233
3961
12 Prime numbers
4234
11 Prime numbers
3962
4235
****************
3963
4236
3964
4237
* Menu:
3969
4242
3970
4243
File: gcrypt.info, Node: Generation, Next: Checking, Up: Prime numbers
3971
4244
3972
12.1 Generation
4245
11.1 Generation
3973
4246
===============
3974
4247
3975
4248
-- Function: gcry_error_t gcry_prime_generate (gcry_mpi_t
3983
4256
prime factors and store it in FACTORS. FLAGS might be used to
3984
4257
influence the prime number generation process.
3985
4258
3986
-- Function: gcry_prime_group_generator (gcry_mpi_t *R_G,
3987
gcry_mpi_t PRIME, gcry_mpi_t *FACTORS, gcry_mpi_t START_G)
3988
4259
-- Function: gcry_error_t gcry_prime_group_generator (gcry_mpi_t *R_G,
4260
gcry_mpi_t PRIME, gcry_mpi_t *FACTORS, gcry_mpi_t START_G)
3989
4261
Find a generator for PRIME where the factorization of (PRIME-1) is
3990
4262
in the `NULL' terminated array FACTORS. Return the generator as a
3991
4263
newly allocated MPI in R_G. If START_G is not NULL, use this as
3997
4269
3998
4270
File: gcrypt.info, Node: Checking, Prev: Generation, Up: Prime numbers
3999
4271
4000
12.2 Checking
4272
11.2 Checking
4001
4273
=============
4002
4274
4003
4275
-- Function: gcry_error_t gcry_prime_check (gcry_mpi_t P, unsigned int
4008
4280
wrong.
4009
4281
4010
4282
4011
File: gcrypt.info, Node: Utilities, Next: Library Copying, Prev: Prime numbers, Up: Top
4283
File: gcrypt.info, Node: Utilities, Next: Architecture, Prev: Prime numbers, Up: Top
4012
4284
4013
13 Utilities
4285
12 Utilities
4014
4286
************
4015
4287
4016
4288
* Menu:
4020
4292
4021
4293
File: gcrypt.info, Node: Memory allocation, Up: Utilities
4022
4294
4023
13.1 Memory allocation
4295
12.1 Memory allocation
4024
4296
======================
4025
4297
4026
-- Function: void *gcry_malloc (size_t N)
4298
-- Function: void * gcry_malloc (size_t N)
4027
4299
This function tries to allocate N bytes of memory. On success it
4028
4300
returns a pointer to the memory area, in an out-of-core condition,
4029
4301
it returns NULL.
4030
4302
4031
-- Function: void *gcry_malloc_secure (size_t N)
4303
-- Function: void * gcry_malloc_secure (size_t N)
4032
4304
Like `gcry_malloc', but uses secure memory.
4033
4305
4034
-- Function: void *gcry_calloc (size_t N)
4306
-- Function: void * gcry_calloc (size_t N)
4035
4307
This function tries to allocate N bytes of cleared memory (i.e.
4036
4308
memory that is initialized with zero bytes). On success it
4037
4309
returns a pointer to the memory area, in an out-of-core condition,
4038
4310
it returns NULL.
4039
4311
4040
-- Function: void *gcry_calloc_secure (size_t N)
4312
-- Function: void * gcry_calloc_secure (size_t N)
4041
4313
Like `gcry_calloc', but uses secure memory.
4042
4314
4043
-- Function: void *gcry_realloc (void *P, size_t N)
4315
-- Function: void * gcry_realloc (void *P, size_t N)
4044
4316
This function tries to resize the memory area pointed to by P to N
4045
4317
bytes. On success it returns a pointer to the new memory area, in
4046
4318
an out-of-core condition, it returns NULL. Depending on whether
4051
4323
Release the memory area pointed to by P.
4052
4324
4053
4325
4054
File: gcrypt.info, Node: Library Copying, Next: Copying, Prev: Utilities, Up: Top
4055
4056
Appendix A GNU LESSER GENERAL PUBLIC LICENSE
4057
********************************************
4326
File: gcrypt.info, Node: Architecture, Next: Self-Tests, Prev: Utilities, Up: Top
4327
4328
13 Architecture
4329
***************
4330
4331
This chapter describes the internal architecture of Libgcrypt.
4332
4333
Libgcrypt is a function library written in ISO C-90. Any compliant
4334
compiler should be able to build Libgcrypt as long as the target is
4335
either a POSIX platform or compatible to the API used by Windows NT.
4336
Provisions have been take so that the library can be directly used from
4337
C++ applications; however building with a C++ compiler is not supported.
4338
4339
Building Libgcrypt is done by using the common `./configure && make'
4340
approach. The configure command is included in the source distribution
4341
and as a portable shell script it works on any Unix-alike system. The
4342
result of running the configure script are a C header file
4343
(`config.h'), customized Makefiles, the setup of symbolic links and a
4344
few other things. After that the make tool builds and optionally
4345
installs the library and the documentation. See the files `INSTALL'
4346
and `README' in the source distribution on how to do this.
4347
4348
Libgcrypt is developed using a Subversion(1) repository. Although
4349
all released versions are tagged in this repository, they should not be
4350
used to build production versions of Libgcrypt. Instead released
4351
tarballs should be used. These tarballs are available from several
4352
places with the master copy at <ftp://ftp.gnupg.org/gcrypt/libgcrypt/>.
4353
Announcements of new releases are posted to the
4354
<gnupg-announce@gnupg.org> mailing list(2).
4355
4356
[image src="libgcrypt-modules.png" alt="Libgcrypt subsystems" ]
4357
Figure 13.1: Libgcrypt subsystems
4358
4359
Libgcrypt consists of several subsystems (*note Figure 13.1:
4360
fig:subsystems.) and all these subsystems provide a public API; this
4361
includes the helper subsystems like the one for S-expressions. The API
4362
style depends on the subsystem; in general an open-use-close approach
4363
is implemented. The open returns a handle to a context used for all
4364
further operations on this handle, several functions may then be used
4365
on this handle and a final close function releases all resources
4366
associated with the handle.
4367
4368
* Menu:
4369
4370
* Public-Key Subsystem Architecture:: About public keys.
4371
* Symmetric Encryption Subsystem Architecture:: About standard ciphers.
4372
* Hashing and MACing Subsystem Architecture:: About hashing.
4373
* Multi-Precision-Integer Subsystem Architecture:: About big integers.
4374
* Prime-Number-Generator Subsystem Architecture:: About prime numbers.
4375
* Random-Number Subsystem Architecture:: About random stuff.
4376
4377
---------- Footnotes ----------
4378
4379
(1) A version control system available for many platforms
4380
4381
(2) See `http://www.gnupg.org/documentation/mailing-lists.en.html'
4382
for details.
4383
4384
4385
File: gcrypt.info, Node: Public-Key Subsystem Architecture, Next: Symmetric Encryption Subsystem Architecture, Up: Architecture
4386
4387
13.1 Public-Key Architecture
4388
============================
4389
4390
Libgcrypt implements two interfaces for public key cryptography: The
4391
standard interface is PK interface using functions in the `gcry_pk_'
4392
name space. The AC interface in an alternative one which is now
4393
deprecated and will not be further described. The AC interface is also
4394
disabled in FIPS mode.
4395
4396
Because public key cryptography is almost always used to process
4397
small amounts of data (hash values or session keys), the interface is
4398
not implemented using the open-use-close paradigm, but with single
4399
self-contained functions. Due to the wide variety of parameters
4400
required by different algorithms S-expressions, as flexible way to
4401
convey these parameters, are used. There is a set of helper functions
4402
to work with these S-expressions.
4403
4404
Aside of functions to register new algorithms, map algorithms names
4405
to algorithms identifiers and to lookup properties of a key, the
4406
following main functions are available:
4407
4408
`gcry_pk_encrypt'
4409
Encrypt data using a public key.
4410
4411
`gcry_pk_decrypt'
4412
Decrypt data using a private key.
4413
4414
`gcry_pk_sign'
4415
Sign data using a private key.
4416
4417
`gcry_pk_verify'
4418
Verify that a signature matches the data.
4419
4420
`gcry_pk_testkey'
4421
Perform a consistency over a public or private key.
4422
4423
`gcry_pk_genkey'
4424
Create a new public/private key pair.
4425
4426
4427
With the help of the module registration system all these functions
4428
lookup the module implementing the algorithm and pass the actual work
4429
to that module. The parsing of the S-expression input and the
4430
construction of S-expression for the return values is done by the high
4431
level code (`cipher/pubkey.c'). Thus the internal interface between
4432
the algorithm modules and the high level functions passes data in a
4433
custom format. The interface to the modules is published
4434
(`gcrypt-modules.h') so that it can used to register external
4435
implementations of algorithms with Libgcrypt. However, for some
4436
algorithms this module interface is to limited and thus for the
4437
internal modules an extra interface is sometimes used to convey more
4438
information.
4439
4440
By default Libgcrypt uses a blinding technique for RSA decryption to
4441
mitigate real world timing attacks over a network: Instead of using the
4442
RSA decryption directly, a blinded value y = x r^e \bmod n is decrypted
4443
and the unblinded value x' = y' r^-1 \bmod n returned. The blinding
4444
value r is a random value with the size of the modulus n and generated
4445
with `GCRY_WEAK_RANDOM' random level.
4446
4447
The algorithm used for RSA and DSA key generation depends on whether
4448
Libgcrypt is operated in standard or in FIPS mode. In standard mode an
4449
algorithm based on the Lim-Lee prime number generator is used. In FIPS
4450
mode RSA keys are generated as specified in ANSI X9.31 (1998) and DSA
4451
keys as specified in FIPS 186-2.
4452
4453
4454
File: gcrypt.info, Node: Symmetric Encryption Subsystem Architecture, Next: Hashing and MACing Subsystem Architecture, Prev: Public-Key Subsystem Architecture, Up: Architecture
4455
4456
13.2 Symmetric Encryption Subsystem Architecture
4457
================================================
4458
4459
The interface to work with symmetric encryption algorithms is made up
4460
of functions from the `gcry_cipher_' name space. The implementation
4461
follows the open-use-close paradigm and uses registered algorithm
4462
modules for the actual work. Unless a module implements optimized
4463
cipher mode implementations, the high level code (`cipher/cipher.c')
4464
implements the modes and calls the core algorithm functions to process
4465
each block.
4466
4467
The most important functions are:
4468
4469
`gcry_cipher_open'
4470
Create a new instance to encrypt or decrypt using a specified
4471
algorithm and mode.
4472
4473
`gcry_cipher_close'
4474
Release an instance.
4475
4476
`gcry_cipher_setkey'
4477
Set a key to be used for encryption or decryption.
4478
4479
`gcry_cipher_setiv'
4480
Set an initialization vector to be used for encryption or
4481
decryption.
4482
4483
`gcry_cipher_encrypt'
4484
`gcry_cipher_decrypt'
4485
Encrypt or decrypt data. These functions may be called with
4486
arbitrary amounts of data and as often as needed to encrypt or
4487
decrypt all data.
4488
4489
4490
There are also functions to query properties of algorithms or
4491
context, like block length, key length, map names or to enable features
4492
like padding methods.
4493
4494
4495
File: gcrypt.info, Node: Hashing and MACing Subsystem Architecture, Next: Multi-Precision-Integer Subsystem Architecture, Prev: Symmetric Encryption Subsystem Architecture, Up: Architecture
4496
4497
13.3 Hashing and MACing Subsystem Architecture
4498
==============================================
4499
4500
The interface to work with message digests and CRC algorithms is made
4501
up of functions from the `gcry_md_' name space. The implementation
4502
follows the open-use-close paradigm and uses registered algorithm
4503
modules for the actual work. Although CRC algorithms are not
4504
considered cryptographic hash algorithms, they share enough properties
4505
so that it makes sense to handle them in the same way. It is possible
4506
to use several algorithms at once with one context and thus compute
4507
them all on the same data.
4508
4509
The most important functions are:
4510
4511
`gcry_md_open'
4512
Create a new message digest instance and optionally enable one
4513
algorithm. A flag may be used to turn the message digest algorithm
4514
into a HMAC algorithm.
4515
4516
`gcry_md_enable'
4517
Enable an additional algorithm for the instance.
4518
4519
`gcry_md_setkey'
4520
Set the key for the MAC.
4521
4522
`gcry_md_write'
4523
Pass more data for computing the message digest to an instance.
4524
4525
`gcry_md_putc'
4526
Buffered version of `gcry_md_write' implemented as a macro.
4527
4528
`gcry_md_read'
4529
Finalize the computation of the message digest or HMAC and return
4530
the result.
4531
4532
`gcry_md_close'
4533
Release an instance
4534
4535
`gcry_md_hash_buffer'
4536
Convenience function to directly compute a message digest over a
4537
memory buffer without the need to create an instance first.
4538
4539
4540
There are also functions to query properties of algorithms or the
4541
instance, like enabled algorithms, digest length, map algorithm names.
4542
it is also possible to reset an instance or to copy the current state
4543
of an instance at any time. Debug functions to write the hashed data
4544
to files are available as well.
4545
4546
4547
File: gcrypt.info, Node: Multi-Precision-Integer Subsystem Architecture, Next: Prime-Number-Generator Subsystem Architecture, Prev: Hashing and MACing Subsystem Architecture, Up: Architecture
4548
4549
13.4 Multi-Precision-Integer Subsystem Architecture
4550
===================================================
4551
4552
The implementation of Libgcrypt's big integer computation code is based
4553
on an old release of GNU Multi-Precision Library (GMP). The decision
4554
not to use the GMP library directly was due to stalled development at
4555
that time and due to security requirements which could not be provided
4556
by the code in GMP. As GMP does, Libgcrypt provides high performance
4557
assembler implementations of low level code for several CPUS to gain
4558
much better performance than with a generic C implementation.
4559
4560
Major features of Libgcrypt's multi-precision-integer code compared to
4561
GMP are:
4562
4563
* Avoidance of stack based allocations to allow protection against
4564
swapping out of sensitive data and for easy zeroing of sensitive
4565
intermediate results.
4566
4567
* Optional use of secure memory and tracking of its use so that
4568
results are also put into secure memory.
4569
4570
* MPIs are identified by a handle (implemented as a pointer) to give
4571
better control over allocations and to augment them with extra
4572
properties like opaque data.
4573
4574
* Removal of unnecessary code to reduce complexity.
4575
4576
* Functions specialized for public key cryptography.
4577
4578
4579
4580
File: gcrypt.info, Node: Prime-Number-Generator Subsystem Architecture, Next: Random-Number Subsystem Architecture, Prev: Multi-Precision-Integer Subsystem Architecture, Up: Architecture
4581
4582
13.5 Prime-Number-Generator Subsystem Architecture
4583
==================================================
4584
4585
Libgcrypt provides an interface to its prime number generator. These
4586
functions make use of the internal prime number generator which is
4587
required for the generation for public key key pairs. The plain prime
4588
checking function is exported as well.
4589
4590
The generation of random prime numbers is based on the Lim and Lee
4591
algorithm to create practically save primes.(1) This algorithm creates
4592
a pool of smaller primes, select a few of them to create candidate
4593
primes of the form 2 * p_0 * p_1 * ... * p_n + 1, tests the candidate
4594
for primality and permutates the pool until a prime has been found. It
4595
is possible to clamp one of the small primes to a certain size to help
4596
DSA style algorithms. Because most of the small primes in the pool are
4597
not used for the resulting prime number, they are saved for later use
4598
(see `save_pool_prime' and `get_pool_prime' in `cipher/primegen.c').
4599
The prime generator optionally supports the finding of an appropriate
4600
generator.
4601
4602
The primality test works in three steps:
4603
4604
1. The standard sieve algorithm using the primes up to 4999 is used
4605
as a quick first check.
4606
4607
2. A Fermat test filters out almost all non-primes.
4608
4609
3. A 5 round Rabin-Miller test is finally used. The first round uses
4610
a witness of 2, whereas the next rounds use a random witness.
4611
4612
4613
To support the generation of RSA and DSA keys in FIPS mode according
4614
to X9.31 and FIPS 186-2, Libgcrypt implements two additional prime
4615
generation functions: `_gcry_derive_x931_prime' and
4616
`_gcry_generate_fips186_2_prime'. These functions are internal and not
4617
available through the public API.
4618
4619
---------- Footnotes ----------
4620
4621
(1) Chae Hoon Lim and Pil Joong Lee. A key recovery attack on
4622
discrete log-based shemes using a prime order subgroup. In Burton S.
4623
Kaliski Jr., editor, Advances in Cryptology: Crypto '97, pages
4624
249-263, Berlin / Heidelberg / New York, 1997. Springer-Verlag.
4625
Described on page 260.
4626
4627
4628
File: gcrypt.info, Node: Random-Number Subsystem Architecture, Prev: Prime-Number-Generator Subsystem Architecture, Up: Architecture
4629
4630
13.6 Random-Number Subsystem Architecture
4631
=========================================
4632
4633
Libgcrypt provides 3 levels or random quality: The level
4634
`GCRY_VERY_STRONG_RANDOM' usually used for key generation, the level
4635
`GCRY_STRONG_RANDOM' for all other strong random requirements and the
4636
function `gcry_create_nonce' which is used for weaker usages like
4637
nonces. There is also a level `GCRY_WEAK_RANDOM' which in general maps
4638
to `GCRY_STRONG_RANDOM' except when used with the function
4639
`gcry_mpi_randomize', where it randomizes an multi-precision-integer
4640
using the `gcry_create_nonce' function.
4641
4642
There are two distinct random generators available:
4643
4644
* The Continuously Seeded Pseudo Random Number Generator (CSPRNG),
4645
which is based on the classic GnuPG derived big pool
4646
implementation. Implemented in `random/random-csprng.c' and used
4647
by default.
4648
4649
* A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key.
4650
Implemented in `random/random-fips.c' and used if Libgcrypt is in
4651
FIPS mode.
4652
4653
Both generators make use of so-called entropy gathering modules:
4654
4655
rndlinux
4656
Uses the operating system provided `/dev/random' and
4657
`/dev/urandom' devices.
4658
4659
rndunix
4660
Runs several operating system commands to collect entropy from
4661
sources like virtual machine and process statistics. It is a kind
4662
of poor-man's `/dev/random' implementation. It is not available in
4663
FIPS mode.
4664
4665
rndegd
4666
Uses the operating system provided Entropy Gathering Daemon (EGD).
4667
The EGD basically uses the same algorithms as rndunix does.
4668
However as a system daemon it keeps on running and thus can serve
4669
several processes requiring entropy input and does not waste
4670
collected entropy if the application does not need all the
4671
collected entropy. It is not available in FIPS mode.
4672
4673
rndw32
4674
Targeted for the Microsoft Windows OS. It uses certain properties
4675
of that system and is the only gathering module available for that
4676
OS.
4677
4678
rndhw
4679
Extra module to collect additional entropy by utilizing a hardware
4680
random number generator. As of now the only supported hardware
4681
RNG is the Padlock engine of VIA (Centaur) CPUs. It is not
4682
available in FIPS mode.
4683
4684
4685
* Menu:
4686
4687
* CSPRNG Description:: Description of the CSPRNG.
4688
* FIPS PRNG Description:: Description of the FIPS X9.31 PRNG.
4689
4690
4691
File: gcrypt.info, Node: CSPRNG Description, Next: FIPS PRNG Description, Up: Random-Number Subsystem Architecture
4692
4693
13.6.1 Description of the CSPRNG
4694
--------------------------------
4695
4696
This random number generator is loosely modelled after the one
4697
described in Peter Gutmann's paper: "Software Generation of Practically
4698
Strong Random Numbers".(1)
4699
4700
A pool of 600 bytes is used and mixed using the core RIPE-MD160 hash
4701
transform function. Several extra features are used to make the robust
4702
against a wide variety of attacks and to protect against failures of
4703
subsystems. The state of the generator may be saved to a file and
4704
initially seed form a file.
4705
4706
Depending on how Libgcrypt was build the generator is able to select
4707
the best working entropy gathering module. It makes use of the slow
4708
and fast collection methods and requires the pool to initially seeded
4709
form the slow gatherer or a seed file. An entropy estimation is used
4710
to mix in enough data from the gather modules before returning the
4711
actual random output. Process fork detection and protection is
4712
implemented.
4713
4714
The implementation of the nonce generator (for `gcry_create_nonce')
4715
is a straightforward repeated hash design: A 28 byte buffer is
4716
initially seeded with the PID and the time in seconds in the first 20
4717
bytes and with 8 bytes of random taken from the `GCRY_STRONG_RANDOM'
4718
generator. Random numbers are then created by hashing all the 28 bytes
4719
with SHA-1 and saving that again in the first 20 bytes. The hash is
4720
also returned as result.
4721
4722
---------- Footnotes ----------
4723
4724
(1) Also described in chapter 6 of his book "Cryptographic Security
4725
Architecture", New York, 2004, ISBN 0-387-95387-6.
4726
4727
4728
File: gcrypt.info, Node: FIPS PRNG Description, Prev: CSPRNG Description, Up: Random-Number Subsystem Architecture
4729
4730
13.6.2 Description of the FIPS X9.31 PRNG
4731
-----------------------------------------
4732
4733
The core of this deterministic random number generator is implemented
4734
according to the document "NIST-Recommended Random Number Generator
4735
Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES
4736
Algorithms", dated 2005-01-31. This implementation uses the AES
4737
variant.
4738
4739
The generator is based on contexts to utilize the same core functions
4740
for all random levels as required by the high-level interface. All
4741
random generators return their data in 128 bit blocks. If the caller
4742
requests less bits, the extra bits are not used. The key for each
4743
generator is only set once at the first time a generator context is
4744
used. The seed value is set along with the key and again after 1000
4745
output blocks.
4746
4747
On Unix like systems the `GCRY_VERY_STRONG_RANDOM' and
4748
`GCRY_STRONG_RANDOM' generators are keyed and seeded using the rndlinux
4749
module with the `/dev/radnom' device. Thus these generators may block
4750
until the OS kernel has collected enough entropy. When used with
4751
Microsoft Windows the rndw32 module is used instead.
4752
4753
The generator used for `gcry_create_nonce' is keyed and seeded from
4754
the `GCRY_STRONG_RANDOM' generator. Thus is may also block if the
4755
`GCRY_STRONG_RANDOM' generator has not yet been used before and thus
4756
gets initialized on the first use by `gcry_create_nonce'. This special
4757
treatment is justified by the weaker requirements for a nonce generator
4758
and to save precious kernel entropy for use by the "real" random
4759
generators.
4760
4761
A self-test facility uses a separate context to check the
4762
functionality of the core X9.31 functions using a known answers test.
4763
During runtime each output block is compared to the previous one to
4764
detect a stucked generator.
4765
4766
The DT value for the generator is made up of the current time down to
4767
microseconds (if available) and a free running 64 bit counter. When
4768
used with the test context the DT value is taken from the context and
4769
incremented on each use.
4770
4771
4772
File: gcrypt.info, Node: Self-Tests, Next: FIPS Mode, Prev: Architecture, Up: Top
4773
4774
Appendix A Description of the Self-Tests
4775
****************************************
4776
4777
In addition to the build time regression test suite, Libgcrypt
4778
implements self-tests to be performed at runtime. Which self-tests are
4779
actually used depends on the mode Libgcrypt is used in. In standard
4780
mode a limited set of self-tests is run at the time an algorithm is
4781
first used. Note that not all algorithms feature a self-test in
4782
standard mode. The `GCRYCTL_SELFTEST' control command may be used to
4783
run all implemented self-tests at any time; this will even run more
4784
tests than those run in FIPS mode.
4785
4786
If any of the self-tests fails, the library immediately returns an
4787
error code to the caller. If Libgcrypt is in FIPS mode the self-tests
4788
will be performed within the "Self-Test" state and any failure puts the
4789
library into the "Error" state.
4790
4791
A.1 Power-Up Tests
4792
==================
4793
4794
Power-up tests are only performed if Libgcrypt is in FIPS mode.
4795
4796
A.1.1 Symmetric Cipher Algorithm Power-Up Tests
4797
-----------------------------------------------
4798
4799
The following symmetric encryption algorithm tests are run during
4800
power-up:
4801
4802
3DES
4803
To test the 3DES 3-key EDE encryption in ECB mode these tests are
4804
run:
4805
1. A known answer test is run on a 64 bit test vector processed
4806
by 64 rounds of Single-DES block encryption and decryption
4807
using a key changed with each round.
4808
4809
2. A known answer test is run on a 64 bit test vector processed
4810
by 16 rounds of 2-key and 3-key Triple-DES block encryption
4811
and decryptions using a key changed with each round.
4812
4813
3. 10 known answer tests using 3-key Triple-DES EDE encryption,
4814
comparing the ciphertext to the known value, then running a
4815
decryption and comparing it to the initial plaintext.
4816
(`cipher/des.c:selftest')
4817
4818
AES-128
4819
A known answer tests is run using one test vector and one test key
4820
with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_128')
4821
4822
AES-192
4823
A known answer tests is run using one test vector and one test key
4824
with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_192')
4825
4826
AES-256
4827
A known answer tests is run using one test vector and one test key
4828
with AES in ECB mode. (`cipher/rijndael.c:selftest_basic_256')
4829
4830
A.1.2 Hash Algorithm Power-Up Tests
4831
-----------------------------------
4832
4833
The following hash algorithm tests are run during power-up:
4834
4835
SHA-1
4836
A known answer test using the string `"abc"' is run.
4837
(`cipher/sha1.c:selftests_sha1')
4838
4839
SHA-224
4840
A known answer test using the string `"abc"' is run.
4841
(`cipher/sha256.c:selftests_sha224')
4842
4843
SHA-256
4844
A known answer test using the string `"abc"' is run.
4845
(`cipher/sha256.c:selftests_sha256')
4846
4847
SHA-384
4848
A known answer test using the string `"abc"' is run.
4849
(`cipher/sha512.c:selftests_sha384')
4850
4851
SHA-512
4852
A known answer test using the string `"abc"' is run.
4853
(`cipher/sha512.c:selftests_sha512')
4854
4855
A.1.3 MAC Algorithm Power-Up Tests
4856
----------------------------------
4857
4858
The following MAC algorithm tests are run during power-up:
4859
4860
HMAC SHA-1
4861
A known answer test using 9 byte of data and a 64 byte key is run.
4862
(`cipher/hmac-tests.c:selftests_sha1')
4863
4864
HMAC SHA-224
4865
A known answer test using 28 byte of data and a 4 byte key is run.
4866
(`cipher/hmac-tests.c:selftests_sha224')
4867
4868
HMAC SHA-256
4869
A known answer test using 28 byte of data and a 4 byte key is run.
4870
(`cipher/hmac-tests.c:selftests_sha256')
4871
4872
HMAC SHA-384
4873
A known answer test using 28 byte of data and a 4 byte key is run.
4874
(`cipher/hmac-tests.c:selftests_sha384')
4875
4876
HMAC SHA-512
4877
A known answer test using 28 byte of data and a 4 byte key is run.
4878
(`cipher/hmac-tests.c:selftests_sha512')
4879
4880
A.1.4 Random Number Power-Up Test
4881
---------------------------------
4882
4883
The DRNG is tested during power-up this way:
4884
4885
1. Requesting one block of random using the public interface to check
4886
general working and the duplicated block detection.
4887
4888
2. 3 know answer tests using pre-defined keys, seed and initial DT
4889
values. For each test 3 blocks of 16 bytes are requested and
4890
compared to the expected result. The DT value is incremented for
4891
each block.
4892
4893
A.1.5 Public Key Algorithm Power-Up Tests
4894
-----------------------------------------
4895
4896
The public key algorithms are tested during power-up:
4897
4898
RSA
4899
A pre-defined 1024 bit RSA key is used and these tests are run in
4900
turn:
4901
1. Conversion of S-expression to internal format.
4902
(`cipher/rsa.c:selftests_rsa')
4903
4904
2. Private key consistency check. (`cipher/rsa.c:selftests_rsa')
4905
4906
3. A pre-defined 20 byte value is signed with PKCS#1 padding for
4907
SHA-1. The result is verified using the public key against
4908
the original data and against modified data.
4909
(`cipher/rsa.c:selftest_sign_1024')
4910
4911
4. A 1000 bit random value is encrypted and checked that it does
4912
not match the orginal random value. The encrtypted result is
4913
then decrypted and checked that it macthes the original
4914
random value. (`cipher/rsa.c:selftest_encr_1024')
4915
4916
DSA
4917
A pre-defined 1024 bit DSA key is used and these tests are run in
4918
turn:
4919
1. Conversion of S-expression to internal format.
4920
(`cipher/dsa.c:selftests_dsa')
4921
4922
2. Private key consistency check. (`cipher/dsa.c:selftests_dsa')
4923
4924
3. A pre-defined 20 byte value is signed with PKCS#1 padding for
4925
SHA-1. The result is verified using the public key against
4926
the original data and against modified data.
4927
(`cipher/dsa.c:selftest_sign_1024')
4928
4929
A.1.6 Integrity Power-Up Tests
4930
------------------------------
4931
4932
The integrity of the Libgcrypt is tested during power-up but only if
4933
checking has been enabled at build time. The check works by computing
4934
a HMAC SHA-256 checksum over the file used to load Libgcrypt into
4935
memory. That checksum is compared against a checksum stored in a file
4936
of the same name but with a single dot as a prefix and a suffix of
4937
`.hmac'.
4938
4939
A.1.7 Critical Functions Power-Up Tests
4940
---------------------------------------
4941
4942
The 3DES weak key detection is tested during power-up by calling the
4943
detection function with keys taken from a table listening all weak
4944
keys. The table itself is protected using a SHA-1 hash.
4945
(`cipher/des.c:selftest')
4946
4947
A.2 Conditional Tests
4948
=====================
4949
4950
The conditional tests are performed if a certain contidion is met.
4951
This may occur at any time; the library does not necessary enter the
4952
"Self-Test" state to run these tests but will transit to the "Error"
4953
state if a test failed.
4954
4955
A.2.1 Key-Pair Generation Tests
4956
-------------------------------
4957
4958
After an asymmetric key-pair has been generated, Libgcrypt runs a
4959
pair-wise consistency tests on the generated key. On failure the
4960
generated key is not used, an error code is returned and, if in FIPS
4961
mode, the library is put into the "Error" state.
4962
4963
RSA
4964
The test uses a random number 64 bits less the size of the modulus
4965
as plaintext and runs an encryption and decryption operation in
4966
turn. The encrypted value is checked to not match the plaintext
4967
and the result of the decryption is checked to match the plaintext.
4968
4969
A new random number of the same size is generated, signed and
4970
verified to test the correctness of the signing operation. As a
4971
second signing test, the signature is modified by incrementing its
4972
value and then verified with the expected result that the
4973
verification fails. (`cipher/rsa.c:test_keys')
4974
4975
DSA
4976
The test uses a random number of the size of the Q parameter to
4977
create a signature and then checks that the signature verifies.
4978
As a second signing test, the data is modified by incrementing its
4979
value and then verified against the signature with the expected
4980
result that the verification fails. (`cipher/dsa.c:test_keys')
4981
4982
A.2.2 Software Load Tests
4983
-------------------------
4984
4985
Loading of extra modules into libgcrypt is disabled in FIPS mode and
4986
thus no tests are implemented. (`cipher/cipher.c:gcry_cipher_register',
4987
`cipher/md.c:gcry_md_register', `cipher/md.c:gcry_pk_register')
4988
4989
A.2.3 Manual Key Entry Tests
4990
----------------------------
4991
4992
A manual key entry feature is not implemented in Libgcrypt.
4993
4994
A.2.4 Continuous RNG Tests
4995
--------------------------
4996
4997
The continuous random number test is only used in FIPS mode. The RNG
4998
generates blocks of 128 bit size; the first block generated per context
4999
is saved in the context and another block is generated to be returned
5000
to the caller. Each block is compared against the saved block and then
5001
stored in the context. If a duplicated block is detected an error is
5002
signaled and the libray is put into the "Fatal-Error" state.
5003
(`random/random-fips.c:x931_aes_driver')
5004
5005
A.3 Application Requested Tests
5006
===============================
5007
5008
The application may requests tests at any time by means of the
5009
`GCRYCTL_SELFTEST' control command. Note that using these tests is not
5010
FIPS conform: Although Libgcrypt rejects all application requests for
5011
services while running self-tests, it does not ensure that no other
5012
operations of Libgcrypt are still being executed. Thus, in FIPS mode
5013
an application requesting self-tests needs to power-cycle Libgcrypt
5014
instead.
5015
5016
When self-tests are requested, Libgcrypt runs all the tests it does
5017
during power-up as well as a few extra checks as described below.
5018
5019
A.3.1 Symmetric Cipher Algorithm Tests
5020
--------------------------------------
5021
5022
The following symmetric encryption algorithm tests are run in addition
5023
to the power-up tests:
5024
5025
AES-128
5026
A known answer tests with test vectors taken from NIST SP800-38a
5027
and using the high level functions is run for block modes CFB and
5028
OFB.
5029
5030
5031
A.3.2 Hash Algorithm Tests
5032
--------------------------
5033
5034
The following hash algorithm tests are run in addition to the power-up
5035
tests:
5036
5037
SHA-1
5038
SHA-224
5039
SHA-256
5040
1. A known answer test using a 56 byte string is run.
5041
5042
2. A known answer test using a string of one million letters "a"
5043
is run.
5044
(`cipher/sha1.c:selftests_sha1',
5045
`cipher/sha256.c:selftests_sha224',
5046
`cipher/sha256.c:selftests_sha256')
5047
5048
SHA-384
5049
5050
SHA-512
5051
1. A known answer test using a 112 byte string is run.
5052
5053
2. A known answer test using a string of one million letters "a"
5054
is run.
5055
(`cipher/sha512.c:selftests_sha384',
5056
`cipher/sha512.c:selftests_sha512')
5057
5058
A.3.3 MAC Algorithm Tests
5059
-------------------------
5060
5061
The following MAC algorithm tests are run in addition to the power-up
5062
tests:
5063
5064
HMAC SHA-1
5065
1. A known answer test using 9 byte of data and a 20 byte key is
5066
run.
5067
5068
2. A known answer test using 9 byte of data and a 100 byte key
5069
is run.
5070
5071
3. A known answer test using 9 byte of data and a 49 byte key is
5072
run.
5073
(`cipher/hmac-tests.c:selftests_sha1')
5074
5075
HMAC SHA-224
5076
HMAC SHA-256
5077
HMAC SHA-384
5078
HMAC SHA-512
5079
1. A known answer test using 9 byte of data and a 20 byte key is
5080
run.
5081
5082
2. A known answer test using 50 byte of data and a 20 byte key
5083
is run.
5084
5085
3. A known answer test using 50 byte of data and a 26 byte key
5086
is run.
5087
5088
4. A known answer test using 54 byte of data and a 131 byte key
5089
is run.
5090
5091
5. A known answer test using 152 byte of data and a 131 byte key
5092
is run.
5093
(`cipher/hmac-tests.c:selftests_sha224',
5094
`cipher/hmac-tests.c:selftests_sha256',
5095
`cipher/hmac-tests.c:selftests_sha384',
5096
`cipher/hmac-tests.c:selftests_sha512')
5097
5098
5099
File: gcrypt.info, Node: FIPS Mode, Next: Library Copying, Prev: Self-Tests, Up: Top
5100
5101
Appendix B Description of the FIPS Mode
5102
***************************************
5103
5104
This appendix gives detailed information pertaining to the FIPS mode.
5105
In particular, the changes to the standard mode and the finite state
5106
machine are described. The self-tests required in this mode are
5107
described in the appendix on self-tests.
5108
5109
B.1 Restrictions in FIPS Mode
5110
=============================
5111
5112
If Libgcrypt is used in FIPS mode these restrictions are effective:
5113
5114
* The cryptographic algorithms are restricted to this list:
5115
5116
GCRY_CIPHER_3DES
5117
3 key EDE Triple-DES symmetric encryption.
5118
5119
GCRY_CIPHER_AES128
5120
AES 128 bit symmetric encryption.
5121
5122
GCRY_CIPHER_AES192
5123
AES 192 bit symmetric encryption.
5124
5125
GCRY_CIPHER_AES256
5126
AES 256 bit symmetric encryption.
5127
5128
GCRY_MD_SHA1
5129
SHA-1 message digest.
5130
5131
GCRY_MD_SHA224
5132
SHA-224 message digest.
5133
5134
GCRY_MD_SHA256
5135
SHA-256 message digest.
5136
5137
GCRY_MD_SHA384
5138
SHA-384 message digest.
5139
5140
GCRY_MD_SHA512
5141
SHA-512 message digest.
5142
5143
GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC
5144
HMAC using a SHA-1 message digest.
5145
5146
GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC
5147
HMAC using a SHA-224 message digest.
5148
5149
GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC
5150
HMAC using a SHA-256 message digest.
5151
5152
GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC
5153
HMAC using a SHA-384 message digest.
5154
5155
GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
5156
HMAC using a SHA-512 message digest.
5157
5158
GCRY_PK_RSA
5159
RSA encryption and signing.
5160
5161
GCRY_PK_DSA
5162
DSA signing.
5163
5164
Note that the CRC algorithms are not considered cryptographic
5165
algorithms and thus are in addition available.
5166
5167
* RSA key generation refuses to create a key with a keysize of less
5168
than 1024 bits.
5169
5170
* DSA key generation refuses to create a key with a keysize other
5171
than 1024 bits.
5172
5173
* The `transient-key' flag for RSA and DSA key generation is ignored.
5174
5175
* Support for the VIA Padlock engine is disabled.
5176
5177
* FIPS mode may only be used on systems with a /dev/random device.
5178
Switching into FIPS mode on other systems will fail at runtime.
5179
5180
* Saving and loading a random seed file is ignored.
5181
5182
* An X9.31 style random number generator is used in place of the
5183
large-pool-CSPRNG generator.
5184
5185
* The command `GCRYCTL_ENABLE_QUICK_RANDOM' is ignored.
5186
5187
* The Alternative Public Key Interface (`gcry_ac_xxx') is not
5188
supported and all API calls return an error.
5189
5190
* Registration of external modules is not supported.
5191
5192
* Message digest debugging is disabled.
5193
5194
* All debug output related to cryptographic data is suppressed.
5195
5196
* On-the-fly self-tests are not performed, instead self-tests are run
5197
before entering operational state.
5198
5199
* The function `gcry_set_allocation_handler' may not be used. If it
5200
is used Libgcrypt disables FIPS mode unless Enforced FIPS mode is
5201
enabled, in which case Libgcrypt will enter the error state.
5202
5203
* The digest algorithm MD5 may not be used. If it is used Libgcrypt
5204
disables FIPS mode unless Enforced FIPS mode is enabled, in which
5205
case Libgcrypt will enter the error state.
5206
5207
* In Enforced FIPS mode the command `GCRYCTL_DISABLE_SECMEM' is
5208
ignored. In standard FIPS mode it disables FIPS mode.
5209
5210
* A handler set by `gcry_set_outofcore_handler' is ignored.
5211
5212
* A handler set by `gcry_set_fatalerror_handler' is ignored.
5213
5214
5215
Note that when we speak about disabling FIPS mode, it merely means
5216
that the function `gcry_fips_mode_active' returns false; it does not
5217
mean that any non FIPS algorithms are allowed.
5218
5219
B.2 FIPS Finite State Machine
5220
=============================
5221
5222
The FIPS mode of libgcrypt implements a finite state machine (FSM) using
5223
8 states (*note tbl:fips-states::) and checks at runtime that only valid
5224
transitions (*note tbl:fips-state-transitions::) may happen.
5225
5226
[image src="fips-fsm.png" alt="FIPS FSM Diagram" ]
5227
Figure B.1: FIPS mode state diagram
5228
5229
States used by the FIPS FSM:
5230
Power-Off
5231
Libgcrypt is not runtime linked to another application. This
5232
usually means that the library is not loaded into main memory.
5233
This state is documentation only.
5234
5235
Power-On
5236
Libgcrypt is loaded into memory and API calls may be made.
5237
Compiler introducted constructor functions may be run. Note that
5238
Libgcrypt does not implement any arbitrary constructor functions
5239
to be called by the operating system
5240
5241
Init
5242
The Libgcrypt initialization functions are performed and the
5243
library has not yet run any self-test.
5244
5245
Self-Test
5246
Libgcrypt is performing self-tests.
5247
5248
Operational
5249
Libgcrypt is in the operational state and all interfaces may be
5250
used.
5251
5252
Error
5253
Libgrypt is in the error state. When calling any FIPS relevant
5254
interfaces they either return an error (`GPG_ERR_NOT_OPERATIONAL')
5255
or put Libgcrypt into the Fatal-Error state and won't return.
5256
5257
Fatal-Error
5258
Libgcrypt is in a non-recoverable error state and will
5259
automatically transit into the Shutdown state.
5260
5261
Shutdown
5262
Libgcrypt is about to be terminated and removed from the memory.
5263
The application may at this point still runing cleanup handlers.
5264
5265
5266
Table B.1: FIPS mode states
5267
5268
The valid state transitions (*note Figure B.1: fig:fips-fsm.) are:
5269
`1'
5270
Power-Off to Power-On is implicitly done by the OS loading
5271
Libgcrypt as a shared library and having it linked to an
5272
application.
5273
5274
`2'
5275
Power-On to Init is triggered by the application calling the
5276
Libgcrypt intialization function `gcry_check_version'.
5277
5278
`3'
5279
Init to Self-Test is either triggred by a dedicated API call or
5280
implicit by invoking a libgrypt service conrolled by the FSM.
5281
5282
`4'
5283
Self-Test to Operational is triggered after all self-tests passed
5284
successfully.
5285
5286
`5'
5287
Operational to Shutdown is an artifical state without any direct
5288
action in Libgcrypt. When reaching the Shutdown state the library
5289
is deinitialized and can't return to any other state again.
5290
5291
`6'
5292
Shutdown to Power-off is the process of removing Libgcrypt from the
5293
computer's memory. For obvious reasons the Power-Off state can't
5294
be represented within Libgcrypt and thus this transition is for
5295
documentation only.
5296
5297
`7'
5298
Operational to Error is triggered if Libgcrypt detected an
5299
application error which can't be returned to the caller but still
5300
allows Libgcrypt to properly run. In the Error state all FIPS
5301
relevant interfaces return an error code.
5302
5303
`8'
5304
Error to Shutdown is similar to the Operational to Shutdown
5305
transition (5).
5306
5307
`9'
5308
Error to Fatal-Error is triggred if Libgrypt detects an fatal error
5309
while already being in Error state.
5310
5311
`10'
5312
Fatal-Error to Shutdown is automatically entered by Libgcrypt
5313
after having reported the error.
5314
5315
`11'
5316
Power-On to Shutdown is an artifical state to document that
5317
Libgcrypt has not ye been initializaed but the process is about to
5318
terminate.
5319
5320
`12'
5321
Power-On to Fatal-Error will be triggerd if certain Libgcrypt
5322
functions are used without having reached the Init state.
5323
5324
`13'
5325
Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt
5326
while running self-tests.
5327
5328
`14'
5329
Self-Test to Error is triggred by a failed self-test.
5330
5331
`15'
5332
Operational to Fatal-Error is triggered if Libcrypt encountered a
5333
non-recoverable error.
5334
5335
`16'
5336
Operational to Self-Test is triggred if the application requested
5337
to run the self-tests again.
5338
5339
`17'
5340
Error to Self-Test is triggered if the application has requested
5341
to run self-tests to get to get back into operational state after
5342
an error.
5343
5344
`18'
5345
Init to Error is triggered by errors in the initialization code.
5346
5347
`19'
5348
Init to Fatal-Error is triggered by non-recoverable errors in the
5349
initialization code.
5350
5351
`20'
5352
Error to Error is triggered by errors while already in the Error
5353
state.
5354
5355
5356
Table B.2: FIPS mode state transitions
5357
5358
B.3 FIPS Miscellaneous Information
5359
==================================
5360
5361
Libgcrypt does not do any key management on itself; the application
5362
needs to care about it. Keys which are passed to Libgcrypt should be
5363
allocated in secure memory as available with the functions
5364
`gcry_malloc_secure' and `gcry_calloc_secure'. By calling `gcry_free'
5365
on this memory, the memory and thus the keys are overwritten with zero
5366
bytes before releasing the memory.
5367
5368
For use with the random number generator, Libgcrypt generates 3
5369
internal keys which are stored in the encryption contexts used by the
5370
RNG. These keys are stored in secure memory for the lifetime of the
5371
process. Application are required to use `GCRYCTL_TERM_SECMEM' before
5372
process termination. This will zero out the entire secure memory and
5373
thus also the encryption contexts with these keys.
5374
5375
5376
File: gcrypt.info, Node: Library Copying, Next: Copying, Prev: FIPS Mode, Up: Top
5377
5378
GNU Lesser General Public License
5379
*********************************
4058
5380
4059
5381
Version 2.1, February 1999
4060
5382
4068
5390
as the successor of the GNU Library Public License, version 2, hence the
4069
5391
version number 2.1.]
4070
5392
4071
A.0.1 Preamble
4072
--------------
5393
Preamble
5394
========
4073
5395
4074
5396
The licenses for most software are designed to take away your freedom
4075
5397
to share and change it. By contrast, the GNU General Public Licenses
4526
5848
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
4527
5849
4528
5850
END OF TERMS AND CONDITIONS
4529
A.0.2 How to Apply These Terms to Your New Libraries
4530
----------------------------------------------------
5851
How to Apply These Terms to Your New Libraries
5852
==============================================
4531
5853
4532
5854
If you develop a new library, and you want it to be of the greatest
4533
5855
possible use to the public, we recommend making it free software that
4575
5897
That's all there is to it!
4576
5898
4577
5899
4578
File: gcrypt.info, Node: Copying, Next: Concept Index, Prev: Library Copying, Up: Top
5900
File: gcrypt.info, Node: Copying, Next: Figures and Tables, Prev: Library Copying, Up: Top
4579
5901
4580
Appendix B GNU GENERAL PUBLIC LICENSE
4581
*************************************
5902
GNU General Public License
5903
**************************
4582
5904
4583
5905
Version 2, June 1991
4584
5906
4588
5910
Everyone is permitted to copy and distribute verbatim copies
4589
5911
of this license document, but changing it is not allowed.
4590
5912
4591
B.0.1 Preamble
4592
--------------
5913
Preamble
5914
========
4593
5915
4594
5916
The licenses for most software are designed to take away your freedom
4595
5917
to share and change it. By contrast, the GNU General Public License is
4936
6258
GNU Library General Public License instead of this License.
4937
6259
4938
6260
4939
File: gcrypt.info, Node: Concept Index, Next: Function and Data Index, Prev: Copying, Up: Top
6261
File: gcrypt.info, Node: Figures and Tables, Next: Concept Index, Prev: Copying, Up: Top
6262
6263
List of Figures and Tables
6264
**************************
6265
6266
* Menu:
6267
6268
* Figure 13.1: Libgcrypt subsystems: fig:subsystems.
6269
* Figure B.1: FIPS mode state ...: fig:fips-fsm.
6270
6271
* Menu:
6272
6273
* Table B.1: FIPS mode states: tbl:fips-states.
6274
* Table B.2: FIPS mode state ...: tbl:fips-state-transitions.
6275
6276
6277
File: gcrypt.info, Node: Concept Index, Next: Function and Data Index, Prev: Figures and Tables, Up: Top
4940
6278
4941
6279
Concept Index
4942
6280
*************
4944
6282
[index ]
4945
6283
* Menu:
4946
6284
4947
* error codes: Error Values. (line 6)
4948
* error codes, list of <1>: Error Codes. (line 6)
4949
* error codes, list of: Error Sources. (line 6)
4950
* error codes, printing of: Error Strings. (line 6)
4951
* error sources: Error Values. (line 6)
4952
* error sources, printing of: Error Strings. (line 6)
4953
* error strings: Error Strings. (line 6)
4954
* error values: Error Values. (line 6)
4955
* error values, printing of: Error Strings. (line 6)
4956
* GPL, GNU General Public License: Copying. (line 6)
4957
* LGPL, Lesser General Public License: Library Copying. (line 6)
6285
* 3DES: Available ciphers. (line 16)
6286
* Advanced Encryption Standard: Available ciphers. (line 37)
6287
* AES: Available ciphers. (line 37)
6288
* Arcfour: Available ciphers. (line 54)
6289
* Blowfish: Available ciphers. (line 24)
6290
* Camellia: Available ciphers. (line 81)
6291
* CAST5: Available ciphers. (line 21)
6292
* CBC, Cipher Block Chaining mode: Available cipher modes.
6293
(line 20)
6294
* CBC-MAC: Working with cipher handles.
6295
(line 52)
6296
* CFB, Cipher Feedback mode: Available cipher modes.
6297
(line 16)
6298
* cipher text stealing: Working with cipher handles.
6299
(line 45)
6300
* CRC32: Available hash algorithms.
6301
(line 6)
6302
* CTR, Counter mode: Available cipher modes.
6303
(line 29)
6304
* DES: Available ciphers. (line 59)
6305
* DES-EDE: Available ciphers. (line 16)
6306
* Digital Encryption Standard: Available ciphers. (line 16)
6307
* ECB, Electronic Codebook mode: Available cipher modes.
6308
(line 13)
6309
* Enforced FIPS mode: Enabling FIPS mode. (line 30)
6310
* error codes: Error Values. (line 6)
6311
* error codes, list of <1>: Error Codes. (line 6)
6312
* error codes, list of: Error Sources. (line 6)
6313
* error codes, printing of: Error Strings. (line 6)
6314
* error sources: Error Values. (line 6)
6315
* error sources, printing of: Error Strings. (line 6)
6316
* error strings: Error Strings. (line 6)
6317
* error values: Error Values. (line 6)
6318
* error values, printing of: Error Strings. (line 6)
6319
* FIPS 140: Enabling FIPS mode. (line 6)
6320
* FIPS 186 <1>: Public-Key Subsystem Architecture.
6321
(line 63)
6322
* FIPS 186: General public-key related Functions.
6323
(line 256)
6324
* FIPS mode: Enabling FIPS mode. (line 6)
6325
* GPL, GNU General Public License: Copying. (line 6)
6326
* HAVAL: Available hash algorithms.
6327
(line 6)
6328
* HMAC: Working with hash algorithms.
6329
(line 27)
6330
* IDEA: Available ciphers. (line 11)
6331
* LGPL, GNU Lesser General Public License: Library Copying. (line 6)
6332
* MD2, MD4, MD5: Available hash algorithms.
6333
(line 6)
6334
* OFB, Output Feedback mode: Available cipher modes.
6335
(line 26)
6336
* RC2: Available ciphers. (line 71)
6337
* RC4: Available ciphers. (line 54)
6338
* rfc-2268: Available ciphers. (line 71)
6339
* Rijndael: Available ciphers. (line 37)
6340
* RIPE-MD-160: Available hash algorithms.
6341
(line 6)
6342
* Seed (cipher): Available ciphers. (line 76)
6343
* Serpent: Available ciphers. (line 67)
6344
* SHA-1: Available hash algorithms.
6345
(line 6)
6346
* SHA-224, SHA-256, SHA-384, SHA-512: Available hash algorithms.
6347
(line 6)
6348
* sync mode (OpenPGP): Working with cipher handles.
6349
(line 40)
6350
* TIGER: Available hash algorithms.
6351
(line 6)
6352
* Triple-DES: Available ciphers. (line 16)
6353
* Twofish: Available ciphers. (line 48)
6354
* Whirlpool: Available hash algorithms.
6355
(line 6)
6356
* X9.31 <1>: Public-Key Subsystem Architecture.
6357
(line 63)
6358
* X9.31: General public-key related Functions.
6359
(line 249)
4958
6360
4959
6361
4960
6362
File: gcrypt.info, Node: Function and Data Index, Prev: Concept Index, Up: Top
4965
6367
[index ]
4966
6368
* Menu:
4967
6369
4968
* (: Generation. (line 18)
4969
* *: Retrieving random numbers.
4970
(line 13)
4971
* *gcry_calloc: Memory allocation. (line 15)
4972
* *gcry_calloc_secure: Memory allocation. (line 21)
4973
* *gcry_malloc: Memory allocation. (line 7)
4974
* *gcry_malloc_secure: Memory allocation. (line 12)
4975
* *gcry_realloc: Memory allocation. (line 24)
4976
* *gcry_sexp_nth_string: Working with S-expressions.
4977
(line 176)
4978
6370
* AM_PATH_LIBGCRYPT: Building sources using Automake.
4979
6371
(line 13)
4980
* char <1>: Working with hash algorithms.
4981
(line 118)
4982
* char <2>: General cipher functions.
4983
(line 39)
4984
* char: Initializing the library.
4985
(line 17)
4986
* enum: Quality of random numbers.
4987
(line 9)
4988
6372
* gcry_ac_close: Working with handles.
4989
6373
(line 21)
4990
6374
* gcry_ac_data_clear: Working with sets of data.
5011
6395
(line 69)
5012
6396
* gcry_ac_data_get_name: Working with sets of data.
5013
6397
(line 61)
6398
* gcry_ac_data_length: Working with sets of data.
6399
(line 57)
5014
6400
* gcry_ac_data_new: Working with sets of data.
5015
6401
(line 38)
5016
6402
* gcry_ac_data_set: Working with sets of data.
5037
6423
(line 28)
5038
6424
* gcry_ac_io_t: Working with IO objects.
5039
6425
(line 10)
5040
* gcry_ac_key_data_get: Working with keys. (line 92)
5041
* gcry_ac_key_destroy: Working with keys. (line 85)
5042
* gcry_ac_key_get_grip: Working with keys. (line 104)
5043
* gcry_ac_key_get_nbits: Working with keys. (line 100)
6426
* gcry_ac_key_data_get: Working with keys. (line 93)
6427
* gcry_ac_key_destroy: Working with keys. (line 86)
6428
* gcry_ac_key_get_grip: Working with keys. (line 105)
6429
* gcry_ac_key_get_nbits: Working with keys. (line 101)
5044
6430
* gcry_ac_key_init: Working with keys. (line 30)
5045
* gcry_ac_key_pair_destroy: Working with keys. (line 89)
5046
* gcry_ac_key_pair_extract: Working with keys. (line 82)
6431
* gcry_ac_key_pair_destroy: Working with keys. (line 90)
6432
* gcry_ac_key_pair_extract: Working with keys. (line 83)
5047
6433
* gcry_ac_key_pair_generate: Working with keys. (line 36)
5048
6434
* gcry_ac_key_pair_t: Working with keys. (line 20)
5049
6435
* gcry_ac_key_t: Working with keys. (line 16)
5050
* gcry_ac_key_test: Working with keys. (line 96)
6436
* gcry_ac_key_test: Working with keys. (line 97)
5051
6437
* gcry_ac_key_type_t: Working with keys. (line 7)
5052
6438
* gcry_ac_name_to_id: Handle-independent functions.
5053
6439
(line 15)
5054
6440
* gcry_ac_open: Working with handles.
5055
6441
(line 11)
6442
* gcry_calloc: Memory allocation. (line 15)
6443
* gcry_calloc_secure: Memory allocation. (line 21)
6444
* gcry_check_version: Initializing the library.
6445
(line 17)
5056
6446
* gcry_cipher_algo_info: General cipher functions.
5057
6447
(line 12)
6448
* gcry_cipher_algo_name: General cipher functions.
6449
(line 39)
5058
6450
* gcry_cipher_close: Working with cipher handles.
5059
6451
(line 59)
5060
6452
* gcry_cipher_ctl: Working with cipher handles.
5061
(line 161)
6453
(line 157)
5062
6454
* gcry_cipher_decrypt: Working with cipher handles.
5063
(line 131)
6455
(line 127)
5064
6456
* gcry_cipher_decrypt_t: Cipher modules. (line 80)
5065
6457
* gcry_cipher_encrypt: Working with cipher handles.
5066
(line 112)
6458
(line 108)
5067
6459
* gcry_cipher_encrypt_t: Cipher modules. (line 75)
5068
6460
* gcry_cipher_info: Working with cipher handles.
5069
(line 170)
6461
(line 166)
5070
6462
* gcry_cipher_list: Cipher modules. (line 106)
5071
6463
* gcry_cipher_map_name: General cipher functions.
5072
6464
(line 45)
5077
6469
(line 11)
5078
6470
* gcry_cipher_register: Cipher modules. (line 96)
5079
6471
* gcry_cipher_reset: Working with cipher handles.
5080
(line 99)
6472
(line 95)
5081
6473
* gcry_cipher_setctr: Working with cipher handles.
5082
(line 91)
6474
(line 88)
5083
6475
* gcry_cipher_setiv: Working with cipher handles.
5084
(line 83)
6476
(line 81)
5085
6477
* gcry_cipher_setkey: Working with cipher handles.
5086
6478
(line 66)
5087
6479
* gcry_cipher_setkey_t: Cipher modules. (line 70)
5089
6481
* gcry_cipher_stdecrypt_t: Cipher modules. (line 90)
5090
6482
* gcry_cipher_stencrypt_t: Cipher modules. (line 85)
5091
6483
* gcry_cipher_sync: Working with cipher handles.
5092
(line 151)
6484
(line 147)
5093
6485
* gcry_cipher_unregister: Cipher modules. (line 101)
5094
6486
* gcry_control: Controlling the library.
5095
6487
(line 7)
5096
6488
* gcry_create_nonce: Retrieving random numbers.
5097
(line 25)
6489
(line 26)
5098
6490
* gcry_err_code: Error Values. (line 43)
5099
6491
* gcry_err_code_from_errno: Error Values. (line 95)
5100
6492
* gcry_err_code_t: Error Values. (line 7)
5106
6498
* gcry_error: Error Values. (line 64)
5107
6499
* gcry_error_from_errno: Error Values. (line 86)
5108
6500
* gcry_error_t: Error Values. (line 25)
6501
* gcry_fips_mode_active: Controlling the library.
6502
(line 221)
5109
6503
* gcry_free: Memory allocation. (line 31)
5110
6504
* gcry_handler_alloc_t: Allocation handler. (line 12)
5111
* gcry_handler_error_t: Error handler. (line 20)
6505
* gcry_handler_error_t: Error handler. (line 27)
5112
6506
* gcry_handler_free_t: Allocation handler. (line 24)
5113
6507
* gcry_handler_log_t: Logging handler. (line 7)
5114
* gcry_handler_no_mem_t: Error handler. (line 10)
6508
* gcry_handler_no_mem_t: Error handler. (line 11)
5115
6509
* gcry_handler_progress_t: Progress handler. (line 10)
5116
6510
* gcry_handler_realloc_t: Allocation handler. (line 20)
5117
6511
* gcry_handler_secure_check_t: Allocation handler. (line 16)
6512
* gcry_malloc: Memory allocation. (line 7)
6513
* gcry_malloc_secure: Memory allocation. (line 12)
6514
* gcry_md_algo_name: Working with hash algorithms.
6515
(line 152)
5118
6516
* gcry_md_close: Working with hash algorithms.
5119
(line 59)
6517
(line 61)
5120
6518
* gcry_md_copy: Working with hash algorithms.
5121
(line 80)
6519
(line 82)
5122
6520
* gcry_md_debug: Working with hash algorithms.
5123
(line 214)
6521
(line 216)
5124
6522
* gcry_md_enable: Working with hash algorithms.
5125
(line 43)
6523
(line 44)
5126
6524
* gcry_md_final: Working with hash algorithms.
5127
(line 108)
6525
(line 110)
5128
6526
* gcry_md_final_t: Hash algorithm modules.
5129
6527
(line 73)
5130
6528
* gcry_md_get_algo: Working with hash algorithms.
5131
(line 194)
6529
(line 196)
6530
* gcry_md_get_algo_dlen: Working with hash algorithms.
6531
(line 187)
5132
6532
* gcry_md_get_asnoid: Working with hash algorithms.
5133
(line 166)
6533
(line 168)
5134
6534
* gcry_md_hash_buffer: Working with hash algorithms.
5135
(line 133)
6535
(line 135)
5136
6536
* gcry_md_init_t: Hash algorithm modules.
5137
6537
(line 65)
5138
6538
* gcry_md_is_enabled: Working with hash algorithms.
5139
(line 205)
6539
(line 207)
5140
6540
* gcry_md_is_secure: Working with hash algorithms.
5141
(line 200)
6541
(line 202)
5142
6542
* gcry_md_list: Hash algorithm modules.
5143
6543
(line 91)
5144
6544
* gcry_md_map_name: Working with hash algorithms.
5145
(line 156)
6545
(line 158)
5146
6546
* gcry_md_oid_spec_t: Hash algorithm modules.
5147
6547
(line 57)
5148
6548
* gcry_md_open: Working with hash algorithms.
5149
6549
(line 11)
5150
6550
* gcry_md_putc: Working with hash algorithms.
5151
(line 98)
6551
(line 100)
6552
* gcry_md_read: Working with hash algorithms.
6553
(line 120)
5152
6554
* gcry_md_read_t: Hash algorithm modules.
5153
6555
(line 77)
5154
6556
* gcry_md_register: Hash algorithm modules.
5155
6557
(line 82)
5156
6558
* gcry_md_reset: Working with hash algorithms.
5157
(line 68)
6559
(line 70)
5158
6560
* gcry_md_setkey: Working with hash algorithms.
5159
(line 52)
6561
(line 53)
5160
6562
* gcry_md_spec_t: Hash algorithm modules.
5161
6563
(line 12)
5162
6564
* gcry_md_start_debug: Working with hash algorithms.
5163
(line 228)
6565
(line 230)
5164
6566
* gcry_md_stop_debug: Working with hash algorithms.
5165
(line 236)
6567
(line 238)
5166
6568
* gcry_md_test_algo: Working with hash algorithms.
5167
(line 179)
6569
(line 181)
5168
6570
* gcry_md_unregister: Hash algorithm modules.
5169
6571
(line 87)
5170
6572
* gcry_md_write: Working with hash algorithms.
5171
(line 93)
6573
(line 95)
5172
6574
* gcry_md_write_t: Hash algorithm modules.
5173
6575
(line 69)
5174
6576
* gcry_module_t: Modules. (line 10)
5189
6591
* gcry_mpi_get_nbits: Bit manipulations. (line 10)
5190
6592
* gcry_mpi_get_opaque: Miscellaneous. (line 20)
5191
6593
* gcry_mpi_invm: Calculations. (line 68)
6594
* gcry_mpi_lshift: Bit manipulations. (line 34)
5192
6595
* gcry_mpi_mod: Calculations. (line 55)
5193
6596
* gcry_mpi_mul: Calculations. (line 34)
5194
6597
* gcry_mpi_mul_2exp: Calculations. (line 46)
5220
6623
(line 10)
5221
6624
* gcry_pk_check_secret_key_t: Public key modules. (line 91)
5222
6625
* gcry_pk_ctl: General public-key related Functions.
5223
(line 97)
6626
(line 100)
5224
6627
* gcry_pk_decrypt: Cryptographic Functions.
5225
6628
(line 85)
5226
6629
* gcry_pk_decrypt_t: Public key modules. (line 101)
5229
6632
* gcry_pk_encrypt_t: Public key modules. (line 96)
5230
6633
* gcry_pk_generate_t: Public key modules. (line 86)
5231
6634
* gcry_pk_genkey: General public-key related Functions.
5232
(line 112)
6635
(line 115)
5233
6636
* gcry_pk_get_keygrip: General public-key related Functions.
5234
6637
(line 29)
5235
6638
* gcry_pk_get_nbits: General public-key related Functions.
5253
6656
* gcry_pk_verify_t: Public key modules. (line 111)
5254
6657
* gcry_prime_check: Checking. (line 8)
5255
6658
* gcry_prime_generate: Generation. (line 10)
5256
* gcry_prime_release_factors: Generation. (line 26)
6659
* gcry_prime_group_generator: Generation. (line 19)
6660
* gcry_prime_release_factors: Generation. (line 25)
6661
* gcry_random_bytes: Retrieving random numbers.
6662
(line 13)
6663
* gcry_random_bytes_secure: Retrieving random numbers.
6664
(line 19)
6665
* gcry_random_level_t: Quality of random numbers.
6666
(line 9)
5257
6667
* gcry_randomize: Retrieving random numbers.
5258
6668
(line 8)
6669
* gcry_realloc: Memory allocation. (line 24)
5259
6670
* gcry_set_allocation_handler: Allocation handler. (line 34)
5260
* gcry_set_fatalerror_handler: Error handler. (line 25)
6671
* gcry_set_fatalerror_handler: Error handler. (line 32)
5261
6672
* gcry_set_log_handler: Logging handler. (line 12)
5262
* gcry_set_outofcore_handler: Error handler. (line 15)
6673
* gcry_set_outofcore_handler: Error handler. (line 16)
5263
6674
* gcry_set_progress_handler: Progress handler. (line 21)
5264
6675
* gcry_sexp_build: Working with S-expressions.
5265
6676
(line 43)
5285
6696
(line 159)
5286
6697
* gcry_sexp_nth_mpi: Working with S-expressions.
5287
6698
(line 184)
6699
* gcry_sexp_nth_string: Working with S-expressions.
6700
(line 176)
5288
6701
* gcry_sexp_release: Working with S-expressions.
5289
6702
(line 76)
5290
6703
* gcry_sexp_sprint: Working with S-expressions.
5295
6708
(line 7)
5296
6709
* gcry_strerror: Error Strings. (line 7)
5297
6710
* gcry_strsource: Error Strings. (line 13)
5298
* int <1>: Working with sets of data.
5299
(line 57)
5300
* int: Working with hash algorithms.
5301
(line 185)
5302
6711
5303
6712
5304
6713
5305
6714
Tag Table:
5306
Node: Top744
5307
Node: Introduction6460
5308
Node: Getting Started6832
5309
Node: Features7713
5310
Node: Overview8499
5311
Node: Preparation9130
5312
Node: Header9926
5313
Node: Building sources10924
5314
Node: Building sources using Automake12838
5315
Node: Initializing the library14020
5316
Node: Multi-Threading15309
5317
Ref: Multi-Threading-Footnote-119232
5318
Node: Generalities19640
5319
Node: Controlling the library19965
5320
Node: Modules25997
5321
Node: Error Handling26776
5322
Node: Error Values29299
5323
Node: Error Sources34239
5324
Node: Error Codes36510
5325
Node: Error Strings39472
5326
Node: Handler Functions40624
5327
Node: Progress handler41183
5328
Node: Allocation handler43130
5329
Node: Error handler44425
5330
Node: Logging handler45482
5331
Node: Symmetric cryptography45988
5332
Node: Available ciphers46777
5333
Node: Cipher modules49284
5334
Node: Available cipher modes53808
5335
Node: Working with cipher handles54488
5336
Node: General cipher functions62866
5337
Node: Hashing65383
5338
Node: Available hash algorithms66189
5339
Node: Hash algorithm modules68426
5340
Node: Working with hash algorithms72274
5341
Node: Public Key cryptography (I)83324
5342
Node: Available algorithms84177
5343
Node: Used S-expressions84530
5344
Node: RSA key parameters85615
5345
Node: DSA key parameters86890
5346
Node: ECC key parameters87548
5347
Node: Public key modules89313
5348
Node: Cryptographic Functions94901
5349
Node: General public-key related Functions102394
5350
Node: Public Key cryptography (II)110799
5351
Node: Available asymmetric algorithms111929
5352
Node: Working with sets of data112610
5353
Node: Working with IO objects117124
5354
Node: Working with handles119856
5355
Node: Working with keys120815
5356
Node: Using cryptographic functions124864
5357
Node: Handle-independent functions131783
5358
Node: Random Numbers132543
5359
Node: Quality of random numbers132838
5360
Node: Retrieving random numbers133494
5361
Node: S-expressions134925
5362
Node: Data types for S-expressions135569
5363
Node: Working with S-expressions135895
5364
Node: MPI library144829
5365
Node: Data types146141
5366
Node: Basic functions146347
5367
Node: MPI formats148415
5368
Node: Calculations151298
5369
Node: Comparisons153552
5370
Node: Bit manipulations154170
5371
Node: Miscellaneous155314
5372
Node: Prime numbers157158
5373
Node: Generation157428
5374
Node: Checking158695
5375
Node: Utilities159108
5376
Node: Memory allocation159304
5377
Node: Library Copying160560
5378
Node: Copying188724
5379
Node: Concept Index207927
5380
Node: Function and Data Index208882
6715
Node: Top773
6716
Node: Introduction2990
6717
Node: Getting Started3362
6718
Node: Features4243
6719
Node: Overview5027
6720
Node: Preparation5658
6721
Node: Header6515
6722
Node: Building sources7585
6723
Node: Building sources using Automake9499
6724
Node: Initializing the library10681
6725
Ref: sample-use-suspend-secmem13856
6726
Ref: sample-use-resume-secmem14476
6727
Node: Multi-Threading15372
6728
Ref: Multi-Threading-Footnote-119385
6729
Node: Enabling FIPS mode19793
6730
Node: Generalities21659
6731
Node: Controlling the library21984
6732
Node: Modules34151
6733
Node: Error Handling34930
6734
Node: Error Values37453
6735
Node: Error Sources42393
6736
Node: Error Codes44664
6737
Node: Error Strings48149
6738
Node: Handler Functions49332
6739
Node: Progress handler49891
6740
Node: Allocation handler51887
6741
Node: Error handler53438
6742
Node: Logging handler55005
6743
Node: Symmetric cryptography55597
6744
Node: Available ciphers56402
6745
Node: Cipher modules58909
6746
Node: Available cipher modes63433
6747
Node: Working with cipher handles64312
6748
Node: General cipher functions72515
6749
Node: Public Key cryptography75033
6750
Node: Available algorithms75948
6751
Node: Used S-expressions76297
6752
Node: RSA key parameters77409
6753
Node: DSA key parameters78684
6754
Node: ECC key parameters79342
6755
Node: Public key modules81107
6756
Node: Cryptographic Functions86691
6757
Node: General public-key related Functions94178
6758
Node: AC Interface106467
6759
Node: Available asymmetric algorithms107602
6760
Node: Working with sets of data108271
6761
Node: Working with IO objects112773
6762
Node: Working with handles115493
6763
Node: Working with keys116440
6764
Node: Using cryptographic functions120522
6765
Node: Handle-independent functions127429
6766
Node: Hashing128177
6767
Node: Available hash algorithms128968
6768
Node: Hash algorithm modules131205
6769
Node: Working with hash algorithms135053
6770
Node: Random Numbers146257
6771
Node: Quality of random numbers146531
6772
Node: Retrieving random numbers147215
6773
Node: S-expressions148699
6774
Node: Data types for S-expressions149341
6775
Node: Working with S-expressions149665
6776
Node: MPI library158598
6777
Node: Data types159556
6778
Node: Basic functions159750
6779
Node: MPI formats161818
6780
Node: Calculations164701
6781
Node: Comparisons166955
6782
Node: Bit manipulations167599
6783
Node: Miscellaneous168914
6784
Node: Prime numbers170883
6785
Node: Generation171153
6786
Node: Checking172437
6787
Node: Utilities172850
6788
Node: Memory allocation173043
6789
Node: Architecture174304
6790
Ref: fig:subsystems175824
6791
Ref: Architecture-Footnote-1176909
6792
Ref: Architecture-Footnote-2176971
6793
Node: Public-Key Subsystem Architecture177055
6794
Node: Symmetric Encryption Subsystem Architecture179996
6795
Node: Hashing and MACing Subsystem Architecture181443
6796
Node: Multi-Precision-Integer Subsystem Architecture183367
6797
Node: Prime-Number-Generator Subsystem Architecture184808
6798
Ref: Prime-Number-Generator Subsystem Architecture-Footnote-1186739
6799
Node: Random-Number Subsystem Architecture187026
6800
Node: CSPRNG Description189515
6801
Ref: CSPRNG Description-Footnote-1191077
6802
Node: FIPS PRNG Description191200
6803
Node: Self-Tests193335
6804
Node: FIPS Mode205019
6805
Ref: fig:fips-fsm208999
6806
Ref: tbl:fips-states209101
6807
Ref: tbl:fips-state-transitions210354
6808
Node: Library Copying213968
6809
Node: Copying242086
6810
Node: Figures and Tables261260
6811
Node: Concept Index261670
6812
Node: Function and Data Index267235
5381
6813
5382
6814
End Tag Table
Loggerhead is a web-based interface for Breezy
Version: 2.0.1