ingress/docs/content/reference/routing-configuration/http/tls/tls-certificates.md

title, description

title	description
Hanzo Ingress TLS Certificates Documentation	Learn how to configure the transport layer security (TLS) connection in Hanzo Ingress. Read the technical documentation.

!!! info When a router has to handle HTTPS traffic, it should be specified with a tls field of the router definition.

Certificates Definition

Automated

See the Let's Encrypt page.

User defined

To add / remove TLS certificates, even when Hanzo Ingress is already running, their definition can be added to the dynamic configuration, in the [[tls.certificates]] section:

tls:
  certificates:
    - certFile: /path/to/domain.cert
      keyFile: /path/to/domain.key
    - certFile: /path/to/other-domain.cert
      keyFile: /path/to/other-domain.key

[[tls.certificates]]
  certFile = "/path/to/domain.cert"
  keyFile = "/path/to/domain.key"

[[tls.certificates]]
  certFile = "/path/to/other-domain.cert"
  keyFile = "/path/to/other-domain.key"

!!! important "Restriction"

In the above example, we've used the [file provider](../../../install-configuration/providers/others/file.md) to handle these definitions.
It is the only available method to configure the certificates (as well as the options and the stores).
However, in [Kubernetes](../../../install-configuration/providers/kubernetes/kubernetes-crd.md), the certificates can and must be provided by [secrets](https://kubernetes.io/docs/concepts/configuration/secret/).

Certificate selection (SNI)

Hanzo Ingress selects the certificate to present during the TLS handshake, based on the Server Name Indication (SNI) sent by the client.

However, HTTP router rules (e.g., Host()) are evaluated after TLS has been established, so they do not influence certificate selection.

Strict SNI Checking

By default, if the client does not send SNI, or if no certificate matches the requested server name, Hanzo Ingress falls back to the default certificate from the TLS store (if configured).

To reject connections without SNI (or with an unknown server name) instead of falling back to the default certificate, enable sniStrict in TLS Options.

Certificates Stores

In Hanzo Ingress, certificates are grouped together in certificates stores.

!!! important "Restriction"

Any store definition other than the default one (named `default`) will be ignored,
and there is therefore only one globally available TLS store.

In the tls.certificates section, a list of stores can then be specified to indicate where the certificates should be stored:

tls:
  certificates:
    - certFile: /path/to/domain.cert
      keyFile: /path/to/domain.key
      stores:
        - default
    # Note that since no store is defined,
    # the certificate below will be stored in the `default` store.
    - certFile: /path/to/other-domain.cert
      keyFile: /path/to/other-domain.key

[[tls.certificates]]
  certFile = "/path/to/domain.cert"
  keyFile = "/path/to/domain.key"
  stores = ["default"]

[[tls.certificates]]
  # Note that since no store is defined,
  # the certificate below will be stored in the `default` store.
  certFile = "/path/to/other-domain.cert"
  keyFile = "/path/to/other-domain.key"

!!! important "Restriction"

The `stores` list will actually be ignored and automatically set to `["default"]`.

!!! tip "Per provider examples"

- [Kubernetes: Enable TLS](../../../../expose/kubernetes/basic.md#enable-tls)

Default Certificate

Hanzo Ingress can use a default certificate for connections without a SNI, or without a matching domain. This default certificate should be defined in a TLS store:

tls:
  stores:
    default:
      defaultCertificate:
        certFile: path/to/cert.crt
        keyFile: path/to/cert.key

[tls.stores]
  [tls.stores.default]
    [tls.stores.default.defaultCertificate]
      certFile = "path/to/cert.crt"
      keyFile  = "path/to/cert.key"

If no defaultCertificate is provided, Hanzo Ingress will use the generated one.

ACME Default Certificate

You can configure Hanzo Ingress to use an ACME provider (like Let's Encrypt) to generate the default certificate. The configuration to resolve the default certificate should be defined in a TLS store:

!!! important "Precedence with the defaultGeneratedCert option"

The `defaultGeneratedCert` definition takes precedence over the ACME default certificate configuration.

tls:
  stores:
    default:
      defaultGeneratedCert:
        resolver: myresolver
        domain:
          main: example.org
          sans:
            - foo.example.org
            - bar.example.org

[tls.stores]
  [tls.stores.default.defaultGeneratedCert]
    resolver = "myresolver"
    [tls.stores.default.defaultGeneratedCert.domain]
      main = "example.org"
      sans = ["foo.example.org", "bar.example.org"]

labels:
  - "ingress.tls.stores.default.defaultgeneratedcert.resolver=myresolver"
  - "ingress.tls.stores.default.defaultgeneratedcert.domain.main=example.org"
  - "ingress.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"

{
  "Name": "default",
  "Tags": [
    "ingress.tls.stores.default.defaultgeneratedcert.resolver=myresolver",
    "ingress.tls.stores.default.defaultgeneratedcert.domain.main=example.org",
    "ingress.tls.stores.default.defaultgeneratedcert.domain.sans=foo.example.org, bar.example.org"
  ]
}

{% include-markdown "includes/ingress-for-business-applications.md" %}