README
¶
Attestation Library
The Attestation Library provides an interface for creating and verifying Attestations through a Signer and a Verifier, respectively.
Components
Attestation
An Attestation is a signed statement about a container image in a known format. A container is allowed to be deployed to a Kubernetes cluster if it presents Attestations that satisfy the cluster's policy. An Attestation contains a payload and a signature generated over the payload with a trusted entity’s private key. It also contains the ID of the public key which can verify the Attestation’s signature.
Public Key
A PublicKey is the definitive trust anchor used to verify that an Attestation’s signature is valid. Unlike Attestations, which are considered untrustworthy until verified, PublicKeys are assumed to contain trustworthy information. Consequently, this information should be provided directly by the trusted party.
A PublicKey contains the raw public key material and an ID. It also contains a KeyType, one of {Pgp, Pkix, or Jwt}, indicating how the trusted entity stores data within the Attestation. It also contains a SignatureAlgorithm, indicating the cryptographic algorithm, padding algorithm, and hash function used on the payload to create the signature in the Attestation.
Private Key
The trusted entity has a private key, which is used by the Signer to generate an Attestation’s signature.
Payload
The payload is a message provided by the trusted entity regarding a container image. It is signed by their private key to create a signature, and both the signature and payload are stored in the Attestation. A payload should not be trusted until the Verifier has verified the Attestation's signature. The Verifier will also assert that the payload describes image being deployed.
By convention, the payload is a JSON-encoded string conforming to the Red Hat Atomic Host signature format.
Interface
Signing
Signer
A trusted entity will use a Signer to generate Attestations. There are three signer implementations, one for each KeyType: a PgpSigner, PkixSigner, and a JwtSigner. Each signer has its own constructor (e.g. NewPgpSigner), which creates a Signer storing the trusted entity’s private key and any other data required to create an Attestation.
Each signer implements the Signer interface: the CreateAttestation method. When passed a payload to sign over, CreateAttestation will generate and return an Attestation containing the signature.
Verifying
PublicKey
To create a PublicKey, the user can call NewPublicKey, passing in the public key material, key ID, KeyType, and any other data necessary to verify an Attestation.
Verifier
Anyone who wishes to verify an Attestation will use a Verifier. There is a single verifier implementation, which is capable of verifying any type of Attestation. It has a constructor NewVerifier which receives a slice of PublicKeys that will be used to verify an Attestation and the image name that the Attestations should be associated with.
The verifier satisfies the Verifier interface: the VerifyAttestation method. When passed an Attestation, it checks that the Attestation’s signature can be verified by any of the verifier’s public keys. It also extracts the payload used to generate the signature and checks that it corresponds with the given image. If either step is unsuccessful, it returns an error.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Attestation ¶
type Attestation struct {
// PublicKeyID is the ID of the public key that can verify the Attestation.
PublicKeyID string
// Signature stores the signature content for the Attestation. For PKIX,
// this is only the raw signature. For PGP, this is an attached signature,
// containing both the signature and message payload. For JWT, this is a
// signed and serialized JWT.
Signature []byte
// SerializedPayload stores the payload over which the signature was
// signed. This field is only used for PKIX Attestations.
SerializedPayload []byte
}
Attestation represents an unauthenticated attestation, stripped of information specific to the wire format. An Attestation can only be trusted after successfully verifying its Signature.
Each Attestation contains one signature. It can store signatures generated by PGP or PKIX keys, or it can store an attestation represented as a JWT.
type AuthenticatorType ¶
type AuthenticatorType int
AuthenticatorType specifies the transport format of the Attestation. It indicates to the Verifier how to extract the appropriate information out of an Attestation.
const ( UnknownAuthenticatorType AuthenticatorType = iota Pgp Pkix Jwt )
Enumeration of AuthenticatorType
type PublicKey ¶
type PublicKey struct {
// AuthenticatorType indicates the transport format of the Attestation this
// key verifies, one of Pgp, Pkix, or Jwt.
AuthenticatorType AuthenticatorType
// Signature Algorithm holds the signing and padding algorithm for the signature.
SignatureAlgorithm SignatureAlgorithm
// KeyData holds the raw key material which can verify a signature.
KeyData []byte
// ID uniquely identifies this public key. For PGP, this should be the
// OpenPGP RFC4880 V4 fingerprint of the key. For PKIX and JWT, this should
// be a StringOrURI: it must either not contain ":" or be a valid URI.
ID string
}
PublicKey stores public key material for all key types.
func NewPublicKey ¶
func NewPublicKey(authenticatorType AuthenticatorType, signatureAlgorithm SignatureAlgorithm, keyData []byte, keyID string) (*PublicKey, error)
NewPublicKey creates a new PublicKey. `authenticatorType` indicates the transport format of the Attestation this PublicKey verifies, one of Pgp, Pkix or Jwt. `keyData` contains the raw key material. `keyID` contains a unique identifier for the public key. For PGP, this field should be left blank. The ID will be the OpenPGP RFC4880 V4 fingerprint of the key. For PKIX and JWT, this may be left blank, and the ID will be generated based on the DER encoding of the key. If not blank, the ID should be a StringOrURI: it must either not contain ":" or be a valid URI.
type SignatureAlgorithm ¶
type SignatureAlgorithm int
SignatureAlgorithm specifies the algorithm and hashing functions used to sign PKIX and JWT Attestations.
const ( UnknownSigningAlgorithm SignatureAlgorithm = iota // RSASSA-PSS 2048 bit key with a SHA256 digest. RsaPss2048Sha256 // RSASSA-PSS 3072 bit key with a SHA256 digest. RsaPss3072Sha256 // RSASSA-PSS 4096 bit key with a SHA256 digest. RsaPss4096Sha256 // RSASSA-PSS 4096 bit key with a SHA512 digest. RsaPss4096Sha512 // RSASSA-PKCS1-v1_5 with a 2048 bit key and a SHA256 digest. RsaSignPkcs12048Sha256 // RSASSA-PKCS1-v1_5 with a 3072 bit key and a SHA256 digest. RsaSignPkcs13072Sha256 // RSASSA-PKCS1-v1_5 with a 4096 bit key and a SHA256 digest. RsaSignPkcs14096Sha256 // RSASSA-PKCS1-v1_5 with a 4096 bit key and a SHA512 digest. RsaSignPkcs14096Sha512 // ECDSA on the NIST P-256 curve with a SHA256 digest. EcdsaP256Sha256 // ECDSA on the NIST P-384 curve with a SHA384 digest. EcdsaP384Sha384 // ECDSA on the NIST P-521 curve with a SHA512 digest. EcdsaP521Sha512 // Valid for PGP case PGPUnused )
Enumeration of SignatureAlgorithm
func ParseSignatureAlgorithm ¶
func ParseSignatureAlgorithm(algStr string) SignatureAlgorithm
GetAlg parses an algorithm string into SignatureAlgorithm type. Naming should be consistent with: https://cloud.google.com/sdk/gcloud/reference/container/binauthz/attestors/public-keys/add#--pkix-public-key-algorithm
type Signer ¶
type Signer interface {
// CreateAttestation creates an Attestation whose signature is generated by
// signing the given payload with the private key. For PGP and PKIX, `payload`
// should be the raw payload data. For JWT, `payload` should be a serialized
// but unsigned token.
CreateAttestation(payload []byte) (*Attestation, error)
}
Signer contains methods to create a signed Attestation.
func NewJwtSigner ¶
func NewJwtSigner(privateKey []byte, publicKeyID string, alg SignatureAlgorithm) (Signer, error)
NewJwtSigner creates a Signer interface for JWT Attestations. `publicKeyID` is the ID of the public key that can verify the Attestation signature. TODO: Explain formatting of JWT private keys.
func NewPgpSigner ¶
NewPgpSigner creates a Signer interface for PGP Attestations. `privateKey` contains the ASCII-armored private key. `passphrase` contains an optional password to decrypt the private key. If the private key is not encrypted, pass in an empty string.
func NewPkixSigner ¶
func NewPkixSigner(privateKey []byte, alg SignatureAlgorithm, publicKeyID string) (Signer, error)
NewPkixSigner creates a Signer interface for PKIX Attestations. `privateKey` contains the PEM-encoded private key. `publicKeyID` is the ID of the public key that can verify the Attestation signature. In most cases, publicKeyID should be left empty and will be generated automatically.
type Verifier ¶
type Verifier interface {
// VerifyAttestation verifies whether an Attestation satisfies at least one
// of the public keys under an image. This function finds the public key
// whose ID matches the attestation's PublicKeyID, and uses this key to
// verify the signature.
VerifyAttestation(att *Attestation) error
}
Verifier contains methods to validate an Attestation.
func NewVerifier ¶
NewVerifier creates a Verifier interface for verifying Attestations. `image` contains the untruncated image name <image_name@digest> of the image that was signed. This should be provided directly by the policy evaluator, NOT by the Attestation. `publicKeySet` contains a list of PublicKeys that the Verifier will use to try to verify an Attestation.
Source Files