News Changing component execution order with KrakenD Workflows

Community Documentation

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

Document updated on Jun 13, 2021

Enabling TLS for HTTPS and HTTP/2

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)

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

TLS Configuration

To start KrakenD with TLS you need to generate the certificate and provide both the public and the private key:

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

If you want to enable mTLS see Mutual TLS configuration

All TLS options are described below:

Fields of TLS/SSL
* required fields

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
curve_preferences array
The list of all the identifiers for the curve preferences. Use 23 for CurveP256, 24 for CurveP384, 25 for CurveP521, 29 for X25519.
Defaults to [23,24,25]
disable_system_ca_pool boolean
Make that any certificate in the system’s CA is not recognized by KrakenD. 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
Maximum TLS version supported.
Possible values are: "SSL3.0" , "TLS10" , "TLS11" , "TLS12" , "TLS13"
Defaults to "TLS13"
min_version
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.
Examples: "/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.
Examples: "/path/to/cert.pem" , "./certs/cert.pem"
Defaults to "./certs/cert.pem"
Schema: https://www.krakend.io/schema/v2.1/tls.json

The list of cipher suites with its values is:

  • 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
  • 49199: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • 49195: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • 49200: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • 49196: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • 52392: TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
  • 52393: TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

TLS 1.3:

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

Default suites are:

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

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:

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"

When you are using self-signed certificates, you must add the certificates to the local CA, or at least add while developing the allow_insecure_connections setting to true. Example:

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

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.

See all support channels