Previous: , Up: Internal architecture of GnuTLS   [Contents][Index]

11.7 FIPS140-2 mode

GnuTLS can operate in a special mode for FIPS140-2. That mode of operation is for the conformance to NIST’s FIPS140-2 publication, which consists of policies for cryptographic modules (such as software libraries). Its implementation in GnuTLS is designed for Red Hat Enterprise Linux, and can only be enabled when the library is explicitly compiled with the ’–enable-fips140-mode’ configure option.

There are two distinct library states with regard to FIPS140-2: the FIPS140-2 mode is installed if /etc/system-fips is present, and the FIPS140-2 mode is enabled if /proc/sys/crypto/fips_enabled contains ’1’, which is typically set with the “fips=1” kernel command line option.

When the FIPS140-2 mode is installed, the operation of the library is modified as follows.

When the FIPS140-2 mode is enabled, The operation of the library is in addition modified as follows.

There are also few environment variables which modify that operation. The environment variable GNUTLS_SKIP_FIPS_INTEGRITY_CHECKS will disable the library integrity tests on startup, and the variable GNUTLS_FORCE_FIPS_MODE can be set to force a value from Figure 11.5, i.e., ’1’ will enable the FIPS140-2 mode, while ’0’ will disable it.

The integrity checks for the dependent libraries and GnuTLS are performed using ’.hmac’ files which are present at the same path as the library. The key for the operations can be provided on compile-time with the configure option ’–with-fips140-key’. The MAC algorithm used is HMAC-SHA256.

On runtime an application can verify whether the library is in FIPS140-2 mode using the gnutls_fips140_mode_enabled function.

Relaxing FIPS140-2 requirements

The library by default operates in a strict enforcing mode, ensuring that all constraints imposed by the FIPS140-2 specification are enforced. However the application can relax these requirements via gnutls_fips140_set_mode which can switch to alternative modes as in Figure 11.5.

GNUTLS_FIPS140_DISABLED

The FIPS140-2 mode is disabled.

GNUTLS_FIPS140_STRICT

The default mode; all forbidden operations will cause an operation failure via error code.

GNUTLS_FIPS140_SELFTESTS

A transient state during library initialization. That state cannot be set or seen by applications.

GNUTLS_FIPS140_LAX

The library still uses the FIPS140-2 relevant algorithms but all forbidden by FIPS140-2 operations are allowed; this is useful when the application is aware of the followed security policy, and needs to utilize disallowed operations for other reasons (e.g., compatibility).

GNUTLS_FIPS140_LOG

Similarly to GNUTLS_FIPS140_LAX , it allows forbidden operations; any use of them results to a message to the audit callback functions.

Figure 11.5: The gnutls_fips_mode_t enumeration.

The intention of this API is to be used by applications which may run in FIPS140-2 mode, while they utilize few algorithms not in the allowed set, e.g., for non-security related purposes. In these cases applications should wrap the non-compliant code within blocks like the following. 

GNUTLS_FIPS140_SET_LAX_MODE();

_gnutls_hash_fast(GNUTLS_DIG_MD5, buffer, sizeof(buffer), output);

GNUTLS_FIPS140_SET_STRICT_MODE();

The GNUTLS_FIPS140_SET_LAX_MODE and GNUTLS_FIPS140_SET_STRICT_MODE are macros to simplify the following sequence of calls. 

if (gnutls_fips140_mode_enabled())
  gnutls_fips140_set_mode(GNUTLS_FIPS140_LAX, GNUTLS_FIPS140_SET_MODE_THREAD);

_gnutls_hash_fast(GNUTLS_DIG_MD5, buffer, sizeof(buffer), output);

if (gnutls_fips140_mode_enabled())
  gnutls_fips140_set_mode(GNUTLS_FIPS140_STRICT, GNUTLS_FIPS140_SET_MODE_THREAD);

The reason of the GNUTLS_FIPS140_SET_MODE_THREAD flag in the previous calls is to localize the change in the mode. Note also, that such a block has no effect when the library is not operating under FIPS140-2 mode, and thus it can be considered a no-op.

Applications could also switch FIPS140-2 mode explicitly off, by calling 

gnutls_fips140_set_mode(GNUTLS_FIPS140_LAX, 0);

Service indicator

The above restrictions may not cover all the requirements in every usage context, and as the FIPS140 standard evolves (like FIPS140-3), GnuTLS may not be able to add new restrictions without breaking compatibility.

Therefore an additional set of API functions is provided to communicate with the user whether any approved mode of operations is performed within a given context.

int gnutls_fips140_context_init (gnutls_fips140_context_t * context)
void gnutls_fips140_context_deinit (gnutls_fips140_context_t context)
int gnutls_fips140_push_context (gnutls_fips140_context_t context)
int gnutls_fips140_pop_context ( void)

The gnutls_fips140_context_t represents the FIPS140-2 mode of operation. It can be attached to the current execution thread with gnutls_fips140_push_context and its internal state will be updated until it is detached with gnutls_fips140_pop_context. Afterwards gnutls_fips140_get_operation_state allows the user to examine whether any approved (or non-approved) security function is invoked.

Function: gnutls_fips140_operation_state_t gnutls_fips140_get_operation_state (gnutls_fips140_context_t context)

context: a gnutls_fips140_context_t

Get the previous operation state of context in terms of FIPS.

Returns: a gnutls_fips140_operation_state_t

Since: 3.7.3

Previous: , Up: Internal architecture of GnuTLS   [Contents][Index]