keys

Documentation

Overview

Package keys provides interfaces and handlers for managing public/private key pairs that are used for sealing and unsealing secure envelopes. This package is not intended for use with symmetric keys that are used to encrypt payloads.

Index

• Variables
• func ParseKeyExchangeData(data []byte) (pubkey interface{}, err error)
• type Certificate
  • func (c *Certificate) Certs() *x509.Certificate
  • func (c *Certificate) IsPrivate() bool
  • func (c *Certificate) Marshal() (_ []byte, err error)
  • func (c *Certificate) Proto() (msg *api.SigningKey, err error)
  • func (c *Certificate) PublicKeyAlgorithm() string
  • func (c *Certificate) PublicKeySignature() (string, error)
  • func (c *Certificate) SealingKey() (interface{}, error)
  • func (c *Certificate) Unmarshal(data []byte) (err error)
  • func (c *Certificate) UnsealingKey() (interface{}, error)
• type Exchange
  • func (e *Exchange) IsPrivate() bool
  • func (e *Exchange) Marshal() ([]byte, error)
  • func (e *Exchange) Proto() (*api.SigningKey, error)
  • func (e *Exchange) PublicKeyAlgorithm() string
  • func (e *Exchange) PublicKeySignature() (_ string, err error)
  • func (e *Exchange) SealingKey() (_ interface{}, err error)
  • func (e *Exchange) Unmarshal(data []byte) (err error)
  • func (e *Exchange) UnsealingKey() (interface{}, error)
• type Key
  • func FromCertificate(cert *x509.Certificate) (Key, error)
  • func FromGDSLookup(in *gds.LookupReply) (_ Key, err error)
  • func FromProvider(certs *trust.Provider) (_ Key, err error)
  • func FromSigningKey(msg *api.SigningKey) (Key, error)
  • func FromX509KeyPair(cert *x509.Certificate, privateKey interface{}) (Key, error)
• type KeyIdentifier
• type KeyMarshaler
• type PrivateKey
• type PublicKey

Variables

var (
	ErrNoPrivateKey          = errors.New("no private unsealing key available")
	ErrNoCertificate         = errors.New("no certificates found in PEM encoded data")
	ErrMultipleKeys          = errors.New("too many private keys found in PEM encoded data")
	ErrUnparsableKeyExchange = errors.New("could not parse key exchange data with known key serialization methods")
	ErrNoPublicKey           = errors.New("no public keys found in PEM encoded data")
	ErrTooManyBlocks         = errors.New("too many public key blocks found in PEM encoded data")
	ErrNoKeyData             = errors.New("cannot parse public key from empty or nil data")
)

Functions

func ParseKeyExchangeData

func ParseKeyExchangeData(data []byte) (pubkey interface{}, err error)

ParseKeyExchangeData attempts to parse key exchange data that may arrive in multiple seralized formats. In order, it first attempts to parse marshaled PKIX public keys, then PEM encoded data (either x509 certificates or public keys), finally attempting to parse raw x509 data. If more exchange formats are detected, they should be added to this methods parsing interface.

Types

type Certificate

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

Certificate is a wrapper for an x509 certificate (containing the public key) and optionally for the private key associated with the certificate. This data structure is used to create exchange keys using TRISA issued sealing-certificates. The public key in the certificate will be used to send keys for sealing and the private key for unsealing certificates.

func (*Certificate) Certs

func (c *Certificate) Certs() *x509.Certificate

Certs returns the wrapped certificate object.

func (*Certificate) IsPrivate

func (c *Certificate) IsPrivate() bool

IsPrivate returns true if there is a private key associated with the certificate.

func (*Certificate) Marshal

func (c *Certificate) Marshal() (_ []byte, err error)

Marshal returns a PEM encoded Certificate Block along with a PEM encoded private key block if one is available. This data is useful for storing Keys (particularly one's own private key pairs and sealing certificates) on disk or in a database, but should not be used to transfer or send keys.

func (*Certificate) Proto

func (c *Certificate) Proto() (msg *api.SigningKey, err error)

Proto returns the protocol buffer message with the public sealing key to exchange with a remote counterparty to begin a TRISA transfer.

func (*Certificate) PublicKeyAlgorithm

func (c *Certificate) PublicKeyAlgorithm() string

PublicKeyAlgorithm refers to the public key algorithm of the x509.Certificate and may be used to determine which cipher to use. Typically is "RSA".

func (*Certificate) PublicKeySignature

func (c *Certificate) PublicKeySignature() (string, error)

PublicKeySignature returns a unique identifier that can be used to manage public keys and associate them with their counterpart private keys for unsealing or to identify the keys in use by the counterparty for creating and sealing secure envelopes.

func (*Certificate) SealingKey

func (c *Certificate) SealingKey() (interface{}, error)

SealingKey is public key used to seal envelopes, usually an *rsa.PublicKey.

func (*Certificate) Unmarshal

func (c *Certificate) Unmarshal(data []byte) (err error)

Unmarshal a PEM encoded Certificate Block and optionally a PEM encoded private key block if one is available. Unmarshal is designed to perform the inverse functionality of Marshal - e.g. Unmarshal will load Marshaled data. However, Unmarshal may work on generic PEM encoded chains - e.g. a trust chain with multiple certificates will use the first certificate and ignore all others. An error is returned if multiple private key blocks are detected in the PEM data.

func (*Certificate) UnsealingKey

func (c *Certificate) UnsealingKey() (interface{}, error)

UnsealingKey is the private key used to unseal envelopes, usually an *rsa.PrivateKey. If no private key is available (IsPrivate() is false) then an error is returned.

type Exchange

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

Exchange wraps a *trisa.SigningKey protocol buffer that is sent during a trisa.KeyExchange RPC and implements the Key interface. Exchange Keys are public keys only (they do not and cannot contain a private key) and are only used for sealing secure envelopes before a trisa.Transfer RPC.

func (*Exchange) IsPrivate

func (e *Exchange) IsPrivate() bool

IsPrivate always returns false for an Exchange key - no private keys are available.

func (*Exchange) Marshal

func (e *Exchange) Marshal() ([]byte, error)

Marshal simply returns the protocol buffer marshaled data for the most compact storage.

func (*Exchange) Proto

func (e *Exchange) Proto() (*api.SigningKey, error)

func (*Exchange) PublicKeyAlgorithm

func (e *Exchange) PublicKeyAlgorithm() string

PublicKeyAlgorithm refers to the public key algorithm of the x509.Certificate and may be used to determine which cipher to use. Typically is "RSA".

func (*Exchange) PublicKeySignature

func (e *Exchange) PublicKeySignature() (_ string, err error)

PublicKeySignature returns a unique identifier that can be used to manage public keys and associate them with their counterpart private keys for unsealing.

func (*Exchange) SealingKey

func (e *Exchange) SealingKey() (_ interface{}, err error)

SealingKey returns the public key used to seal envelopes, usually an *rsa.PublicKey. This method attempts to parse the keys that may have been sent in the exchange, either a raw PKIX key or an x509 certificate, in PEM encoding or not. If the sealing key cannot be parsed an error is returned.

func (*Exchange) Unmarshal

func (e *Exchange) Unmarshal(data []byte) (err error)

Unmarshal the protocol buffer marshaled data and load the sealing key. If the sealing key is invalid or unparsable this method returns an error.

func (*Exchange) UnsealingKey

func (e *Exchange) UnsealingKey() (interface{}, error)

UnsealingKey always returns an error for an Exchange key - no private keys are available.

type Key

type Key interface {
	PublicKey
	PrivateKey
	KeyMarshaler

	// Indicates if the Key contains a private key. If this method returns false, then
	// the UnsealingKey() method should always return an error.
	IsPrivate() bool
}

Key provides a generic interface to either a private key pair or to a public key that has been shared in a TRISA key-exchange. The primary use of this top level interface is serializing and deserializing keys with the marshaler interface and creating a unified mechanism to manage keys on disk.

func FromCertificate

func FromCertificate(cert *x509.Certificate) (Key, error)

Create a Key from an x509 certificate or sealing certificate issued by TRISA.

func FromGDSLookup

func FromGDSLookup(in *gds.LookupReply) (_ Key, err error)

FromGDSLookup returns a Key returned from the TRISA Global Directory Service. If the lookup returns a signing certificate, that key is used, otherwise the identity certificate is used. If no certificates are available, an error is returned. This method expects the GDS to return a PEM encoded x509 certificate.

func FromProvider

func FromProvider(certs *trust.Provider) (_ Key, err error)

FromProvider returns a Key from a deserialized trust provider. This is the most common mechanism of loading a certificate from disk and is the most flexible.

func FromSigningKey

func FromSigningKey(msg *api.SigningKey) (Key, error)

Create a Key from an *trisa.SigningKey received during the trisa.KeyExchange RPC. If the signing key contains an invalid or unparseable public key an error is returned.

func FromX509KeyPair

func FromX509KeyPair(cert *x509.Certificate, privateKey interface{}) (Key, error)

Create a Key from an x509 certificate and a private key pair.

type KeyIdentifier

type KeyIdentifier interface {
	PublicKeyAlgorithm() string          // The sealing public key algorithm to identify the key type
	PublicKeySignature() (string, error) // An identifier of the public key for key management
}

type KeyMarshaler

type KeyMarshaler interface {
	Marshal() ([]byte, error)
	Unmarshal(data []byte) error
}

type PrivateKey

type PrivateKey interface {
	// Return the key object that can be used to unseal an envelope, typically an *rsa.PrivateKey
	UnsealingKey() (interface{}, error)
}

type PublicKey

type PublicKey interface {
	KeyIdentifier

	// Return the key object that can be used to seal an envelope, typically an *rsa.PublicKey
	SealingKey() (interface{}, error)

	// Return the protocol buffer exchange key object to send to the counterparty
	Proto() (*api.SigningKey, error)
}