policy

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: May 7, 2024 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// PolicyRef defines the Git namespace used for gittuf policies.
	PolicyRef = "refs/gittuf/policy"

	// PolicyStagingRef defines the Git namespace used as a staging area when creating or updating gittuf policies.
	PolicyStagingRef = "refs/gittuf/policy-staging"

	// RootRoleName defines the expected name for the gittuf root of trust.
	RootRoleName = "root"

	// TargetsRoleName defines the expected name for the top level gittuf policy file.
	TargetsRoleName = "targets"

	// DefaultCommitMessage defines the fallback message to use when updating the policy ref if an action specific message is unavailable.
	DefaultCommitMessage = "Update policy state"
)
View Source 
const AllowRuleName = "gittuf-allow-rule"

Variables

View Source 
var (
	ErrMetadataNotFound           = errors.New("unable to find requested metadata file; has it been initialized?")
	ErrInvalidPolicyTree          = errors.New("invalid policy tree structure")
	ErrDanglingDelegationMetadata = errors.New("unreachable targets metadata found")
	ErrNotRSLEntry                = errors.New("RSL entry expected, annotation found instead")
	ErrDelegationNotFound         = errors.New("required delegation entry not found")
	ErrPolicyExists               = errors.New("cannot initialize Policy namespace as it exists already")
	ErrPolicyNotFound             = errors.New("cannot find policy")
	ErrDuplicatedRuleName         = errors.New("two rules with same name found in policy")
	ErrUnableToMatchRootKeys      = errors.New("unable to match root public keys, gittuf policy is in a broken state")
	ErrNotAncestor                = errors.New("cannot apply changes since policy is not an ancestor of the policy staging")
)
View Source 
var (
	ErrCannotMeetThreshold = errors.New("insufficient keys to meet threshold")
	ErrRootMetadataNil     = errors.New("rootMetadata is nil")
	ErrRootKeyNil          = errors.New("root key not found")
	ErrTargetsMetadataNil  = errors.New("targetsMetadata not found")
	ErrTargetsKeyNil       = errors.New("targetsKey is nil")
	ErrKeyIDEmpty          = errors.New("keyID is empty")
)
View Source 
var (
	ErrUnauthorizedSignature   = errors.New("unauthorized signature")
	ErrInvalidEntryNotSkipped  = errors.New("invalid entry found not marked as skipped")
	ErrLastGoodEntryIsSkipped  = errors.New("entry expected to be unskipped is marked as skipped")
	ErrUnknownObjectType       = errors.New("unknown object type passed to verify signature")
	ErrInvalidVerifier         = errors.New("verifier has invalid parameters (is threshold 0?)")
	ErrVerifierConditionsUnmet = errors.New("verifier's key and threshold constraints not met")
)
View Source 
var ErrCannotManipulateAllowRule = errors.New("cannot change in-built gittuf-allow-rule")

Functions

func AddDelegation added in v0.4.0 

func AddDelegation(targetsMetadata *tuf.TargetsMetadata, ruleName string, authorizedKeys []*tuf.Key, rulePatterns []string, threshold int) (*tuf.TargetsMetadata, error)

AddDelegation adds a new delegation to TargetsMetadata.

func AddKeyToTargets 

func AddKeyToTargets(targetsMetadata *tuf.TargetsMetadata, authorizedKeys []*tuf.Key) (*tuf.TargetsMetadata, error)

AddKeyToTargets adds public keys to the specified targets metadata.

func AddRootKey added in v0.3.0 

func AddRootKey(rootMetadata *tuf.RootMetadata, rootKey *tuf.Key) *tuf.RootMetadata

AddRootKey adds rootKey as a trusted public key in rootMetadata for the Root role.

func AddTargetsKey 

func AddTargetsKey(rootMetadata *tuf.RootMetadata, targetsKey *tuf.Key) (*tuf.RootMetadata, error)

AddTargetsKey adds the 'targetsKey' as a trusted public key in 'rootMetadata' for the top level Targets role.

func AllowRule 

func AllowRule() tuf.Delegation

AllowRule returns the default, last rule for all policy files.

func Apply added in v0.4.0 

func Apply(ctx context.Context, repo *git.Repository, signRSLEntry bool) error

Apply takes valid changes from the policy staging ref, and fast-forward merges it into the policy ref. Apply only takes place if the latest state on the policy staging ref is valid. This prevents invalid changes to the policy taking affect, and allowing new changes, that until signed by multiple users would be invalid to be made, by utilizing the policy staging ref.

func DeleteRootKey added in v0.3.0 

func DeleteRootKey(rootMetadata *tuf.RootMetadata, keyID string) (*tuf.RootMetadata, error)

DeleteRootKey removes keyID from the list of trusted Root public keys in rootMetadata. It does not remove the key entry itself as it does not check if other roles can be verified using the same key.

func DeleteTargetsKey 

func DeleteTargetsKey(rootMetadata *tuf.RootMetadata, keyID string) (*tuf.RootMetadata, error)

DeleteTargetsKey removes the key matching 'keyID' from trusted public keys for top level Targets role in 'rootMetadata'. Note: It doesn't remove the key entry itself as it doesn't check if other roles can use the same key.

func InitializeNamespace 

func InitializeNamespace(repo *git.Repository) error

InitializeNamespace creates a git ref for the policy. Initially, the entry has a zero hash.

func InitializeRootMetadata 

func InitializeRootMetadata(key *tuf.Key) *tuf.RootMetadata

InitializeRootMetadata initializes a new instance of tuf.RootMetadata with default values and a given key. The default values are version set to 1, expiry date set to one year from now, and the provided key is added.

func InitializeTargetsMetadata 

func InitializeTargetsMetadata() *tuf.TargetsMetadata

InitializeTargetsMetadata creates a new instance of TargetsMetadata.

func RemoveDelegation 

func RemoveDelegation(targetsMetadata *tuf.TargetsMetadata, ruleName string) (*tuf.TargetsMetadata, error)

RemoveDelegation deletes a delegation entry from TargetsMetadata.

func UpdateDelegation added in v0.4.0 

func UpdateDelegation(targetsMetadata *tuf.TargetsMetadata, ruleName string, authorizedKeys []*tuf.Key, rulePatterns []string, threshold int) (*tuf.TargetsMetadata, error)

UpdateDelegation is used to amend a delegation in TargetsMetadata.

func UpdateRootThreshold added in v0.4.0 

func UpdateRootThreshold(rootMetadata *tuf.RootMetadata, threshold int) (*tuf.RootMetadata, error)

UpdateRootThreshold sets the threshold for the Root role.

func UpdateTargetsThreshold added in v0.4.0 

func UpdateTargetsThreshold(rootMetadata *tuf.RootMetadata, threshold int) (*tuf.RootMetadata, error)

UpdateTargetsThreshold sets the threshold for the top level Targets role.

func VerifyCommit 

func VerifyCommit(ctx context.Context, repo *git.Repository, ids ...string) map[string]string

VerifyCommit verifies the signature on the specified commits (identified by their hash or via a reference that is resolved). For each commit, the policy applicable when the commit was first recorded (directly or indirectly) in the RSL is used. The function returns a map that identifies the verification status for each of the submitted IDs. All commit IDs that are passed in will have an entry in the returned status. The status is currently meant to be consumed directly by the user, as this is used for a special, user-invoked workflow. gittuf's other verification workflows are currently not expected to use this function.

func VerifyRef 

func VerifyRef(ctx context.Context, repo *git.Repository, target string) (plumbing.Hash, error)

VerifyRef verifies the signature on the latest RSL entry for the target ref using the latest policy. The expected Git ID for the ref in the latest RSL entry is returned if the policy verification is successful.

func VerifyRefFromEntry added in v0.4.0 

func VerifyRefFromEntry(ctx context.Context, repo *git.Repository, target string, entryID plumbing.Hash) (plumbing.Hash, error)

VerifyRefFromEntry performs verification for the reference from a specific RSL entry. The expected Git ID for the ref in the latest RSL entry is returned if the policy verification is successful.

func VerifyRefFull 

func VerifyRefFull(ctx context.Context, repo *git.Repository, target string) (plumbing.Hash, error)

VerifyRefFull verifies the entire RSL for the target ref from the first entry. The expected Git ID for the ref in the latest RSL entry is returned if the policy verification is successful.

func VerifyRelativeForRef 

func VerifyRelativeForRef(ctx context.Context, repo *git.Repository, initialPolicyEntry, initialAttestationsEntry, firstEntry, lastEntry *rsl.ReferenceEntry, target string) error

VerifyRelativeForRef verifies the RSL between specified start and end entries using the provided policy entry for the first entry.

TODO: should the policy entry be inferred from the specified first entry?

func VerifyTag 

func VerifyTag(ctx context.Context, repo *git.Repository, ids []string) map[string]string

VerifyTag verifies the signature on the RSL entries for the specified tags. In addition, each tag object's signature is also verified using the same set of trusted keys. If the tag is not protected by policy, then all keys in the applicable policy are used to verify the signatures.

Types

type DelegationWithDepth added in v0.3.0 

type DelegationWithDepth struct {
	Delegation tuf.Delegation
	Depth      int
}

func ListRules added in v0.3.0 

func ListRules(ctx context.Context, repo *git.Repository, targetRef string) ([]*DelegationWithDepth, error)

ListRules returns a list of all the rules as an array of the delegations in a pre order traversal of the delegation tree, with the depth of each delegation.

type State 

type State struct {
	RootEnvelope        *sslibdsse.Envelope
	TargetsEnvelope     *sslibdsse.Envelope
	DelegationEnvelopes map[string]*sslibdsse.Envelope
	RootPublicKeys      []*tuf.Key
	// contains filtered or unexported fields
}

State contains the full set of metadata and root keys present in a policy state.

func GetStateForCommit 

func GetStateForCommit(ctx context.Context, repo *git.Repository, commit *object.Commit) (*State, error)

GetStateForCommit scans the RSL to identify the first time a commit was seen in the repository. The policy preceding that RSL entry is returned as the State to be used for verifying the commit's signature. If the commit hasn't been seen in the repository previously, no policy state is returned. Also, no error is returned. Identifying the policy in this case is left to the calling workflow.

func LoadCurrentState 

func LoadCurrentState(ctx context.Context, repo *git.Repository, ref string) (*State, error)

LoadCurrentState returns the State corresponding to the repository's current active policy. It verifies the root of trust for the state starting from the initial policy entry in the RSL.

func LoadState 

func LoadState(ctx context.Context, repo *git.Repository, entry *rsl.ReferenceEntry) (*State, error)

LoadState returns the State of the repository's policy corresponding to the entry. It verifies the root of trust for the state from the initial policy entry in the RSL. If no policy states are found and the entry is for the policy-staging ref, that entry is returned with no verification.

func (*State) Commit 

func (s *State) Commit(repo *git.Repository, commitMessage string, signCommit bool) error

Commit verifies and writes the State to the policy-staging namespace. It also creates an RSL entry recording the new tip of the policy-staging namespace.

func (*State) FindPublicKeysForPath deprecated 

func (s *State) FindPublicKeysForPath(ctx context.Context, path string) ([]*tuf.Key, error)

FindPublicKeysForPath identifies the trusted keys for the path. If the path protected in gittuf policy, the trusted keys are returned.

Deprecated: use FindVerifiersForPath.

func (*State) FindVerifiersForPath added in v0.2.0 

func (s *State) FindVerifiersForPath(path string) ([]*Verifier, error)

FindVerifiersForPath identifies the trusted set of verifiers for the specified path. While walking the delegation graph for the path, signatures for delegated metadata files are verified using the verifier context.

func (*State) GetRootKeys added in v0.4.0 

func (s *State) GetRootKeys() ([]*tuf.Key, error)

func (*State) GetRootMetadata 

func (s *State) GetRootMetadata() (*tuf.RootMetadata, error)

GetRootMetadata returns the deserialized payload of the State's RootEnvelope.

func (*State) GetTargetsMetadata 

func (s *State) GetTargetsMetadata(roleName string) (*tuf.TargetsMetadata, error)

func (*State) HasRuleName added in v0.4.0 

func (s *State) HasRuleName(name string) bool

func (*State) HasTargetsRole 

func (s *State) HasTargetsRole(roleName string) bool

func (*State) PublicKeys 

func (s *State) PublicKeys() (map[string]*tuf.Key, error)

PublicKeys returns all the public keys associated with a state.

func (*State) Verify 

func (s *State) Verify(ctx context.Context) error

Verify verifies the contents of the State for internal consistency. Specifically, it checks that the root keys in the root role match the ones stored on disk in the state. Further, it also verifies the signatures of the top level Targets role and all reachable delegated Targets roles. Any unreachable role returns an error.

func (*State) VerifyNewState 

func (s *State) VerifyNewState(ctx context.Context, newPolicy *State) error

VerifyNewState ensures that when a new policy is encountered, its root role is signed by keys trusted in the current policy.

type Verifier added in v0.2.0 

type Verifier struct {
	// contains filtered or unexported fields
}

func (*Verifier) Keys added in v0.2.0 

func (v *Verifier) Keys() []*tuf.Key

func (*Verifier) Name added in v0.2.0 

func (v *Verifier) Name() string

func (*Verifier) Threshold added in v0.2.0 

func (v *Verifier) Threshold() int

func (*Verifier) Verify added in v0.2.0 

func (v *Verifier) Verify(ctx context.Context, gitObject object.Object, env *sslibdsse.Envelope) error

Verify is used to check for a threshold of signatures using the verifier. The threshold of signatures may be met using a combination of at most one Git signature and signatures embedded in a DSSE envelope. Verify does not inspect the envelope's payload, but instead only verifies the signatures. The caller must ensure the validity of the envelope's contents.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.