envelope

README

Hyperledger Fabric chaincode kit (CCKit) - Envelope extension

The envelope extension allows to pass additional data with the request to check user signature and protect from replay attacks. The extension is implemented as cckit middleware.

Envelope structure

The envelope is a structure that consists of the following attributes:

• public_key - signer public key (bytes)
• signature - payload signature (bytes)
• nonce - number is given for replay protection (string)
• hash_to_sign - payload hash (bytes)
• hash_func - function used for hashing (string)
• deadline - signature is not valid after deadline (timestamp)
• domain_separator - to prevent replay attacks from other domains (bytes)

How the envelope works

Sign the message and send the envelope (usually on the frontend)

1. Create the message to sign
2. Create the nonce
3. Hash the message with the nonce (sha-256)
4. Sign the hash (ed25519)
5. Create the envelope
6. Encode the envelope to base64
7. Send the envelope in request header (X-Envelop) if the cckit gateway is used
8. Get envelope in the cckit gateway, decode it from base64 and pack it as a third chaincode argument

Receive the envelope and verify the signature (chaincode)

1. Receive the envelope from request header
2. Decode the envelope from base64
3. Recreate the hash from the original message and the nonce (from envelope)
4. Verify the signature using pubkey from the envelope and the hash from the previous step

The sha-256 algorithm is used to hash the message.

The signature is generated using Ed25519.

How to use the envelope on chaincode

r := router.New(name).Pre(envelope.Verify)

Documentation

Index

• Constants
• Variables
• func CheckSig(payload []byte, nonce, channel, chaincode, method string, pubKey []byte, ...) error
• func CreateKeys() (ed25519.PublicKey, ed25519.PrivateKey, error)
• func CreateNonce() string
• func CreateSig(payload []byte, nonce, channel, chaincode, method string, privateKey []byte) ([]byte, []byte)
• func DecodeEnvelope(encEnvelope []byte) ([]byte, error)
• func EnvelopeMatcher(key string) (string, bool)
• func Hash(payload []byte, nonce, channel, chaincode, method string) [32]byte
• func Verify() router.MiddlewareFunc
• func WithEnvelope() gateway.Opt
• type Envelope
  • func (*Envelope) Descriptor() ([]byte, []int)
  • func (x *Envelope) GetChaincode() string
  • func (x *Envelope) GetChannel() string
  • func (x *Envelope) GetDeadline() *timestamppb.Timestamp
  • func (x *Envelope) GetHashFunc() string
  • func (x *Envelope) GetHashToSign() []byte
  • func (x *Envelope) GetMethod() string
  • func (x *Envelope) GetNonce() string
  • func (x *Envelope) GetPublicKey() []byte
  • func (x *Envelope) GetSignature() []byte
  • func (*Envelope) ProtoMessage()
  • func (x *Envelope) ProtoReflect() protoreflect.Message
  • func (x *Envelope) Reset()
  • func (x *Envelope) String() string

Constants

const HeaderKey = "X-Envelope"

Variables

var (
	ErrSignatureNotFound = errors.New(`signature not found`)

	ErrSignatureCheckFailed = errors.New(`check signature failed`)

	ErrDeadlineExpired = errors.New(`deadline expired`)

	ErrCheckSignatureFailed = errors.New(`check signature failed`)

	ErrTxAlreadyExecuted = errors.New(`tx already executed`)

	ErrInvalidMethod = errors.New(`invalid method in envelope`)

	ErrInvalidChannel = errors.New(`invalid channel in envelope`)
)

var File_envelope_envelope_proto protoreflect.FileDescriptor

Functions

func CheckSig

func CheckSig(payload []byte, nonce, channel, chaincode, method string, pubKey []byte, sig []byte) error

func CreateKeys

func CreateKeys() (ed25519.PublicKey, ed25519.PrivateKey, error)

func CreateNonce

func CreateNonce() string

func CreateSig

func CreateSig(payload []byte, nonce, channel, chaincode, method string, privateKey []byte) ([]byte, []byte)

func DecodeEnvelope

func DecodeEnvelope(encEnvelope []byte) ([]byte, error)

decode base64 envelop

func EnvelopeMatcher

func EnvelopeMatcher(key string) (string, bool)

handle custom header to pass envelope

func Hash

func Hash(payload []byte, nonce, channel, chaincode, method string) [32]byte

func Verify

func Verify() router.MiddlewareFunc

middleware for checking signature that is got in envelop

func WithEnvelope

func WithEnvelope() gateway.Opt

input opt for gateway to handle envelope with signature

Types

type Envelope

type Envelope struct {
	PublicKey  []byte                 `protobuf:"bytes,1,opt,name=public_key,json=publicKey,proto3" json:"public_key,omitempty"`      // signer public key
	Signature  []byte                 `protobuf:"bytes,2,opt,name=signature,proto3" json:"signature,omitempty"`                       // payload signature
	Nonce      string                 `protobuf:"bytes,3,opt,name=nonce,proto3" json:"nonce,omitempty"`                               // number is given for replay protection
	HashToSign []byte                 `protobuf:"bytes,4,opt,name=hash_to_sign,json=hashToSign,proto3" json:"hash_to_sign,omitempty"` // payload hash
	HashFunc   string                 `protobuf:"bytes,5,opt,name=hash_func,json=hashFunc,proto3" json:"hash_func,omitempty"`         // function used for hashing
	Deadline   *timestamppb.Timestamp `protobuf:"bytes,6,opt,name=deadline,proto3" json:"deadline,omitempty"`                         // signature is not valid after deadline (EIP-2612)
	// channel + chaincode + method are used as domain separator to prevent replay attack from other domains (EIP-2612)
	Channel   string `protobuf:"bytes,7,opt,name=channel,proto3" json:"channel,omitempty"`
	Chaincode string `protobuf:"bytes,8,opt,name=chaincode,proto3" json:"chaincode,omitempty"`
	Method    string `protobuf:"bytes,9,opt,name=method,proto3" json:"method,omitempty"`
	// contains filtered or unexported fields
}

func (*Envelope) Descriptor

func (*Envelope) Descriptor() ([]byte, []int)

Deprecated: Use Envelope.ProtoReflect.Descriptor instead.

func (*Envelope) GetChaincode

func (x *Envelope) GetChaincode() string

func (*Envelope) GetChannel

func (x *Envelope) GetChannel() string

func (*Envelope) GetDeadline

func (x *Envelope) GetDeadline() *timestamppb.Timestamp

func (*Envelope) GetHashFunc

func (x *Envelope) GetHashFunc() string

func (*Envelope) GetHashToSign

func (x *Envelope) GetHashToSign() []byte

func (*Envelope) GetMethod

func (x *Envelope) GetMethod() string

func (*Envelope) GetNonce

func (x *Envelope) GetNonce() string

func (*Envelope) GetPublicKey

func (x *Envelope) GetPublicKey() []byte

func (*Envelope) GetSignature

func (x *Envelope) GetSignature() []byte

func (*Envelope) ProtoMessage

func (*Envelope) ProtoMessage()

func (*Envelope) ProtoReflect

func (x *Envelope) ProtoReflect() protoreflect.Message

func (*Envelope) Reset

func (x *Envelope) Reset()

func (*Envelope) String

func (x *Envelope) String() string