Skip to content

Commit 7baea9f

Browse files
crandmckcrandmck
committed
More reorg
1 parent ee9dc27 commit 7baea9f

File tree

7 files changed

+162
-124
lines changed

7 files changed

+162
-124
lines changed

‎docs/getting-started.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,8 @@ In practice, to use a certificate with the CAI SDK, follow this process:
8686
2. Extract the certificate by using a tool such as OpenSSL (for use during development). In production, you should host the private key in a secure environment like a hardware security module (HSM).
8787
3. Use one of the supporting CAI libraries or C2PA Tool to sign manifests using the certificate and your private key.
8888

89-
:::tip
90-
For a short tutorial example, see [Signing manifests](signing/signing-manifests.md). For more information on how to get and use a signing certificate in production, see [Getting and using a signing certificate](signing/prod-cert.mdx).
89+
:::info
90+
For more information on getting and using certificates, see [Signing and certificates](signing/signing-certs.md).
9191
:::
9292

9393
### Verify known certificate list

‎docs/signing/get-cert.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
id: get-cert
3+
title: Getting a signing certificate
4+
---
5+
6+
:::note
7+
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.
8+
:::
9+
10+
## Requirements
11+
12+
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:
13+
14+
- Follow the public key infrastructure (PKI) X.509 V3 specification.
15+
- Have the Key Usage (KU) extension, which must be marked as critical.
16+
- Assert the `digitalSignature` bit.
17+
- Have the Extended Key Usage (EKU) extension. If the Basic Constraints extension is absent or the certificate authority (CA) Boolean is not asserted, the EKU must be non-empty.
18+
- The `anyExtendedKeyUsageEKU` field (2.5.29.37.0) must not be present.
19+
- If the configuration store does not contain a list of EKUs, a certificate that signs C2PA manifests must be valid for the `id-kp-emailProtection` (1.3.6.1.5.5.7.3.4) purpose and/or the `id-kp-documentSigning` (1.3.6.1.5.5.7.3.36) purpose.
20+
21+
## Certificate authorities (CAs)
22+
23+
To get a signing certificate, you must purchase a X.509 v3 security certificate from a certificate authority (CA).
24+
25+
You must select at least one of the extended key usage (EKU) fields that specify what the certificate can be used for: **email protection** and **document signing**. Applications that use the CAI SDK won't accept the certificate unless it has one of these EKUs.
26+
27+
There are many CAs that issue certificates. Some of the most popular ones are:
28+
29+
- GlobalSign: [S/MIME email signing](https://shop.globalsign.com/en/secure-email), [document signing](https://shop.globalsign.com/en/document-signing)
30+
- IdenTrust: [S/MIME email signing](https://www.identrust.com/digital-certificates/secure-email-smime), [document signing](https://www.identrust.com/digital-certificates/document-signing)
31+
- Comodo Cybersecurity: [S/MIME email signing cert](https://ssl.comodoca.com/s-mime), [document signing cert](https://ssl.comodoca.com/document-signing-certificates)
32+
- 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)
33+
34+
The above list is for reference only; inclusion does not imply endorsement by CAI or Adobe, Inc.
35+
36+
### Types of certificates
37+
38+
CAs offer a variety of different kinds of certificates (links below are to [Digicert](https://www.digicert.com), but there are many other CAs):
39+
40+
- The simplest and least expensive option is an [S/MIME email certificate](https://www.digicert.com/tls-ssl/compare-secure-email-smime-certificates).
41+
- 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.
42+
43+
### Organization name
44+
45+
If you want the C2PA [Verify tool](https://verify.contentauthenticity.org/) to display your organization name in the Content Credentials, your certificate must include the "O" or [Organization Name attribute](https://www.alvestrand.no/objectid/2.5.4.10.html) (OID value 2.5.4.10) in the distinguished name information. The CA may require some validation steps to prove you are part of that organization (details vary by CA).
46+
47+
## Purchasing a certificate
48+
49+
To create or modify Content Credentials, you must have a valid X.509 v3 security certificate and key that conform to the requirements laid out in the [C2PA specification](https://c2pa.org/specifications/specifications/2.0/specs/C2PA_Specification.html#x509_certificates). You must purchase a certificate from a certificate authority (CA). There are many CAs; some popular ones are listed in [Getting started](getting-started.mdx#getting-a-security-certificate).
50+
51+
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.
52+
53+
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.
54+
55+
### Signature types
56+
57+
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.
58+
59+
| Certificate `signatureAlgorithm` | Description | Recommended signature type | RFC Reference |
60+
| -------------------------------- | ------------ | -------------------------- | ------------- |
61+
| `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) |
62+
| `ecdsa-with-SHA384` | ECDSA with SHA-384 | ES384<sup>\*</sup> | [RFC 5758 section 3.2](https://www.rfc-editor.org/rfc/rfc5758.html#section-3.2) |
63+
| `ecdsa-with-SHA512` | ECDSA with SHA-512 | ES512<sup>\*</sup> | [RFC 5758 section 3.2](https://www.rfc-editor.org/rfc/rfc5758.html#section-3.2) |
64+
| `sha256WithRSAEncryption` | RSASSA-PSS with SHA-256<br/>MGF1 with SHA-256 | PS256 | [RFC 8017 appendix A.2.4](https://www.rfc-editor.org/rfc/rfc8017.html#appendix-A.2.4) |
65+
| `sha384WithRSAEncryption` | RSASSA-PSS<br/>SHA-384, MGF1 with SHA-384 | PS384 | [RFC 8017 appendix A.2.4](https://www.rfc-editor.org/rfc/rfc8017.html#appendix-A.2.4) |
66+
| `sha512WithRSAEncryption` | RSASSA-PSS<br/>SHA-512, MGF1 with SHA-512 | PS512 | [RFC 8017 appendix A.2.4](https://www.rfc-editor.org/rfc/rfc8017.html#appendix-A.2.4) |
67+
| `id-RSASSA-PSS` - ASN1 OID: prime256v1, NIST CURVE: P-256 | RSA-PSS | ES256<sup>\*</sup> | [RFC 5758 section 3.2](https://www.rfc-editor.org/rfc/rfc5758.html#section-3.2) |
68+
| `id-RSASSA-PSS` - ASN1 OID: secp384r1 | RSA-PSS | ES384<sup>\*</sup> | [RFC 5758 section 3.2](https://www.rfc-editor.org/rfc/rfc5758.html#section-3.2) |
69+
| `id-RSASSA-PSS` - ASN1 OID: secp521r1 | RSA-PSS | ES512<sup>\*</sup> | [RFC 5758 section 3.2](https://www.rfc-editor.org/rfc/rfc5758.html#section-3.2) |
70+
| `id-Ed25519` | EdDSA (Edwards-Curve DSA) with SHA-512 (SHA-2) and Curve25519 | Ed25519 instance ONLY. | [RFC 8410 section 3](https://www.rfc-editor.org/rfc/rfc8410.html#section-3) |
71+
72+
:::info
73+
74+
<a name="table-note"></a>
75+
<sup>*</sup> ES256, ES384, and ES512 signatures must be in IEEE P1363 format.
76+
77+
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.
78+
79+
### Certificate signing requests (CSRs)
80+
81+
A CSR is just an unsigned certificate that's a template for the certificate that you're requesting. The CA creates a new certificate with the parameters specified in the CSR, and signs it with their root certificate, which makes it a valid certificate.
82+
83+
A CSR comprises a public key, as well as ["distinguished name" information](https://knowledge.digicert.com/general-information/what-is-a-distinguished-name) that identifies the individual or organization requesting the certificate. The distinguished name includes a common name, organization, city, state, country, and e-mail address. Not all of these fields are required and will vary depending with the assurance level of the desired certificate.
84+
85+
:::tip
86+
For the C2PA [Verify tool](https://verify.contentauthenticity.org/) to display your organization name in the Content Credentials, your CSR must include the "O" or Organization Name attribute in the distinguished name information. See [below](#organization-name) for details.
87+
:::
88+
89+
You sign the CSR with your private key; this proves to the CA that you have control of the private key that corresponds to the public key included in the CSR. Once the requested information in a CSR passes a vetting process and domain control is established, the CA may sign the public key to indicate that it can be publicly trusted.
90+

‎docs/signing/index.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
id: signing-and-certs
3+
title: Signing and certificates
4+
---
5+
6+
:::tip
7+
Be sure to read [Getting started](getting-started.mdx#signing-and-certificates) for some basic background on public-key infrastructure (PKI) technology, certificates, and signing manifests.
8+
:::
9+
10+
As you're developing an application that uses the CAI SDK, there are three ways to sign manifest claims:
11+
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.
12+
1. [**Local/internal testing**](local-signing.md): Once your code is working with the test certs and keys, you're ready to purchase your own certificate from a certificate authority (CA) using your private key. Then for internal testing, your application can use the certificate and key *locally* (i.e. directly from the file system) to sign manifest claims; however, this is NOT safe in production.
13+
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). Then your application can access it securely in production.
14+
15+
:::warning
16+
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.
17+
:::

0 commit comments

Comments
 (0)