// Module included in the following assemblies:
//
// assembly-security.adoc

[id='installing-your-own-ca-certificates-{context}']
= Installing your own CA certificates and private keys

[role="_abstract"]
Install your own CA certificates and private keys instead of using the cluster and clients CA certificates and private keys generated by the Cluster Operator.

By default, Strimzi uses the following xref:con-certificates-{context}[cluster CA and clients CA secrets], which are renewed automatically.

* Cluster CA secrets
** `<cluster_name>-cluster-ca`
** `<cluster_name>-cluster-ca-cert`
* Clients CA secrets
** `<cluster_name>-clients-ca`
** `<cluster_name>-clients-ca-cert`

To install your own certificates, use the same names.

.Prerequisites

* The Cluster Operator is running.
* A Kafka cluster is not yet deployed.
+
If you have already deployed a Kafka cluster, you can xref:proc-replacing-your-own-private-keys-{context}[replace the default CA certificates with your own]. 
* Your own X.509 certificates and keys in PEM format for the cluster CA or clients CA.
+
** If you want to use a cluster or clients CA which is not a Root CA, you have to include the whole chain in the certificate file.
The chain should be in the following order:
+
1. The cluster or clients CA
2. One or more intermediate CAs
3. The root CA
+
** All CAs in the chain should be configured using the X509v3 Basic Constraints extension. Basic Constraints limit the path length of a certificate chain.
* The OpenSSL TLS management tool for converting certificates.

.Before you begin
The Cluster Operator generates keys and certificates in PEM (Privacy Enhanced Mail) and PKCS #12 (Public-Key Cryptography Standards) formats.
Only the keys and certificates in the PEM format are used internally by Strimzi.
The PKCS #12 store is there only for user applications that do not support using the PEM format directly.
When using custom CA certificates, adding the PKCS #12 store and its password to the secret is optional only.

.Procedure

. Create a new secret that contains the CA certificate.
+
.Client secret creation with a certificate in PEM format only
[source,shell,subs="+quotes"]
kubectl create secret generic <cluster_name>-clients-ca-cert --from-file=ca.crt=ca.crt
+
.Cluster secret creation with certificates in PEM and PKCS #12 format
[source,shell,subs="+quotes"]
----
kubectl create secret generic <cluster_name>-cluster-ca-cert \
  --from-file=ca.crt=ca.crt \
  --from-file=ca.p12=ca.p12 \
  --from-literal=ca.password=_P12-PASSWORD_
----
+
Replace <cluster_name> with the name of your Kafka cluster.

. Create a new secret that contains the private key.
+
[source,shell,subs="+quotes"]
kubectl create secret generic <ca_key_secret> --from-file=ca.key=ca.key

. Label the secrets.
+
[source,shell,subs="+quotes"]
----
kubectl label secret <ca_certificate_secret> strimzi.io/kind=Kafka strimzi.io/cluster="<cluster_name>"
----
+
[source,shell,subs="+quotes"]
----
kubectl label secret <ca_key_secret> strimzi.io/kind=Kafka strimzi.io/cluster="<cluster_name>"
----
+
* Label `strimzi.io/kind=Kafka` identifies the Kafka custom resource.
* Label `strimzi.io/cluster="<cluster_name>"` identifies the Kafka cluster.

. Annotate the secrets
+
[source,shell,subs="+quotes"]
----
kubectl annotate secret <ca_certificate_secret> strimzi.io/ca-cert-generation="<ca_certificate_generation>"
----
+
[source,shell,subs="+quotes"]
----
kubectl annotate secret <ca_key_secret> strimzi.io/ca-key-generation="<ca_key_generation>"
----
+
* Annotation `strimzi.io/ca-cert-generation="<ca_certificate_generation>"` defines the generation of a new CA certificate.
* Annotation `strimzi.io/ca-key-generation="<ca_key_generation>"` defines the generation of a new CA key.
+
Start from 0 (zero) as the incremental value (`strimzi.io/ca-cert-generation=0`) for your own CA certificate. Set a higher incremental value when you renew the certificates.

. Create the `Kafka` resource for your cluster, configuring either the `Kafka.spec.clusterCa` or the `Kafka.spec.clientsCa` object to _not_ use generated CAs.
+
.Example fragment `Kafka` resource configuring the cluster CA to use certificates you supply for yourself
[source,yaml,subs="attributes"]
----
kind: Kafka
version: {KafkaApiVersion}
spec:
  # ...
  clusterCa:
    generateCertificateAuthority: false
----

[role="_additional-resources"]
.Additional resources

* xref:renewing-your-own-ca-certificates-{context}[]
* xref:proc-replacing-your-own-private-keys-{context}[]
* xref:proc-installing-certs-per-listener-{context}[]
