AWS Certificate Manager Private Certificate Authority Update: Private Certificate Authority (PCA) documentation updates

Author: AWS

.changes/next-release/feature-AWSCertificateManagerPrivateCertificateAuthority-1784599.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS Certificate Manager Private Certificate Authority",
+    "contributor": "",
+    "description": "Private Certificate Authority (PCA) documentation updates"
+}

services/acmpca/src/main/resources/codegen-resources/service-2.json

@@ -890,11 +890,11 @@
         },
         "CrlType":{
           "shape":"CrlType",
-          "documentation":"<p>Choose whether to use a partitioned or complete CRL. Your choice determines the maximum number of certificates that the certificate authority can issue and revoke, as described in the <a href=\"https://docs.aws.amazon.com/general/latest/gr/pca.html#limits_pca-connector-ad\">Amazon Web Services Private CA quotas</a>.</p> <ul> <li> <p> <code>PARTITIONED</code> - The default setting. Partitioned CRLs are an especially good option for devices that have limited processing power or storage capacity, such as certain IoT devices. Compared to complete CRLs, partitioned CRLs dramatically increase the number of certificates your private CA can issue. Each certificate that Amazon Web Services Private CA issues is bound to a specific CRL partition through the CRL distribution point (CDP) defined in <a href=\"https://datatracker.ietf.org/doc/html/rfc5280\">RFC 5280</a>.</p> <important> <p>To make sure that your client fetches the CRL from a valid endpoint, we recommend that you programmatically validate that the CRL's issuing distribution point (IDP) URI matches the certificate's CDP URI. Amazon Web Services Private CA marks the IDP extension as critical, which your client must be able to process.</p> </important> </li> <li> <p> <code>COMPLETE</code> - Amazon Web Services Private CA maintains a single CRL file for all unexpired certificates issued by a CA that have been revoked for any reason.</p> </li> </ul>"
+          "documentation":"<p>Specifies whether to create a complete or partitioned CRL. This setting determines the maximum number of certificates that the certificate authority can issue and revoke. For more information, see <a href=\"privateca/latest/userguide/pca.html#limits_pca\">Amazon Web Services Private CA quotas</a>.</p> <ul> <li> <p> <code>COMPLETE</code> - The default setting. Amazon Web Services Private CA maintains a single CRL file for all unexpired certificates issued by a CA that have been revoked for any reason. Each certificate that Amazon Web Services Private CA issues is bound to a specific CRL through its CRL distribution point (CDP) extension, defined in <a href=\"https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.9\"> RFC 5280</a>.</p> </li> <li> <p> <code>PARTITIONED</code> - Compared to complete CRLs, partitioned CRLs dramatically increase the number of certificates your private CA can issue. </p> <important> <p> When using partitioned CRLs, you must validate that the CRL's associated issuing distribution point (IDP) URI matches the certificate's CDP URI to ensure the right CRL has been fetched. Amazon Web Services Private CA marks the IDP extension as critical, which your client must be able to process. </p> </important> </li> </ul>"
         },
         "CustomPath":{
           "shape":"CrlPathString",
-          "documentation":"<p>Designates a custom file path in S3 for CRL(s). For example, <code>http://&lt;CustomName&gt;/&lt;CustomPath&gt;/&lt;CrlPartition_GUID&gt;.crl</code>. You can change the custom path up to five times.</p>"
+          "documentation":"<p>Designates a custom file path in S3 for CRL(s). For example, <code>http://&lt;CustomName&gt;/ &lt;CustomPath&gt;/&lt;CrlPartition_GUID&gt;.crl</code>. </p>"
         }
       },
       "documentation":"<p>Contains configuration information for a certificate revocation list (CRL). Your private certificate authority (CA) creates base CRLs. Delta CRLs are not supported. You can enable CRLs for your new or an existing private CA by setting the <b>Enabled</b> parameter to <code>true</code>. Your private CA writes CRLs to an S3 bucket that you specify in the <b>S3BucketName</b> parameter. You can hide the name of your bucket by specifying a value for the <b>CustomCname</b> parameter. Your private CA by default copies the CNAME or the S3 bucket name to the <b>CRL Distribution Points</b> extension of each certificate it issues. If you want to configure this default behavior to be something different, you can set the <b>CrlDistributionPointExtensionConfiguration</b> parameter. Your S3 bucket policy must give write permission to Amazon Web Services Private CA. </p> <p>Amazon Web Services Private CA assets that are stored in Amazon S3 can be protected with encryption. For more information, see <a href=\"https://docs.aws.amazon.com/privateca/latest/userguide/crl-planning.html#crl-encryption\">Encrypting Your CRLs</a>.</p> <p>Your private CA uses the value in the <b>ExpirationInDays</b> parameter to calculate the <b>nextUpdate</b> field in the CRL. The CRL is refreshed prior to a certificate's expiration date or when a certificate is revoked. When a certificate is revoked, it appears in the CRL until the certificate expires, and then in one additional CRL after expiration, and it always appears in the audit report.</p> <p>A CRL is typically updated approximately 30 minutes after a certificate is revoked. If for any reason a CRL update fails, Amazon Web Services Private CA makes further attempts every 15 minutes.</p> <p>CRLs contain the following fields:</p> <ul> <li> <p> <b>Version</b>: The current version number defined in RFC 5280 is V2. The integer value is 0x1. </p> </li> <li> <p> <b>Signature Algorithm</b>: The name of the algorithm used to sign the CRL.</p> </li> <li> <p> <b>Issuer</b>: The X.500 distinguished name of your private CA that issued the CRL.</p> </li> <li> <p> <b>Last Update</b>: The issue date and time of this CRL.</p> </li> <li> <p> <b>Next Update</b>: The day and time by which the next CRL will be issued.</p> </li> <li> <p> <b>Revoked Certificates</b>: List of revoked certificates. Each list item contains the following information.</p> <ul> <li> <p> <b>Serial Number</b>: The serial number, in hexadecimal format, of the revoked certificate.</p> </li> <li> <p> <b>Revocation Date</b>: Date and time the certificate was revoked.</p> </li> <li> <p> <b>CRL Entry Extensions</b>: Optional extensions for the CRL entry.</p> <ul> <li> <p> <b>X509v3 CRL Reason Code</b>: Reason the certificate was revoked.</p> </li> </ul> </li> </ul> </li> <li> <p> <b>CRL Extensions</b>: Optional extensions for the CRL.</p> <ul> <li> <p> <b>X509v3 Authority Key Identifier</b>: Identifies the public key associated with the private key used to sign the certificate.</p> </li> <li> <p> <b>X509v3 CRL Number:</b>: Decimal sequence number for the CRL.</p> </li> </ul> </li> <li> <p> <b>Signature Algorithm</b>: Algorithm used by your private CA to sign the CRL.</p> </li> <li> <p> <b>Signature Value</b>: Signature computed over the CRL.</p> </li> </ul> <p>Certificate revocation lists created by Amazon Web Services Private CA are DER-encoded. You can use the following OpenSSL command to list a CRL.</p> <p> <code>openssl crl -inform DER -text -in <i>crl_path</i> -noout</code> </p> <p>For more information, see <a href=\"https://docs.aws.amazon.com/privateca/latest/userguide/crl-planning.html\">Planning a certificate revocation list (CRL)</a> in the <i>Amazon Web Services Private Certificate Authority User Guide</i> </p>"