libtrust

package module
v0.0.0-...-c1716e8 Latest Latest
Warning

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

 Go to latest Published: Jan 21, 2023 License: Apache-2.0 Imports: 31 Imported by: 8

README

libtrust

WARNING this library is no longer actively developed, and will be integrated in the [docker/distribution][https://www.github.com/docker/distribution] repository in future.

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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.