Signature & Verification Guide

Cryptographic signatures are central to Makoto's trust model. Starting at Level 2, all attestations must be signed to ensure authenticity and tamper-evidence. This guide covers key management, signature generation, verification, and security best practices.

Overview

Makoto uses the DSSE (Dead Simple Signing Envelope) format for signed attestations, the same format used by SLSA and in-toto. This ensures interoperability with existing software supply chain security tooling.

Signature Requirements by Level

DSSE Envelope Format

A signed Makoto attestation wraps the in-toto statement in a DSSE envelope. The envelope contains the payload (base64-encoded statement), payload type, and one or more signatures.

{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEiLC4uLn0=",
  "signatures": [
    {
      "keyid": "SHA256:abc123...",
      "sig": "MEUCIQD...base64-signature..."
    }
  ]
}

Signature Computation

The signature is computed over a PAE (Pre-Authentication Encoding) of the payload:

// PAE (Pre-Authentication Encoding)
PAE(type, payload) = "DSSEv1" + SP + LEN(type) + SP + type + SP + LEN(payload) + SP + payload

// Where SP is a space (0x20) and LEN is the ASCII decimal length
// Example:
"DSSEv1 29 application/vnd.in-toto+json 123 {\"_type\":...}"

This encoding prevents type confusion attacks where an attacker might try to get a signature for one payload type accepted as another.

Signing Key Management

Proper key management is essential for maintaining the integrity of your attestations. The approach varies significantly between L2 and L3.

# Generate private key
openssl ecparam -genkey -name prime256v1 -noout -out signing-key.pem

# Extract public key
openssl ec -in signing-key.pem -pubout -out signing-key.pub

# Compute key ID (SHA256 fingerprint of public key)
openssl ec -in signing-key.pem -pubout -outform DER | \
  openssl dgst -sha256 -binary | base64

# Sign attestation with Sigstore (using cosign)
cosign attest --type makoto --predicate attestation.json \
  --fulcio-url https://fulcio.sigstore.dev \
  --rekor-url https://rekor.sigstore.dev \
  dataset:sha256:abc123...

Signature Generation

The signature generation process creates a DSSE envelope containing the signed attestation. This section covers the step-by-step process.

Generation Steps

1. Construct the in-toto statement — Create the attestation with subject and predicate
2. Serialize to JSON — Canonicalize the JSON (sorted keys, no extra whitespace)
3. Base64 encode — Encode the serialized statement
4. Compute PAE — Pre-Authentication Encoding with payload type
5. Sign the PAE — Using ECDSA P-256 or equivalent algorithm
6. Construct envelope — Wrap payload and signature(s) in DSSE format

Example: Python Signature Generation

import json
import base64
import hashlib
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec

def sign_attestation(statement: dict, private_key) -> dict:
    # 1. Serialize statement (canonical JSON)
    payload = json.dumps(statement, sort_keys=True, separators=(',', ':'))
    payload_bytes = payload.encode('utf-8')

    # 2. Base64 encode
    payload_b64 = base64.b64encode(payload_bytes).decode('ascii')

    # 3. Compute PAE
    payload_type = "application/vnd.in-toto+json"
    pae = f"DSSEv1 {len(payload_type)} {payload_type} {len(payload_bytes)} ".encode()
    pae += payload_bytes

    # 4. Sign
    signature = private_key.sign(pae, ec.ECDSA(hashes.SHA256()))
    sig_b64 = base64.b64encode(signature).decode('ascii')

    # 5. Compute key ID
    public_der = private_key.public_key().public_bytes(...)
    key_id = "SHA256:" + hashlib.sha256(public_der).hexdigest()[:16]

    # 6. Construct envelope
    return {
        "payloadType": payload_type,
        "payload": payload_b64,
        "signatures": [{"keyid": key_id, "sig": sig_b64}]
    }

Multi-Signature Support

DSSE envelopes can contain multiple signatures, useful for scenarios requiring multi-party attestation or key rotation:

{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "...",
  "signatures": [
    {
      "keyid": "SHA256:abc123...",
      // Primary signer (data processor)
      "sig": "MEUCIQD..."
    },
    {
      "keyid": "SHA256:def456...",
      // Secondary signer (platform attestation)
      "sig": "MEQCIGx..."
    }
  ]
}

Signature Verification

Consumers must verify signatures before trusting attestation claims. Verification confirms both the cryptographic validity and the identity binding.

Verification Steps

1. Parse the DSSE envelope — Extract payload, payload type, and signatures
2. Fetch the public key — Using keyid, retrieve from trusted key registry
3. Recompute PAE — Same Pre-Authentication Encoding as signing
4. Verify cryptographic signature — Using the public key
5. Check identity policy — Verify signer is authorized for this data/pipeline

Example: Python Verification

def verify_attestation(envelope: dict, trusted_keys: dict) -> bool:
    # 1. Parse envelope
    payload_type = envelope["payloadType"]
    payload_b64 = envelope["payload"]
    payload_bytes = base64.b64decode(payload_b64)

    # 2. Recompute PAE
    pae = f"DSSEv1 {len(payload_type)} {payload_type} {len(payload_bytes)} ".encode()
    pae += payload_bytes

    # 3. Verify at least one signature
    for sig_info in envelope["signatures"]:
        key_id = sig_info["keyid"]
        signature = base64.b64decode(sig_info["sig"])

        # Fetch public key from trusted registry
        if key_id not in trusted_keys:
            continue  # Unknown key

        public_key = trusted_keys[key_id]

        try:
            public_key.verify(signature, pae, ec.ECDSA(hashes.SHA256()))
            return True  # Valid signature found
        except InvalidSignature:
            continue

    return False  # No valid signature

Trust Policies

Verification isn't just about cryptographic validity—you must also verify that the signer is authorized. Common policy patterns include:

Timestamp Authority Integration

Timestamps prove when an attestation was created, preventing backdating attacks. Makoto L2+ requires verifiable timestamps following RFC 3161.

Why Timestamps Matter

RFC 3161 Timestamp Structure

A timestamp token contains:

• Message imprint — Hash of the signed data (the DSSE signature)
• Serial number — Unique identifier from the TSA
• Generation time — When the TSA created the token
• TSA signature — The authority's signature over the token

Adding Timestamps to Attestations

{
  "payloadType": "application/vnd.in-toto+json",
  "payload": "...",
  "signatures": [
    {
      "keyid": "SHA256:abc123...",
      "sig": "MEUCIQD...",
      "timestamp": {
        "authority": "https://freetsa.org/tsr",
        "token": "MIIEpgYJKoZI...base64-encoded-rfc3161-token..."
      }
    }
  ]
}

Timestamp Authorities

Obtaining a Timestamp

# 1. Create timestamp request from signature hash
openssl ts -query -data signature.bin -sha256 -out request.tsq

# 2. Send to TSA
curl -H "Content-Type: application/timestamp-query" \
  --data-binary @request.tsq \
  https://freetsa.org/tsr -o response.tsr

# 3. Verify timestamp response
openssl ts -verify -data signature.bin -in response.tsr \
  -CAfile freetsa-cacert.pem

Security Best Practices

Follow these practices to maintain the integrity of your signing infrastructure and protect against common attack vectors.

Key Management

Signing Operations

Verification

Common Pitfalls to Avoid

Quick Reference

Algorithm Identifiers

Related Specifications

• DSSE (Dead Simple Signing Envelope) — Envelope format
• in-toto Attestation Framework — Statement format
• RFC 3161 — Timestamp protocol
• Sigstore Documentation — Keyless signing
• SLSA Verification — Related verification guidance