Polish edits, check links

crandmck · crandmck · commit 11073b8d4627 · 2025-04-04T10:20:45.000-07:00
diff --git a/docs/signing/get-cert.md b/docs/signing/get-cert.md
@@ -11,9 +11,7 @@ To sign manifest claims, you must have an X.509 v3 security certificate and key
 
 ## Certificate authorities (CAs)
 
-To create or modify Content Credentials, you must purchase a signing certificate from a certificate authority (CA). 
-
-There are many CAs that issue certificates. Some popular ones include:
+You must purchase a signing certificate from a certificate authority (CA).  There are many CAs that issue certificates. Some popular ones include:
 
 - GlobalSign: [S/MIME email signing](https://shop.globalsign.com/en/secure-email), [document signing](https://shop.globalsign.com/en/document-signing)
 - IdenTrust: [S/MIME email signing](https://www.identrust.com/digital-certificates/secure-email-smime), [document signing](https://www.identrust.com/digital-certificates/document-signing)
@@ -49,7 +47,7 @@ You sign the CSR with your private key; this proves to the CA that you have cont
 
 ## Certificate requirements
 
-A signing certificate and key (credentials) must conform to the requirements in the [C2PA specification Trust Model section](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_trust_model). The certificate must:
+A signing certificate and key (credentials) must conform to the requirements in the [C2PA specification X.509 Certificates section](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#x509_certificates); specifically, it must:
 
 - Follow the public key infrastructure (PKI) X.509 V3 specification.
 - Have the Key Usage (KU) extension, which must be marked as critical. 
@@ -70,6 +68,8 @@ If you want the C2PA [Verify tool](https://verify.contentauthenticity.org/) to d
 
 The following table describes the signature algorithms and types that the CAI SDK supports. You must supply credentials (certificates and keys) that correspond to the signing algorithm (`signatureAlgorithm`). Signing/validation will fail if the the supplied credentials don't support the signature type.
 
+This table is provided for convenience, and is based on information in the [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#x509_certificates). The specification is authoritative; refer to it for more details.  The C2PA specification also covers two other certificates for timestamp responses and OCSP certificate revocation, which are not covered here.
+
 | Certificate `signatureAlgorithm` | Description  | Recommended signature type | RFC Reference |
 | -------------------------------- | ------------ | -------------------------- | ------------- |
 | `ecdsa-with-SHA256`                                       | ECDSA with SHA-256                                            | ES256<sup>\*</sup>         | [RFC 5758 section 3.2](https://www.rfc-editor.org/rfc/rfc5758.html#section-3.2)       |
@@ -85,8 +85,6 @@ The following table describes the signature algorithms and types that the CAI SD
 
 <sup>*</sup> ES256, ES384, and ES512 signatures must be in IEEE P1363 format.
 
----
 
-The information in this table is based on the [C2PA specification Trust Model section](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_trust_model). The C2PA specification also covers two other certificates for timestamp responses and OCSP certificate revocation, which are not covered here.
 
 
diff --git a/docs/signing/index.md b/docs/signing/index.md
@@ -9,9 +9,9 @@ Be sure to read [Getting started](getting-started.mdx#signing-and-certificates)
 
 As you're developing an application that uses the CAI SDK, there are three ways to sign manifest claims, depending on where you are in your development process:
 1. **Initial prototyping and development**: Use the test certificates and keys included with the SDK libraries to sign claims.  These certs and keys are provided for convenience, but aren't valid for actual signing.  For more information, see [Using test certificates](test-certs.md).
-1. **Local/internal testing**: Once your code is working with the test certs and keys:
-  - [Purchase your own certificate](get-cert.md) from a certificate authority (CA). 
-  - Then your application can [use the certificate and key *locally*](local-signing.md) (directly from the file system) to sign manifest claims; however, this is NOT safe in production. 
+1. **Local/internal testing**: Once your code is working with the test certs and keys, you can move on to:
+    - [Purchase your own certificate](get-cert.md) from a certificate authority (CA). 
+    - Change your application to [use the certificate and key *locally*](local-signing.md) (directly from the file system) to sign manifest claims; however, this is NOT safe in production. 
 1. **Production testing/deployment**: To secure your private key for use in a publicly-accessible production application, store it in a hardware security module (HSM) or key management service (KMS) where your application can access it securely . 
 
 :::note
diff --git a/docs/signing/local-signing.md b/docs/signing/local-signing.md
@@ -13,9 +13,7 @@ Trust lists connect the end-entity certificate that signed a manifest back to th
 
 The simplest way to add a C2PA manifest to an asset file and sign it is by using C2PA Tool (`c2patool`). You can run C2PA Tool manually from the command line (for example, during development) and more generally from any executable program that can call out to the shell, such as a Node.js application as shown in the [c2patool Node.js service example](../c2pa-node-example).
 
-Similarly, using the Rust SDK, you can [add a manifest to an asset file](https://docs.rs/c2pa/latest/c2pa/#example-adding-a-manifest-to-a-file), referencing the certificate and private key file. For a simple example of creating and signing a manifest from a C program, see the [c2c2pa repository](https://github.com/contentauth/c2c2pa).
-
-The prerelease libraries for [Node.js](../c2pa-node), [Python](../c2pa-python), and [C++/C](../c2pa-c) can also add and sign a manifest.
+Similarly, using the Rust SDK, you can [add a manifest to an asset file](https://docs.rs/c2pa/latest/c2pa/#example-adding-a-manifest-to-a-file), referencing the certificate and private key file. The prerelease libraries for [Node.js](../c2pa-node), [Python](../c2pa-python), and [C++/C](../c2pa-c) can also add and sign a manifest.
 
 :::warning Warning
 Accessing a private key and certificate directly from the file system is fine during development, but doing so in production is not secure. Instead use a Key Management Service (KMS) or a hardware security module (HSM) to access the certificate and key; For more information, see [Using a certificate in production](prod-cert.mdx). 
diff --git a/docs/signing/prod-cert.mdx b/docs/signing/prod-cert.mdx
@@ -22,7 +22,7 @@ Some useful references for handling keys and certificates include:
 
 ## Pre-production steps
 
-Because using a KMS can be complex, you may want to start by using a local "mock" service such as LocalStack (for Amazon KMS). Doing this enables you to test your code before you set up a production KMS.
+Because using a KMS can be complex, you may want to start by using a local "mock" service (such as LocalStack for Amazon KMS) as illustrated in the [c2pa-python-example](c2pa-python-example/readme.md#using-localstack). Doing this enables you to test your code before you set up a production KMS.
 
 You can also create a self-signed certificate for development purposes. The resulting manifests signed with this certificate won't be trusted, but you can use it to run the application to see how it works before purchasing a real certificate from a CA.
 
diff --git a/docs/signing/test-certs.md b/docs/signing/test-certs.md
@@ -3,17 +3,18 @@ id: test-certs
 title: Using test certificates
 ---
 
-For development and testing, C2PA Tool, the Rust library, and the CAI prerelease libraries include one or more [test certificates](signing-certs.md#test-certificates) and private keys for use during development. While these test certificates and keys are useful during development and testing, for production deployment you must use your own private key and certificate.
-
-The [Rust library `sdk/tests/fixtures/certs/` folder](https://github.com/contentauth/c2pa-rs/tree/main/sdk/tests/fixtures/certs) contains certificates and signing keys for many of the supported signature types [described below](prod-cert.mdx#signature-types).
-
-The CAI prerelease libraries also provide a subset of test certificates in each repository's `tests/fixtures` folder. The Node.js library even provides a [`CreateTestSigner()`](https://github.com/contentauth/c2pa-node/blob/main/docs/README.md#createtestsigner) convenience function to create a local signer instance using the test certificate.
-
 The CAI SDK does not allow you to use a self-signed certificate to sign a manifest.
 
+For initial development and testing, the SDK provides example *test certificates* and private keys:
+- The [Rust library `sdk/tests/fixtures/certs/` folder](https://github.com/contentauth/c2pa-rs/tree/main/sdk/tests/fixtures/certs) contains certificates and signing keys for many of the supported [signature types](get-cert.md#signature-types).
+- The prerelease libraries (Node.js, Python, and C++) provide a subset of test certificates in each repository's `tests/fixtures` folder. The Node.js library even provides a [`CreateTestSigner()`](https://github.com/contentauth/c2pa-node/blob/main/docs/README.md#createtestsigner) convenience function to create a local signer instance using the test certificate.
+
 :::warning Warning
-The test certificates are for use during development and testing only.  Do not use them in production!
+While these test credentials are useful during development, you must [get your own certificate](get-cert.md) and use your own private key for production deployment.  
 :::
 
-Although not recommended due to complexity and difficulty, you can create your own certificates for development and testing. Follow the requirements in the C2PA Technical Specification [Credential Types](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_credential_types) and [Digital Signatures](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_digital_signatures) sections.
+Although not recommended due to complexity and difficulty, you can create your own certificates for development and testing. Follow the requirements in the C2PA Technical Specification [X.509 Certificates](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#x509_certificates) and [Digital Signatures](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_digital_signatures) sections.
+
+For manifest claims signed with one of the test certificates, the C2PA Verify tool will display the message "The Content Credential issuer couldn't be recognized."  See [Using the Verify tool](../verify.mdx#signing-information) for more information.
+
 
diff --git a/docs/verify.mdx b/docs/verify.mdx
@@ -166,9 +166,9 @@ For example, suppose you downloaded a file from Adobe Stock and renamed it `my_s
  }
 ```
 
-**Signing information**
+#### Signing information
 
-If the Content Credential was signed by a certificate that is NOT on the [known certificate list](verify-known-cert-list), such as the CAI test certificate in the SDK, then Verify displays "Unrecognized" at the top of this section with this notice:
+If the Content Credential was signed by a certificate that is NOT on the [known certificate list](verify-known-cert-list), such as one of the SDK's [test certificates](signing/test-certs.md), then Verify displays "Unrecognized" at the top of this section with this notice:
 
 import verify_unknown_source from '../static/img/verify-cc-unknown-source.png';
 
@@ -177,7 +177,11 @@ import verify_unknown_source from '../static/img/verify-cc-unknown-source.png';
   style={{ width: '283px', display: 'block', margin: '10px auto' }}
 />
 
-However, if the Content Credential was signed by a certificate on the [known certificate list](verify-known-cert-list), then this section displays the name of the issuer of the claim signature from the `signature_info.issuer` property in the active manifest, as shown in the example snippet below. It shows the organization name only if the signing certificate includes the "O" or [Organization Name attribute](https://www.alvestrand.no/objectid/2.5.4.10.html) (OID value 2.5.4.10) in the certificate's distinguished name information.
+However, if the Content Credential was signed by a certificate on the [known certificate list](verify-known-cert-list), then this section displays the name of the issuer of the claim signature from the `signature_info.issuer` property in the active manifest, as shown in the example snippet below.
+
+:::note
+This section shows the organization name only if the signing certificate includes the "O" or [Organization Name attribute](https://www.alvestrand.no/objectid/2.5.4.10.html) (OID value 2.5.4.10) in the certificate's distinguished name information.
+:::
 
 For signers on the known certificate list, this section also displays the time of the claim signature from the `signature_info.time` property in the active manifest, as shown in the example snippet below. The date is converted from UTC to the local time zone.
 
