Documentation
¶
Overview ¶
Package attest wraps a prove document (see cmd/corvint/prove.go and docs/specs/falsifiable-packet-v0.md, requirement FPK-V0-012) as an in-toto Statement v1 (https://in-toto.io/Statement/v1), and signs that statement inside a DSSE envelope (https://github.com/secure-systems-lab/dsse) so an external gate can consume it.
Index ¶
- Constants
- Variables
- func CEMStatement(name string, cem []byte) ([]byte, error)
- func CEMStatementV1(name string, cem []byte) ([]byte, error)
- func Envelope(statement []byte, privateKey ed25519.PrivateKey) ([]byte, error)
- func ReadPrivateKey(path string) (ed25519.PrivateKey, error)
- func ReadPublicKey(path string) (ed25519.PublicKey, error)
- func Statement(proveDocument []byte, subjects []Subject) ([]byte, error)
- func Verify(envelope []byte, publicKey ed25519.PublicKey) ([]byte, error)
- type CEMVerification
- type Subject
Constants ¶
const ( CEMVerified = "VERIFIED" CEMNotRun = "NOT_RUN" )
CEM verification statuses. NOT_RUN means the envelope and the signed claim verified but no CEM bytes were supplied, so the map itself was not checked.
const CEMPredicateType = "https://corvint-context.dev/attestation/cem/0"
CEMPredicateType is the in-toto predicateType URI for an attestation about one Change Evidence Map (docs/specs/falsifiable-packet-v0.md, FPK-V0-030, experimental prototype).
const CEMPredicateTypeV1 = "https://corvint-context.dev/attestation/cem/v1"
CEMPredicateTypeV1 is the versioned in-toto predicateType URI for an attestation about one Change Evidence Map (docs/specs/falsifiable-packet-v0.md, FPK-V0-033, experimental prototype). Its predicate names the map as an in-toto ResourceDescriptor and also binds the base revision and patch the map covers; CEMPredicateType is unchanged.
const PredicateType = "https://corvint-context.dev/attestation/falsifiable-packet/0"
PredicateType is the in-toto predicateType URI for a falsifiable-packet/0 proof document.
Variables ¶
var ErrCEMBytesMismatch = errors.New("attest: CEM bytes do not match the attested claim")
ErrCEMBytesMismatch is wrapped by the VerifyCEM error for supplied CEM bytes whose sha256 or size differ from the signed claim, so a caller can tell a changed map from an envelope that does not verify.
Functions ¶
func CEMStatement ¶
CEMStatement builds an in-toto Statement v1 whose single subject is the CEM at name with the sha256 of cem, and whose predicate is a content-addressed reference to that map: name, sha256 digest, byte size, and CEM spec. The map bytes are not embedded. It returns canonical JSON as Statement does, and rejects an empty name or bytes that wire.ParseMap does not accept.
func CEMStatementV1 ¶ added in v0.7.0
CEMStatementV1 builds the canonical in-toto Statement v1 of FPK-V0-033: the subject CEMStatement writes, and the predicate {"base":{"digest":{"gitCommit":OID}},"cem":{"digest":{"sha256":HEX},"name":NAME}, "patch":{"digest":{"sha256":HEX}},"size":BYTES,"spec":SPEC}, with base and patch read from the map. It refuses what CEMStatement refuses.
func Envelope ¶
func Envelope(statement []byte, privateKey ed25519.PrivateKey) ([]byte, error)
Envelope wraps statement in a DSSE envelope, signed with Ed25519 over the DSSE pre-authentication encoding (PAE) of (payloadType, statement). The envelope's payloadType is fixed at "application/vnd.in-toto+json". keyid is the lowercase hex sha256 of the raw Ed25519 public key bytes.
func ReadPrivateKey ¶
func ReadPrivateKey(path string) (ed25519.PrivateKey, error)
ReadPrivateKey reads an Ed25519 private key from the PEM file at path. The file must contain a single PKCS#8 "PRIVATE KEY" block, the format `openssl genpkey -algorithm ed25519` produces. ReadPrivateKey never writes to path, and rejects any file larger than 16 KiB or any key type other than Ed25519.
func ReadPublicKey ¶
ReadPublicKey reads an Ed25519 public key from the PEM file at path under the same bounds as ReadPrivateKey: a single PKIX "PUBLIC KEY" block, the format `openssl pkey -pubout` produces, in a file of at most 16 KiB.
func Statement ¶
Statement builds an in-toto Statement v1 whose predicate is proveDocument parsed as JSON, and whose predicateType is PredicateType. It returns canonical JSON: object keys sorted at every level (plain byte order), no insignificant whitespace, UTF-8, and no trailing newline.
Statement rejects a proveDocument that does not parse as JSON, is not a JSON object, does not have "profile":"falsifiable-packet/0", or does not carry a non-empty string "revision". It also rejects a repeated member name at any depth and invalid UTF-8, which the decoder would resolve last-wins or replace with U+FFFD, so the predicate would not be the document unchanged.
func Verify ¶
Verify checks a DSSE envelope's single signature against publicKey and returns the statement payload. It rejects: a public key that is not 32 bytes; a payloadType other than "application/vnd.in-toto+json"; zero or multiple signatures; a keyid that does not match the lowercase hex sha256 of publicKey; payload or signature bytes that are not valid base64; a signature that does not verify; any envelope member other than payload, payloadType, and signatures; and, in the envelope or its signature object, a repeated member name or one that differs from a defined member name only in case.
Types ¶
type CEMVerification ¶
type CEMVerification struct {
Name string
SHA256 string
Size int64
Spec string
Status string
Reason string
// PredicateType is set by VerifyCEMPredicate only; BaseRevision and
// PatchSHA256 only for a CEMPredicateTypeV1 claim.
PredicateType string
BaseRevision string
PatchSHA256 string
}
CEMVerification is what VerifyCEM established about a signed CEM claim.
func VerifyCEM ¶
VerifyCEM verifies envelope with Verify, requires its statement to be a CEMStatement whose subject and predicate agree, and then checks cem against the signed digest and size. A nil cem is not a failure: the claim is returned with Status NOT_RUN so the caller cannot mistake it for a checked map. A non-nil cem, including an empty one, that does not match is refused.
func VerifyCEMPredicate ¶ added in v0.7.0
func VerifyCEMPredicate(envelope []byte, publicKey ed25519.PublicKey, cem []byte) (CEMVerification, error)
VerifyCEMPredicate is VerifyCEM for a statement of either CEMPredicateType or CEMPredicateTypeV1, reporting which in PredicateType. For a v1 claim the supplied bytes must also be a CEM whose baseRevision and patchSha256 equal the signed ones.
Source Files