News KrakenD CE v2.6 released with OpenTelemetry

Community Documentation

Recent changes

You are viewing a previous version of KrakenD Community Edition (v2.2) , go to the latest version

Enabling TLS for HTTPS and HTTP/2

Document updated on Feb 28, 2023

There are two different strategies when using TLS over KrakenD:

  • Use TLS for HTTPS and HTTP/2 in KrakenD (this document)
  • Use a balancer with TLS termination in front of KrakenD (e.g., ELB, HAproxy)

If you want to enable TLS, add a tls key at the service level (configuration’s file root) with at least the public and private keys. When you add TLS, KrakenD listens only using TLS, and no traffic to plain HTTP is accepted.

If you want to enable mTLS see Mutual TLS configuration

TLS Configuration

Secure by default
When you don’t set any other parameters than stated below, KrakenD defaults to very strong security. Only TLS 1.3 is accepted (with its three cipher suites), and attempts to negotiate other versions will fail. Nevertheless, you can change this behavior.

To start KrakenD with TLS, you need to provide a certificate for both the public and the private keys:

{
  "version": 3,
  "tls": {
    "public_key": "/path/to/cert.pem",
    "private_key": "/path/to/key.pem"
  }
}

All TLS options are described below:

Fields of TLS/SSL "tls"
* required fields
Minimum configuration needs any of: public_key + private_key , or null object
ca_certs

array
An array with all the CA certificates you would like to load to KrakenD when using mTLS, in addition to the certificates present in the system’s CA.
Example: ["ca.pem"]
Defaults to []
cipher_suites

array
The list of cipher suites as defined in the documentation.
Defaults to [4865,4866,4867]
curve_preferences

array
The list of all the identifiers for the curve preferences. Use 23 for CurveP256, 24 for CurveP384 or 25 for CurveP521.
Defaults to [23,24,25]
disable_system_ca_pool

boolean
Ignore any certificate in the system’s CA. The only certificates loaded will be the ones in the ca_certs list when true.
Defaults to false
disabled

boolean
A flag to disable TLS (useful while in development).
Defaults to false
enable_mtls

boolean
Whether to enable or not Mutual Authentication. When mTLS is enabled, all KrakenD endpoints require clients to provide a known client-side X.509 authentication certificate. KrakenD relies on the system’s CA to validate certificates.
Defaults to false
max_version

string
Maximum TLS version supported.
Possible values are: "SSL3.0" , "TLS10" , "TLS11" , "TLS12" , "TLS13"
Defaults to "TLS13"
min_version

string
Minimum TLS version supported. When specifiying very old and insecure versions under TLS12 you must provide the ciphers_list.
Possible values are: "SSL3.0" , "TLS10" , "TLS11" , "TLS12" , "TLS13"
Defaults to "TLS13"
prefer_server_cipher_suites

boolean
Enforces the use of TLS versions and cipher suites configured, and blocks all traffic not in the range.
Defaults to false
private_key

string
Absolute path to the private key, or relative to the current working directory.
Example: "/path/to/key.pem" , "./certs/key.pem"
Defaults to "./certs/key.pem"
public_key

string
Absolute path to the public key, or relative to the current working directory.
Example: "/path/to/cert.pem" , "./certs/cert.pem"
Defaults to "./certs/cert.pem"

Supporting older TLS 1.2 and below

Although we do not recommend downgrading your installation, this is the configuration you will need to support older protocol versions.

Support old TLS v1.2

To support TLS v1.2 and 1.3 simultaneously, you need the following configuration. As you are accepting older cipher suites, it is recommended to add the flag prefer_server_cipher_suites to block clients from trying to negotiate weaker cipher suites:

{
  "version": 3,
  "tls": {
    "public_key": "/path/to/cert.pem",
    "private_key": "/path/to/key.pem",
    "min_version": "TLS12",
    "prefer_server_cipher_suites": true
  }
}

Support archaic TLS versions

To support versions older than 1.2, specify the list of cipher_suites you want to enable and the prefer_server_cipher_suites set to true.

Supported cipher suites

You can select which cipher_suites you’d like to support by passing an array of integers. The possible values of the cipher suites are listed below. The recommendation is to stay with TLS 1.3, or downgrade to TLS 1.2 when strongly needed. Down that should be out of the table.

Default suites for TLS 1.3 are:

  • 4865: TLS_AES_128_GCM_SHA256
  • 4866: TLS_AES_256_GCM_SHA384
  • 4867: TLS_CHACHA20_POLY1305_SHA256

Default suites for TLS 1.2 are:

  • 49199: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • 49200: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • 52392: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
  • 49196: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • 52393: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
  • 49195: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

Other cipher_suites are supported but not recommended. Their existence is to support legacy systems:

  • 5: TLS_RSA_WITH_RC4_128_SHA
  • 10: TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • 47: TLS_RSA_WITH_AES_128_CBC_SHA
  • 53: TLS_RSA_WITH_AES_256_CBC_SHA
  • 60: TLS_RSA_WITH_AES_128_CBC_SHA256
  • 156: TLS_RSA_WITH_AES_128_GCM_SHA256
  • 157: TLS_RSA_WITH_AES_256_GCM_SHA384
  • 49159: TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
  • 49161: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • 49162: TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • 49169: TLS_ECDHE_RSA_WITH_RC4_128_SHA
  • 49170: TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • 49171: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • 49172: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • 49187: TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • 49191: TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

Generating certificates

You can acquire, use external tools, or self-generate your certificates.

For example, to generate a self-signed certificate from the command line, you can do the following:

Generate a certificate 
$openssl req -newkey rsa:2048 -new -nodes -x509 -days 365 -out cert.pem -keyout key.pem \
    -subj "/C=US/ST=California/L=Mountain View/O=Your Organization/OU=Your Unit/CN=localhost"

Common TLS errors

Self-signed certificates will show in the logs:

http: TLS handshake error from 172.17.0.1:45474: local error: tls: bad record MAC

Old clients trying to connect to a newer TLS version, will produce errors as follows:

http: TLS handshake error from 172.17.0.1:33698: tls: unsupported SSLv2 handshake received
http: TLS handshake error from 172.17.0.1:33710: tls: client offered only unsupported versions

Incompatible curves offered by client:

http: TLS handshake error from 172.17.0.1:33810: tls: no cipher suite supported by both client and server
http: TLS handshake error from 172.17.0.1:33814: tls: no ECDHE curve supported by both client and server

When the client offers a limited set of options that the server cannot accept. It will hang up the connection with an End Of File:

http: TLS handshake error from 172.17.0.1:33990: EOF

SSL scan results for the default settings

The following output is the results of the sslscan command with a KrakenD configuration specifying the private and public keys in the configuration with no other additional tls settings:

Version: 2.0.15-7-gbc46606-static
OpenSSL 1.1.1u-dev  xx XXX xxxx

Connected to ::1

Testing SSL server localhost on port 443 using SNI name localhost

  SSL/TLS Protocols:
SSLv2     disabled
SSLv3     disabled
TLSv1.0   disabled
TLSv1.1   disabled
TLSv1.2   disabled
TLSv1.3   enabled

  TLS Fallback SCSV:
Server supports TLS Fallback SCSV

  TLS renegotiation:
Session renegotiation not supported

  TLS Compression:
Compression disabled

  Heartbleed:
TLSv1.3 not vulnerable to heartbleed

  Supported Server Cipher(s):
Preferred TLSv1.3  128 bits  TLS_AES_128_GCM_SHA256        Curve P-521 DHE 521
Accepted  TLSv1.3  256 bits  TLS_AES_256_GCM_SHA384        Curve P-521 DHE 521
Accepted  TLSv1.3  256 bits  TLS_CHACHA20_POLY1305_SHA256  Curve P-521 DHE 521

  Server Key Exchange Group(s):
TLSv1.3  128 bits  secp256r1 (NIST P-256)
TLSv1.3  192 bits  secp384r1 (NIST P-384)
TLSv1.3  260 bits  secp521r1 (NIST P-521)

  SSL Certificate:
Signature Algorithm: sha256WithRSAEncryption
RSA Key Strength:    2048

Subject:  localhost
Issuer:   localhost

Not valid before: Feb 28 11:44:05 2023 GMT
Not valid after:  Feb 28 11:44:05 2024 GMT
Scarf

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information