Renewing certificates in a private PKI - AWS Certificate Manager

Renewing certificates in a private PKI

ACM certificates that were signed by a private CA from ACM Private CA are eligible for managed renewal. Unlike publicly trusted ACM certificates, a certificate for a private PKI requires no validation. Trust is established when an administrator installs the appropriate root CA certificate in client trust stores.

Note

Only certificates obtained using the ACM console or the RequestCertificate action of the ACM API are eligible for managed renewal. Certificates issued directly from ACM Private CA using the IssueCertificate action of the PCA API are not managed by ACM.

When a managed certificate is 60 days away from expiration, ACM automatically attempts to renew it. This includes certificates that were exported and installed manually (for example, in an on-premises data center). Customers can also force renewal at any time using the RenewCertificate action of the ACM API. For a sample Java implementation of forced renewal, see Renewing a certificate.

After renewal, a certificate's deployment into service occurs in one of the following ways:

Automating export of renewed certificates

The following procedure provides an example solution for automating export of your private PKI certificates when ACM renews them. This example only exports a certificate and its private key out of ACM; after export, the certificate must still be installed on its target device.

To automate certificate export using the console

  1. Following procedures in the AWS Lambda Developer Guide, create and configure a Lambda function that calls ACM export API.

    1. Create a Lambda function.

    2. Create a Lambda execution role for your function and add the following trust policy to it. The policy grants permission to the code in your function to retrieve the renewed certificate and private key by calling the ExportCertificate action of the ACM API.

      { "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":"acm:ExportCertificate", "Resource":"*" } ] }
    3. Add application code to your function such as the following sample in Python. This code examines the event that triggers the function to call the ExportCertificate action. For more information, see Building Lambda functions with Python.

      import json import boto3 acm = boto3.client('acm') passphrase = b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x00' def lambda_handler(event, context): context.log("Incoming Event : " + json.dumps(event) + "\n"); certificateArn = event['resources'][0]; context.log("Renewed Certificate ARN : " + certificateArn + "\n"); description = event['detail']['eventDescription'][0]['latestDescription']; if "completed the renewal" in description: response = acm.export_certificate(CertificateArn=certificateArn,Passphrase=passphrase) certificate = response['Certificate'] certificateChain = response['CertificateChain'] encrPrivateKey = response['PrivateKey'] context.log("Certificate : " + certificate + "\n"); context.log("Certificate Chain : " + certificateChain + "\n"); context.log("Encrypted Private Key : " + encrPrivateKey + "\n"); #TODO Install the private key, cert and chain to where it will be consumed return { 'statusCode': 200, }
  2. Create a rule in Amazon EventBridge to listen for ACM health events and call your Lambda function when it detects one. ACM writes to an AWS Health event each time it attempts to renew a certificate. For more information about these notices, see Check the status using Personal Health Dashboard (PHD).

    Configure the rule by adding the following event pattern.

    { "source":[ "aws.health" ], "detail-type":[ "AWS Health Event" ], "detail":{ "service":[ "ACM" ], "eventTypeCategory":[ "scheduledChange" ], "eventTypeCode":[ "AWS_ACM_RENEWAL_STATE_CHANGE" ] }, "resources":[ "arn:aws:acm:region:account:certificate/certificate_ID" ] }
  3. Complete the renewal process by manually installing the certificate on the target system.

Testing managed renewal of private PKI certificates

You can use the ACM API or AWS CLI to manually test the configuration of your ACM managed renewal workflow. By doing so, you can confirm that your certificates will be renewed automatically by ACM prior to expiration.

Note

You can only test the renewal of certificates issued by ACM Private CA.

When you use API actions or CLI commands described below, ACM attempts to renew the certificate. If the renewal succeeds, ACM updates the certificate metadata displayed in the management console or in API output. If the certificate is associated with an ACM integrated services, the new certificate is deployed and a renewal event is generated in Amazon CloudWatch Events. If the renewal fails, ACM returns a error and suggests remedial action. (You can view this information using the describe-certificate command.) If the certificate is not deployed through an integrated service, you still need to export it and manually install it on your resource.

Important

In order to renew your ACM Private CA certificates with ACM, you must first grant the ACM service principal permissions to do so. For more information, see Assigning Certificate Renewal Permissions to ACM.

To manually test certificate renewal (AWS CLI)

  1. Use the renew-certificate command to renew a private exported certificate.

    aws acm renew-certificate \ --certificate-arn arn:aws:acm:region:account:certificate-authority/CA_ID/certificate/certificate_ID
  2. Then use the describe-certificate command to confirm that the certificate's renewal details have been updated.

    aws acm describe-certificate \ --certificate-arn arn:aws:acm:region:account:certificate-authority/CA_ID/certificate/certificate_ID

To manually test certificate renewal (ACM API)

  • Send a RenewCertificate request, specifying the ARN of the private certificate to renew. Then use the DescribeCertificate operation to confirm that the certificate's renewal details have been updated.