7.4.2 Using the OpenSSL FIPS Object Module

If the kernel command line specifies a fips=1 entry, the value of /proc/sys/crypto/fips_enabled is set to 1, which causes the OpenSSL library module to initialize the FIPS-approved mode of operation automatically. To handle automatic initialization, an application that uses the module must call one of the following routines:

void OPENSSL_add_all_algorithms(void)

Calls OPENSSL_init() implicitly and adds all approved algorithms to the EVP API in FIPS-approved mode.

void OPENSSL_init_library(void)

Performs basic initialization of the library and initialize FIPS-approved mode without setting up the EVP API with supported algorithms.

void SSL_library_init(void)

Calls OPENSSL_init() implicitly, adds algorithms that are necessary for TLS protocol support and initializes the SSL library.

To put the library into FIPS-approved mode explicitly, an application can call the int FIPS_mode_set(int on) function. If the value of on is set to 1, the library switches from non-approved to approved mode. If any self tests or integrity verification tests fail, the library is put into the error state and the function returns 0. If the tests succeed, the function returns 1. If the value of on is set to 0, the library switches to non-approved mode. Alternatively, the application can call OPENSSL_conf(const char *config_name) to enable FIPS mode by reading the alg_section that is defined for the config_name entry in the standard configuration file (openssl.conf), for example:

[ config_name ]
alg_section = algsec
...
[ algsec ]
fips_mode = yes

OPENSSL_config() does not return a value. If there is an error in the configuration, the function writes a message to the standard error and forces the application to exit. To provide better error control, an application can call the CONF_modules_load_file() function instead.

An application can use the following functions to query the OpenSSL library module:

int FIPS_mode(void)

Returns 1 if the module is in FIPS-approved mode; otherwise it returns 0.

int FIPS_selftest_failed(void)

Returns 1 if the module is in the error state; otherwise it returns 0.

To set the FIPS random number generator key and internal state to zero, an application can call the void RAND_cleanup(void) function.

Note

If you set the value of the OPENSSL_FIPS environment variable to 1, the openssl binary that is included in the openssl-fips-1.0.1* package, and which has been built using the FIPS-compliant OpenSSL library, uses only FIPS 140-2 approved algorithms. The value of OPENSSL_FIPS has no effect on the FIPS mode of the system. Do not assume that the value of OPENSSL_FIPS has any effect on other applications that use the FIPS-compliant OpenSSL library.

For more information about using the OpenSSL library with FIPS, see http://www.openssl.org/docs/fips/UserGuide-2.0.pdf.