Merge pull request #153 from contentauth/signing-cert-example

Add new page on buying and using certs, c2pa-python-example, and c2pa-min example

Author: crandmck

docs/c2pa-min/.gitkeep

@@ -84,7 +84,7 @@ In practice, to use a certificate with the CAI SDK, follow this process:
 
 1. Purchase security credentials (certificate and key) from a certificate authority. Either email protection or document signing certificates are valid.
 2. Extract the certificate by using a tool such as OpenSSL. You could also host the certificate in a secure environment like a hardware security module (HSM).
-3. Use the Rust library or C2PA Tool to sign manifests using the certificate.
+3. Use one of the supporting CAI libraries or C2PA Tool to sign manifests using the certificate. 
 
 :::tip
 For more details and a short tutorial example, see [Signing manifests](manifest/signing-manifests).
@@ -127,10 +127,14 @@ The _private key_ associated with the certificate is extremely sensitive. Always
 
 The simplest way to add a C2PA manifest to an asset file is by using C2PA Tool (`c2patool`). You can run C2PA Tool 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-service-example).
 
-You can also add Content Credentials using the prerelease libraries for [Node.js](c2pa-node/), [Python](c2pa-python/), and [C++/C](c2pa-c/)
+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. For a simple example of creating and signing a manifest from a C program, see the [c2c2pa repository](https://github.com/contentauth/c2c2pa).
 
+:::warning Warning
+Do not access a private key and certificate directly from the file system in production. Doing so is not secure because it exposes these sensitive files to potential attackers. Instead use a hardware security module (HSM) and optionally a Key Management Service (KMS); for example as show in the [C2PA Python Example](../docs/c2pa-python-example).
+:::
+
 ### Verify known certificate list
 
 import verify_unknown_source from '../static/img/verify-cc-unknown-source.png';

docs/c2pa-python-example/.gitkeep

@@ -41,15 +41,15 @@ For development and testing, use the sample certificates provided with the SDK.
 Additionally, for convenience, 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.
 
 :::warning Warning
-These certificates are for use during development and testing only.  Do not use them in production!
+The test certificates are for use during development and testing only.  Do not use them in production!
 :::
 
-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.3/specs/C2PA_Specification.html#_credential_types) and [Digital Signatures](https://c2pa.org/specifications/specifications/1.3/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 [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.
 
 
 ### Signature types
 
-The following table describes the signature algorithms and recommended signature types that the [C2PA Tool](/docs/c2patool) and [Rust library](/docs/rust-sdk) support. You must supply credentials (certificates and keys) that correspond to the signing algorithm. Signing/validation will fail if the the supplied credentials don't support the signature type. 
+The following table describes the signature algorithms and signature types that the CAI SDK supports. You must supply credentials (certificates and keys) that correspond to the signing algorithm. Signing/validation will fail if the the supplied credentials don't support the signature type. 
 
 | Certificate `signatureAlgorithm` | Description  | Recommended signature type | RFC Reference |
 | -------------------------------- | ------------ | -------------------------- | ------------- |
@@ -65,7 +65,7 @@ The following table describes the signature algorithms and recommended signature
 | `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) |
 
 
-The information in this table is based on the [C2PA specification Trust Model section](https://c2pa.org/specifications/specifications/1.3/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.
+The information in this table is based on the [C2PA specification Trust Model section](https://c2pa.org/specifications/specifications/1.4/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.
 
 ## Example
 
@@ -85,7 +85,7 @@ Follow the instructions to purchase and download your `.pfx` file. This file is
 
 :::warning Warning
 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.
-:::info
+:::
 
 The rest of this tutorial uses OpenSSL (a set of cryptographic utilities). If OpenSSL is not installed on your system, see [OpenSSL](https://www.openssl.org/source/) for the source distribution or the [list of unofficial binary distributions](https://wiki.openssl.org/index.php/Binaries).
 
@@ -165,18 +165,20 @@ You now have all the needed information to configure C2PA Tool for manifest sign
 "sign_cert": "mycerts.pem"
 ```
 
-:::note
 The `private_key` and `sign_cert` properties must be full paths to the key and certificate chain files generated above.
-:::note
 
-You can now use C2PA Tool as described in its [documentation](/docs/c2patool/#adding-a-manifest-to-an-asset-file) to add a to add a manifest to an image or other asset file. The command will be something like this:
+You can now use C2PA Tool as described in its [documentation](/docs/c2patool/#adding-a-manifest-to-an-asset-file) to add a manifest to an image or other asset file. The command will be something like this:
 
 ```
 c2patool -m my_manifest.json -o signed_image.jpg my_image.jpg
 ```
 
 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`.
 
+:::warning
+In a production application, do not access a private key and certificate directly from the file system as shown in this example. Doing so is fine during development, but not in production because it exposes these sensitive files to potential attackers. Instead use a hardware security module (HSM) and optionally a Key Management Service (KMS) to access them; for example as show in the [C2PA Python Example](../../docs/c2pa-python-example).
+:::
+
 ### Confirm it worked
 
 Use C2PA Tool to confirm that you successfully signed the asset. Enter a command like this:

docs/getting-started.mdx

@@ -0,0 +1,48 @@
+---
+id: prod-cert
+title: Getting and using a signing certificate
+---
+
+## Overview
+
+For convenience, C2PA Tool, the Rust library, and the CAI prerelease libraries include one or more [test certificates](manifest/signing-manifests#test-certificates) and private keys for use during development, typically in the `tests/fixtures` directory. While these test certificates and keys are useful during development and testing, for production deployment you must use your own private key and certificate.
+
+Certificates and private keys are often stored on a hardware security module (HSM), a physical device that attaches directly to a computer or server and is used to securely manage and perform operations on cryptographic keys. A Key Management Service (KMS) is software used to manage keys in a networked environment. A KMS can be connected to a HSM for extra security. For example, the [Python example application](/c2pa-python-example) uses [AWS KMS](https://aws.amazon.com/kms/).
+
+## Purchasing a certificate
+
+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#getting-a-security-certificate).
+
+When you purchase a certificate, 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.
+
+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 (see below). Regardless of the process, what you get back is a signed certificate that you use to create a certificate chain.
+
+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.
+
+### Certificate signing requests (CSRs)
+
+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.
+
+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.
+
+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.
+
+### Types of certificates
+
+CAs offer a variety of different kinds of certificates (links below are to [Digicert](https://www.digicert.com), but there are many other CAs):
+
+- 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.
+
+### CA validation
+
+CAs offer many levels of validation. For Content Credentials, one of these types is highly recommended (though not required):
+
+- **Organization Validated (OV).** The CA validates the organization's identity by checking its credentials against extensive databases, including those held by local governments.
+- **Extended Validation (EV).** A fully authenticated certificate, needed to offer secure web locations, email, and financial transactions.
+
+If you don't get an OV certificate, then the C2PA [Verify tool](https://verify.contentauthenticity.org/) won't display your organization name in the Content Credentials.
+
+## The C2PA Python example
+
+The [c2pa-python-example](/c2pa-python-example) app provides an example of constructing a certificate signing request (CSR) and of using a certificate in a way suitable for a production environment.

docs/manifest/signing-manifests.md

@@ -24,6 +24,11 @@ const readmes = [
     repo: 'contentauth/c2pa-rs',
     path: 'README.md',
   },
+  {
+    dest: resolve(__dirname, '../docs/c2pa-min/readme.md'),
+    repo: 'contentauth/c2pa-min',
+    path: 'README.md',
+  },
   {
     dest: resolve(__dirname, '../docs/c2patool/readme.md'),
     repo: 'contentauth/c2patool',
@@ -69,6 +74,11 @@ const readmes = [
     repo: 'contentauth/c2pa-python',
     path: 'README.md',
   },
+  {
+    dest: resolve(__dirname, '../docs/c2pa-python-example/readme.md'),
+    repo: 'contentauth/c2pa-python-example',
+    path: 'README.md',
+  },
 ];
 
 function resolveMarkdownLinks(linkBase, content) {

docs/prod-cert.mdx

@@ -130,6 +130,11 @@ const sidebars = {
               label: 'GitHub',
               href: 'https://github.com/contentauth/c2pa-python',
             },
+            {
+              type: 'doc',
+              label: 'C2PA Python Example',
+              id: 'c2pa-python-example/readme',
+            },
           ],
         },
         {
@@ -164,8 +169,18 @@ const sidebars = {
           label: 'GitHub',
           href: 'https://github.com/contentauth/c2pa-rs',
         },
+        {
+          type: 'doc',
+          label: 'C2PA Rust example application',
+          id: 'c2pa-min/readme',
+        },
       ],
     },
+    {
+      type: 'doc',
+      label: 'Getting and using a certificate',
+      id: 'prod-cert',
+    },
     {
       type: 'doc',
       label: 'FAQs',