Documentation, OIDC updates for FIPS 140-3 #8069
Description
Update the following section with information about FIPS 140-3:
https://openliberty.io/docs/latest/reference/feature/openidConnectClient-1.0.html#jwe
This can go at the end of the Accept tokens in JWE format section:
The Semeru FIPS 140-3 requires the use of ECDH algorithms for key agreement during encryption. The FIPS module in use by the IBM Semeru runtime is planning to certify RSA-OAEP operations in a future release. In the meantime, to use RSA-OAEP when FIPS 140-3 is enabled, see the section titled OIDC Client, Social Login, or JWT using RSA-OAEP example below.
Use of ECDH algorithms requires the use of EC keys. See the section titled Generate EC Keys for ECDH section below.
To setup your OIDC Client, Social Login, or JWT consumer to use ECDH-ES, you’ll need to add the EC private key to the keystore and configure the following depending on if you’re using openidConnectClient, oidcLogin, or jwtConsumer.
<openidConnectClient keyManagementKeyAlias="myECPrivateKey" />
<oidcLogin keyManagementKeyAlias="myECPrivateKey" />
<jwtConsumer keyManagementKeyAlias="myECPrivateKey" />
Where myECPrivateKey is the alias for the EC private key.
To setup your JWT builder to use ECDH-ES, you’ll need to add the EC public key to the keystore and configure the following.
<jwtBuilder keyManagementKeyAlgorithm="ECDH-ES" keyManagementKeyAlias="myECPublicKey" />
Where myECPublicKey is the alias for the EC public key.
OIDC Client, Social Login, or JWT using RSA-OAEP example
If your OIDC Client, Social Login, or JWT configuration cannot support ECDH-ES, and you must use RSA-OAEP, you can try and add the following to the FIPS140-3-Liberty-Application.properties custom profile file created when FIPS 140-3 is configured:
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Liberty-Application.jce.provider.2 = sun.security.provider.Sun [+ \
{MessageDigest, SHA-1, *, FullClassName:org.jose4j.jwa.AlgorithmFactory}, \
{MessageDigest, SHA-1, *, FullClassName:org.jose4j.jwe.CipherUtil}, \
{MessageDigest, SHA-1, *, FullClassName:org.jose4j.jwe.WrappingKeyManagementAlgorithm}]
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Liberty-Application.jce.provider.4 = com.sun.crypto.provider.SunJCE [+ \
{Cipher, RSA, *, FullClassName:org.jose4j.jwa.AlgorithmFactory}, \
{Cipher, RSA, *, FullClassName:org.jose4j.jwe.CipherUtil}]
Note that this is just an example, and you may need different constraints based on your application.
This will add the constraints to the already registered Sun and SunJCE providers to allow for RSA-OAEP key agreement algorithm. The constraints to be added will be discovered through the troubleshooting process as described in Troubleshooting FIPS 140-3 on Liberty.
Generate EC Keys for ECDH
To use ECDH, one needs to configure the EC keys in the keystores.
The EC public and private key pair can be generated using securityUtility or keytool, for example:
./securityUtility createSSLCertificate --sigAlg=SHA256withECDSA --keySize=256 --server=myServer --validity=3650 --password=password
keytool -genkeypair -alias eccert -keyalg EC -groupname secp256r1 -validity 3650 -storetype pkcs12 -keystore