distsign

Documentation

Overview

Package distsign implements signature and validation of arbitrary distributable files.

There are 3 parties in this exchange:

• builder, which creates files, signs them with signing keys and publishes to server
• server, which distributes public signing keys, files and signatures
• client, which downloads files and signatures from server, and validates the signatures

There are 2 types of keys:

• signing keys, that sign individual distributable files on the builder
• root keys, that sign signing keys and are kept offline

root keys -(sign)-> signing keys -(sign)-> files

All keys are asymmetric Ed25519 key pairs.

The server serves static files under some known prefix. The kinds of files are:

• distsign.pub - bundle of PEM-encoded public signing keys
• distsign.pub.sig - signature of distsign.pub using one of the root keys
• $file - any distributable file
• $file.sig - signature of $file using any of the signing keys

The root public keys are baked into the client software at compile time. These keys are long-lived and prove the validity of current signing keys from distsign.pub. To rotate root keys, a new client release must be published, they are not rotated dynamically. There are multiple root keys in different locations specifically to allow this rotation without using the discarded root key for any new signatures.

The signing public keys are fetched by the client dynamically before every download and can be rotated more readily, assuming that most deployed clients trust the root keys used to issue fresh signing keys.

Index

• func GenerateRootKey() (priv, pub []byte, err error)
• func GenerateSigningKey() (priv, pub []byte, err error)
• func ParseRootKeyBundle(bundle []byte) ([]ed25519.PublicKey, error)
• func ParseSigningKeyBundle(bundle []byte) ([]ed25519.PublicKey, error)
• func VerifyAny(keys []ed25519.PublicKey, msg, sig []byte) bool
• type Client
  • func NewClient(logf logger.Logf, pkgsAddr string) (*Client, error)
  • func (c *Client) Download(ctx context.Context, srcPath, dstPath string) error
  • func (c *Client) ValidateLocalBinary(srcURLPath, localFilePath string) error
• type PackageHash
  • func NewPackageHash() *PackageHash
  • func (ph *PackageHash) Len() int64
  • func (ph *PackageHash) Reset()
  • func (ph *PackageHash) Write(b []byte) (int, error)
• type RootKey
  • func ParseRootKey(privKey []byte) (*RootKey, error)
  • func (r *RootKey) SignSigningKeys(pubBundle []byte) ([]byte, error)
• type SigningKey
  • func ParseSigningKey(privKey []byte) (*SigningKey, error)
  • func (s *SigningKey) SignPackageHash(hash []byte, len int64) ([]byte, error)

Functions

func GenerateRootKey

func GenerateRootKey() (priv, pub []byte, err error)

GenerateRootKey generates a new root key pair and encodes it as PEM.

func GenerateSigningKey

func GenerateSigningKey() (priv, pub []byte, err error)

GenerateSigningKey generates a new signing key pair and encodes it as PEM.

func ParseRootKeyBundle

func ParseRootKeyBundle(bundle []byte) ([]ed25519.PublicKey, error)

ParseRootKeyBundle parses the bundle of PEM-encoded public root keys.

func ParseSigningKeyBundle

func ParseSigningKeyBundle(bundle []byte) ([]ed25519.PublicKey, error)

ParseSigningKeyBundle parses the bundle of PEM-encoded public signing keys.

func VerifyAny

func VerifyAny(keys []ed25519.PublicKey, msg, sig []byte) bool

VerifyAny verifies whether sig is valid for msg using any of the keys. VerifyAny will panic if any of the keys have the wrong size for Ed25519.

Types

type Client

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

Client downloads and validates files from a distribution server.

func NewClient

func NewClient(logf logger.Logf, pkgsAddr string) (*Client, error)

NewClient returns a new client for distribution server located at pkgsAddr, and uses embedded root keys from the roots/ subdirectory of this package.

func (*Client) Download

func (c *Client) Download(ctx context.Context, srcPath, dstPath string) error

Download fetches a file at path srcPath from pkgsAddr passed in NewClient. The file is downloaded to dstPath and its signature is validated using the embedded root keys. Download returns an error if anything goes wrong with the actual file download or with signature validation.

func (*Client) ValidateLocalBinary

func (c *Client) ValidateLocalBinary(srcURLPath, localFilePath string) error

ValidateLocalBinary fetches the latest signature associated with the binary at srcURLPath and uses it to validate the file located on disk via localFilePath. ValidateLocalBinary returns an error if anything goes wrong with the signature download or with signature validation.

type PackageHash

type PackageHash struct {
	hash.Hash
	// contains filtered or unexported fields
}

PackageHash is a hash.Hash that counts the number of bytes written. Use it to get the hash and length inputs to SigningKey.SignPackageHash.

func NewPackageHash

func NewPackageHash() *PackageHash

NewPackageHash returns an initialized PackageHash using BLAKE2s.

func (*PackageHash) Len

func (ph *PackageHash) Len() int64

Len returns the total number of bytes written.

func (*PackageHash) Reset

func (ph *PackageHash) Reset()

Reset the PackageHash to its initial state.

func (*PackageHash) Write

func (ph *PackageHash) Write(b []byte) (int, error)

type RootKey

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

RootKey is a root key used to sign signing keys.

func ParseRootKey

func ParseRootKey(privKey []byte) (*RootKey, error)

ParseRootKey parses the PEM-encoded private root key. The key must be in the same format as returned by GenerateRootKey.

func (*RootKey) SignSigningKeys

func (r *RootKey) SignSigningKeys(pubBundle []byte) ([]byte, error)

SignSigningKeys signs the bundle of public signing keys. The bundle must be a sequence of PEM blocks joined with newlines.

type SigningKey

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

SigningKey is a signing key used to sign packages.

func ParseSigningKey

func ParseSigningKey(privKey []byte) (*SigningKey, error)

ParseSigningKey parses the PEM-encoded private signing key. The key must be in the same format as returned by GenerateSigningKey.

func (*SigningKey) SignPackageHash

func (s *SigningKey) SignPackageHash(hash []byte, len int64) ([]byte, error)

SignPackageHash signs the hash and the length of a package. Use PackageHash to compute the inputs.