Skip to main content
Version: v4.1

Certificates for CloudFormation-deployed sidecars

You can use Cyral's default sidecar-created 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 are CloudFormation stacks that can be deployed to AWS after you set the values of a few parameters.

Let's Encrypt signed certificate

The stack we provide will manage the creation and automatic renewal of Let's Encrypt certificates.

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

Follow the steps below to deploy it:

  1. Check which region you are deploying to

    • If you are deploying to us-east-1, us-east-2, us-west-1 or us-west-2, then follow these steps:

      • Create the CloudFormation stack in AWS.

      • For Template source, choose Amazon S3 URL

      • For Amazon S3 URL, specify the Cyral sidecar custom certificate for Let's Encrypt template download URL as follows:

        https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-letsencrypt-cft-latest.yaml

        where region is one of us-east-1, us-east-2, us-west-1 or us-west-2

    • If you are deploying to any other region, follow these steps:

      • Download the CloudFormation template from the following URL:

        https://cyral-public-assets-us-east-1.s3.us-east-1.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-letsencrypt-cft-latest.yaml
      • Create the CloudFormation stack in AWS.

      • For Template source, choose Upload a template file and provide the downloaded file.

      note

      You also have the option to use a versioned path for the custom certificate template. Form the versioned URL according to the following general format:

      https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/<version>/sidecar-custom-certificate-letsencrypt-cft-<version>.yaml

      where version is your desired version as discussed with Cyral support, for example, v0.2.6

      For example, to get version v0.1.0 for running in us-east-2, you would use the URL,

      https://cyral-public-assets-us-east-2.s3.us-east-2.amazonaws.com/sidecar-custom-certificate/v0.1.0/sidecar-custom-certificate-letsencrypt-cft-v0.1.0.yaml

Parameters for certificate creation

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

    • SidecarDomain: The domain to generate a certificate for. For example, my-snowflake-sidecar.mydomain.com

    • Provide a value for one of the following:

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

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

        SidecarDomains="snowflake.foo.com"
        SidecarSubdomains=""
        SnowflakeAccountRegion="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
    • StagingCertificate: 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 stack will perform the certificate renewal:

    • RegistrationEmail: (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.

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

    • RenewalIntervalWindowStart: 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 SidecarCustomCertificateSecretARN and SidecarCustomCertificateRoleARN. 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 SidecarCustomCertificateRoleARN and SidecarCustomCertificateSecretARN. These parameters must be used to feed the parameters with same names in this stack, as follows:

    • SidecarCustomCertificateSecretARN: (Optional) ARN of the secret to store the certificate in. Use this parameter if the sidecar is hosted in a different account.
    • SidecarCustomCertificateRoleARN: (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:
    • LambdaCodeS3Bucket: (Optional) S3 bucket that contains the Lambda deployment package. LEAVE EMPTY UNLESS YOU WANT TO OVERRIDE THE DEFAULT.
    • LambdaCodeS3Key: (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 template 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.

  • CloudFormation templates have a maximum size of 4096 characters for parameter values. Therefore, if your base64-encoded certificate or private key have more than 4096 characters, you must split it into parts of no more than 4096 characters each, and provide the parts in order to the template. The template allows a maximum of three parts.

  • 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 stack is created, provide the secret ARN found in the output parameter SecretId 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.

Deploy your certificate

Follow the steps below to deploy it:

  1. Check which region you are deploying to

    • If you are deploying to us-east-1, us-east-2, us-west-1 or us-west-2, then follow these steps:

      • Create the CloudFormation stack in AWS.

      • For Template source, choose Amazon S3 URL

      • For Amazon S3 URL, specify the Cyral sidecar custom certificate template download URL as follows:

        https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-cft-latest.yaml

        where region is one of us-east-1, us-east-2, us-west-1 or us-west-2

    • If you are deploying to any other region, follow these steps:

      • Download the CloudFormation template from the following URL:

        https://cyral-public-assets-us-east-1.s3.us-east-1.amazonaws.com/sidecar-custom-certificate/sidecar-custom-certificate-cft-latest.yaml
      • Create the CloudFormation stack in AWS.

      • For Template source, choose Upload a template file and provide the downloaded file.

      note

      You also have the option to use a versioned path for the custom certificate template. Form the versioned URL according to the following general format:

      https://cyral-public-assets-<region>.s3.<region>.amazonaws.com/sidecar-custom-certificate/<version>/sidecar-custom-certificate-cft-<version>.yaml

      where version is your desired version as discussed with Cyral support, for example, v0.2.6

      For example, to get version v0.1.0 for running in us-east-2, you would use the URL,

      https://cyral-public-assets-us-east-2.s3.us-east-2.amazonaws.com/sidecar-custom-certificate/v0.1.0/sidecar-custom-certificate-cft-v0.1.0.yaml
  2. Use the following parameters to provide the certificate details:

    • CustomCertificateBase64PartX: Base64-encoded full certificate chain.

    • CustomPrivateKeyBase64PartX: Base64-encoded private key.

    Where PartX can be Part1, Part2 or Part3. Each part can contain at most 4096 characters. For example, if your base64-encoded certificate has 8000 characters, you can divide it into two parts of 4000 characters each. In this case, provide the first part to CustomCertificateBase64Part1, and the second part to CustomCertificateBase64Part2.