libtrust

package
v2.0.0-rc.2+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 8, 2015 License: Apache-2.0, Apache-2.0 Imports: 31 Imported by: 0

README

libtrust

Libtrust is library for managing authentication and authorization using public key cryptography.

Authentication is handled using the identity attached to the public key. Libtrust provides multiple methods to prove possession of the private key associated with an identity.

  • TLS x509 certificates
  • Signature verification
  • Key Challenge

Authorization and access control is managed through a distributed trust graph. Trust servers are used as the authorities of the trust graph and allow caching portions of the graph for faster access.

Code and documentation copyright 2014 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.

Documentation

Overview

Package libtrust provides an interface for managing authentication and authorization using public key cryptography. Authentication is handled using the identity attached to the public key and verified through TLS x509 certificates, a key challenge, or signature. Authorization and access control is managed through a trust graph distributed between both remote trust servers and locally cached and managed data.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidSignContent is used when the content to be signed is invalid.
	ErrInvalidSignContent = errors.New("invalid sign content")

	// ErrInvalidJSONContent is used when invalid json is encountered.
	ErrInvalidJSONContent = errors.New("invalid json content")

	// ErrMissingSignatureKey is used when the specified signature key
	// does not exist in the JSON content.
	ErrMissingSignatureKey = errors.New("missing signature key")
)
View Source
var (
	// ErrKeyFileDoesNotExist indicates that the private key file does not exist.
	ErrKeyFileDoesNotExist = errors.New("key file does not exist")
)

Functions

func AddKeySetFile

func AddKeySetFile(filename string, key PublicKey) error

AddKeySetFile adds a key to a key set

func GenerateCACert

func GenerateCACert(signer PrivateKey, trustedKey PublicKey) (*x509.Certificate, error)

GenerateCACert creates a certificate which can be used as a trusted certificate authority.

func GenerateCACertPool

func GenerateCACertPool(signer PrivateKey, trustedKeys []PublicKey) (*x509.CertPool, error)

GenerateCACertPool creates a certificate authority pool to be used for a TLS configuration. Any self-signed certificates issued by the specified trusted keys will be verified during a TLS handshake

func GenerateSelfSignedClientCert

func GenerateSelfSignedClientCert(key PrivateKey) (*x509.Certificate, error)

GenerateSelfSignedClientCert creates a self-signed certificate for the given key which is to be used for TLS clients.

func GenerateSelfSignedServerCert

func GenerateSelfSignedServerCert(key PrivateKey, domains []string, ipAddresses []net.IP) (*x509.Certificate, error)

GenerateSelfSignedServerCert creates a self-signed certificate for the given key which is to be used for TLS servers with the given domains and IP addresses.

func LoadCertificateBundle

func LoadCertificateBundle(filename string) ([]*x509.Certificate, error)

LoadCertificateBundle loads certificates from the given file. The file should be pem encoded containing one or more certificates. The expected pem type is "CERTIFICATE".

func LoadCertificatePool

func LoadCertificatePool(filename string) (*x509.CertPool, error)

LoadCertificatePool loads a CA pool from the given file. The file should be pem encoded containing one or more certificates. The expected pem type is "CERTIFICATE".

func NewCertAuthTLSConfig

func NewCertAuthTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)

NewCertAuthTLSConfig creates a tls.Config for the server to use for certificate authentication

func NewIdentityAuthTLSClientConfig

func NewIdentityAuthTLSClientConfig(dockerUrl string, trustUnknownHosts bool, rootConfigPath string, serverName string) (*tls.Config, error)

NewIdentityAuthTLSClientConfig returns a tls.Config configured to use identity based authentication from the specified dockerUrl, the rootConfigPath and the server name to which it is connecting. If trustUnknownHosts is true it will automatically add the host to the known-hosts.json in rootConfigPath.

func NewIdentityAuthTLSConfig

func NewIdentityAuthTLSConfig(trustKey PrivateKey, clients *ClientKeyManager, addr string, domain string) (*tls.Config, error)

NewIdentityAuthTLSConfig creates a tls.Config for the server to use for libtrust identity authentication for the domain specified

func SaveKey

func SaveKey(filename string, key PrivateKey) error

SaveKey saves the given key to a file using the provided filename. This process will overwrite any existing file at the provided location.

func SavePublicKey

func SavePublicKey(filename string, key PublicKey) error

SavePublicKey saves the given public key to the file.

Types

type ClientKeyManager

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

ClientKeyManager manages client keys on the filesystem

func NewClientKeyManager

func NewClientKeyManager(trustKey PrivateKey, clientFile, clientDir string) (*ClientKeyManager, error)

NewClientKeyManager loads a new manager from a set of key files and managed by the given private key.

func (*ClientKeyManager) RegisterTLSConfig

func (c *ClientKeyManager) RegisterTLSConfig(tlsConfig *tls.Config) error

RegisterTLSConfig registers a tls configuration to manager such that any changes to the keys may be reflected in the tls client CA pool

type JSONSignature

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

JSONSignature represents a signature of a json object.

func NewJSONSignature

func NewJSONSignature(content []byte, signatures ...[]byte) (*JSONSignature, error)

NewJSONSignature returns a new unsigned JWS from a json byte array. JSONSignature will need to be signed before serializing or storing. Optionally, one or more signatures can be provided as byte buffers, containing serialized JWS signatures, to assemble a fully signed JWS package. It is the callers responsibility to ensure uniqueness of the provided signatures.

func NewJSONSignatureFromMap

func NewJSONSignatureFromMap(content interface{}) (*JSONSignature, error)

NewJSONSignatureFromMap returns a new unsigned JSONSignature from a map or struct. JWS will need to be signed before serializing or storing.

func ParseJWS

func ParseJWS(content []byte) (*JSONSignature, error)

ParseJWS parses a JWS serialized JSON object into a Json Signature.

func ParsePrettySignature

func ParsePrettySignature(content []byte, signatureKey string) (*JSONSignature, error)

ParsePrettySignature parses a formatted signature into a JSON signature. If the signatures are missing the format information an error is thrown. The formatted signature must be created by the same method as format signature.

func (*JSONSignature) JWS

func (js *JSONSignature) JWS() ([]byte, error)

JWS returns JSON serialized JWS according to http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-31#section-7.2

func (*JSONSignature) Merge

func (js *JSONSignature) Merge(others ...*JSONSignature) error

Merge combines the signatures from one or more other signatures into the method receiver. If the payloads differ for any argument, an error will be returned and the receiver will not be modified.

func (*JSONSignature) Payload

func (js *JSONSignature) Payload() ([]byte, error)

Payload returns the encoded payload of the signature. This payload should not be signed directly

func (*JSONSignature) PrettySignature

func (js *JSONSignature) PrettySignature(signatureKey string) ([]byte, error)

PrettySignature formats a json signature into an easy to read single json serialized object.

func (*JSONSignature) Sign

func (js *JSONSignature) Sign(key PrivateKey) error

Sign adds a signature using the given private key.

func (*JSONSignature) SignWithChain

func (js *JSONSignature) SignWithChain(key PrivateKey, chain []*x509.Certificate) error

SignWithChain adds a signature using the given private key and setting the x509 chain. The public key of the first element in the chain must be the public key corresponding with the sign key.

func (*JSONSignature) Signatures

func (js *JSONSignature) Signatures() ([][]byte, error)

Signatures provides the signatures on this JWS as opaque blobs, sorted by keyID. These blobs can be stored and reassembled with payloads. Internally, they are simply marshaled json web signatures but implementations should not rely on this.

func (*JSONSignature) Verify

func (js *JSONSignature) Verify() ([]PublicKey, error)

Verify verifies all the signatures and returns the list of public keys used to sign. Any x509 chains are not checked.

func (*JSONSignature) VerifyChains

func (js *JSONSignature) VerifyChains(ca *x509.CertPool) ([][]*x509.Certificate, error)

VerifyChains verifies all the signatures and the chains associated with each signature and returns the list of verified chains. Signatures without an x509 chain are not checked.

type PrivateKey

type PrivateKey interface {
	// A PrivateKey contains all fields and methods of a PublicKey of the
	// same type. The MarshalJSON method also outputs the private key as a
	// JSON Web Key, and the PEMBlock method outputs the private key as a
	// PEM block.
	PublicKey
	// PublicKey returns the PublicKey associated with this PrivateKey.
	PublicKey() PublicKey
	// Sign signs the data read from the io.Reader using a signature algorithm
	// supported by the private key. If the specified hashing algorithm is
	// supported by this key, that hash function is used to generate the
	// signature otherwise the the default hashing algorithm for this key is
	// used. Returns the signature and identifier of the algorithm used.
	Sign(data io.Reader, hashID crypto.Hash) (signature []byte, alg string, err error)
	// CryptoPrivateKey returns the internal object which can be used as a
	// crypto.PublicKey for use with other standard library operations. The
	// type is either *rsa.PublicKey or *ecdsa.PublicKey
	CryptoPrivateKey() crypto.PrivateKey
}

PrivateKey is a generic interface for a Private Key.

func FromCryptoPrivateKey

func FromCryptoPrivateKey(cryptoPrivateKey crypto.PrivateKey) (PrivateKey, error)

FromCryptoPrivateKey returns a libtrust PrivateKey representation of the given *ecdsa.PrivateKey or *rsa.PrivateKey. Returns a non-nil error when the given key is of an unsupported type.

func GenerateECP256PrivateKey

func GenerateECP256PrivateKey() (PrivateKey, error)

GenerateECP256PrivateKey generates a key pair using elliptic curve P-256.

func GenerateECP384PrivateKey

func GenerateECP384PrivateKey() (PrivateKey, error)

GenerateECP384PrivateKey generates a key pair using elliptic curve P-384.

func GenerateECP521PrivateKey

func GenerateECP521PrivateKey() (PrivateKey, error)

GenerateECP521PrivateKey generates aß key pair using elliptic curve P-521.

func GenerateRSA2048PrivateKey

func GenerateRSA2048PrivateKey() (PrivateKey, error)

GenerateRSA2048PrivateKey generates a key pair using 2048-bit RSA.

func GenerateRSA3072PrivateKey

func GenerateRSA3072PrivateKey() (PrivateKey, error)

GenerateRSA3072PrivateKey generates a key pair using 3072-bit RSA.

func GenerateRSA4096PrivateKey

func GenerateRSA4096PrivateKey() (PrivateKey, error)

GenerateRSA4096PrivateKey generates a key pair using 4096-bit RSA.

func LoadKeyFile

func LoadKeyFile(filename string) (PrivateKey, error)

LoadKeyFile opens the given filename and attempts to read a Private Key encoded in either PEM or JWK format (if .json or .jwk file extension).

func LoadOrCreateTrustKey

func LoadOrCreateTrustKey(trustKeyPath string) (PrivateKey, error)

LoadOrCreateTrustKey will load a PrivateKey from the specified path

func UnmarshalPrivateKeyJWK

func UnmarshalPrivateKeyJWK(data []byte) (PrivateKey, error)

UnmarshalPrivateKeyJWK unmarshals the given JSON Web Key into a generic Private Key to be used with libtrust.

func UnmarshalPrivateKeyPEM

func UnmarshalPrivateKeyPEM(data []byte) (PrivateKey, error)

UnmarshalPrivateKeyPEM parses the PEM encoded data and returns a libtrust PrivateKey or an error if there is a problem with the encoding.

type PublicKey

type PublicKey interface {
	// KeyType returns the key type for this key. For elliptic curve keys,
	// this value should be "EC". For RSA keys, this value should be "RSA".
	KeyType() string
	// KeyID returns a distinct identifier which is unique to this Public Key.
	// The format generated by this library is a base32 encoding of a 240 bit
	// hash of the public key data divided into 12 groups like so:
	//    ABCD:EFGH:IJKL:MNOP:QRST:UVWX:YZ23:4567:ABCD:EFGH:IJKL:MNOP
	KeyID() string
	// Verify verifyies the signature of the data in the io.Reader using this
	// Public Key. The alg parameter should identify the digital signature
	// algorithm which was used to produce the signature and should be
	// supported by this public key. Returns a nil error if the signature
	// is valid.
	Verify(data io.Reader, alg string, signature []byte) error
	// CryptoPublicKey returns the internal object which can be used as a
	// crypto.PublicKey for use with other standard library operations. The type
	// is either *rsa.PublicKey or *ecdsa.PublicKey
	CryptoPublicKey() crypto.PublicKey
	// These public keys can be serialized to the standard JSON encoding for
	// JSON Web Keys. See section 6 of the IETF draft RFC for JOSE JSON Web
	// Algorithms.
	MarshalJSON() ([]byte, error)
	// These keys can also be serialized to the standard PEM encoding.
	PEMBlock() (*pem.Block, error)
	// The string representation of a key is its key type and ID.
	String() string
	AddExtendedField(string, interface{})
	GetExtendedField(string) interface{}
}

PublicKey is a generic interface for a Public Key.

func FilterByHosts

func FilterByHosts(keys []PublicKey, host string, includeEmpty bool) ([]PublicKey, error)

FilterByHosts filters the list of PublicKeys to only those which contain a 'hosts' pattern which matches the given host. If *includeEmpty* is true, then keys which do not specify any hosts are also returned.

func FromCryptoPublicKey

func FromCryptoPublicKey(cryptoPublicKey crypto.PublicKey) (PublicKey, error)

FromCryptoPublicKey returns a libtrust PublicKey representation of the given *ecdsa.PublicKey or *rsa.PublicKey. Returns a non-nil error when the given key is of an unsupported type.

func LoadKeySetFile

func LoadKeySetFile(filename string) ([]PublicKey, error)

LoadKeySetFile loads a key set

func LoadPublicKeyFile

func LoadPublicKeyFile(filename string) (PublicKey, error)

LoadPublicKeyFile opens the given filename and attempts to read a Public Key encoded in either PEM or JWK format (if .json or .jwk file extension).

func UnmarshalPublicKeyJWK

func UnmarshalPublicKeyJWK(data []byte) (PublicKey, error)

UnmarshalPublicKeyJWK unmarshals the given JSON Web Key into a generic Public Key to be used with libtrust.

func UnmarshalPublicKeyJWKSet

func UnmarshalPublicKeyJWKSet(data []byte) ([]PublicKey, error)

UnmarshalPublicKeyJWKSet parses the JSON encoded data as a JSON Web Key Set and returns a slice of Public Key objects.

func UnmarshalPublicKeyPEM

func UnmarshalPublicKeyPEM(data []byte) (PublicKey, error)

UnmarshalPublicKeyPEM parses the PEM encoded data and returns a libtrust PublicKey or an error if there is a problem with the encoding.

func UnmarshalPublicKeyPEMBundle

func UnmarshalPublicKeyPEMBundle(data []byte) ([]PublicKey, error)

UnmarshalPublicKeyPEMBundle parses the PEM encoded data as a bundle of PEM blocks appended one after the other and returns a slice of PublicKey objects that it finds.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL