Difference between revisions of "FIPS mode()"

From OpenSSLWiki
Jump to: navigation, search
(Importing text file)
 
(Removed the previously added notice and updated the page as per Matt's suggestions on the FIPS mode talk page.)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=pod
+
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].
  
=head1 NAME
+
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.
  
FIPS_mode - retrieve the current FIPS 140-2 mode of operation
+
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>.
  
=head1 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.
  
=head1 DESCRIPTION
+
#include <openssl/crypto.h>
  
FIPS_mode() is used to determine the FIPS mode of operation by a
+
The function itself takes no parameters, and returns an integer indicating the mode of operation as described above.
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 OpenSSL Security Policy.
 
  
The return value is either 0 to indicate that the FIPS mode of
+
int FIPS_MODE(void);
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,
+
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).
then the function will return 0 with an error code of
 
CRYPTO_R_FIPS_MODE_NOT_SUPPORTED (0x0f06d065).
 
  
=head1 RETURN VALUES
+
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);
 +
}
 +
 +
// ...
  
A return code of non-zero indicates FIPS mode, 0 indicates non-FIPS mode.
 
When called from a version of OpenSSL that is not "FIPS capable" (capable
 
of utilizing an embedded FIPS Object Module), then FIPS_mode() will always
 
return 0.
 
  
=head1 SEE ALSO
+
= See Also =
 +
* FIPS_mode_set(3)
 +
* FIPS_selftest(3)
  
L<FIPS_mode_set(3)|FIPS_mode_set(3)>, L<FIPS_selftest(3)|FIPS_selftest(3)>
 
  
=head1 NOTES
+
= Notes =
 +
<tt>FIPS_mode()</tt> was formerly included with <openssl/fips.h>.
  
FIPS_mode() was formerly included with <openssl/fips.h>.
 
  
=head1 HISTORY
+
= 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]
  
FIPS support was introduced in version 0.9.7 of OpenSSL.
 
  
=cut
+
[[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]