(version @value{VERSION}, @value{UPDATED}),
which is GNU's library of cryptographic building blocks.
-Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 2000, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Symmetric cryptography:: How to use symmetric cryptography.
* Public Key cryptography:: How to use public key cryptography.
* Hashing:: How to use hash and MAC algorithms.
+* Key Derivation:: How to derive keys from strings
* Random Numbers:: How to work with random numbers.
* S-expressions:: How to manage S-expressions.
* MPI library:: How to work with multi-precision-integers.
Do not define the shorthand macros @code{mpi_*} for @code{gcry_mpi_*}.
@item GCRYPT_NO_DEPRECATED
-Do not include defintions for deprecated features. This is useful to
+Do not include definitions for deprecated features. This is useful to
make sure that no deprecated features are used.
@end table
fputs ("libgcrypt version mismatch\n", stderr);
exit (2);
@}
-
+
/* Disable secure memory. */
gcry_control (GCRYCTL_DISABLE_SECMEM, 0);
gcry_control (GCRYCTL_SUSPEND_SECMEM_WARN);
/* ... If required, other initialization goes here. Note that the
- process might still be running with increased privileges and that
+ process might still be running with increased privileges and that
the secure memory has not been intialized. */
/* Allocate a pool of 16k secure memory. This make the secure memory
@{
fputs ("libgcrypt has not been initialized\n", stderr);
abort ();
- @}
+ @}
@end example
Instead of terminating the process, the library may instead print a
@node Multi-Threading
@section Multi-Threading
-As mentioned earlier, the Libgcrypt library is
+As mentioned earlier, the Libgcrypt library is
thread-safe if you adhere to the following requirements:
@itemize @bullet
Libgcrypt into this mode:
@itemize
-@item
+@item
If the file @file{/proc/sys/crypto/fips_enabled} exists and contains a
numeric value other than @code{0}, Libgcrypt is put into FIPS mode at
initialization time. Obviously this works only on systems with a
@code{proc} file system (i.e. GNU/Linux).
-@item
+@item
If the file @file{/etc/gcrypt/fips_enabled} exists, Libgcrypt is put
into FIPS mode at initialization time. Note that this filename is
hardwired and does not depend on any configuration options.
-@item
+@item
If the application requests FIPS mode using the control command
@code{GCRYCTL_FORCE_FIPS_MODE}. This must be done prior to any
initialization (i.e. before @code{gcry_check_version}).
Many applications do not require secure memory, so they should disable
it right away. This command should be executed right after
-@code{gcry_check_version}.
+@code{gcry_check_version}.
@item GCRYCTL_INIT_SECMEM; Arguments: int nbytes
This command is used to allocate a pool of secure memory and thus
@code{gcry_check_version}.
@item GCRYCTL_SUSPEND_SECMEM_WARN; Arguments: none
-Postpone warning messages from the secure memory subsystem.
+Postpone warning messages from the secure memory subsystem.
@xref{sample-use-suspend-secmem,,the initialization example}, on how to
-use it.
+use it.
@item GCRYCTL_RESUME_SECMEM_WARN; Arguments: none
Resume warning messages from the secure memory subsystem.
do this basic intialization is by calling gcry_check_version.
@item GCRYCTL_INITIALIZATION_FINISHED; Arguments: none
-This command tells the libray that the application has finished the
+This command tells the library that the application has finished the
intialization.
@item GCRYCTL_INITIALIZATION_FINISHED_P; Arguments: none
self-tests. It works in standard and in FIPS mode. Returns 0 on
success or an error code on failure.
+@item GCRYCTL_DISABLE_HWF; Arguments: const char *name
+
+Libgcrypt detects certain features of the CPU at startup time. For
+performace tests it is sometimes required not to use such a feature.
+This option may be used to disabale a certain feature; i.e. Libgcrypt
+behaves as if this feature has not been detected. Note that the
+detection code might be run if the feature has been disabled. This
+command must be used at initialization time; i.e. before calling
+@code{gcry_check_version}.
@end table
gcry_cipher_hd_t handle;
gcry_error_t err = 0;
- err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
+ err = gcry_cipher_open (&handle, GCRY_CIPHER_AES,
GCRY_CIPHER_MODE_CBC, 0);
if (err)
@{
@chapter Handler Functions
Libgcrypt makes it possible to install so called `handler functions',
-which get called by Libgcrypt in case of certain events.
+which get called by Libgcrypt in case of certain events.
@menu
* Progress handler:: Using a progress handler function.
@item GCRY_CIPHER_CAST5
@cindex CAST5
CAST128-5 block cipher algorithm. The key size is 128 bits.
-
+
@item GCRY_CIPHER_BLOWFISH
@cindex Blowfish
The blowfish algorithm. The current implementation allows only for a key
@item GCRY_CIPHER_SAFER_SK128
Reserved and not currently implemented.
-@item GCRY_CIPHER_DES_SK
+@item GCRY_CIPHER_DES_SK
Reserved and not currently implemented.
-
-@item GCRY_CIPHER_AES
+
+@item GCRY_CIPHER_AES
@itemx GCRY_CIPHER_AES128
@itemx GCRY_CIPHER_RIJNDAEL
@itemx GCRY_CIPHER_RIJNDAEL128
@cindex Advanced Encryption Standard
AES (Rijndael) with a 128 bit key.
-@item GCRY_CIPHER_AES192
+@item GCRY_CIPHER_AES192
@itemx GCRY_CIPHER_RIJNDAEL192
AES (Rijndael) with a 192 bit key.
-@item GCRY_CIPHER_AES256
+@item GCRY_CIPHER_AES256
@itemx GCRY_CIPHER_RIJNDAEL256
AES (Rijndael) with a 256 bit key.
-
+
@item GCRY_CIPHER_TWOFISH
@cindex Twofish
The Twofish algorithm with a 256 bit key.
-
+
@item GCRY_CIPHER_TWOFISH128
The Twofish algorithm with a 128 bit key.
-
-@item GCRY_CIPHER_ARCFOUR
+
+@item GCRY_CIPHER_ARCFOUR
@cindex Arcfour
@cindex RC4
An algorithm which is 100% compatible with RSA Inc.'s RC4 algorithm.
Note that this is a stream cipher and must be used very carefully to
-avoid a couple of weaknesses.
+avoid a couple of weaknesses.
@item GCRY_CIPHER_DES
@cindex DES
Register a new cipher module whose specification can be found in
@var{cipher}. On success, a new algorithm ID is stored in
@var{algorithm_id} and a pointer representing this module is stored
-in @var{module}.
+in @var{module}. Deprecated; the module register interface will be
+removed in a future version.
@end deftypefun
@deftypefun void gcry_cipher_unregister (gcry_module_t @var{module})
@item GCRY_CIPHER_MODE_ECB
@cindex ECB, Electronic Codebook mode
-Electronic Codebook mode.
+Electronic Codebook mode.
@item GCRY_CIPHER_MODE_CFB
@cindex CFB, Cipher Feedback mode
@cindex CTR, Counter mode
Counter mode.
+@item GCRY_CIPHER_MODE_AESWRAP
+@cindex AES-Wrap mode
+This mode is used to implement the AES-Wrap algorithm according to
+RFC-3394. It may be used with any 128 bit block length algorithm,
+however the specs require one of the 3 AES algorithms. These special
+conditions apply: If @code{gcry_cipher_setiv} has not been used the
+standard IV is used; if it has been used the lower 64 bit of the IV
+are used as the Alternative Initial Value. On encryption the provided
+output buffer must be 64 bit (8 byte) larger than the input buffer;
+in-place encryption is still allowed. On decryption the output buffer
+may be specified 64 bit (8 byte) shorter than then input buffer. As
+per specs the input length must be at least 128 bits and the length
+must be a multiple of 64 bits.
+
@end table
@node Working with cipher handles
@item GCRY_CIPHER_ENABLE_SYNC
@cindex sync mode (OpenPGP)
This flag enables the CFB sync mode, which is a special feature of
-Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
+Libgcrypt's CFB mode implementation to allow for OpenPGP's CFB variant.
See @code{gcry_cipher_sync}.
@item GCRY_CIPHER_CBC_CTS
@cindex cipher text stealing
only output the last block. Cannot be used simultaneous as
GCRY_CIPHER_CBC_CTS.
@end table
-@end deftypefun
+@end deftypefun
Use the following function to release an existing handle:
the return code of the function or copied to the provided @var{buffer}
whose allocated length must be available in an integer variable with the
address passed in @var{nbytes}. This variable will also receive the
-actual used length of the buffer.
+actual used length of the buffer.
Here is a list of supported codes for @var{what}:
@item GCRYCTL_TEST_ALGO:
Returns @code{0} when the specified algorithm is available for use.
@var{buffer} and @var{nbytes} must be zero.
-
-@end table
+
+@end table
@c end constants for gcry_cipher_algo_info
@end deftypefun
parameters must be given or none of them. They are mandatory for
gcry_pk_testkey.
-Note that OpenSSL uses slighly different parameters: @math{q < p} and
+Note that OpenSSL uses slighly different parameters: @math{q < p} and
@math{u = q^{-1} \bmod p}. To use these parameters you will need to
swap the values and recompute @math{u}. Here is example code to do this:
Register a new public key module whose specification can be found in
@var{pubkey}. On success, a new algorithm ID is stored in
-@var{algorithm_id} and a pointer representing this module is stored
-in @var{module}.
+@var{algorithm_id} and a pointer representing this module is stored in
+@var{module}. Deprecated; the module register interface will be
+removed in a future version.
+
@end deftypefun
@deftypefun void gcry_pk_unregister (gcry_module_t @var{module})
@noindent
Note that we will in future allow to use keys without p,q and u
specified and may also support other parameters for performance
-reasons.
+reasons.
@noindent
@table @code
@item pkcs1
-Use PKCS#1 block type 2 padding.
+Use PKCS#1 block type 2 padding for encryption, block type 1 padding
+for signing.
+@item oaep
+Use RSA-OAEP padding for encryption.
+@item pss
+Use RSA-PSS padding for signing.
@item no-blinding
Do not use a technique called `blinding', which is used by default in
order to prevent leaking of secret information. Blinding is only
If you don't want to let Libgcrypt handle the padding, you must pass an
appropriate MPI using this expression for @var{data}:
-@example
+@example
(data
(flags raw)
(value @var{mpi}))
@end example
@noindent
-This has the same semantics as the old style MPI only way. @var{MPI} is
-the actual data, already padded appropriate for your protocol. Most
-systems however use PKCS#1 padding and so you can use this S-expression
-for @var{data}:
+This has the same semantics as the old style MPI only way. @var{MPI}
+is the actual data, already padded appropriate for your protocol.
+Most RSA based systems however use PKCS#1 padding and so you can use
+this S-expression for @var{data}:
-@example
+@example
(data
(flags pkcs1)
(value @var{block}))
@end example
@noindent
-Note that this function currently does not know of any padding
-methods and the caller must do any un-padding on his own.
+This function does not remove padding from the data by default. To
+let Libgcrypt remove padding, give a hint in `flags' telling which
+padding method was used when encrypting:
+
+@example
+(flags @var{padding-method})
+@end example
+
+@noindent
+Currently @var{padding-method} is either @code{pkcs1} for PKCS#1 block
+type 2 padding, or @code{oaep} for RSA-OAEP padding.
@noindent
The function returns 0 on success or an error code. The variable at the
with just one MPI or a modern and more versatile S-expression which
allows to let Libgcrypt handle padding:
-@example
+@example
(data
(flags pkcs1)
(hash @var{hash-algo} @var{block}))
flags:
@table @code
-@item GCRY_PK_USAGE_SIGN
+@item GCRY_PK_USAGE_SIGN
Algorithm is usable for signing.
-@item GCRY_PK_USAGE_ENCR
+@item GCRY_PK_USAGE_ENCR
Algorithm is usable for encryption.
@end table
@item qbits
This is only meanigful for DSA keys. If it is given the DSA key is
-generated with a Q parameyer of this size. If it is not given or zero
+generated with a Q parameyer of this size. If it is not given or zero
Q is deduced from NBITS in this way:
@table @samp
@item 512 <= N <= 1024
15680 are valid as long as they are multiples of 8.
@item transient-key
-This is only meaningful for RSA and DSA keys. This is a flag with no
-value. If given the RSA or DSA key is created using a faster and a
-somewhat less secure random number generator. This flag may be used
-for keys which are only used for a short time and do not require full
+This is only meaningful for RSA, DSA, ECDSA, and ECDH keys. This is a flag
+with no value. If given the key is created using a faster and a
+somewhat less secure random number generator. This flag may be used for
+keys which are only used for a short time or per-message and do not require full
cryptographic strength.
@item domain
key may be stored before the public key. @var{n1 n2 ... nn} is a list
of prime numbers used to composite @var{p-mpi}; this is in general not
a very useful information and only available if the key generation
-algorithm provides them.
+algorithm provides them.
@end deftypefun
@c end gcry_pk_genkey
@cindex SHA-224, SHA-256, SHA-384, SHA-512
@cindex RIPE-MD-160
@cindex MD2, MD4, MD5
-@cindex TIGER
+@cindex TIGER, TIGER1, TIGER2
@cindex HAVAL
@cindex Whirlpool
@cindex CRC32
This algorithm has severe weaknesses and should not be used.
@item GCRY_MD_TIGER
-This is the TIGER/192 algorithm which yields a message digest of 24 bytes.
+This is the TIGER/192 algorithm which yields a message digest of 24
+bytes. Actually this is a variant of TIGER with a different output
+print order as used by GnuPG up to version 1.3.2.
+
+@item GCRY_MD_TIGER1
+This is the TIGER variant as used by the NESSIE project. It uses the
+most commonly used output print order.
+
+@item GCRY_MD_TIGER2
+This is another variant of TIGER with a different padding scheme.
+
@item GCRY_MD_HAVAL
This is an reserved value for the HAVAL algorithm with 5 passes and 160
Register a new digest module whose specification can be found in
@var{digest}. On success, a new algorithm ID is stored in
@var{algorithm_id} and a pointer representing this module is stored
-in @var{module}.
+in @var{module}. Deprecated; the module register interface will be
+removed in a future version.
@end deftypefun
@deftypefun void gcry_md_unregister (gcry_module_t @var{module})
Pass the byte in @var{c} to the digest object with handle @var{h} to
update the digest value. This is an efficient function, implemented as
-a macro to buffer the data before an actual update.
+a macro to buffer the data before an actual update.
@end deftypefun
The semantics of the hash functions do not provide for reading out intermediate
@end deftypefun
Because it is often necessary to get the message digest of one block of
-memory, a fast convenience function is available for this task:
+memory, a fast convenience function is available for this task:
@deftypefun void gcry_md_hash_buffer (int @var{algo}, void *@var{digest}, const void *@var{buffer}, size_t @var{length});
To test whether an algorithm is actually available for use, the
following macro should be used:
-@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
+@deftypefun gcry_error_t gcry_md_test_algo (int @var{algo})
The macro returns 0 if the algorithm @var{algo} is available for use.
@end deftypefun
@end deftypefun
+@c *******************************************************
+@c ******************* KDF *****************************
+@c *******************************************************
+@node Key Derivation
+@chapter Key Derivation
+
+@acronym{Libgcypt} provides a general purpose function to derive keys
+from strings.
+
+@deftypefun gpg_error_t gcry_kdf_derive ( @
+ @w{const void *@var{passphrase}}, @w{size_t @var{passphraselen}}, @
+ @w{int @var{algo}}, @w{int @var{subalgo}}, @
+ @w{const void *@var{salt}}, @w{size_t @var{saltlen}}, @
+ @w{unsigned long @var{iterations}}, @
+ @w{size_t @var{keysize}}, @w{void *@var{keybuffer}} )
+
+
+Derive a key from a passphrase. @var{keysize} gives the requested
+size of the keys in octets. @var{keybuffer} is a caller provided
+buffer filled on success with the derived key. The input passphrase
+is taken from @var{passphrase} which is an arbitrary memory buffer of
+@var{passphraselen} octets. @var{algo} specifies the KDF algorithm to
+use; see below. @var{subalgo} specifies an algorithm used internally
+by the KDF algorithms; this is usually a hash algorithm but certain
+KDF algorithms may use it differently. @var{salt} is a salt of length
+@var{saltlen} octets, as needed by most KDF algorithms.
+@var{iterations} is a positive integer parameter to most KDFs.
+
+@noindent
+On success 0 is returned; on failure an error code.
+
+@noindent
+Currently supported KDFs (parameter @var{algo}):
+
+@table @code
+@item GCRY_KDF_SIMPLE_S2K
+The OpenPGP simple S2K algorithm (cf. RFC4880). Its use is strongly
+deprecated. @var{salt} and @var{iterations} are not needed and may be
+passed as @code{NULL}/@code{0}.
+
+@item GCRY_KDF_SALTED_S2K
+The OpenPGP salted S2K algorithm (cf. RFC4880). Usually not used.
+@var{iterations} is not needed and may be passed as @code{0}. @var{saltlen}
+must be given as 8.
+
+@item GCRY_KDF_ITERSALTED_S2K
+The OpenPGP iterated+salted S2K algorithm (cf. RFC4880). This is the
+default for most OpenPGP applications. @var{saltlen} must be given as
+8. Note that OpenPGP defines a special encoding of the
+@var{iterations}; however this function takes the plain decoded
+iteration count.
+
+@item GCRY_KDF_PBKDF2
+The PKCS#5 Passphrase Based Key Derivation Function number 2.
+
+@end table
+@end deftypefun
+
+
@c **********************************************************
@c ******************* Random *****************************
@c **********************************************************
This is the generic function to create an new S-expression object from
its external representation in @var{buffer} of @var{length} bytes. On
-success the result is stored at the address given by @var{r_sexp}.
+success the result is stored at the address given by @var{r_sexp}.
With @var{autodetect} set to 0, the data in @var{buffer} is expected to
be in canonized format, with @var{autodetect} set to 1 the parses any of
the defined external formats. If @var{buffer} does not hold a valid
@table @samp
@item %m
The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
-its value is inserted into the resulting S-expression.
+its value is inserted into the resulting S-expression. The MPI is
+stored as a signed integer.
+@item %M
+The next argument is expected to be of type @code{gcry_mpi_t} and a copy of
+its value is inserted into the resulting S-expression. The MPI is
+stored as an unsigned integer.
@item %s
The next argument is expected to be of type @code{char *} and that
string is inserted into the resulting S-expression.
@item %d
The next argument is expected to be of type @code{int} and its value is
inserted into the resulting S-expression.
+@item %u
+The next argument is expected to be of type @code{unsigned int} and
+its value is inserted into the resulting S-expression.
@item %b
The next argument is expected to be of type @code{int} directly
followed by an argument of type @code{char *}. This represents a
@var{mpifmt} and returned as a standard Libgcrypt MPI. The caller must
release this returned value using @code{gcry_mpi_release}. If there is
no data at the given index, the index represents a list or the value
-can't be converted to an MPI, @code{NULL} is returned.
+can't be converted to an MPI, @code{NULL} is returned. If you use
+this function to parse results of a public key function, you most
+likely want to use @code{GCRYMPI_FMT_USG}.
@end deftypefun
Public key cryptography is based on mathematics with large numbers. To
implement the public key functions, a library for handling these large
numbers is required. Because of the general usefulness of such a
-library, its interface is exposed by Libgcrypt.
+library, its interface is exposed by Libgcrypt.
In the context of Libgcrypt and in most other applications, these large
numbers are called MPIs (multi-precision-integers).
@deftypefun int gcry_mpi_gcd (@w{gcry_mpi_t @var{g}}, @w{gcry_mpi_t @var{a}}, @w{gcry_mpi_t @var{b}})
-Set @var{g} to the greatest common divisor of @var{a} and @var{b}.
+Set @var{g} to the greatest common divisor of @var{a} and @var{b}.
Return true if the @var{g} is 1.
@end deftypefun
Compare the multi-precision-integers number @var{u} and @var{v}
returning 0 for equality, a positive value for @var{u} > @var{v} and a
-negative for @var{u} < @var{v}.
+negative for @var{u} < @var{v}. If both numbers are opaque values
+(cf, gcry_mpi_set_opaque) the comparison is done by checking the bit
+sizes using memcmp. If only one number is an opaque value, the opaque
+value is less than the other number.
@end deftypefun
@deftypefun int gcry_mpi_cmp_ui (@w{const gcry_mpi_t @var{u}}, @w{unsigned long @var{v}})
@table @code
-@item gcry_pk_encrypt
+@item gcry_pk_encrypt
Encrypt data using a public key.
-@item gcry_pk_decrypt
+@item gcry_pk_decrypt
Decrypt data using a private key.
-@item gcry_pk_sign
+@item gcry_pk_sign
Sign data using a private key.
@item gcry_pk_verify
Release an instance.
@item gcry_cipher_setkey
-Set a key to be used for encryption or decryption.
+Set a key to be used for encryption or decryption.
@item gcry_cipher_setiv
Set an initialization vector to be used for encryption or decryption.
@item gcry_cipher_encrypt
-@itemx gcry_cipher_decrypt
+@itemx gcry_cipher_decrypt
Encrypt or decrypt data. These functions may be called with arbitrary
amounts of data and as often as needed to encrypt or decrypt all data.
GMP are:
@itemize
-@item
+@item
Avoidance of stack based allocations to allow protection against
swapping out of sensitive data and for easy zeroing of sensitive
intermediate results.
multi-precision-integer using the @code{gcry_create_nonce} function.
@noindent
-There are two distinct random generators available:
+There are two distinct random generators available:
@itemize
-@item
+@item
The Continuously Seeded Pseudo Random Number Generator (CSPRNG), which
is based on the classic GnuPG derived big pool implementation.
Implemented in @code{random/random-csprng.c} and used by default.
@c @node Helper Subsystems Architecture
@c @section Helper Subsystems Architecture
-@c
+@c
@c There are a few smaller subsystems which are mainly used internally by
@c Libgcrypt but also available to applications.
-@c
+@c
@c @menu
@c * S-expression Subsystem Architecture:: Details about the S-expression architecture.
@c * Memory Subsystem Architecture:: Details about the memory allocation architecture.
@c * Miscellaneous Subsystems Architecture:: Details about other subsystems.
@c @end menu
-@c
+@c
@c @node S-expression Subsystem Architecture
@c @subsection S-expression Subsystem Architecture
-@c
+@c
@c Libgcrypt provides an interface to S-expression to create and parse
@c them. To use an S-expression with Libgcrypt it needs first be
@c converted into the internal representation used by Libgcrypt (the type
@c of the S-expression specification and further fature a printf like
@c function to convert a list of big integers or other binary data into
@c an S-expression.
-@c
+@c
@c Libgcrypt currently implements S-expressions using a tagged linked
@c list. However this is not exposed to an application and may be
@c changed in future releases to reduce overhead when already working
@c with canonically encoded S-expressions. Secure memory is supported by
@c this S-expressions implementation.
-@c
-@c @node Memory Subsystem Architecture
-@c @subsection Memory Subsystem Architecture
-@c
+@c
+@c @node Memory Subsystem Architecture
+@c @subsection Memory Subsystem Architecture
+@c
@c TBD.
-@c
-@c
+@c
+@c
@c @node Miscellaneous Subsystems Architecture
@c @subsection Miscellaneous Subsystems Architecture
-@c
+@c
@c TBD.
-@c
-@c
+@c
+@c
@c --------------------------------
@section Power-Up Tests
-Power-up tests are only performed if Libgcrypt is in FIPS mode.
+Power-up tests are only performed if Libgcrypt is in FIPS mode.
@subsection Symmetric Cipher Algorithm Power-Up Tests
The DRNG is tested during power-up this way:
@enumerate
-@item
+@item
Requesting one block of random using the public interface to check
general working and the duplicated block detection.
@item
A pre-defined 1024 bit RSA key is used and these tests are run
in turn:
@enumerate
-@item
-Conversion of S-expression to internal format.
+@item
+Conversion of S-expression to internal format.
(@code{cipher/@/rsa.c:@/selftests_rsa})
-@item
+@item
Private key consistency check.
(@code{cipher/@/rsa.c:@/selftests_rsa})
@item
context is saved in the context and another block is generated to be
returned to the caller. Each block is compared against the saved
block and then stored in the context. If a duplicated block is
-detected an error is signaled and the libray is put into the
+detected an error is signaled and the library is put into the
``Fatal-Error'' state.
(@code{random/@/random-fips.c:@/x931_aes_driver})
@subsection Hash Algorithm Tests
-The following hash algorithm tests are run in addition to the
+The following hash algorithm tests are run in addition to the
power-up tests:
@table @asis
@enumerate
@item
A known answer test using a 56 byte string is run.
-@item
+@item
A known answer test using a string of one million letters "a" is run.
@end enumerate
(@code{cipher/@/sha1.c:@/selftests_sha1},
@enumerate
@item
A known answer test using a 112 byte string is run.
-@item
+@item
A known answer test using a string of one million letters "a" is run.
@end enumerate
(@code{cipher/@/sha512.c:@/selftests_sha384},
@item GCRY_MD_SHA512,GCRY_MD_FLAG_HMAC
HMAC using a SHA-512 message digest.
@item GCRY_PK_RSA
-RSA encryption and signing.
+RSA encryption and signing.
@item GCRY_PK_DSA
DSA signing.
@end table
@item
RSA key generation refuses to create a key with a keysize of
-less than 1024 bits.
+less than 1024 bits.
@item
DSA key generation refuses to create a key with a keysize other
@item
Support for the VIA Padlock engine is disabled.
-@item
+@item
FIPS mode may only be used on systems with a /dev/random device.
Switching into FIPS mode on other systems will fail at runtime.
@item
Registration of external modules is not supported.
-@item
+@item
Message digest debugging is disabled.
@item
All debug output related to cryptographic data is suppressed.
-@item
+@item
On-the-fly self-tests are not performed, instead self-tests are run
before entering operational state.
disables FIPS mode unless Enforced FIPS mode is enabled, in which case
Libgcrypt will enter the error state.
-@item
+@item
In Enforced FIPS mode the command @code{GCRYCTL_DISABLE_SECMEM} is
ignored. In standard FIPS mode it disables FIPS mode.
States used by the FIPS FSM:
@table @asis
-@item Power-Off
+@item Power-Off
Libgcrypt is not runtime linked to another application. This usually
means that the library is not loaded into main memory. This state is
documentation only.
not yet run any self-test.
@item Self-Test
-Libgcrypt is performing self-tests.
+Libgcrypt is performing self-tests.
@item Operational
Libgcrypt is in the operational state and all interfaces may be used.
@item Error
Libgrypt is in the error state. When calling any FIPS relevant
interfaces they either return an error (@code{GPG_ERR_NOT_OPERATIONAL})
-or put Libgcrypt into the Fatal-Error state and won't return.
+or put Libgcrypt into the Fatal-Error state and won't return.
@item Fatal-Error
-Libgcrypt is in a non-recoverable error state and
-will automatically transit into the Shutdown state.
+Libgcrypt is in a non-recoverable error state and
+will automatically transit into the Shutdown state.
@item Shutdown
Libgcrypt is about to be terminated and removed from the memory. The
@noindent
The valid state transitions (@pxref{fig:fips-fsm}) are:
@table @code
-@item 1
+@item 1
Power-Off to Power-On is implicitly done by the OS loading Libgcrypt as
a shared library and having it linked to an application.
Init to Self-Test is either triggred by a dedicated API call or implicit
by invoking a libgrypt service conrolled by the FSM.
-@item 4
+@item 4
Self-Test to Operational is triggered after all self-tests passed
-successfully.
+successfully.
@item 5
Operational to Shutdown is an artifical state without any direct action
while already being in Error state.
@item 10
-Fatal-Error to Shutdown is automatically entered by Libgcrypt
+Fatal-Error to Shutdown is automatically entered by Libgcrypt
after having reported the error.
@item 11
@c LocalWords: int HD
-
-
-
-
projects / libgcrypt.git / blobdiff