Deprecated: use github.com/sylabs/sif/v2 instead.
The highest tagged major version is
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()
Deprecated: this package is deprecated. Users should migrate applications to package github.com/sylabs/sif/v2/pkg/integrity.
This package is frozen and no new functionality will be added.
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.
type SignerOpt ¶
SignerOpt are used to configure s.
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).
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 ¶
VerifierOpt are used to configure v.
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 interface {
// Signature returns the ID of the signature object associated with the result.
Signature() uint32
// Signed returns the IDs of data objects that were signed.
Signed() []uint32
// Verified returns the IDs of data objects that were verified.
Verified() []uint32
// Entity returns the signing entity, or nil if the signing entity could not be determined.
Entity() *openpgp.Entity
// Error returns an error describing the reason verification failed, or nil if verification was
// successful.
Error() error
}
VerifyResult is the interface that each verification result implements.
Source Files