idmgr

Documentation

Overview

Package idmgr is a key manager designed for use with bmagent, but which can also be used independently. It handles and handles hierarchically deterministic keys, imported keys (from PyBitmessage or other legacy systems), as well as channels.

The file format for storage is a JSON document encrypted with SalsaX20 and MAC'd with Poly1305. The scheme used is byte compatible with secretbox from NaCl. Currently, it supports encrypting the entire file containing identity information (encryption and signing keys, required PoW constants, etc) and master key.

Future support for separately encrypting master key and signing keys is planned. This could be useful for:

• Read only bmclient nodes that are intended to only receive and decrypt messages bound for them and are not likely to be used for sending messages.
• Security conscious users who might be worried about memory-reading malware. Note that even if we configure bmclient as such, the malware would still be able to get the user's private encryption key. By the very nature of Bitmessage, private encryption keys need to be in memory all the time.

The contents of the encrypted file are arranged as such: Nonce (24 bytes) || Salt for PBKDF2 (32 bytes) || Encrypted data

Both the nonce and salt are re-generated each time the file needs to be saved. This, along with a high number of PBKDF2 iterations (2^15), helps to ensure that an adversary with access to the key file will have an extremely hard time trying to bruteforce it. Rainbow tables will be useless.

WARNING (again): The key manager is insecure against memory reading malware

and is at the mercy of Go's garbage collector.

Index

• Variables
• type Manager
  • func FromEncrypted(enc, pass []byte) (*Manager, error)
  • func FromPlaintext(r io.Reader) (*Manager, error)
  • func New(seed []byte) (*Manager, error)
  • func (mgr *Manager) Addresses() []string
  • func (mgr *Manager) ExportEncrypted(pass []byte) ([]byte, error)
  • func (mgr *Manager) ExportPlaintext() ([]byte, error)
  • func (mgr *Manager) ForEach(f func(*keys.PrivateID) error) error
  • func (mgr *Manager) Get(address string) *keys.PrivateID
  • func (mgr *Manager) ImportIdentity(privID keys.PrivateID)
  • func (mgr *Manager) ImportKeys(data []byte) map[string]string
  • func (mgr *Manager) ImportKeysFromPyBitmessage(f ini.File) map[string]string
  • func (mgr *Manager) NameAddress(address, name string) error
  • func (mgr *Manager) Names() map[string]string
  • func (mgr *Manager) New(name string, stream uint64, behavior uint32) *keys.PrivateID
  • func (mgr *Manager) NewUnnamed(stream uint64, behavior uint32) *keys.PrivateID
  • func (mgr *Manager) NumDeterministic() int
  • func (mgr *Manager) NumImported() int
  • func (mgr *Manager) Size() int
  • func (mgr *Manager) UnnameAddress(address string) error

Variables

var (
	// ErrDecryptionFailed is returned when decryption of the key file fails.
	// This could be due to invalid passphrase or corrupt/tampered data.
	ErrDecryptionFailed = errors.New("invalid passphrase")

	// ErrDuplicateIdentity is returned by Import when the identity to be
	// imported already exists in the key manager.
	ErrDuplicateIdentity = errors.New("identity already in key manager")

	// ErrNonexistentIdentity is returned when the identity doesn't exist in the
	// key manager.
	ErrNonexistentIdentity = errors.New("identity doesn't exist")
)

var (
	// ErrUnknownKeyfileVersion  is returned when the version of the keyfile is
	// unknown. Maybe we are using a newer keyfile with an older bmclient.
	ErrUnknownKeyfileVersion = errors.New("unknown keyfile version")
)

Types

type Manager

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

Manager is the key manager used for managing imported as well as hierarchically deterministic keys. It is safe for access from multiple goroutines.

func FromEncrypted

func FromEncrypted(enc, pass []byte) (*Manager, error)

FromEncrypted creates a new Manager object from the specified encrypted data and passphrase. The actual key used for decryption is derived from the salt, which is a part of enc, and the passphrase using PBKDF2.

func FromPlaintext

func FromPlaintext(r io.Reader) (*Manager, error)

FromPlaintext imports a key manager from plaintext.

func New

func New(seed []byte) (*Manager, error)

New creates a new key manager and generates a master key from the provided seed. The seed must be between 128 and 512 bits and should be generated by a cryptographically secure random generation source. Refer to docs for hdkeychain.NewMaster and hdkeychain.GenerateSeed for more info.

func (*Manager) Addresses

func (mgr *Manager) Addresses() []string

Addresses returns the set of addresses in the key manager.

func (*Manager) ExportEncrypted

func (mgr *Manager) ExportEncrypted(pass []byte) ([]byte, error)

ExportEncrypted encrypts the current state of the key manager with the specified password and returns it. The salt used as input to PBKDF2 as well as nonce for input to secretbox are randomly generated. The actual key used for encryption is derived from the salt and the passphrase using PBKDF2.

func (*Manager) ExportPlaintext

func (mgr *Manager) ExportPlaintext() ([]byte, error)

ExportPlaintext exports the state of the key manager in an unencrypted state. It's useful for debugging or manual inspection of keys.

func (*Manager) ForEach

func (mgr *Manager) ForEach(f func(*keys.PrivateID) error) error

ForEach runs the specified function for all the identities stored in the key manager. It does not return until the function has been invoked for all keys and breaks early on error.

func (*Manager) Get

func (mgr *Manager) Get(address string) *keys.PrivateID

Get looks up a private identity in the key manager by its address. If no matching identity can be found, ErrNonexistentIdentity is returned.

func (*Manager) ImportIdentity

func (mgr *Manager) ImportIdentity(privID keys.PrivateID)

ImportIdentity imports an existing identity into the key manager. It's useful for users who have existing identities or want to subscribe to channels.

func (*Manager) ImportKeys

func (mgr *Manager) ImportKeys(data []byte) map[string]string

ImportKeys import skeys from Pybitmessage or another bmagent identity. Returns a map containing the imported addresses and names.

func (*Manager) ImportKeysFromPyBitmessage

func (mgr *Manager) ImportKeysFromPyBitmessage(f ini.File) map[string]string

ImportKeysFromPyBitmessage given an ini file like that created by PyBitmessage, import into the key manager. TODO test this function with a more current PyBitmessage file format.

func (*Manager) NameAddress

func (mgr *Manager) NameAddress(address, name string) error

NameAddress names an address.

func (*Manager) Names

func (mgr *Manager) Names() map[string]string

Names returns the map of addresses to names.

func (*Manager) New

func (mgr *Manager) New(name string, stream uint64, behavior uint32) *keys.PrivateID

New generates a new HD identity and numbers it based on previously derived identities. If 2^32 identities have already been generated, new identities would be duplicates because of overflow problems.

func (*Manager) NewUnnamed

func (mgr *Manager) NewUnnamed(stream uint64, behavior uint32) *keys.PrivateID

NewUnnamed returns a new unnamed key.

func (*Manager) NumDeterministic

func (mgr *Manager) NumDeterministic() int

NumDeterministic returns the number of identities that have been created deterministically (according to BIP-BM01).

func (*Manager) NumImported

func (mgr *Manager) NumImported() int

NumImported returns the number of imported identities that the key manager has in the database.

func (*Manager) Size

func (mgr *Manager) Size() int

Size returns the size of the key manager.

func (*Manager) UnnameAddress

func (mgr *Manager) UnnameAddress(address string) error

UnnameAddress removes a name from the address.