Configuring TLS security profiles

TLS security profiles provide a way for servers to regulate which ciphers a client can use when connecting to the server. This ensures that OKD components use cryptographic libraries that do not allow known insecure protocols, ciphers, or algorithms.

Cluster administrators can choose which TLS security profile to use for each of the following components:

• the Ingress Controller

• the control plane

  This includes the Kubernetes API server, OpenShift API server, OpenShift OAuth API server, and OpenShift OAuth server.

Understanding TLS security profiles

You can use a TLS (Transport Layer Security) security profile to define which TLS ciphers are required by various OKD components. The OKD TLS security profiles are based on Mozilla recommended configurations.

You can specify one of the following TLS security profiles for each component:

Viewing TLS security profile details

You can view the minimum TLS version and ciphers for the predefined TLS security profiles for each of the following components: Ingress Controller and control plane.

Procedure

• View details for a specific TLS security profile:

  $ oc explain <component>.spec.tlsSecurityProfile.<profile> (1)

  1	For <component>, specify ingresscontroller or apiserver. For <profile>, specify old, intermediate, or custom.

  For example, to check the ciphers included for the intermediate profile for the control plane:

  $ oc explain apiserver.spec.tlsSecurityProfile.intermediate

  Example output

  KIND:     APIServer
  VERSION:  config.openshift.io/v1
  DESCRIPTION:
      intermediate is a TLS security profile based on:
      https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29
      and looks like this (yaml):
      ciphers: - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 -
      TLS_CHACHA20_POLY1305_SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 -
      ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES256-GCM-SHA384 -
      ECDHE-RSA-AES256-GCM-SHA384 - ECDHE-ECDSA-CHACHA20-POLY1305 -
      ECDHE-RSA-CHACHA20-POLY1305 - DHE-RSA-AES128-GCM-SHA256 -
      DHE-RSA-AES256-GCM-SHA384 minTLSVersion: TLSv1.2

• View all details for the tlsSecurityProfile field of a component:

  $ oc explain <component>.spec.tlsSecurityProfile (1)

  1	For <component>, specify ingresscontroller or apiserver.

  For example, to check all details for the tlsSecurityProfile field for the Ingress Controller:

  $ oc explain ingresscontroller.spec.tlsSecurityProfile

  Example output

  KIND:     IngressController
  VERSION:  operator.openshift.io/v1
  RESOURCE: tlsSecurityProfile <Object>
  DESCRIPTION:
       ...
  FIELDS:
     custom    <>
       custom is a user-defined TLS security profile. Be extremely careful using a
       custom profile as invalid configurations can be catastrophic. An example
       custom profile looks like this:
       ciphers: - ECDHE-ECDSA-CHACHA20-POLY1305 - ECDHE-RSA-CHACHA20-POLY1305 -
       ECDHE-RSA-AES128-GCM-SHA256 - ECDHE-ECDSA-AES128-GCM-SHA256 minTLSVersion:
       TLSv1.1
     intermediate    <>
       intermediate is a TLS security profile based on:
       https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29
       and looks like this (yaml):
       ... (1)
     modern    <>
       modern is a TLS security profile based on:
       https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility and
       looks like this (yaml):
       ... (2)
       NOTE: Currently unsupported.
     old    <>
       old is a TLS security profile based on:
       https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility
       and looks like this (yaml):
       ... (3)
     type    <string>
       ...

  1	Lists ciphers and minimum version for the intermediate profile here.
  2	Lists ciphers and minimum version for the modern profile here.
  3	Lists ciphers and minimum version for the old profile here.

Configuring the TLS security profile for the Ingress Controller

To configure a TLS security profile for an Ingress Controller, edit the IngressController custom resource (CR) to specify a predefined or custom TLS security profile. If a TLS security profile is not configured, the default value is based on the TLS security profile set for the API server.

Sample IngressController CR that configures the Old TLS security profile

apiVersion: config.openshift.io/v1
kind: IngressController
 ...
spec:
  tlsSecurityProfile:
    old: {}
    type: Old
 ...

The TLS security profile defines the minimum TLS version and the TLS ciphers for TLS connections for Ingress Controllers.

You can see the ciphers and the minimum TLS version of the configured TLS security profile in the IngressController custom resource (CR) under Status.Tls Profile and the configured TLS security profile under Spec.Tls Security Profile. For the Custom TLS security profile, the specific ciphers and minimum TLS version are listed under both parameters.

Prerequisites

• You have access to the cluster as a user with the cluster-admin role.

Procedure

1. Edit the IngressController CR in the openshift-ingress-operator project to configure the TLS security profile:

   $ oc edit IngressController default -n openshift-ingress-operator

2. Add the spec.tlsSecurityProfile field:

   Sample IngressController CR for a Custom profile

   apiVersion: operator.openshift.io/v1
   kind: IngressController
    ...
   spec:
     tlsSecurityProfile:
       type: Custom (1)
       custom: (2)
         ciphers: (3)
         - ECDHE-ECDSA-CHACHA20-POLY1305
         - ECDHE-RSA-CHACHA20-POLY1305
         - ECDHE-RSA-AES128-GCM-SHA256
         - ECDHE-ECDSA-AES128-GCM-SHA256
         minTLSVersion: VersionTLS11
    ...

   1	Specify the TLS security profile type (Old, Intermediate, or Custom). The default is Intermediate.
   2	Specify the appropriate field for the selected type: old: {} intermediate: {} custom:
   3	For the custom type, specify a list of TLS ciphers and minimum accepted TLS version.

3. Save the file to apply the changes.

Verification

• Verify that the profile is set in the IngressController CR:

  $ oc describe IngressController default -n openshift-ingress-operator

  Example output

  Name:         default
  Namespace:    openshift-ingress-operator
  Labels:       <none>
  Annotations:  <none>
  API Version:  operator.openshift.io/v1
  Kind:         IngressController
   ...
  Spec:
   ...
    Tls Security Profile:
      Custom:
        Ciphers:
          ECDHE-ECDSA-CHACHA20-POLY1305
          ECDHE-RSA-CHACHA20-POLY1305
          ECDHE-RSA-AES128-GCM-SHA256
          ECDHE-ECDSA-AES128-GCM-SHA256
        Min TLS Version:  VersionTLS11
      Type:               Custom
   ...

Configuring the TLS security profile for the control plane

To configure a TLS security profile for the control plane, edit the APIServer custom resource (CR) to specify a predefined or custom TLS security profile. Setting the TLS security profile in the APIServer CR propagates the setting to the following control plane components:

• Kubernetes API server

• OpenShift API server

• OpenShift OAuth API server

• OpenShift OAuth server

If a TLS security profile is not configured, the default TLS security profile is Intermediate.

Sample APIServer CR that configures the Old TLS security profile

apiVersion: config.openshift.io/v1
kind: APIServer
 ...
spec:
  tlsSecurityProfile:
    old: {}
    type: Old
 ...

The TLS security profile defines the minimum TLS version and the TLS ciphers required to communicate with the control plane components.

You can see the configured TLS security profile in the APIServer custom resource (CR) under Spec.Tls Security Profile. For the Custom TLS security profile, the specific ciphers and minimum TLS version are listed.

Prerequisites

• You have access to the cluster as a user with the cluster-admin role.

Procedure

1. Edit the default APIServer CR to configure the TLS security profile:

   $ oc edit APIServer cluster

2. Add the spec.tlsSecurityProfile field:

   Sample APIServer CR for a Custom profile

   apiVersion: config.openshift.io/v1
   kind: APIServer
   metadata:
     name: cluster
   spec:
     tlsSecurityProfile:
       type: Custom (1)
       custom: (2)
         ciphers: (3)
         - ECDHE-ECDSA-CHACHA20-POLY1305
         - ECDHE-RSA-CHACHA20-POLY1305
         - ECDHE-RSA-AES128-GCM-SHA256
         - ECDHE-ECDSA-AES128-GCM-SHA256
         minTLSVersion: VersionTLS11

   1	Specify the TLS security profile type (Old, Intermediate, or Custom). The default is Intermediate.
   2	Specify the appropriate field for the selected type: old: {} intermediate: {} custom:
   3	For the custom type, specify a list of TLS ciphers and minimum accepted TLS version.

3. Save the file to apply the changes.

Verification

• Verify that the TLS security profile is set in the APIServer CR:

  $ oc describe apiserver cluster

  Example output

  Name:         cluster
  Namespace:
   ...
  API Version:  config.openshift.io/v1
  Kind:         APIServer
   ...
  Spec:
    Audit:
      Profile:  Default
    Tls Security Profile:
      Custom:
        Ciphers:
          ECDHE-ECDSA-CHACHA20-POLY1305
          ECDHE-RSA-CHACHA20-POLY1305
          ECDHE-RSA-AES128-GCM-SHA256
          ECDHE-ECDSA-AES128-GCM-SHA256
        Min TLS Version:  VersionTLS11
      Type:               Custom
   ...