witness

README

go-witness

A client library for Witness, written in Go.

Status

This library is currently pre-1.0 and therefore the API may be subject to breaking changes.

Features

• Creation and signing of in-toto attestations
• Verification of in-toto attestations and associated signatures with:
  • Witness policy engine
  • OPA Rego policy language
• A growing list of attestor types defined under a common interface
• A selection of attestation sources to search for attestation collections

Documentation

For more detail regarding the library itself, we recommend viewing pkg.go.dev. For the documentation of the witness project, please view the main witness repository.

Requirements

In order to effectively contribute to this library, you will need:

• A Unix-compatible Operating System
• GNU Make
• Go 1.19

Running Tests

This repository uses Go tests for testing. You can run these tests by executing make test.

Documentation

Index

• func Sign(r io.Reader, dataType string, w io.Writer, opts ...dsse.SignOption) error
• func VerifySignature(r io.Reader, verifiers ...cryptoutil.Verifier) (dsse.Envelope, error)
• type RunOption
  • func RunWithAttestationOpts(opts ...attestation.AttestationContextOption) RunOption
  • func RunWithAttestors(attestors []attestation.Attestor) RunOption
  • func RunWithInsecure(insecure bool) RunOption
  • func RunWithSigners(signers ...cryptoutil.Signer) RunOption
  • func RunWithTimestampers(ts ...timestamp.Timestamper) RunOption
• type RunResult
  • func Run(stepName string, opts ...RunOption) (RunResult, error)
  • func RunWithExports(stepName string, opts ...RunOption) ([]RunResult, error)
• type VerifyOption
  • func VerifyWithAttestorOptions(opts ...policyverify.Option) VerifyOption
  • func VerifyWithCollectionSource(source source.Sourcer) VerifyOption
  • func VerifyWithPolicyCAIntermediates(certs []*x509.Certificate) VerifyOption
  • func VerifyWithPolicyCARoots(certs []*x509.Certificate) VerifyOption
  • func VerifyWithPolicyCertConstraints(commonName string, dnsNames []string, emails []string, organizations []string, ...) VerifyOption
  • func VerifyWithPolicyFulcioCertExtensions(extensions certificate.Extensions) VerifyOption
  • func VerifyWithPolicyTimestampAuthorities(verifiers []timestamp.TimestampVerifier) VerifyOption
  • func VerifyWithRunOptions(opts ...RunOption) VerifyOption
  • func VerifyWithSigners(signers ...cryptoutil.Signer) VerifyOption
  • func VerifyWithSubjectDigests(subjectDigests []cryptoutil.DigestSet) VerifyOption
• type VerifyResult
  • func Verify(ctx context.Context, policyEnvelope dsse.Envelope, ...) (VerifyResult, error)

Functions

func Sign

func Sign(r io.Reader, dataType string, w io.Writer, opts ...dsse.SignOption) error

func VerifySignature

func VerifySignature(r io.Reader, verifiers ...cryptoutil.Verifier) (dsse.Envelope, error)

Types

type RunOption

type RunOption func(ro *runOptions)

func RunWithAttestationOpts

func RunWithAttestationOpts(opts ...attestation.AttestationContextOption) RunOption

RunWithAttestationOpts takes in any AttestationContextOptions and forwards them to the context that Run creates

func RunWithAttestors

func RunWithAttestors(attestors []attestation.Attestor) RunOption

RunWithAttestors defines which attestors should be run and added to the resulting AttestationCollection

func RunWithInsecure

func RunWithInsecure(insecure bool) RunOption

RunWithInsecure will allow attestations to be generated unsigned. If insecure is true, RunResult will not contain a signed DSSE envelope

func RunWithSigners

func RunWithSigners(signers ...cryptoutil.Signer) RunOption

RunWithSigners configures the signers that will be used to sign the DSSE envelope containing the generated attestation collection.

func RunWithTimestampers

func RunWithTimestampers(ts ...timestamp.Timestamper) RunOption

RunWithTimestampers will timestamp any signatures created on the DSSE time envelope with the provided timestampers

type RunResult

type RunResult struct {
	Collection     attestation.Collection
	SignedEnvelope dsse.Envelope
	AttestorName   string
}

RunResult contains the generated attestation collection as well as the signed DSSE envelope, if one was created.

func Run

func Run(stepName string, opts ...RunOption) (RunResult, error)

Deprecated: Use RunWithExports instead

func RunWithExports

func RunWithExports(stepName string, opts ...RunOption) ([]RunResult, error)

type VerifyOption

type VerifyOption func(*verifyOptions)

func VerifyWithAttestorOptions

func VerifyWithAttestorOptions(opts ...policyverify.Option) VerifyOption

VerifyWithAttestorOptions forwards the provided options to the policyverify attestor.

func VerifyWithCollectionSource

func VerifyWithCollectionSource(source source.Sourcer) VerifyOption

VerifyWithCollectionSource configures the policy engine's sources for signed attestation collections. For example: disk or archivista are two typical sources.

func VerifyWithPolicyCAIntermediates

func VerifyWithPolicyCAIntermediates(certs []*x509.Certificate) VerifyOption

func VerifyWithPolicyCARoots

func VerifyWithPolicyCARoots(certs []*x509.Certificate) VerifyOption

func VerifyWithPolicyCertConstraints

func VerifyWithPolicyCertConstraints(commonName string, dnsNames []string, emails []string, organizations []string, uris []string) VerifyOption

func VerifyWithPolicyFulcioCertExtensions

func VerifyWithPolicyFulcioCertExtensions(extensions certificate.Extensions) VerifyOption

func VerifyWithPolicyTimestampAuthorities

func VerifyWithPolicyTimestampAuthorities(verifiers []timestamp.TimestampVerifier) VerifyOption

func VerifyWithRunOptions

func VerifyWithRunOptions(opts ...RunOption) VerifyOption

VerifyWithRunOptions forwards the provided RunOptions to the Run function that Verify calls.

func VerifyWithSigners

func VerifyWithSigners(signers ...cryptoutil.Signer) VerifyOption

VerifyWithSigners will configure the provided signers to be used to sign a DSSE envelope with the resulting policyverify attestor. See VerifyWithRunOptions for additional options.

func VerifyWithSubjectDigests

func VerifyWithSubjectDigests(subjectDigests []cryptoutil.DigestSet) VerifyOption

VerifyWithSubjectDigests configured the "seed" subject digests to start evaluating a policy. This is typically the digest of the software artifact or some other identifying digest.

type VerifyResult

type VerifyResult struct {
	RunResult
	VerificationSummary slsa.VerificationSummary
	StepResults         map[string]policy.StepResult
}

func Verify

func Verify(ctx context.Context, policyEnvelope dsse.Envelope, policyVerifiers []cryptoutil.Verifier, opts ...VerifyOption) (VerifyResult, error)

Verify verifies a set of attestations against a provided policy. The set of attestations that satisfy the policy will be returned if verifiation is successful.