webkms

Documentation

Index

• Constants
• func CreateKeyStore(httpClient *http.Client, keyserverURL, controller, vaultID string, ...) (string, error)
• type CryptoBox
  • func NewCryptoBox(w kms.KeyManager) (*CryptoBox, error)
  • func (b *CryptoBox) Easy(payload, nonce, theirPub []byte, myKID string) ([]byte, error)
  • func (b *CryptoBox) EasyOpen(cipherText, nonce, theirPub, myPub []byte) ([]byte, error)
  • func (b *CryptoBox) Seal(payload, theirEncPub []byte, randSource io.Reader) ([]byte, error)
  • func (b *CryptoBox) SealOpen(cipherText, myPub []byte) ([]byte, error)
• type Opt
  • func WithCache(cacheSize int) Opt
  • func WithHeaders(addHeadersFunc addHeaders) Opt
• type Opts
  • func NewOpt() *Opts
• type RemoteKMS
  • func New(keystoreURL string, client *http.Client, opts ...Opt) *RemoteKMS
  • func (r *RemoteKMS) Create(kt kms.KeyType) (string, interface{}, error)
  • func (r *RemoteKMS) CreateAndExportPubKeyBytes(kt kms.KeyType) (string, []byte, error)
  • func (r *RemoteKMS) ExportPubKeyBytes(keyID string) ([]byte, error)
  • func (r *RemoteKMS) Get(keyID string) (interface{}, error)
  • func (r *RemoteKMS) ImportPrivateKey(privKey interface{}, kt kms.KeyType, opts ...kms.PrivateKeyOpts) (string, interface{}, error)
  • func (r *RemoteKMS) PubKeyBytesToHandle(pubKey []byte, kt kms.KeyType) (interface{}, error)
  • func (r *RemoteKMS) Rotate(kt kms.KeyType, keyID string) (string, interface{}, error)

Constants

const (
	// KeystoreEndpoint represents a remote keystore endpoint with swappable {serverEndpoint} value.
	KeystoreEndpoint = "{serverEndpoint}/kms/keystores"

	// ContentType is remoteKMS http content-type.
	ContentType = "application/json"

	// LocationHeader is remoteKMS http header set by the key server (usually to identify a keystore or key url).
	LocationHeader = "Location"
)

Functions

func CreateKeyStore

func CreateKeyStore(httpClient *http.Client, keyserverURL, controller, vaultID string, marshaller marshalFunc,
	opts ...Opt) (string, error)

CreateKeyStore calls the key server's create keystore REST function and returns the resulting keystoreURL value. Arguments of this function are described below:

• httpClient used to POST the request
• keyserverURL representing the key server url
• marshaller the marshal function used for marshaling content in the client. Usually: `json.Marshal`
• headersOpt optional function setting any necessary http headers for key server authorization

Returns:

• keystore URL (if successful)
• error (if error encountered)

Types

type CryptoBox

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

CryptoBox provides an elliptic-curve-based authenticated encryption scheme executed on a remote key server

Payloads are encrypted using symmetric encryption (XChacha20Poly1305) using a shared key derived from a shared secret created by

Curve25519 Elliptic Curve Diffie-Hellman key exchange.

CryptoBox is created by a remote KMS, and remotely reads secret keys from the KMS

for encryption/decryption, so clients do not need to see
the secrets themselves.

func NewCryptoBox

func NewCryptoBox(w kms.KeyManager) (*CryptoBox, error)

NewCryptoBox creates a CryptoBox which provides remote crypto box encryption using the given KMS's key.

func (*CryptoBox) Easy

func (b *CryptoBox) Easy(payload, nonce, theirPub []byte, myKID string) ([]byte, error)

Easy remotely seals a message with a provided nonce theirPub is used as a public key, while myPub is used to identify the private key that should be used.

func (*CryptoBox) EasyOpen

func (b *CryptoBox) EasyOpen(cipherText, nonce, theirPub, myPub []byte) ([]byte, error)

EasyOpen remotely unseals a message sealed with Easy, where the nonce is provided. theirPub is the public key used to decrypt directly, while myPub is used to identify the private key to be used.

func (*CryptoBox) Seal

func (b *CryptoBox) Seal(payload, theirEncPub []byte, randSource io.Reader) ([]byte, error)

Seal seals a payload using the equivalent of libsodium box_seal. This is an exact copy of localkms's CryptoBox.Seal() as no private key is involved and therefore it is not necessary to call the key server.

Generates an ephemeral keypair to use for the sender, and includes the ephemeral sender public key in the message.

func (*CryptoBox) SealOpen

func (b *CryptoBox) SealOpen(cipherText, myPub []byte) ([]byte, error)

SealOpen remotely decrypts a payload encrypted with Seal.

Reads the ephemeral sender public key, prepended to a properly-formatted message, and uses that along with the recipient private key corresponding to myPub to decrypt the message.

type Opt

type Opt func(opts *Opts)

Opt are the remoteKMS option.

func WithCache

func WithCache(cacheSize int) Opt

WithCache add cache. if size is zero cache content will not be purged.

func WithHeaders

func WithHeaders(addHeadersFunc addHeaders) Opt

WithHeaders option is for setting additional http request headers (since it's a function, it can call a remote authorization server to fetch the necessary info needed in these headers).

type Opts

type Opts struct {
	HeadersFunc     addHeaders
	ComputeMACCache gcache.Cache
}

Opts represents option.

func NewOpt

func NewOpt() *Opts

NewOpt creates a new empty option. Not to be used directly. It's intended for implementations of remoteKMS. Use WithHeaders() option function below instead.

type RemoteKMS

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

RemoteKMS implementation of kms.KeyManager api.

func New

func New(keystoreURL string, client *http.Client, opts ...Opt) *RemoteKMS

New creates a new remoteKMS instance using http client connecting to keystoreURL.

func (*RemoteKMS) Create

func (r *RemoteKMS) Create(kt kms.KeyType) (string, interface{}, error)

Create a new key/keyset/key handle for the type kt remotely Returns:

• KeyID raw ID of the handle
• handle instance representing a remote keystore URL including KeyID
• error if failure

func (*RemoteKMS) CreateAndExportPubKeyBytes

func (r *RemoteKMS) CreateAndExportPubKeyBytes(kt kms.KeyType) (string, []byte, error)

CreateAndExportPubKeyBytes will remotely create a key of type kt and export its public key in raw bytes and returns it. The key must be an asymmetric key. Returns:

• KeyID of the new handle created.
• marshalled public key []byte
• error if it fails to export the public key bytes

func (*RemoteKMS) ExportPubKeyBytes

func (r *RemoteKMS) ExportPubKeyBytes(keyID string) ([]byte, error)

ExportPubKeyBytes will remotely fetch a key referenced by id then gets its public key in raw bytes and returns it. The key must be an asymmetric key. Returns:

• marshalled public key []byte
• error if it fails to export the public key bytes

func (*RemoteKMS) Get

func (r *RemoteKMS) Get(keyID string) (interface{}, error)

Get key handle for the given KeyID remotely Returns:

• handle instance representing a remote keystore URL including KeyID
• error if failure

func (*RemoteKMS) ImportPrivateKey

func (r *RemoteKMS) ImportPrivateKey(privKey interface{}, kt kms.KeyType,
	opts ...kms.PrivateKeyOpts) (string, interface{}, error)

ImportPrivateKey will import privKey into the KMS storage for the given KeyType then returns the new key id and the newly persisted Handle. 'privKey' possible types are: *ecdsa.PrivateKey and ed25519.PrivateKey 'kt' possible types are signing key types only (ECDSA keys or Ed25519) 'opts' allows setting the keysetID of the imported key using WithKeyID() option. If the ID is already used, then an error is returned. Returns:

• KeyID of the handle
• handle instance (to private key)
• error if import failure (key empty, invalid, doesn't match KeyType, unsupported KeyType or storing key failed)

func (*RemoteKMS) PubKeyBytesToHandle

func (r *RemoteKMS) PubKeyBytesToHandle(pubKey []byte, kt kms.KeyType) (interface{}, error)

PubKeyBytesToHandle is not implemented in remoteKMS.

func (*RemoteKMS) Rotate

func (r *RemoteKMS) Rotate(kt kms.KeyType, keyID string) (string, interface{}, error)

Rotate remotely a key referenced by KeyID and return a new handle of a keyset including old key and new key with type kt. It also returns the updated KeyID as the first return value Returns:

• new KeyID
• handle instance (to private key)
• error if failure