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 ¶
- func DecodeDSSEPayload(envelope *DSSEEnvelope) ([]byte, error)
- func DecodeSignature(envelope *DSSEEnvelope) ([]byte, error)
- func HashEqual(a, b string) bool
- func PAE(payloadType string, payload []byte) []byte
- func SHA256Hex(data []byte) string
- func SHA384Hex(data []byte) string
- func VerifySubjectDigest(statement *InTotoStatement, artifact []byte) error
- type BlobVerifyResult
- type DSSEEnvelope
- type DSSESignature
- type DSSEVerifyResult
- type InTotoStatement
- type InTotoSubject
- type KMSVerifier
- type MessageDigest
- type MessageSignature
- type PublicKeyRef
- type SigstoreBundle
- type VerificationMaterial
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 ¶
HashEqual performs constant-time comparison of two hex-encoded hashes to prevent timing attacks. It returns true if the hashes are equal.
func PAE ¶
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 ¶
SHA256Hex computes the SHA-256 hash of the input data and returns it as a hex string
func SHA384Hex ¶ added in v0.0.27
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 ¶
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 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 ¶
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 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"`
}