Mutual TLS

This policy enables automatic encrypted mTLS traffic for all the services in a Mesh.

Kuma ships with a builtin CA (Certificate Authority) which is initialized with an auto-generated root certificate. The root certificate is unique for every Mesh and it used to sign identity certificates for every data-plane. Kuma also supports third-party CA.

The mTLS feature is used for AuthN/Z as well: each data-plane is being assigned with a workload identity certificate, which is SPIFFE compatible. This certificate has a SAN set to spiffe://<mesh name>/<service name>. When Kuma enforces policies that require an identity, like TrafficPermission, it will extract the SAN from the client certificate and use it for every identity matching operation.

By default, mTLS is not enabled. You can enable Mutual TLS by updating the Mesh policy with the mtls setting.

With mTLS enabled, all traffic is denied by default.

Remember to apply a TrafficPermission policy to explicitly allow legitimate traffic between certain Dataplanes.

Builtin CA

On Universal:

  1. type: Mesh
  2. name: default
  3. mtls:
  4.   enabled: true # enable mTLS
  5.   ca:
  6.     builtin: {} # use Builtin CA (a unique Root CA certificate will be generated automatically)

You can apply this configuration with kumactl apply -f [file-path].

On Kubernetes:

  1. apiVersion: kuma.io/v1alpha1
  2. kind: Mesh
  3. metadata:
  4.   name: default
  5. spec:
  6.   mtls:
  7.     enabled: true # enable mTLS
  8.     ca:
  9.       builtin: {} # use Builtin CA (a unique Root CA certificate will be generated automatically)

You can apply this configuration with kubectl apply -f [file-path].

Provided CA

In some cases users might need to opt out of auto-generated Root CA certificates, e.g. to stay compliant with internal company policies.

To that end, Kuma supports another type of CA - provided CA.

Like the name implies, a user will have to provide a custom Root CA certificate and take a responsibility for managing its lifecycle.

A complete workflow of changing CA type from builtin to provided looks the following way:

  1. A user must first upload a custom Root CA certificate using kumactl manage ca provided command, e.g.

    1. kumactl manage ca provided certificates add --mesh demo --cert-file demo.root_ca.crt --key-file demo.root_ca.key

    This is a security-sensitive opreation, which implies very restrictive default settings.

    If you are just Getting Started with Kuma, run kumactl manage ca provided commands on the same machine where kuma-cp is running.

  2. Next, a user must disable mTLS on a Mesh before he will be allowed to change CA type from builtin to provided, e.g.

    On Universal:

    1. echo "
    2. type: Mesh
    3. name: demo
    4. mtls:
    5.   enabled: false # disable mTLS
    6.   ca:
    7.     builtin: {}  # every Mesh has `builtin` CA by default
    8. " | kumactl apply -f -

    On Kubernetes:

    1. echo "
    2. apiVersion: kuma.io/v1alpha1
    3. kind: Mesh
    4. metadata:
    5.   name: default
    6. spec:
    7.   mtls:
    8.     enabled: false # disable mTLS
    9.     ca:
    10.       builtin: {}  # every Mesh has `builtin` CA by default
    11. " | kubectl apply -f -

  3. A user can now change CA type to provided and enable mTLS back after that

    On Universal:

    1. echo "
    2. type: Mesh
    3. name: demo
    4. mtls:
    5.   enabled: true  # enable mTLS
    6.   ca:
    7.     provided: {} # use Provided CA (an existing Root CA certificate must have already been provided by a user)
    8. " | kumactl apply -f -

    On Kubernetes:

    1. echo "
    2. apiVersion: kuma.io/v1alpha1
    3. kind: Mesh
    4. metadata:
    5.   name: default
    6. spec:
    7.   mtls:
    8.     enabled: true  # enable mTLS
    9.     ca:
    10.       provided: {} # use Provided CA (an existing Root CA certificate must have already been provided by a user)
    11. " | kubectl apply -f -

Root CA certificate provided by a user must meet certain constraints:

  1. It MUST be a self-signed Root CA certificate (Intermediate CA certificates are not allowed)
  2. It MUST have basic constraint CA set to true (see X509-SVID: 4.1. Basic ConstraintsMutual TLS - 图1)
  3. It MUST have key usage extension keyCertSign set (see X509-SVID: 4.3. Key UsageMutual TLS - 图2)
  4. It MUST NOT have key usage extension ‘digitalSignature’ set (see X509-SVID: Appendix A. X.509 Field ReferenceMutual TLS - 图3)
  5. It MUST NOT have key usage extension ‘keyAgreement’ set (see X509-SVID: Appendix A. X.509 Field ReferenceMutual TLS - 图4)
  6. It MUST NOT have key usage extension ‘keyEncipherment’ set (see X509-SVID: Appendix A. X.509 Field ReferenceMutual TLS - 图5)

If a provided certificate doesn’t meet those constraints, kumactl manage ca provided certificates add command will fail with a respective error message, e.g.

  1. kumactl manage ca provided certificates add --mesh demo --cert-file demo.root_ca.crt --key-file demo.root_ca.key
  3. Error: Could not add signing cert (Resource is not valid)
  4. * cert: certificate must be self-signed (intermediate CAs are not allowed)

The error message in the above example indicates that a user is trying to upload an Intermediate CA certificate while only Root CA certificates are allowed.