1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre Proncheryfips_config - OpenSSL FIPS configuration 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 DESCRIPTION 8*b077aed3SPierre Pronchery 9*b077aed3SPierre ProncheryA separate configuration file, using the OpenSSL L<config(5)> syntax, 10*b077aed3SPierre Proncheryis used to hold information about the FIPS module. This includes a digest 11*b077aed3SPierre Proncheryof the shared library file, and status about the self-testing. 12*b077aed3SPierre ProncheryThis data is used automatically by the module itself for two 13*b077aed3SPierre Proncherypurposes: 14*b077aed3SPierre Pronchery 15*b077aed3SPierre Pronchery=over 4 16*b077aed3SPierre Pronchery 17*b077aed3SPierre Pronchery=item - Run the startup FIPS self-test known answer tests (KATS). 18*b077aed3SPierre Pronchery 19*b077aed3SPierre ProncheryThis is normally done once, at installation time, but may also be set up to 20*b077aed3SPierre Proncheryrun each time the module is used. 21*b077aed3SPierre Pronchery 22*b077aed3SPierre Pronchery=item - Verify the module's checksum. 23*b077aed3SPierre Pronchery 24*b077aed3SPierre ProncheryThis is done each time the module is used. 25*b077aed3SPierre Pronchery 26*b077aed3SPierre Pronchery=back 27*b077aed3SPierre Pronchery 28*b077aed3SPierre ProncheryThis file is generated by the L<openssl-fipsinstall(1)> program, and 29*b077aed3SPierre Proncheryused internally by the FIPS module during its initialization. 30*b077aed3SPierre Pronchery 31*b077aed3SPierre ProncheryThe following options are supported. They should all appear in a section 32*b077aed3SPierre Proncherywhose name is identified by the B<fips> option in the B<providers> 33*b077aed3SPierre Proncherysection, as described in L<config(5)/Provider Configuration Module>. 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=over 4 36*b077aed3SPierre Pronchery 37*b077aed3SPierre Pronchery=item B<activate> 38*b077aed3SPierre Pronchery 39*b077aed3SPierre ProncheryIf present, the module is activated. The value assigned to this name is not 40*b077aed3SPierre Proncherysignificant. 41*b077aed3SPierre Pronchery 42*b077aed3SPierre Pronchery=item B<install-version> 43*b077aed3SPierre Pronchery 44*b077aed3SPierre ProncheryA version number for the fips install process. Should be 1. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre Pronchery=item B<conditional-errors> 47*b077aed3SPierre Pronchery 48*b077aed3SPierre ProncheryThe FIPS module normally enters an internal error mode if any self test fails. 49*b077aed3SPierre ProncheryOnce this error mode is active, no services or cryptographic algorithms are 50*b077aed3SPierre Proncheryaccessible from this point on. 51*b077aed3SPierre ProncheryContinuous tests are a subset of the self tests (e.g., a key pair test during key 52*b077aed3SPierre Proncherygeneration, or the CRNG output test). 53*b077aed3SPierre ProncherySetting this value to C<0> allows the error mode to not be triggered if any 54*b077aed3SPierre Proncherycontinuous test fails. The default value of C<1> will trigger the error mode. 55*b077aed3SPierre ProncheryRegardless of the value, the operation (e.g., key generation) that called the 56*b077aed3SPierre Proncherycontinuous test will return an error code if its continuous test fails. The 57*b077aed3SPierre Proncheryoperation may then be retried if the error mode has not been triggered. 58*b077aed3SPierre Pronchery 59*b077aed3SPierre Pronchery=item B<security-checks> 60*b077aed3SPierre Pronchery 61*b077aed3SPierre ProncheryThis indicates if run-time checks related to enforcement of security parameters 62*b077aed3SPierre Proncherysuch as minimum security strength of keys and approved curve names are used. 63*b077aed3SPierre ProncheryA value of '1' will perform the checks, otherwise if the value is '0' the checks 64*b077aed3SPierre Proncheryare not performed and FIPS compliance must be done by procedures documented in 65*b077aed3SPierre Proncherythe relevant Security Policy. 66*b077aed3SPierre Pronchery 67*b077aed3SPierre Pronchery=item B<module-mac> 68*b077aed3SPierre Pronchery 69*b077aed3SPierre ProncheryThe calculated MAC of the FIPS provider file. 70*b077aed3SPierre Pronchery 71*b077aed3SPierre Pronchery=item B<install-status> 72*b077aed3SPierre Pronchery 73*b077aed3SPierre ProncheryAn indicator that the self-tests were successfully run. 74*b077aed3SPierre ProncheryThis should only be written after the module has 75*b077aed3SPierre Proncherysuccessfully passed its self tests during installation. 76*b077aed3SPierre ProncheryIf this field is not present, then the self tests will run when the module 77*b077aed3SPierre Proncheryloads. 78*b077aed3SPierre Pronchery 79*b077aed3SPierre Pronchery=item B<install-mac> 80*b077aed3SPierre Pronchery 81*b077aed3SPierre ProncheryA MAC of the value of the B<install-status> option, to prevent accidental 82*b077aed3SPierre Proncherychanges to that value. 83*b077aed3SPierre ProncheryIt is written-to at the same time as B<install-status> is updated. 84*b077aed3SPierre Pronchery 85*b077aed3SPierre Pronchery=back 86*b077aed3SPierre Pronchery 87*b077aed3SPierre ProncheryFor example: 88*b077aed3SPierre Pronchery 89*b077aed3SPierre Pronchery [fips_sect] 90*b077aed3SPierre Pronchery activate = 1 91*b077aed3SPierre Pronchery install-version = 1 92*b077aed3SPierre Pronchery conditional-errors = 1 93*b077aed3SPierre Pronchery security-checks = 1 94*b077aed3SPierre Pronchery module-mac = 41:D0:FA:C2:5D:41:75:CD:7D:C3:90:55:6F:A4:DC 95*b077aed3SPierre Pronchery install-mac = FE:10:13:5A:D3:B4:C7:82:1B:1E:17:4C:AC:84:0C 96*b077aed3SPierre Pronchery install-status = INSTALL_SELF_TEST_KATS_RUN 97*b077aed3SPierre Pronchery 98*b077aed3SPierre Pronchery=head1 NOTES 99*b077aed3SPierre Pronchery 100*b077aed3SPierre ProncheryWhen using the FIPS provider, it is recommended that the 101*b077aed3SPierre ProncheryB<config_diagnostics> option is enabled to prevent accidental use of 102*b077aed3SPierre Proncherynon-FIPS validated algorithms via broken or mistaken configuration. 103*b077aed3SPierre ProncherySee L<config(5)>. 104*b077aed3SPierre Pronchery 105*b077aed3SPierre Pronchery=head1 SEE ALSO 106*b077aed3SPierre Pronchery 107*b077aed3SPierre ProncheryL<config(5)> 108*b077aed3SPierre ProncheryL<openssl-fipsinstall(1)> 109*b077aed3SPierre Pronchery 110*b077aed3SPierre Pronchery=head1 HISTORY 111*b077aed3SPierre Pronchery 112*b077aed3SPierre ProncheryThis functionality was added in OpenSSL 3.0. 113*b077aed3SPierre Pronchery 114*b077aed3SPierre Pronchery=head1 COPYRIGHT 115*b077aed3SPierre Pronchery 116*b077aed3SPierre ProncheryCopyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 117*b077aed3SPierre Pronchery 118*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 119*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 120*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 121*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 122*b077aed3SPierre Pronchery 123*b077aed3SPierre Pronchery=cut 124