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
- type PackageHash
- type RootKey
- type SigningKey
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GenerateRootKey ¶
GenerateRootKey generates a new root key pair and encodes it as PEM.
func GenerateSigningKey ¶
GenerateSigningKey generates a new signing key pair and encodes it as PEM.
func ParseRootKeyBundle ¶
ParseRootKeyBundle parses the bundle of PEM-encoded public root keys.
func ParseSigningKeyBundle ¶
ParseSigningKeyBundle parses the bundle of PEM-encoded public signing keys.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client downloads and validates files from a distribution server.
func NewClient ¶
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 ¶
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 ¶
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 ¶
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.
type RootKey ¶
type RootKey struct {
// contains filtered or unexported fields
}
RootKey is a root key used to sign signing keys.
func ParseRootKey ¶
ParseRootKey parses the PEM-encoded private root key. The key must be in the same format as returned by GenerateRootKey.
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.
Source Files