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 ¶
var ErrHeaderIntegrity = errors.New("header integrity compromised")
ErrHeaderIntegrity is the error returned when the integrity of the SIF global header is compromised.
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 ¶
NewSigner returns a Signer to add digital signature(s) to f, according to opts.
Sign requires key material be provided. OptSignWithEntity can be used for this purpose.
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, header and descriptor timestamps are set to the current time. To override this behavior, consider using OptSignWithTime or OptSignDeterministic.
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 ¶
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 ¶
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 OptSignWithEntity ¶
OptSignWithEntity specifies e as the entity to use to generate signature(s).
func OptSignWithTime ¶
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. 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 ¶
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 ¶
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 ¶
Verify performs all cryptographic verification tasks specified by v.
If key material was not provided when v was created, Verify returns an error wrapping ErrNoKeyMaterial.
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 OptVerifyWithKeyRing ¶
func OptVerifyWithKeyRing(kr openpgp.KeyRing) VerifierOpt
OptVerifyWithKeyRing sets the keyring to use for verification to kr.
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) 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