Proposed type of image signature

image-signature.go

package main

const (
	// The supported type of image signature.
	ImageSignatureTypeAtomic string = "atomic"

	// Signature wasn't recognized or a check couldn't be performed for some reason.
	SignatureStateUnknown SignatureState = "unknown"
	// Signature didn't match particular image, given type or it couldn't be parsed.
	SignatureStateUntrusted SignatureState = "untrusted"
	// Signature matched particular image but the signing key had been revoked.
	SignatureStateRevoked SignatureState = "revoked"
	// Signature matched particular image but the signature or signing key had been expired at the time of
	// check.
	SignatureStateExpired SignatureState = "expired"
	// Signature matched particular image and the signing key was valid at the time of check.
	SignatureStateTrusted SignatureState = "trusted"

	// It couldn't be verified that the signature belongs to the image.
	SignatureForImageUnknown SignatureForImage = "unknown"
	// The signature doesn't match the image.
	SignatureForImageMismatch SignatureForImage = "mismatch"
	// The signature matches the image. IOW signature's image hash matches the name of the image.
	SignatureForImageMatch SignatureForImage = "match"
)

// SignatureState holds a result of signature's server-side check.
type SignatureState string

// SignatureForImage describes relation of the signature to the image containing it.
type SignatureForImage string

// ImageSignature holds a signature of an image.
type ImageSignature struct {
	// Describes a type of stored blob.
	Type string
	// An opaque binary string which is an image's signature.
	Content []byte
	// A time of last server-side signature check. IOW a time of the last update of SignatureState.
	Checked *unversioned.Time
	// Says whether the signature matches image object containing it.
	ForImage SignatureForImage
	// Result of the last server-side signature check performed at Checked. Filled by server.
	State SignatureState

	// Following metadata fields will be set by server if the signature content is successfully parsed and
	// the data is available.

	// Digest of manifest of the signed image (e.g. "sha256:xxxxx...").
	ImageHash string
	// A human readable string representing image's identity. It could contain company's name, a product name
	// and a version. Eligible value is image's pull specification
	// (e.g. "registry.access.redhat.com/rhel7/rhel:7.2").
	ImageIdentity string
	// Optional. Contains all the signed claims with associated values.
	SignedClaims map[string]string
	// If specified, it is the time of signature's creation.
	Created *unversioned.Time
	// If specified, it holds information about an issuer of signing certificate or key (a person or entity
	// who signed the signing certificate or key).
	IssuedBy SignatureIssuer
	// If specified, it holds information about a subject of signing certificate or key (a person or entity
	// who signed the image).
	IssuedTo SignatureSubject
}

// SignatureGenericEntity holds a generic information about a person or entity who is an issuer or a subject
// of signing certificate or key.
type SignatureGenericEntity struct {
	// Organization name.
	Organization string
	// Common name (e.g. openshift-signing-service).
	CommonName string
}

// SignatureIssuer holds information about an issuer of signing certifikate or key.
type SignatureIssuer struct {
	SignatureGenericEntity
}

// SignatureSubject holds information about a person or entity who created the signature.
type SignatureSubject struct {
	SignatureGenericEntity
	// If present, it is a fingerprint of public key belonging to the subject used to verify image signature.
	PublicKeyID string
	// If present, it is an algorithm used to hash the public key to create its ID.
	PublicKeyIDAlgorithm string
}

SignedIdentity or ImageIdentity? @smarterclayton (do notifications work here?)

SignedClaims must be optional

IssuedBy and IssuedTo might benefit from structure. common name and organization?

ImageHash I still think this should be pre-compared for match/unmatch/unknown.

ImageHash I still think this should be pre-compared for match/unmatch/unknown.

@deads2k the same question as in https://github.com/openshift/origin/pull/8371/files/e2ee2502036892b3ee92f2be36e2f3287bb7d628#r64895494: does match also mean that the hash belongs to parent?

Shall we put the SignedIdentity to SignedClaims if replaced with just a first-class enumeration field ForImage?

Linking proposed signature template https://gist.github.com/mtrmac/a39d184e25dde95012719cc0691ca074 for reference.

/cc @mtrmac

I'm still unconvinced there's a need for ForImage because the same information can be parsed from State.

I'm still unconvinced there's a need for ForImage because the same information can be parsed from State.

Make it Condition following the usual form and I think I agree with you.