« back to all changes in this revision
Viewing changes to doc/gcrypt.texi
- browse files at revision 1.2.3
- compare with another revision
- download diff
- download tarball
- view history from revision 1.2.3
- Committer: Bazaar Package Importer
- Author(s): Andreas Metzler
- Date: 2009-02-21 13:46:58 UTC
- mto: (1.1.6 upstream) (2.1.3 squeeze)
- mto: This revision was merged to the branch mainline in revision 18.
- Revision ID: james.westby@ubuntu.com-20090221134658-855twvcr4ezk2ron
Import upstream version 1.4.4
- files added:
- cipher/hash-common.c
- random
- files removed:
- BUGS
- files modified:
- AUTHORS
added
removed
doc/gcrypt.texi
12
12
(version @value{VERSION}, @value{UPDATED}),
13
13
which is GNU's library of cryptographic building blocks.
14
14
15
Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007 Free Software Foundation, Inc.
15
Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008 Free Software Foundation, Inc.
16
16
17
17
@quotation
18
18
Permission is granted to copy, distribute and/or modify this document
19
19
under the terms of the GNU General Public License as published by the
20
20
Free Software Foundation; either version 2 of the License, or (at your
21
21
option) any later version. The text of the license can be found in the
22
section entitled ``Copying''.
22
section entitled ``GNU General Public License''.
23
23
@end quotation
24
24
@end copying
25
25
66
66
* Generalities:: General library functions and data types.
67
67
* Handler Functions:: Working with handler functions.
68
68
* Symmetric cryptography:: How to use symmetric cryptography.
69
* Hashing:: How to use hashing.
70
* Public Key cryptography (I):: How to use public key cryptography.
71
* Public Key cryptography (II):: How to use public key cryptography, alternatively.
69
* Public Key cryptography:: How to use public key cryptography.
70
* Hashing:: How to use hash and MAC algorithms.
72
71
* Random Numbers:: How to work with random numbers.
73
72
* S-expressions:: How to manage S-expressions.
74
73
* MPI library:: How to work with multi-precision-integers.
75
74
* Prime numbers:: How to use the Prime number related functions.
76
75
* Utilities:: Utility functions.
76
* Architecture:: How Libgcrypt works internally.
77
77
78
78
Appendices
79
79
80
* Self-Tests:: Description of the self-tests.
81
* FIPS Mode:: Description of the FIPS mode.
80
82
* Library Copying:: The GNU Lesser General Public License
81
83
says how you can copy and share Libgcrypt.
82
84
* Copying:: The GNU General Public License says how you
84
86
85
87
Indices
86
88
89
* Figures and Tables:: Index of figures and tables.
87
90
* Concept Index:: Index of concepts and programs.
88
91
* Function and Data Index:: Index of functions, variables and data types.
89
92
90
@detailmenu
91
--- The Detailed Node Listing ---
92
93
Introduction
94
* Getting Started:: How to use this manual.
95
* Features:: A glance at Libgcrypt's features.
96
* Overview:: Overview about the library.
97
98
Preparation
99
* Header:: What header file you need to include.
100
* Building sources:: How to build sources using the library.
101
* Building sources using Automake:: How to build sources with the help of Automake.
102
* Initializing the library:: How to initialize the library.
103
* Multi-Threading:: How Libgcrypt can be used in a MT environment.
104
105
Generalities
106
* Controlling the library:: Controlling Libgcrypt's behavior.
107
* Modules:: Description of extension modules.
108
* Error Handling:: Error codes and such.
109
110
Handler Functions
111
* Progress handler:: Using a progress handler function.
112
* Allocation handler:: Using special memory allocation functions.
113
* Error handler:: Using error handler functions.
114
* Logging handler:: Using a special logging function.
115
116
Symmetric cryptography
117
* Available ciphers:: List of ciphers supported by the library.
118
* Cipher modules:: How to work with cipher modules.
119
* Available cipher modes:: List of cipher modes supported by the library.
120
* Working with cipher handles:: How to perform operations related to cipher handles.
121
* General cipher functions:: General cipher functions independent of cipher handles.
122
123
Hashing
124
* Available hash algorithms:: List of hash algorithms supported by the library.
125
* Hash algorithm modules:: How to work with hash algorithm modules.
126
* Working with hash algorithms:: List of functions related to hashing.
127
128
Public Key cryptography (I)
129
* Used S-expressions:: Introduction into the used S-expression.
130
* Available algorithms:: Algorithms supported by the library.
131
* Public key modules:: How to work with public key modules.
132
* Cryptographic Functions:: Functions for performing the cryptographic actions.
133
* General public-key related Functions:: General functions, not implementing any cryptography.
134
135
Public Key cryptography (II)
136
* Available asymmetric algorithms:: List of algorithms supported by the library.
137
* Working with sets of data:: How to work with sets of data.
138
* Working with handles:: How to use handles.
139
* Working with keys:: How to work with keys.
140
* Using cryptographic functions:: How to perform cryptographic operations.
141
* Handle-independent functions:: General functions independent of handles.
142
143
Random Numbers
144
* Quality of random numbers:: Libgcrypt uses different quality levels.
145
* Retrieving random numbers:: How to retrieve random numbers.
146
147
S-expressions
148
* Data types for S-expressions:: Data types related with S-expressions.
149
* Working with S-expressions:: How to work with S-expressions.
150
151
MPI library
152
* Data types:: MPI related data types.
153
* Basic functions:: First steps with MPI numbers.
154
* MPI formats:: External representation of MPIs.
155
* Calculations:: Performing MPI calculations.
156
* Comparisons:: How to compare MPI values.
157
* Bit manipulations:: How to access single bits of MPI values.
158
* Miscellaneous:: Miscellaneous MPI functions.
159
160
Prime numbers
161
* Generation:: Generation of new prime numbers.
162
* Checking:: Checking if a given number is prime.
163
164
Utilities
165
* Memory allocation:: Functions related with memory allocation.
166
167
@end detailmenu
168
169
170
93
@end menu
171
94
172
95
@ifhtml
181
104
@c **********************************************************
182
105
@node Introduction
183
106
@chapter Introduction
107
184
108
Libgcrypt is a library providing cryptographic building blocks.
185
109
186
110
@menu
220
144
@item It's Free Software
221
145
Anybody can use, modify, and redistribute it under the terms of the GNU
222
146
Lesser General Public License (@pxref{Library Copying}). Note, that
223
some parts (which are not needed on a GNU or GNU/Linux system) are
224
subject to the terms of the GNU General Public License
225
(@pxref{Copying}); please see the README file of the distribution for of
226
list of these parts.
147
some parts (which are in general not needed by applications) are subject
148
to the terms of the GNU General Public License (@pxref{Copying}); please
149
see the README file of the distribution for of list of these parts.
227
150
228
151
@item It encapsulates the low level cryptography
229
152
Libgcrypt provides a high level interface to cryptographic
264
187
* Building sources using Automake:: How to build sources with the help of Automake.
265
188
* Initializing the library:: How to initialize the library.
266
189
* Multi-Threading:: How Libgcrypt can be used in a MT environment.
190
* Enabling FIPS mode:: How to enable the FIPS mode.
267
191
@end menu
268
192
269
193
295
219
Do not define the shorthand macros @code{mpi_*} for @code{gcry_mpi_*}.
296
220
297
221
@item GCRYPT_NO_DEPRECATED
298
Do not include defintions for deprecated features.
222
Do not include defintions for deprecated features. This is useful to
223
make sure that no deprecated features are used.
299
224
@end table
300
225
301
302
226
@node Building sources
303
227
@section Building sources
304
228
392
316
be used. So you may want to check that the version is okay right
393
317
after program startup.
394
318
395
@deftypefun const char *gcry_check_version (const char *@var{req_version})
319
@deftypefun {const char *} gcry_check_version (const char *@var{req_version})
396
320
397
The function @code{gcry_check_version} initializes the sub-systems
398
used by Libgcrypt and must be invoked before any other function in the
399
library, with the exception of the @code{GCRYCTL_SET_THREAD_CBS}
400
command (called via the @code{gcry_control} function), see
321
The function @code{gcry_check_version} initializes some subsystems used
322
by Libgcrypt and must be invoked before any other function in the
323
library, with the exception of the @code{GCRYCTL_SET_THREAD_CBS} command
324
(called via the @code{gcry_control} function).
401
325
@xref{Multi-Threading}.
402
326
403
327
Furthermore, this function returns the version number of the library.
406
330
pointer.
407
331
@end deftypefun
408
332
333
Libgcrypt uses a concept known as secure memory, which is a region of
334
memory set aside for storing sensitive data. Because such memory is a
335
scarce resource, it needs to be setup in advanced to a fixed size.
336
Further, most operating systems have special requirements on how that
337
secure memory can be used. For example, it might be required to install
338
an application as ``setuid(root)'' to allow allocating such memory.
339
Libgcrypt requires a sequence of initialization steps to make sure that
340
this works correctly. The following examples show the necessary steps.
341
342
If you don't have a need for secure memory, for example if your
343
application does not use secret keys or other confidential data or it
344
runs in a controlled environment where key material floating around in
345
memory is not a problem, you should initialize Libgcrypt this way:
346
347
@example
348
/* Version check should be the very first call because it
349
makes sure that important subsystems are intialized. */
350
if (!gcry_check_version (GCRYPT_VERSION))
351
@{
352
fputs ("libgcrypt version mismatch\n", stderr);
353
exit (2);
354
@}
355
356
/* Disable secure memory. */
357
gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
358
359
/* ... If required, other initialization goes here. */
360
361
/* Tell Libgcrypt that initialization has completed. */
362
gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
363
@end example
364
365
366
If you have to protect your keys or other information in memory against
367
being swapped out to disk and to enable an automatic overwrite of used
368
and freed memory, you need to initialize Libgcrypt this way:
369
370
@example
371
/* Version check should be the very first call because it
372
makes sure that important subsystems are intialized. */
373
if (!gcry_check_version (GCRYPT_VERSION))
374
@{
375
fputs ("libgcrypt version mismatch\n", stderr);
376
exit (2);
377
@}
378
379
@anchor{sample-use-suspend-secmem}
380
/* We don't want to see any warnings, e.g. because we have not yet
381
parsed program options which might be used to suppress such
382
warnings. */
383
gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
384
385
/* ... If required, other initialization goes here. Note that the
386
process might still be running with increased privileges and that
387
the secure memory has not been intialized. */
388
389
/* Allocate a pool of 16k secure memory. This make the secure memory
390
available and also drops privileges where needed. */
391
gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
392
393
@anchor{sample-use-resume-secmem}
394
/* It is now okay to let Libgcrypt complain when there was/is
395
a problem with the secure memory. */
396
gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
397
398
/* ... If required, other initialization goes here. */
399
400
/* Tell Libgcrypt that initialization has completed. */
401
gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
402
@end example
403
404
It is important that these initialization steps are not done by a
405
library but by the actual application. A library using Libgcrypt might
406
want to check for finished initialization using:
407
408
@example
409
if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
410
@{
411
fputs ("libgcrypt has not been initialized\n", stderr);
412
abort ();
413
@}
414
@end example
415
416
Instead of terminating the process, the library may instead print a
417
warning and try to initialize Libgcrypt itself. See also the section on
418
multi-threading below for more pitfalls.
419
420
409
421
410
422
@node Multi-Threading
411
423
@section Multi-Threading
463
475
strict rules may apply.}.
464
476
465
477
@item
466
467
478
Just like the function @code{gpg_strerror}, the function
468
479
@code{gcry_strerror} is not thread safe. You have to use
469
480
@code{gpg_strerror_r} instead.
481
470
482
@end itemize
471
483
472
484
476
488
@table @code
477
489
@item GCRY_THREAD_OPTION_PTH_IMPL
478
490
479
This macro defines the following (static) symbols: gcry_pth_init,
480
gcry_pth_mutex_init, gcry_pth_mutex_destroy, gcry_pth_mutex_lock,
481
gcry_pth_mutex_unlock, gcry_pth_read, gcry_pth_write, gcry_pth_select,
482
gcry_pth_waitpid, gcry_pth_accept, gcry_pth_connect, gcry_threads_pth.
491
This macro defines the following (static) symbols:
492
@code{gcry_pth_init}, @code{gcry_pth_mutex_init},
493
@code{gcry_pth_mutex_destroy}, @code{gcry_pth_mutex_lock},
494
@code{gcry_pth_mutex_unlock}, @code{gcry_pth_read},
495
@code{gcry_pth_write}, @code{gcry_pth_select},
496
@code{gcry_pth_waitpid}, @code{gcry_pth_accept},
497
@code{gcry_pth_connect}, @code{gcry_threads_pth}.
483
498
484
After including this macro, gcry_control() shall be used with a
485
command of GCRYCTL_SET_THREAD_CBS in order to register the thread
486
callback structure named ``gcry_threads_pth''.
499
After including this macro, @code{gcry_control()} shall be used with a
500
command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the
501
thread callback structure named ``gcry_threads_pth''.
487
502
488
503
@item GCRY_THREAD_OPTION_PTHREAD_IMPL
489
504
490
505
This macro defines the following (static) symbols:
491
gcry_pthread_mutex_init, gcry_pthread_mutex_destroy, gcry_mutex_lock,
492
gcry_mutex_unlock, gcry_threads_pthread.
506
@code{gcry_pthread_mutex_init}, @code{gcry_pthread_mutex_destroy},
507
@code{gcry_pthread_mutex_lock}, @code{gcry_pthread_mutex_unlock},
508
@code{gcry_threads_pthread}.
493
509
494
After including this macro, gcry_control() shall be used with a
495
command of GCRYCTL_SET_THREAD_CBS in order to register the thread
496
callback structure named ``gcry_threads_pthread''.
510
After including this macro, @code{gcry_control()} shall be used with a
511
command of @code{GCRYCTL_SET_THREAD_CBS} in order to register the
512
thread callback structure named ``gcry_threads_pthread''.
497
513
@end table
498
514
499
515
Note that these macros need to be terminated with a semicolon. Keep
500
516
in mind that these are convenient macros for C programmers; C++
501
517
programmers might have to wrap these macros in an ``extern C'' body.
502
518
519
520
@node Enabling FIPS mode
521
@section How to enable the FIPS mode
522
@cindex FIPS mode
523
@cindex FIPS 140
524
525
Libgcrypt may be used in a FIPS 140-2 mode. Note, that this does not
526
necessary mean that Libcgrypt is an appoved FIPS 140-2 module. Check the
527
NIST database at @url{http://csrc.nist.gov/groups/STM/cmvp/} to see what
528
versions of Libgcrypt are approved.
529
530
Because FIPS 140 has certain restrictions on the use of cryptography
531
which are not always wanted, Libgcrypt needs to be put into FIPS mode
532
explicitly. Three alternative mechanisms are provided to switch
533
Libgcrypt into this mode:
534
535
@itemize
536
@item
537
If the file @file{/proc/sys/crypto/fips_enabled} exists and contains a
538
numeric value other than @code{0}, Libgcrypt is put into FIPS mode at
539
initialization time. Obviously this works only on systems with a
540
@code{proc} file system (i.e. GNU/Linux).
541
542
@item
543
If the file @file{/etc/gcrypt/fips_enabled} exists, Libgcrypt is put
544
into FIPS mode at initialization time. Note that this filename is
545
hardwired and does not depend on any configuration options.
546
547
@item
548
If the application requests FIPS mode using the control command
549
@code{GCRYCTL_FORCE_FIPS_MODE}. This must be done prior to any
550
initialization (i.e. before @code{gcry_check_version}).
551
552
@end itemize
553
554
@cindex Enforced FIPS mode
555
556
In addition to the standard FIPS mode, Libgcrypt may also be put into
557
an Enforced FIPS mode by writing a non-zero value into the file
558
@file{/etc/gcrypt/fips_enabled}. The Enforced FIPS mode helps to
559
detect applications which don't fulfill all requirements for using
560
Libgcrypt in FIPS mode (@pxref{FIPS Mode}).
561
562
Once Libgcrypt has been put into FIPS mode, it is not possible to
563
switch back to standard mode without terminating the process first.
564
If the logging verbosity level of Libgcrypt has been set to at least
565
2, the state transitions and the self-tests are logged.
566
567
568
503
569
@c **********************************************************
504
570
@c ******************* General ****************************
505
571
@c **********************************************************
541
607
This option can only be used at initialization time.
542
608
543
609
544
@item GCRYCTL_DUMP_RANDOM_STATS
545
This command dumps PRNG related statistics to the librarys logging
546
stream.
610
@item GCRYCTL_DUMP_RANDOM_STATS; Arguments: none
611
This command dumps randum number generator related statistics to the
612
library's logging stream.
547
613
548
@item GCRYCTL_DUMP_MEMORY_STATS
549
This command dumps memory manamgent related statistics to the librarys
614
@item GCRYCTL_DUMP_MEMORY_STATS; Arguments: none
615
This command dumps memory managment related statistics to the library's
550
616
logging stream.
551
617
552
@item GCRYCTL_DUMP_SECMEM_STATS
618
@item GCRYCTL_DUMP_SECMEM_STATS; Arguments: none
553
619
This command dumps secure memory manamgent related statistics to the
554
librarys logging stream.
555
556
@item GCRYCTL_DUMP_CONFIG; Arguments: none
557
This command dumps information pertaining to the configuration of
558
libgcrypt to the logging stream. It may be used before the
559
intialization has been finished but not before a gcry_version_check.
560
561
@item GCRYCTL_DROP_PRIVS
620
library's logging stream.
621
622
@item GCRYCTL_DROP_PRIVS; Arguments: none
562
623
This command disables the use of secure memory and drops the priviliges
563
of the current process. FIXME.
624
of the current process. This command has not much use; the suggested way
625
to disable secure memory is to use @code{GCRYCTL_DISABLE_SECMEM} right
626
after initialization.
564
627
565
@item GCRYCTL_DISABLE_SECMEM
566
This command disables the use of secure memory.
628
@item GCRYCTL_DISABLE_SECMEM; Arguments: none
629
This command disables the use of secure memory. If this command is
630
used in FIPS mode, FIPS mode will be disabled and the function
631
@code{gcry_fips_mode_active} returns false. However, in Enforced FIPS
632
mode this command has no effect at all.
567
633
568
634
Many applications do not require secure memory, so they should disable
569
it right away. There won't be a problem if not disabling it unless one
570
makes use of a feature which requires secure memory - in that case the
571
process will abort because the secmem is not initialized.
572
573
574
@item GCRYCTL_INIT_SECMEM
575
@item GCRYCTL_TERM_SECMEM
576
@item GCRYCTL_DISABLE_SECMEM_WARN
577
@item GCRYCTL_SUSPEND_SECMEM_WARN
578
@item GCRYCTL_RESUME_SECMEM_WARN
635
it right away. This command should be executed right after
636
@code{gcry_check_version}.
637
638
@item GCRYCTL_INIT_SECMEM; Arguments: int nbytes
639
This command is used to allocate a pool of secure memory and thus
640
enabling the use of secure memory. It also drops all extra privileges
641
the process has (i.e. if it is run as setuid (root)). If the argument
642
@var{nbytes} is 0, secure memory will be disabled. The minimum amount
643
of secure memory allocated is currently 16384 bytes; you may thus use a
644
value of 1 to request that default size.
645
646
@item GCRYCTL_TERM_SECMEM; Arguments: none
647
This command zeroises the secure memory and destroys the handler. The
648
secure memory pool may not be used anymore after running this command.
649
If the secure memory pool as already been destroyed, this command has
650
no effect. Applications might want to run this command from their
651
exit handler to make sure that the secure memory gets properly
652
destroyed. This command is not necessarily thread-safe but that
653
should not be needed in cleanup code. It may be called from a signal
654
handler.
655
656
@item GCRYCTL_DISABLE_SECMEM_WARN; Arguments: none
657
Disable warning messages about problems with the secure memory
658
subsystem. This command should be run right after
659
@code{gcry_check_version}.
660
661
@item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none
662
Postpone warning messages from the secure memory subsystem.
663
@xref{sample-use-suspend-secmem,,the initialization example}, on how to
664
use it.
665
666
@item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none
667
Resume warning messages from the secure memory subsystem.
668
@xref{sample-use-resume-secmem,,the initialization example}, on how to
669
use it.
579
670
580
671
@item GCRYCTL_USE_SECURE_RNDPOOL; Arguments: none
581
582
672
This command tells the PRNG to store random numbers in secure memory.
583
FIXME: what about initialization time?
673
This command should be run right after @code{gcry_check_version} and not
674
later than the command GCRYCTL_INIT_SECMEM. Note that in FIPS mode the
675
secure memory is always used.
584
676
585
677
@item GCRYCTL_SET_RANDOM_SEED_FILE; Arguments: const char *filename
586
587
678
This command specifies the file, which is to be used as seed file for
588
679
the PRNG. If the seed file is registered prior to initialization of the
589
680
PRNG, the seed file's content (if it exists and seems to be valid) is
593
684
594
685
595
686
@item GCRYCTL_UPDATE_RANDOM_SEED_FILE; Arguments: none
596
597
687
Write out the PRNG pool's content into the registered seed file.
598
688
599
689
Multiple instances of the applications sharing the same random seed file
611
701
requested as in this case enough extra entropy gets mixed. It is also
612
702
not an issue when using Linux (rndlinux driver), because this one
613
703
guarantees to read full 16 bytes from /dev/urandom and thus there is no
614
way for an attacker without kernel access to conrol these 16 bytes.
615
616
@item GCRYCTL_SET_VERBOSITY
617
618
619
@item GCRYCTL_SET_DEBUG_FLAGS
620
@item GCRYCTL_CLEAR_DEBUG_FLAGS
621
@item GCRYCTL_DISABLE_INTERNAL_LOCKING
622
@item GCRYCTL_ANY_INITIALIZATION_P
623
@item GCRYCTL_INITIALIZATION_FINISHED_P
624
@item GCRYCTL_INITIALIZATION_FINISHED
704
way for an attacker without kernel access to control these 16 bytes.
705
706
@item GCRYCTL_SET_VERBOSITY; Arguments: int level
707
This command sets the verbosity of the logging. A level of 0 disables
708
all extra logging whereas positive numbers enable more verbose logging.
709
The level may be changed at any time but be aware that no memory
710
synchronization is done so the effect of this command might not
711
immediately show up in other threads. This command may even be used
712
prior to @code{gcry_check_version}.
713
714
@item GCRYCTL_SET_DEBUG_FLAGS; Arguments: unsigned int flags
715
Set the debug flag bits as given by the argument. Be aware that that no
716
memory synchronization is done so the effect of this command might not
717
immediately show up in other threads. The debug flags are not
718
considered part of the API and thus may change without notice. As of
719
now bit 0 enables debugging of cipher functions and bit 1 debugging of
720
multi-precision-integers. This command may even be used prior to
721
@code{gcry_check_version}.
722
723
@item GCRYCTL_CLEAR_DEBUG_FLAGS; Arguments: unsigned int flags
724
Set the debug flag bits as given by the argument. Be aware that that no
725
memory synchronization is done so the effect of this command might not
726
immediately show up in other threads. This command may even be used
727
prior to @code{gcry_check_version}.
728
729
@item GCRYCTL_DISABLE_INTERNAL_LOCKING; Arguments: none
730
This command does nothing. It exists only for backward compatibility.
731
732
@item GCRYCTL_ANY_INITIALIZATION_P; Arguments: none
733
This command returns true if the library has been basically initialized.
734
Such a basic initialization happens implicitly with many commands to get
735
certain internal subsystems running. The common and suggested way to
736
do this basic intialization is by calling gcry_check_version.
737
738
@item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none
739
This command tells the libray that the application has finished the
740
intialization.
741
742
@item GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none
743
This command returns true if the command@*
744
GCRYCTL_INITIALIZATION_FINISHED has already been run.
625
745
626
746
@item GCRYCTL_SET_THREAD_CBS; Arguments: struct ath_ops *ath_ops
627
628
This command registers a thread-callback structure. See section ``multi
629
threading'' for more information on this command.
630
631
@item GCRYCTL_FAST_POLL
632
747
This command registers a thread-callback structure.
748
@xref{Multi-Threading}.
749
750
@item GCRYCTL_FAST_POLL; Arguments: none
633
751
Run a fast random poll.
634
752
635
636
753
@item GCRYCTL_SET_RNDEGD_SOCKET; Arguments: const char *filename
637
638
754
This command may be used to override the default name of the EGD socket
639
755
to connect to. It may be used only during initialization as it is not
640
756
thread safe. Changing the socket name again is not supported. The
641
757
function may return an error if the given filename is too long for a
642
758
local socket name.
643
759
644
EGD is an alternative random gatherer, used only on a few systems.
645
760
EGD is an alternative random gatherer, used only on systems lacking a
761
proper random device.
762
763
@item GCRYCTL_PRINT_CONFIG; Arguments: FILE *stream
764
This command dumps information pertaining to the configuration of the
765
library to the given stream. If NULL is given for @var{stream}, the log
766
system is used. This command may be used before the intialization has
767
been finished but not before a gcry_version_check.
768
769
@item GCRYCTL_OPERATIONAL_P; Arguments: none
770
This command returns true if the library is in an operational state.
771
This information makes only sense in FIPS mode. In contrast to other
772
functions, this is a pure test function and won't put the library into
773
FIPS mode or change the internal state. This command may be used before
774
the intialization has been finished but not before a gcry_version_check.
775
776
@item GCRYCTL_FIPS_MODE_P; Arguments: none
777
This command returns true if the library is in FIPS mode. Note, that
778
this is no indication about the current state of the library. This
779
command may be used before the intialization has been finished but not
780
before a gcry_version_check. An application may use this command or
781
the convenience macro below to check whether FIPS mode is actually
782
active.
783
784
@deftypefun int gcry_fips_mode_active (void)
785
786
Returns true if the FIPS mode is active. Note that this is
787
implemented as a macro.
788
@end deftypefun
789
790
791
792
@item GCRYCTL_FORCE_FIPS_MODE; Arguments: none
793
Running this command puts the library into FIPS mode. If the library is
794
already in FIPS mode, a self-test is triggered and thus the library will
795
be put into operational state. This command may be used before a call
796
to gcry_check_version and that is actually the recommended way to let an
797
application switch the library into FIPS mode. Note that Libgcrypt will
798
reject an attempt to switch to fips mode during or after the intialization.
799
800
@item GCRYCTL_SELFTEST; Arguments: none
801
This may be used at anytime to have the library run all implemented
802
self-tests. It works in standard and in FIPS mode. Returns 0 on
803
success or an error code on failure.
646
804
647
805
648
806
@end table
855
1013
course @code{GPG_ERR_SOURCE_UNKNOWN}.
856
1014
857
1015
The list of error sources that might occur in applications using
858
@acronym{Libgctypt} is:
1016
@acronym{Libgcrypt} is:
859
1017
860
1018
@table @code
861
1019
@item GPG_ERR_SOURCE_UNKNOWN
980
1138
This value means a verification failed because the public key is not
981
1139
available.
982
1140
1141
@item GPG_ERR_NOT_OPERATIONAL
1142
This value means that the library is not yet in state which allows to
1143
use this function. This error code is in particular returned if
1144
Libgcrypt is operated in FIPS mode and the internal state of the
1145
library does not yet or not anymore allow the use of a service.
1146
1147
This error code is only available with newer libgpg-error versions, thus
1148
you might see ``invalid error code'' when passing this to
1149
@code{gpg_strerror}. The numeric value of this error code is 176.
1150
983
1151
@item GPG_ERR_USER_1
984
1152
@item GPG_ERR_USER_2
985
1153
@item ...
1022
1190
gcry_cipher_hd_t handle;
1023
1191
gcry_error_t err = 0;
1024
1192
1025
err = gcry_cipher_open (&handle, GCRY_CIPHER_AES, GCRY_CIPHER_MODE_CBC, 0);
1193
err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
1194
GCRY_CIPHER_MODE_CBC, 0);
1026
1195
if (err)
1027
1196
@{
1028
1197
fprintf (stderr, "Failure: %s/%s\n",
1039
1208
@chapter Handler Functions
1040
1209
1041
1210
Libgcrypt makes it possible to install so called `handler functions',
1042
which get called by Libgcrypt in case of certain events.
1211
which get called by Libgcrypt in case of certain events.
1043
1212
1044
1213
@menu
1045
1214
* Progress handler:: Using a progress handler function.
1067
1236
@deftypefun void gcry_set_progress_handler (gcry_handler_progress_t @var{cb}, void *@var{cb_data})
1068
1237
1069
1238
This function installs @var{cb} as the `Progress handler' function.
1070
@var{cb} must be defined as follows:
1239
It may be used only during initialization. @var{cb} must be defined
1240
as follows:
1071
1241
1072
1242
@example
1073
1243
void
1141
1311
1142
1312
@deftypefun void gcry_set_allocation_handler (gcry_handler_alloc_t @var{func_alloc}, gcry_handler_alloc_t @var{func_alloc_secure}, gcry_handler_secure_check_t @var{func_secure_check}, gcry_handler_realloc_t @var{func_realloc}, gcry_handler_free_t @var{func_free})
1143
1313
Install the provided functions and use them instead of the built-in
1144
functions for doing memory allocation.
1314
functions for doing memory allocation. Using this function is in
1315
general not recommended because the standard Libgcrypt allocation
1316
functions are guaranteed to zeroize memory if needed.
1317
1318
This function may be used only during initialization and may not be
1319
used in fips mode.
1320
1321
1145
1322
@end deftypefun
1146
1323
1147
1324
@node Error handler
1148
1325
@section Error handler
1149
1326
1150
1327
The following functions may be used to register handler functions that
1151
are called by Libgcrypt in case certain error conditions
1152
occur.
1328
are called by Libgcrypt in case certain error conditions occur. They
1329
may and should be registered prior to calling @code{gcry_check_version}.
1153
1330
1154
1331
@deftp {Data type} gcry_handler_no_mem_t
1155
This type is defined as: @code{void (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
1332
This type is defined as: @code{int (*gcry_handler_no_mem_t) (void *, size_t, unsigned int)}
1156
1333
@end deftp
1157
1334
@deftypefun void gcry_set_outofcore_handler (gcry_handler_no_mem_t @var{func_no_mem}, void *@var{cb_data})
1158
1335
This function registers @var{func_no_mem} as `out-of-core handler',
1159
1336
which means that it will be called in the case of not having enough
1160
memory available.
1337
memory available. The handler is called with 3 arguments: The first
1338
one is the pointer @var{cb_data} as set with this function, the second
1339
is the requested memory size and the last being a flag. If bit 0 of
1340
the flag is set, secure memory has been requested. The handler should
1341
either return true to indicate that Libgcrypt should try again
1342
allocating memory or return false to let Libgcrypt use its default
1343
fatal error handler.
1161
1344
@end deftypefun
1162
1345
1163
1346
@deftp {Data type} gcry_handler_error_t
1177
1360
@end deftp
1178
1361
1179
1362
@deftypefun void gcry_set_log_handler (gcry_handler_log_t @var{func_log}, void *@var{cb_data})
1180
This function registers @var{func_log} as `logging handler', which
1181
means that it will be called in case Libgcrypt wants to log
1182
a message.
1363
This function registers @var{func_log} as `logging handler', which means
1364
that it will be called in case Libgcrypt wants to log a message. This
1365
function may and should be used prior to calling
1366
@code{gcry_check_version}.
1183
1367
@end deftypefun
1184
1368
1185
1369
@c **********************************************************
1211
1395
The value always evaluates to false.
1212
1396
1213
1397
@item GCRY_CIPHER_IDEA
1398
@cindex IDEA
1214
1399
This is the IDEA algorithm. The constant is provided but there is
1215
1400
currently no implementation for it because the algorithm is patented.
1216
1401
1217
1402
@item GCRY_CIPHER_3DES
1403
@cindex 3DES
1404
@cindex Triple-DES
1405
@cindex DES-EDE
1406
@cindex Digital Encryption Standard
1218
1407
Triple-DES with 3 Keys as EDE. The key size of this algorithm is 168 but
1219
1408
you have to pass 192 bits because the most significant bits of each byte
1220
1409
are ignored.
1221
1410
1222
1411
@item GCRY_CIPHER_CAST5
1412
@cindex CAST5
1223
1413
CAST128-5 block cipher algorithm. The key size is 128 bits.
1224
1414
1225
1415
@item GCRY_CIPHER_BLOWFISH
1416
@cindex Blowfish
1226
1417
The blowfish algorithm. The current implementation allows only for a key
1227
1418
size of 128 bits.
1228
1419
1236
1427
@itemx GCRY_CIPHER_AES128
1237
1428
@itemx GCRY_CIPHER_RIJNDAEL
1238
1429
@itemx GCRY_CIPHER_RIJNDAEL128
1430
@cindex Rijndael
1431
@cindex AES
1432
@cindex Advanced Encryption Standard
1239
1433
AES (Rijndael) with a 128 bit key.
1240
1434
1241
1435
@item GCRY_CIPHER_AES192
1247
1441
AES (Rijndael) with a 256 bit key.
1248
1442
1249
1443
@item GCRY_CIPHER_TWOFISH
1444
@cindex Twofish
1250
1445
The Twofish algorithm with a 256 bit key.
1251
1446
1252
1447
@item GCRY_CIPHER_TWOFISH128
1253
1448
The Twofish algorithm with a 128 bit key.
1254
1449
1255
1450
@item GCRY_CIPHER_ARCFOUR
1451
@cindex Arcfour
1452
@cindex RC4
1256
1453
An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
1257
1454
Note that this is a stream cipher and must be used very carefully to
1258
1455
avoid a couple of weaknesses.
1259
1456
1260
@item GCRY_CIPHER_DES
1457
@item GCRY_CIPHER_DES
1458
@cindex DES
1261
1459
Standard DES with a 56 bit key. You need to pass 64 bit but the high
1262
1460
bits of each byte are ignored. Note, that this is a weak algorithm
1263
1461
which can be broken in reasonable time using a brute force approach.
1265
1463
@item GCRY_CIPHER_SERPENT128
1266
1464
@itemx GCRY_CIPHER_SERPENT192
1267
1465
@itemx GCRY_CIPHER_SERPENT256
1466
@cindex Serpent
1268
1467
The Serpent cipher from the AES contest.
1269
1468
1270
1469
@item GCRY_CIPHER_RFC2268_40
1271
1470
@itemx GCRY_CIPHER_RFC2268_128
1471
@cindex rfc-2268
1472
@cindex RC2
1272
1473
Ron's Cipher 2 in the 40 and 128 bit variants. Note, that we currently
1273
1474
only support the 40 bit variant. The identifier for 128 is reserved for
1274
1475
future use.
1275
1476
1276
1477
@item GCRY_CIPHER_SEED
1478
@cindex Seed (cipher)
1277
1479
A 128 bit cipher as described by RFC4269.
1278
1480
1279
1481
@item GCRY_CIPHER_CAMELLIA128
1280
1482
@itemx GCRY_CIPHER_CAMELLIA192
1281
1483
@itemx GCRY_CIPHER_CAMELLIA256
1484
@cindex Camellia
1282
1485
The Camellia cipher by NTT. See
1283
1486
@uref{http://info.isl.ntt.co.jp/@/crypt/@/eng/@/camellia/@/specifications.html}.
1284
1487
1363
1566
1364
1567
@deftp {Data type} gcry_cipher_stencrypt_t
1365
1568
Type for the `stencrypt' function, defined as: gcry_err_code_t
1366
(*gcry_cipher_stencrypt_t) (void *c, const unsigned char *outbuf, const
1569
(*gcry_@/cipher_@/stencrypt_@/t) (void *c, const unsigned char *outbuf, const
1367
1570
unsigned char *, unsigned int n)
1368
1571
@end deftp
1369
1572
1370
1573
@deftp {Data type} gcry_cipher_stdecrypt_t
1371
1574
Type for the `stdecrypt' function, defined as: gcry_err_code_t
1372
(*gcry_cipher_stdecrypt_t) (void *c, const unsigned char *outbuf, const
1575
(*gcry_@/cipher_@/stdecrypt_@/t) (void *c, const unsigned char *outbuf, const
1373
1576
unsigned char *, unsigned int n)
1374
1577
@end deftp
1375
1578
1401
1604
1402
1605
@table @code
1403
1606
@item GCRY_CIPHER_MODE_NONE
1404
No mode specified, may be set later using other functions. The value
1405
of this constant is always 0.
1607
No mode specified. This should not be used. The only exception is that
1608
if Libgcrypt is not used in FIPS mode and if any debug flag has been
1609
set, this mode may be used to bypass the actual encryption.
1406
1610
1407
1611
@item GCRY_CIPHER_MODE_ECB
1612
@cindex ECB, Electronic Codebook mode
1408
1613
Electronic Codebook mode.
1409
1614
1410
1615
@item GCRY_CIPHER_MODE_CFB
1411
Cipher Feedback mode.
1616
@cindex CFB, Cipher Feedback mode
1617
Cipher Feedback mode. The shift size equals the block size of the
1618
cipher (e.g. for AES it is CFB-128).
1412
1619
1413
1620
@item GCRY_CIPHER_MODE_CBC
1621
@cindex CBC, Cipher Block Chaining mode
1414
1622
Cipher Block Chaining mode.
1415
1623
1416
1624
@item GCRY_CIPHER_MODE_STREAM
1417
1625
Stream mode, only to be used with stream cipher algorithms.
1418
1626
1419
1627
@item GCRY_CIPHER_MODE_OFB
1628
@cindex OFB, Output Feedback mode
1420
1629
Output Feedback mode.
1421
1630
1422
1631
@item GCRY_CIPHER_MODE_CTR
1632
@cindex CTR, Counter mode
1423
1633
Counter mode.
1424
1634
1425
1635
@end table
1448
1658
@xref{Available cipher modes}, for a list of supported cipher modes
1449
1659
and the according constants. Note that some modes are incompatible
1450
1660
with some algorithms - in particular, stream mode
1451
(GCRY_CIPHER_MODE_STREAM) only works with stream ciphers. Any block
1452
cipher mode (GCRY_CIPHER_MODE_ECB, GCRY_CIPHER_MODE_CBC,
1453
GCRY_CIPHER_MODE_CFB, GCRY_CIPHER_MODE_OFB or GCRY_CIPHER_MODE_CTR)
1454
will work with any block cipher algorithm.
1661
(@code{GCRY_CIPHER_MODE_STREAM}) only works with stream ciphers. Any
1662
block cipher mode (@code{GCRY_CIPHER_MODE_ECB},
1663
@code{GCRY_CIPHER_MODE_CBC}, @code{GCRY_CIPHER_MODE_CFB},
1664
@code{GCRY_CIPHER_MODE_OFB} or @code{GCRY_CIPHER_MODE_CTR}) will work
1665
with any block cipher algorithm.
1455
1666
1456
1667
The third argument @var{flags} can either be passed as @code{0} or as
1457
1668
the bit-wise OR of the following constants.
1461
1672
Make sure that all operations are allocated in secure memory. This is
1462
1673
useful when the key material is highly confidential.
1463
1674
@item GCRY_CIPHER_ENABLE_SYNC
1675
@cindex sync mode (OpenPGP)
1464
1676
This flag enables the CFB sync mode, which is a special feature of
1465
1677
Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
1466
1678
See @code{gcry_cipher_sync}.
1467
1679
@item GCRY_CIPHER_CBC_CTS
1680
@cindex cipher text stealing
1468
1681
Enable cipher text stealing (CTS) for the CBC mode. Cannot be used
1469
1682
simultaneous as GCRY_CIPHER_CBC_MAC. CTS mode makes it possible to
1470
1683
transform data of almost arbitrary size (only limitation is that it
1471
1684
must be greater than the algorithm's block size).
1472
1685
@item GCRY_CIPHER_CBC_MAC
1686
@cindex CBC-MAC
1473
1687
Compute CBC-MAC keyed checksums. This is the same as CBC mode, but
1474
1688
only output the last block. Cannot be used simultaneous as
1475
1689
GCRY_CIPHER_CBC_CTS.
1486
1700
In order to use a handle for performing cryptographic operations, a
1487
1701
`key' has to be set first:
1488
1702
1489
@deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
1703
@deftypefun gcry_error_t gcry_cipher_setkey (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
1490
1704
1491
1705
Set the key @var{k} used for encryption or decryption in the context
1492
1706
denoted by the handle @var{h}. The length @var{l} of the key @var{k}
1495
1709
function checks this and returns an error if there is a problem. A
1496
1710
caller should always check for an error.
1497
1711
1498
Note that this is currently implemented as a macro but may be changed
1499
to a function in the future.
1500
1712
@end deftypefun
1501
1713
1502
1714
Most crypto modes requires an initialization vector (IV), which
1504
1716
The CTR mode requires a counter, which is also similar to a salt
1505
1717
value. To set the IV or CTR, use these functions:
1506
1718
1507
@deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, void *@var{k}, size_t @var{l})
1719
@deftypefun gcry_error_t gcry_cipher_setiv (gcry_cipher_hd_t @var{h}, const void *@var{k}, size_t @var{l})
1508
1720
1509
1721
Set the initialization vector used for encryption or decryption. The
1510
1722
vector is passed as the buffer @var{K} of length @var{l} and copied to
1511
1723
internal data structures. The function checks that the IV matches the
1512
requirement of the selected algorithm and mode. Note that this is
1513
implemented as a macro.
1724
requirement of the selected algorithm and mode.
1514
1725
@end deftypefun
1515
1726
1516
@deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, void *@var{c}, size_t @var{l})
1727
@deftypefun gcry_error_t gcry_cipher_setctr (gcry_cipher_hd_t @var{h}, const void *@var{c}, size_t @var{l})
1517
1728
1518
1729
Set the counter vector used for encryption or decryption. The counter
1519
1730
is passed as the buffer @var{c} of length @var{l} and copied to
1520
1731
internal data structures. The function checks that the counter
1521
1732
matches the requirement of the selected algorithm (i.e., it must be
1522
the same size as the block size). Note that this is implemented as a
1523
macro.
1733
the same size as the block size).
1524
1734
@end deftypefun
1525
1735
1526
1736
@deftypefun gcry_error_t gcry_cipher_reset (gcry_cipher_hd_t @var{h})
1648
1858
@end deftypefun
1649
1859
@c end gcry_cipher_algo_info
1650
1860
1651
@deftypefun const char *gcry_cipher_algo_name (int @var{algo})
1861
@deftypefun {const char *} gcry_cipher_algo_name (int @var{algo})
1652
1862
1653
1863
@code{gcry_cipher_algo_name} returns a string with the name of the
1654
1864
cipher algorithm @var{algo}. If the algorithm is not known or another
1674
1884
1675
1885
1676
1886
@c **********************************************************
1677
@c ******************* Hash Functions *********************
1678
@c **********************************************************
1679
@node Hashing
1680
@chapter Hashing
1681
1682
Libgcrypt provides an easy and consistent to use interface
1683
for hashing. Hashing is buffered and several hash algorithms can be
1684
updated at once. It is possible to calculate a MAC using the same
1685
routines. The programming model follows an open/process/close
1686
paradigm and is in that similar to other building blocks provided by
1687
Libgcrypt.
1688
1689
For convenience reasons, a few cyclic redundancy check value operations
1690
are also supported.
1691
1692
@menu
1693
* Available hash algorithms:: List of hash algorithms supported by the library.
1694
* Hash algorithm modules:: How to work with hash algorithm modules.
1695
* Working with hash algorithms:: List of functions related to hashing.
1696
@end menu
1697
1698
@node Available hash algorithms
1699
@section Available hash algorithms
1700
1701
@c begin table of hash algorithms
1702
@table @code
1703
@item GCRY_MD_NONE
1704
This is not a real algorithm but used by some functions as an error
1705
return value. This constant is guaranteed to have the value @code{0}.
1706
1707
@item GCRY_MD_SHA1
1708
This is the SHA-1 algorithm which yields a message digest of 20 bytes.
1709
1710
@item GCRY_MD_RMD160
1711
This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
1712
Like SHA-1 it also yields a digest of 20 bytes.
1713
1714
@item GCRY_MD_MD5
1715
This is the well known MD5 algorithm, which yields a message digest of
1716
16 bytes.
1717
1718
@item GCRY_MD_MD4
1719
This is the MD4 algorithm, which yields a message digest of 16 bytes.
1720
1721
@item GCRY_MD_MD2
1722
This is an reserved identifier for MD-2; there is no implementation yet.
1723
1724
@item GCRY_MD_TIGER
1725
This is the TIGER/192 algorithm which yields a message digest of 24 bytes.
1726
1727
@item GCRY_MD_HAVAL
1728
This is an reserved for the HAVAL algorithm with 5 passes and 160
1729
bit. It yields a message digest of 20 bytes. Note that there is no
1730
implementation yet available.
1731
1732
@item GCRY_MD_SHA224
1733
This is the SHA-224 algorithm which yields a message digest of 28 bytes.
1734
See Change Notice 1 for FIPS 180-2 for the specification.
1735
1736
@item GCRY_MD_SHA256
1737
This is the SHA-256 algorithm which yields a message digest of 32 bytes.
1738
See FIPS 180-2 for the specification.
1739
1740
@item GCRY_MD_SHA384
1741
This is the SHA-384 algorithm which yields a message digest of 48 bytes.
1742
See FIPS 180-2 for the specification.
1743
1744
@item GCRY_MD_SHA512
1745
This is the SHA-384 algorithm which yields a message digest of 64 bytes.
1746
See FIPS 180-2 for the specification.
1747
1748
@item GCRY_MD_CRC32
1749
This is the ISO 3309 and ITU-T V.42 cyclic redundancy check. It
1750
yields an output of 4 bytes.
1751
1752
@item GCRY_MD_CRC32_RFC1510
1753
This is the above cyclic redundancy check function, as modified by RFC
1754
1510. It yields an output of 4 bytes.
1755
1756
@item GCRY_MD_CRC24_RFC2440
1757
This is the OpenPGP cyclic redundancy check function. It yields an
1758
output of 3 bytes.
1759
1760
@item GCRY_MD_WHIRLPOOL
1761
This is the Whirlpool algorithm which yields a message digest of 64
1762
bytes.
1763
1764
@end table
1765
@c end table of hash algorithms
1766
1767
@node Hash algorithm modules
1768
@section Hash algorithm modules
1769
1770
Libgcrypt makes it possible to load additional `message
1771
digest modules'; these digests can be used just like the message digest
1772
algorithms that are built into the library directly. For an
1773
introduction into extension modules, see @xref{Modules}.
1774
1775
@deftp {Data type} gcry_md_spec_t
1776
This is the `module specification structure' needed for registering
1777
message digest modules, which has to be filled in by the user before
1778
it can be used to register a module. It contains the following
1779
members:
1780
1781
@table @code
1782
@item const char *name
1783
The primary name of this algorithm.
1784
@item unsigned char *asnoid
1785
Array of bytes that form the ASN OID.
1786
@item int asnlen
1787
Length of bytes in `asnoid'.
1788
@item gcry_md_oid_spec_t *oids
1789
A list of OIDs that are to be associated with the algorithm. The
1790
list's last element must have it's `oid' member set to NULL. See
1791
below for an explanation of this type. See below for an explanation
1792
of this type.
1793
@item int mdlen
1794
Length of the message digest algorithm. See below for an explanation
1795
of this type.
1796
@item gcry_md_init_t init
1797
The function responsible for initializing a handle. See below for an
1798
explanation of this type.
1799
@item gcry_md_write_t write
1800
The function responsible for writing data into a message digest
1801
context. See below for an explanation of this type.
1802
@item gcry_md_final_t final
1803
The function responsible for `finalizing' a message digest context.
1804
See below for an explanation of this type.
1805
@item gcry_md_read_t read
1806
The function responsible for reading out a message digest result. See
1807
below for an explanation of this type.
1808
@item size_t contextsize
1809
The size of the algorithm-specific `context', that should be
1810
allocated for each handle.
1811
@end table
1812
@end deftp
1813
1814
@deftp {Data type} gcry_md_oid_spec_t
1815
This type is used for associating a user-provided algorithm
1816
implementation with certain OIDs. It contains the following members:
1817
1818
@table @code
1819
@item const char *oidstring
1820
Textual representation of the OID.
1821
@end table
1822
@end deftp
1823
1824
@deftp {Data type} gcry_md_init_t
1825
Type for the `init' function, defined as: void (*gcry_md_init_t) (void
1826
*c)
1827
@end deftp
1828
1829
@deftp {Data type} gcry_md_write_t
1830
Type for the `write' function, defined as: void (*gcry_md_write_t)
1831
(void *c, unsigned char *buf, size_t nbytes)
1832
@end deftp
1833
1834
@deftp {Data type} gcry_md_final_t
1835
Type for the `final' function, defined as: void (*gcry_md_final_t)
1836
(void *c)
1837
@end deftp
1838
1839
@deftp {Data type} gcry_md_read_t
1840
Type for the `read' function, defined as: unsigned char
1841
*(*gcry_md_read_t) (void *c)
1842
@end deftp
1843
1844
@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
1845
1846
Register a new digest module whose specification can be found in
1847
@var{digest}. On success, a new algorithm ID is stored in
1848
@var{algorithm_id} and a pointer representing this module is stored
1849
in @var{module}.
1850
@end deftypefun
1851
1852
@deftypefun void gcry_md_unregister (gcry_module_t @var{module})
1853
Unregister the digest identified by @var{module}, which must have been
1854
registered with gcry_md_register.
1855
@end deftypefun
1856
1857
@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
1858
Get a list consisting of the IDs of the loaded message digest modules.
1859
If @var{list} is zero, write the number of loaded message digest
1860
modules to @var{list_length} and return. If @var{list} is non-zero,
1861
the first *@var{list_length} algorithm IDs are stored in @var{list},
1862
which must be of according size. In case there are less message
1863
digests modules than *@var{list_length}, *@var{list_length} is updated
1864
to the correct number.
1865
@end deftypefun
1866
1867
@node Working with hash algorithms
1868
@section Working with hash algorithms
1869
1870
To use most of these function it is necessary to create a context;
1871
this is done using:
1872
1873
@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
1874
1875
Create a message digest object for algorithm @var{algo}. @var{flags}
1876
may be given as an bitwise OR of constants described below. @var{algo}
1877
may be given as @code{0} if the algorithms to use are later set using
1878
@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
1879
handle or NULL.
1880
1881
For a list of supported algorithms, see @xref{Available hash
1882
algorithms}.
1883
1884
The flags allowed for @var{mode} are:
1885
1886
@c begin table of hash flags
1887
@table @code
1888
@item GCRY_MD_FLAG_SECURE
1889
Allocate all buffers and the resulting digest in "secure memory". Use
1890
this is the hashed data is highly confidential.
1891
1892
@item GCRY_MD_FLAG_HMAC
1893
Turn the algorithm into a HMAC message authentication algorithm. This
1894
only works if just one algorithm is enabled for the handle. Note that the function
1895
@code{gcry_md_setkey} must be used to set the MAC key. If you want CBC
1896
message authentication codes based on a cipher, see @xref{Working with
1897
cipher handles}.
1898
1899
@end table
1900
@c begin table of hash flags
1901
1902
You may use the function @code{gcry_md_is_enabled} to later check
1903
whether an algorithm has been enabled.
1904
1905
@end deftypefun
1906
@c end function gcry_md_open
1907
1908
If you want to calculate several hash algorithms at the same time, you
1909
have to use the following function right after the @code{gcry_md_open}:
1910
1911
@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
1912
1913
Add the message digest algorithm @var{algo} to the digest object
1914
described by handle @var{h}. Duplicated enabling of algorithms is
1915
detected and ignored.
1916
@end deftypefun
1917
1918
If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
1919
be set using the function:
1920
1921
@deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
1922
1923
For use with the HMAC feature, set the MAC key to the value of @var{key}
1924
of length @var{keylen}.
1925
@end deftypefun
1926
1927
1928
After you are done with the hash calculation, you should release the
1929
resources by using:
1930
1931
@deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
1932
1933
Release all resources of hash context @var{h}. @var{h} should not be
1934
used after a call to this function. A @code{NULL} passed as @var{h} is
1935
ignored.
1936
1937
@end deftypefun
1938
1939
Often you have to do several hash operations using the same algorithm.
1940
To avoid the overhead of creating and releasing context, a reset function
1941
is provided:
1942
1943
@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
1944
1945
Reset the current context to its initial state. This is effectively
1946
identical to a close followed by an open and enabling all currently
1947
active algorithms.
1948
@end deftypefun
1949
1950
1951
Often it is necessary to start hashing some data and then continue to
1952
hash different data. To avoid hashing the same data several times (which
1953
might not even be possible if the data is received from a pipe), a
1954
snapshot of the current hash context can be taken and turned into a new
1955
context:
1956
1957
@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
1958
1959
Create a new digest object as an exact copy of the object described by
1960
handle @var{handle_src} and store it in @var{handle_dst}. The context
1961
is not reset and you can continue to hash data using this context and
1962
independently using the original context.
1963
@end deftypefun
1964
1965
1966
Now that we have prepared everything to calculate hashes, it is time to
1967
see how it is actually done. There are two ways for this, one to
1968
update the hash with a block of memory and one macro to update the hash
1969
by just one character. Both methods can be used on the same hash context.
1970
1971
@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
1972
1973
Pass @var{length} bytes of the data in @var{buffer} to the digest object
1974
with handle @var{h} to update the digest values. This
1975
function should be used for large blocks of data.
1976
@end deftypefun
1977
1978
@deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
1979
1980
Pass the byte in @var{c} to the digest object with handle @var{h} to
1981
update the digest value. This is an efficient function, implemented as
1982
a macro to buffer the data before an actual update.
1983
@end deftypefun
1984
1985
The semantics of the hash functions do not provide for reading out intermediate
1986
message digests because the calculation must be finalized first. This
1987
finalization may for example include the number of bytes hashed in the
1988
message digest or some padding.
1989
1990
@deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
1991
1992
Finalize the message digest calculation. This is not really needed
1993
because @code{gcry_md_read} does this implicitly. After this has been
1994
done no further updates (by means of @code{gcry_md_write} or
1995
@code{gcry_md_putc} are allowed. Only the first call to this function
1996
has an effect. It is implemented as a macro.
1997
@end deftypefun
1998
1999
The way to read out the calculated message digest is by using the
2000
function:
2001
2002
@deftypefun unsigned char *gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
2003
2004
@code{gcry_md_read} returns the message digest after finalizing the
2005
calculation. This function may be used as often as required but it will
2006
always return the same value for one handle. The returned message digest
2007
is allocated within the message context and therefore valid until the
2008
handle is released or reseted (using @code{gcry_md_close} or
2009
@code{gcry_md_reset}. @var{algo} may be given as 0 to return the only
2010
enabled message digest or it may specify one of the enabled algorithms.
2011
The function does return @code{NULL} if the requested algorithm has not
2012
been enabled.
2013
@end deftypefun
2014
2015
Because it is often necessary to get the message digest of one block of
2016
memory, a fast convenience function is available for this task:
2017
2018
@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
2019
2020
@code{gcry_md_hash_buffer} is a shortcut function to calculate a message
2021
digest of a buffer. This function does not require a context and
2022
immediately returns the message digest of the @var{length} bytes at
2023
@var{buffer}. @var{digest} must be allocated by the caller, large
2024
enough to hold the message digest yielded by the the specified algorithm
2025
@var{algo}. This required size may be obtained by using the function
2026
@code{gcry_md_get_algo_dlen}.
2027
2028
Note that this function will abort the process if an unavailable
2029
algorithm is used.
2030
@end deftypefun
2031
2032
@c ***********************************
2033
@c ***** MD info functions ***********
2034
@c ***********************************
2035
2036
Hash algorithms are identified by internal algorithm numbers (see
2037
@code{gcry_md_open} for a list). However, in most applications they are
2038
used by names, so two functions are available to map between string
2039
representations and hash algorithm identifiers.
2040
2041
@deftypefun const char *gcry_md_algo_name (int @var{algo})
2042
2043
Map the digest algorithm id @var{algo} to a string representation of the
2044
algorithm name. For unknown algorithms this function returns the
2045
string @code{"?"}. This function should not be used to test for the
2046
availability of an algorithm.
2047
@end deftypefun
2048
2049
@deftypefun int gcry_md_map_name (const char *@var{name})
2050
2051
Map the algorithm with @var{name} to a digest algorithm identifier.
2052
Returns 0 if the algorithm name is not known. Names representing
2053
@acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}
2054
dotted format is used and the OID is prefixed with either "@code{oid.}"
2055
or "@code{OID.}". For a list of supported OIDs, see the source code at
2056
@file{cipher/md.c}. This function should not be used to test for the
2057
availability of an algorithm.
2058
@end deftypefun
2059
2060
@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
2061
2062
Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
2063
user allocated @var{buffer}. @var{length} must point to variable with
2064
the available size of @var{buffer} and receives after return the
2065
actual size of the returned OID. The returned error code may be
2066
@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
2067
the OID; it is possible to call the function with @code{NULL} for
2068
@var{buffer} to have it only return the required size. The function
2069
returns 0 on success.
2070
2071
@end deftypefun
2072
2073
2074
To test whether an algorithm is actually available for use, the
2075
following macro should be used:
2076
2077
@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
2078
2079
The macro returns 0 if the algorithm @var{algo} is available for use.
2080
@end deftypefun
2081
2082
If the length of a message digest is not known, it can be retrieved
2083
using the following function:
2084
2085
@deftypefun unsigned int gcry_md_get_algo_dlen (int @var{algo})
2086
2087
Retrieve the length in bytes of the digest yielded by algorithm
2088
@var{algo}. This is often used prior to @code{gcry_md_read} to allocate
2089
sufficient memory for the digest.
2090
@end deftypefun
2091
2092
2093
In some situations it might be hard to remember the algorithm used for
2094
the ongoing hashing. The following function might be used to get that
2095
information:
2096
2097
@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
2098
2099
Retrieve the algorithm used with the handle @var{h}. Note that this
2100
does not work reliable if more than one algorithm is enabled in @var{h}.
2101
@end deftypefun
2102
2103
The following macro might also be useful:
2104
2105
@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
2106
2107
This function returns true when the digest object @var{h} is allocated
2108
in "secure memory"; i.e. @var{h} was created with the
2109
@code{GCRY_MD_FLAG_SECURE}.
2110
@end deftypefun
2111
2112
@deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})
2113
2114
This function returns true when the algorithm @var{algo} has been
2115
enabled for the digest object @var{h}.
2116
@end deftypefun
2117
2118
2119
2120
Tracking bugs related to hashing is often a cumbersome task which
2121
requires to add a lot of printf statements into the code.
2122
Libgcrypt provides an easy way to avoid this. The actual data
2123
hashed can be written to files on request.
2124
2125
@deftypefun void gcry_md_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
2126
2127
Enable debugging for the digest object with handle @var{h}. This
2128
creates create files named @file{dbgmd-<n>.<string>} while doing the
2129
actual hashing. @var{suffix} is the string part in the filename. The
2130
number is a counter incremented for each new hashing. The data in the
2131
file is the raw data as passed to @code{gcry_md_write} or
2132
@code{gcry_md_putc}. If @code{NULL} is used for @var{suffix}, the
2133
debugging is stopped and the file closed. This is only rarely required
2134
because @code{gcry_md_close} implicitly stops debugging.
2135
@end deftypefun
2136
2137
2138
The following two deprecated macros are used for debugging by old code.
2139
They shopuld be replaced by @code{gcry_md_debug}.
2140
2141
@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
2142
2143
Enable debugging for the digest object with handle @var{h}. This
2144
creates create files named @file{dbgmd-<n>.<string>} while doing the
2145
actual hashing. @var{suffix} is the string part in the filename. The
2146
number is a counter incremented for each new hashing. The data in the
2147
file is the raw data as passed to @code{gcry_md_write} or
2148
@code{gcry_md_putc}.
2149
@end deftypefun
2150
2151
2152
@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved})
2153
2154
Stop debugging on handle @var{h}. @var{reserved} should be specified as
2155
0. This function is usually not required because @code{gcry_md_close}
2156
does implicitly stop debugging.
2157
@end deftypefun
2158
2159
2160
@c **********************************************************
2161
1887
@c ******************* Public Key *************************
2162
1888
@c **********************************************************
2163
@node Public Key cryptography (I)
2164
@chapter Public Key cryptography (I)
1889
@node Public Key cryptography
1890
@chapter Public Key cryptography
2165
1891
2166
1892
Public key cryptography, also known as asymmetric cryptography, is an
2167
1893
easy way for key management and to provide digital signatures.
2175
1901
* Public key modules:: How to work with public key modules.
2176
1902
* Cryptographic Functions:: Functions for performing the cryptographic actions.
2177
1903
* General public-key related Functions:: General functions, not implementing any cryptography.
1904
1905
* AC Interface:: Alternative interface to public key functions.
2178
1906
@end menu
2179
1907
2180
1908
@node Available algorithms
2192
1920
@uref{http://people.csail.mit.edu/@/rivest/@/sexp.html}) and does not work
2193
1921
with contexts as most of the other building blocks of Libgcrypt do.
2194
1922
1923
@noindent
2195
1924
The following information are stored in S-expressions:
2196
1925
2197
@table @asis
1926
@itemize @asis
2198
1927
@item keys
2199
1928
2200
1929
@item plain text data
2203
1932
2204
1933
@item signatures
2205
1934
2206
@end table
1935
@end itemize
2207
1936
2208
1937
@noindent
2209
1938
To describe how Libgcrypt expect keys, we use examples. Note that
2216
1945
@end iftex
2217
1946
indicate parameters whereas lowercase words are literals.
2218
1947
2219
Note that all MPI (big integer) values are expected to be in
1948
Note that all MPI (multi-precision-integers) values are expected to be in
2220
1949
@code{GCRYMPI_FMT_USG} format. An easy way to create S-expressions is
2221
1950
by using @code{gcry_sexp_build} which allows to pass a string with
2222
1951
printf-like escapes to insert MPI values.
2610
2339
does the padding and encrypts it.
2611
2340
2612
2341
If the function could successfully perform the encryption, the return
2613
value will be 0 and a a new S-expression with the encrypted result is
2342
value will be 0 and a new S-expression with the encrypted result is
2614
2343
allocated and assigned to the variable at the address of @var{r_ciph}.
2615
2344
The caller is responsible to release this value using
2616
2345
@code{gcry_sexp_release}. In case of an error, an error code is
2833
2562
2834
2563
@table @code
2835
2564
@item GCRYCTL_TEST_ALGO:
2836
Return 0 when the specified algorithm is available for use.
2565
Return 0 if the specified algorithm is available for use.
2837
2566
@var{buffer} must be @code{NULL}, @var{nbytes} may be passed as
2838
2567
@code{NULL} or point to a variable with the required usage of the
2839
2568
algorithm. This may be 0 for "don't care" or the bit-wise OR of these
2846
2575
Algorithm is usable for encryption.
2847
2576
@end table
2848
2577
2578
Unless you need to test for the allowed usage, it is in general better
2579
to use the macro gcry_pk_test_algo instead.
2580
2849
2581
@item GCRYCTL_GET_ALGO_USAGE:
2850
2582
Return the usage flags for the given algorithm. An invalid algorithm
2851
2583
return 0. Disabled algorithms are ignored here because we
2895
2627
@c end gcry_pk_ctl
2896
2628
2897
2629
@noindent
2898
Libgcrypt also provides a function for generating public key
2630
Libgcrypt also provides a function to generate public key
2899
2631
pairs:
2900
2632
2901
2633
@deftypefun gcry_error_t gcry_pk_genkey (@w{gcry_sexp_t *@var{r_key}}, @w{gcry_sexp_t @var{parms}})
2907
2639
success or an error code otherwise.
2908
2640
2909
2641
@noindent
2910
Here is an example for @var{parms} for creating a 1024 bit RSA key:
2642
Here is an example for @var{parms} to create an 2048 bit RSA key:
2911
2643
2912
2644
@example
2913
2645
(genkey
2914
2646
(rsa
2915
(nbits 4:1024)))
2647
(nbits 4:2048)))
2916
2648
@end example
2917
2649
2918
2650
@noindent
2943
2675
@item 0
2944
2676
Use a secure and fast value. This is currently the number 41.
2945
2677
@item 1
2946
Use a secure value as required by some specification. This is currently
2678
Use a value as required by some crypto policies. This is currently
2947
2679
the number 65537.
2948
2680
@item 2
2949
2681
Reserved
2682
@item > 2
2683
Use the given value.
2950
2684
@end table
2951
2685
2952
2686
@noindent
2973
2707
are allowed. When specifying Q all values of N in the range 512 to
2974
2708
15680 are valid as long as they are multiples of 8.
2975
2709
2710
@item transient-key
2711
This is only meaningful for RSA and DSA keys. This is a flag with no
2712
value. If given the RSA or DSA key is created using a faster and a
2713
somewhat less secure random number generator. This flag may be used
2714
for keys which are only used for a short time and do not require full
2715
cryptographic strength.
2716
2717
@item domain
2718
This is only meaningful for DLP algorithms. If specified keys are
2719
generated with domain parameters taken from this list. The exact
2720
format of this parameter depends on the actual algorithm. It is
2721
currently only implemented for DSA using this format:
2722
2723
@example
2724
(genkey
2725
(dsa
2726
(domain
2727
(p @var{p-mpi})
2728
(q @var{q-mpi})
2729
(g @var{q-mpi}))))
2730
@end example
2731
2732
@code{nbits} and @code{qbits} may not be specified because they are
2733
derived from the domain parameters.
2734
2735
@item derive-parms
2736
This is currently only implemented for RSA and DSA keys. It is not
2737
allowed to use this together with a @code{domain} specification. If
2738
given, it is used to derive the keys using the given parameters.
2739
2740
If given for an RSA key the X9.31 key generation algorithm is used
2741
even if libgcrypt is not in FIPS mode. If given for a DSA key, the
2742
FIPS 186 algorithm is used even if libgcrypt is not in FIPS mode.
2743
2744
@example
2745
(genkey
2746
(rsa
2747
(nbits 4:1024)
2748
(rsa-use-e 1:3)
2749
(derive-parms
2750
(Xp1 #1A1916DDB29B4EB7EB6732E128#)
2751
(Xp2 #192E8AAC41C576C822D93EA433#)
2752
(Xp #D8CD81F035EC57EFE822955149D3BFF70C53520D
2753
769D6D76646C7A792E16EBD89FE6FC5B605A6493
2754
39DFC925A86A4C6D150B71B9EEA02D68885F5009
2755
B98BD984#)
2756
(Xq1 #1A5CF72EE770DE50CB09ACCEA9#)
2757
(Xq2 #134E4CAA16D2350A21D775C404#)
2758
(Xq #CC1092495D867E64065DEE3E7955F2EBC7D47A2D
2759
7C9953388F97DDDC3E1CA19C35CA659EDC2FC325
2760
6D29C2627479C086A699A49C4C9CEE7EF7BD1B34
2761
321DE34A#))))
2762
@end example
2763
2764
@example
2765
(genkey
2766
(dsa
2767
(nbits 4:1024)
2768
(derive-parms
2769
(seed @var{seed-mpi}))))
2770
@end example
2771
2772
2773
@item use-x931
2774
@cindex X9.31
2775
Force the use of the ANSI X9.31 key generation algorithm instead of
2776
the default algorithm. This flag is only meaningful for RSA and
2777
usually not required. Note that this algorithm is implicitly used if
2778
either @code{derive-parms} is given or Libgcrypt is in FIPS mode.
2779
2780
@item use-fips186
2781
@cindex FIPS 186
2782
Force the use of the FIPS 186 key generation algorithm instead of the
2783
default algorithm. This flag is only meaningful for DSA and usually
2784
not required. Note that this algorithm is implicitly used if either
2785
@code{derive-parms} is given or Libgcrypt is in FIPS mode. As of now
2786
FIPS 186-2 is implemented; after the approval of FIPS 186-3 the code
2787
will be changed to implement 186-3.
2788
2789
2790
@item use-fips186-2
2791
Force the use of the FIPS 186-2 key generation algorithm instead of
2792
the default algorithm. This algorithm is slighlty different from
2793
FIPS 186-3 and allows only 1024 bit keys. This flag is only meaningful
2794
for DSA and only required for FIPS testing backward compatibility.
2795
2796
2976
2797
@end table
2977
2798
@c end table of parameters
2978
2799
2998
2819
(y @var{y-mpi})
2999
2820
(x @var{x-mpi})))
3000
2821
(misc-key-info
3001
(pm1-factors @var{n1 n2 ... nn})))
2822
(pm1-factors @var{n1 n2 ... nn}))
3002
2823
@end example
3003
2824
3004
2825
@noindent
3005
As you can see, some of the information is duplicated, but this provides
3006
an easy way to extract either the public or the private key. Note that
3007
the order of the elements is not defined, e.g. the private key may be
3008
stored before the public key. @var{n1 n2 ... nn} is a list of prime
3009
numbers used to composite @var{p-mpi}; this is in general not a very
3010
useful information.
2826
As you can see, some of the information is duplicated, but this
2827
provides an easy way to extract either the public or the private key.
2828
Note that the order of the elements is not defined, e.g. the private
2829
key may be stored before the public key. @var{n1 n2 ... nn} is a list
2830
of prime numbers used to composite @var{p-mpi}; this is in general not
2831
a very useful information and only available if the key generation
2832
algorithm provides them.
3011
2833
@end deftypefun
3012
2834
@c end gcry_pk_genkey
3013
2835
3014
@node Public Key cryptography (II)
3015
@chapter Public Key cryptography (II)
2836
@node AC Interface
2837
@section Alternative Public Key Interface
3016
2838
3017
This chapter documents the alternative interface to asymmetric
2839
This section documents the alternative interface to asymmetric
3018
2840
cryptography (ac) that is not based on S-expressions, but on native C
3019
2841
data structures. As opposed to the pk interface described in the
3020
2842
former chapter, this one follows an open/use/close paradigm like other
3022
2844
3023
2845
@strong{This interface has a few known problems; most noteworthy an
3024
2846
inherent tendency to leak memory. It might not be available in
3025
forthcoming versions Libgcrypt.}
2847
forthcoming versions of Libgcrypt.}
3026
2848
3027
2849
3028
2850
@menu
3036
2858
@end menu
3037
2859
3038
2860
@node Available asymmetric algorithms
3039
@section Available asymmetric algorithms
2861
@subsection Available asymmetric algorithms
3040
2862
3041
2863
Libgcrypt supports the RSA (Rivest-Shamir-Adleman)
3042
2864
algorithms as well as DSA (Digital Signature Algorithm) and Elgamal.
3059
2881
@end deftp
3060
2882
3061
2883
@node Working with sets of data
3062
@section Working with sets of data
2884
@subsection Working with sets of data
3063
2885
3064
2886
In the context of this interface the term `data set' refers to a list
3065
2887
of `named MPI values' that is used by functions performing
3116
2938
@var{data_cp}. FIXME: exact semantics undefined.
3117
2939
@end deftypefun
3118
2940
3119
@deftypefun unsigned int gcry_ac_data_length (gcry_ac_data_t @var{data})
2941
@deftypefun {unsigned int} gcry_ac_data_length (gcry_ac_data_t @var{data})
3120
2942
Returns the number of named MPI values inside of the data set
3121
2943
@var{data}.
3122
2944
@end deftypefun
3164
2986
@end deftypefun
3165
2987
3166
2988
@node Working with IO objects
3167
@section Working with IO objects
2989
@subsection Working with IO objects
3168
2990
3169
2991
Note: IO objects are currently only used in the context of message
3170
2992
encoding/decoding and encryption/signature schemes.
3239
3061
@end table
3240
3062
3241
3063
@node Working with handles
3242
@section Working with handles
3064
@subsection Working with handles
3243
3065
3244
3066
In order to use an algorithm, an according handle must be created.
3245
3067
This is done using the following function:
3261
3083
@end deftypefun
3262
3084
3263
3085
@node Working with keys
3264
@section Working with keys
3086
@subsection Working with keys
3265
3087
3266
3088
@deftp {Data type} gcry_ac_key_type_t
3267
3089
Defined constants:
3337
3159
err = gcry_ac_open (&handle, GCRY_AC_RSA, 0);
3338
3160
assert (! err);
3339
3161
3340
err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec, &key_pair, NULL);
3162
err = gcry_ac_key_pair_generate (handle, 1024, &rsa_spec,
3163
&key_pair, NULL);
3341
3164
assert (! err);
3342
3165
@}
3343
3166
@end example
3375
3198
@end deftypefun
3376
3199
3377
3200
@node Using cryptographic functions
3378
@section Using cryptographic functions
3201
@subsection Using cryptographic functions
3379
3202
3380
3203
The following flags might be relevant:
3381
3204
3532
3355
@end deftypefun
3533
3356
3534
3357
@node Handle-independent functions
3535
@section Handle-independent functions
3358
@subsection Handle-independent functions
3536
3359
3537
3360
These two functions are deprecated; do not use them for new code.
3538
3361
3548
3371
@end deftypefun
3549
3372
3550
3373
@c **********************************************************
3374
@c ******************* Hash Functions *********************
3375
@c **********************************************************
3376
@node Hashing
3377
@chapter Hashing
3378
3379
Libgcrypt provides an easy and consistent to use interface for hashing.
3380
Hashing is buffered and several hash algorithms can be updated at once.
3381
It is possible to compute a MAC using the same routines. The
3382
programming model follows an open/process/close paradigm and is in that
3383
similar to other building blocks provided by Libgcrypt.
3384
3385
For convenience reasons, a few cyclic redundancy check value operations
3386
are also supported.
3387
3388
@menu
3389
* Available hash algorithms:: List of hash algorithms supported by the library.
3390
* Hash algorithm modules:: How to work with hash algorithm modules.
3391
* Working with hash algorithms:: List of functions related to hashing.
3392
@end menu
3393
3394
@node Available hash algorithms
3395
@section Available hash algorithms
3396
3397
@c begin table of hash algorithms
3398
@cindex SHA-1
3399
@cindex SHA-224, SHA-256, SHA-384, SHA-512
3400
@cindex RIPE-MD-160
3401
@cindex MD2, MD4, MD5
3402
@cindex TIGER
3403
@cindex HAVAL
3404
@cindex Whirlpool
3405
@cindex CRC32
3406
@table @code
3407
@item GCRY_MD_NONE
3408
This is not a real algorithm but used by some functions as an error
3409
return value. This constant is guaranteed to have the value @code{0}.
3410
3411
@item GCRY_MD_SHA1
3412
This is the SHA-1 algorithm which yields a message digest of 20 bytes.
3413
3414
@item GCRY_MD_RMD160
3415
This is the 160 bit version of the RIPE message digest (RIPE-MD-160).
3416
Like SHA-1 it also yields a digest of 20 bytes.
3417
3418
@item GCRY_MD_MD5
3419
This is the well known MD5 algorithm, which yields a message digest of
3420
16 bytes.
3421
3422
@item GCRY_MD_MD4
3423
This is the MD4 algorithm, which yields a message digest of 16 bytes.
3424
3425
@item GCRY_MD_MD2
3426
This is an reserved identifier for MD-2; there is no implementation yet.
3427
3428
@item GCRY_MD_TIGER
3429
This is the TIGER/192 algorithm which yields a message digest of 24 bytes.
3430
3431
@item GCRY_MD_HAVAL
3432
This is an reserved for the HAVAL algorithm with 5 passes and 160
3433
bit. It yields a message digest of 20 bytes. Note that there is no
3434
implementation yet available.
3435
3436
@item GCRY_MD_SHA224
3437
This is the SHA-224 algorithm which yields a message digest of 28 bytes.
3438
See Change Notice 1 for FIPS 180-2 for the specification.
3439
3440
@item GCRY_MD_SHA256
3441
This is the SHA-256 algorithm which yields a message digest of 32 bytes.
3442
See FIPS 180-2 for the specification.
3443
3444
@item GCRY_MD_SHA384
3445
This is the SHA-384 algorithm which yields a message digest of 48 bytes.
3446
See FIPS 180-2 for the specification.
3447
3448
@item GCRY_MD_SHA512
3449
This is the SHA-384 algorithm which yields a message digest of 64 bytes.
3450
See FIPS 180-2 for the specification.
3451
3452
@item GCRY_MD_CRC32
3453
This is the ISO 3309 and ITU-T V.42 cyclic redundancy check. It
3454
yields an output of 4 bytes.
3455
3456
@item GCRY_MD_CRC32_RFC1510
3457
This is the above cyclic redundancy check function, as modified by RFC
3458
1510. It yields an output of 4 bytes.
3459
3460
@item GCRY_MD_CRC24_RFC2440
3461
This is the OpenPGP cyclic redundancy check function. It yields an
3462
output of 3 bytes.
3463
3464
@item GCRY_MD_WHIRLPOOL
3465
This is the Whirlpool algorithm which yields a message digest of 64
3466
bytes.
3467
3468
@end table
3469
@c end table of hash algorithms
3470
3471
@node Hash algorithm modules
3472
@section Hash algorithm modules
3473
3474
Libgcrypt makes it possible to load additional `message
3475
digest modules'; these digests can be used just like the message digest
3476
algorithms that are built into the library directly. For an
3477
introduction into extension modules, see @xref{Modules}.
3478
3479
@deftp {Data type} gcry_md_spec_t
3480
This is the `module specification structure' needed for registering
3481
message digest modules, which has to be filled in by the user before
3482
it can be used to register a module. It contains the following
3483
members:
3484
3485
@table @code
3486
@item const char *name
3487
The primary name of this algorithm.
3488
@item unsigned char *asnoid
3489
Array of bytes that form the ASN OID.
3490
@item int asnlen
3491
Length of bytes in `asnoid'.
3492
@item gcry_md_oid_spec_t *oids
3493
A list of OIDs that are to be associated with the algorithm. The
3494
list's last element must have it's `oid' member set to NULL. See
3495
below for an explanation of this type. See below for an explanation
3496
of this type.
3497
@item int mdlen
3498
Length of the message digest algorithm. See below for an explanation
3499
of this type.
3500
@item gcry_md_init_t init
3501
The function responsible for initializing a handle. See below for an
3502
explanation of this type.
3503
@item gcry_md_write_t write
3504
The function responsible for writing data into a message digest
3505
context. See below for an explanation of this type.
3506
@item gcry_md_final_t final
3507
The function responsible for `finalizing' a message digest context.
3508
See below for an explanation of this type.
3509
@item gcry_md_read_t read
3510
The function responsible for reading out a message digest result. See
3511
below for an explanation of this type.
3512
@item size_t contextsize
3513
The size of the algorithm-specific `context', that should be
3514
allocated for each handle.
3515
@end table
3516
@end deftp
3517
3518
@deftp {Data type} gcry_md_oid_spec_t
3519
This type is used for associating a user-provided algorithm
3520
implementation with certain OIDs. It contains the following members:
3521
3522
@table @code
3523
@item const char *oidstring
3524
Textual representation of the OID.
3525
@end table
3526
@end deftp
3527
3528
@deftp {Data type} gcry_md_init_t
3529
Type for the `init' function, defined as: void (*gcry_md_init_t) (void
3530
*c)
3531
@end deftp
3532
3533
@deftp {Data type} gcry_md_write_t
3534
Type for the `write' function, defined as: void (*gcry_md_write_t)
3535
(void *c, unsigned char *buf, size_t nbytes)
3536
@end deftp
3537
3538
@deftp {Data type} gcry_md_final_t
3539
Type for the `final' function, defined as: void (*gcry_md_final_t)
3540
(void *c)
3541
@end deftp
3542
3543
@deftp {Data type} gcry_md_read_t
3544
Type for the `read' function, defined as: unsigned char
3545
*(*gcry_md_read_t) (void *c)
3546
@end deftp
3547
3548
@deftypefun gcry_error_t gcry_md_register (gcry_md_spec_t *@var{digest}, unsigned int *algorithm_id, gcry_module_t *@var{module})
3549
3550
Register a new digest module whose specification can be found in
3551
@var{digest}. On success, a new algorithm ID is stored in
3552
@var{algorithm_id} and a pointer representing this module is stored
3553
in @var{module}.
3554
@end deftypefun
3555
3556
@deftypefun void gcry_md_unregister (gcry_module_t @var{module})
3557
Unregister the digest identified by @var{module}, which must have been
3558
registered with gcry_md_register.
3559
@end deftypefun
3560
3561
@deftypefun gcry_error_t gcry_md_list (int *@var{list}, int *@var{list_length})
3562
Get a list consisting of the IDs of the loaded message digest modules.
3563
If @var{list} is zero, write the number of loaded message digest
3564
modules to @var{list_length} and return. If @var{list} is non-zero,
3565
the first *@var{list_length} algorithm IDs are stored in @var{list},
3566
which must be of according size. In case there are less message
3567
digests modules than *@var{list_length}, *@var{list_length} is updated
3568
to the correct number.
3569
@end deftypefun
3570
3571
@node Working with hash algorithms
3572
@section Working with hash algorithms
3573
3574
To use most of these function it is necessary to create a context;
3575
this is done using:
3576
3577
@deftypefun gcry_error_t gcry_md_open (gcry_md_hd_t *@var{hd}, int @var{algo}, unsigned int @var{flags})
3578
3579
Create a message digest object for algorithm @var{algo}. @var{flags}
3580
may be given as an bitwise OR of constants described below. @var{algo}
3581
may be given as @code{0} if the algorithms to use are later set using
3582
@code{gcry_md_enable}. @var{hd} is guaranteed to either receive a valid
3583
handle or NULL.
3584
3585
For a list of supported algorithms, see @xref{Available hash
3586
algorithms}.
3587
3588
The flags allowed for @var{mode} are:
3589
3590
@c begin table of hash flags
3591
@table @code
3592
@item GCRY_MD_FLAG_SECURE
3593
Allocate all buffers and the resulting digest in "secure memory". Use
3594
this is the hashed data is highly confidential.
3595
3596
@item GCRY_MD_FLAG_HMAC
3597
@cindex HMAC
3598
Turn the algorithm into a HMAC message authentication algorithm. This
3599
only works if just one algorithm is enabled for the handle. Note that
3600
the function @code{gcry_md_setkey} must be used to set the MAC key.
3601
The size of the MAC is equal to the message digest of the underlying
3602
hash algorithm. If you want CBC message authentication codes based on
3603
a cipher, see @xref{Working with cipher handles}.
3604
3605
@end table
3606
@c begin table of hash flags
3607
3608
You may use the function @code{gcry_md_is_enabled} to later check
3609
whether an algorithm has been enabled.
3610
3611
@end deftypefun
3612
@c end function gcry_md_open
3613
3614
If you want to calculate several hash algorithms at the same time, you
3615
have to use the following function right after the @code{gcry_md_open}:
3616
3617
@deftypefun gcry_error_t gcry_md_enable (gcry_md_hd_t @var{h}, int @var{algo})
3618
3619
Add the message digest algorithm @var{algo} to the digest object
3620
described by handle @var{h}. Duplicated enabling of algorithms is
3621
detected and ignored.
3622
@end deftypefun
3623
3624
If the flag @code{GCRY_MD_FLAG_HMAC} was used, the key for the MAC must
3625
be set using the function:
3626
3627
@deftypefun gcry_error_t gcry_md_setkey (gcry_md_hd_t @var{h}, const void *@var{key}, size_t @var{keylen})
3628
3629
For use with the HMAC feature, set the MAC key to the value of @var{key}
3630
of length @var{keylen}. There is no restriction on the length of the key.
3631
@end deftypefun
3632
3633
3634
After you are done with the hash calculation, you should release the
3635
resources by using:
3636
3637
@deftypefun void gcry_md_close (gcry_md_hd_t @var{h})
3638
3639
Release all resources of hash context @var{h}. @var{h} should not be
3640
used after a call to this function. A @code{NULL} passed as @var{h} is
3641
ignored.
3642
3643
@end deftypefun
3644
3645
Often you have to do several hash operations using the same algorithm.
3646
To avoid the overhead of creating and releasing context, a reset function
3647
is provided:
3648
3649
@deftypefun void gcry_md_reset (gcry_md_hd_t @var{h})
3650
3651
Reset the current context to its initial state. This is effectively
3652
identical to a close followed by an open and enabling all currently
3653
active algorithms.
3654
@end deftypefun
3655
3656
3657
Often it is necessary to start hashing some data and then continue to
3658
hash different data. To avoid hashing the same data several times (which
3659
might not even be possible if the data is received from a pipe), a
3660
snapshot of the current hash context can be taken and turned into a new
3661
context:
3662
3663
@deftypefun gcry_error_t gcry_md_copy (gcry_md_hd_t *@var{handle_dst}, gcry_md_hd_t @var{handle_src})
3664
3665
Create a new digest object as an exact copy of the object described by
3666
handle @var{handle_src} and store it in @var{handle_dst}. The context
3667
is not reset and you can continue to hash data using this context and
3668
independently using the original context.
3669
@end deftypefun
3670
3671
3672
Now that we have prepared everything to calculate hashes, it is time to
3673
see how it is actually done. There are two ways for this, one to
3674
update the hash with a block of memory and one macro to update the hash
3675
by just one character. Both methods can be used on the same hash context.
3676
3677
@deftypefun void gcry_md_write (gcry_md_hd_t @var{h}, const void *@var{buffer}, size_t @var{length})
3678
3679
Pass @var{length} bytes of the data in @var{buffer} to the digest object
3680
with handle @var{h} to update the digest values. This
3681
function should be used for large blocks of data.
3682
@end deftypefun
3683
3684
@deftypefun void gcry_md_putc (gcry_md_hd_t @var{h}, int @var{c})
3685
3686
Pass the byte in @var{c} to the digest object with handle @var{h} to
3687
update the digest value. This is an efficient function, implemented as
3688
a macro to buffer the data before an actual update.
3689
@end deftypefun
3690
3691
The semantics of the hash functions do not provide for reading out intermediate
3692
message digests because the calculation must be finalized first. This
3693
finalization may for example include the number of bytes hashed in the
3694
message digest or some padding.
3695
3696
@deftypefun void gcry_md_final (gcry_md_hd_t @var{h})
3697
3698
Finalize the message digest calculation. This is not really needed
3699
because @code{gcry_md_read} does this implicitly. After this has been
3700
done no further updates (by means of @code{gcry_md_write} or
3701
@code{gcry_md_putc} are allowed. Only the first call to this function
3702
has an effect. It is implemented as a macro.
3703
@end deftypefun
3704
3705
The way to read out the calculated message digest is by using the
3706
function:
3707
3708
@deftypefun {unsigned char *} gcry_md_read (gcry_md_hd_t @var{h}, int @var{algo})
3709
3710
@code{gcry_md_read} returns the message digest after finalizing the
3711
calculation. This function may be used as often as required but it will
3712
always return the same value for one handle. The returned message digest
3713
is allocated within the message context and therefore valid until the
3714
handle is released or reseted (using @code{gcry_md_close} or
3715
@code{gcry_md_reset}. @var{algo} may be given as 0 to return the only
3716
enabled message digest or it may specify one of the enabled algorithms.
3717
The function does return @code{NULL} if the requested algorithm has not
3718
been enabled.
3719
@end deftypefun
3720
3721
Because it is often necessary to get the message digest of one block of
3722
memory, a fast convenience function is available for this task:
3723
3724
@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
3725
3726
@code{gcry_md_hash_buffer} is a shortcut function to calculate a message
3727
digest of a buffer. This function does not require a context and
3728
immediately returns the message digest of the @var{length} bytes at
3729
@var{buffer}. @var{digest} must be allocated by the caller, large
3730
enough to hold the message digest yielded by the the specified algorithm
3731
@var{algo}. This required size may be obtained by using the function
3732
@code{gcry_md_get_algo_dlen}.
3733
3734
Note that this function will abort the process if an unavailable
3735
algorithm is used.
3736
@end deftypefun
3737
3738
@c ***********************************
3739
@c ***** MD info functions ***********
3740
@c ***********************************
3741
3742
Hash algorithms are identified by internal algorithm numbers (see
3743
@code{gcry_md_open} for a list). However, in most applications they are
3744
used by names, so two functions are available to map between string
3745
representations and hash algorithm identifiers.
3746
3747
@deftypefun {const char *} gcry_md_algo_name (int @var{algo})
3748
3749
Map the digest algorithm id @var{algo} to a string representation of the
3750
algorithm name. For unknown algorithms this function returns the
3751
string @code{"?"}. This function should not be used to test for the
3752
availability of an algorithm.
3753
@end deftypefun
3754
3755
@deftypefun int gcry_md_map_name (const char *@var{name})
3756
3757
Map the algorithm with @var{name} to a digest algorithm identifier.
3758
Returns 0 if the algorithm name is not known. Names representing
3759
@acronym{ASN.1} object identifiers are recognized if the @acronym{IETF}
3760
dotted format is used and the OID is prefixed with either "@code{oid.}"
3761
or "@code{OID.}". For a list of supported OIDs, see the source code at
3762
@file{cipher/md.c}. This function should not be used to test for the
3763
availability of an algorithm.
3764
@end deftypefun
3765
3766
@deftypefun gcry_error_t gcry_md_get_asnoid (int @var{algo}, void *@var{buffer}, size_t *@var{length})
3767
3768
Return an DER encoded ASN.1 OID for the algorithm @var{algo} in the
3769
user allocated @var{buffer}. @var{length} must point to variable with
3770
the available size of @var{buffer} and receives after return the
3771
actual size of the returned OID. The returned error code may be
3772
@code{GPG_ERR_TOO_SHORT} if the provided buffer is to short to receive
3773
the OID; it is possible to call the function with @code{NULL} for
3774
@var{buffer} to have it only return the required size. The function
3775
returns 0 on success.
3776
3777
@end deftypefun
3778
3779
3780
To test whether an algorithm is actually available for use, the
3781
following macro should be used:
3782
3783
@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
3784
3785
The macro returns 0 if the algorithm @var{algo} is available for use.
3786
@end deftypefun
3787
3788
If the length of a message digest is not known, it can be retrieved
3789
using the following function:
3790
3791
@deftypefun {unsigned int} gcry_md_get_algo_dlen (int @var{algo})
3792
3793
Retrieve the length in bytes of the digest yielded by algorithm
3794
@var{algo}. This is often used prior to @code{gcry_md_read} to allocate
3795
sufficient memory for the digest.
3796
@end deftypefun
3797
3798
3799
In some situations it might be hard to remember the algorithm used for
3800
the ongoing hashing. The following function might be used to get that
3801
information:
3802
3803
@deftypefun int gcry_md_get_algo (gcry_md_hd_t @var{h})
3804
3805
Retrieve the algorithm used with the handle @var{h}. Note that this
3806
does not work reliable if more than one algorithm is enabled in @var{h}.
3807
@end deftypefun
3808
3809
The following macro might also be useful:
3810
3811
@deftypefun int gcry_md_is_secure (gcry_md_hd_t @var{h})
3812
3813
This function returns true when the digest object @var{h} is allocated
3814
in "secure memory"; i.e. @var{h} was created with the
3815
@code{GCRY_MD_FLAG_SECURE}.
3816
@end deftypefun
3817
3818
@deftypefun int gcry_md_is_enabled (gcry_md_hd_t @var{h}, int @var{algo})
3819
3820
This function returns true when the algorithm @var{algo} has been
3821
enabled for the digest object @var{h}.
3822
@end deftypefun
3823
3824
3825
3826
Tracking bugs related to hashing is often a cumbersome task which
3827
requires to add a lot of printf statements into the code.
3828
Libgcrypt provides an easy way to avoid this. The actual data
3829
hashed can be written to files on request.
3830
3831
@deftypefun void gcry_md_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
3832
3833
Enable debugging for the digest object with handle @var{h}. This
3834
creates create files named @file{dbgmd-<n>.<string>} while doing the
3835
actual hashing. @var{suffix} is the string part in the filename. The
3836
number is a counter incremented for each new hashing. The data in the
3837
file is the raw data as passed to @code{gcry_md_write} or
3838
@code{gcry_md_putc}. If @code{NULL} is used for @var{suffix}, the
3839
debugging is stopped and the file closed. This is only rarely required
3840
because @code{gcry_md_close} implicitly stops debugging.
3841
@end deftypefun
3842
3843
3844
The following two deprecated macros are used for debugging by old code.
3845
They shopuld be replaced by @code{gcry_md_debug}.
3846
3847
@deftypefun void gcry_md_start_debug (gcry_md_hd_t @var{h}, const char *@var{suffix})
3848
3849
Enable debugging for the digest object with handle @var{h}. This
3850
creates create files named @file{dbgmd-<n>.<string>} while doing the
3851
actual hashing. @var{suffix} is the string part in the filename. The
3852
number is a counter incremented for each new hashing. The data in the
3853
file is the raw data as passed to @code{gcry_md_write} or
3854
@code{gcry_md_putc}.
3855
@end deftypefun
3856
3857
3858
@deftypefun void gcry_md_stop_debug (gcry_md_hd_t @var{h}, int @var{reserved})
3859
3860
Stop debugging on handle @var{h}. @var{reserved} should be specified as
3861
0. This function is usually not required because @code{gcry_md_close}
3862
does implicitly stop debugging.
3863
@end deftypefun
3864
3865
3866
@c **********************************************************
3551
3867
@c ******************* Random *****************************
3552
3868
@c **********************************************************
3553
3869
@node Random Numbers
3563
3879
3564
3880
@acronym{Libgcypt} offers random numbers of different quality levels:
3565
3881
3566
@deftp {Data type} enum gcry_random_level
3567
The constants for the random quality levels are of this type.
3882
@deftp {Data type} gcry_random_level_t
3883
The constants for the random quality levels are of this enum type.
3568
3884
@end deftp
3569
3885
3570
3886
@table @code
3571
3887
@item GCRY_WEAK_RANDOM
3572
This should not anymore be used. It has recently been changed to an
3573
alias of GCRY_STRONG_RANDOM. Use @code{gcry_create_nonce} instead.
3888
For all functions, except for @code{gcry_mpi_randomize}, this level maps
3889
to GCRY_STRONG_RANDOM. If you do not want this, consider using
3890
@code{gcry_create_nonce}.
3574
3891
@item GCRY_STRONG_RANDOM
3575
Use this level for e.g. session keys and similar purposes.
3892
Use this level for session keys and similar purposes.
3576
3893
@item GCRY_VERY_STRONG_RANDOM
3577
Use this level for e.g. key material.
3894
Use this level for long term key material.
3578
3895
@end table
3579
3896
3580
3897
@node Retrieving random numbers
3586
3903
as defined by @var{level}.
3587
3904
@end deftypefun
3588
3905
3589
@deftypefun void * gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
3906
@deftypefun {void *} gcry_random_bytes (size_t @var{nbytes}, enum gcry_random_level @var{level})
3590
3907
3591
Allocate a memory block consisting of @var{nbytes} fresh random bytes
3592
using a random quality as defined by @var{level}.
3908
Convenience function to allocate a memory block consisting of
3909
@var{nbytes} fresh random bytes using a random quality as defined by
3910
@var{level}.
3593
3911
@end deftypefun
3594
3912
3595
@deftypefun void * gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
3913
@deftypefun {void *} gcry_random_bytes_secure (size_t @var{nbytes}, enum gcry_random_level @var{level})
3596
3914
3597
Allocate a memory block consisting of @var{nbytes} fresh random bytes
3598
using a random quality as defined by @var{level}. This function
3599
differs from @code{gcry_random_bytes} in that the returned buffer is
3600
allocated in a ``secure'' area of the memory.
3915
Convenience function to allocate a memory block consisting of
3916
@var{nbytes} fresh random bytes using a random quality as defined by
3917
@var{level}. This function differs from @code{gcry_random_bytes} in
3918
that the returned buffer is allocated in a ``secure'' area of the
3919
memory.
3601
3920
@end deftypefun
3602
3921
3603
3922
@deftypefun void gcry_create_nonce (unsigned char *@var{buffer}, size_t @var{length})
3844
4163
@end example
3845
4164
@end deftypefun
3846
4165
3847
@deftypefun char *gcry_sexp_nth_string (@w{gcry_sexp_t @var{list}}, @w{int @var{number}})
4166
@deftypefun {char *} gcry_sexp_nth_string (@w{gcry_sexp_t @var{list}}, @w{int @var{number}})
3848
4167
3849
4168
This function is used to get and convert data from a @var{list}. The
3850
4169
data is assumed to be a Nul terminated string. The caller must
3883
4202
Public key cryptography is based on mathematics with large numbers. To
3884
4203
implement the public key functions, a library for handling these large
3885
4204
numbers is required. Because of the general usefulness of such a
3886
library, its interface is exposed by Libgcrypt. The implementation is
3887
based on an old release of GNU Multi-Precision Library (GMP) but in the
3888
meantime heavily modified and stripped down to what is required for
3889
cryptography. For a lot of CPUs, high performance assembler
3890
implementations of some very low level functions are used to gain much
3891
better performance than with the standard C implementation.
3892
3893
@noindent
4205
library, its interface is exposed by Libgcrypt.
3894
4206
In the context of Libgcrypt and in most other applications, these large
3895
4207
numbers are called MPIs (multi-precision-integers).
3896
4208
3897
4209
@node Data types
3898
4210
@section Data types
3899
4211
3900
@deftp {Data type} gcry_mpi_t
3901
The @code{gcry_mpi_t} type represents an object to hold an MPI.
4212
@deftp {Data type} {gcry_mpi_t}
4213
This type represents an object to hold an MPI.
3902
4214
@end deftp
3903
4215
3904
4216
@node Basic functions
4132
4444
4133
4445
@deftypefun int gcry_mpi_cmp (@w{const gcry_mpi_t @var{u}}, @w{const gcry_mpi_t @var{v}})
4134
4446
4135
Compare the big integer number @var{u} and @var{v} returning 0 for
4136
equality, a positive value for @var{u} > @var{v} and a negative for
4137
@var{u} < @var{v}.
4138
@end deftypefun
4139
4140
@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
4141
4142
Compare the big integer number @var{u} with the unsigned integer @var{v}
4447
Compare the multi-precision-integers number @var{u} and @var{v}
4143
4448
returning 0 for equality, a positive value for @var{u} > @var{v} and a
4144
4449
negative for @var{u} < @var{v}.
4145
4450
@end deftypefun
4146
4451
4452
@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
4453
4454
Compare the multi-precision-integers number @var{u} with the unsigned
4455
integer @var{v} returning 0 for equality, a positive value for @var{u} >
4456
@var{v} and a negative for @var{u} < @var{v}.
4457
@end deftypefun
4458
4147
4459
4148
4460
@node Bit manipulations
4149
4461
@section Bit manipulations
4188
4500
result in @var{x}.
4189
4501
@end deftypefun
4190
4502
4503
@deftypefun void gcry_mpi_lshift (@w{gcry_mpi_t @var{x}}, @w{gcry_mpi_t @var{a}}, @w{unsigned int @var{n}})
4504
4505
Shift the value of @var{a} by @var{n} bits to the left and store the
4506
result in @var{x}.
4507
@end deftypefun
4508
4191
4509
@node Miscellaneous
4192
4510
@section Miscellaneous
4193
4511
4221
4539
4222
4540
@deftypefun void gcry_mpi_clear_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
4223
4541
4224
Clear @var{flag} for the big integer @var{a}. Note that this function is
4225
currently useless as no flags are allowed.
4542
Clear @var{flag} for the multi-precision-integers @var{a}. Note that
4543
this function is currently useless as no flags are allowed.
4226
4544
@end deftypefun
4227
4545
4228
4546
@deftypefun int gcry_mpi_get_flag (@w{gcry_mpi_t @var{a}}, @w{enum gcry_mpi_flag @var{flag}})
4232
4550
4233
4551
@deftypefun void gcry_mpi_randomize (@w{gcry_mpi_t @var{w}}, @w{unsigned int @var{nbits}}, @w{enum gcry_random_level @var{level}})
4234
4552
4235
Set the big integer @var{w} to a random value of @var{nbits}, using
4236
random data quality of level @var{level}. In case @var{nbits} is not
4237
a multiple of a byte, @var{nbits} is rounded up to the next byte
4238
boundary.
4553
Set the multi-precision-integers @var{w} to a random value of
4554
@var{nbits}, using random data quality of level @var{level}. In case
4555
@var{nbits} is not a multiple of a byte, @var{nbits} is rounded up to
4556
the next byte boundary. When using a @var{level} of
4557
@code{GCRY_WEAK_RANDOM} this function makes use of
4558
@code{gcry_create_nonce}.
4239
4559
@end deftypefun
4240
4560
4241
4561
@c **********************************************************
4262
4582
might be used to influence the prime number generation process.
4263
4583
@end deftypefun
4264
4584
4265
@deftypefun gcry_prime_group_generator (gcry_mpi_t *@var{r_g},
4266
gcry_mpi_t @var{prime}, gcry_mpi_t *@var{factors}, gcry_mpi_t @var{start_g})
4585
@deftypefun gcry_error_t gcry_prime_group_generator (gcry_mpi_t *@var{r_g}, gcry_mpi_t @var{prime}, gcry_mpi_t *@var{factors}, gcry_mpi_t @var{start_g})
4267
4586
4268
4587
Find a generator for @var{prime} where the factorization of
4269
4588
(@var{prime}-1) is in the @code{NULL} terminated array @var{factors}.
4300
4619
@node Memory allocation
4301
4620
@section Memory allocation
4302
4621
4303
@deftypefun void *gcry_malloc (size_t @var{n})
4622
@deftypefun {void *} gcry_malloc (size_t @var{n})
4304
4623
4305
4624
This function tries to allocate @var{n} bytes of memory. On success
4306
4625
it returns a pointer to the memory area, in an out-of-core condition,
4307
4626
it returns NULL.
4308
4627
@end deftypefun
4309
4628
4310
@deftypefun void *gcry_malloc_secure (size_t @var{n})
4629
@deftypefun {void *} gcry_malloc_secure (size_t @var{n})
4311
4630
Like @code{gcry_malloc}, but uses secure memory.
4312
4631
@end deftypefun
4313
4632
4314
@deftypefun void *gcry_calloc (size_t @var{n})
4633
@deftypefun {void *} gcry_calloc (size_t @var{n})
4315
4634
4316
4635
This function tries to allocate @var{n} bytes of cleared memory
4317
4636
(i.e. memory that is initialized with zero bytes). On success it
4319
4638
returns NULL.
4320
4639
@end deftypefun
4321
4640
4322
@deftypefun void *gcry_calloc_secure (size_t @var{n})
4641
@deftypefun {void *} gcry_calloc_secure (size_t @var{n})
4323
4642
Like @code{gcry_calloc}, but uses secure memory.
4324
4643
@end deftypefun
4325
4644
4326
@deftypefun void *gcry_realloc (void *@var{p}, size_t @var{n})
4645
@deftypefun {void *} gcry_realloc (void *@var{p}, size_t @var{n})
4327
4646
4328
4647
This function tries to resize the memory area pointed to by @var{p} to
4329
4648
@var{n} bytes. On success it returns a pointer to the new memory
4337
4656
@end deftypefun
4338
4657
4339
4658
@c **********************************************************
4659
@c ***************** Architecure Overview *****************
4660
@c **********************************************************
4661
@node Architecture
4662
@chapter Architecture
4663
4664
This chapter describes the internal architecture of Libgcrypt.
4665
4666
Libgcrypt is a function library written in ISO C-90. Any compliant
4667
compiler should be able to build Libgcrypt as long as the target is
4668
either a POSIX platform or compatible to the API used by Windows NT.
4669
Provisions have been take so that the library can be directly used from
4670
C++ applications; however building with a C++ compiler is not supported.
4671
4672
Building Libgcrypt is done by using the common @code{./configure && make}
4673
approach. The configure command is included in the source distribution
4674
and as a portable shell script it works on any Unix-alike system. The
4675
result of running the configure script are a C header file
4676
(@file{config.h}), customized Makefiles, the setup of symbolic links and
4677
a few other things. After that the make tool builds and optionally
4678
installs the library and the documentation. See the files
4679
@file{INSTALL} and @file{README} in the source distribution on how to do
4680
this.
4681
4682
Libgcrypt is developed using a Subversion@footnote{A version control
4683
system available for many platforms} repository. Although all released
4684
versions are tagged in this repository, they should not be used to build
4685
production versions of Libgcrypt. Instead released tarballs should be
4686
used. These tarballs are available from several places with the master
4687
copy at @indicateurl{ftp://ftp.gnupg.org/gcrypt/libgcrypt/}.
4688
Announcements of new releases are posted to the
4689
@indicateurl{gnupg-announce@@gnupg.org} mailing list@footnote{See
4690
@url{http://www.gnupg.org/documentation/mailing-lists.en.html} for
4691
details.}.
4692
4693
4694
@float Figure,fig:subsystems
4695
@caption{Libgcrypt subsystems}
4696
@center @image{libgcrypt-modules, 150mm,,Libgcrypt subsystems}
4697
@end float
4698
4699
Libgcrypt consists of several subsystems (@pxref{fig:subsystems}) and
4700
all these subsystems provide a public API; this includes the helper
4701
subsystems like the one for S-expressions. The API style depends on the
4702
subsystem; in general an open-use-close approach is implemented. The
4703
open returns a handle to a context used for all further operations on
4704
this handle, several functions may then be used on this handle and a
4705
final close function releases all resources associated with the handle.
4706
4707
@menu
4708
* Public-Key Subsystem Architecture:: About public keys.
4709
* Symmetric Encryption Subsystem Architecture:: About standard ciphers.
4710
* Hashing and MACing Subsystem Architecture:: About hashing.
4711
* Multi-Precision-Integer Subsystem Architecture:: About big integers.
4712
* Prime-Number-Generator Subsystem Architecture:: About prime numbers.
4713
* Random-Number Subsystem Architecture:: About random stuff.
4714
@c * Helper Subsystems Architecture:: About other stuff.
4715
@end menu
4716
4717
4718
4719
@node Public-Key Subsystem Architecture
4720
@section Public-Key Architecture
4721
4722
Libgcrypt implements two interfaces for public key cryptography: The
4723
standard interface is PK interface using functions in the
4724
@code{gcry_pk_} name space. The AC interface in an alternative one
4725
which is now deprecated and will not be further described. The AC
4726
interface is also disabled in FIPS mode.
4727
4728
Because public key cryptography is almost always used to process small
4729
amounts of data (hash values or session keys), the interface is not
4730
implemented using the open-use-close paradigm, but with single
4731
self-contained functions. Due to the wide variety of parameters
4732
required by different algorithms S-expressions, as flexible way to
4733
convey these parameters, are used. There is a set of helper functions
4734
to work with these S-expressions.
4735
@c see @xref{S-expression Subsystem Architecture}.
4736
4737
Aside of functions to register new algorithms, map algorithms names to
4738
algorithms identifiers and to lookup properties of a key, the
4739
following main functions are available:
4740
4741
@table @code
4742
4743
@item gcry_pk_encrypt
4744
Encrypt data using a public key.
4745
4746
@item gcry_pk_decrypt
4747
Decrypt data using a private key.
4748
4749
@item gcry_pk_sign
4750
Sign data using a private key.
4751
4752
@item gcry_pk_verify
4753
Verify that a signature matches the data.
4754
4755
@item gcry_pk_testkey
4756
Perform a consistency over a public or private key.
4757
4758
@item gcry_pk_genkey
4759
Create a new public/private key pair.
4760
4761
@end table
4762
4763
With the help of the module registration system all these functions
4764
lookup the module implementing the algorithm and pass the actual work
4765
to that module. The parsing of the S-expression input and the
4766
construction of S-expression for the return values is done by the high
4767
level code (@file{cipher/pubkey.c}). Thus the internal interface
4768
between the algorithm modules and the high level functions passes data
4769
in a custom format. The interface to the modules is published
4770
(@file{gcrypt-modules.h}) so that it can used to register external
4771
implementations of algorithms with Libgcrypt. However, for some
4772
algorithms this module interface is to limited and thus for the
4773
internal modules an extra interface is sometimes used to convey more
4774
information.
4775
4776
By default Libgcrypt uses a blinding technique for RSA decryption to
4777
mitigate real world timing attacks over a network: Instead of using
4778
the RSA decryption directly, a blinded value @math{y = x r^{e} \bmod n}
4779
is decrypted and the unblinded value @math{x' = y' r^{-1} \bmod n}
4780
returned. The blinding value @math{r} is a random value with the size
4781
of the modulus @math{n} and generated with @code{GCRY_WEAK_RANDOM}
4782
random level.
4783
4784
@cindex X9.31
4785
@cindex FIPS 186
4786
The algorithm used for RSA and DSA key generation depends on whether
4787
Libgcrypt is operated in standard or in FIPS mode. In standard mode
4788
an algorithm based on the Lim-Lee prime number generator is used. In
4789
FIPS mode RSA keys are generated as specified in ANSI X9.31 (1998) and
4790
DSA keys as specified in FIPS 186-2.
4791
4792
4793
4794
@node Symmetric Encryption Subsystem Architecture
4795
@section Symmetric Encryption Subsystem Architecture
4796
4797
The interface to work with symmetric encryption algorithms is made up
4798
of functions from the @code{gcry_cipher_} name space. The
4799
implementation follows the open-use-close paradigm and uses registered
4800
algorithm modules for the actual work. Unless a module implements
4801
optimized cipher mode implementations, the high level code
4802
(@file{cipher/cipher.c}) implements the modes and calls the core
4803
algorithm functions to process each block.
4804
4805
The most important functions are:
4806
4807
@table @code
4808
4809
@item gcry_cipher_open
4810
Create a new instance to encrypt or decrypt using a specified
4811
algorithm and mode.
4812
4813
@item gcry_cipher_close
4814
Release an instance.
4815
4816
@item gcry_cipher_setkey
4817
Set a key to be used for encryption or decryption.
4818
4819
@item gcry_cipher_setiv
4820
Set an initialization vector to be used for encryption or decryption.
4821
4822
@item gcry_cipher_encrypt
4823
@itemx gcry_cipher_decrypt
4824
Encrypt or decrypt data. These functions may be called with arbitrary
4825
amounts of data and as often as needed to encrypt or decrypt all data.
4826
4827
@end table
4828
4829
There are also functions to query properties of algorithms or context,
4830
like block length, key length, map names or to enable features like
4831
padding methods.
4832
4833
4834
4835
@node Hashing and MACing Subsystem Architecture
4836
@section Hashing and MACing Subsystem Architecture
4837
4838
The interface to work with message digests and CRC algorithms is made
4839
up of functions from the @code{gcry_md_} name space. The
4840
implementation follows the open-use-close paradigm and uses registered
4841
algorithm modules for the actual work. Although CRC algorithms are
4842
not considered cryptographic hash algorithms, they share enough
4843
properties so that it makes sense to handle them in the same way.
4844
It is possible to use several algorithms at once with one context and
4845
thus compute them all on the same data.
4846
4847
The most important functions are:
4848
4849
@table @code
4850
@item gcry_md_open
4851
Create a new message digest instance and optionally enable one
4852
algorithm. A flag may be used to turn the message digest algorithm
4853
into a HMAC algorithm.
4854
4855
@item gcry_md_enable
4856
Enable an additional algorithm for the instance.
4857
4858
@item gcry_md_setkey
4859
Set the key for the MAC.
4860
4861
@item gcry_md_write
4862
Pass more data for computing the message digest to an instance.
4863
4864
@item gcry_md_putc
4865
Buffered version of @code{gcry_md_write} implemented as a macro.
4866
4867
@item gcry_md_read
4868
Finalize the computation of the message digest or HMAC and return the
4869
result.
4870
4871
@item gcry_md_close
4872
Release an instance
4873
4874
@item gcry_md_hash_buffer
4875
Convenience function to directly compute a message digest over a
4876
memory buffer without the need to create an instance first.
4877
4878
@end table
4879
4880
There are also functions to query properties of algorithms or the
4881
instance, like enabled algorithms, digest length, map algorithm names.
4882
it is also possible to reset an instance or to copy the current state
4883
of an instance at any time. Debug functions to write the hashed data
4884
to files are available as well.
4885
4886
4887
4888
@node Multi-Precision-Integer Subsystem Architecture
4889
@section Multi-Precision-Integer Subsystem Architecture
4890
4891
The implementation of Libgcrypt's big integer computation code is
4892
based on an old release of GNU Multi-Precision Library (GMP). The
4893
decision not to use the GMP library directly was due to stalled
4894
development at that time and due to security requirements which could
4895
not be provided by the code in GMP. As GMP does, Libgcrypt provides
4896
high performance assembler implementations of low level code for
4897
several CPUS to gain much better performance than with a generic C
4898
implementation.
4899
4900
@noindent
4901
Major features of Libgcrypt's multi-precision-integer code compared to
4902
GMP are:
4903
4904
@itemize
4905
@item
4906
Avoidance of stack based allocations to allow protection against
4907
swapping out of sensitive data and for easy zeroing of sensitive
4908
intermediate results.
4909
4910
@item
4911
Optional use of secure memory and tracking of its use so that results
4912
are also put into secure memory.
4913
4914
@item
4915
MPIs are identified by a handle (implemented as a pointer) to give
4916
better control over allocations and to augment them with extra
4917
properties like opaque data.
4918
4919
@item
4920
Removal of unnecessary code to reduce complexity.
4921
4922
@item
4923
Functions specialized for public key cryptography.
4924
4925
@end itemize
4926
4927
4928
4929
@node Prime-Number-Generator Subsystem Architecture
4930
@section Prime-Number-Generator Subsystem Architecture
4931
4932
Libgcrypt provides an interface to its prime number generator. These
4933
functions make use of the internal prime number generator which is
4934
required for the generation for public key key pairs. The plain prime
4935
checking function is exported as well.
4936
4937
The generation of random prime numbers is based on the Lim and Lee
4938
algorithm to create practically save primes.@footnote{Chae Hoon Lim
4939
and Pil Joong Lee. A key recovery attack on discrete log-based shemes
4940
using a prime order subgroup. In Burton S. Kaliski Jr., editor,
4941
Advances in Cryptology: Crypto '97, pages 249-263, Berlin /
4942
Heidelberg / New York, 1997. Springer-Verlag. Described on page 260.}
4943
This algorithm creates a pool of smaller primes, select a few of them
4944
to create candidate primes of the form @math{2 * p_0 * p_1 * ... * p_n
4945
+ 1}, tests the candidate for primality and permutates the pool until
4946
a prime has been found. It is possible to clamp one of the small
4947
primes to a certain size to help DSA style algorithms. Because most
4948
of the small primes in the pool are not used for the resulting prime
4949
number, they are saved for later use (see @code{save_pool_prime} and
4950
@code{get_pool_prime} in @file{cipher/primegen.c}). The prime
4951
generator optionally supports the finding of an appropriate generator.
4952
4953
@noindent
4954
The primality test works in three steps:
4955
4956
@enumerate
4957
@item
4958
The standard sieve algorithm using the primes up to 4999 is used as a
4959
quick first check.
4960
4961
@item
4962
A Fermat test filters out almost all non-primes.
4963
4964
@item
4965
A 5 round Rabin-Miller test is finally used. The first round uses a
4966
witness of 2, whereas the next rounds use a random witness.
4967
4968
@end enumerate
4969
4970
To support the generation of RSA and DSA keys in FIPS mode according
4971
to X9.31 and FIPS 186-2, Libgcrypt implements two additional prime
4972
generation functions: @code{_gcry_derive_x931_prime} and
4973
@code{_gcry_generate_fips186_2_prime}. These functions are internal
4974
and not available through the public API.
4975
4976
4977
4978
@node Random-Number Subsystem Architecture
4979
@section Random-Number Subsystem Architecture
4980
4981
Libgcrypt provides 3 levels or random quality: The level
4982
@code{GCRY_VERY_STRONG_RANDOM} usually used for key generation, the
4983
level @code{GCRY_STRONG_RANDOM} for all other strong random
4984
requirements and the function @code{gcry_create_nonce} which is used
4985
for weaker usages like nonces. There is also a level
4986
@code{GCRY_WEAK_RANDOM} which in general maps to
4987
@code{GCRY_STRONG_RANDOM} except when used with the function
4988
@code{gcry_mpi_randomize}, where it randomizes an
4989
multi-precision-integer using the @code{gcry_create_nonce} function.
4990
4991
@noindent
4992
There are two distinct random generators available:
4993
4994
@itemize
4995
@item
4996
The Continuously Seeded Pseudo Random Number Generator (CSPRNG), which
4997
is based on the classic GnuPG derived big pool implementation.
4998
Implemented in @code{random/random-csprng.c} and used by default.
4999
@item
5000
A FIPS approved ANSI X9.31 PRNG using AES with a 128 bit key. Implemented in
5001
@code{random/random-fips.c} and used if Libgcrypt is in FIPS mode.
5002
@end itemize
5003
5004
@noindent
5005
Both generators make use of so-called entropy gathering modules:
5006
5007
@table @asis
5008
@item rndlinux
5009
Uses the operating system provided
5010
@file{/dev/random} and @file{/dev/urandom} devices.
5011
5012
@item rndunix
5013
Runs several operating system commands to collect entropy from sources
5014
like virtual machine and process statistics. It is a kind of
5015
poor-man's @code{/dev/random} implementation. It is not available in
5016
FIPS mode.
5017
5018
@item rndegd
5019
Uses the operating system provided Entropy Gathering Daemon (EGD).
5020
The EGD basically uses the same algorithms as rndunix does. However
5021
as a system daemon it keeps on running and thus can serve several
5022
processes requiring entropy input and does not waste collected entropy
5023
if the application does not need all the collected entropy. It is not
5024
available in FIPS mode.
5025
5026
@item rndw32
5027
Targeted for the Microsoft Windows OS. It uses certain properties of
5028
that system and is the only gathering module available for that OS.
5029
5030
@item rndhw
5031
Extra module to collect additional entropy by utilizing a hardware
5032
random number generator. As of now the only supported hardware RNG is
5033
the Padlock engine of VIA (Centaur) CPUs. It is not available in FIPS
5034
mode.
5035
5036
@end table
5037
5038
5039
@menu
5040
* CSPRNG Description:: Description of the CSPRNG.
5041
* FIPS PRNG Description:: Description of the FIPS X9.31 PRNG.
5042
@end menu
5043
5044
5045
@node CSPRNG Description
5046
@subsection Description of the CSPRNG
5047
5048
This random number generator is loosely modelled after the one
5049
described in Peter Gutmann's paper: "Software Generation of
5050
Practically Strong Random Numbers".@footnote{Also described in chapter
5051
6 of his book "Cryptographic Security Architecture", New York, 2004,
5052
ISBN 0-387-95387-6.}
5053
5054
A pool of 600 bytes is used and mixed using the core RIPE-MD160 hash
5055
transform function. Several extra features are used to make the
5056
robust against a wide variety of attacks and to protect against
5057
failures of subsystems. The state of the generator may be saved to a
5058
file and initially seed form a file.
5059
5060
Depending on how Libgcrypt was build the generator is able to select
5061
the best working entropy gathering module. It makes use of the slow
5062
and fast collection methods and requires the pool to initially seeded
5063
form the slow gatherer or a seed file. An entropy estimation is used
5064
to mix in enough data from the gather modules before returning the
5065
actual random output. Process fork detection and protection is
5066
implemented.
5067
5068
@c FIXME: The design and implementaion needs a more verbose description.
5069
5070
The implementation of the nonce generator (for
5071
@code{gcry_create_nonce}) is a straightforward repeated hash design: A
5072
28 byte buffer is initially seeded with the PID and the time in
5073
seconds in the first 20 bytes and with 8 bytes of random taken from
5074
the @code{GCRY_STRONG_RANDOM} generator. Random numbers are then
5075
created by hashing all the 28 bytes with SHA-1 and saving that again
5076
in the first 20 bytes. The hash is also returned as result.
5077
5078
5079
@node FIPS PRNG Description
5080
@subsection Description of the FIPS X9.31 PRNG
5081
5082
The core of this deterministic random number generator is implemented
5083
according to the document ``NIST-Recommended Random Number Generator
5084
Based on ANSI X9.31 Appendix A.2.4 Using the 3-Key Triple DES and AES
5085
Algorithms'', dated 2005-01-31. This implementation uses the AES
5086
variant.
5087
5088
The generator is based on contexts to utilize the same core functions
5089
for all random levels as required by the high-level interface. All
5090
random generators return their data in 128 bit blocks. If the caller
5091
requests less bits, the extra bits are not used. The key for each
5092
generator is only set once at the first time a generator context is
5093
used. The seed value is set along with the key and again after 1000
5094
output blocks.
5095
5096
On Unix like systems the @code{GCRY_VERY_STRONG_RANDOM} and
5097
@code{GCRY_STRONG_RANDOM} generators are keyed and seeded using the
5098
rndlinux module with the @file{/dev/radnom} device. Thus these
5099
generators may block until the OS kernel has collected enough entropy.
5100
When used with Microsoft Windows the rndw32 module is used instead.
5101
5102
The generator used for @code{gcry_create_nonce} is keyed and seeded
5103
from the @code{GCRY_STRONG_RANDOM} generator. Thus is may also block
5104
if the @code{GCRY_STRONG_RANDOM} generator has not yet been used
5105
before and thus gets initialized on the first use by
5106
@code{gcry_create_nonce}. This special treatment is justified by the
5107
weaker requirements for a nonce generator and to save precious kernel
5108
entropy for use by the ``real'' random generators.
5109
5110
A self-test facility uses a separate context to check the
5111
functionality of the core X9.31 functions using a known answers test.
5112
During runtime each output block is compared to the previous one to
5113
detect a stucked generator.
5114
5115
The DT value for the generator is made up of the current time down to
5116
microseconds (if available) and a free running 64 bit counter. When
5117
used with the test context the DT value is taken from the context and
5118
incremented on each use.
5119
5120
5121
5122
@c @node Helper Subsystems Architecture
5123
@c @section Helper Subsystems Architecture
5124
@c
5125
@c There are a few smaller subsystems which are mainly used internally by
5126
@c Libgcrypt but also available to applications.
5127
@c
5128
@c @menu
5129
@c * S-expression Subsystem Architecture:: Details about the S-expression architecture.
5130
@c * Memory Subsystem Architecture:: Details about the memory allocation architecture.
5131
@c * Miscellaneous Subsystems Architecture:: Details about other subsystems.
5132
@c @end menu
5133
@c
5134
@c @node S-expression Subsystem Architecture
5135
@c @subsection S-expression Subsystem Architecture
5136
@c
5137
@c Libgcrypt provides an interface to S-expression to create and parse
5138
@c them. To use an S-expression with Libgcrypt it needs first be
5139
@c converted into the internal representation used by Libgcrypt (the type
5140
@c @code{gcry_sexp_t}). The conversion functions support a large subset
5141
@c of the S-expression specification and further fature a printf like
5142
@c function to convert a list of big integers or other binary data into
5143
@c an S-expression.
5144
@c
5145
@c Libgcrypt currently implements S-expressions using a tagged linked
5146
@c list. However this is not exposed to an application and may be
5147
@c changed in future releases to reduce overhead when already working
5148
@c with canonically encoded S-expressions. Secure memory is supported by
5149
@c this S-expressions implementation.
5150
@c
5151
@c @node Memory Subsystem Architecture
5152
@c @subsection Memory Subsystem Architecture
5153
@c
5154
@c TBD.
5155
@c
5156
@c
5157
@c @node Miscellaneous Subsystems Architecture
5158
@c @subsection Miscellaneous Subsystems Architecture
5159
@c
5160
@c TBD.
5161
@c
5162
@c
5163
5164
5165
5166
@c **********************************************************
4340
5167
@c ******************* Appendices *************************
4341
5168
@c **********************************************************
4342
5169
5170
@c ********************************************
5171
@node Self-Tests
5172
@appendix Description of the Self-Tests
5173
5174
In addition to the build time regression test suite, Libgcrypt
5175
implements self-tests to be performed at runtime. Which self-tests
5176
are actually used depends on the mode Libgcrypt is used in. In
5177
standard mode a limited set of self-tests is run at the time an
5178
algorithm is first used. Note that not all algorithms feature a
5179
self-test in standard mode. The @code{GCRYCTL_SELFTEST} control
5180
command may be used to run all implemented self-tests at any time;
5181
this will even run more tests than those run in FIPS mode.
5182
5183
If any of the self-tests fails, the library immediately returns an
5184
error code to the caller. If Libgcrypt is in FIPS mode the self-tests
5185
will be performed within the ``Self-Test'' state and any failure puts
5186
the library into the ``Error'' state.
5187
5188
@c --------------------------------
5189
@section Power-Up Tests
5190
5191
Power-up tests are only performed if Libgcrypt is in FIPS mode.
5192
5193
@subsection Symmetric Cipher Algorithm Power-Up Tests
5194
5195
The following symmetric encryption algorithm tests are run during
5196
power-up:
5197
5198
@table @asis
5199
@item 3DES
5200
To test the 3DES 3-key EDE encryption in ECB mode these tests are
5201
run:
5202
@enumerate
5203
@item
5204
A known answer test is run on a 64 bit test vector processed by 64
5205
rounds of Single-DES block encryption and decryption using a key
5206
changed with each round.
5207
@item
5208
A known answer test is run on a 64 bit test vector processed by 16
5209
rounds of 2-key and 3-key Triple-DES block encryption and decryptions
5210
using a key changed with each round.
5211
@item
5212
10 known answer tests using 3-key Triple-DES EDE encryption, comparing
5213
the ciphertext to the known value, then running a decryption and
5214
comparing it to the initial plaintext.
5215
@end enumerate
5216
(@code{cipher/des.c:selftest})
5217
5218
@item AES-128
5219
A known answer tests is run using one test vector and one test
5220
key with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_128})
5221
5222
@item AES-192
5223
A known answer tests is run using one test vector and one test
5224
key with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_192})
5225
5226
@item AES-256
5227
A known answer tests is run using one test vector and one test key
5228
with AES in ECB mode. (@code{cipher/rijndael.c:selftest_basic_256})
5229
@end table
5230
5231
@subsection Hash Algorithm Power-Up Tests
5232
5233
The following hash algorithm tests are run during power-up:
5234
5235
@table @asis
5236
@item SHA-1
5237
A known answer test using the string @code{"abc"} is run.
5238
(@code{cipher/@/sha1.c:@/selftests_sha1})
5239
@item SHA-224
5240
A known answer test using the string @code{"abc"} is run.
5241
(@code{cipher/@/sha256.c:@/selftests_sha224})
5242
@item SHA-256
5243
A known answer test using the string @code{"abc"} is run.
5244
(@code{cipher/@/sha256.c:@/selftests_sha256})
5245
@item SHA-384
5246
A known answer test using the string @code{"abc"} is run.
5247
(@code{cipher/@/sha512.c:@/selftests_sha384})
5248
@item SHA-512
5249
A known answer test using the string @code{"abc"} is run.
5250
(@code{cipher/@/sha512.c:@/selftests_sha512})
5251
@end table
5252
5253
@subsection MAC Algorithm Power-Up Tests
5254
5255
The following MAC algorithm tests are run during power-up:
5256
5257
@table @asis
5258
@item HMAC SHA-1
5259
A known answer test using 9 byte of data and a 64 byte key is run.
5260
(@code{cipher/hmac-tests.c:selftests_sha1})
5261
@item HMAC SHA-224
5262
A known answer test using 28 byte of data and a 4 byte key is run.
5263
(@code{cipher/hmac-tests.c:selftests_sha224})
5264
@item HMAC SHA-256
5265
A known answer test using 28 byte of data and a 4 byte key is run.
5266
(@code{cipher/hmac-tests.c:selftests_sha256})
5267
@item HMAC SHA-384
5268
A known answer test using 28 byte of data and a 4 byte key is run.
5269
(@code{cipher/hmac-tests.c:selftests_sha384})
5270
@item HMAC SHA-512
5271
A known answer test using 28 byte of data and a 4 byte key is run.
5272
(@code{cipher/hmac-tests.c:selftests_sha512})
5273
@end table
5274
5275
@subsection Random Number Power-Up Test
5276
5277
The DRNG is tested during power-up this way:
5278
5279
@enumerate
5280
@item
5281
Requesting one block of random using the public interface to check
5282
general working and the duplicated block detection.
5283
@item
5284
3 know answer tests using pre-defined keys, seed and initial DT
5285
values. For each test 3 blocks of 16 bytes are requested and compared
5286
to the expected result. The DT value is incremented for each block.
5287
@end enumerate
5288
5289
@subsection Public Key Algorithm Power-Up Tests
5290
5291
The public key algorithms are tested during power-up:
5292
5293
@table @asis
5294
@item RSA
5295
A pre-defined 1024 bit RSA key is used and these tests are run
5296
in turn:
5297
@enumerate
5298
@item
5299
Conversion of S-expression to internal format.
5300
(@code{cipher/@/rsa.c:@/selftests_rsa})
5301
@item
5302
Private key consistency check.
5303
(@code{cipher/@/rsa.c:@/selftests_rsa})
5304
@item
5305
A pre-defined 20 byte value is signed with PKCS#1 padding for SHA-1.
5306
The result is verified using the public key against the original data
5307
and against modified data. (@code{cipher/@/rsa.c:@/selftest_sign_1024})
5308
@item
5309
A 1000 bit random value is encrypted and checked that it does not
5310
match the orginal random value. The encrtypted result is then
5311
decrypted and checked that it macthes the original random value.
5312
(@code{cipher/@/rsa.c:@/selftest_encr_1024})
5313
@end enumerate
5314
5315
@item DSA
5316
A pre-defined 1024 bit DSA key is used and these tests are run in turn:
5317
@enumerate
5318
@item
5319
Conversion of S-expression to internal format.
5320
(@code{cipher/@/dsa.c:@/selftests_dsa})
5321
@item
5322
Private key consistency check.
5323
(@code{cipher/@/dsa.c:@/selftests_dsa})
5324
@item
5325
A pre-defined 20 byte value is signed with PKCS#1 padding for
5326
SHA-1. The result is verified using the public key against the
5327
original data and against modified data.
5328
(@code{cipher/@/dsa.c:@/selftest_sign_1024})
5329
@end enumerate
5330
@end table
5331
5332
@subsection Integrity Power-Up Tests
5333
5334
The integrity of the Libgcrypt is tested during power-up but only if
5335
checking has been enabled at build time. The check works by computing
5336
a HMAC SHA-256 checksum over the file used to load Libgcrypt into
5337
memory. That checksum is compared against a checksum stored in a file
5338
of the same name but with a single dot as a prefix and a suffix of
5339
@file{.hmac}.
5340
5341
5342
@subsection Critical Functions Power-Up Tests
5343
5344
The 3DES weak key detection is tested during power-up by calling the
5345
detection function with keys taken from a table listening all weak
5346
keys. The table itself is protected using a SHA-1 hash.
5347
(@code{cipher/@/des.c:@/selftest})
5348
5349
5350
5351
@c --------------------------------
5352
@section Conditional Tests
5353
5354
The conditional tests are performed if a certain contidion is met.
5355
This may occur at any time; the library does not necessary enter the
5356
``Self-Test'' state to run these tests but will transit to the
5357
``Error'' state if a test failed.
5358
5359
@subsection Key-Pair Generation Tests
5360
5361
After an asymmetric key-pair has been generated, Libgcrypt runs a
5362
pair-wise consistency tests on the generated key. On failure the
5363
generated key is not used, an error code is returned and, if in FIPS
5364
mode, the library is put into the ``Error'' state.
5365
5366
@table @asis
5367
@item RSA
5368
The test uses a random number 64 bits less the size of the modulus as
5369
plaintext and runs an encryption and decryption operation in turn. The
5370
encrypted value is checked to not match the plaintext and the result
5371
of the decryption is checked to match the plaintext.
5372
5373
A new random number of the same size is generated, signed and verified
5374
to test the correctness of the signing operation. As a second signing
5375
test, the signature is modified by incrementing its value and then
5376
verified with the expected result that the verification fails.
5377
(@code{cipher/@/rsa.c:@/test_keys})
5378
@item DSA
5379
The test uses a random number of the size of the Q parameter to create
5380
a signature and then checks that the signature verifies. As a second
5381
signing test, the data is modified by incrementing its value and then
5382
verified against the signature with the expected result that the
5383
verification fails. (@code{cipher/@/dsa.c:@/test_keys})
5384
@end table
5385
5386
5387
@subsection Software Load Tests
5388
5389
Loading of extra modules into libgcrypt is disabled in FIPS mode and
5390
thus no tests are
5391
implemented. (@code{cipher/@/cipher.c:@/gcry_cipher_register},
5392
@code{cipher/@/md.c:@/gcry_md_register},
5393
@code{cipher/@/md.c:@/gcry_pk_register})
5394
5395
5396
@subsection Manual Key Entry Tests
5397
5398
A manual key entry feature is not implemented in Libgcrypt.
5399
5400
5401
@subsection Continuous RNG Tests
5402
5403
The continuous random number test is only used in FIPS mode. The RNG
5404
generates blocks of 128 bit size; the first block generated per
5405
context is saved in the context and another block is generated to be
5406
returned to the caller. Each block is compared against the saved
5407
block and then stored in the context. If a duplicated block is
5408
detected an error is signaled and the libray is put into the
5409
``Fatal-Error'' state.
5410
(@code{random/@/random-fips.c:@/x931_aes_driver})
5411
5412
5413
5414
@c --------------------------------
5415
@section Application Requested Tests
5416
5417
The application may requests tests at any time by means of the
5418
@code{GCRYCTL_SELFTEST} control command. Note that using these tests
5419
is not FIPS conform: Although Libgcrypt rejects all application
5420
requests for services while running self-tests, it does not ensure
5421
that no other operations of Libgcrypt are still being executed. Thus,
5422
in FIPS mode an application requesting self-tests needs to power-cycle
5423
Libgcrypt instead.
5424
5425
When self-tests are requested, Libgcrypt runs all the tests it does
5426
during power-up as well as a few extra checks as described below.
5427
5428
@subsection Symmetric Cipher Algorithm Tests
5429
5430
The following symmetric encryption algorithm tests are run in addition
5431
to the power-up tests:
5432
5433
@table @asis
5434
@item AES-128
5435
A known answer tests with test vectors taken from NIST SP800-38a and
5436
using the high level functions is run for block modes CFB and OFB.
5437
5438
@end table
5439
5440
@subsection Hash Algorithm Tests
5441
5442
The following hash algorithm tests are run in addition to the
5443
power-up tests:
5444
5445
@table @asis
5446
@item SHA-1
5447
@itemx SHA-224
5448
@itemx SHA-256
5449
@enumerate
5450
@item
5451
A known answer test using a 56 byte string is run.
5452
@item
5453
A known answer test using a string of one million letters "a" is run.
5454
@end enumerate
5455
(@code{cipher/@/sha1.c:@/selftests_sha1},
5456
@code{cipher/@/sha256.c:@/selftests_sha224},
5457
@code{cipher/@/sha256.c:@/selftests_sha256})
5458
@item SHA-384
5459
@item SHA-512
5460
@enumerate
5461
@item
5462
A known answer test using a 112 byte string is run.
5463
@item
5464
A known answer test using a string of one million letters "a" is run.
5465
@end enumerate
5466
(@code{cipher/@/sha512.c:@/selftests_sha384},
5467
@code{cipher/@/sha512.c:@/selftests_sha512})
5468
@end table
5469
5470
@subsection MAC Algorithm Tests
5471
5472
The following MAC algorithm tests are run in addition to the power-up
5473
tests:
5474
5475
@table @asis
5476
@item HMAC SHA-1
5477
@enumerate
5478
@item
5479
A known answer test using 9 byte of data and a 20 byte key is run.
5480
@item
5481
A known answer test using 9 byte of data and a 100 byte key is run.
5482
@item
5483
A known answer test using 9 byte of data and a 49 byte key is run.
5484
@end enumerate
5485
(@code{cipher/hmac-tests.c:selftests_sha1})
5486
@item HMAC SHA-224
5487
@itemx HMAC SHA-256
5488
@itemx HMAC SHA-384
5489
@itemx HMAC SHA-512
5490
@enumerate
5491
@item
5492
A known answer test using 9 byte of data and a 20 byte key is run.
5493
@item
5494
A known answer test using 50 byte of data and a 20 byte key is run.
5495
@item
5496
A known answer test using 50 byte of data and a 26 byte key is run.
5497
@item
5498
A known answer test using 54 byte of data and a 131 byte key is run.
5499
@item
5500
A known answer test using 152 byte of data and a 131 byte key is run.
5501
@end enumerate
5502
(@code{cipher/@/hmac-tests.c:@/selftests_sha224},
5503
@code{cipher/@/hmac-tests.c:@/selftests_sha256},
5504
@code{cipher/@/hmac-tests.c:@/selftests_sha384},
5505
@code{cipher/@/hmac-tests.c:@/selftests_sha512})
5506
@end table
5507
5508
5509
@c ********************************************
5510
@node FIPS Mode
5511
@appendix Description of the FIPS Mode
5512
5513
This appendix gives detailed information pertaining to the FIPS mode.
5514
In particular, the changes to the standard mode and the finite state
5515
machine are described. The self-tests required in this mode are
5516
described in the appendix on self-tests.
5517
5518
@c -------------------------------
5519
@section Restrictions in FIPS Mode
5520
5521
@noindent
5522
If Libgcrypt is used in FIPS mode these restrictions are effective:
5523
5524
@itemize
5525
@item
5526
The cryptographic algorithms are restricted to this list:
5527
5528
@table @asis
5529
@item GCRY_CIPHER_3DES
5530
3 key EDE Triple-DES symmetric encryption.
5531
@item GCRY_CIPHER_AES128
5532
AES 128 bit symmetric encryption.
5533
@item GCRY_CIPHER_AES192
5534
AES 192 bit symmetric encryption.
5535
@item GCRY_CIPHER_AES256
5536
AES 256 bit symmetric encryption.
5537
@item GCRY_MD_SHA1
5538
SHA-1 message digest.
5539
@item GCRY_MD_SHA224
5540
SHA-224 message digest.
5541
@item GCRY_MD_SHA256
5542
SHA-256 message digest.
5543
@item GCRY_MD_SHA384
5544
SHA-384 message digest.
5545
@item GCRY_MD_SHA512
5546
SHA-512 message digest.
5547
@item GCRY_MD_SHA1,GCRY_MD_FLAG_HMAC
5548
HMAC using a SHA-1 message digest.
5549
@item GCRY_MD_SHA224,GCRY_MD_FLAG_HMAC
5550
HMAC using a SHA-224 message digest.
5551
@item GCRY_MD_SHA256,GCRY_MD_FLAG_HMAC
5552
HMAC using a SHA-256 message digest.
5553
@item GCRY_MD_SHA384,GCRY_MD_FLAG_HMAC
5554
HMAC using a SHA-384 message digest.
5555
@item GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
5556
HMAC using a SHA-512 message digest.
5557
@item GCRY_PK_RSA
5558
RSA encryption and signing.
5559
@item GCRY_PK_DSA
5560
DSA signing.
5561
@end table
5562
5563
Note that the CRC algorithms are not considered cryptographic algorithms
5564
and thus are in addition available.
5565
5566
@item
5567
RSA key generation refuses to create a key with a keysize of
5568
less than 1024 bits.
5569
5570
@item
5571
DSA key generation refuses to create a key with a keysize other
5572
than 1024 bits.
5573
5574
@item
5575
The @code{transient-key} flag for RSA and DSA key generation is ignored.
5576
5577
@item
5578
Support for the VIA Padlock engine is disabled.
5579
5580
@item
5581
FIPS mode may only be used on systems with a /dev/random device.
5582
Switching into FIPS mode on other systems will fail at runtime.
5583
5584
@item
5585
Saving and loading a random seed file is ignored.
5586
5587
@item
5588
An X9.31 style random number generator is used in place of the
5589
large-pool-CSPRNG generator.
5590
5591
@item
5592
The command @code{GCRYCTL_ENABLE_QUICK_RANDOM} is ignored.
5593
5594
@item
5595
The Alternative Public Key Interface (@code{gcry_ac_xxx}) is not
5596
supported and all API calls return an error.
5597
5598
@item
5599
Registration of external modules is not supported.
5600
5601
@item
5602
Message digest debugging is disabled.
5603
5604
@item
5605
All debug output related to cryptographic data is suppressed.
5606
5607
@item
5608
On-the-fly self-tests are not performed, instead self-tests are run
5609
before entering operational state.
5610
5611
@item
5612
The function @code{gcry_set_allocation_handler} may not be used. If
5613
it is used Libgcrypt disables FIPS mode unless Enforced FIPS mode is
5614
enabled, in which case Libgcrypt will enter the error state.
5615
5616
@item
5617
The digest algorithm MD5 may not be used. If it is used Libgcrypt
5618
disables FIPS mode unless Enforced FIPS mode is enabled, in which case
5619
Libgcrypt will enter the error state.
5620
5621
@item
5622
In Enforced FIPS mode the command @code{GCRYCTL_DISABLE_SECMEM} is
5623
ignored. In standard FIPS mode it disables FIPS mode.
5624
5625
@item
5626
A handler set by @code{gcry_set_outofcore_handler} is ignored.
5627
@item
5628
A handler set by @code{gcry_set_fatalerror_handler} is ignored.
5629
5630
@end itemize
5631
5632
Note that when we speak about disabling FIPS mode, it merely means
5633
that the function @code{gcry_fips_mode_active} returns false; it does
5634
not mean that any non FIPS algorithms are allowed.
5635
5636
@c ********************************************
5637
@section FIPS Finite State Machine
5638
5639
The FIPS mode of libgcrypt implements a finite state machine (FSM) using
5640
8 states (@pxref{tbl:fips-states}) and checks at runtime that only valid
5641
transitions (@pxref{tbl:fips-state-transitions}) may happen.
5642
5643
@float Figure,fig:fips-fsm
5644
@caption{FIPS mode state diagram}
5645
@center @image{fips-fsm,150mm,,FIPS FSM Diagram}
5646
@end float
5647
5648
@float Table,tbl:fips-states
5649
@caption{FIPS mode states}
5650
@noindent
5651
States used by the FIPS FSM:
5652
@table @asis
5653
5654
@item Power-Off
5655
Libgcrypt is not runtime linked to another application. This usually
5656
means that the library is not loaded into main memory. This state is
5657
documentation only.
5658
5659
@item Power-On
5660
Libgcrypt is loaded into memory and API calls may be made. Compiler
5661
introducted constructor functions may be run. Note that Libgcrypt does
5662
not implement any arbitrary constructor functions to be called by the
5663
operating system
5664
5665
@item Init
5666
The Libgcrypt initialization functions are performed and the library has
5667
not yet run any self-test.
5668
5669
@item Self-Test
5670
Libgcrypt is performing self-tests.
5671
5672
@item Operational
5673
Libgcrypt is in the operational state and all interfaces may be used.
5674
5675
@item Error
5676
Libgrypt is in the error state. When calling any FIPS relevant
5677
interfaces they either return an error (@code{GPG_ERR_NOT_OPERATIONAL})
5678
or put Libgcrypt into the Fatal-Error state and won't return.
5679
5680
@item Fatal-Error
5681
Libgcrypt is in a non-recoverable error state and
5682
will automatically transit into the Shutdown state.
5683
5684
@item Shutdown
5685
Libgcrypt is about to be terminated and removed from the memory. The
5686
application may at this point still runing cleanup handlers.
5687
5688
@end table
5689
@end float
5690
5691
5692
@float Table,tbl:fips-state-transitions
5693
@caption{FIPS mode state transitions}
5694
@noindent
5695
The valid state transitions (@pxref{fig:fips-fsm}) are:
5696
@table @code
5697
@item 1
5698
Power-Off to Power-On is implicitly done by the OS loading Libgcrypt as
5699
a shared library and having it linked to an application.
5700
5701
@item 2
5702
Power-On to Init is triggered by the application calling the
5703
Libgcrypt intialization function @code{gcry_check_version}.
5704
5705
@item 3
5706
Init to Self-Test is either triggred by a dedicated API call or implicit
5707
by invoking a libgrypt service conrolled by the FSM.
5708
5709
@item 4
5710
Self-Test to Operational is triggered after all self-tests passed
5711
successfully.
5712
5713
@item 5
5714
Operational to Shutdown is an artifical state without any direct action
5715
in Libgcrypt. When reaching the Shutdown state the library is
5716
deinitialized and can't return to any other state again.
5717
5718
@item 6
5719
Shutdown to Power-off is the process of removing Libgcrypt from the
5720
computer's memory. For obvious reasons the Power-Off state can't be
5721
represented within Libgcrypt and thus this transition is for
5722
documentation only.
5723
5724
@item 7
5725
Operational to Error is triggered if Libgcrypt detected an application
5726
error which can't be returned to the caller but still allows Libgcrypt
5727
to properly run. In the Error state all FIPS relevant interfaces return
5728
an error code.
5729
5730
@item 8
5731
Error to Shutdown is similar to the Operational to Shutdown transition
5732
(5).
5733
5734
@item 9
5735
Error to Fatal-Error is triggred if Libgrypt detects an fatal error
5736
while already being in Error state.
5737
5738
@item 10
5739
Fatal-Error to Shutdown is automatically entered by Libgcrypt
5740
after having reported the error.
5741
5742
@item 11
5743
Power-On to Shutdown is an artifical state to document that Libgcrypt
5744
has not ye been initializaed but the process is about to terminate.
5745
5746
@item 12
5747
Power-On to Fatal-Error will be triggerd if certain Libgcrypt functions
5748
are used without having reached the Init state.
5749
5750
@item 13
5751
Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt while
5752
running self-tests.
5753
5754
@item 14
5755
Self-Test to Error is triggred by a failed self-test.
5756
5757
@item 15
5758
Operational to Fatal-Error is triggered if Libcrypt encountered a
5759
non-recoverable error.
5760
5761
@item 16
5762
Operational to Self-Test is triggred if the application requested to run
5763
the self-tests again.
5764
5765
@item 17
5766
Error to Self-Test is triggered if the application has requested to run
5767
self-tests to get to get back into operational state after an error.
5768
5769
@item 18
5770
Init to Error is triggered by errors in the initialization code.
5771
5772
@item 19
5773
Init to Fatal-Error is triggered by non-recoverable errors in the
5774
initialization code.
5775
5776
@item 20
5777
Error to Error is triggered by errors while already in the Error
5778
state.
5779
5780
5781
@end table
5782
@end float
5783
5784
@c ********************************************
5785
@section FIPS Miscellaneous Information
5786
5787
Libgcrypt does not do any key management on itself; the application
5788
needs to care about it. Keys which are passed to Libgcrypt should be
5789
allocated in secure memory as available with the functions
5790
@code{gcry_malloc_secure} and @code{gcry_calloc_secure}. By calling
5791
@code{gcry_free} on this memory, the memory and thus the keys are
5792
overwritten with zero bytes before releasing the memory.
5793
5794
For use with the random number generator, Libgcrypt generates 3
5795
internal keys which are stored in the encryption contexts used by the
5796
RNG. These keys are stored in secure memory for the lifetime of the
5797
process. Application are required to use @code{GCRYCTL_TERM_SECMEM}
5798
before process termination. This will zero out the entire secure
5799
memory and thus also the encryption contexts with these keys.
5800
5801
5802
5803
@c **********************************************************
5804
@c ************* Appendices (license etc.) ****************
5805
@c **********************************************************
4343
5806
@include lgpl.texi
4344
5807
4345
5808
@include gpl.texi
4346
5809
5810
@node Figures and Tables
5811
@unnumbered List of Figures and Tables
5812
5813
@listoffloats Figure
5814
5815
@listoffloats Table
5816
4347
5817
@node Concept Index
4348
5818
@unnumbered Concept Index
4349
5819
4354
5824
4355
5825
@printindex fn
4356
5826
5827
5828
4357
5829
@bye
4358
5830
4359
/* Version check should be the very first gcry call because it
4360
makes sure that constructor functions are run. */
4361
if (!gcry_check_version (GCRYPT_VERSION))
4362
die ("version mismatch\n");
4363
/* Many applications don't require secure memory, so they should
4364
disable it right away. There won't be a problem unless one makes
4365
use of a feature which requires secure memory - in that case the
4366
process would abort because the secmem is not initialized. */
4367
gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
4368
4369
/* .. add whatever initialization you want, but better don't make calls
4370
to libgcrypt from more than one thread ... */
4371
4372
/* Tell Libgcrypt that initialization has completed. */
4373
gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
4374
4375
4376
If you require secure memory, this code should be used:
4377
4378
if (!gcry_check_version (GCRYPT_VERSION))
4379
die ("version mismatch\n");
4380
/* We don't want to see any warnings, e.g. because we have not yet
4381
parsed options which might be used to suppress such warnings */
4382
gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
4383
4384
/* ... */
4385
4386
/* Allocate a pool of 16k secure memory. This also drops privileges
4387
on some systems. */
4388
gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
4389
4390
/* It is now okay to let Libgcrypt complain when there was/is a problem
4391
with the secure memory. */
4392
gcry_control (GCRYCTL_RESUME_SECMEM_WARN);
4393
4394
/* Tell Libgcrypt that initialization has completed. */
4395
gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
4396
4397
4398
This sounds a bit complicated but has the advantage that the caller
4399
must decide whether he wants secure memory or not - there is no
4400
default.
4401
4402
It is important that this initialization is not done by a library but
4403
in the application. The library might want to check for finished
4404
initialization using:
4405
4406
if (!gcry_control (GCRYCTL_INITIALIZATION_FINISHED_P))
4407
return MYLIB_ERROR_LIBGCRYPT_NOT_INITIALIZED;
5831
GCRYCTL_SET_RANDOM_DAEMON_SOCKET
5832
GCRYCTL_USE_RANDOM_DAEMON
5833
The random damon is still a bit experimental, thus we do not document
5834
them. Note that they should be used during initialization and that
5835
these functions are not really thread safe.
5836
5837
4408
5838
4409
5839
4410
5840
@c LocalWords: int HD
Loggerhead is a web-based interface for Breezy
Version: 2.0.1