You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/signing/get-cert.md
+38-36Lines changed: 38 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,28 +3,17 @@ id: get-cert
3
3
title: Getting a signing certificate
4
4
---
5
5
6
-
:::note
6
+
:::note Important
7
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
8
:::
9
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.
10
+
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).
20
11
21
12
## Certificate authorities (CAs)
22
13
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.
14
+
To create or modify Content Credentials, you must purchase a signing certificate from a certificate authority (CA).
26
15
27
-
There are many CAs that issue certificates. Some of the most popular ones are:
16
+
There are many CAs that issue certificates. Some popular ones include:
@@ -35,22 +24,47 @@ The above list is for reference only; inclusion does not imply endorsement by CA
35
24
36
25
### Types of certificates
37
26
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):
27
+
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):
39
28
40
29
- The simplest and least expensive option is an [S/MIME email certificate](https://www.digicert.com/tls-ssl/compare-secure-email-smime-certificates).
41
30
- 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
31
43
-
### Organization name
32
+
### Purchasing a certificate
44
33
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).
34
+
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.
46
35
47
-
## Purchasing a certificate
36
+
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.
48
37
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).
38
+
### Certificate signing requests (CSRs)
50
39
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.
40
+
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.
52
41
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.
42
+
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.
43
+
44
+
:::tip
45
+
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.
46
+
:::
47
+
48
+
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.
49
+
50
+
## Certificate requirements
51
+
52
+
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:
53
+
54
+
- Follow the public key infrastructure (PKI) X.509 V3 specification.
55
+
- Have the Key Usage (KU) extension, which must be marked as critical.
56
+
- Assert the `digitalSignature` bit.
57
+
- 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.
58
+
- The `anyExtendedKeyUsageEKU` field (2.5.29.37.0) must not be present.
59
+
- 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.
60
+
61
+
### Extended key usage (EKU) fields
62
+
63
+
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.
64
+
65
+
### Organization name
66
+
67
+
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).
54
68
55
69
### Signature types
56
70
@@ -69,22 +83,10 @@ The following table describes the signature algorithms and types that the CAI SD
|`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
85
72
-
:::info
73
-
74
-
<aname="table-note"></a>
75
86
<sup>*</sup> ES256, ES384, and ES512 signatures must be in IEEE P1363 format.
76
87
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.
88
+
---
84
89
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
-
:::
90
+
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.
88
91
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.
Copy file name to clipboardExpand all lines: docs/signing/index.md
+8-6Lines changed: 8 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,11 +7,13 @@ title: Signing and certificates
7
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
8
:::
9
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.
10
+
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:
11
+
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).
12
+
1.**Local/internal testing**: Once your code is working with the test certs and keys:
13
+
-[Purchase your own certificate](get-cert.md) from a certificate authority (CA).
14
+
- 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.
15
+
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 .
14
16
15
-
:::warning
17
+
:::note
16
18
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.
Copy file name to clipboardExpand all lines: docs/signing/local-signing.md
+6-17Lines changed: 6 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,14 +9,6 @@ To sign a claim in a C2PA manifest you need an end-entity certificate that compl
9
9
10
10
Trust lists connect the end-entity certificate that signed a manifest back to the originating root CA. This is accomplished by supplying the subordinate public X.509 certificates forming the trust chain (the public X.509 certificate chain). If those are not supplied, you can use a private credential store to validate the certificate trust chain. If you do not supply a certificate chain or trust list, validators may reject the manifest. See the C2PA specification for more details.
11
11
12
-
### Extracting the certificate
13
-
14
-
To work with the certificate, you need to extract it. When the CAI SDK adds Content Credentials to an asset, it incorporates the certificate (including the associated public key) into the manifest.
15
-
16
-
:::warning Important
17
-
The _private key_ associated with the certificate is extremely sensitive. Always treat it with the highest security to ensure your credentials are not compromised. If someone does obtain your private key, they will be able to sign C2PA manifests and other content on your behalf without your consent.
18
-
:::
19
-
20
12
## Signing a manifest
21
13
22
14
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).
@@ -26,16 +18,12 @@ Similarly, using the Rust SDK, you can [add a manifest to an asset file](https:/
26
18
The prerelease libraries for [Node.js](../c2pa-node), [Python](../c2pa-python), and [C++/C](../c2pa-c) can also add and sign a manifest.
27
19
28
20
:::warning Warning
29
-
Accessing a private key and certificate directly from the file system is fine during development, but doing so in production is not ecure. Instead use a Key Management Service (KMS) or a hardware security module (HSM) to access the certificate and key; for example as show in the [C2PA Python Example](https://github.com/contentauth/c2pa-python-example).
21
+
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).
30
22
:::
31
23
32
24
## Example
33
25
34
-
Here is an example of generating a C2PA-compliant set of credentials using [GlobalSign](http://globalsign.com/) certificate authority (CA).
35
-
GlobalSign is just one of many CAs. For a list of some others, see [Getting a security certificate](#getting-a-security-certificate) above.
36
-
37
-
38
-
Credential management is a complex topic and different for every organization. See [above](#overview) for links to best practices.
26
+
Here is an example of generating a C2PA-compliant set of credentials using [GlobalSign](http://globalsign.com/) certificate authority (CA). GlobalSign is just one of many CAs. For a list of some others, see [Getting a security certificate](get-cert.md#certificate-authorities-cas).
39
27
40
28
:::note
41
29
This example uses an inexpensive personal certificate, which is fine for development and testing, but for production use an enterprise certificate is strongly recommended. An enterprise certificate is required for [Verify](https://verify.contentauthenticity.org/) to display your organization name when for signed assets.
@@ -51,6 +39,7 @@ The rest of this tutorial uses OpenSSL (a set of cryptographic utilities). If Op
51
39
52
40
### Step 2: Extract the certificate and key
53
41
42
+
To work with the certificate, you need to extract it. When the CAI SDK adds Content Credentials to an asset, it incorporates the certificate (including the associated public key) into the manifest.
54
43
Use the commands below to extract the key and certificate chain. If prompted, enter the password that was used to generate the `.pfx` file.
55
44
56
45
:::tip
@@ -117,7 +106,7 @@ Certificate:
117
106
.
118
107
```
119
108
120
-
You now have all the needed information to configure C2PA Tool for manifest signing. Edit your [manifest store file](c2patool/docs/manifest.md) to add the following fields that are specific to C2PA Tool:
109
+
You now have all the needed information to configure C2PA Tool for manifest signing. Edit your [manifest store file](../c2patool/docs/manifest.md) to add the following fields that are specific to C2PA Tool:
121
110
122
111
```json
123
112
"alg": "ps256",
@@ -127,7 +116,7 @@ You now have all the needed information to configure C2PA Tool for manifest sign
127
116
128
117
The `private_key` and `sign_cert` properties must be full paths to the key and certificate chain files generated above.
129
118
130
-
You can now use C2PA Tool [to add a manifest to an image or other asset file](c2patool/docs/usage.md#adding-a-manifest-to-an-asset-file). The command will be something like this:
119
+
You can now use C2PA Tool [to add a manifest to an image or other asset file](../c2patool/docs/usage.md#adding-a-manifest-to-an-asset-file). The command will be something like this:
The example above uses the information in `my_manifest.json` to add a new manifest to output `signed_image.jpg` using source `my_image.jpg`. The manifest will be signed using the PS256 signature algorithm with private key `mykey.pem`. The manifest will contain the trust chain specified in `mycerts.pem`.
137
126
138
127
:::warning
139
-
This example accesses the private key and certificate directly from the file system, which is fine during development, but is not secure for use in production. Instead, use a hardware security module (HSM) or a Key Management Service (KMS); for example as show in the [C2PA Python Example](c2pa-python-example/readme.md).
128
+
This example accesses the private key and certificate directly from the file system, which is fine during development, but is not secure for productionuse. For more information, see [Using a certificate in production](prod-cert.mdx).
0 commit comments