---
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 selected digest of the RFC 8785 canonical JSON bytes (SHA-256 by default)
- 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. This example uses the default SHA-256 algorithm:

```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 selected digest algorithm in in-toto notation, such as `sha256`, `sha384`, or `sha3_256`. Defaults to `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`.                                                                             |

Supported digest names are `sha224`, `sha256`, `sha384`, `sha512`, `sha3_224`, `sha3_256`, `sha3_384`, and `sha3_512`. After verifying the DSSE signature, verification detects the algorithm from the authenticated predicate's `digestAlgorithm` and checks the corresponding subject digest. An explicit `--digest-algorithm` additionally requires the predicate to identify that algorithm. The algorithm metadata is covered by the DSSE signature.

See [Digest algorithms](../../tutorials/cli.md#digest-algorithms) for CLI selection and compatibility with existing SHA-256 envelopes.