How to create certificates with custom extensions using AWS Certificate Manager Private CA

Digital certificates, also known as X.509 or TLS/SSL certificates, are used to prove the identity of entities like web servers or VPN users and to establish secure communication channels between them. In this blog post, I’ll discuss certificate extensions. You can use certificate extensions for applications beyond the common use case of identifying TLS server endpoints. These additional applications include code signing, signing Online Certificate Status Protocol (OCSP) responses, TLS clients for establishing two-way (mutual) authentication, and custom applications that include extensions you specify. I’ll also discuss how you can use AWS Identity and Access Management (IAM) policies to selectively control who can issue each kind of certificate. Finally, I’ll describe two use cases for certificate templates: OCSP signing and two-way TLS. A certificate template allows CA administrators and public key infrastructure (PKI) operators a way to control and specify X.509 certificate extensions for the certificates they issue with AWS Certificate Manager Private Certificate Authority (ACM Private CA).

What are certificate extensions?

Extension fields (“extensions”) define the usage of the certificate. The values of these fields — and the corresponding allowed usage of the certificates — can be very different. Certificates bind a subject name and public key for the named subject with a digital signature from a certificate authority. What makes one certificate useful for signing code, while another certificate is useful for terminating TLS are the extension fields in the certificate.

Digital certificates used on the internet (and with other modern applications) are defined in the internet standards specification RFC 5280. Extensions were introduced in v3 of the X.509 specification as a way to give certificates more flexibility. There are 19 extension types defined in RFC 5280, but the extensions widely used for defining certificate usage are basic constraints, key usage, and extended key usage.

• Basic constraints indicate whether the certificate can be used to identify a certificate authority versus an end entity, such as a web server. Certificates that include basic constraints with a value of “CA=true” are CA certificates and are allowed to issue other certificates.
• Key usage refers to the purpose of the public key contained in the certificate and the actions that can be performed with the key. An example of a key usage value is “digital signature.” If you use this value, it allows your public key to be used for verifying digital signatures (other than signatures on certificates and CRLs), such as those used for authentication and integrity, like when a TLS connection is established. The key usage extension is limited to nine key usage values that define the specific cryptographic functions the associated key pair can perform. Those values are: decipherOnly, encipherOnly, cRLSign, keyCertSign, keyAgreement, dataEncipherment, keyEncipherment, contentCommitment, nonRepudiation, and digitalSignature.
• In contrast to key usage, the extended key usage extension defines the specific protocols and functions that the certificate can be used with. For example, one extended key usage value is “TLS web server authentication,” which indicates the public key can be used to terminate TLS as a server. There’s also “TLS web client authentication,” which indicates the key can be used to terminate TLS as a client, and “code signing,” which means the key can be used to validate digital signatures on software. RFC5246 defines the TLS protocol and the use of server and client certificates.

Available templates

ACM Private CA offers ten templates so you can control and specify the X.509 certificate extensions for the certificates you issue with ACM Private CA. The templates allow CA administrators to maintain control of specific X.509 certificate extensions — including key usage, extended key usage, and basic constraints — while allowing users to customize certificates with additional extensions.

Template Details

End-entity certificates

Use the end-entity certificate templates to create certificates for resources that are TLS clients or servers, such as web and application servers, API endpoints, or TLS clients like IoT (internet of things) devices and API users. All of the certificates issued by these template types have the key usage values of “digital signature” and “key encipherment.”

• EndEntityCertificate — This template generates certificates that can be used as the server certificate in a one-way TLS session or as the server or client certificate in a two-way TLS handshake. This certificate has the extended key usage values of “TLS web server authentication” and “TLS client server authentication.”
• EndEntityClientAuthCertificate — This template only generates certificates used by the client in two-way TLS. This certificate has an extended key usage value of “TLS Client Server Authentication.”
• EndEntityServerAuthCertificate — This template only generates server certificates used for one-way or two-way TLS. This certificate has an extended key usage value of “TLS Web Server Authentication.”

OCSP signing certificates

An Online Certificate Status Protocol (OCSP) responder provides a mechanism to check if a certificate has been revoked. Clients that check certificate revocation status with OCSP require a response signed either by the CA or a certificate issued by the CA. Creating an OCSP signing certificate to sign OCSP responses allows you to offload response generation and signing from the CA to the responder or to another server. The ACM Private CA OCSPSigningCertificate template allows you to issue OCSP signing certificates that you can use to sign OCSP responses and operate your own OCSP responder. The key usage value for an OCSP certificate is “digital signature” and the extended key usage value is “OCSP Signing.”

Code signing certificates

Software developers use code signing certificates to digitally sign software, apps, drivers, and programs. Operating systems check code signatures before running the code to ensure it was signed by a trusted entity and has not been modified by an unauthorized third-party. The ACM Private CA CodeSigningCertificate template allows you to issue code signing certificates. The key usage value of a code signing certificate is “digital signatures” and the extended key usage value is “code signing.”

CSR passthrough certificates

A certificate signing request (CSR) is an identity document that contains a public key and a subject. You can also configure the CSR to contain a set of extension requests that the requested certificate should inclue. Normally, the CA ignores certificate extension requests included in the CSR rather than including them in the certificate it issues. In many cases, “ignore” is desired behavior because it allows the CA to remove unnecessary extensions and enforce the CA configurations. The templates described so far work this way, but there is another set of templates for which extensions from the CSR are passed to the certificate.

Private CA users can customize certificates by adding any X.509 extension to the certificate signing request (CSR) when they issue the certificate. If the CSR includes extensions that overlap with the extensions in the template, the value from the template will be used. The CA administrator can thus control the extensions in certificates by controlling access to the templates. One common example is for code signing certificates. For example, the subject directory attributes extension can be used to convey identification attributes such as the nationality of the certificate subject. If a customer is issuing certificates for different geographic locations from a single CA, they can include the SubjectDirectoryAttributes value in each individual CSR and have it correspond to the location of the domain for the certificate.

The ten certificate templates can be broken up into five pairs of templates, as shown in Table 1 below. For example, one pair would be EndEntityCertificate and EndEntityCertificate_CSRPassthrough. Each member of the pair issues the same certificate extension but with one major difference: the first template in the pair utilizes the CA values as the override for all the X509v3 fields. The second template (the CSRPassthrough template) allows CA administrators to maintain control of the most important and fundamental X.509 certificate extensions that determine how the certificate can be used, including key usage, extended key usage, and basic constraints.

The CSRPassthrough templates allow users making certificate requests to customize their certificates by including additional extensions when necessary. For example, CA users who want to build their own online certificate status protocol (OCSP) responders can include the location of the responder in certificates they issue by including a special authority information access (AIA) extension that clients use to identify the OCSP responder endpoint.

Table 1: The full list of supported templates

How to issue a certificate with a template

You can use ACM Private CA to issue a certificate with a template by using the ACM Private CA Command Line Interface (CLI). Here’s an example of a call to create a Server-Only TLS certificate:

aws acm-pca issue-certificate --certificate-authority-arn arn:aws:acm-pca:us-west-2:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 --csr file://C:\cert_1.csr --signing-algorithm "SHA256WITHRSA" --template-arn “arn:aws:acm-pca:::template/EndEntityServerAuthCertificate/V1” --validity Value=365,Type="DAYS"

Here are the pieces of this command:

• The command is <issue-certificate>
• The certificate authority ARN identifies the private CA that will be used to issue the certificate.
• The CSR is a pointer to the file which contains the CSR.
• The signing algorithm is used by the CA to sign the final certificate; in this example it’s SHA-256 with RSA.
• The template ARN is for a server-only TLS certificate. The ACM Private CA documentation has the full list of templates.
• The validity period of this certificate is set to 365 days.

This command creates a certificate with the extended key usage extension value of clientAuth. Other than that change, it’s identical to the EndEntityCertificate template as specified in the ACM Private CA User Guide.

How to configure user-based permissions

You can combine templates with Identity and Access Management (IAM) permissions to create roles with fine-grained access controls that are assigned to individuals or systems. In AWS, an IAM role has specific permissions that determine what the identity can and cannot do in AWS. For example, you might have a team in charge of building and maintaining OCSP infrastructure. The account this team uses could be configured so that it only has permission to use the OCSP signing template, as opposed to being able to issue any type of certificate. In other words, you can restrict their issuance of certificates to align with their job responsibilities. You could also use IAM policies to grant or deny the team permission to use the CSR Passthrough Template.

Here’s a sample of the IAM permissions which would deny the use of CSR Passthrough templates. This template might be used to ensure that no certificate requestors inserted custom values through a CSR passthrough template variant.

{
    "Effect": "Deny",
    "Action": [
        "acm-pca:IssueCertificate"
    ],
    "Resource": "arn:aws:acm-pca:*:*:certificate-authority/*",
    "Condition": {
        "StringLike": {
            "acm-pca:TemplateArn": [
                "arn:aws:acm-pca:::template/*CSRPassthrough*/V*"
            ]
        }
    }
},

Two use cases for certificate extensions

IoT devices with client-only TLS certificates

To authenticate and allow for secure communications with an IoT device, manufacturers frequently install TLS certificates on their devices. The production system that installs TLS certificates requires a CA in order to issue certificates with the appropriate extensions. Let’s say that a device manufacturer only wants their IoT devices to be able to initiate a TLS connection with the server. Using certificates with the client-only TLS template would prevent someone from trying to establish a connection with the device to start an inappropriate communication channel. The manufacturer also wants to enforce a fixed set of certificate extensions for the production environment, while allowing more flexibility in the extensions in locations that are considered more physically secure.

To achieve this, the manufacturer can restrict the issuing CA via IAM policies, enforcing the use of an End Entity Client Certificate (EndEntityClientAuthCertificate) that includes specific and fixed certificate extensions that will prevent the use of CSR Passthrough in the production environment. This configuration will prevent the certificate from being used as the server of a TLS transaction for inappropriate access from a third party. Not enabling CSR passthrough ensures the certificate fields are set to defined/required values.

This is the command to create an IoT certificate with client-only TLS:

aws acm-pca issue-certificate --certificate-authority-arn arn:aws:acm-pca:us-west-2:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 --csr file://C:\cert_2.csr --signing-algorithm "SHA256WITHRSA" --template-arn “arn:aws:acm-pca:::template/EndEntityClientAuthCertificate/V1” --validity Value=40,Type="YEARS"

This certificate is similar to the preceding certificate example, with two major changes: It will only work as a server-only certificate, and the validity is 40 years instead of one year. The 40-year validity is because IoT devices won’t return to the floor to be able to get a new certificate issued. After 40 years (which is beyond the expected lifespan of the device), the certificate would expire and the device would no longer be able to communicate.

In this example, the value of the ExtendedKeyUsage field is configured to “clientAuth.”

OCSP responder

One element of the construction of an OCSP responder is the OCSP signing certificate. (I’ve described the details of how the elements of an OCSP are built in the “OCSP signing certificates” section of this post.) When configuring an OCSP service, the administrator responsible for renewing that certificate should be given permission for that template. The OCSP signing certificate normally has a short duration, so the certificate needs to be renewed frequently. An important note is that an OCSP signing certificate generated by ACM Private CA only supports certificates issued by the same CA that created the OCSP signing certificate. It cannot be used to handle certificates up or down the CA hierarchy.

The command to generate a certificate for this use case is:

aws acm-pca issue-certificate --certificate-authority-arn arn:aws:acm-pca:us-west-2:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 --csr file://C:\cert_3.csr --signing-algorithm "SHA256WITHRSA" --template-arn “arn:aws:acm-pca:::template/OCSPSigningCertificate_CSRPassthrough/V1” --validity Value=365,Type="DAYS" --idempotency-token 1234

This certificate must be a CSR Passthrough because the Authority Information Access (AIA) will have the value ocsp for the accessMethod field and the URI address of the OCSP responder in the accessLocation field. Setting these two values requires CSR passthrough.

Conclusion

Certificates issued by Private CA can be used for a variety of use cases. TLS certificates are the most common. You can also generate certificates for other uses such as code signing. I’ve shown some examples of how to use templates in ACM to ensure that the certificates are created with the correct extensions. As your organization looks beyond TLS, or expands to the point where privilege for use matters, certificate templates can support the design and security guidelines of your environment.

To get started with ACM Private CA for TLS, OCSP or other use cases, read the getting started pages of the ACM Private CA documentation. If you have feedback about this blog post, submit comments in the Comments section below. If you have questions about this blog post, start a new thread on the Amazon AWS Certificate Manager forum or contact AWS Support.

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.