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

[id='certificates-and-secrets-{context}']
= Secrets generated by the operators

[role="_abstract"]
The Cluster Operator automatically sets up and renews TLS certificates to enable encryption and authentication within a cluster.
It also sets up other TLS certificates if you want to enable encryption or mTLS authentication between Kafka brokers and clients.

Secrets are created when custom resources are deployed, such as `Kafka` and `KafkaUser`. 
Strimzi uses these secrets to store private and public key certificates for Kafka clusters, clients, and users.
The secrets are used for establishing TLS encrypted connections between Kafka brokers, and between brokers and clients.
They are also used for mTLS authentication.

Cluster and clients secrets are always pairs: one contains the public key and one contains the private key.

Cluster secret:: A cluster secret contains the _cluster CA_ to sign Kafka broker certificates.
Connecting clients use the certificate to establish a TLS encrypted connection with a Kafka cluster. The certificate verifies broker identity.
Client secret:: A client secret contains the _clients CA_ for a user to sign its own client certificate.
This allows mutual authentication against the Kafka cluster. The broker validates a client's identity through the certificate.
User secret:: A user secret contains a private key and certificate. The secret is created and signed by the clients CA when a new user is created. The key and certificate are used to authenticate and authorize the user when accessing the cluster.

NOTE: You can provide xref:proc-installing-certs-per-listener-str[_Kafka listener certificates_] for TLS listeners or external listeners that have TLS encryption enabled.
Use Kafka listener certificates to incorporate the security infrastructure you already have in place.

[id='certificates-and-secrets-formats-{context}']
== TLS authentication using keys and certificates in PEM or PKCS #12 format

The secrets created by Strimzi provide private keys and certificates in PEM (Privacy Enhanced Mail) and PKCS #12 (Public-Key Cryptography Standards) formats.
PEM and PKCS #12 are OpenSSL-generated key formats for TLS communications using the SSL protocol.

You can configure mutual TLS (mTLS) authentication that uses the credentials contained in the secrets generated for a Kafka cluster and user. 

To set up mTLS, you must first do the following:

* xref:con-securing-kafka-authentication-{context}[Configure your Kafka cluster with a listener that uses mTLS]
* xref:con-securing-client-authentication-{context}[Create a `KafkaUser` that provides client credentials for mTLs]

When you deploy a Kafka cluster, a `<cluster_name>-cluster-ca-cert` secret is created with public key to verify the cluster. 
You use the public key to configure a truststore for the client. 

When you create a `KafkaUser`, a `<kafka_user_name>` secret is created with the keys and certificates to verify the user (client).
Use these credentials to configure a keystore for the client.

With the Kafka cluster and client set up to use mTLS, you extract credentials from the secrets and add them to your client configuration.

PEM keys and certificates::
For PEM, you add the following to your client configuration:
+
--
Truststore::
* `ca.crt` from the `<cluster_name>-cluster-ca-cert` secret, which is the CA certificate for the cluster.
Keystore::
* `user.crt` from the `<kafka_user_name>` secret, which is the public certificate of the user.
* `user.key` from the `<kafka_user_name>` secret, which is the private key of the user.
--

PKCS #12 keys and certificates::
For PKCS #12, you add the following to your client configuration:
+
--
Truststore::
* `ca.p12` from the `<cluster_name>-cluster-ca-cert` secret, which is the CA certificate for the cluster.
* `ca.password` from the `<cluster_name>-cluster-ca-cert` secret, which is the password to access the public cluster CA certificate.
Keystore::
* `user.p12` from the `<kafka_user_name>` secret, which is the public key certificate of the user.
* `user.password` from the `<kafka_user_name>` secret, which is the password to access the public key certificate of the Kafka user.
--

PKCS #12 is supported by Java, so you can add the values of the certificates directly to your Java client configuration. 
You can also reference the certificates from a secure storage location.  
With PEM files, you must add the certificates directly to the client configuration in single-line format.  
Choose a format that's suitable for establishing TLS connections between your Kafka cluster and client.
Use PKCS #12 if you are unfamiliar with PEM. 

NOTE: All keys are 2048 bits in size and, by default, are valid for 365 days from the initial generation.
You can xref:con-certificate-renewal-str[change the validity period].

[id='con-certificates-{context}']
== Secrets generated by the Cluster Operator

The Cluster Operator generates the following certificates, which are saved as secrets in the Kubernetes cluster.
Strimzi uses these secrets by default.

The cluster CA and clients CA have separate secrets for the private key and public key.

`_<cluster_name>_-cluster-ca`::
Contains the private key of the cluster CA. Strimzi and Kafka components use the private key to sign server certificates.
`_<cluster_name>_-cluster-ca-cert`::
Contains the public key of the cluster CA. Kafka clients use the public key to verify the identity of the Kafka brokers they are connecting to with TLS server authentication.
`_<cluster_name>_-clients-ca`::
Contains the private key of the clients CA. Kafka clients use the private key to sign new user certificates for mTLS authentication when connecting to Kafka brokers.
`_<cluster_name>_-clients-ca-cert`::
Contains the public key of the clients CA. Kafka brokers use the public key to verify the identity of clients accessing the Kafka brokers when mTLS authentication is used.

Secrets for communication between Strimzi components contain a private key and a public key certificate signed by the cluster CA.

`_<cluster_name>_-kafka-brokers`::
Contains the private and public keys for Kafka brokers.
`_<cluster_name>_-cluster-operator-certs`:: Contains the private and public keys for encrypting communication between the Cluster Operator and Kafka.
`_<cluster_name>_-entity-topic-operator-certs`::
Contains the private and public keys for encrypting communication between the Topic Operator and Kafka.
`_<cluster_name>_-entity-user-operator-certs`::
Contains the private and public keys for encrypting communication between the User Operator and Kafka.
`_<cluster_name>_-cruise-control-certs`:: Contains the private and public keys for encrypting communication between Cruise Control and Kafka.
`_<cluster_name>_-kafka-exporter-certs`:: Contains the private and public keys for encrypting communication between Kafka Exporter and Kafka.

NOTE: You can xref:proc-installing-certs-per-listener-str[provide your own server certificates and private keys] to connect to Kafka brokers using _Kafka listener certificates_ rather than certificates signed by the cluster CA.

== Cluster CA secrets

Cluster CA secrets are managed by the Cluster Operator in a Kafka cluster.

Only the `_<cluster_name>_-cluster-ca-cert` secret is required by clients.
All other cluster secrets are accessed by Strimzi components.
You can enforce this using Kubernetes role-based access controls, if necessary.

NOTE: The CA certificates in `_<cluster_name>_-cluster-ca-cert` must be trusted by Kafka client applications so that they validate the Kafka broker certificates when connecting to Kafka brokers over TLS.

.Fields in the `_<cluster_name>_-cluster-ca` secret
[cols="30,70",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦ca.key
¦The current private key for the cluster CA.

|===

.Fields in the `_<cluster_name>_-cluster-ca-cert` secret
[cols="30,70",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦ca.p12
¦PKCS #12 store for storing certificates and keys.

m¦ca.password
¦Password for protecting the PKCS #12 store.

m¦ca.crt
¦The current certificate for the cluster CA.

|===

.Fields in the `_<cluster_name>_-kafka-brokers` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦_<cluster_name>_-kafka-_<num>_.p12
¦PKCS #12 store for storing certificates and keys.

m¦_<cluster_name>_-kafka-_<num>_.password
¦Password for protecting the PKCS #12 store.

m¦_<cluster_name>_-kafka-_<num>_.crt
¦Certificate for a Kafka broker pod _<num>_. Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦_<cluster_name>_-kafka-_<num>_.key
¦Private key for a Kafka broker pod `_<num>_`.

|===

.Fields in the `_<cluster_name>_-cluster-operator-certs` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦cluster-operator.p12
¦PKCS #12 store for storing certificates and keys.

m¦cluster-operator.password
¦Password for protecting the PKCS #12 store.

m¦cluster-operator.crt
¦Certificate for mTLS communication between the Cluster Operator and Kafka.
Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦cluster-operator.key
¦Private key for mTLS communication between the Cluster Operator and Kafka.

|===

.Fields in the `_<cluster_name>_-entity-topic-operator-certs` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦entity-operator.p12
¦PKCS #12 store for storing certificates and keys.

m¦entity-operator.password
¦Password for protecting the PKCS #12 store.

m¦entity-operator.crt
¦Certificate for mTLS communication between the Topic Operator and Kafka.
Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦entity-operator.key
¦Private key for mTLS communication between the Topic Operator and Kafka.

|===

.Fields in the `_<cluster_name>_-entity-user-operator-certs` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦entity-operator.p12
¦PKCS #12 store for storing certificates and keys.

m¦entity-operator.password
¦Password for protecting the PKCS #12 store.

m¦entity-operator.crt
¦Certificate for mTLS communication between the User Operator and Kafka.
Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦entity-operator.key
¦Private key for mTLS communication between the User Operator and Kafka.

|===

.Fields in the `_<cluster_name>_-cruise-control-certs` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦cruise-control.p12
¦PKCS #12 store for storing certificates and keys.

m¦cruise-control.password
¦Password for protecting the PKCS #12 store.

m¦cruise-control.crt
¦Certificate for mTLS communication between Cruise Control and Kafka.
Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦cruise-control.key
¦Private key for mTLS communication between the Cruise Control and Kafka.

|===

.Fields in the `_<cluster_name>_-kafka-exporter-certs` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦kafka-exporter.p12
¦PKCS #12 store for storing certificates and keys.

m¦kafka-exporter.password
¦Password for protecting the PKCS #12 store.

m¦kafka-exporter.crt
¦Certificate for mTLS communication between Kafka Exporter and Kafka.
Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦kafka-exporter.key
¦Private key for mTLS communication between the Kafka Exporter and Kafka.

|===

== Clients CA secrets

Clients CA secrets are managed by the Cluster Operator in a Kafka cluster.

The certificates in `_<cluster_name>_-clients-ca-cert` are those which the Kafka brokers trust.

The `_<cluster_name>_-clients-ca` secret is used to sign the certificates of client applications.
This secret must be accessible to the Strimzi components and for administrative access if you are intending to issue application certificates without using the User Operator.
You can enforce this using Kubernetes role-based access controls, if necessary.


.Fields in the `_<cluster_name>_-clients-ca` secret
[cols="30,70",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦ca.key
¦The current private key for the clients CA.

|===

.Fields in the `_<cluster_name>_-clients-ca-cert` secret
[cols="30,70",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦ca.p12
¦PKCS #12 store for storing certificates and keys.

m¦ca.password
¦Password for protecting the PKCS #12 store.

m¦ca.crt
¦The current certificate for the clients CA.

|===

== User secrets generated by the User Operator                      

User secrets are managed by the User Operator.

When a user is created using the User Operator, a secret is generated using the name of the user.

.Fields in the `_user_name_` secret
[cols="3,3,4", options="header"]
|===
|Secret name
|Field within secret
|Description

.4+|`_<user_name>_`
|`user.p12`
|PKCS #12 store for storing certificates and keys.
|`user.password`
|Password for protecting the PKCS #12 store.
|`user.crt`
|Certificate for the user, signed by the clients CA
|`user.key`
|Private key for the user
|===

== Adding labels and annotations to cluster CA secrets

By configuring the `clusterCaCert` template property in the `Kafka` custom resource, you can add custom labels and annotations to the Cluster CA secrets created by the Cluster Operator.
Labels and annotations are useful for identifying objects and adding contextual information.
You configure template properties in Strimzi custom resources.

.Example template customization to add labels and annotations to secrets
[source,yaml,subs=attributes+]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    # ...
    template:
      clusterCaCert:
        metadata:
          labels:
            label1: value1
            label2: value2
          annotations:
            annotation1: value1
            annotation2: value2
    # ...
----

== Disabling `ownerReference` in the CA secrets

By default, the cluster and clients CA secrets are created with an `ownerReference` property that is set to the `Kafka` custom resource.
This means that, when the `Kafka` custom resource is deleted, the CA secrets are also deleted (garbage collected) by Kubernetes.

If you want to reuse the CA for a new cluster, you can disable the `ownerReference` by setting the `generateSecretOwnerReference` property for the cluster and clients CA secrets to `false` in the `Kafka` configuration.
When the `ownerReference` is disabled, CA secrets are not deleted by Kubernetes when the corresponding `Kafka` custom resource is deleted.

.Example Kafka configuration with disabled `ownerReference` for cluster and clients CAs
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
# ...
spec:
# ...
  clusterCa:
    generateSecretOwnerReference: false
  clientsCa:
    generateSecretOwnerReference: false
# ...
----

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

* link:{BookURLConfiguring}#type-CertificateAuthority-reference[`CertificateAuthority` schema reference^]
