Certificates for Terraform-deployed sidecars

You can use Cyral's default sidecar-installed certificate or use a custom certificate to secure the communications between the Cyral control plane and the sidecar.

In this page we provide you two ways of deploying a custom certificate (signed by Let's Encrypt in a Route53 domain or signed by the certificate authority of your choice) to your sidecar. Both use Terraform modules that can be deployed to AWS after you set the values of a few parameters.

Let's Encrypt signed certificate

Our Terraform module for custom certificates issued by Let's Encrypt will manage the creation and automatic renewal of Let's Encrypt certificates.

Once the module is deployed, provide the secret ARN found in the output parameter certificate_secret_arn to the control plane so that the sidecar can use the certificate. See how to do it here.

1. We provide some examples to help you deploy the module in some common use cases:
   • Custom certificate renewal
   • Domain name and sidecar in different accounts
   • Domain name and sidecar in different accounts combined with sidecar module for AWS
   • Snowflake sidecar

Parameters for certificate creation

1. Use the following parameters to define how the module will create the certificate:

   • sidecar_domain: The domain to generate a certificate for. Ex: my-snowflake-sidecar.mydomain.com

   • Provide a value for one of the following:

     • sidecar_subdomains: Specify the list of subdomains to generate a certificate for, delimited by comma (Note! Use the snowflake_account_region setting instead, if you're configuring a Snowflake sidecar); or

     • snowflake_account_region: Use this parameter for Snowflake deployments. Specify the AWS region your Snowflake account is running on. For example, us-east-1. If snowflake_account_region is set, the program will automatically append a set of default subdomains to sidecar_subdomains. For example, given the configuration

       sidecar_domains="snowflake.foo.com"
       sidecar_subdomains=""
       snowflake_account_region="us-east-1"

       the list of subdomains will be defined as:

       *.snowflake.foo.com
       *.s3.snowflake.foo.com
       *.s3.us-east-1.snowflake.foo.com
       *.s3-us-east-1.snowflake.foo.com

   • staging_certificate: Enter true to use a staging (test) certificate. Default is false. Use this only for testing; staging certificates are not valid for production use.

Parameters for certificate renewal

1. Use the following parameters to define how the module will perform the certificate renewal:

   • registration_email: (Optional) Administrative email to use for registration and recovery contact with Let's Encrypt.

     This parameter is optional, but we recommend you don't leave it empty. Enter one or more emails (delimited by comma) that will be used to send alerts that the certificate is close to its expiry date. Let's Encrypt will take care of sending the notification emails.

     Note that the application should automatically renew the certificate. However, if the application is failing to do that for whatever reason, this is the means by which you will be alerted.

   • renewal_interval_checks: How often to check if certificate should be renewed, in days. Default is 1 day.

   • renewal_interval_window_start: Number of days before expiry date to renew the certificate. Default is 35 days.

Parameters for cross-account deployment

If you have a scenario in which you have two different accounts that you will deploy the sidecar and another account that will manage the DNS using Route53, then you need to use parameters sidecar_custom_certificate_secret_arn and sidecar_custom_certificate_role_arn. Suppose you have the following configuration:

• Account 111111111111 used to manage DNS using Route53
• Account 222222222222 used to deploy the sidecar

1. You must first deploy the sidecar in account 222222222222, specifying the account 111111111111 in parameter SidecarCustomCertificateAccountID.

2. Once the sidecar is deployed, it will output parameters sidecar_custom_certificate_role_arn and sidecar_custom_certificate_secret_arn. These parameters must be used to feed the parameters with same names in this module, as follows:

   • sidecar_custom_certificate_role_arn: (Optional) ARN of the secret to store the certificate in. Use this parameter if the sidecar is hosted in a different account.
   • sidecar_custom_certificate_role_arn: (Optional) Role to assume when accessing secrets manager. Use this paramenter if the sidecar is hosted in a different account.

Parameters for lambda configuration

1. If you want to deploy a lambda from a different bucket or with a different version, use the following parameters:
   • lambda_code_s3_bucket: (Optional) S3 bucket that contains the Lambda deployment package. LEAVE EMPTY UNLESS YOU WANT TO OVERRIDE THE DEFAULT.
   • lambda_code_s3_key: (Optional) Object key for the Lambda deployment package on the S3 bucket. LEAVE EMPTY UNLESS YOU WANT TO OVERRIDE THE DEFAULT.

Use your own certificate

note

Manually building a TLS certificate / private key pair is not recommended unless your team has expertise in certificate generation and validation. Contact Cyral support if you need help.

We also provide a solution for those willing to use their own certificate emitted by the Certificate Authority of their choice. Before choosing to use your own certificate, be sure to understand the limitations of this solution:

• The module provided by Cyral must be deployed to the same account where the sidecar is hosted.

• The certificate must be in X.509 format, and encoded in the UTF-8 charset.

• The certificate and private key must be base64-encoded so it can be used by our template.

• It is your responsibility to manage the validity and renewal of the provided certificate and private key. None of the templates will renew or control the validity of the certificate.

Once the module is deployed, provide the secret ARN found in the output parameter certificate_secret_arn to the control plane so that the sidecar can use the certificate. See how to do it here.

Verify your certificate

Prior to deploying your certificate and private key, it is good practice to verify their format. Below, we provide you with some steps you can take to verify your certificate. We will assume pkey.pem contains your private key, full_chain.pem contains your X.509 full certificate chain, and ca.pem contains the certificate(s) for the intermediary and root CAs.

1. Verify the charset. The certificate and private key must be encoded in the UTF-8 charset. In Linux or macOS X, you can check the charset by running file -i full_chain.pem and file -i pkey.pem. Verify that it displays charset=us-ascii or charset=utf-8.

   tip

   Windows commonly uses UTF-16 little-endian encoding. A UTF-16 certificate or private key will not work in the sidecar. If you are using Windows, you can use the following command in Powershell to create a file file_utf8.pem with the UTF-8 content corresponding to the UTF-16-encoded file file_utf16.pem.

   Get-Content file_utf16.pem -Encoding Unicode | Set-Content -Encoding UTF8 file_utf8.pem

2. Verify the certificate chain. To check that your full certificate chain is valid, you can run openssl verify -CAfile ca.pem full_chain.pem. Check that it displays full_chain.pem: OK.

3. Verify that certificate and private key match. Verifying that the certificate and private key match is trickier. It will depend on which public key algorithm you use. For RSA, you can use openssl rsa. Run openssl rsa -modulus -noout -in pkey.pem | openssl md5 to see the checksum of the modulus for the private key, and openssl x509 -noout -modulus -in full_chain.pem | openssl md5 to see the checksum of the modulus for the certificate. Check that the checksum of the certificate and private key modulus match.

4. Verify base64-encoding. If you encode the chain and private key in base64 prior to using our templates, you can check the validity of the encoding in a Linux or macOS X machine by running cat full_chain_b64 | base64 -d 1>/dev/null, considering full_chain_b64 contains your full chain in base64 format (similar command for private key). Verify that there is no output. You may also run cat full_chain_b64 | base64 -d to visually check that it looks right.

   Note: Terraform has a built-in function to base64-encode the certificate, base64encode. Make sure not to base64-encode the certificate twice.

Deploy your certificate

Use our Terraform module for custom certificates to deploy your own certificate and use it in the sidecar.

1. Use the following parameters to provide the certificate details:

   • custom_certificate_base64: Base64-encoded full certificate chain.

   • custom_private_key_base64: Base64-encoded private key.