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

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

Strimzi uses _Secrets_ to store private keys and certificates for Kafka cluster components and clients.
Secrets are used for establishing TLS encrypted connections between Kafka brokers, and between brokers and clients.
They are also used for mutual TLS authentication.

* A _Cluster Secret_ contains a cluster CA certificate to sign Kafka broker certificates, and is used by a connecting client to establish a TLS encrypted connection with the Kafka cluster to validate broker identity.
* A _Client Secret_ contains a client CA certificate for a user to sign its own client certificate to allow mutual authentication against the Kafka cluster.
The broker validates the client identity through the client CA certificate itself.
* A _User Secret_ contains a private key and certificate, which are generated and signed by the client CA certificate when a new user is created.
The key and certificate are used for authentication and authorization when accessing the cluster.

Secrets provide private keys and certificates in PEM and PKCS #12 formats.
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 Java applications.
PKCS #12 storage provides a truststore (or keystore) that can be used directly.

All keys are 2048 bits in size.

== PKCS #12 storage

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.

== Cluster CA Secrets

The following tables describe the Cluster Secrets that are managed by the Cluster Operator in a Kafka cluster.

Only the `_<cluster>_-cluster-ca-cert` Secret needs to be used by clients.
All other `Secrets` described only need to be accessed by the Strimzi components.
You can enforce this using Kubernetes role-based access controls, if necessary.

.Fields in the `_<cluster>_-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>_-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.

|===

NOTE: The CA certificates in `_<cluster>_-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>_-kafka-brokers` Secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

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

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

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

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

|===

.Fields in the `_<cluster>_-zookeeper-nodes` Secret
[cols="40,60",options="header",stripes="none",separator=¦]
|===

¦Field
¦Description

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

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

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

m¦_<cluster>_-zookeeper-_<num>_.key
¦Private key for ZooKeeper pod `_<num>_`.

|===

.Fields in the `_<cluster>_-entity-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 Entity Operator and Kafka or ZooKeeper.
Signed by a current or former cluster CA private key in `_<cluster>_-cluster-ca`.

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

|===

== Client CA Secrets

.Clients CA `Secrets` managed by the Cluster Operator in _<cluster>_
[cols="3,3,4", options="header"]
|===
|Secret name
|Field within Secret
|Description

|`_<cluster>_-clients-ca`
|`ca.key`
|The current private key for the clients CA.
.3+|`_<cluster>_-clients-ca-cert`
|`ca.p12`
|PKCS #12 archive file for storing certificates and keys.
|`ca.password`
|Password for protecting the  PKCS #12 archive file.
|`ca.crt`
|The current certificate for the clients CA.
|===

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

NOTE: `_<cluster>_-clients-ca` is used to sign certificates of client applications.
It needs to 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.

== Adding labels and annotations to 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]

== User Secrets

.`Secrets` managed by the User Operator
[cols="3,3,4", options="header"]
|===
|Secret name
|Field within Secret
|Description

.4+|`_<user>_`
|`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
|===
