From 65646a9b3314a5da6885634d66a6faf0a04edd58 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Thu, 28 Sep 2023 18:19:15 -0700 Subject: [PATCH 1/4] Add CM BYO Root tutorial --- certificate-manager/byo-root.mdx | 150 +++++++++++++++++++++++++++++++ manifest.json | 4 + 2 files changed, 154 insertions(+) create mode 100644 certificate-manager/byo-root.mdx diff --git a/certificate-manager/byo-root.mdx b/certificate-manager/byo-root.mdx new file mode 100644 index 00000000..f2248f7f --- /dev/null +++ b/certificate-manager/byo-root.mdx @@ -0,0 +1,150 @@ +--- +title: "Smallstep Certificate Manager: Bring Your Own Root" +html_title: "Smallstep Certificate Manager: Bring Your Own Root" +description: Use your existing root to sign an intermediate certificate for use in Smallstep +--- + + +With the Smallstep platform, you can bring your existing PKI to us, by signing a Smallstep intermediate CA from your existing root. + +Intermediate CAs (also called subordinate CAs) are used to sign and issue leaf certificates to subscribers. Intermediates aren't generally included in trust stores, making them easier to revoke and rotate. This is why they are commonly used for online CAs like Smallstep Certificate Manager. + +This tutorial will walk you through importing your root CA certificate to Smallstep, and signing an intermediate CA that we'll use to issue certificates on your behalf. + +The steps are: +1. Upload your root CA certificate to Smallstep. +2. Customize your intermediate CA certificate properties. Smallstep will create an intermediate private key and a Certificate Signing Request (CSR) for you. +3. Download the CSR and use your root CA to sign in +4. Upload the signed certificate to Smallstep, and we will finish creating your Authority + +## Requirements + +All you need is a [Smallstep Certificate Manager](https://smallstep.com/signup) account and access to your existing root CA. +This feature requires an Advanced Authority. +It is recommended to use an airgapped machine to sign the CSR. + +## Overview + +The Smallstep app has a workflow for bringing your own root. +To find it, + +1. Sign into your Smallstep team. +2. Then, choose **Authorities** under **Certificate Manager** in the menu menu. +3. Select **Add an Authority**. +4. Select the **Default Authority** workflow. +5. Give your new CA a name and subdomain, and change the Authority Type to Advanced Authority. +6. On the next page, select "Upload external root" + +Here, you can upload the PEM file for your existing root CA certificate. +**Do not upload your root private key to Smallstep.** + +## Signing the Certificate Signing Request + +Smallstep will send a CSR file for you to download and sign. + +You will need to transfer the CSR file to your existing root CA and get it signed. Below we have examples of +how to do this using `step`, Active Directory Certificate Services, AWS Certificate Manager Private CA, OpenSSL, and CFSSL. + +### Use `step` to sign your intermediate CSR + +The `step` CLI can be used to sign an intermediate CSR using your existing root. + +```shell +step certificate sign --not-after 87600h --profile intermediate-ca --path-len 0 csr-9e63a172-EXAMPLE-5b0c7.csr root_ca.crt root_ca_key +``` + +### Active Directory Certificate Services + +Use the `certreq` tool. + +```shell +certreq -submit -attrib "CertificateTemplate:SubCA" csr-9e63a172-EXAMPLE-5b0c7.csr intermediate.crt +``` + +#### AWS Certificate Manager Private CA + +You can now use the following python script that uses issue-certificate to process the CSR: + +```python nocopy +import boto3 +import sys + +AWS_CA_ARN = '[YOUR_PRIVATE_CA_ARN]' + +csr = ''.join(sys.stdin.readlines()) + +client = boto3.client('acm-pca') +response = client.issue_certificate( + CertificateAuthorityArn=AWS_CA_ARN, + Csr=csr, + SigningAlgorithm='SHA256WITHRSA', + TemplateArn='arn:aws:acm-pca:::template/SubordinateCACertificate_PathLen1/V1', + Validity={ + 'Value': 5, + 'Type': 'YEARS' + } +) +print(f"Creating certificate with ARN {response['CertificateArn']}...", file=sys.stderr, end='') +waiter = client.get_waiter('certificate_issued') +waiter.wait( + CertificateAuthorityArn=AWS_CA_ARN, + CertificateArn=response['CertificateArn'] +) +print('done.', file=sys.stderr) +response = client.get_certificate( + CertificateArn=response['CertificateArn'], + CertificateAuthorityArn=AWS_CA_ARN +) +print(response['Certificate']) +``` + +To run it, fill in the ARN of your CA and run: + +```shell-session nocopy +$ python issue_certificate.py < csr-9e63a172-EXAMPLE-5b0c7.csr > intermediate.crt +``` + +#### OpenSSL + +```shell-session nocopy +openssl ca -config [ROOT_CA_CONFIG_FILE] \ + -extensions v3_intermediate_ca \ + -days 3650 -notext -md sha512 \ + -in csr-9e63a172-EXAMPLE-5b0c7.csr \ + -out intermediate.crt + ``` + +#### CFSSL + +For CFSSL you'll need a signing profile that specifies a 10-year expiry: +``` shell-session nocopy +$ cat > ca-smallstep-config.json < Date: Thu, 28 Sep 2023 18:21:52 -0700 Subject: [PATCH 2/4] Fix headers --- certificate-manager/byo-root.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/certificate-manager/byo-root.mdx b/certificate-manager/byo-root.mdx index f2248f7f..06cdb085 100644 --- a/certificate-manager/byo-root.mdx +++ b/certificate-manager/byo-root.mdx @@ -38,7 +38,7 @@ To find it, Here, you can upload the PEM file for your existing root CA certificate. **Do not upload your root private key to Smallstep.** -## Signing the Certificate Signing Request +## How to Sign the Certificate Signing Request Smallstep will send a CSR file for you to download and sign. @@ -61,7 +61,7 @@ Use the `certreq` tool. certreq -submit -attrib "CertificateTemplate:SubCA" csr-9e63a172-EXAMPLE-5b0c7.csr intermediate.crt ``` -#### AWS Certificate Manager Private CA +### AWS Certificate Manager Private CA You can now use the following python script that uses issue-certificate to process the CSR: @@ -104,7 +104,7 @@ To run it, fill in the ARN of your CA and run: $ python issue_certificate.py < csr-9e63a172-EXAMPLE-5b0c7.csr > intermediate.crt ``` -#### OpenSSL +### OpenSSL ```shell-session nocopy openssl ca -config [ROOT_CA_CONFIG_FILE] \ @@ -114,7 +114,7 @@ openssl ca -config [ROOT_CA_CONFIG_FILE] \ -out intermediate.crt ``` -#### CFSSL +### CFSSL For CFSSL you'll need a signing profile that specifies a 10-year expiry: ``` shell-session nocopy @@ -144,7 +144,7 @@ $ cfssl sign -ca ca.pem \ This process will yield a signed intermediate.crt certificate (or cert.pem for CFSSL). -### 4. Upload the certificate to Smallstep +## Conclusion You can now upload your signed certificate to Smallstep, and we'll create your new CA. From 7dba31fc1cec81dcadaf3bee8f7105a22495f969 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Tue, 10 Oct 2023 15:08:04 -0700 Subject: [PATCH 3/4] Add Vault support --- certificate-manager/byo-root.mdx | 26 ++++++++++++++++++++++---- tutorials/intermediate-ca-new-ca.mdx | 12 ++++++++++-- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/certificate-manager/byo-root.mdx b/certificate-manager/byo-root.mdx index 06cdb085..37041b7e 100644 --- a/certificate-manager/byo-root.mdx +++ b/certificate-manager/byo-root.mdx @@ -43,14 +43,18 @@ Here, you can upload the PEM file for your existing root CA certificate. Smallstep will send a CSR file for you to download and sign. You will need to transfer the CSR file to your existing root CA and get it signed. Below we have examples of -how to do this using `step`, Active Directory Certificate Services, AWS Certificate Manager Private CA, OpenSSL, and CFSSL. +how to do this using PEM files, Active Directory Certificate Services, AWS Certificate Manager Private CA, OpenSSL, and CFSSL. -### Use `step` to sign your intermediate CSR +### Root PEM certificate and key -The `step` CLI can be used to sign an intermediate CSR using your existing root. +If you have your root CA key and certificate files, the `step` CLI can be used to sign an intermediate CSR using your existing root. ```shell -step certificate sign --not-after 87600h --profile intermediate-ca --path-len 0 csr-9e63a172-EXAMPLE-5b0c7.csr root_ca.crt root_ca_key +step certificate sign \ + --not-after 87600h \ + --profile intermediate-ca \ + --path-len 0 \ + csr-9e63a172-EXAMPLE-5b0c7.csr root_ca.crt root_ca_key ``` ### Active Directory Certificate Services @@ -104,6 +108,20 @@ To run it, fill in the ARN of your CA and run: $ python issue_certificate.py < csr-9e63a172-EXAMPLE-5b0c7.csr > intermediate.crt ``` +### Hashicorp Vault + +You will need [`jq`](https://jqlang.github.io/jq/) installed, to extract the certificate PEM programmatically. + +Run: + +``` +INTERMEDIATE_CA_TTL="87600h" +vault write -format=json pki/root/sign-intermediate \ + csr=@csr-9a63a172-EXAMPLE-5b0c7.csr \ + format=pem_bundle \ + ttl=$INTERMEDIATE_CA_TTL | jq -r .data.certificate > intermediate.crt +``` + ### OpenSSL ```shell-session nocopy diff --git a/tutorials/intermediate-ca-new-ca.mdx b/tutorials/intermediate-ca-new-ca.mdx index bce88406..f8ced4f6 100644 --- a/tutorials/intermediate-ca-new-ca.mdx +++ b/tutorials/intermediate-ca-new-ca.mdx @@ -24,8 +24,16 @@ This tutorial will walk you through three ways of bootstrapping `step-ca` to cre ## Requirements -- **Open Source -** This tutorial assumes you have initialized and started up a `step-ca`instance using the steps in [Getting Started](../step-ca/getting-started.mdx). -- **[Smallstep Certificate Manager](https://smallstep.com/certificate-manager) -** Please contact [Smallstep Customer Success](mailto:support@smallstep.com) and we will assist in creating your intermediate authority off an existing Root. +This tutorial assumes you have initialized and started up a `step-ca`instance using the steps in [Getting Started](../step-ca/getting-started.mdx). + + +
+ Using Certificate Manager?
+ See Bring Your Own Root for Certificate Manager. +
+ + + ## Overview From 2962f11dac5a50a2be36059c8b268a01adf9d0b8 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 11 Oct 2023 09:14:40 -0700 Subject: [PATCH 4/4] Updates based on Hunter's feedback --- certificate-manager/byo-root.mdx | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/certificate-manager/byo-root.mdx b/certificate-manager/byo-root.mdx index 37041b7e..987b314f 100644 --- a/certificate-manager/byo-root.mdx +++ b/certificate-manager/byo-root.mdx @@ -5,7 +5,7 @@ description: Use your existing root to sign an intermediate certificate for use --- -With the Smallstep platform, you can bring your existing PKI to us, by signing a Smallstep intermediate CA from your existing root. +With the Smallstep platform, you can bring your existing PKI to us by signing a Smallstep intermediate CA from your existing root. Intermediate CAs (also called subordinate CAs) are used to sign and issue leaf certificates to subscribers. Intermediates aren't generally included in trust stores, making them easier to revoke and rotate. This is why they are commonly used for online CAs like Smallstep Certificate Manager. @@ -14,8 +14,8 @@ This tutorial will walk you through importing your root CA certificate to Smalls The steps are: 1. Upload your root CA certificate to Smallstep. 2. Customize your intermediate CA certificate properties. Smallstep will create an intermediate private key and a Certificate Signing Request (CSR) for you. -3. Download the CSR and use your root CA to sign in -4. Upload the signed certificate to Smallstep, and we will finish creating your Authority +3. Download the CSR and use your root CA to sign in. +4. Upload the signed certificate to Smallstep, and we will finish creating your Authority. ## Requirements @@ -33,7 +33,7 @@ To find it, 3. Select **Add an Authority**. 4. Select the **Default Authority** workflow. 5. Give your new CA a name and subdomain, and change the Authority Type to Advanced Authority. -6. On the next page, select "Upload external root" +6. On the next page, select "Upload external root." Here, you can upload the PEM file for your existing root CA certificate. **Do not upload your root private key to Smallstep.** @@ -43,11 +43,11 @@ Here, you can upload the PEM file for your existing root CA certificate. Smallstep will send a CSR file for you to download and sign. You will need to transfer the CSR file to your existing root CA and get it signed. Below we have examples of -how to do this using PEM files, Active Directory Certificate Services, AWS Certificate Manager Private CA, OpenSSL, and CFSSL. +how to do this using the [`step` CLI](../step-cli), Active Directory Certificate Services, HashiCorp Vault, AWS Certificate Manager Private CA, OpenSSL, and CFSSL. ### Root PEM certificate and key -If you have your root CA key and certificate files, the `step` CLI can be used to sign an intermediate CSR using your existing root. +If you have your root CA key and certificate files, the [`step` CLI](../step-cli) can be used to sign an intermediate CSR using your existing root. ```shell step certificate sign \ @@ -164,5 +164,8 @@ This process will yield a signed intermediate.crt certificate (or cert.pem for C ## Conclusion -You can now upload your signed certificate to Smallstep, and we'll create your new CA. +You're all set! 🎉 +You can now upload your signed certificate to Smallstep, and we'll create your new CA. +All of your clients that trust you existing root CA will now trust your Smallstep CA as well. +And, you can continue to use your existing CA infrastructure to issue certificates as needed.