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 ¶
- Variables
- func AddKeySetFile(filename string, key PublicKey) error
- func GenerateCACert(signer PrivateKey, trustedKey PublicKey) (*x509.Certificate, error)
- func GenerateCACertPool(signer PrivateKey, trustedKeys []PublicKey) (*x509.CertPool, error)
- func GenerateSelfSignedClientCert(key PrivateKey) (*x509.Certificate, error)
- func GenerateSelfSignedServerCert(key PrivateKey, domains []string, ipAddresses []net.IP) (*x509.Certificate, error)
- func LoadCertificateBundle(filename string) ([]*x509.Certificate, error)
- func LoadCertificatePool(filename string) (*x509.CertPool, error)
- func NewCertAuthTLSConfig(caPath, certPath, keyPath string) (*tls.Config, error)
- func NewIdentityAuthTLSClientConfig(dockerUrl string, trustUnknownHosts bool, rootConfigPath string, ...) (*tls.Config, error)
- func NewIdentityAuthTLSConfig(trustKey PrivateKey, clients *ClientKeyManager, addr string, domain string) (*tls.Config, error)
- func SaveKey(filename string, key PrivateKey) error
- func SavePublicKey(filename string, key PublicKey) error
- type ClientKeyManager
- type JSONSignature
- func (js *JSONSignature) JWS() ([]byte, error)
- func (js *JSONSignature) Merge(others ...*JSONSignature) error
- func (js *JSONSignature) Payload() ([]byte, error)
- func (js *JSONSignature) PrettySignature(signatureKey string) ([]byte, error)
- func (js *JSONSignature) Sign(key PrivateKey) error
- func (js *JSONSignature) SignWithChain(key PrivateKey, chain []*x509.Certificate) error
- func (js *JSONSignature) Signatures() ([][]byte, error)
- func (js *JSONSignature) Verify() ([]PublicKey, error)
- func (js *JSONSignature) VerifyChains(ca *x509.CertPool) ([][]*x509.Certificate, error)
- type PrivateKey
- func FromCryptoPrivateKey(cryptoPrivateKey crypto.PrivateKey) (PrivateKey, error)
- func GenerateECP256PrivateKey() (PrivateKey, error)
- func GenerateECP384PrivateKey() (PrivateKey, error)
- func GenerateECP521PrivateKey() (PrivateKey, error)
- func GenerateRSA2048PrivateKey() (PrivateKey, error)
- func GenerateRSA3072PrivateKey() (PrivateKey, error)
- func GenerateRSA4096PrivateKey() (PrivateKey, error)
- func LoadKeyFile(filename string) (PrivateKey, error)
- func LoadOrCreateTrustKey(trustKeyPath string) (PrivateKey, error)
- func UnmarshalPrivateKeyJWK(data []byte) (PrivateKey, error)
- func UnmarshalPrivateKeyPEM(data []byte) (PrivateKey, error)
- type PublicKey
- func FilterByHosts(keys []PublicKey, host string, includeEmpty bool) ([]PublicKey, error)
- func FromCryptoPublicKey(cryptoPublicKey crypto.PublicKey) (PublicKey, error)
- func LoadKeySetFile(filename string) ([]PublicKey, error)
- func LoadPublicKeyFile(filename string) (PublicKey, error)
- func UnmarshalPublicKeyJWK(data []byte) (PublicKey, error)
- func UnmarshalPublicKeyJWKSet(data []byte) ([]PublicKey, error)
- func UnmarshalPublicKeyPEM(data []byte) (PublicKey, error)
- func UnmarshalPublicKeyPEMBundle(data []byte) ([]PublicKey, error)
Constants ¶
This section is empty.
Variables ¶
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") )
var ( // ErrKeyFileDoesNotExist indicates that the private key file does not exist. ErrKeyFileDoesNotExist = errors.New("key file does not exist") )
Functions ¶
func AddKeySetFile ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
LoadKeySetFile loads a key set
func LoadPublicKeyFile ¶
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 ¶
UnmarshalPublicKeyJWK unmarshals the given JSON Web Key into a generic Public Key to be used with libtrust.
func UnmarshalPublicKeyJWKSet ¶
UnmarshalPublicKeyJWKSet parses the JSON encoded data as a JSON Web Key Set and returns a slice of Public Key objects.
func UnmarshalPublicKeyPEM ¶
UnmarshalPublicKeyPEM parses the PEM encoded data and returns a libtrust PublicKey or an error if there is a problem with the encoding.
func UnmarshalPublicKeyPEMBundle ¶
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.