NVIDIA/yaml-sigil-spec

NVIDIA/yaml-sigil-spec

Description: YAML-preserving + Protobuf round-trip in-toto signing format, seeking evolutionary hardening through public collaboration.

Language: Rust

License: Apache-2.0

Stars: 2

Forks: 0

Open issues: 1

Created: 2026-06-23T20:05:48Z

Pushed: 2026-08-17T19:28:27Z

Default branch: main

Fork: no

Archived: no

README:

YamlSigil.v1alpha1 Specification

tl;dr

yaml-sigil defines a user-facing signed in-toto YAML artifact format. A YAML-form artifact is ordinary payload bytes followed by a final YAML signature document that can be read (but not validated) without agent tool calls:

some: random
yaml: document
---
schema: YamlSigilSignature.v1alpha1
alg: ED25519_PUREEDDSA_RAW_RS64_CANONICAL
keyid:
signature:

A spec matching this didn't exist in any other form to the best of my knowledge. This began as an exploratory effort, found its footing, and even has a Rust implementation: yaml-sigil-traits + yaml-sigil-rs.

There are [known deficiencies](#known-deficiencies) here, but they aren't too rough around the edges in practice.

You're invited to join in helping advance the effort towards a v1alpha2 if you'd like to!

Summary

YamlSigil.v1alpha1 defines two concrete in-toto forms for the same signed artifact model:

• YAML form: payload bytes followed by a final YAML signature document.
• Protobuf form: serialized SignedYamlArtifact.

In both forms the signature covers only the payload bytes. The signature document carries verification inputs: schema, alg, keyid, and signature. Those fields are not authenticated claims.

> [!IMPORTANT] > YamlSigil.v1alpha1 defines a payload-signature layer, not a complete > application security protocol. A Verified result authenticates exact > payload bytes under the verifier's configured key and algorithm policy. > > Your human-readable YAML payload can carry purpose and freshness claims. Your > operating context authorizes the verification key, validates those claims, > enforces replay policy, and assigns meaning to the verified payload bytes.

Artifact Forms

v1alpha1 defines no magic bytes, registered media type, or required file extension. Callers identify the form out of band.

Form selection is deployment policy, not content sniffing. A deployment that supports both forms MUST bind each artifact source, route, or storage class to one accepted form before processing artifact bytes. It MUST NOT retry the same bytes under the other form after a structural or verification failure, and it MUST NOT carry a verification decision into a consumer that interprets those bytes under a different form.

YAML Form

A YAML-form signed artifact is a UTF-8 byte sequence whose last constrained marker starts the signature document. A constrained marker is exactly ---\n or ---\r\n at a line-start position.

some: random
yaml: document
---
schema: YamlSigilSignature.v1alpha1
alg: ED25519_PUREEDDSA_RAW_RS64_CANONICAL
keyid:
signature:

Earlier constrained markers belong to the payload stream:

some: random
yaml: document
---
some: other-random
yaml: document
---
schema: YamlSigilSignature.v1alpha1
alg: ED25519_PUREEDDSA_RAW_RS64_CANONICAL
keyid:
signature:

After encoding preconditions pass, YAML-form decomposition is byte-level and parser-independent:

• No constrained marker produces Unsigned.
• A marker at offset 0 is valid and signs the empty byte string.
• A marker with no following signature-carrier body produces

MalformedAttemptedSigned.

• A final constrained-marker span that is not a valid

YamlSigilSignature.v1alpha1 document produces MalformedAttemptedSigned, not Unsigned.

The full YAML boundary algorithm is in [Artifact Decomposition](./artifact-decomposition.md).

Protobuf Form

The protobuf form is serialized yaml_sigil.v1alpha1.SignedYamlArtifact:

• payload carries arbitrary payload bytes.
• signature carries a YamlSigilSignature submessage.

The protobuf payload is an arbitrary byte container. The YAML-form UTF-8, BOM, and trailing-line-terminator rules do not apply to SignedYamlArtifact.payload. A protobuf artifact whose payload does not satisfy the YAML envelope cannot be transcoded to YAML form.

The Signature Document

The YAML signature document and protobuf YamlSigilSignature are two representations of the same logical schema. Edits MUST keep [proto/yaml_sigil/v1alpha1/yaml_sigil.proto](./proto/yaml_sigil/v1alpha1/yaml_sigil.proto) and [schema/YamlSigilSignature.v1alpha1.schema.json](./schema/YamlSigilSignature.v1alpha1.schema.json) aligned.

| Field | YAML form | Protobuf form | Rule | | --- | --- | --- | --- | | schema | Required string scalar. | Message type. | YAML value MUST be YamlSigilSignature.v1alpha1. | | alg | Required string scalar. | Required Algorithm value. | MUST identify a schema-defined algorithm. | | keyid | Optional string scalar. | Optional string. | When present, MUST be non-empty, at most 1024 UTF-8 octets, and contain no U+000A or U+000D. It is only a lookup hint. | | signature | Required base64url string scalar. | Required bytes. | YAML uses the profile in [Base64 Requirements](./base64-requirements.md). Decoded signature octets MUST be non-empty before runtime algorithm-support classification. |

Algorithms

The YAML alg scalar uses the canonical name. The protobuf enum uses the ALGORITHM_ prefix required by protobuf and Buf style.

| Slot | Canonical name | Protobuf enum constant | | ---: | --- | --- | | 1 | ED25519_PUREEDDSA_RAW_RS64_CANONICAL | ALGORITHM_ED25519_PUREEDDSA_RAW_RS64_CANONICAL | | 2 | ECDSA_SECP256R1_SHA256_RAW_RS64 | ALGORITHM_ECDSA_SECP256R1_SHA256_RAW_RS64 |

Slot 0, ALGORITHM_UNSPECIFIED, is invalid at runtime. Verifiers map it to MalformedAttemptedSigned. Signers refuse it as InvalidOrUnsupportedAlgorithm.

Per-algorithm rules live in:

• [algorithms/01-ED25519_PUREEDDSA_RAW_RS64_CANONICAL.md](./algorithms/01-ED25519_PUREEDDSA_RAW_RS64_CANONICAL.md).
• [algorithms/02-ECDSA_SECP256R1_SHA256_RAW_RS64.md](./algorithms/02-ECDSA_SECP256R1_SHA256_RAW_RS64.md).

Conformance Profiles

Verifiers advertise one inner-signature-document conformance profile.

| Profile | Inner signature-document rule | | --- | --- | | Strict | Reject unknown fields and duplicate known singular fields. | | Permissive | Accept unknown fields....