crypto

Documentation

Overview

Package crypto contains the Crypto interface to be used by the framework. It will be created via Options creation in pkg/framework/context.Provider. BBS+ signature scheme is not included in the main Crypto interface. It is defined separately under the primitive sub-package including its implementation which should not be referenced directly. It is accessible via the framework's KMS BBS+ keys and tinkcrypto's bbs package's Signer and Verifier primitives or via webkms for remote KMS BBS+ signing.

Index

• func NewOpt() *wrapKeyOpts
• type Crypto
• type PrivateKey
• type PublicKey
• type RecipientWrappedKey
• type WrapKeyOpts
  • func WithEPK(epk *PrivateKey) WrapKeyOpts
  • func WithSender(senderKey interface{}) WrapKeyOpts
  • func WithTag(tag []byte) WrapKeyOpts
  • func WithXC20PKW() WrapKeyOpts

Functions

func NewOpt

func NewOpt() *wrapKeyOpts

NewOpt creates a new empty wrap key option. Not to be used directly. It's intended for implementations of Crypto interface Use WithSender() option function below instead.

Types

type Crypto

type Crypto interface {
	// Encrypt will encrypt msg and aad using a matching AEAD primitive in kh key handle of a public key
	// returns:
	// 		cipherText in []byte
	//		nonce in []byte
	//		error in case of errors during encryption
	Encrypt(msg, aad []byte, kh interface{}) ([]byte, []byte, error)
	// Decrypt will decrypt cipher with aad and given nonce using a matching AEAD primitive in kh key handle of a
	// private key
	// returns:
	//		plainText in []byte
	//		error in case of errors
	Decrypt(cipher, aad, nonce []byte, kh interface{}) ([]byte, error)
	// Sign will sign msg using a matching signature primitive in kh key handle of a private key
	// returns:
	// 		signature in []byte
	//		error in case of errors
	Sign(msg []byte, kh interface{}) ([]byte, error)
	// Verify will verify a signature for the given msg using a matching signature primitive in kh key handle of
	// a public key
	// returns:
	// 		error in case of errors or nil if signature verification was successful
	Verify(signature, msg []byte, kh interface{}) error
	// ComputeMAC computes message authentication code (MAC) for code data
	// using a matching MAC primitive in kh key handle
	ComputeMAC(data []byte, kh interface{}) ([]byte, error)
	// VerifyMAC determines if mac is a correct authentication code (MAC) for data
	// using a matching MAC primitive in kh key handle and returns nil if so, otherwise it returns an error.
	VerifyMAC(mac, data []byte, kh interface{}) error
	// WrapKey will execute key wrapping of cek using apu, apv and recipient public key 'recPubKey'.
	// 'opts' allows setting the optional sender key handle using WithSender() option and the an authentication tag
	// using WithTag() option. These allow ECDH-1PU key unwrapping (aka Authcrypt).
	// The absence of these options uses ECDH-ES key wrapping (aka Anoncrypt). Another option that can
	// be used is WithXC20PKW() to instruct the WrapKey to use XC20P key wrapping instead of the default A256GCM.
	// returns:
	// 		RecipientWrappedKey containing the wrapped cek value
	// 		error in case of errors
	WrapKey(cek, apu, apv []byte, recPubKey *PublicKey,
		opts ...WrapKeyOpts) (*RecipientWrappedKey, error)
	// UnwrapKey unwraps a key in recWK using recipient private key kh.
	// 'opts' allows setting the optional sender key handle using WithSender() option and the an authentication tag
	// using WithTag() option. These allow ECDH-1PU key unwrapping (aka Authcrypt).
	// The absence of these options uses ECDH-ES key unwrapping (aka Anoncrypt). There is no need to
	// use WithXC20PKW() for UnwrapKey since the function will use the wrapping algorithm based on recWK.Alg.
	// returns:
	// 		unwrapped key in raw bytes
	// 		error in case of errors
	UnwrapKey(recWK *RecipientWrappedKey, kh interface{}, opts ...WrapKeyOpts) ([]byte, error)
	// SignMulti will create a signature of messages using a matching signing primitive found in kh key handle of a
	// private key.
	// returns:
	// 		signature in []byte
	//		error in case of errors
	SignMulti(messages [][]byte, kh interface{}) ([]byte, error)
	// VerifyMulti will verify a signature of messages using a matching signing primitive found in kh key handle of a
	// public key.
	// returns:
	// 		error in case of errors or nil if signature verification was successful
	VerifyMulti(messages [][]byte, signature []byte, kh interface{}) error
	// VerifyProof will verify a signature proof (generated e.g. by Verifier's DeriveProof() call) for revealedMessages
	// using a matching signing primitive found in kh key handle of a public key.
	// returns:
	// 		error in case of errors or nil if signature proof verification was successful
	VerifyProof(revealedMessages [][]byte, proof, nonce []byte, kh interface{}) error
	// DeriveProof will create a signature proof for a list of revealed messages using BBS signature (can be built using
	// a Signer's SignMulti() call) and a matching signing primitive found in kh key handle of a public key.
	// returns:
	// 		signature proof in []byte
	//		error in case of errors
	DeriveProof(messages [][]byte, bbsSignature, nonce []byte, revealedIndexes []int, kh interface{}) ([]byte, error)
}

Crypto interface provides all crypto operations needed in the Aries framework.

type PrivateKey

type PrivateKey struct {
	PublicKey PublicKey `json:"pubKey,omitempty"`
	D         []byte    `json:"d,omitempty"`
}

PrivateKey mainly used to exchange ephemeral private key in JWE encrypter.

type PublicKey

type PublicKey struct {
	KID   string `json:"kid,omitempty"`
	X     []byte `json:"x,omitempty"`
	N     []byte `json:"n,omitempty"`
	E     []byte `json:"e,omitempty"`
	Y     []byte `json:"y,omitempty"`
	Curve string `json:"curve,omitempty"`
	Type  string `json:"type,omitempty"`
}

PublicKey mainly to exchange EPK in RecipientWrappedKey.

type RecipientWrappedKey

type RecipientWrappedKey struct {
	KID          string    `json:"kid,omitempty"`
	EncryptedCEK []byte    `json:"encryptedcek,omitempty"`
	EPK          PublicKey `json:"epk,omitempty"`
	Alg          string    `json:"alg,omitempty"`
	APU          []byte    `json:"apu,omitempty"`
	APV          []byte    `json:"apv,omitempty"`
}

RecipientWrappedKey contains recipient key material required to unwrap CEK.

type WrapKeyOpts

type WrapKeyOpts func(opts *wrapKeyOpts)

WrapKeyOpts are the crypto.Wrap key options.

func WithEPK

func WithEPK(epk *PrivateKey) WrapKeyOpts

WithEPK option is to instruct the key wrapping function of the ephemeral key to be used in the wrapping process. It is mainly used for ECDH-1PU during KDF. This option allows passing a predefined EPK instead of generating a new one when wrapping. It is useful for Wrap() call only since Unwrap() already uses a predefined EPK. The absence of this option means a new EPK will be generated internally.

func WithSender

func WithSender(senderKey interface{}) WrapKeyOpts

WithSender option is for setting a sender key with crypto wrapping (eg: AuthCrypt). For Anoncrypt, this option must not be set. Sender is a key used for ECDH-1PU key agreement for authenticating the sender. senderkey can be of the following there types:

• *keyset.Handle (requires private key handle for crypto.WrapKey())
• *crypto.PublicKey (available for UnwrapKey() only)
• *ecdsa.PublicKey (available for UnwrapKey() only)

func WithTag

func WithTag(tag []byte) WrapKeyOpts

WithTag option is to instruct the key wrapping function of the authentication tag to be used in the wrapping process. It is mainly used with CBC+HMAC content encryption to authenticate the sender of an encrypted JWE message (ie authcrypt/ECDH-1PU). The absence of this option means the sender's identity is not revealed (ie anoncrypt/ECDH-ES).

func WithXC20PKW

func WithXC20PKW() WrapKeyOpts

WithXC20PKW option is a flag option for crypto wrapping. When used, key wrapping will use XChacha20Poly1305 encryption as key wrapping. The absence of this option (default) uses AES256-GCM encryption as key wrapping. The KDF used in the crypto wrapping function is selected based on the type of recipient key argument of KeyWrap(), it is independent of this option.