cryptoutil

package
v0.0.33 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 22, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package cryptoutil provides cryptographic verification primitives for content integrity and build provenance.

It supports:

  • KMS-backed signature verification (ECDSA P-256/P-384, RSA-PSS with optional PKCS1v15 fallback)
  • Sigstore bundle parsing and verification (DSSE envelopes and blob signatures)
  • In-toto statement subject digest verification
  • Constant-time hash comparison to prevent timing side-channels
  • SHA-256 and SHA-384 hashing utilities

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeDSSEPayload

func DecodeDSSEPayload(envelope *DSSEEnvelope) ([]byte, error)

DecodeDSSEPayload base64-decodes the envelope payload.

func DecodeSignature

func DecodeSignature(envelope *DSSEEnvelope) ([]byte, error)

DecodeSignature base64-decodes the first signature from the envelope.

func HashEqual

func HashEqual(a, b string) bool

HashEqual performs constant-time comparison of two hex-encoded hashes to prevent timing attacks. It returns true if the hashes are equal.

func PAE

func PAE(payloadType string, payload []byte) []byte

PAE computes the DSSE Pre-Authentication Encoding. This is the exact byte sequence that cosign signed. Format: "DSSEv1" SP len(type) SP type SP len(body) SP body

func SHA256Hex

func SHA256Hex(data []byte) string

SHA256Hex computes the SHA-256 hash of the input data and returns it as a hex string

func SHA384Hex added in v0.0.27

func SHA384Hex(data []byte) string

SHA384Hex computes the SHA-384 hash of the input data and returns it as a hex string

func VerifySubjectDigest

func VerifySubjectDigest(statement *InTotoStatement, artifact []byte) error

VerifySubjectDigest checks that the in-toto statement's subject contains a sha256 digest matching the provided artifact bytes.

Types

type BlobVerifyResult

type BlobVerifyResult struct {
	Verified bool
	KeyHint  string
}

func VerifyBlobSignature

func VerifyBlobSignature(ctx context.Context, v *KMSVerifier, bundleJSON, artifact []byte) (*BlobVerifyResult, error)

VerifyBlobSignature verifies a cosign sign-blob bundle against the original artifact bytes using a KMSVerifier.

type DSSEEnvelope

type DSSEEnvelope struct {
	Payload     string          `json:"payload"`     // base64-encoded in-toto statement
	PayloadType string          `json:"payloadType"` // "application/vnd.in-toto+json"
	Signatures  []DSSESignature `json:"signatures"`
}

type DSSESignature

type DSSESignature struct {
	Sig string `json:"sig"` // base64-encoded signature over PAE
}

type DSSEVerifyResult

type DSSEVerifyResult struct {
	KeyHint       string // from bundle verification material
	SubjectName   string // from in-toto statement
	SubjectDigest string // sha256 from subject
	PredicateType string // "phxi.net/attestations/release/v1"
}

DSSEVerifyResult holds the outcome of a successful verification.

func VerifyReleaseDSSE

func VerifyReleaseDSSE(ctx context.Context, v *KMSVerifier, bundleJSON, artifact []byte) (*DSSEVerifyResult, error)

VerifyReleaseDSSE verifies a cosign-produced sigstore bundle against the original artifact bytes using a KMSVerifier.

type InTotoStatement

type InTotoStatement struct {
	Type          string          `json:"_type"`
	PredicateType string          `json:"predicateType"`
	Subject       []InTotoSubject `json:"subject"`
	Predicate     json.RawMessage `json:"predicate"`
}

In-toto statement (decoded from DSSE payload)

type InTotoSubject

type InTotoSubject struct {
	Name   string            `json:"name"`
	Digest map[string]string `json:"digest"`
}

type KMSVerifier

type KMSVerifier struct {

	// AllowPKCS1v15 controls whether RSA PKCS1v15 is accepted as a fallback
	// when PSS verification fails. Default false (PSS-only). Set true to
	// preserve backward compatibility with existing PKCS1v15 signatures.
	AllowPKCS1v15 bool
	// contains filtered or unexported fields
}

func NewKMSVerifier

func NewKMSVerifier(client *kms.Client, keyARN string) *KMSVerifier

func (*KMSVerifier) PublicKey

func (v *KMSVerifier) PublicKey(ctx context.Context) (crypto.PublicKey, error)

PublicKey fetches and caches the KMS public key for local verification. First call hits KMS API, subsequent calls return cached key.

func (*KMSVerifier) VerifyBlob

func (v *KMSVerifier) VerifyBlob(ctx context.Context, bundleJSON, artifact []byte) error

func (*KMSVerifier) VerifySignature

func (v *KMSVerifier) VerifySignature(ctx context.Context, message, signature []byte) error

VerifySignature fetches the public key (cached) and verifies the signature locally. Supports ECDSA (P-256/P-384) and RSA (PSS-only by default).

Key type determines the hash algorithm:

  • ECDSA P-384: SHA-384
  • ECDSA P-256: SHA-256
  • RSA: SHA-256 (PSS only; PKCS1v15 fallback when AllowPKCS1v15 is true)

type MessageDigest

type MessageDigest struct {
	Algorithm string `json:"algorithm"`
	Digest    string `json:"digest"` // base64 of the raw hash bytes
}

type MessageSignature

type MessageSignature struct {
	MessageDigest MessageDigest `json:"messageDigest"`
	Signature     string        `json:"signature"` // base64
}

Blob signature bundle format (from cosign sign-blob)

type PublicKeyRef

type PublicKeyRef struct {
	Hint string `json:"hint"`
}

type SigstoreBundle

type SigstoreBundle struct {
	MediaType            string               `json:"mediaType"`
	VerificationMaterial VerificationMaterial `json:"verificationMaterial"`
	DSSEEnvelope         *DSSEEnvelope        `json:"dsseEnvelope,omitempty"`
	MessageSignature     *MessageSignature    `json:"messageSignature,omitempty"`
}

Sigstore bundle format (cosign output)

func ParseBundle

func ParseBundle(bundleJSON []byte) (*SigstoreBundle, error)

ParseBundle parses a sigstore bundle JSON and extracts the components needed for verification.

type VerificationMaterial

type VerificationMaterial struct {
	PublicKey PublicKeyRef `json:"publicKey"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL