cryptutil

README

cryptutil

Some tools for handling common crypto tasks not found in the go standard library

ECDH Message encryption

Sometimes you want to send a message. Sometimes you want it encrypted. Sending an encrypted message to a ECDSA key can be painful and come with all sorts of difficulties.

This library aims to provide a simple encryption/decryption scheme that just takes a plaintext and a key and returns an encrypted string.

The decryption function accepts any kind of ECDH handler, allowing the actual private key to be stored into a TPM or a HSM.

Bottle

Bottles are containers for arbitrary data (json, cbor, anything) that can be used to add any number of signatures, encryption layers etc to the underlying message, while keeping recovery of the original message fairly easy.

// Create a new bottle with a message inside
bottle := cryptutil.NewBottle([]byte("s.o.s. to the world"))

// encrypt for Alice OR Bob (either will be able to open the bottle)
bottle.Encrypt(bob.Public(), alice.Public())
bottle.BottleUp() // bottle in a bottle, so that the signature includes the encryption
bottle.Sign(alice) // sign from Alice

// Bob is opening the bottle
opener, err := cryptutil.NewOpener(bob)
res, info, err := opener.Open(bottle)
// first, check err to see if opening the bottle was successful
// Then you can inspect info to see which signatures were verified, and how many
// layers of encryption were decrypted

ID Card

ID Cards can be used by entities with a signing key to provide alternate encryption keys.

Documentation

Index

• Variables
• func DecryptShortBuffer(k []byte, rcvd any) ([]byte, error)
• func ECDHDecrypt(data []byte, privateKey ECDHHandler) ([]byte, error)
• func ECDHEncrypt(data []byte, remote *ecdh.PublicKey, rnd io.Reader) ([]byte, error)
• func EncryptShortBuffer(k []byte, rcvd crypto.PublicKey) ([]byte, error)
• func Hash(b []byte, alg ...func() hash.Hash) []byte
• func MemClr(b []byte)
• type Bottle
  • func AsCborBottle(data []byte) *Bottle
  • func AsJsonBottle(data []byte) *Bottle
  • func NewBottle(data []byte) *Bottle
  • func (m *Bottle) BottleUp() error
  • func (m *Bottle) Encrypt(recipients ...crypto.PublicKey) error
  • func (m *Bottle) IsCleanBottle() bool
  • func (m *Bottle) Sign(key crypto.Signer) error
• type ECDHHandler
• type IDCard
  • func NewIDCard(k crypto.PublicKey) (*IDCard, error)
  • func (id *IDCard) GetKeys(purpose string) []crypto.PublicKey
  • func (id *IDCard) SetKeyDuration(k crypto.PublicKey, t time.Duration) error
  • func (id *IDCard) SetKeyPurposes(k crypto.PublicKey, purposes ...string) error
  • func (id *IDCard) Sign(k crypto.Signer) ([]byte, error)
  • func (id *IDCard) UnmarshalBinary(b []byte) error
• type MessageFormat
• type MessageRecipient
  • func (r *MessageRecipient) OpenWith(k any) ([]byte, error)
• type MessageSignature
  • func (sig *MessageSignature) Verify(buf []byte) error
• type OpenResult
• type Opener
  • func NewOpener(keys ...any) (*Opener, error)
  • func (o *Opener) Open(b *Bottle) ([]byte, *OpenResult, error)
  • func (o *Opener) OpenCbor(b []byte) ([]byte, *OpenResult, error)
  • func (o *Opener) OpenJson(b []byte) ([]byte, *OpenResult, error)
• type SubKey

Variables

var (
	ErrNoAppropriateKey = errors.New("no appropriate key available to open bottle")
)

Functions

func DecryptShortBuffer

func DecryptShortBuffer(k []byte, rcvd any) ([]byte, error)

DecryptShortBuffer decrypts a given buffer

func ECDHDecrypt

func ECDHDecrypt(data []byte, privateKey ECDHHandler) ([]byte, error)

ECDHDecrypt decrypts data received for us, using the private key passed (can be a tpm, etc)

func ECDHEncrypt

func ECDHEncrypt(data []byte, remote *ecdh.PublicKey, rnd io.Reader) ([]byte, error)

ECDHEncrypt encrypts data for receiving by remote

func EncryptShortBuffer

func EncryptShortBuffer(k []byte, rcvd crypto.PublicKey) ([]byte, error)

EncryptShortBuffer performs a simple encryption of a buffer

func Hash

func Hash(b []byte, alg ...func() hash.Hash) []byte

Hash is a helper function to perform hashes on buffers, including multi-level hashing

func MemClr

func MemClr(b []byte)

Types

type Bottle

type Bottle struct {
	Header     map[string]any      `json:"hdr,omitempty"` // extra values to be stored, will not be signed/encrypted unless the message is bottled
	Message    []byte              `json:"msg"`
	Format     MessageFormat       `json:"fmt"`
	Recipients []*MessageRecipient `json:"dst,omitempty"` // if Format != ClearText
	Signatures []*MessageSignature `json:"sig,omitempty"` // signature
	// contains filtered or unexported fields
}

Bottle is a signed, encrypted message container. Any Format other than ClearText means the Message contains a Bottle that has been encrypted.

func AsCborBottle

func AsCborBottle(data []byte) *Bottle

AsCborBottle considers data to be a cbor-encoded Bottle, and will return a Bottle container matching this assumption

func AsJsonBottle

func AsJsonBottle(data []byte) *Bottle

AsJsonBottle considers data to be a json-encoded Bottle, and will return a Bottle container matching this assumption

func NewBottle

func NewBottle(data []byte) *Bottle

NewBottle will return a new clean bottle only containing the provided data

func (*Bottle) BottleUp

func (m *Bottle) BottleUp() error

BottleUp encodes the current message into itself, allowing application of extra layers

func (*Bottle) Encrypt

func (m *Bottle) Encrypt(recipients ...crypto.PublicKey) error

Encrypt encrypts the message so only recipients can decrypt it

func (*Bottle) IsCleanBottle

func (m *Bottle) IsCleanBottle() bool

IsCleanBottle returns true if the Bottle is clean (ie. so signature has been scribbed on top) and contains another Bottle.

func (*Bottle) Sign

func (m *Bottle) Sign(key crypto.Signer) error

Sign signs the message, and can be called multiple times. Any message can be signed, including a raw message. It is however recommanded to bottle up an encrypted message before signing in order to ensure the encryption information is signed too.

Attempting to apply encryption to a message with a signature will always cause it to be bottled up

type ECDHHandler

type ECDHHandler interface {
	ECDH(remote *ecdh.PublicKey) ([]byte, error)
}

type IDCard

type IDCard struct {
	Self    []byte    `json:"self" cbor:"1,keyasint"` // our own public key (PKIX)
	Issued  time.Time `json:"iss" cbor:"2,keyasint"`  // issuance date. If two IDCard exist for the same public key, the most recent one will be taken into account
	SubKeys []*SubKey `json:"sub" cbor:"3,keyasint"`  // known sub keys
	Revoke  []*SubKey `json:"rev" cbor:"4,keyasint"`  // any key into the revoke list will be strongly rejected
}

IDCard is a basic ID for a given signature key that allows it to specify keys that can be used for encryption/etc

func NewIDCard

func NewIDCard(k crypto.PublicKey) (*IDCard, error)

NewIDCard generates a new ID card for the given public key

func (*IDCard) GetKeys

func (id *IDCard) GetKeys(purpose string) []crypto.PublicKey

func (*IDCard) SetKeyDuration

func (id *IDCard) SetKeyDuration(k crypto.PublicKey, t time.Duration) error

SetKeyDuration specifies the duration for the given key

func (*IDCard) SetKeyPurposes

func (id *IDCard) SetKeyPurposes(k crypto.PublicKey, purposes ...string) error

SetKeyPurposes specifies the purpose of a given key (sign, decrypt, etc)

func (*IDCard) Sign

func (id *IDCard) Sign(k crypto.Signer) ([]byte, error)

Sign will return a signed bottle containing this ID Card

func (*IDCard) UnmarshalBinary

func (id *IDCard) UnmarshalBinary(b []byte) error

UnmarshalBinary will read a signed ID card, returning an error if it wasn't signed

type MessageFormat

type MessageFormat int

const (
	ClearText  MessageFormat = iota
	CborBottle               // bottle in a bottle
	AES                      // AES+AEAD encrypted cbor bottle
	JsonBottle               // bottle in a bottle (json version)
)

type MessageRecipient

type MessageRecipient struct {
	Type      int    `json:"typ,omitempty"` // always 0 (for now)
	Recipient []byte `json:"key"`           // recipient's public key
	Data      []byte `json:"dat"`           // encrypted key payload (only recipient's eyes)
	// contains filtered or unexported fields
}

func (*MessageRecipient) OpenWith

func (r *MessageRecipient) OpenWith(k any) ([]byte, error)

type MessageSignature

type MessageSignature struct {
	Type   int    `json:"typ,omitempty"` // always 0 (for now)
	Signer []byte `json:"key"`           // signature's key
	Data   []byte `json:"dat"`           // signature payload, similar format to jwt (NOTE: ECDSA signatures are weird)
	// contains filtered or unexported fields
}

func (*MessageSignature) Verify

func (sig *MessageSignature) Verify(buf []byte) error

type OpenResult

type OpenResult struct {
	Decryption int                 // number of performed decryptions
	Signatures []*MessageSignature // verified message signatures
	Bottles    []*Bottle
}

type Opener

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

Opener allows opening a Bottle

func NewOpener

func NewOpener(keys ...any) (*Opener, error)

func (*Opener) Open

func (o *Opener) Open(b *Bottle) ([]byte, *OpenResult, error)

Open opens the given Bottle, decrypting any encrypted elements, checking all signatures and returning the embedded buffer in the end

func (*Opener) OpenCbor

func (o *Opener) OpenCbor(b []byte) ([]byte, *OpenResult, error)

OpenCbor opens the given Bottle encoded as cbor data.

func (*Opener) OpenJson

func (o *Opener) OpenJson(b []byte) ([]byte, *OpenResult, error)

OpenJson opens the given Bottle encoded as json data.

type SubKey

type SubKey struct {
	Key      []byte     `json:"key" cbor:"1,keyasint"`                     // public key as PKIX
	Issued   time.Time  `json:"iss" cbor:"2,keyasint"`                     // issuance (addition) date
	Expires  *time.Time `json:"exp,omitempty" cbor:"3,keyasint,omitempty"` // expiration date (if any)
	Purposes []string   `json:"pur" cbor:"4,keyasint"`                     // purposes: can contain "sign", "decrypt"
}

SubKey is a key found in a given id card