Documentation, OIDC updates for FIPS 140-3

[jimmy1wu]

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.

More information on ECDH and RSA-OAEP can be found in the SAML section above including creating the EC keys that are required for the ECDH support

Generate EC Keys for ECDH

To use ECDH, one needs to configure the EC keys in the keystores. This would apply to the SAML, JWE and WebServices sections below.

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 

[jimmy1wu]

Box:
https://ibm.box.com/s/4ffd2g9zf8ouzibukfn74k0y7kjne44e