Certificates for sidecars
The Cyral sidecar requires certificates to communicate in a secure way. The Cyral sidecar will by default install its own certificates as part of the deployment process, which we refer to as sidecar-created certificates. You may also choose to provide your own self-signed certificate or signed by the Certificate Authority (CA) of your choice, which we refer to as custom certificates.
Sidecar certificate types
The sidecar uses two types of certificate: a TLS certificate, and a CA certificate.
TLS. The TLS certificate is used handle TLS connections terminated at the sidecar. This is used by all Cyral repository types when communicating with TLS terminated at the sidecar.
CA. The CA certificate is used by the sidecar when it is acting as a proxy. It is not used for all Cyral repository types. Repository types that use this certificate include S3 and DynamoDB.
Sidecar-created certificate
If custom certificates are not provided by you, the sidecar will automatically install self-signed certificates. For those deployment templates provided by Cyral, these certificates will live as long as the sidecar is deployed. They are shared amongst multiple sidecar instances and will not be replaced during sidecar upgrades.
The sidecar-created certificate domains correspond to the sidecar DNS name you
provided during deployment. If you did not provide a DNS name, the certificate
uses the DNS name sidecar.app.cyral.com
If you are managing your own deployment code by using the Linux sidecar or managing directly the sidecar container, the self-signed certificate will be automatically created per instance. In such scenarios, should you prefer to share the same certificate across multiple instances, you are responsible for providing the same custom certificate for your sidecar instances.
Custom certificate
You can use a self-signed or a CA issued certificate and provide it to the sidecar in the form of a custom certificate.
note
It is your responsibility to manage the validity and renewal of a custom certificate.
A custom certificate follows the X.509 format and is comprised of two parts:
a public certificate and its private key.
The sidecar is only able to read certificates encoded in UTF-8, so make sure
to convert both the public certificate and the private key before providing them
to the sidecar.
warning
Windows commonly uses UTF-16 little-endian encoding. A UTF-16 certificate
or private key will not work in the sidecar. Make sure to convert them to
UTF-8 before providing to the sidecar.
Deploy a custom certificate
If you are using one of our quickstarts, refer to the Sidecar certificates documentation page of the quickstart of your choice for more information on how to deploy a customer certificate.
If you are managing the sidecar container directly, using the express installer or using a quickstart that does not have an external parameter to handle certificates, you can provide them to the sidecar following the steps below:
- Make sure your certificate and private key are encoded in
UTF-8. - Encode both the certificate and the private key in base 64. You can
easily do this by running
cat <file_name> | base64 -w 0. - Store the base64-encoded TLS and/or CA certificates and private keys in the following environment variables and pass them to the sidecar container upon initialization:
CYRAL_SIDECAR_CA_CERT=<base64-encoded CA certificate>
CYRAL_SIDECAR_CA_PRIVATE_KEY=<base64-encoded CA private key>
CYRAL_SIDECAR_TLS_CERT=<base64-encoded TLS certificate>
CYRAL_SIDECAR_TLS_PRIVATE_KEY=<base64-encoded TLS private key>