keystorev4

README

go-keystorev4

Keystore v4, for BLS12-381 keys, following ERC-2335.

For hierarchical key-derivation (ERC-2333, ERC-2334), see github.com/protolambda/bls12-381-hd.

Warning: experimental, not audited

License

MIT, see LICENSE file.

Documentation

Index

• Variables
• func NormalizePassphrase(passphrase []byte) []byte
• type AES128CTRParams
  • func NewAES128CTRParams() (*AES128CTRParams, error)
  • func (a *AES128CTRParams) Decipher(cipherMsg []byte, decryptionKey []byte) (secret []byte, err error)
  • func (a *AES128CTRParams) Encipher(decryptionKey []byte, secret []byte) (cipherMsg []byte, err error)
  • func (a *AES128CTRParams) Function() string
• type ChecksumParams
• type CipherParams
• type HashChecksumParams
  • func (hc *HashChecksumParams) Checksum(decryptionKey []byte, cipherMessage []byte) ([]byte, error)
  • func (hc *HashChecksumParams) Function() string
• type JsonBytes
  • func (v *JsonBytes) MarshalText() ([]byte, error)
  • func (v *JsonBytes) UnmarshalText(text []byte) error
• type KDFParams
• type Keystore
  • func EncryptToKeystore(secret []byte, passphrase []byte) (*Keystore, error)
  • func (v *Keystore) Decrypt(passphrase []byte) (secret []byte, err error)
• type KeystoreChecksumModule
  • func (s *KeystoreChecksumModule) UnmarshalJSON(data []byte) error
• type KeystoreCipherModule
  • func (s *KeystoreCipherModule) UnmarshalJSON(data []byte) error
• type KeystoreCrypto
  • func Encrypt(secret []byte, passphrase []byte, kdfParams KDFParams, ...) (*KeystoreCrypto, error)
  • func (v *KeystoreCrypto) Decrypt(passphrase []byte) (secret []byte, err error)
• type KeystoreKDFModule
  • func (s *KeystoreKDFModule) UnmarshalJSON(data []byte) error
• type PBKDF2Params
  • func NewPBKDF2Params() (*PBKDF2Params, error)
  • func (sp *PBKDF2Params) DecryptionKey(normedPassphrase []byte) ([]byte, error)
  • func (sp *PBKDF2Params) Function() string
• type ScryptParams
  • func NewScryptParams() (*ScryptParams, error)
  • func (sp *ScryptParams) DecryptionKey(normedPassphrase []byte) ([]byte, error)
  • func (sp *ScryptParams) Function() string

Variables

var ChecksumMismatchErr = errors.New("checksum mismatch")

var Sha256ChecksumParams = &HashChecksumParams{Hasher: sha256.New, Name: "sha256"}

Functions

func NormalizePassphrase

func NormalizePassphrase(passphrase []byte) []byte

NormalizePassphrase transforms a passphrase for usage in the keystore.

The password is a string of arbitrary unicode characters. The password is first converted to its NFKD representation, then the control codes (specified below) are stripped from the password and finally it is UTF-8 encoded.

Stripped control codes: C0: 0x00 - 0x1F (inclusive) C1: 0x80 - 0x9F (inclusive) Delete: 7F

Types

type AES128CTRParams

type AES128CTRParams struct {
	IV JsonBytes `json:"iv"`
}

func NewAES128CTRParams

func NewAES128CTRParams() (*AES128CTRParams, error)

func (*AES128CTRParams) Decipher

func (a *AES128CTRParams) Decipher(cipherMsg []byte, decryptionKey []byte) (secret []byte, err error)

func (*AES128CTRParams) Encipher

func (a *AES128CTRParams) Encipher(decryptionKey []byte, secret []byte) (cipherMsg []byte, err error)

func (*AES128CTRParams) Function

func (a *AES128CTRParams) Function() string

type ChecksumParams

type ChecksumParams interface {
	// Computes the checksum
	Checksum(decryptionKey []byte, cipherMessage []byte) ([]byte, error)
	Function() string
}

type CipherParams

type CipherParams interface {
	Decipher(cipherMsg []byte, decryptionKey []byte) (secret []byte, err error)
	Encipher(decryptionKey []byte, secret []byte) (cipherMsg []byte, err error)
	Function() string
}

type HashChecksumParams

type HashChecksumParams struct {
	Hasher func() hash.Hash `json:"-"`
	// Name is already declared in the Function field
	Name string `json:"-"`
}

func (*HashChecksumParams) Checksum

func (hc *HashChecksumParams) Checksum(decryptionKey []byte, cipherMessage []byte) ([]byte, error)

func (*HashChecksumParams) Function

func (hc *HashChecksumParams) Function() string

type JsonBytes

type JsonBytes []byte

func (*JsonBytes) MarshalText

func (v *JsonBytes) MarshalText() ([]byte, error)

func (*JsonBytes) UnmarshalText

func (v *JsonBytes) UnmarshalText(text []byte) error

type KDFParams

type KDFParams interface {
	DecryptionKey(normedPassphrase []byte) ([]byte, error)
	Function() string
}

type Keystore

type Keystore struct {
	Crypto      KeystoreCrypto `json:"crypto"`
	Description string         `json:"description,omitempty"`
	Pubkey      JsonBytes      `json:"pubkey,omitempty"`
	// Path used in HD derivation.
	// EIP-2335 marks this as required field, but it may not exist, thus sometimes empty here.
	Path    string    `json:"path"`
	UUID    uuid.UUID `json:"uuid"`
	Version uint      `json:"version"`
}

Keystore as defined in EIP-2335, designed for BLS12-381 secret keys.

func EncryptToKeystore

func EncryptToKeystore(secret []byte, passphrase []byte) (*Keystore, error)

EncryptToKeystore encrypts a secret with the given passphrase, using the default parameters, new random 32-byte salts, PBKDF2 as KDF, AES-128-CTR as cipher, SHA-256 as checksum.

The keystore Description, Pubkey and Path fields are not initialized, and can be set by the caller.

func (*Keystore) Decrypt

func (v *Keystore) Decrypt(passphrase []byte) (secret []byte, err error)

Decrypts the given keystore (up to user to unmarshal from JSON), returns the secret The keystore version is validated, but Path and Pubkey are NOT.

type KeystoreChecksumModule

type KeystoreChecksumModule struct {
	Function string         `json:"function"`
	Params   ChecksumParams `json:"params"`
	Message  JsonBytes      `json:"message"`
}

func (*KeystoreChecksumModule) UnmarshalJSON

func (s *KeystoreChecksumModule) UnmarshalJSON(data []byte) error

type KeystoreCipherModule

type KeystoreCipherModule struct {
	Function string       `json:"function"`
	Params   CipherParams `json:"params"`
	Message  JsonBytes    `json:"message"`
}

func (*KeystoreCipherModule) UnmarshalJSON

func (s *KeystoreCipherModule) UnmarshalJSON(data []byte) error

type KeystoreCrypto

type KeystoreCrypto struct {
	KDF      KeystoreKDFModule      `json:"kdf"`
	Checksum KeystoreChecksumModule `json:"checksum"`
	Cipher   KeystoreCipherModule   `json:"cipher"`
}

func Encrypt

func Encrypt(secret []byte, passphrase []byte, kdfParams KDFParams, checksumParams ChecksumParams, cipherParams CipherParams) (*KeystoreCrypto, error)

func (*KeystoreCrypto) Decrypt

func (v *KeystoreCrypto) Decrypt(passphrase []byte) (secret []byte, err error)

type KeystoreKDFModule

type KeystoreKDFModule struct {
	Function string    `json:"function"`
	Params   KDFParams `json:"params"`
	Message  JsonBytes `json:"message"`
}

func (*KeystoreKDFModule) UnmarshalJSON

func (s *KeystoreKDFModule) UnmarshalJSON(data []byte) error

type PBKDF2Params

type PBKDF2Params struct {
	Dklen int       `json:"dklen"`
	C     int       `json:"c"`
	Prf   string    `json:"prf"`
	Salt  JsonBytes `json:"salt"`
}

func NewPBKDF2Params

func NewPBKDF2Params() (*PBKDF2Params, error)

func (*PBKDF2Params) DecryptionKey

func (sp *PBKDF2Params) DecryptionKey(normedPassphrase []byte) ([]byte, error)

func (*PBKDF2Params) Function

func (sp *PBKDF2Params) Function() string

type ScryptParams

type ScryptParams struct {
	Dklen int       `json:"dklen"`
	N     int       `json:"n"`
	P     int       `json:"p"`
	R     int       `json:"r"`
	Salt  JsonBytes `json:"salt"`
}

func NewScryptParams

func NewScryptParams() (*ScryptParams, error)

func (*ScryptParams) DecryptionKey

func (sp *ScryptParams) DecryptionKey(normedPassphrase []byte) ([]byte, error)

func (*ScryptParams) Function

func (sp *ScryptParams) Function() string