AWS Private CA

(1)

AWS Private CA

API Reference

API Version 2017-08-22

(2)

AWS Private CA: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

This is the ACM Private CA API Reference. It provides descriptions, syntax, and usage examples for each of the actions and data types involved in creating and managing private certiﬁcate authorities (CA) for your organization.

The documentation for each action shows the Query API request parameters and the XML response.

Alternatively, you can use one of the AWS SDKs to access an API that's tailored to the programming language or platform that you're using. For more information, see AWS SDKs.

Each ACM Private CA API operation has a quota that determines the number of times the operation can be called per second. ACM Private CA throttles API requests at diﬀerent rates depending on the operation. Throttling means that ACM Private CA rejects an otherwise valid request because the request exceeds the operation's quota for the number of requests per second. When a request is throttled, ACM Private CA returns a ThrottlingException error. ACM Private CA does not guarantee a minimum request rate for APIs.

To see an up-to-date list of your ACM Private CA quotas, or to request a quota increase, log into your AWS account and visit the Service Quotas console.

This document was last published on March 6, 2022.

(9)

Actions

The following actions are supported:

• CreateCertiﬁcateAuthority (p. 3)

• CreateCertiﬁcateAuthorityAuditReport (p. 9)

• CreatePermission (p. 13)

• DeleteCertiﬁcateAuthority (p. 17)

• DeletePermission (p. 20)

• DeletePolicy (p. 23)

• DescribeCertiﬁcateAuthority (p. 26)

• DescribeCertiﬁcateAuthorityAuditReport (p. 31)

• GetCertiﬁcate (p. 35)

• GetCertiﬁcateAuthorityCertiﬁcate (p. 39)

• GetCertiﬁcateAuthorityCsr (p. 42)

• GetPolicy (p. 45)

• ImportCertiﬁcateAuthorityCertiﬁcate (p. 48)

• IssueCertiﬁcate (p. 53)

• ListCertiﬁcateAuthorities (p. 60)

• ListPermissions (p. 66)

• ListTags (p. 70)

• PutPolicy (p. 74)

• RestoreCertiﬁcateAuthority (p. 78)

• RevokeCertiﬁcate (p. 81)

• TagCertiﬁcateAuthority (p. 85)

• UntagCertiﬁcateAuthority (p. 88)

• UpdateCertiﬁcateAuthority (p. 91)

(10)

CreateCertiﬁcateAuthority

Creates a root or subordinate private certificate authority (CA). You must specify the CA configuration, an optional configuration for Online Certificate Status Protocol (OCSP) and/or a certificate revocation list (CRL), the CA type, and an optional idempotency token to avoid accidental creation of multiple CAs. The CA configuration specifies the name of the algorithm and key size to be used to create the CA private key, the type of signing algorithm that the CA uses, and X.500 subject information. The OCSP configuration can optionally specify a custom URL for the OCSP responder. The CRL configuration specifies the CRL expiration period in days (the validity period of the CRL), the Amazon S3 bucket that will contain the CRL, and a CNAME alias for the S3 bucket that is included in certificates issued by the CA.

If successful, this action returns the Amazon Resource Name (ARN) of the CA.

ACM Private CA assets that are stored in Amazon S3 can be protected with encryption. For more information, see Encrypting Your CRLs.

NoteBoth PCA and the IAM principal must have permission to write to the S3 bucket that you specify.

If the IAM principal making the call does not have permission to write to the bucket, then an exception is thrown. For more information, see Access policies for CRLs in Amazon S3.

Request Syntax

{ "CertificateAuthorityConfiguration": { "CsrExtensions": {

"KeyUsage": {

"CRLSign": boolean,

"DataEncipherment": boolean, "DecipherOnly": boolean, "DigitalSignature": boolean, "EncipherOnly": boolean, "KeyAgreement": boolean, "KeyCertSign": boolean, "KeyEncipherment": boolean, "NonRepudiation": boolean },

"SubjectInformationAccess": [ {

"AccessLocation": { "DirectoryName": { "CommonName": "string", "Country": "string",

"DistinguishedNameQualifier": "string", "GenerationQualifier": "string", "GivenName": "string",

"Initials": "string", "Locality": "string", "Organization": "string", "OrganizationalUnit": "string", "Pseudonym": "string",

"SerialNumber": "string", "State": "string", "Surname": "string", "Title": "string"

},

"DnsName": "string", "EdiPartyName": {

"NameAssigner": "string", "PartyName": "string"

},

"IpAddress": "string",

(11)

Request Parameters

"OtherName": { "TypeId": "string", "Value": "string"

},

"RegisteredId": "string", "Rfc822Name": "string",

"UniformResourceIdentifier": "string"

},

"AccessMethod": {

"AccessMethodType": "string", "CustomObjectIdentifier": "string"

} } ] },

"KeyAlgorithm": "string", "SigningAlgorithm": "string", "Subject": {

"CommonName": "string", "Country": "string",

"DistinguishedNameQualifier": "string", "GenerationQualifier": "string",

"GivenName": "string", "Initials": "string", "Locality": "string", "Organization": "string", "OrganizationalUnit": "string", "Pseudonym": "string",

} },

"CertificateAuthorityType": "string", "IdempotencyToken": "string",

"KeyStorageSecurityStandard": "string", "RevocationConfiguration": {

"CrlConfiguration": { "CustomCname": "string", "Enabled": boolean,

"ExpirationInDays": number, "S3BucketName": "string", "S3ObjectAcl": "string"

},

"OcspConfiguration": { "Enabled": boolean,

"OcspCustomCname": "string"

} },

"Tags": [ {

"Key": "string", "Value": "string"

} ] }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 130).

The request accepts the following data in JSON format.

(12)

Request Parameters

CertiﬁcateAuthorityConﬁguration (p. 3)

Name and bit size of the private key algorithm, the name of the signing algorithm, and X.500 certiﬁcate subject information.

Type: CertiﬁcateAuthorityConﬁguration (p. 105) object Required: Yes

CertiﬁcateAuthorityType (p. 3)

The type of the certiﬁcate authority.

Type: String

Valid Values: ROOT | SUBORDINATE Required: Yes

IdempotencyToken (p. 3)

Custom string that can be used to distinguish between calls to the CreateCertificateAuthority action. Idempotency tokens for CreateCertificateAuthority time out after five minutes. Therefore, if you call CreateCertificateAuthority multiple times with the same idempotency token within five minutes, ACM Private CA recognizes that you are requesting only certificate authority and will issue only one. If you change the idempotency token for each call, PCA recognizes that you are requesting multiple certificate authorities.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 36.

Pattern: [\u0009\u000A\u000D\u0020-\u00FF]*

Required: No

KeyStorageSecurityStandard (p. 3)

Speciﬁes a cryptographic key management compliance standard used for handling CA keys.

Default: FIPS_140_2_LEVEL_3_OR_HIGHER

Note: FIPS_140_2_LEVEL_3_OR_HIGHER is not supported in Region ap-northeast-3. When creating a CA in the ap-northeast-3, you must provide FIPS_140_2_LEVEL_2_OR_HIGHER as the argument for KeyStorageSecurityStandard. Failure to do this results in an

InvalidArgsException with the message, "A certiﬁcate authority cannot be created in this region with the speciﬁed security standard."

Type: String

Valid Values: FIPS_140_2_LEVEL_2_OR_HIGHER | FIPS_140_2_LEVEL_3_OR_HIGHER Required: No

RevocationConﬁguration (p. 3)

Contains information to enable Online Certificate Status Protocol (OCSP) support, to enable a certificate revocation list (CRL), to enable both, or to enable neither. The default is for both certificate validation mechanisms to be disabled. For more information, see the OcspConfiguration and CrlConfiguration types.

Type: RevocationConﬁguration (p. 126) object Required: No

(13)

Response Syntax

Tags (p. 3)

Key-value pairs that will be attached to the new private CA. You can associate up to 50 tags with a private CA. For information using tags with IAM to manage permissions, see Controlling Access Using IAM Tags.

Type: Array of Tag (p. 127) objects

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Required: No

Response Syntax

{ "CertificateAuthorityArn": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

CertiﬁcateAuthorityArn (p. 6)

If successful, the Amazon Resource Name (ARN) of the certiﬁcate authority (CA). This is of the form:

arn:aws:acm-pca:region:account:certificate- authority/12345678-1234-1234-1234-123456789012 . Type: String

Pattern: arn:[\w+=/,.@-]+:[\w+=/,.@-]+:[\w+=/,.@-]*:[0-9]*:[\w+=,.@-]+(/[\w +=,.@-]+)*

Errors

For information about the errors that are common to all actions, see Common Errors (p. 132).

InvalidArgsException

One or more of the speciﬁed arguments was not valid.

HTTP Status Code: 400 InvalidPolicyException

The resource policy is invalid or is missing a required statement. For general information about IAM policy and statement structure, see Overview of JSON Policies.

HTTP Status Code: 400 InvalidTagException

The tag associated with the CA is not valid. The invalid argument is contained in the message ﬁeld.

(14)

Examples

HTTP Status Code: 400 LimitExceededException

An ACM Private CA quota has been exceeded. See the exception message returned to determine the quota that was exceeded.

HTTP Status Code: 400

Examples

Example

This example illustrates one usage of CreateCertiﬁcateAuthority.

Sample Request

POST / HTTP/1.1

Host: acm-pca.amazonaws.com Accept-Encoding: identity Content-Length: 512

X-Amz-Target: ACMPrivateCA.CreateCertificateAuthority X-Amz-Date: 20210310T165448Z

User-Agent: aws-cli/1.15.4 Python/2.7.9 Windows/8 botocore/1.10.4 Content-Type: application/x-amz-json-1.1

Authorization: AWS4-HMAC-SHA256 Credential=AWS_Access_Key_ID/20180515/AWS_Region/acm-pca/

aws4_request,

SignedHeaders=content-type;host;x-amz-date;x-amz-target,

Signature=6fc58aaf789659cb4e0dd0ba484a2562d982b6b8edd56ea0c5c94c2af9aeafbe {

"IdempotencyToken":"98256344",

"CertificateAuthorityConfiguration":{

"KeyAlgorithm":"RSA_2048",

"SigningAlgorithm":"SHA256WITHRSA", "Subject":{

"Locality":"Seattle", "Country":"US",

"CommonName":"www.example.com", "State":"WA",

"Organization":"Example Ltd.", "OrganizationalUnit":"Corporate"

} },

"CertificateAuthorityType":"SUBORDINATE", "RevocationConfiguration":{

"CrlConfiguration":{

"CustomCname":"CRL", "Enabled":true, "ExpirationInDays":7, "S3BucketName":"my-bucket"

},

"OcspConfiguration":{

"Enabled":false }

} }

Example

This example illustrates one usage of CreateCertiﬁcateAuthority.

(15)

See Also

Sample Response

HTTP/1.1 200 OK

Date: Tue, 10 March 2021 16:54:56 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 127

x-amzn-RequestId: eacb346a-d80b-4be6-a1b2-1732c3ae3c38 Connection: keep-alive

{

"CertificateAuthorityArn": "arn:aws:acm-pca:region:account:certificate- authority/12345678-1234-1234-1234-123456789012"

}

CreateCertiﬁcateAuthorityAuditReport

Creates an audit report that lists every time that your CA private key is used. The report is saved in the Amazon S3 bucket that you specify on input. The IssueCertiﬁcate and RevokeCertiﬁcate actions use the private key.

NoteBoth PCA and the IAM principal must have permission to write to the S3 bucket that you specify.

If the IAM principal making the call does not have permission to write to the bucket, then an exception is thrown. For more information, see Access policies for CRLs in Amazon S3.

ACM Private CA assets that are stored in Amazon S3 can be protected with encryption. For more information, see Encrypting Your Audit Reports.

Request Syntax

{ "AuditReportResponseFormat": "string", "CertificateAuthorityArn": "string", "S3BucketName": "string"

}

Request Parameters

AuditReportResponseFormat (p. 9)

The format in which to create the report. This can be either JSON or CSV.

Type: String

Valid Values: JSON | CSV Required: Yes

The Amazon Resource Name (ARN) of the CA to be audited. This is of the form:

Required: Yes S3BucketName (p. 9)

The name of the S3 bucket that will contain the audit report.

(17)

Response Syntax

Type: String

Required: Yes

Response Syntax

{

"AuditReportId": "string", "S3Key": "string"

}

Response Elements

AuditReportId (p. 10)

An alphanumeric string that contains a report identiﬁer.

Type: String

Length Constraints: Fixed length of 36.

Pattern: [a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}

S3Key (p. 10)

The key that uniquely identiﬁes the report ﬁle in your S3 bucket.

Type: String

Length Constraints: Maximum length of 1024.

Errors

HTTP Status Code: 400 InvalidArnException

The requested Amazon Resource Name (ARN) does not refer to an existing resource.

HTTP Status Code: 400 InvalidStateException

The state of the private CA does not allow this action to occur.

(18)

Examples

RequestFailedException

The request has failed for an unspeciﬁed reason.

HTTP Status Code: 400 RequestInProgressException

Your request is already in progress.

HTTP Status Code: 400 ResourceNotFoundException

A resource such as a private CA, S3 bucket, certiﬁcate, audit report, or policy cannot be found.

Examples

Example

This example illustrates one usage of CreateCertiﬁcateAuthorityAuditReport.

Sample Request

POST / HTTP/1.1

X-Amz-Target: ACMPrivateCA.CreateCertificateAuthorityAuditReport X-Amz-Date: 20180226T184819Z

aws4_request,

Signature=62380db816189148e510734f0ef2bfec08248fb3f447f64d740f31757e1beda0 {

"AuditReportResponseFormat": "JSON", "S3BucketName": "your-bucket-name",

}

Example

This example illustrates one usage of CreateCertiﬁcateAuthorityAuditReport.

Sample Response

HTTP/1.1 200 OK

Date: Tue, 15 May 2018 16:29:03 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 158

x-amzn-RequestId: e8516078-ff66-4e2a-bc38-eb1aaae2d886 Connection: keep-alive

{

(19)

See Also

"AuditReportId": "9654b603-d6a9-4c57-952a-ebcc95631fab",

"S3Key": "audit-reportPCA_ID/9654b603-d6a9-4c57-952a-ebcc95631fab.json"

}

CreatePermission

Grants one or more permissions on a private CA to the AWS Certiﬁcate Manager (ACM) service principal (acm.amazonaws.com). These permissions allow ACM to issue and renew ACM certiﬁcates that reside in the same AWS account as the CA.

You can list current permissions with the ListPermissions action and revoke them with the DeletePermission action.

About Permissions

• If the private CA and the certiﬁcates it issues reside in the same account, you can use

CreatePermission to grant permissions for ACM to carry out automatic certiﬁcate renewals.

• For automatic certiﬁcate renewal to succeed, the ACM service principal needs permissions to create, retrieve, and list certiﬁcates.

• If the private CA and the ACM certificates reside in different accounts, then permissions cannot be used to enable automatic renewals. Instead, the ACM certificate owner must set up a resource-based policy to enable cross-account issuance and renewals. For more information, see Using a Resource Based Policy with ACM Private CA.

Request Syntax

{ "Actions": [ "string" ],

"CertificateAuthorityArn": "string", "Principal": "string",

"SourceAccount": "string"

}

Request Parameters

Actions (p. 13)

The actions that the speciﬁed AWS service principal can use. These include IssueCertificate, GetCertificate, and ListPermissions.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 3 items.

Valid Values: IssueCertificate | GetCertificate | ListPermissions Required: Yes

The Amazon Resource Name (ARN) of the CA that grants the permissions. You can ﬁnd the ARN by calling the ListCertiﬁcateAuthorities action. This must have the following form:

arn:aws:acm-pca:region:account:certificate- authority/12345678-1234-1234-1234-123456789012 .

(21)

Response Elements

Type: String

Required: Yes Principal (p. 13)

The AWS service or identity that receives the permission. At this time, the only valid principal is acm.amazonaws.com.

Type: String

Pattern: ^[^*]+$

Required: Yes SourceAccount (p. 13)

The ID of the calling account.

Type: String

Pattern: [0-9]+

Required: No

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

InvalidArnException

HTTP Status Code: 400 LimitExceededException

An ACM Private CA quota has been exceeded. See the exception message returned to determine the quota that was exceeded.

(22)

Examples

PermissionAlreadyExistsException

The designated permission has already been given to the user.

HTTP Status Code: 400 RequestFailedException

Examples

Example

This example illustrates one usage of CreatePermission.

Sample Request

POST / HTTP/1.1

Host: acm.us-east-1.amazonaws.com

X-Amz-Target: CertificateManager.CreatePermission X-Amz-Date: 20190207T170903Z

User-Agent: aws-cli/1.10.20 Python/2.7.3 Linux/3.13.0-83-generic botocore/1.4.11 Content-Type: application/x-amz-json-1.1

Authorization: AUTHPARAMS,

SignedHeaders=content-type;host;user-agent;x-amz-date;x-amz-target, Signature=379429306c5e89b9b4be5b35e29c26cc1da38215d8055a5ed0bdda57bcc881cc {

"Actions": {

"IssueCertificate", "GetCertificate", "ListPermissions"

},

"CertificateArn":"arn:aws:acm:us-east-1:111122223333:certificate-authority/01234567-89ab- cdef-0123-0123456789ab",

"Principal":"acm.amazonaws.com", "SourceAccount":"012345678901"

}

Example

This example illustrates one usage of CreatePermission.

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 3c8d676d-025e-11e6-8823-93164b47113c Content-Type: application/x-amz-json-1.1

Content-Length: 0

Date: Thu, Feb 7 2019 17:09:05 GMT

(23)

See Also

DeleteCertiﬁcateAuthority

Deletes a private certificate authority (CA). You must provide the Amazon Resource Name (ARN) of the private CA that you want to delete. You can find the ARN by calling the ListCertificateAuthorities action.

NoteDeleting a CA will invalidate other CAs and certiﬁcates below it in your CA hierarchy.

Before you can delete a CA that you have created and activated, you must disable it. To do this, call the UpdateCertiﬁcateAuthority action and set the CertiﬁcateAuthorityStatus parameter to DISABLED.

Additionally, you can delete a CA if you are waiting for it to be created (that is, the status of the CA is CREATING). You can also delete it if the CA has been created but you haven't yet imported the signed certiﬁcate into ACM Private CA (that is, the status of the CA is PENDING_CERTIFICATE).

When you successfully call DeleteCertificateAuthority, the CA's status changes to DELETED. However, the CA won't be permanently deleted until the restoration period has passed. By default, if you do not set the PermanentDeletionTimeInDays parameter, the CA remains restorable for 30 days. You can set the parameter from 7 to 30 days. The DescribeCertificateAuthority action returns the time remaining in the restoration window of a private CA in the DELETED state. To restore an eligible CA, call the RestoreCertificateAuthority action.

Request Syntax

{

"CertificateAuthorityArn": "string", "PermanentDeletionTimeInDays": number }

Request Parameters

The Amazon Resource Name (ARN) that was returned when you called CreateCertiﬁcateAuthority.

This must have the following form:

Required: Yes

PermanentDeletionTimeInDays (p. 17)

The number of days to make a CA restorable after it has been deleted. This can be anywhere from 7 to 30 days, with 30 being the default.

(25)

Response Elements

Type: Integer

Valid Range: Minimum value of 7. Maximum value of 30.

Required: No

Response Elements

Errors

ConcurrentModiﬁcationException

A previous update to your private CA is still ongoing.

Examples

Example

This example illustrates one usage of DeleteCertiﬁcateAuthority.

Sample Request

POST / HTTP/1.1

X-Amz-Target: ACMPrivateCA.DeleteCertificateAuthority X-Amz-Date: 20180515T160248Z

aws4_request,

Signature=8f7e5b799989c607156141bc6856eb48acd45def7eecd2b2b7fbaa11f34d7bd1

(26)

See Also

{"PermanentDeletionTimeInDays": 17, "CertificateAuthorityArn": "arn:aws:acm-pca:us- west-2:493619779192:certificate-authority/4ce5e894-a076-4ed8-9d5c-42afbd4cbf88"}

Example

This example illustrates one usage of DeleteCertiﬁcateAuthority.

Sample Response

This function does not return a value.

DeletePermission

Revokes permissions on a private CA granted to the AWS Certiﬁcate Manager (ACM) service principal (acm.amazonaws.com).

These permissions allow ACM to issue and renew ACM certificates that reside in the same AWS account as the CA. If you revoke these permissions, ACM will no longer renew the affected certificates automatically.

Permissions can be granted with the CreatePermission action and listed with the ListPermissions action.

About Permissions

• If the private CA and the certiﬁcates it issues reside in the same account, you can use

CreatePermission to grant permissions for ACM to carry out automatic certiﬁcate renewals.

• For automatic certiﬁcate renewal to succeed, the ACM service principal needs permissions to create, retrieve, and list certiﬁcates.

• If the private CA and the ACM certificates reside in different accounts, then permissions cannot be used to enable automatic renewals. Instead, the ACM certificate owner must set up a resource-based policy to enable cross-account issuance and renewals. For more information, see Using a Resource Based Policy with ACM Private CA.

Request Syntax

{

"CertificateAuthorityArn": "string", "Principal": "string",

"SourceAccount": "string"

}

Request Parameters

The Amazon Resource Number (ARN) of the private CA that issued the permissions. You can ﬁnd the CA's ARN by calling the ListCertiﬁcateAuthorities action. This must have the following form:

Required: Yes Principal (p. 20)

The AWS service or identity that will have its CA permissions revoked. At this time, the only valid service principal is acm.amazonaws.com

(28)

Response Elements

Type: String

Pattern: ^[^*]+$

Required: Yes SourceAccount (p. 20)

The AWS account that calls this action.

Type: String

Pattern: [0-9]+

Required: No

Response Elements

Errors

DeletePolicy

Deletes the resource-based policy attached to a private CA. Deletion will remove any access that the policy has granted. If there is no policy attached to the private CA, this action will return successful.

If you delete a policy that was applied through AWS Resource Access Manager (RAM), the CA will be removed from all shares in which it was included.

The AWS Certiﬁcate Manager Service Linked Role that the policy supports is not aﬀected when you delete the policy.

The current policy can be shown with GetPolicy and updated with PutPolicy.

About Policies

• A policy grants access on a private CA to an AWS customer account, to AWS Organizations, or to an AWS Organizations unit. Policies are under the control of a CA administrator. For more information, see Using a Resource Based Policy with ACM Private CA.

• A policy permits a user of AWS Certiﬁcate Manager (ACM) to issue ACM certiﬁcates signed by a CA in another account.

• For ACM to manage automatic renewal of these certificates, the ACM user must configure a Service Linked Role (SLR). The SLR allows the ACM service to assume the identity of the user, subject to confirmation against the ACM Private CA policy. For more information, see Using a Service Linked Role with ACM.

• Updates made in AWS Resource Manager (RAM) are reﬂected in policies. For more information, see Attach a Policy for Cross-Account Access.

Request Syntax

{

"ResourceArn": "string"

}

Request Parameters

ResourceArn (p. 23)

The Amazon Resource Number (ARN) of the private CA that will have its policy deleted. You can ﬁnd the CA's ARN by calling the ListCertiﬁcateAuthorities action. The ARN value must have the form arn:aws:acm-pca:region:account:certificate-authority/01234567-89ab- cdef-0123-0123456789ab.

Type: String

Required: Yes

(31)

Response Elements

Errors

ConcurrentModiﬁcationException

A previous update to your private CA is still ongoing.

HTTP Status Code: 400 LockoutPreventedException

The current action was prevented because it would lock the caller out from performing subsequent actions. Verify that the speciﬁed parameters would not result in the caller being denied access to the resource.

DescribeCertiﬁcateAuthority

Lists information about your private certiﬁcate authority (CA) or one that has been shared with you. You specify the private CA on input by its ARN (Amazon Resource Name). The output contains the status of your CA. This can be any of the following:

• CREATING - ACM Private CA is creating your private certiﬁcate authority.

• PENDING_CERTIFICATE - The certiﬁcate is pending. You must use your ACM Private CA-hosted or on- premises root or subordinate CA to sign your private CA CSR and then import it into PCA.

• ACTIVE - Your private CA is active.

• DISABLED - Your private CA has been disabled.

• EXPIRED - Your private CA certiﬁcate has expired.

• FAILED - Your private CA has failed. Your CA can fail because of problems such a network outage or back-end AWS failure or other errors. A failed CA can never return to the pending state. You must create a new CA.

• DELETED - Your private CA is within the restoration period, after which it is permanently deleted. The length of time remaining in the CA's restoration period is also included in this action's output.

Request Syntax

{ "CertificateAuthorityArn": "string"

}

Request Parameters

This must be of the form:

Required: Yes

Response Syntax

{ "CertificateAuthority": {

(34)

Response Syntax

"Arn": "string",

"CertificateAuthorityConfiguration": { "CsrExtensions": {

"KeyUsage": {

"CRLSign": boolean,

"DataEncipherment": boolean, "DecipherOnly": boolean, "DigitalSignature": boolean, "EncipherOnly": boolean, "KeyAgreement": boolean, "KeyCertSign": boolean, "KeyEncipherment": boolean, "NonRepudiation": boolean },

"SubjectInformationAccess": [ {

"AccessLocation": { "DirectoryName": { "CommonName": "string", "Country": "string",

"DistinguishedNameQualifier": "string", "GenerationQualifier": "string",

"GivenName": "string", "Initials": "string", "Locality": "string", "Organization": "string", "OrganizationalUnit": "string", "Pseudonym": "string",

},

"DnsName": "string", "EdiPartyName": {

"NameAssigner": "string", "PartyName": "string"

},

"IpAddress": "string", "OtherName": { "TypeId": "string", "Value": "string"

},

"RegisteredId": "string", "Rfc822Name": "string",

"UniformResourceIdentifier": "string"

},

"AccessMethod": {

"AccessMethodType": "string", "CustomObjectIdentifier": "string"

} } ] },

"KeyAlgorithm": "string", "SigningAlgorithm": "string", "Subject": {

"CommonName": "string", "Country": "string",

"DistinguishedNameQualifier": "string", "GenerationQualifier": "string", "GivenName": "string",

"Initials": "string", "Locality": "string", "Organization": "string", "OrganizationalUnit": "string",

(35)

Response Elements

"Pseudonym": "string", "SerialNumber": "string", "State": "string",

"Surname": "string", "Title": "string"

} },

"CreatedAt": number, "FailureReason": "string",

"KeyStorageSecurityStandard": "string", "LastStateChangeAt": number,

"NotAfter": number, "NotBefore": number, "OwnerAccount": "string", "RestorableUntil": number, "RevocationConfiguration": { "CrlConfiguration": { "CustomCname": "string", "Enabled": boolean,

"ExpirationInDays": number, "S3BucketName": "string", "S3ObjectAcl": "string"

},

"OcspConfiguration": { "Enabled": boolean,

"OcspCustomCname": "string"

} },

"Serial": "string", "Status": "string", "Type": "string"

}}

Response Elements

CertiﬁcateAuthority (p. 26)

A CertiﬁcateAuthority structure that contains information about your private CA.

Type: CertiﬁcateAuthority (p. 102) object

Errors

(36)

Examples

Example

This example illustrates one usage of DescribeCertiﬁcateAuthority.

Sample Request

POST / HTTP/1.1

X-Amz-Target: ACMPrivateCA.DescribeCertificateAuthority X-Amz-Date: 20180226T175919Z

Authorization: AWS4-HMAC-SHA256 Credential=Access_Key_ID/20180226/AWS_Region/acm-pca/

aws4_request,

Signature=953a014106627a76d91f55fd86bb1149bf65d578886bf2371aa4c73c56e16a1d {"CertificateAuthorityArn": "arn:aws:acm-pca:region:account:certificate- authority/12345678-1234-1234-1234-123456789012"}

Example

This example illustrates one usage of DescribeCertiﬁcateAuthority.

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 8d51e9ff-8ae9-4ccf-816a-8e7d9c3dc1af Connection: keep-alive

{

"CertificateAuthority": {

"Arn": "arn:aws:acm-pca:gh:account:certificate- authority/12345678-1234-1234-1234-123456789012", "CertificateAuthorityConfiguration": { "KeyAlgorithm": "RSA_2048",

"SigningAlgorithm": "SHA256WITHRSA", "Subject": {

"CommonName": "www.example.com", "Country": "US",

"Locality": "Seattle",

"Organization": "Example Company", "OrganizationalUnit": "Corporate", "State": "WA"

} },

"CreatedAt": 1.516130652887E9,

"LastStateChangeAt": 1.516130652887E9, "NotAfter": 1.831494803E9,

"NotBefore": 1.516134803E9, "RevocationConfiguration": { "CrlConfiguration": {

"CustomCname": "http://somename.crl",

(37)

See Also

"Enabled": true,

"ExpirationInDays": 3650,

"S3BucketName": "your-bucket-name"

} },

"Serial": "4118", "Status": "ACTIVE", "Type": "SUBORDINATE"

} }

DescribeCertiﬁcateAuthorityAuditReport

Lists information about a speciﬁc audit report created by calling the

CreateCertificateAuthorityAuditReport action. Audit information is created every time the certificate authority (CA) private key is used. The private key is used when you call the IssueCertificate action or the RevokeCertificate action.

Request Syntax

{

"AuditReportId": "string",

"CertificateAuthorityArn": "string"

}

Request Parameters

AuditReportId (p. 31)

The report ID returned by calling the CreateCertiﬁcateAuthorityAuditReport action.

Type: String

Pattern: [a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}

Required: Yes

The Amazon Resource Name (ARN) of the private CA. This must be of the form:

Required: Yes

Response Syntax

{ "AuditReportStatus": "string", "CreatedAt": number,

"S3BucketName": "string",

(39)

Response Elements

"S3Key": "string"

}

Response Elements

AuditReportStatus (p. 31)

Speciﬁes whether report creation is in progress, has succeeded, or has failed.

Type: String

Valid Values: CREATING | SUCCESS | FAILED CreatedAt (p. 31)

The date and time at which the report was created.

Type: Timestamp S3BucketName (p. 31)

Name of the S3 bucket that contains the report.

Type: String

S3Key (p. 31)

S3 key that uniquely identiﬁes the report ﬁle in your S3 bucket.

Type: String

Length Constraints: Maximum length of 1024.

Errors

(40)

Examples

Example

This example illustrates one usage of DescribeCertiﬁcateAuthorityAuditReport.

Sample Request

POST / HTTP/1.1

X-Amz-Target: ACMPrivateCA.DescribeCertificateAuthorityAuditReport X-Amz-Date: 20180226T185916Z

aws4_request,

Signature=96531073ea22cc7057267543f332911b97a5db830dca85a74a7324c9737cee7a { "AuditReportId": "11111111-2222-3333-4444-555555555555",

}

Example

This example illustrates one usage of DescribeCertiﬁcateAuthorityAuditReport.

Sample Response

HTTP/1.1 200 OK

Date: Tue, 15 May 2018 16:33:26 GMT

Content-Type: application/xget-amz-json-1.1 Content-Length: 211

x-amzn-RequestId: 3af6a588-856c-48eb-81ab-f2f08fbc618c Connection: keep-alive

{

"AuditReportStatus": "SUCCESS", "CreatedAt": 1.526401743081E9, "S3BucketName": "your-bucket-name",

"S3Key": "audit-report/PCA_ID/Audit_Report_ID.json"

}

GetCertiﬁcate

Retrieves a certificate from your private CA or one that has been shared with you. The ARN of the certificate is returned when you call the IssueCertificate action. You must specify both the ARN of your private CA and the ARN of the issued certificate when calling the GetCertificate action. You can retrieve the certificate if it is in the ISSUED state. You can call the CreateCertificateAuthorityAuditReport action to create a report that contains information about all of the certificates issued and revoked by your private CA.

Request Syntax

{ "CertificateArn": "string",

}

Request Parameters

CertiﬁcateArn (p. 35)

The ARN of the issued certiﬁcate. The ARN contains the certiﬁcate serial number and must be in the following form:

arn:aws:acm-pca:region:account:certificate- authority/12345678-1234-1234-1234-123456789012/

certificate/286535153982981100925020015808220737245 Type: String

Required: Yes

This must be of the form:

Required: Yes

(43)

Response Syntax

{

"Certificate": "string", "CertificateChain": "string"

}

Response Elements

Certiﬁcate (p. 36)

The base64 PEM-encoded certiﬁcate speciﬁed by the CertificateArn parameter.

Type: String CertiﬁcateChain (p. 36)

The base64 PEM-encoded certificate chain that chains up to the root CA certificate that you used to sign your private CA certificate.

Type: String

Errors

HTTP Status Code: 400 RequestInProgressException

Your request is already in progress.

(44)

Examples

Example

This example illustrates one usage of GetCertiﬁcate.

Sample Request

POST / HTTP/1.1

X-Amz-Target: ACMPrivateCA.GetCertificate X-Amz-Date: 20180226T194913Z

Authorization: AWS4-HMAC-SHA256 Credential=AWS_Access_Key_ID/20180226/AWS_Region/

acm-pca/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=4fe34fdad8c09d5b608be6f5d4f4939444dd7cdd542ec09b1002182e4ef9fcee {

"CertificateArn": "arn:aws:acm-pca:region:account:certificate- authority/12345678-1234-1234-1234-123456789012/certificate/

e8cbd2bedb122329f97706bcfec990f8",

}

Example

This example illustrates one usage of GetCertiﬁcate.

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 9f537e0a-993c-4a03-8aec-0fc52c772b84 Connection: keep-alive

{

"Certificate": "---BEGIN CERTIFICATE--- base64-encoded certificate ---END CERTIFICATE---",

"CertificateChain": "---BEGIN CERTIFICATE--- base64-encoded certificate ---END CERTIFICATE---"

}

GetCertiﬁcateAuthorityCertiﬁcate

Retrieves the certificate and certificate chain for your private certificate authority (CA) or one that has been shared with you. Both the certificate and the chain are base64 PEM-encoded. The chain does not include the CA certificate. Each certificate in the chain signs the one before it.

Request Syntax

{

}

Request Parameters

The Amazon Resource Name (ARN) of your private CA. This is of the form:

Required: Yes

Response Syntax

{ "Certificate": "string", "CertificateChain": "string"

}

Response Elements

Certiﬁcate (p. 39)

Base64-encoded certiﬁcate authority (CA) certiﬁcate.

Type: String

(47)

Errors

CertiﬁcateChain (p. 39)

Base64-encoded certificate chain that includes any intermediate certificates and chains up to root certificate that you used to sign your private CA certificate. The chain does not include your private CA certificate. If this is a root CA, the value will be null.

Type: String

Errors

Examples

Example

This example illustrates one usage of GetCertiﬁcateAuthorityCertiﬁcate.

Sample Request

POST / HTTP/1.1

X-Amz-Target: ACMPrivateCA.GetCertificateAuthorityCertificate X-Amz-Date: 20180226T174831Z

Authorization: AWS4-HMAC-SHA256 Credential=Access_Key_ID/20180226/AWS_Region/acm-pca/

aws4_request,

Signature=2675f0e4055c234f5b6e155bd3245ca327382d47a16e0c20f2abc802e1f0eab6 {"CertificateAuthorityArn": "arn:aws:acm-pca:AWS_Region:AWS_Account:certificate- authority/12345678-1234-1234-1234-123456789012"}

Example

This example illustrates one usage of GetCertiﬁcateAuthorityCertiﬁcate.

(48)

See Also

Sample Response

HTTP/1.1 200 OK

x-amzn-RequestId: 8c607f26-6d9e-4972-a529-02cc5608c81a Connection: keep-alive

{

"Certificate": "---BEGIN CERTIFICATE--- base64-encoded certificate ---END CERTIFICATE---",

"CertificateChain": "---BEGIN CERTIFICATE--- base64-encoded certificate chain --- END CERTIFICATE---"

}

AWS Private CA

AWS Private CA

API Reference

API Version 2017-08-22

AWS Private CA: API Reference

Table of Contents

Welcome

Actions

CreateCertiﬁcateAuthority

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Example

Sample Response

See Also

CreateCertiﬁcateAuthorityAuditReport

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Example

Sample Response

See Also

CreatePermission

Request Syntax

Request Parameters

Response Elements

Errors

Examples

Example

Sample Request

Example

Sample Response

See Also

DeleteCertiﬁcateAuthority

Request Syntax

Request Parameters

Response Elements

Errors

Examples

Example

Sample Request

Example

Sample Response

See Also

DeletePermission

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DeletePolicy

Request Syntax

Request Parameters

Response Elements

Errors

See Also

DescribeCertiﬁcateAuthority

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Example

Sample Response

See Also

DescribeCertiﬁcateAuthorityAuditReport

Request Syntax