Difference between revisions of "FIPS mode()"

From OpenSSLWiki
Jump to: navigation, search
m (moved FIPS mode to FIPS mode(): Have page name map function name as closely as possible)
(Removed the previously added notice and updated the page as per Matt's suggestions on the FIPS mode talk page.)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
----
+
The '''FIPS_mode()''' function is used to determine the current [[FIPS]] [[FIPS 140-2|140-2]] mode of operation by a program utilizing the services of the 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 [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.16.pdf security policy].
'''NAME'''
 
  
FIPS_mode - retrieve the current FIPS 140-2 mode of operation
+
The return value is either <tt>0</tt> to indicate that the FIPS mode of operation is not enabled, or the value used for the <tt>ONOFF</tt> parameter passed to an earlier successful call to <tt>FIPS_mode_set()</tt>. Effectively, any non-zero value indicates FIPS mode. Values other than <tt>1</tt> may have additional significance, such as designating an additional restriction to [[Suite B]] algorithms.
  
 +
The only current [[FIPS]]-capable release of OpenSSL is version 1.0.2. Calling the function from an application linked to OpenSSL versions <tt>1.1.0</tt> or <tt>1.1.1</tt> will always return <tt>0</tt>, indicating non-FIPS mode, with an error code of <tt>CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0x0f06d065)</tt>.
  
----
 
'''SYNOPSIS'''
 
  
#include <openssl/crypto.h>
+
= History =
 +
FIPS support was introduced in version 0.9.7 of [https://www.openssl.org/ OpenSSL].
  
int FIPS_mode(void);
 
  
 +
= Example =
 +
To call the function, the OpenSSL <tt>crypto</tt> header must be included.
  
----
+
#include <openssl/crypto.h>
'''DESCRIPTION'''
 
 
 
FIPS_mode() is used to determine the FIPS mode of operation by a program utilizing the services of the 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 Open''''''SSL Security Policy.
 
 
 
The return value is either 0 to indicate that the FIPS mode of operation is not enabled, or the value used for the ONOFF parameter passed to an earlier successful call to FIPS_mode_set(). Effectively any non-zero value indicates FIPS mode; values other than 1 may have additional significance such as designating an additional restriction to Suite B algorithms.
 
 
 
If the library was built without support of the FIPS Object Module, then the function will return 0 with an error code of CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0x0f06d065).
 
  
 +
The function itself takes no parameters, and returns an integer indicating the mode of operation as described above.
  
----
+
int FIPS_MODE(void);
'''RETURN VALUES'''
 
  
A return code of non-zero indicates FIPS mode, 0 indicates non-FIPS mode. When called from a version of Open''''''SSL that is not "FIPS capable" (capable of utilizing an embedded FIPS Object Module), then FIPS_mode() will always return 0.
+
In the following example, the program tests the return value of the <tt>FIPS_mode()</tt> function call, exiting with an error if the library being linked to is not FIPS-capable. The return value of the function is saved because the return code may carry additional information, in addition to FIPS-capability (see above).
  
 +
int fips_compatible_build = -1;
 +
 +
if ((fips_compatible_build = FIPS_mode()) == 0) {
 +
    fprintf(stderr, "The current version of OpenSSL is not FIPS-capable.\n");
 +
    exit(EXIT_FAILURE);
 +
}
 +
 +
// ...
  
----
 
'''SEE ALSO'''
 
  
FIPS_mode_set(3), FIPS_selftest(3)
+
= See Also =
 +
* FIPS_mode_set(3)
 +
* FIPS_selftest(3)
  
  
----
+
= Notes =
'''NOTES'''
+
<tt>FIPS_mode()</tt> was formerly included with <openssl/fips.h>.
  
FIPS_mode() was formerly included with <openssl/fips.h>.
 
  
 +
= External Links =
 +
* Information regarding the [https://www.openssl.org/docs/fips.html OpenSSL FIPS 140-2 validation] at the [https://www.openssl.org/ OpenSSL] project.
 +
* [https://www.openssl.org/docs/fips/SecurityPolicy-2.0.16.pdf OpenSSL Security Policy]
  
----
 
'''HISTORY'''
 
  
FIPS support was introduced in version 0.9.7 of Open''''''SSL.
+
[[Category:FIPS 140-2]]
 +
[[Category:Crypto API]]
 +
[[Category:C level]]

Latest revision as of 19:03, 9 August 2019

The FIPS_mode() function is used to determine the current FIPS 140-2 mode of operation by a program utilizing the services of the 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 security policy.

The return value is either 0 to indicate that the FIPS mode of operation is not enabled, or the value used for the ONOFF parameter passed to an earlier successful call to FIPS_mode_set(). Effectively, any non-zero value indicates FIPS mode. Values other than 1 may have additional significance, such as designating an additional restriction to Suite B algorithms.

The only current FIPS-capable release of OpenSSL is version 1.0.2. Calling the function from an application linked to OpenSSL versions 1.1.0 or 1.1.1 will always return 0, indicating non-FIPS mode, with an error code of CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0x0f06d065).


History[edit]

FIPS support was introduced in version 0.9.7 of OpenSSL.


Example[edit]

To call the function, the OpenSSL crypto header must be included.

#include <openssl/crypto.h>

The function itself takes no parameters, and returns an integer indicating the mode of operation as described above.

int FIPS_MODE(void);

In the following example, the program tests the return value of the FIPS_mode() function call, exiting with an error if the library being linked to is not FIPS-capable. The return value of the function is saved because the return code may carry additional information, in addition to FIPS-capability (see above).

int fips_compatible_build = -1;

if ((fips_compatible_build = FIPS_mode()) == 0) {
    fprintf(stderr, "The current version of OpenSSL is not FIPS-capable.\n");
    exit(EXIT_FAILURE);
}

// ...


See Also[edit]

  • FIPS_mode_set(3)
  • FIPS_selftest(3)


Notes[edit]

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


External Links[edit]