From 8b512beb56553c9ff9537e8ae896fc0c7da18fa6 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 21 Apr 2025 13:25:12 -0700 Subject: [PATCH] clean up edits to signing info --- docs/signing/get-cert.md | 34 +++++++++++++++++++--------------- docs/signing/index.md | 7 ++++--- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/signing/get-cert.md b/docs/signing/get-cert.md index 54e928a..9322ccf 100644 --- a/docs/signing/get-cert.md +++ b/docs/signing/get-cert.md @@ -7,31 +7,35 @@ title: Getting a signing certificate Best practices for handling keys and certificates are beyond the scope of this documentation. Always protect your private keys with the highest level of security; for example, never share them through insecure channels such as email. ::: -To sign manifest claims, you must have an X.509 v3 security certificate and key that conform to the requirements laid out in the [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#x509_certificates). +To sign manifest claims, you must have an X.509 v3 security certificate and key that conform to the requirements laid out in the [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#x509_certificates). -## Certificate authorities (CAs) +## Purchasing a certificate -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) -- Comodo Cybersecurity: [S/MIME email signing cert](https://ssl.comodoca.com/s-mime), [document signing cert](https://ssl.comodoca.com/document-signing-certificates) -- Digicert: [S/MIME email signing cert](https://www.digicert.com/tls-ssl/secure-email-smime-certificates), [document signing cert](https://www.digicert.com/signing/document-signing-certificates) +The process to purchase a certificate and key is different for each CA: You might be able to simply click a "Buy" button on the CA's website. Or your can make your own key and use it to create a certificate signing request (CSR) that you send to the CA. Regardless of the process, what you get back is a signed certificate that you use to create a certificate chain. -The above list is for reference only; inclusion does not imply endorsement by CAI or Adobe, Inc. +The certificate chain starts with the certificate from the last tool that signed the manifest (known as the "end-entity") followed by the certificate that signed it, and so on, back to the original CA issuer. This enables a validating application to determine that the manifest is valid because the certificate chain goes back to a trusted root certificate authority. ### Types of certificates -CAs offer a variety of different types of certificates (links below are to [Digicert](https://www.digicert.com), but most CAs offer these types of certificates): +The C2PA specification requires that an "end entity" signing certificate must be either: -- The simplest and least expensive option is an [S/MIME email certificate](https://www.digicert.com/tls-ssl/compare-secure-email-smime-certificates). -- Other options, such as [document signing certificate](https://www.digicert.com/signing/compare-document-signing-certificates) require more rigor (like proving your identity) and cost more. +- An S/MIME email certificate (`id-kp-emailProtection` EKU). This is usually the simplest and least expensive option. +- A document signing certificate (`id-kp-documentSigning` EKU). Obtaining these kinds of certificates typically have more stringent requirements (like proving your identity) and costs more. -### Purchasing a certificate +:::note +For more details, see [Certificate requirements](#certificate-requirements) below. +::: -The process to purchase a certificate and key is different for each CA: You might be able to simply click a "Buy" button on the CA's website. Or your can make your own key and use it to create a certificate signing request (CSR) that you send to the CA. Regardless of the process, what you get back is a signed certificate that you use to create a certificate chain. +### Certificate authorities (CAs) -The certificate chain starts with the certificate from the last tool that signed the manifest (known as the "end-entity") followed by the certificate that signed it, and so on, back to the original CA issuer. This enables a validating application to determine that the manifest is valid because the certificate chain goes back to a trusted root certificate authority. +You must purchase a signing certificate from a certificate authority (CA). The following table provides some links to popular CAs for convenience. This information is for reference only; inclusion does not imply endorsement by CAI or Adobe, Inc. + +| CA | S/MIME email signing | Document signing | +|----|----------------------|------------------| +| 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) | +| Comodo Cybersecurity | [S/MIME email signing](https://ssl.comodoca.com/s-mime) | [Document signing](https://ssl.comodoca.com/document-signing-certificates) | +| Digicert | [S/MIME email signing](https://www.digicert.com/tls-ssl/secure-email-smime-certificates) | [Document signing](https://www.digicert.com/signing/document-signing-certificates) | ### Certificate signing requests (CSRs) diff --git a/docs/signing/index.md b/docs/signing/index.md index 9ad8a15..acc5189 100644 --- a/docs/signing/index.md +++ b/docs/signing/index.md @@ -8,11 +8,12 @@ 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. [**Initial prototyping and development**](test-certs.md): 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. 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 . + - [Use the certificate and key *locally*](local-signing.md) (directly from the file system) to sign manifest claims. IMPORTANT: this is *not* safe in production. +1. [**Production testing/deployment**](prod-cert.mdx): 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 Best practices for handling keys and certificates are beyond the scope of this documentation. Always protect your private keys with the highest level of security; for example, never share them through insecure channels such as email.