feat: add OSCAL signing and verification flow (#2253)

* feat: add OSCAL signing and verification flow

Signed-off-by: Matteo Fari <matteofari06@gmail.com>

* fix: address signing and verification review feedback

Signed-off-by: Matteo Fari <matteofari06@gmail.com>

* fix: gate signing commands behind beta feature

Signed-off-by: Matteo Fari <matteofari06@gmail.com>

---------

Signed-off-by: Matteo Fari <matteofari06@gmail.com>

Author: MatteoFari

README.md

@@ -30,6 +30,7 @@ Trestle provides tooling to help orchestrate the compliance process across a num
 - Tooling manage authoring and governance of markdown and drawio files within a repository.
 - Support within trestle to streamline management within a managed git environment.
 - An underlying object model that supports developers interacting with OSCAL artifacts.
+- Detached signing and verification for JSON artifacts.
 
 ## Why Trestle
 

docs/index.md

@@ -34,6 +34,7 @@ Trestle provides tooling to help orchestrate the compliance process across a num
 - Tooling manage authoring and governance of markdown and drawio files withn a repository.
 - Support within trestle to streamline management within a managed git environment.
 - An underlying object model that supports developers interacting with OSCAL artefacts.
+- Detached signing and verification for JSON artifacts. See the [`trestle sign` and `trestle verify` CLI documentation](tutorials/cli.md#trestle-sign).
 
 ## Important Note:
 

docs/predicates/oscal-signing/v1.md

@@ -0,0 +1,63 @@
+---
+title: OSCAL Signing Predicate v1
+description: Predicate type used by compliance-trestle detached JSON signatures
+---
+
+# OSCAL Signing Predicate v1
+
+Trestle uses this predicate type in the in-toto Statement created by `trestle sign`:
+
+```text
+https://oscal-compass.github.io/compliance-trestle/predicates/oscal-signing/v1
+```
+
+The predicate describes how trestle created the digest for a signed JSON artifact.
+The predicate type URI is recorded in the signed Statement and is not fetched
+during verification.
+
+For command usage, see the [`trestle sign` and `trestle verify` CLI documentation](../../tutorials/cli.md#trestle-sign).
+
+## What is signed
+
+`trestle sign` creates a detached DSSE envelope. The envelope payload is an in-toto Statement that records:
+
+- the subject file name
+- the SHA-256 digest of the RFC 8785 canonical JSON bytes
+- the predicate type and predicate fields described below
+
+The DSSE signature is made over the DSSE pre-authentication encoding of the
+Statement payload. The original JSON file is not modified.
+
+## Statement
+
+The DSSE payload is a base64-encoded in-toto Statement with exactly one subject:
+
+```json
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "catalog.json",
+      "digest": {
+        "sha256": "..."
+      }
+    }
+  ],
+  "predicateType": "https://oscal-compass.github.io/compliance-trestle/predicates/oscal-signing/v1",
+  "predicate": {
+    "canonicalization": "RFC8785",
+    "digestAlgorithm": "sha256",
+    "digestSource": "canonical-json",
+    "tool": "compliance-trestle"
+  }
+}
+```
+
+## Predicate fields
+
+| Field              | Description                                                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canonicalization` | The canonicalization algorithm applied before hashing. Trestle uses `RFC8785`.                                                                  |
+| `digestAlgorithm`  | The digest algorithm used over the canonical JSON bytes. Trestle uses `sha256`.                                                                 |
+| `digestSource`     | The bytes that were hashed. `canonical-json` means the digest was computed over the RFC 8785 canonical JSON bytes, not the original file bytes. |
+| `tool`             | The producer of the predicate. Trestle writes `compliance-trestle`.                                                                             |

docs/tutorials/cli.md

@@ -5,13 +5,14 @@ description: An introductory tutorial into trestle's CLI and OSCAL use cases
 
 # trestle CLI Overview and OSCAL usecases
 
-The trestle CLI has five primary use cases:
+The trestle CLI has six primary use cases:
 
 - Serve as tooling to generate and manipulate OSCAL files directly by an end user. The objective is to reduce the complexity of creating and editing workflows. Example commands are: `trestle import`, `trestle create`, `trestle split`, `trestle merge`.
 - Act as an automation tool that, by design, can be an integral part of a CI/CD pipeline e.g. `trestle validate`, `trestle tasks`.
 - Allow governance of markdown documents so they conform to specific style or structure requirements.
 - Canonicalize JSON documents with `trestle canonicalize`. See [Canonicalizing JSON documents](canonicalization.md).
 - Manage experimental commands with `trestle beta`.
+- Sign and verify JSON artifacts with detached DSSE envelopes.
 
 To support each of these use cases trestle creates an opinionated directory structure to manage governed documents.
 
@@ -593,6 +594,68 @@ By default validate will display warning messages and a message indicating the f
 The links validator is special because it always returns success that the file is valid - but it will list any inconsistencies it finds between the
 references to links, and corresponding links in the backmatter.
 
+## `trestle sign`
+
+Trestle sign writes a detached DSSE envelope for a JSON file. It canonicalizes the JSON using RFC 8785, computes a SHA-256 digest, records that digest in an in-toto Statement, and signs the Statement with a PEM private key.
+
+The sign and verify commands are beta features. Enable them before use:
+
+```bash
+trestle beta enable json-signing
+```
+
+You can also pass `--beta` to `trestle sign` or `trestle verify` to run the beta command one time without writing beta state to config.
+
+Generate an Ed25519 private/public key pair with OpenSSL:
+
+```bash
+openssl genpkey -algorithm ed25519 -out private.pem
+openssl pkey -in private.pem -pubout -out public.pem
+chmod 600 private.pem
+```
+
+The private key is used for signing. Keep it secret. The public key can be shared with users or systems that need to verify signatures.
+
+```bash
+trestle sign \
+  -f catalog.json \
+  --key private.pem \
+  -o catalog.json.dsse
+```
+
+For an encrypted private key, use `--key-password-env`. The option names an environment variable that contains the password, so the password is not passed as a command-line argument.
+
+```bash
+export TRESTLE_KEY_PASSWORD='replace-with-your-password'
+openssl genpkey -algorithm ed25519 -aes-256-cbc -pass env:TRESTLE_KEY_PASSWORD -out private-encrypted.pem
+openssl pkey -in private-encrypted.pem -passin env:TRESTLE_KEY_PASSWORD -pubout -out public.pem
+chmod 600 private-encrypted.pem
+trestle sign \
+  -f catalog.json \
+  --key private-encrypted.pem \
+  --key-password-env TRESTLE_KEY_PASSWORD \
+  -o catalog.json.dsse
+```
+
+RSA PEM keys may also be used.
+
+The `--subject-name` option records a subject name other than the input file name. Verification must use the same subject name.
+
+The signed Statement uses the [OSCAL signing predicate](../predicates/oscal-signing/v1.md).
+
+## `trestle verify`
+
+Trestle verify checks a JSON file against a detached DSSE envelope and a PEM public key. Verification checks the DSSE signature, the predicate fields, and the SHA-256 digest of the RFC 8785 canonical JSON bytes.
+
+```bash
+trestle verify \
+  -f catalog.json \
+  --signature catalog.json.dsse \
+  --key public.pem
+```
+
+If signing used `--subject-name`, pass the same value during verification.
+
 ## `trestle tasks`
 
 Open Shift Compliance Operator and Tanium are supported as 3rd party tools.

pyproject.toml

@@ -48,6 +48,7 @@ dependencies = [
     "cmarkgfm>=2024.1,<2025.11",
     "orjson",
     "rfc8785>=0.1.4",
+    "securesystemslib[crypto]>=1.3.1,<2.0",
     "requests>=2.32.2",
     "importlib_resources",
 ]