Fixed some typographical and language usage issues in fips.adoc (#24056)
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>
This commit is contained in:
Stephen Morris
GitHub
parent
1ac2c0997d
commit
17389e6e29
1 changed files with 26 additions and 27 deletions
|
|
@ -7,8 +7,7 @@ title="FIPS 140-2 support"
|
|||
summary="How to configure Keycloak server for FIPS compliance"
|
||||
includedOptions="">
|
||||
|
||||
The Federal Information Processing Standard Publication 140-2, (FIPS 140-2), is a U.S. government computer security standard used to approve cryptographic modules. Keycloak supports to
|
||||
run in FIPS 140-2 compliant mode. In this case, Keycloak will use only FIPS approved cryptography algorithms for it's functionality.
|
||||
The Federal Information Processing Standard Publication 140-2, (FIPS 140-2), is a U.S. government computer security standard used to approve cryptographic modules. Keycloak supports running in FIPS 140-2 compliant mode. In this case, Keycloak will use only FIPS approved cryptography algorithms for its functionality.
|
||||
|
||||
To run in FIPS 140-2, Keycloak should run on a FIPS 140-2 enabled system. This requirement usually assumes RHEL or Fedora where FIPS was enabled during installation.
|
||||
See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html-single/security_hardening/index#assembly_installing-the-system-in-fips-mode_security-hardening[RHEL documentation]
|
||||
|
|
@ -22,7 +21,7 @@ To check that the system is in FIPS mode, you can check it with the following co
|
|||
fips-mode-setup --check
|
||||
----
|
||||
|
||||
If the system is not in FIPS mode, you can enable it with the following command, however it is recommended that system is in FIPS mode since the installation rather than later enabled this way:
|
||||
If the system is not in FIPS mode, you can enable it with the following command, however it is recommended that system is in FIPS mode since the installation rather than subsequently enabling it as follows:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
|
|
@ -31,10 +30,10 @@ fips-mode-setup --enable
|
|||
|
||||
== BouncyCastle library
|
||||
|
||||
Keycloak internally uses the BouncyCastle library for many cryptography utilities. However, the default flavor of the BouncyCastle library that shipped with Keycloak is not FIPS compliant,
|
||||
but, BouncyCastle also provides a FIPS validated version of it's library. The FIPS validated BouncyCastle library cannot be shipped with Keycloak due to license constraints and
|
||||
Keycloak internally uses the BouncyCastle library for many cryptography utilities. Please note that the default version of the BouncyCastle library that shipped with Keycloak is not FIPS compliant;
|
||||
however, BouncyCastle also provides a FIPS validated version of its library. The FIPS validated BouncyCastle library cannot be shipped with Keycloak due to license constraints and
|
||||
Keycloak cannot provide official support of it. Therefore, to run in FIPS compliant mode, you need to download BouncyCastle-FIPS bits and add them to the Keycloak distribution.
|
||||
When Keycloak executes in fips-mode, it will use the BCFIPS bits instead of the default BouncyCastle bits, which achieves FIPS compliance.
|
||||
When Keycloak executes in fips mode, it will use the BCFIPS bits instead of the default BouncyCastle bits, which achieves FIPS compliance.
|
||||
|
||||
=== BouncyCastle FIPS bits
|
||||
|
||||
|
|
@ -53,7 +52,7 @@ You can create either `pkcs12` or `bcfks` keystore to be used for the Keycloak s
|
|||
|
||||
The `p12` (or `pkcs12`) keystore (and/or truststore) works well in BCFIPS non-approved mode.
|
||||
|
||||
PKCS12 keystore can be generated with OpenJDK 17 Java on RHEL 9 in the standard way. For instance this command can be used to generate such keystore:
|
||||
PKCS12 keystore can be generated with OpenJDK 17 Java on RHEL 9 in the standard way. For instance, the following command can be used to generate the keystore:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
|
|
@ -63,20 +62,20 @@ keytool -genkeypair -sigalg SHA512withRSA -keyalg RSA -storepass passwordpasswor
|
|||
-dname CN=localhost -keypass passwordpassword
|
||||
----
|
||||
|
||||
When system is in FIPS mode, the default `java.security` file is changed in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in PKCS12 keystore you can store PBE (password-based encryption) keys simply via the keytool command, which makes it ideal for using it with Keycloak KeyStore Vault and/or to store configuration properties in the KeyStore Config Source. For more details, see the <@links.server id="configuration"/> and the <@links.server id="vault"/>.
|
||||
When the system is in FIPS mode, the default `java.security` file is changed in order to use FIPS enabled security providers, so no additional configuration is needed. Additionally, in the PKCS12 keystore, you can store PBE (password-based encryption) keys simply by using the keytool command, which makes it ideal for using it with Keycloak KeyStore Vault and/or to store configuration properties in the KeyStore Config Source. For more details, see the <@links.server id="configuration"/> and the <@links.server id="vault"/>.
|
||||
|
||||
=== BCFKS keystore
|
||||
|
||||
BCFKS keystore generation requires the use of the BouncyCastle FIPS libraries and a custom security file.
|
||||
|
||||
You can start with create a helper file, such as `/tmp/kc.keystore-create.java.security`. The content of the file needs only to have the following property:
|
||||
You can start by creating a helper file, such as `/tmp/kc.keystore-create.java.security`. The content of the file needs only to have the following property:
|
||||
|
||||
[source]
|
||||
----
|
||||
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS
|
||||
----
|
||||
|
||||
Next enter a command such as the following to generate the keystore:
|
||||
Next, enter a command such as the following to generate the keystore:
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
|
|
@ -102,8 +101,8 @@ To run the server with BCFIPS in non-approved mode, enter the following command:
|
|||
|
||||
<@kc.start parameters="--features=fips --hostname=localhost --https-key-store-password=passwordpassword --log-level=INFO,org.keycloak.common.crypto:TRACE,org.keycloak.crypto:TRACE"/>
|
||||
|
||||
NOTE: In non-approved mode, the default keystore type (as well as default truststore type) is PKCS12. Hence if you generated BCFKS keystore as described above,
|
||||
it is also needed to use command `--https-key-store-type=bcfks`. Similar might be needed for the truststore as well if you want to use it.
|
||||
NOTE: In non-approved mode, the default keystore type (as well as default truststore type) is PKCS12. Hence if you generated a BCFKS keystore as described above,
|
||||
it is also required to use the command `--https-key-store-type=bcfks`. A similar command might be needed for the truststore as well if you want to use it.
|
||||
|
||||
NOTE: You can disable logging in production if everything works as expected.
|
||||
|
||||
|
|
@ -113,10 +112,10 @@ There is the `fips-mode` option, which is automatically set to `non-strict` when
|
|||
The more secure alternative is to use `--features=fips --fips-mode=strict` in which case BouncyCastle FIPS will use "approved mode".
|
||||
Using that option results in stricter security requirements on cryptography and security algorithms.
|
||||
|
||||
NOTE: In strict mode, the default keystore type (as well as default truststore type) is BCFKS. If you want to use different keystore type
|
||||
it is needed to use option `--https-key-store-type` with appropriate type. Similar might be needed for the truststore as well if you want to use it.
|
||||
NOTE: In strict mode, the default keystore type (as well as default truststore type) is BCFKS. If you want to use a different keystore type
|
||||
it is required to use the option `--https-key-store-type` with appropriate type. A similar command might be needed for the truststore as well if you want to use it.
|
||||
|
||||
When starting server, you can check that the startup log contains `KC` provider with the note about `Approved Mode` such as the following:
|
||||
When starting the server, you can check that the startup log contains `KC` provider with the note about `Approved Mode` such as the following:
|
||||
|
||||
[source]
|
||||
----
|
||||
|
|
@ -125,7 +124,7 @@ KC(BCFIPS version 1.000203 Approved Mode, FIPS-JVM: enabled) version 1.0 - class
|
|||
|
||||
=== Cryptography restrictions in strict mode
|
||||
|
||||
* As mentioned in the previous section, strict mode may not work with `pkcs12` keystore. It is needed to use another keystore (like `bcfks`) as mentioned earlier. Also `jks` and `pkcs12` keystores are not
|
||||
* As mentioned in the previous section, strict mode may not work with `pkcs12` keystore. It is required to use another keystore (like `bcfks`) as mentioned earlier. Also `jks` and `pkcs12` keystores are not
|
||||
supported in Keycloak when using strict mode. Some examples are importing or generating a keystore of an OIDC or SAML client in the Admin Console or for a `java-keystore` provider in the realm keys.
|
||||
|
||||
* User passwords must be 14 characters or longer. Keycloak uses PBKDF2 based password encoding by default. BCFIPS approved mode requires passwords to be at least 112 bits
|
||||
|
|
@ -145,8 +144,8 @@ requirement as they are longer than 14 characters.
|
|||
* RSA keys of 1024 bits do not work (2048 is the minimum). This applies for keys used by the Keycloak realm itself (Realm keys from the `Keys` tab in the admin console), but also client keys and IDP keys
|
||||
|
||||
* HMAC SHA-XXX keys must be at least 112 bits (or 14 characters long). For example if you use OIDC clients with the client authentication `Signed Jwt with Client Secret` (or `client-secret-jwt` in
|
||||
the OIDC notation), then your client secrets should be at least 14 characters long. Note that for good security, it is recommended to use client secrets generated by Keycloak server, which
|
||||
always match this requirement.
|
||||
the OIDC notation), then your client secrets should be at least 14 characters long. Note that for good security, it is recommended to use client secrets generated by the Keycloak server, which
|
||||
always fulfils this requirement.
|
||||
|
||||
== Other restrictions
|
||||
|
||||
|
|
@ -167,7 +166,7 @@ Details are in the https://bugzilla.redhat.com/show_bug.cgi?id=1940064[bugzilla]
|
|||
NOTE: It is recommended to look at `JAVA_HOME/conf/security/java.security` and check all configured providers here and make sure that the number matches. In other words, `fips.provider.7`
|
||||
assumes that there are already 6 providers configured with prefix like `fips.provider.N` in this file.
|
||||
|
||||
If prefer not to edit your `java.security` file inside java itself, you can create a custom java security file (for example named `kc.java.security`) and add only the single
|
||||
If you prefer not to edit your `java.security` file inside java itself, you can create a custom java security file (for example named `kc.java.security`) and add only the single
|
||||
property above for adding XMLDSig provider into that file. Then start your Keycloak server with this property file attached:
|
||||
|
||||
[source]
|
||||
|
|
@ -202,14 +201,14 @@ fips.keystore.type=bcfks" > /tmp/kcadm.java.security
|
|||
export KC_OPTS="-Djava.security.properties=/tmp/kcadm.java.security"
|
||||
----
|
||||
|
||||
== Keycloak server in FIPS mode in the container
|
||||
== Keycloak server in FIPS mode in containers
|
||||
|
||||
When you want Keycloak in FIPS mode to be executed inside a container, your "host" must be using FIPS mode as well. The container
|
||||
will then "inherit" FIPS mode from the parent host.
|
||||
See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#enabling-fips-mode-in-a-container_using-the-system-wide-cryptographic-policies[this section]
|
||||
in the RHEL documentation for the details.
|
||||
|
||||
The keycloak container image will be just automatically in fips mode when executed from the host in FIPS mode.
|
||||
The keycloak container image will automatically be in fips mode when executed from the host in FIPS mode.
|
||||
However, make sure that the Keycloak container also uses BCFIPS jars (instead of BC jars) and proper options when started.
|
||||
|
||||
Regarding this, it is best to build your own container image as described in the <@links.server id="containers"/> and tweak it to use BCFIPS etc.
|
||||
|
|
@ -242,12 +241,12 @@ COPY --from=builder /opt/keycloak/ /opt/keycloak/
|
|||
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
|
||||
----
|
||||
|
||||
Then build FIPS an optimized docker image and start it as described in the <@links.server id="containers"/>. These steps require that you use arguments as described above when starting the image.
|
||||
Then build FIPS as an optimized Docker image and start it as described in the <@links.server id="containers"/>. These steps require that you use arguments as described above when starting the image.
|
||||
|
||||
== Migration from non-fips environment
|
||||
|
||||
If you previously used Keycloak in the non-fips environment, it is possible to migrate it to FIPS environment including it's data. However, restrictions and considerations exist as
|
||||
mentioned in previous sections. To highlight some of them:
|
||||
If you previously used Keycloak in a non-fips environment, it is possible to migrate it to a FIPS environment including its data. However, restrictions and considerations exist as
|
||||
mentioned in previous sections, namely:
|
||||
|
||||
* Make sure all the Keycloak functionality relying on keystores uses only supported keystore types. This differs based on whether strict or non-strict mode is used.
|
||||
* Kerberos authentication may not work. If your authentication flow uses `Kerberos` authenticator, this authenticator will be automatically switched to `DISABLED` when migrated to FIPS
|
||||
|
|
@ -260,7 +259,7 @@ In addition to the preceding requirements, be sure to doublecheck this before sw
|
|||
* Make sure that clients relying on `Signed JWT with Client Secret` use at least 14 characters long secrets (ideally generated secrets)
|
||||
|
||||
* Password length restriction as described earlier. In case your users have shorter passwords, be sure to start the server with the max padding length set to 14 of PBKDF2 provider as mentioned
|
||||
earlier. If you prefer to avoid this option, you can for instance ask all your users to reset their password (for example by the `Forget password` link) during the first authentication in the new environment.
|
||||
earlier. If you prefer to avoid this option, you can for instance ask all your users to reset their password (for example by the `Forgot password` link) during the first authentication in the new environment.
|
||||
|
||||
|
||||
== Keycloak FIPS mode on the non-fips system
|
||||
|
|
@ -268,10 +267,10 @@ earlier. If you prefer to avoid this option, you can for instance ask all your u
|
|||
Keycloak is tested on a FIPS enabled RHEL 8 system and `ubi8` image. It is supported with RHEL 9 (and `ubi9` image) as well. Running on
|
||||
the non-RHEL compatible platform or on the non-FIPS enabled platform, the FIPS compliance cannot be strictly guaranteed and cannot be officially supported.
|
||||
|
||||
If you are still restricted to run Keycloak on such a system, you can at least update your security providers configured in `java.security` file. This update does not mean FIPS compliance, but
|
||||
If you are still restricted to running Keycloak on such a system, you can at least update your security providers configured in `java.security` file. This update does not amount to FIPS compliance, but
|
||||
at least the setup is closer to it. It can be done by providing a custom security file with only an overriden list of security providers as described earlier. For a list of recommended providers,
|
||||
see the https://access.redhat.com/documentation/en-us/openjdk/17/html/configuring_openjdk_17_on_rhel_with_fips/openjdk-default-fips-configuration[OpenJDK 17 documentation].
|
||||
|
||||
You can check the Keycloak server log at startup to see if the correct security providers are used. TRACE logging should be enabled for crypto-related Keycloak packages as described in the Keycloak startup command earlier.
|
||||
|
||||
</@tmpl.guide>
|
||||
</@tmpl.guide>
|
||||
|
|
|
|||
Loading…
Reference in a new issue