From d88b1d468cab0ffe502321721b96c777dd2cb24e Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Tue, 4 Feb 2025 15:26:19 -0800 Subject: [PATCH 1/5] Add sanity check instructions --- docs/trust-list.mdx | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/trust-list.mdx b/docs/trust-list.mdx index 29fa9a6..9414552 100644 --- a/docs/trust-list.mdx +++ b/docs/trust-list.mdx @@ -26,13 +26,44 @@ The [contentcredentials.org](https://contentcredentials.org/) site hosts the fol - **The temporary known anchor list** in https://contentcredentials.org/trust/anchors.pem contains the list of known anchor certificates. If an end-entity [certificate's chain](getting-started.mdx#signing-and-certificates) can be traced back to an anchor certificate on this list, the certificate is considered "known." - **The configuration file**, https://contentcredentials.org/trust/store.cfg, specifies the [Extended Key Usage (EKU)](https://datatracker.ietf.org/doc/html/rfc9336) values accepted for end-entity certificates. An end-entity certificate must have at least one of the EKUs in this list to be valid. +## Checking your certificate + +Perform a preliminary "sanity check" on your certificate before requesting that it be added to the known certificate list. + +1. Ensure that C2PA Tool can use the certificate and doesn't return any validation errors by using a command like this: + +``` +c2patool ./image.jpg trust --allowed_list ./cert.pem +``` + +Confirm that the result does not contain a `validation_status` field which indicates an error. + +1. Confirm that the `signature_info.issuer` field in the manifest is correct. This field determines what Verify displays. In this example, replace "XYZ Inc." with the name of your organization: + +``` +c2patool ./image.jpg trust --allowed_list ./cert.pem \ +| jq --args '.manifests[].signature_info.issuer' "XYZ Inc." +``` + +1. Perform basic verification of the certificate you're submitting; for example: + +``` +openssl x509 -noout -text -in 'cert.pem' | grep 'Subject:' +``` + +Example response: + +``` +Subject: organizationIdentifier=XYZ-7155227, C=US, ST=Delaware, L=Dover, O=Whatever Inc., SN=xxx, GN=xxx, CN=xxx +``` + ## Using the known certificate list You can use the C2PA Tool or the CAI JavaScript library to determine whether a certificate is on the temporary known certificate list. ### Using with C2PA Tool -The [C2PA Tool documentation](c2patool/readme.md#configuring-trust-support) explains how to use the temporary known certificate list with the tool. +The [C2PA Tool documentation](c2patool/docs/usage.md#configuring-trust-support) explains how to use the temporary known certificate list with the tool. ### Using with the JavaScript library @@ -84,6 +115,9 @@ This code is for illustration purposes only. To ensure acceptable performance, p ## How to add a certificate to the list -If you have an application that is in production and publicly available, you can request to add its signing certificate to the temporary known certificate list: Simply email `verify-tl@c2pa.org`. +If you have an application that is in production and publicly available, you can request to add its signing certificate to the temporary known certificate list. + +Follow these steps: -We will review your request, and if it is approved, we'll ask for more details. Once we receive them and deploy the change, you will receive a confirmation email. +1. [**Do a preliminary check of your certificate**](#checking-your-certificate) to ensure it meets the requirements for C2PA signing certificates and to be in the Verify temporary certificate list. +1. **Submit your request** by emailing `verify-tl@c2pa.org`. We will review your request, and if it is approved, we'll ask for more details. Once we receive them and deploy the update to the trust list, you will receive a confirmation email. From 6c953abee9218fedfee78c1635be6f4870ca7350 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Tue, 4 Feb 2025 15:44:37 -0800 Subject: [PATCH 2/5] Clean up and formatting --- docs/trust-list.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/trust-list.mdx b/docs/trust-list.mdx index 9414552..fb8d167 100644 --- a/docs/trust-list.mdx +++ b/docs/trust-list.mdx @@ -28,24 +28,24 @@ The [contentcredentials.org](https://contentcredentials.org/) site hosts the fol ## Checking your certificate -Perform a preliminary "sanity check" on your certificate before requesting that it be added to the known certificate list. +Before requesting to add your signing certificate to the known certificate list, perform a preliminary "sanity check" on your certificate by following these steps: -1. Ensure that C2PA Tool can use the certificate and doesn't return any validation errors by using a command like this: +1. **Ensure that signing with the certificate doesn't have any validation errors** by using a C2PA Tool command like this: ``` c2patool ./image.jpg trust --allowed_list ./cert.pem ``` -Confirm that the result does not contain a `validation_status` field which indicates an error. +Confirm that the result does not contain a `validation_status` field, which indicates an error. -1. Confirm that the `signature_info.issuer` field in the manifest is correct. This field determines what Verify displays. In this example, replace "XYZ Inc." with the name of your organization: +1. **Confirm that the `signature_info.issuer` field in the manifest is correct**. This field determines what [Verify displays for the organization name](verify.mdx#title-and-signing-information) after "Issued by ...". In this example, replace "XYZ Inc." with the name of your organization: ``` c2patool ./image.jpg trust --allowed_list ./cert.pem \ | jq --args '.manifests[].signature_info.issuer' "XYZ Inc." ``` -1. Perform basic verification of the certificate you're submitting; for example: +1. **Use `openssl` to perform basic verification of the certificate** you're submitting; for example: ``` openssl x509 -noout -text -in 'cert.pem' | grep 'Subject:' From 53bffbba7035c744e2e3bac0f6d1fecddd6ed415 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 5 Feb 2025 13:53:28 -0800 Subject: [PATCH 3/5] reword --- docs/trust-list.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/trust-list.mdx b/docs/trust-list.mdx index fb8d167..443746b 100644 --- a/docs/trust-list.mdx +++ b/docs/trust-list.mdx @@ -28,7 +28,7 @@ The [contentcredentials.org](https://contentcredentials.org/) site hosts the fol ## Checking your certificate -Before requesting to add your signing certificate to the known certificate list, perform a preliminary "sanity check" on your certificate by following these steps: +Before requesting to add your signing certificate to the known certificate list, perform a preliminary check on your certificate by following these steps: 1. **Ensure that signing with the certificate doesn't have any validation errors** by using a C2PA Tool command like this: From 1e60315fcec2fbf19a87824e1ccfba3111c83b52 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 5 Feb 2025 14:13:10 -0800 Subject: [PATCH 4/5] Review comments from AH --- docs/trust-list.mdx | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/trust-list.mdx b/docs/trust-list.mdx index 443746b..be6f1ef 100644 --- a/docs/trust-list.mdx +++ b/docs/trust-list.mdx @@ -38,13 +38,21 @@ c2patool ./image.jpg trust --allowed_list ./cert.pem Confirm that the result does not contain a `validation_status` field, which indicates an error. -1. **Confirm that the `signature_info.issuer` field in the manifest is correct**. This field determines what [Verify displays for the organization name](verify.mdx#title-and-signing-information) after "Issued by ...". In this example, replace "XYZ Inc." with the name of your organization: +1. **Confirm that the `signature_info.issuer` field in the manifest is correct**. This field determines what [Verify displays for the organization name](verify.mdx#title-and-signing-information) after "Issued by ...". Use a C2PA Tool command like this: ``` c2patool ./image.jpg trust --allowed_list ./cert.pem \ -| jq --args '.manifests[].signature_info.issuer' "XYZ Inc." +| jq --args '.manifests[].signature_info.issuer' ``` +The response should be something like this: + +``` +"XYZ Inc." +``` + +Where "XYZ Inc." is the name of your organization. + 1. **Use `openssl` to perform basic verification of the certificate** you're submitting; for example: ``` From 0af1bfd18b6f623c014146c03c9e0a45f13d3cd9 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 5 Feb 2025 14:49:59 -0800 Subject: [PATCH 5/5] Add prereqs, fix list formatting --- docs/trust-list.mdx | 58 +++++++++++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/docs/trust-list.mdx b/docs/trust-list.mdx index be6f1ef..c142ea2 100644 --- a/docs/trust-list.mdx +++ b/docs/trust-list.mdx @@ -28,42 +28,58 @@ The [contentcredentials.org](https://contentcredentials.org/) site hosts the fol ## Checking your certificate -Before requesting to add your signing certificate to the known certificate list, perform a preliminary check on your certificate by following these steps: +Before requesting to [add your signing certificate to the known certificate list](#how-to-add-a-certificate-to-the-list), perform a preliminary check to ensure the certificate is configured properly. + +### Prerequisites + +The preliminary certificate check procedure below requires the following tools. You must install them if you haven't done so already: + +- [jq](https://jqlang.org/), a lightweight and flexible command-line JSON processor. On macOS, if you have [Homebrew](https://brew.sh/), you can install jq by entering `brew install jq`. +- [OpenSSL](https://www.openssl.org/), a cryptographic software library and CLI. It's installed on many systems such as macOS (but make sure you have a recent version). If OpenSSL is not installed on your system, see the [list of unofficial binary distributions](https://wiki.openssl.org/index.php/Binaries). +- [C2PA Tool](c2patool/readme.md), the command line tool for working with C2PA manifests and media assets. + +### Procedure + +:::note +In the example commands given below, `cert.pem` is your certificate file. +::: + +Check your certificate by following these steps: 1. **Ensure that signing with the certificate doesn't have any validation errors** by using a C2PA Tool command like this: -``` -c2patool ./image.jpg trust --allowed_list ./cert.pem -``` + ``` + c2patool ./image.jpg trust --allowed_list ./cert.pem + ``` -Confirm that the result does not contain a `validation_status` field, which indicates an error. + Confirm that the result does not contain a `validation_status` field, which indicates an error. 1. **Confirm that the `signature_info.issuer` field in the manifest is correct**. This field determines what [Verify displays for the organization name](verify.mdx#title-and-signing-information) after "Issued by ...". Use a C2PA Tool command like this: -``` -c2patool ./image.jpg trust --allowed_list ./cert.pem \ -| jq --args '.manifests[].signature_info.issuer' -``` + ``` + c2patool ./image.jpg trust --allowed_list ./cert.pem \ + | jq --args '.manifests[].signature_info.issuer' + ``` -The response should be something like this: + The response should be something like this: -``` -"XYZ Inc." -``` + ``` + "XYZ Inc." + ``` -Where "XYZ Inc." is the name of your organization. + Where "XYZ Inc." is the name of your organization. 1. **Use `openssl` to perform basic verification of the certificate** you're submitting; for example: -``` -openssl x509 -noout -text -in 'cert.pem' | grep 'Subject:' -``` + ``` + openssl x509 -noout -text -in 'cert.pem' | grep 'Subject:' + ``` -Example response: + Example response: -``` -Subject: organizationIdentifier=XYZ-7155227, C=US, ST=Delaware, L=Dover, O=Whatever Inc., SN=xxx, GN=xxx, CN=xxx -``` + ``` + Subject: organizationIdentifier=XYZ-7155227, C=US, ST=Delaware, L=Dover, O=Whatever Inc., SN=xxx, GN=xxx, CN=xxx + ``` ## Using the known certificate list