Documentation, FIPS 140-3: Support FIPS 140-3 in Liberty with IBM Semeru #7962
Description
Feature epic details
- For the title of this issue, type: Documentation, Development epic name
- Link to development epic: Support FIPS 140-3 in Liberty with IBM Semeru open-liberty#31843
- Target GA release: 25.0.0.12
Operating systems
Does the documentation apply to all operating systems?
- Yes
- No; specify operating systems:
AIX on 64-bit IBM POWER hardware
Linux on x86-64 hardware
Linux (Little Endian) on 64-bit IBM POWER hardware
Windows on x86-64 hardware
NOTE: these are the only supported operating systems.
Summary
Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?
- We are releasing support for FIPS 140-3 using IBM Semeru for OpenLiberty.
- This feature will allow users to run their OpenLiberty servers using FIPS 140-3 certified cryptography.
- FIPS 140-3 does not rely on any operating system level functionality, the entire standard can be enabled on the JVM level (unlike the FIPS 140-2 which required RHEL and manual steps for creating key stores, etc).
Configuration
List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:
- To use FIPS 140-3 on IBM Semeru, you will need to use an IBM Semeru minimum version of 11.0.29, 17.0.17, 21.0.9, 25.0.1 or higher.
Enabling FIPS 140-3
The securityUtility has a new task for enabling FIPS 140-3. The task is called configureFIPS.
This new task is applicable for both IBM Semeru Runtimes and IBM SDK 8
The configureFIPS task operates at 3 levels
- Install
- Server
- Client
To enable across all servers, clients and tools, you can enable FIPS 140-3 at the Install level by running
securityUtility configureFIPS
To enable or configure a particular server
securityUtility configureFIPS --server=<server name>
To enable or configure a particular client
securityUtility configureFIPS --client=<client name>
For IBM Semeru Runtimes, these commands will configure the FIPS enablement requirements and create a Java security properties file that can be edited to set the required constraints of the application.
More information about setting the constraints can be found in Creating extensions of profiles.
To create a profile in a particular location or with a particular name --customProfileFile=<file path/s separated by the OS-specific path separator> can be specified and file/s are created that can be edited. The name of the file is used as the name of the profile. The configuration is set to point at the supplied files.
Multiple files can be specified in the property. All the files will be created and will extend the one before itself. the final file that is specified being the last in the chain.
If as part of the securityUtility configureFIPS command you do not specify the --customProfileFile the file is created in the following locations depending on whether you specified a server or client
- If neither server or client is specified
<Liberty install location>/wlp/etc/FIPS140-3-Liberty-Application.properties - if server is specified
<server root>/resources/security/FIPS140-3-Liberty-Application.properties - if client is specified
<client root>/resources/security/FIPS140-3-Liberty-Application.properties
To disable FIPS 140-3 at the required level it is enabled at add the following option to the command.
--disable
Updates to existing topics
To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ
https://openliberty.io/docs/latest/enable-fips.html
- Change
To enable FIPS for Liberty with the IBM SDK, Java Technology Edition, see - To
To enable FIPS for Liberty with the IBM SDK, Java Technology Edition, or IBM Semeru Runtimes see - Change
Enable FIPS for Open Liberty on IBM Semeru Runtimes - To
Enable FIPS 140-2 for Open Liberty on IBM Semeru Runtimes
https://openliberty.io/docs/latest/network-hardening.html#jmx-connector
- Add new sentence at the beginning:
Avoid the use of [localConnector-1.0](https://openliberty.io/docs/latest/reference/feature/localConnector-1.0.html) in production. Instead, use [restConnector-2.0](https://openliberty.io/docs/latest/reference/feature/restConnector-2.0.html).
https://openliberty.io/docs/latest/reference/command/securityUtility-createLTPAKeys.html
- Change:
When FIPS 140-3 is enabled, set the system properties by using the following JVM_ARGS environment variable to enable the 'securityUtility' tool to create LTPA keys with the 'createLTPAKeys' command:
Copy code block
export JVM_ARGS="-Xenablefips140-3 -Dcom.ibm.jsse2.usefipsprovider=true -Dcom.ibm.jsse2.usefipsProviderName=IBMJCEPlusFIPS"
After the system properties are set, replace the existing LTPA keys with the newly created LTPA keys.
For more information about FIPS 140-3, see [Run FIPS-compliant applications on Open Liberty](https://openliberty.io/docs/latest/enable-fips.html).
- To:
For information about creating LTPA keys using FIPS 140-3 approved algorithms, see [Setting up Liberty for FIPS compliance](https://www.ibm.com/docs/en/was-liberty/nd?topic=liberty-setting-up-fips-compliance).
Create a new topic
To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.
[NEW] securityUtility configureFIPS
- There should be a link from https://openliberty.io/docs/latest/reference/command/securityUtility-commands.html to this new command
- Websphere Liberty docs for configureFIPS if it helps https://www.ibm.com/docs/en/was-liberty/nd?topic=applications-securityutility-command#rwlp_command_securityutil__configureFIPS
description
The securityUtility configureFIPS command configures FIPS 140-3 for servers, clients, and tools.
usage example
Enable FIPS 140-3 across all servers, clients, and tools.
securityUtility configureFIPS
syntax
Run the command from the path_to_liberty/wlp/bin directory.
securityUtility configureFIPS [options]
options
--server=server_name
Configures FIPS 140-3 at a specified server.
--client=client_name
Configures FIPS 140-3 at a specified client.
--customProfileFile=name
For IBM Semeru Runtime, creates a custom profile file with a specified name or at a specified location. The default name of the custom profile file is FIPS140-3-Liberty-Application.properties.
- If this option is not provided, the custom profile file is located in the /etc directory of your Liberty installation.
- If this option is not provided and the --server option is used, the custom profile file is located in the /security directory of the specified server.
- If this option is not provided and the --client option is used, the custom profile file is located in the /security directory of the specified client.
--disable
Disables FIPS 140-3 from all servers and clients that were not individually configured. Use the --server and --client options with the --disable option to disable FIPS 140-3 from specified servers and clients respectively.
exit codes
0 | This code indicates successful completion of the requested operation.
1 | This code indicates a generic error.
2 | This code indicates that the server is not found.
3 | This code indicates that the client is not found.
4 | This code indicates that the path can not be created.