FIPS 140-3 compliance in Kong Gateway

Uses: Kong Gateway

Configure FIPS

To start in FIPS mode, set the following configuration property to on in the kong.conf configuration file before starting Kong Gateway:

fips = on # fips mode is enabled, causing incompatible ciphers to be disabled

Copied!

You can also set this configuration using an environment variable:

export KONG_FIPS=on

Copied!

Warning: Migrating from non-FIPS to FIPS mode, or the reverse, is not supported. Migrating directly between the FIPS 140-2 and FIPS 140-3 packages is also not supported, as the FIPS 140-3 distribution ships as a separate package. If you need to transition from the FIPS 140-2 package to the FIPS 140-3 package, follow the recommendations in the section Transitioning from FIPS 140-2 to FIPS 140-3.

Transitioning from FIPS 140-2 to FIPS 140-3

The FIPS 140-3 distribution ships as a separate package, so there is no in-place upgrade from a FIPS 140-2 install. Plan the transition as a fresh install of the FIPS 140-3 package on a supported Kong Gateway version, including preparation of your upstreams, clients, and stored configuration to match the tighter FIPS 140-3 boundary.

Prerequisites

Before migrating to FIPS 140-3, review existing legacy configurations and prepare for the transition.

Items to inventory before switching to FIPS 140-3

The FIPS 140-3 package doesn’t silently rewrite legacy stored artifacts, and it fails closed on configuration that references non-approved algorithms. Before enabling it, inventory the following:

Area	What to check
Peers on Kong’s TLS surface	Inbound clients and outbound upstream services. Any peer that doesn’t support TLS 1.2 with Extended Master Secret (EMS, RFC 7627) or TLS 1.3 will fail during the handshake.
Cipher configurations	Remove custom `ssl_ciphers` values and any `*_ssl_conf_command` overrides. The FIPS 140-3 package pins TLS 1.2 / 1.3 with approved AES-GCM profiles.
Plugin configuration	Referencing non-approved algorithms such as SAML request signatures, HMAC-Auth secrets, JWT Signer/JOSE/JWA algorithm choices, and any plugin still selecting SHA-1 or MD5.
Keyring	RSA transport keys smaller than 2048 bits must be rotated. Legacy AES-GCM exports created without an authentication tag remain importable via the explicit legacy path but must be re-exported afterward.
`key-auth-enc` credentials	Plan a batched `PATCH` or `POST` on each credential so it is re-hashed as SHA-256. Existing SHA-1 credentials keep working (read-only), but new credentials must be SHA-256.

What’s not available after switching to FIPS 140-3

The following are rejected outright when the FIPS 140-3 package runs with fips = on:

Rejected item	Details
TLS 1.0 and 1.1	Rejected at any surface Kong terminates.
TLS 1.2 without EMS	The handshake fails.
Non-AES-GCM cipher suites	The cipher list is fixed to approved AES-GCM profiles. Low-level SSL overrides no longer widen it.
MD5 and ChaCha20	Rejected under default OpenSSL properties.
SAML request SHA-1 signatures	Rejected.
HMAC-SHA1 authentication configuration	Rejected.
Ed25519 / Ed448 JWKS generation	Use RSA-PSS or a NIST-curve ECDSA key (for example P-256, P-384) instead.
Application-supplied IVs for AES-GCM	The FIPS provider generates the IV inside the cryptographic boundary.
Keyring RSA keys below 2048 bits	Rejected at configuration validation, before startup completes.
`hash_secret = true` on the OAuth2 plugin	The setting is disabled in FIPS mode. Use secrets management or database encryption instead.

Install and verify

Download and install a Kong Gateway FIPS 140-3 package on a supported OS.

The FIPS 140-3 package name and download URL use a -fips-140-3 suffix. For links to the correct package for your distribution, see the Kong Gateway install page, or see the FIPS 140-3 packages on Docker Hub.

Note: Currently, the FIPS 140-3 package is only available on Kong Gateway 3.14 LTS and 3.16.
Confirm fips = on in kong.conf or set KONG_FIPS=on as an environment variable.
Restart Kong Gateway.
Verify the loaded provider using the Admin API:
```
curl -s http://localhost:8001/fips-status
```
Copied!
Verify that your clients are working as expected with your new installation of Kong Gateway.

Password hashing

The following table describes how Kong Gateway uses key derivation functions:

Component	Normal mode	FIPS mode	Notes
core/rbac	bcrypt	PBKDF2 ¹	Compliant via OpenSSL 3.1.2 FIPS provider
plugins/oauth2 ²	Argon2 or bcrypt (when `hash_secret=true`)	Disabled (`hash_secret` can’t be set to `true`)	Compliant via OpenSSL 3.1.2 FIPS provider
plugins/key-auth-enc ³	SHA1	SHA256	SHA1 is read-only in FIPS mode.

[1]: As of Kong Gateway FIPS 3.0, RBAC uses PBKDF2 as the password hashing algorithm.

[2]: As of Kong Gateway FIPS 3.1, the OAuth2 plugin disables the hash_secret feature, so you can’t turn it on. This means the password is stored as plaintext in the database. You can use secrets management or database encryption instead.

[3]: As of Kong Gateway FIPS 3.1, key-auth-enc uses SHA1 to speed up lookup of a key in the database. As of Kong Gateway FIPS 3.2, SHA1 support is read-only, meaning existing credentials in the database are still validated, but any new credentials are hashed in SHA256.

Important: If you are migrating from Kong Gateway 3.1 to 3.2 in FIPS mode and are using the key-auth-enc plugin, you should send PATCH or POST requests to all existing key-auth-enc credentials to re-hash them in SHA256.

Non-cryptographic usage of cryptographic algorithms

FIPS only defines the approved algorithms to use for each specific purpose, so FIPS policy doesn’t explicitly restrict the usage of cryptographic algorithms to only cases where they are necessary.

For example, using SHA-256 as the message digest algorithm is approved, while MD5 is not. However, that doesn’t mean MD5 must be completely absent from the application.

The following table explains where cryptographic algorithms are used for non-cryptographic purposes in Kong Gateway:

Component	Normal mode	FIPS mode	Notes
core/balancer	xxhash32	xxhash32	Used to generate a unique identifier.
core/balancer	crc32	crc32	crc32 isn’t a message digest.
core/uuid	Lua random number generator	Lua random number generator	The RNG isn’t used for cryptographic purposes.
core/declarative_config/uuid	UUIDv5 (namespaced SHA1)	UUIDv5 (namespaced SHA1)	Used to generate a unique identifier.
core/declarative_config/config_hash and core/hybrid/hashes	MD5	MD5	Used to generate a unique identifier.
core/kong_request_id v3.5+	rand(3)	rand(3)	The RNG isn’t used for cryptographic purposes.

SSL client

FIPS 140-3 defines requirements for the cryptographic module, not for SSL client roles. Kong Gateway does not enforce a FIPS-specific policy on outbound clients. Traffic that traverses Kong Gateway’s own inbound and outbound TLS enforcement does honor the TLS 1.2/1.3 and EMS constraints described in the limitations section.

This includes:

Using Lua to communicate over HTTPS and PostgreSQL SSL.
Using an upstream that proxies over HTTPS.