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

[id='certificates-and-secrets-{context}']
= Secrets

[role="_abstract"]
Strimzi uses secrets to store private and public key certificates for Kafka clusters, clients, and users.
Secrets are used for establishing TLS encrypted connections between Kafka brokers, and between brokers and clients.
They are also used for mutual TLS 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.

== Secrets in PEM and PKCS #12 formats

Secrets provide private keys and certificates in PEM and PKCS #12 formats.
Use the format that's suitable for your client.
Using private keys and certificates in PEM format means that users have to get them from the secrets,
and generate a corresponding truststore or keystore to use in their applications.
PKCS #12 storage provides a truststore or keystore that can be used directly.

PKCS #12 defines an archive file format (`.p12`) for storing cryptography objects into a single file with password protection.
You can use PKCS #12 to manage certificates and keys in one place.

Each secret contains fields specific to PKCS #12.

* The `.p12` field contains the certificates and keys.
* The `.password` field is the password that protects the archive.

All keys are 2048 bits in size and are valid by default for 365 days from 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 TLS client authentication when connecting to Kafka brokers.
`_<cluster_name>_-clients-ca-cert`::
Contains the public key of the client CA. Kafka brokers use the public key to verify the identity of clients accessing the Kafka brokers when TLS client 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>_-zookeeper-nodes`::
Contains the private and public keys for ZooKeeper nodes.
`_<cluster_name>_-cluster-operator-certs`:: Contains the private and public keys for encrypting communication between the Cluster Operator and Kafka or ZooKeeper.
`_<cluster_name>_-entity-topic-operator-certs`::
Contains the private and public keys for encrypting communication between the Topic Operator and Kafka or ZooKeeper.
`_<cluster_name>_-entity-user-operator-certs`::
Contains the private and public keys for encrypting communication between the User Operator and Kafka or ZooKeeper.
`_<cluster_name>_-cruise-control-certs`:: Contains the private and public keys for encrypting communication between Cruise Control and Kafka or ZooKeeper.
`_<cluster_name>_-kafka-exporter-certs`:: Contains the private and public keys for encrypting communication between Kafka Exporter and Kafka or ZooKeeper.

NOTE: You can xref:kafka-listener-certificates-str[provide your own server certificates and private keys] to connect to to Kafka brokers using _Kafka listener certificates_ rather than certificates signed by the cluster CA or clients 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 archive file for storing certificates and keys.

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

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 archive file for storing certificates and keys.

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

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>_-zookeeper-nodes` secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

m¦_<cluster_name>_-zookeeper-_<num>_.p12
¦PKCS #12 archive file for storing certificates and keys.

m¦_<cluster_name>_-zookeeper-_<num>_.password
¦Password for protecting the  PKCS #12 archive file.

m¦_<cluster_name>_-zookeeper-_<num>_.crt
¦Certificate for ZooKeeper node _<num>_. Signed by a current or former cluster CA private key in `_<cluster_name>_-cluster-ca`.

m¦_<cluster_name>_-zookeeper-_<num>_.key
¦Private key for ZooKeeper 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 archive file for storing certificates and keys.

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

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

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

|===

.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 archive file for storing certificates and keys.

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

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

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

|===

.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 archive file for storing certificates and keys.

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

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

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

|===

.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 archive file for storing certificates and keys.

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

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

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

|===

.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 archive file for storing certificates and keys.

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

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

m¦kafka-exporter.key
¦Private key for TLS communication between the Kafka Exporter and Kafka or ZooKeeper.

|===

== Client 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 archive file for storing certificates and keys.

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

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

|===

== User secrets

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 archive file for storing certificates and keys.
|`user.password`
|Password for protecting the PKCS #12 archive file.
|`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
    # ...
----

For more information on configuring template properties, see xref:assembly-customizing-kubernetes-resources-str[].

== Disabling `ownerReference` in the CA secrets

By default, the Cluster and Client 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 Client 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 Client CAs
[source,yaml,subs="+quotes,attributes"]
----
apiVersion: {KafkaApiVersion}
kind: Kafka
# ...
spec:
# ...
  clusterCa:
    generateSecretOwnerReference: false
  clientsCa:
    generateSecretOwnerReference: false
# ...
----

.Additional resources

* xref:type-CertificateAuthority-reference[`CertificateAuthority` schema reference]
