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