Appendix B Description of the FIPS Mode
This appendix gives detailed information pertaining to the FIPS mode.
In particular, the changes to the standard mode and the finite state
machine are described. The self-tests required in this mode are
described in the appendix on self-tests.
B.1 Restrictions in FIPS Mode
If Libgcrypt is used in FIPS mode these restrictions are effective:
Note that when we speak about disabling FIPS mode, it merely means
that the function gcry_fips_mode_active returns false; it does
not mean that any non FIPS algorithms are allowed.
B.2 FIPS Finite State Machine
The FIPS mode of libgcrypt implements a finite state machine (FSM) using
8 states (see tbl:fips-states) and checks at runtime that only valid
transitions (see tbl:fips-state-transitions) may happen.
Figure B.1: FIPS mode state diagram
States used by the FIPS FSM:
- 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.
- Power-On
- Libgcrypt is loaded into memory and API calls may be made. Compiler
introducted constructor functions may be run. Note that Libgcrypt does
not implement any arbitrary constructor functions to be called by the
operating system
- Init
- The Libgcrypt initialization functions are performed and the library has
not yet run any self-test.
- Self-Test
- Libgcrypt is performing self-tests.
- Operational
- Libgcrypt is in the operational state and all interfaces may be used.
- Error
- Libgrypt is in the error state. When calling any FIPS relevant
interfaces they either return an error (
GPG_ERR_NOT_OPERATIONAL)
or put Libgcrypt into the Fatal-Error state and won't return.
- Fatal-Error
- Libgcrypt is in a non-recoverable error state and
will automatically transit into the Shutdown state.
- Shutdown
- Libgcrypt is about to be terminated and removed from the memory. The
application may at this point still runing cleanup handlers.
Table B.1: FIPS mode states
The valid state transitions (see
Figure B.1) are:
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.
2- Power-On to Init is triggered by the application calling the
Libgcrypt intialization function
gcry_check_version.
3- Init to Self-Test is either triggred by a dedicated API call or implicit
by invoking a libgrypt service conrolled by the FSM.
4- Self-Test to Operational is triggered after all self-tests passed
successfully.
5- Operational to Shutdown is an artifical state without any direct action
in Libgcrypt. When reaching the Shutdown state the library is
deinitialized and can't return to any other state again.
6- Shutdown to Power-off is the process of removing Libgcrypt from the
computer's memory. For obvious reasons the Power-Off state can't be
represented within Libgcrypt and thus this transition is for
documentation only.
7- Operational to Error is triggered if Libgcrypt detected an application
error which can't be returned to the caller but still allows Libgcrypt
to properly run. In the Error state all FIPS relevant interfaces return
an error code.
8- Error to Shutdown is similar to the Operational to Shutdown transition
(5).
9- Error to Fatal-Error is triggred if Libgrypt detects an fatal error
while already being in Error state.
10- Fatal-Error to Shutdown is automatically entered by Libgcrypt
after having reported the error.
11- Power-On to Shutdown is an artifical state to document that Libgcrypt
has not ye been initializaed but the process is about to terminate.
12- Power-On to Fatal-Error will be triggerd if certain Libgcrypt functions
are used without having reached the Init state.
13- Self-Test to Fatal-Error is triggred by severe errors in Libgcrypt while
running self-tests.
14- Self-Test to Error is triggred by a failed self-test.
15- Operational to Fatal-Error is triggered if Libcrypt encountered a
non-recoverable error.
16- Operational to Self-Test is triggred if the application requested to run
the self-tests again.
17- Error to Self-Test is triggered if the application has requested to run
self-tests to get to get back into operational state after an error.
18- Init to Error is triggered by errors in the initialization code.
19- Init to Fatal-Error is triggered by non-recoverable errors in the
initialization code.
20- Error to Error is triggered by errors while already in the Error
state.
Table B.2: FIPS mode state transitions
B.3 FIPS Miscellaneous Information
Libgcrypt does not do any key management on itself; the application
needs to care about it. Keys which are passed to Libgcrypt should be
allocated in secure memory as available with the functions
gcry_malloc_secure and gcry_calloc_secure. By calling
gcry_free on this memory, the memory and thus the keys are
overwritten with zero bytes before releasing the memory.
For use with the random number generator, Libgcrypt generates 3
internal keys which are stored in the encryption contexts used by the
RNG. These keys are stored in secure memory for the lifetime of the
process. Application are required to use GCRYCTL_TERM_SECMEM
before process termination. This will zero out the entire secure
memory and thus also the encryption contexts with these keys.
