Shift configuration for mTLS support

Shift Configuration mTLS support

To enable mutual TLS support, the CA issuer Certificate needs to be created to support mTLS.

When the CA Issuer Certificate is already created the policies need to be updated to support mTLS.

The Charts then need to be updated with the new CA issuer certificate and the mTLS enabled , and then be deployed to the installation.

Issuer CA

An issuer CA certificate and private key must be generated for each shift deployment. The private key cannot be changed afterwards. Generate the issuer CA according to the following instructions.

The key must be in PKCS#8 format. Both, the CA certificate and key must be DER-encoded
The CA's key pair must be of one of the supported algorithms:
- RSA with >= 2048 bit keys
- ECDSA with one of the supported curves:
  - secp256r1 (or P-256), secp384r1 (or P-384), secp521r1 (or P-521)
- Ed25519
It is recommended to use the same key algorithm that is configured for the signer CAs through ca.signers.key_generation.algorithm (default ecdsa) also for the issuer CA. The curve parameter (for ECDSA) or the strength parameter (for RSA) may differ for the CA to provide additional security.
The CA must have the Basic Constraints extension with cA=True and pathLen unset or >= 1. The extension must be marked as critical.
The CA must have the Key Usage extension with at least the bits for keyCertSign and cRLSign set. The extension must be marked as critical. Other usage bits should not be set.
The CA must have certain Certificate Policies extension. These policies depend on the feature sets that are required. Alternatively, the extension may specify anyPolicy. The extension should not be marked critical. The following policies are supported:
- Base policy with OID 1.3.6.1.4.1.14481.109.4.1. This policy must always be added.
- SCP policy with OID 1.3.6.1.4.1.14481.109.4.2. This policy is needed when scp services are deployed and messaging features are used.
- mTLS policy with OID 1.3.6.1.4.1.14481.109.4.3. This policy is needed when ast services are configured to enforce mutualTLS communication with clients.
Above mentioned policies are umbrella policies for feature sets. They serve as a symbolic placeholder to the profiles required by that feature set. It's recommended to use these umbrella policies. In detail, they combine the following profiles:
- Base policy contains
  - 1.3.6.1.4.1.14481.109.1.0 (profile LEAF_CA)
  - 1.3.6.1.4.1.14481.109.1.4 (profile AST_DEVICE)
- SCP policy contains
  - 1.3.6.1.4.1.14481.109.1.1 (profile SIGNATURE)
  - 1.3.6.1.4.1.14481.109.1.2 (profile AUTHENTICATION)
  - 1.3.6.1.4.1.14481.109.1.3 (profile ENCRYPTION)
  - 1.3.6.1.4.1.14481.109.1.6 (profile SIGNATURE_GATEWAY)
  - 1.3.6.1.4.1.14481.109.1.7 (profile AUTHENTICATION_GATEWAY)
  - 1.3.6.1.4.1.14481.109.1.8 (profile ENCRYPTION_GATEWAY)
- mTLS policy contains
  - 1.3.6.1.4.1.14481.109.1.9 (profile TLS_CLIENT)
  - 1.3.6.1.4.1.14481.109.1.10 (profile TLS_CLIENT_AND_KEY)
The CA may have the Extended Key Usage extension with the id_kp_OCSPSigning key purpose set. Other key purpose IDs should not be set.
Other extensions should not be present.

Below is a simple example how to generate a self signed issuer CA using OpenSSL. The example generates an issuer CA for all three umbrella policies described above.

Create file openssl.cnf with the following content

   [req]
   default_bits = 4096
   encrypt_key = no
   default_md = sha512
   prompt = no
   utf8 = yes
   x509_extensions = v3_req
   distinguished_name = req_distinguished_name

  
   # Adjust below values as required
   [req_distinguished_name]
   C = DE
   ST = Rheinland-Pfalz
   L = Worms
   O = KOBIL GmbH
   CN = KOBIL Shift Issuer CA
   
   [v3_req]
   basicConstraints = critical, CA:TRUE, pathlen:1
   keyUsage = critical, keyCertSign, cRLSign
   # explicit policies
   certificatePolicies = 1.3.6.1.4.1.14481.109.4.1, 1.3.6.1.4.1.14481.109.4.2, 1.3.6.1.4.1.14481.109.4.3
   # or alternatively anyPolicy
   # certificatePolicies = 2.5.29.32.0

Create an ECDSA key-pair for curve P-521, convert it to PKCS#8 format, and store it in file key.der.

openssl ecparam -name P-521 -genkey -noout -outform DER | openssl pkcs8 -inform DER -topk8 -nocrypt -outform DER -out key.der

Create a self-signed certificate with a validity of 10 years for the public key generated in the previous step and store it in file cert.der.

openssl req -nodes -x509 -days 3650 -config openssl.cnf -key key.der -keyform DER -out cert.der -outform DER

Base64 encode key and certificate. The content of resulting files key.b64 and cert.b64 can be added to values common.ast.issuer.key and common.ast.issuer.certs, respectively.

openssl enc -a -A -in key.der -out key.b64
openssl enc -a -A -in cert.der -out cert.b64

Updating policies

It is possible to change the supported certificate policies of the issuer CA. This can be done by reissuing the issuer CA certificate with the updated policies.

When reissuing the issuer CA certificate, the issuer CA's key pair (public and private key) must not be changed.

When using the above OpenSSL example, edit the openssl.cnf config file and adjust the policies accordingly. Then reissue the issuer CA certificate using command

openssl req -nodes -x509 -days 3650 -config openssl.cnf -key key.der -keyform DER -out cert.der -outform DER

Then base64 encode it using command

openssl enc -a -A -in cert.der -out cert.b64

Then update the value common.ast.issuer.certs with content of file cert.b64.

After updating the issuer CA certificate's policies, existing tenant signer certificates must be manually updated using the following instructions:

For each tenant, in which a signer exists, obtain an access token with admin write privileges
- In the default permission configuration, the required role is ks-management/Admin
- If the permission configuration was changed from the default, use a token with any of the api.security.jwtAuth.external.writeAccessRoles from the AST CA service's values
Execute PATCH /v1/tenants/<tenant>/signers/admin with the admin token and an empty request body
If successful, the CA service returns a body that looks like this:

{
"id": "<the new signer ID>",
"tenant": "<tenant>",
"name": "<signer name>"
}

The CA Service has enqueued the signer for reissuance and will create a new certificate for the same signer key pair
It is recommended to recreate the SDK Config JWT for the tenant, although not required.

Chart Configuration

The following needs to be set in the charts to activate mTLS.

Activate the mTLS for the services and setup the IstioIngress certificate and the AST issuer

common section

common:
  mutualTLS:
    services:
      enabled: true
    istioIngressGateway:
      enabled: true
      cacerts: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURERENDQW02Z0F3.... xZTAyY3VNU2RDaTVJNjhGdz09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K"
  ast:
    issuer:
      certs:
      - "MIIDDDCCAm6gAwIBAgIUU5l4a8FG3VAjOjwVnTi+kOdNop8wC....jMqTtdiIqjclV1e02cuMSdCi5I68Fw=="
      key: "MIHuAgEAMBAGByqGSM49AgEGBSuBBAAjBIHWMIHTAgEBBEIA....ja7hSpAVBic6mvJdjzVgmTpIuDn+lg=="

Configure ingress when being used to allow for SSL passthrough

routing section

routing:
  istio:
    ingress:
      admin:
        annotations:
          nginx.ingress.kubernetes.io/ssl-passthrough: "true"

Shift Configuration mTLS support​

Issuer CA​

Updating policies​

Chart Configuration​

Shift Configuration mTLS support

Issuer CA

Updating policies

Chart Configuration