View source for FIPS mode set()

The FIPS_mode_set(3) function has the following prototype: int FIPS_mode_set(int onoff);

when set to non-zero you go into FIPS mode.
when set to zero you go into non-FIPS mode.

[[Category:FIPS 140]]
[[Category:C level]]
[[Category:Crypto API]]

----
'''NAME'''

FIPS_mode - enter or exit FIPS 140-2 mode of operation


----
'''SYNOPSIS'''

 #include <openssl/crypto.h>

 int FIPS_mode_set(int ONOFF);


----
'''DESCRIPTION'''

FIPS_mode_set() is used to set the FIPS mode of operation of a running program utilizing the services of a validated library. The library must have been built with the FIPS Object Module, and the FIPS Object Module must have been acquired, built, and installed in accordance with the OpenSSL Security Policy.

When invoked with non-zero value for ONOFF value, FIPS_mode_set() will attempt to enter FIPS mode of operation. If the FIPS Object Module successfully enters FIPS mode, the function will return that non-zero value.

Currently all non-zero values of ONOFF enable FIPS mode. In the future other values may specify additional actions beyond enabling FIPS mode, such as a value of 2 to designate an additional restriction to Suite B algorithms. To avoid further compatibility issues, a program is encouraged to call FIPS_mode_set() with a ONOFF value of 1 (rather than an arbitrary non-zero value).

During a call to FIPS_mode_set() with a non-zero value of ONOFF, a number of tests are performed. See FIPS_selftest() for details on the testing performed by the validated FIPS Object Module.

When invoked with ONOFF value of 0, FIPS_mode_set() will attempt to exit the FIPS mode of operation. If the FIPS Object Module successfully exits FIPS mode, the function will return 1.

If FIPS_mode_set() returns a value of 0, then the request to enter or exit the FIPS mode of operation failed. In this case, the caller should call ERR_get_error() to retrieve the error code associated with the failure. The error code can later be used by ERR_error_string(<err>) or `openssl errstr <err>' for a readable string.

FIPS_mode_set() can fail for a number of reasons, and many of the error codes are discussed in detail in the OpenSSL FIPS Object Module User Guide 2.0. One common code is CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0xf06d065). The particular error code indicates the application was likely linked against an OpenSSL library without validated cryptography. That is, a FIPS Capable Library was *not* used during application linking.


----
'''RETURN VALUES'''

A non-zero return value indicates success, 0 failure.


----
'''EXAMPLE'''

<pre>
int mode = FIPS_mode(), ret = 0; unsigned long err = 0;

/* Toggle FIPS mode */
if(mode == 0)
{
    ret = FIPS_mode_set(1 /*on*/);
    if(ret != 1)
    {
        err = ERR_get_error();
    }
}
else
{
    ret = FIPS_mode_set(0 /*off*/);
    if(ret != 1)
    {
        err = ERR_get_error();
    }
}

if(ret != 1)
    printf("FIPS_mode_set failed: %lx.", err);
</pre>

[[Category:Examples]]

----
'''SEE ALSO'''

FIPS_mode(3), FIPS_selftest(3), ERR_get_error(3), ERR_error_string(3), openssl(8)


----
'''NOTES'''

FIPS_mode_set() was formerly included with <openssl/fips.h>.


----
'''HISTORY'''

FIPS support was introduced in version 0.9.7 of OpenSSL.

[[Category:FIPS 140-2]]