integrity

package
v2.11.1 Latest Latest
Warning

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

 Go to latest Published: Mar 20, 2023 License: BSD-3-Clause Imports: 18 Imported by: 0

Documentation

Overview

Package integrity implements functions to add, examine, and verify digital signatures in a SIF image.

Sign

To add one or more digital signatures to a SIF, create a Signer, and supply a signing PGP entity: 

s, err := integrity.NewSigner(f, OptSignWithEntity(e))

By default, the returned Signer will add one digital signature per group of objects in f. To override this behavior, supply additional options. For example, to apply a signature to object group 1 only: 

s, err := integrity.NewSigner(f, OptSignWithEntity(e), OptSignGroup(1))

Finally, to apply the signature(s): 

err := s.Sign()

Verify

To examine and/or verify digital signatures in a SIF, create a Verifier: 

v, err := NewVerifier(f)

If you intend to perform cryptographic verification, you must provide a source of key material: 

v, err := NewVerifier(f, OptVerifyWithKeyRing(kr))

By default, the returned Verifier will consider non-legacy signatures for all object groups. To override this behavior, supply additional options. For example, to consider non-legacy signatures on object group 1 only: 

v, err := NewVerifier(f, OptVerifyWithKeyRing(kr), OptVerifyGroup(1))

Finally, to perform cryptographic verification: 

err := v.Verify()

Index

Constants

This section is empty.

Variables

View Source 
var ErrHeaderIntegrity = errors.New("header integrity compromised")

ErrHeaderIntegrity is the error returned when the integrity of the SIF global header is compromised.

View Source 
var ErrNoKeyMaterial = errors.New("key material not provided")

ErrNoKeyMaterial is the error returned when no key material was provided.

Functions

This section is empty.

Types

type DescriptorIntegrityError 

type DescriptorIntegrityError struct {
	ID uint32 // Data object ID.
}

DescriptorIntegrityError records an error in cryptographic verification of a data object descriptor.

func (*DescriptorIntegrityError) Error 

func (e *DescriptorIntegrityError) Error() string

func (*DescriptorIntegrityError) Is 

func (e *DescriptorIntegrityError) Is(target error) bool

Is compares e against target. If target is a DescriptorIntegrityError and matches e or target has a zero value ID, true is returned.

type ObjectIntegrityError 

type ObjectIntegrityError struct {
	ID uint32 // Data object ID.
}

ObjectIntegrityError records an error in cryptographic verification of a data object.

func (*ObjectIntegrityError) Error 

func (e *ObjectIntegrityError) Error() string

func (*ObjectIntegrityError) Is 

func (e *ObjectIntegrityError) Is(target error) bool

Is compares e against target. If target is a ObjectIntegrityError and matches e or target has a zero value ID, true is returned.

type SignatureNotFoundError 

type SignatureNotFoundError struct {
	ID      uint32 // ID of the object/group for which signature was not found.
	IsGroup bool   // If true, ID is a group ID. Otherwise, ID is an object ID.
}

SignatureNotFoundError records an error attempting to locate one or more signatures for a data object or data object group.

func (*SignatureNotFoundError) Error 

func (e *SignatureNotFoundError) Error() string

func (*SignatureNotFoundError) Is 

func (e *SignatureNotFoundError) Is(target error) bool

Is compares e against target. If target is a SignatureNotFoundError and matches e or target has a zero value ID, true is returned.

type SignatureNotValidError 

type SignatureNotValidError struct {
	ID  uint32 // Signature object ID.
	Err error  // Wrapped error.
}

SignatureNotValidError records an error when an invalid signature is encountered.

func (*SignatureNotValidError) Error 

func (e *SignatureNotValidError) Error() string

func (*SignatureNotValidError) Is 

func (e *SignatureNotValidError) Is(target error) bool

Is compares e against target. If target is a SignatureNotValidError and matches e or target has a zero value ID, true is returned.

func (*SignatureNotValidError) Unwrap 

func (e *SignatureNotValidError) Unwrap() error

type Signer 

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

Signer describes a SIF image signer.

func NewSigner 

func NewSigner(f *sif.FileImage, opts ...SignerOpt) (*Signer, error)

NewSigner returns a Signer to add digital signature(s) to f, according to opts. Key material must be provided, or an error wrapping ErrNoKeyMaterial is returned.

To provide key material, consider using OptSignWithSigner or OptSignWithEntity.

By default, one digital signature is added per object group in f. To override this behavior, consider using OptSignGroup and/or OptSignObjects.

By default, signature timestamps are set to the current time. To override this behavior, consider using OptSignWithTime.

By default, header and descriptor timestamps are set to the current time for non-deterministic images, and unset otherwise. To override this behavior, consider using OptSignWithTime or OptSignDeterministic.

func (*Signer) Sign 

func (s *Signer) Sign() error

Sign adds digital signatures as specified by s.

type SignerOpt 

type SignerOpt func(so *signOpts) error

SignerOpt are used to configure so.

func OptSignDeterministic added in v2.3.1 

func OptSignDeterministic() SignerOpt

OptSignDeterministic sets SIF header/descriptor fields to values that support deterministic modification of images. This does not affect the signature timestamps; to specify deterministic signature timestamps, use OptSignWithTime.

func OptSignGroup 

func OptSignGroup(groupID uint32) SignerOpt

OptSignGroup specifies that a signature be applied to cover all objects in the group with the specified groupID. This may be called multiple times to add multiple group signatures.

func OptSignObjects 

func OptSignObjects(ids ...uint32) SignerOpt

OptSignObjects specifies that one or more signature(s) be applied to cover objects with the specified ids. One signature will be applied for each group ID associated with the object(s). This may be called multiple times to add multiple signatures.

func OptSignWithContext added in v2.10.0 

func OptSignWithContext(ctx context.Context) SignerOpt

OptSignWithContext specifies that the given context should be used in RPC to external services.

func OptSignWithEntity 

func OptSignWithEntity(e *openpgp.Entity) SignerOpt

OptSignWithEntity specifies e as the entity to use to generate signature(s).

func OptSignWithSigner added in v2.9.0 

func OptSignWithSigner(ss ...signature.Signer) SignerOpt

OptSignWithSigner specifies signer(s) to use to generate signature(s).

func OptSignWithTime 

func OptSignWithTime(fn func() time.Time) SignerOpt

OptSignWithTime specifies fn as the func to obtain signature timestamp(s). Unless OptSignDeterministic is supplied, fn is also used to set SIF timestamps.

type Verifier 

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

Verifier describes a SIF image verifier.

func NewVerifier 

func NewVerifier(f *sif.FileImage, opts ...VerifierOpt) (*Verifier, error)

NewVerifier returns a Verifier to examine and/or verify digital signatures(s) in f according to opts.

Verify requires key material be provided. OptVerifyWithVerifier and/or OptVerifyWithKeyRing can be used for this purpose. Key material is not required for routines that do not perform cryptographic verification, such as AnySignedBy or AllSignedBy.

By default, the returned Verifier will consider non-legacy signatures for all object groups. To override this behavior, consider using OptVerifyGroup, OptVerifyObject, OptVerifyLegacy, and/or OptVerifyLegacyAll.

func (*Verifier) AllSignedBy 

func (v *Verifier) AllSignedBy() ([][]byte, error)

AllSignedBy returns fingerprints for entities that have signed all of the objects specified by verification tasks in v.

Note that this routine does not perform cryptograhic validation. To ensure the image contains cryptographically valid signatures, use Verify.

func (*Verifier) AnySignedBy 

func (v *Verifier) AnySignedBy() ([][]byte, error)

AnySignedBy returns fingerprints for entities that have signed any of the objects specified by verification tasks in v.

Note that this routine does not perform cryptograhic validation. To ensure the image contains cryptographically valid signatures, use Verify.

func (*Verifier) Verify 

func (v *Verifier) Verify() error

Verify performs all cryptographic verification tasks specified by v.

If appropriate key material was not provided when v was created, Verify returns an error.

If no signatures are found for a task specified by v, an error wrapping a SignatureNotFoundError is returned. If an invalid signature is encountered, an error wrapping a SignatureNotValidError is returned.

If verification of the SIF global header fails, an error wrapping ErrHeaderIntegrity is returned. If verification of a data object descriptor fails, an error wrapping a DescriptorIntegrityError is returned. If verification of a data object fails, an error wrapping a ObjectIntegrityError is returned.

type VerifierOpt 

type VerifierOpt func(vo *verifyOpts) error

VerifierOpt are used to configure vo.

func OptVerifyCallback 

func OptVerifyCallback(cb VerifyCallback) VerifierOpt

OptVerifyCallback registers cb as the verification callback, which is called after each signature is verified.

func OptVerifyGroup 

func OptVerifyGroup(groupID uint32) VerifierOpt

OptVerifyGroup adds a verification task for the group with the specified groupID. This may be called multliple times to request verification of more than one group.

func OptVerifyLegacy 

func OptVerifyLegacy() VerifierOpt

OptVerifyLegacy enables verification of legacy signatures. Non-legacy signatures will not be considered.

Note that legacy signatures do not provide integrity protection of metadata contained in the global header or object descriptors. For the best security, use of non-legacy signatures is required.

func OptVerifyLegacyAll 

func OptVerifyLegacyAll() VerifierOpt

OptVerifyLegacyAll enables verification of legacy signatures, and adds verification tasks for all non-signature objects that are part of a group. Non-legacy signatures will not be considered.

Note that legacy signatures do not provide integrity protection of metadata contained in the global header or object descriptors. For the best security, use of non-legacy signatures is required.

func OptVerifyObject 

func OptVerifyObject(id uint32) VerifierOpt

OptVerifyObject adds a verification task for the object with the specified id. This may be called multliple times to request verification of more than one object.

func OptVerifyWithContext added in v2.10.0 

func OptVerifyWithContext(ctx context.Context) VerifierOpt

OptVerifyWithContext specifies that the given context should be used in RPC to external services.

func OptVerifyWithKeyRing 

func OptVerifyWithKeyRing(kr openpgp.KeyRing) VerifierOpt

OptVerifyWithKeyRing sets the keyring to use for verification to kr.

func OptVerifyWithVerifier added in v2.9.0 

func OptVerifyWithVerifier(vs ...signature.Verifier) VerifierOpt

OptVerifyWithVerifier appends verifier(s) to the sources of key material used for verification.

type VerifyCallback 

type VerifyCallback func(r VerifyResult) (ignoreError bool)

VerifyCallback is called immediately after a signature is verified. If r contains a non-nil error, and the callback returns true, the error is ignored, and verification proceeds as if no error occurred.

type VerifyResult 

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

VerifyResult describes the results of an individual signature validation.

func (VerifyResult) Entity 

func (r VerifyResult) Entity() *openpgp.Entity

Entity returns the signing entity, or nil if the signing entity could not be determined.

func (VerifyResult) Error 

func (r VerifyResult) Error() error

Error returns an error describing the reason verification failed, or nil if verification was successful.

func (VerifyResult) Keys added in v2.9.0 

func (r VerifyResult) Keys() []crypto.PublicKey

Keys returns the public key(s) used to verify the signature.

func (VerifyResult) Signature 

func (r VerifyResult) Signature() sif.Descriptor

Signature returns the signature object associated with the result.

func (VerifyResult) Verified 

func (r VerifyResult) Verified() []sif.Descriptor

Verified returns the data objects that were verified.

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.