Skip to content

API

Jump to bottom
Daniele Bianco edited this page Oct 15, 2025 · 3 revisions

policy

Index

func Check 

func Check(p *[]PolicyEntry, s *statement.Statement) (err error)

Check if the claims present in a given statement are satisfying the policy requirements.

The policy array (i.e. list of per-artifact bundle requirements) is traversed to verify whether there is at least one entry matching the claims for the artifacts bundle.

The logic applied depends by the artifact category, and thus, it is defined in the corresponding artifact package.

Return error if:

  • the bundle does not met the policy requirements
  • the claim parsing fails
  • the requirement parsing fails

func Parse 

func Parse(jsonPolicy []byte) (policy *[]PolicyEntry, err error)

Parse the boot policy requirements from the serialized JSON

Return error if:

  • the parsing fails

type ArtifactRequirements

Define the required set of properties to authorize an artifact from a given category.

type ArtifactRequirements struct {
    // define the artifact category (e.g. LinuxKernel, Initrd, Dtb, ...)
    Category uint `json:"category"`

    // JSON containing the list of properties that must
    // match the claims for an artifact of this category.
    // The set of properties that are supported depends by the artifact category.
    // The JSON format should reflect the underlying structure that is defined
    // in the artifact package for the given category.
    Requirements json.RawMessage `json:"requirements"`
}

type PolicyEntry

Define the policy entry as a set of requirements to authorize a given bundle of artifacts.

type PolicyEntry struct {
    // artifact rules
    Artifacts []ArtifactRequirements `json:"artifacts"`

    // require at least a quorum of n signatures for the bundle
    Signatures SigningRequirement `json:"signatures,omitempty"`
}

type Signer

Define a trusted signer

type Signer struct {
    // human-readable signer name
    Name string `json:"name,omitempty"`

    // signer's public key
    PubKey string `json:"pub_key"`
}

type SigningRequirement

Define a signing quorum that must be satisfied to authorize the bundle

type SigningRequirement struct {
    // list of trusted signers that are participating to the quorum
    Signers []Signer `json:"signers"`

    // requires at least n signatures out of the total number of trusted signers
    Quorum uint64 `json:"quorum"`
}

transparency

Index

Constants

Supported transparency engines

const (
    Sigsum uint = iota + 0x0001
    Tessera
)

func Add 

func Add(e Engine, t uint)

Register a transparency engine

type Engine

Define high-level interface for transparency layer.

This interface abstracts the functionalities implemented by the underlying transparency engine.

type Engine interface {
    // Request to the public log the information required to assemble a
    // proof bundle.
    // The public log is identified via its origin while the information
    // from ProofBundle allow to assemble the request for the log leaf.
    // The function expects as input a ProofBundle as returned by ProofParse().
    // The function does not require any previous log status (i.e. checkpoint).
    // The latest signed tree-head is fetched from the log along with the leaf
    // inclusion proof.
    // The inclusion proof is returned as []byte where its actual
    // content depends by the chosen transparency engine.
    //
    // Return error if:
    //   - the transparency engine is configured off-line
    //   - the log key is not configured
    //   - the submitter key is not configured
    //   - the statement leaf is not present in the log
    //   - any other error is returned by the public log
    GetProof(proofBundle interface{}) ([]byte, error)

    // Parse the witness policy according with the format expected by the
    // chosen transparency engine.
    // Return error if:
    //   - the parsing of the policy fails
    ParseWitnessPolicy(wp []byte) (interface{}, error)

    // Set log and submitter keys that will be used by the transparency
    // engine to fetch, or verify, the proof.
    // Return error if:
    //    - the parsing of the public keys fails
    SetKey(logKey []string, submitKey []string) error

    // Set the witness policy for the transparency engine.
    // The function expects in input a policy as returned by ParseWitnessPolicy()
    // Return error if:
    //   - the parsing of the policy fails
    SetWitnessPolicy(wp interface{}) error

    // Reset the witness policy for the transparency engine.
    ResetWitnessPolicy()

    // Verify the proof of the log, expects an input proof bundle
    // as returned by ParseProof().
    // Return error if:
    //    - the proof verification fails
    //    - the parsing of the proof bundle fails
    //    - public keys for log, submitter or cosigners are not set
    //    - the witness signing quorum is not reached
    VerifyProof(proofBundle interface{}) error

    // Parse the probing data, and the inclusion proof (if present)
    // of a given proof bundle in JSON format, return the proof bundle
    // as expected by the given transparency engine.
    // The function also return, as second value, a JSON marshal
    // version of the parsed proof bundle.
    // Return error if the parsing fails.
    ParseProof(jsonProofBundle []byte) (interface{}, []byte, error)
}

func GetEngine 

func GetEngine(t uint) (Engine, error)

Return the registered transparency engine, if present

type ProofBundle

Define the transparency proof bundle which includes: - the bundle format (i.e. sigsum, tessera) - the logged statement (i.e. claims) - the probing data to request the inclusion proof to the log - the inclusion proof

type ProofBundle struct {
    // specify which transparency engine should be used to
    // verify this proof (i.e. Sigsum, Tessera)
    Format uint `json:"format"`

    // serialized JSON of Statement struct
    Statement []byte `json:"statement"`

    // serialized inclusion proof probing data,
    // its format depends by the chosen transparency engine
    Probe json.RawMessage `json:"probe,omitempty"`

    // inclusion proof, its format depends by the chosen
    // transparency engine
    Proof json.RawMessage `json:"proof,omitempty"`
}

statement

Index

type Artifact

Define Artifact structure as a container for claims for a given artifact

type Artifact struct {
    // type of artifact (e.g. 1: LinuxKernel, 2: Initrd, 3: Dtb, ...)
    Category uint `json:"category"`

    // JSON containing the claims for a given artifact
    // The set of claims that are supported depends by the artifact category,
    // the JSON format must reflect the underlying structure that is defined
    // in the artifact package for the given category.
    Claims json.RawMessage `json:"claims"`
}

type Signature

Signature including the signer's public key to ease the verifier while checking its validity

type Signature struct {
    // Ed25519 signer public key in OpenSSH format
    PubKey string `json:"pub_key"`

    // Ed25519 signature in hex format
    Signature string `json:"signature"`
}

type Statement

Define the statement that will be logged when releasing a new bundle of artifacts

type Statement struct {
    // human-readable title for the bundle
    Description string `json:"description,omitempty"`

    // bundle version, using Semantic Versioning 2.0.0 (see semver.org)
    Version string `json:"version,omitempty"`

    // artifact claims
    Artifacts []Artifact `json:"artifacts"`

    // statement signatures
    Signatures []Signature `json:"signatures,omitempty"`
}

func Parse 

func Parse(jsonStatement []byte) (s *Statement, err error)

Parse the logged statement which is included as serialized JSON in the proof bundle

artifact

Index

Constants

Supported artifact category UIDs

const (
    // 0x0001 - 0x7FFF reserved for boot artifacts
    LinuxKernel uint = iota + 0x0001
    Initrd
    Dtb
    UEFIBinary
    WindowsBootMgr

    // 0x8001 - 0x8FFF reserved for bios artifacts
    UEFIBIOS

    // 0x9001 - 0x9FFF reserved for generic artifacts
    CVE
)

func Add 

func Add(h Handler, c uint)

Register an artifact handler for a given category

func CheckArrayInclusion 

func CheckArrayInclusion(require []string, claim []string) (err error)

Check the inclusion of an array of claimed strings within the required one

func CheckElementInclusion 

func CheckElementInclusion(slice []string, element string) bool

Check the inclusion of a claimed string within an array of required ones

func CheckHash 

func CheckHash(requireHash string, claimHash string) (err error)

Compare claimed file hash to ensure hash requirement is met

func CheckMaxVersion 

func CheckMaxVersion(requireVersion string, claimVersion string) (err error)

Compare semantic versions to ensure maximum version requirement is met

func CheckMinTimestamp 

func CheckMinTimestamp(requireMinTimestamp string, claimTimestamp string) (err error)

Check the claimed timestamp to ensure the min timestamp requirement is met

func CheckMinVersion 

func CheckMinVersion(requireVersion string, claimVersion string) (err error)

Compare semantic versions to ensure minimum version requirement is met

func CheckStringInclude 

func CheckStringInclude(require string, claim string) (err error)

Check if string inclusion requirement is met

func CheckStringMatch 

func CheckStringMatch(require string, claim string) (err error)

Check if string matching requirement is met

func CheckStringNotInclude 

func CheckStringNotInclude(require string, claim string) (err error)

Check if string non-inclusion requirement is met

type Handler

Define a high-level interface for artifact handlers.

This interface abstracts the functionalities implemented by the underlying artifact category package.

type Handler interface {
    // Parse serialized JSON containing requirements for a given artifact
    ParseRequirements(jsonRequirements []byte) (interface{}, error)
    // Parse serialized JSON containing claims for a given artifact
    ParseClaims(jsonClaims []byte) (interface{}, error)
    // Check matching between requirements and claims for a given artifact
    Check(requirements interface{}, claims interface{}) error
}

func GetHandler 

func GetHandler(c uint) (Handler, error)

Return the registered artifact handler, if any, for a given category

Clone this wiki locally