keys

package
v0.39.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 4, 2021 License: Apache-2.0 Imports: 26 Imported by: 0

README

Keys API

API Reference

The Keybase interface

The Keybase interface defines the methods that a type needs to implement to be used as key storage backend. This package provides few implementations out-of-the-box.

Constructors

New

The New constructor returns an on-disk implementation backed by LevelDB storage that has been the default implementation used by the SDK until v0.38.0. Due to security concerns, we recommend to drop it in favor of the NewKeyring or NewKeyringFile constructors. We strongly advise to migrate away from this function as it may be removed in a future release.

NewInMemory

The NewInMemory constructor returns an implementation backed by an in-memory, goroutine-safe map that we've historically used for testing purposes or on-the-fly key generation and we consider safe for the aforementioned use cases since the generated keys are discarded when the process terminates or the type instance is garbage collected.

NewKeyring

The NewKeyring constructor returns an implementation backed by the Keyring library, whose aim is to provide a common abstraction and uniform interface between secret stores available for Windows, macOS, and most GNU/Linux distributions. The instance returned by this constructor will use the operating system's default credentials store, which will then handle keys storage operations securely.

NewKeyringFile, NewTestKeyring

Both NewKeyringFile and NewTestKeyring constructors return on-disk implementations backed by the Keyring file backend. Whilst NewKeyringFile returns a secure, encrypted file-based type that requires user's password in order to function correctly, the implementation returned by NewTestKeyring stores keys information in clear text and must be used only for testing purposes.

NewKeyringFile and NewTestKeyring store key files in the client home directory's keyring and keyring-test subdirectories respectively.

Documentation

Index

Examples

Constants

View Source 
const (
	BackendFile    = "file"
	BackendOS      = "os"
	BackendKWallet = "kwallet"
	BackendPass    = "pass"
	BackendTest    = "test"
)
View Source 
const (
	// MultiAlgo implies that a pubkey is a multisignature
	MultiAlgo = SigningAlgo("multi")
	// Secp256k1 uses the Bitcoin secp256k1 ECDSA parameters.
	Secp256k1 = SigningAlgo("secp256k1")
	// Ed25519 represents the Ed25519 signature system.
	// It is currently not supported for end-user keys (wallets/ledgers).
	Ed25519 = SigningAlgo("ed25519")
	// Sr25519 represents the Sr25519 signature system.
	Sr25519 = SigningAlgo("sr25519")
)
View Source 
const (
	// used for deriving seed from mnemonic
	DefaultBIP39Passphrase = ""
)

Variables

View Source 
var (
	// ErrUnsupportedSigningAlgo is raised when the caller tries to use a
	// different signing scheme than secp256k1.
	ErrUnsupportedSigningAlgo = errors.New("unsupported signing algo")

	// ErrUnsupportedLanguage is raised when the caller tries to use a
	// different language than english for creating a mnemonic sentence.
	ErrUnsupportedLanguage = errors.New("unsupported language: only english is supported")
)
View Source 
var CryptoCdc *codec.Codec

CryptoCdc defines the codec required for keys and info

Functions

func CreateHDPath 

func CreateHDPath(account uint32, index uint32) *hd.BIP44Params

CreateHDPath returns BIP 44 object from account and index parameters.

func IsSupportedAlgorithm 

func IsSupportedAlgorithm(supported []SigningAlgo, algo SigningAlgo) bool

IsSupportedAlgorithm returns whether the signing algorithm is in the passed-in list of supported algorithms.

func RegisterCodec 

func RegisterCodec(cdc *codec.Codec)

RegisterCodec registers concrete types and interfaces on the given codec.

func SecpDeriveKey 

func SecpDeriveKey(mnemonic string, bip39Passphrase, hdPath string) ([]byte, error)

SecpDeriveKey derives and returns the secp256k1 private key for the given seed and HD path.

func SecpPrivKeyGen 

func SecpPrivKeyGen(bz []byte) tmcrypto.PrivKey

SecpPrivKeyGen generates a secp256k1 private key from the given bytes

func StdDeriveKey 

func StdDeriveKey(mnemonic string, bip39Passphrase, hdPath string, algo SigningAlgo) ([]byte, error)

StdDeriveKey is the default DeriveKey function in the keybase. For now, it only supports Secp256k1

func StdPrivKeyGen 

func StdPrivKeyGen(bz []byte, algo SigningAlgo) (tmcrypto.PrivKey, error)

StdPrivKeyGen is the default PrivKeyGen function in the keybase. For now, it only supports Secp256k1

Types

type DeriveKeyFunc 

type DeriveKeyFunc func(mnemonic string, bip39Passphrase, hdPath string, algo SigningAlgo) ([]byte, error)

DeriveKeyFunc defines the function to derive a new key from a seed and hd path

type Info 

type Info interface {
	// Human-readable type for key listing
	GetType() KeyType
	// Name of the key
	GetName() string
	// Public key
	GetPubKey() crypto.PubKey
	// Address
	GetAddress() types.AccAddress
	// Bip44 Path
	GetPath() (*hd.BIP44Params, error)
	// Algo
	GetAlgo() SigningAlgo
}

Info is the publicly exposed information about a keypair

func NewMultiInfo 

func NewMultiInfo(name string, pub crypto.PubKey) Info

NewMultiInfo creates a new multiInfo instance

type KeyOutput 

type KeyOutput struct {
	Name      string                 `json:"name" yaml:"name"`
	Type      string                 `json:"type" yaml:"type"`
	Address   string                 `json:"address" yaml:"address"`
	PubKey    string                 `json:"pubkey" yaml:"pubkey"`
	Mnemonic  string                 `json:"mnemonic,omitempty" yaml:"mnemonic"`
	Threshold uint                   `json:"threshold,omitempty" yaml:"threshold"`
	PubKeys   []multisigPubKeyOutput `json:"pubkeys,omitempty" yaml:"pubkeys"`
}

KeyOutput defines a structure wrapping around an Info object used for output functionality.

func Bech32ConsKeyOutput 

func Bech32ConsKeyOutput(keyInfo Info) (KeyOutput, error)

Bech32ConsKeyOutput create a KeyOutput in with "cons" Bech32 prefixes.

func Bech32KeyOutput 

func Bech32KeyOutput(keyInfo Info) (KeyOutput, error)

Bech32KeyOutput create a KeyOutput in with "acc" Bech32 prefixes. If the public key is a multisig public key, then the threshold and constituent public keys will be added.

func Bech32KeysOutput 

func Bech32KeysOutput(infos []Info) ([]KeyOutput, error)

Bech32KeysOutput returns a slice of KeyOutput objects, each with the "acc" Bech32 prefixes, given a slice of Info objects. It returns an error if any call to Bech32KeyOutput fails.

func Bech32ValKeyOutput 

func Bech32ValKeyOutput(keyInfo Info) (KeyOutput, error)

Bech32ValKeyOutput create a KeyOutput in with "val" Bech32 prefixes.

func NewKeyOutput 

func NewKeyOutput(name, keyType, address, pubkey string) KeyOutput

NewKeyOutput creates a default KeyOutput instance without Mnemonic, Threshold and PubKeys

type KeyType 

type KeyType uint

KeyType reflects a human-readable type for key listing. 

const (
	TypeLocal   KeyType = 0
	TypeLedger  KeyType = 1
	TypeOffline KeyType = 2
	TypeMulti   KeyType = 3
)

Info KeyTypes

func (KeyType) String 

func (kt KeyType) String() string

String implements the stringer interface for KeyType.

type Keybase 

type Keybase interface {
	// CRUD on the keystore
	List() ([]Info, error)
	// Get returns the public information about one key.
	Get(name string) (Info, error)
	// Get performs a by-address lookup and returns the public
	// information about one key if there's any.
	GetByAddress(address types.AccAddress) (Info, error)
	// Delete removes a key.
	Delete(name, passphrase string, skipPass bool) error
	// Sign bytes, looking up the private key to use.
	Sign(name, passphrase string, msg []byte) ([]byte, crypto.PubKey, error)

	// CreateMnemonic generates a new mnemonic, derives a hierarchical deterministic
	// key from that. and persists it to storage, encrypted using the provided password.
	// It returns the generated mnemonic and the key Info. It returns an error if it fails to
	// generate a key for the given algo type, or if another key is already stored under the
	// same name.
	CreateMnemonic(name string, language Language, passwd string, algo SigningAlgo) (info Info, seed string, err error)

	// CreateAccount converts a mnemonic to a private key and BIP 32 HD Path
	// and persists it, encrypted with the given password.
	CreateAccount(name, mnemonic, bip39Passwd, encryptPasswd, hdPath string, algo SigningAlgo) (Info, error)

	// CreateLedger creates, stores, and returns a new Ledger key reference
	CreateLedger(name string, algo SigningAlgo, hrp string, account, index uint32) (info Info, err error)

	// CreateOffline creates, stores, and returns a new offline key reference
	CreateOffline(name string, pubkey crypto.PubKey, algo SigningAlgo) (info Info, err error)

	// CreateMulti creates, stores, and returns a new multsig (offline) key reference
	CreateMulti(name string, pubkey crypto.PubKey) (info Info, err error)

	// The following operations will *only* work on locally-stored keys
	Update(name, oldpass string, getNewpass func() (string, error)) error

	// Import imports ASCII armored Info objects.
	Import(name string, armor string) (err error)

	// ImportPrivKey imports a private key in ASCII armor format.
	// It returns an error if a key with the same name exists or a wrong encryption passphrase is
	// supplied.
	ImportPrivKey(name, armor, passphrase string) error

	// ImportPubKey imports ASCII-armored public keys.
	// Store a new Info object holding a public key only, i.e. it will
	// not be possible to sign with it as it lacks the secret key.
	ImportPubKey(name string, armor string) (err error)

	// Export exports an Info object in ASCII armored format.
	Export(name string) (armor string, err error)

	// ExportPubKey returns public keys in ASCII armored format.
	// Retrieve a Info object by its name and return the public key in
	// a portable format.
	ExportPubKey(name string) (armor string, err error)

	// ExportPrivKey returns a private key in ASCII armored format.
	// It returns an error if the key does not exist or a wrong encryption passphrase is supplied.
	ExportPrivKey(name, decryptPassphrase, encryptPassphrase string) (armor string, err error)

	// ExportPrivateKeyObject *only* works on locally-stored keys. Temporary method until we redo the exporting API
	ExportPrivateKeyObject(name string, passphrase string) (crypto.PrivKey, error)

	// SupportedAlgos returns a list of signing algorithms supported by the keybase
	SupportedAlgos() []SigningAlgo

	// SupportedAlgosLedger returns a list of signing algorithms supported by the keybase's ledger integration
	SupportedAlgosLedger() []SigningAlgo

	// CloseDB closes the database.
	CloseDB()
}

Keybase exposes operations on a generic keystore

func New 

func New(name, dir string, opts ...KeybaseOption) Keybase

New creates a new instance of a lazy keybase.

Example 
// Select the encryption and storage for your cryptostore
customKeyGenFunc := func(bz []byte, algo SigningAlgo) (crypto.PrivKey, error) {
	var bzArr [32]byte
	copy(bzArr[:], bz)
	return secp256k1.PrivKeySecp256k1(bzArr), nil
}
cstore := NewInMemory(WithKeygenFunc(customKeyGenFunc))

sec := Secp256k1

// Add keys and see they return in alphabetical order
bob, _, err := cstore.CreateMnemonic("Bob", English, "friend", sec)
if err != nil {
	// this should never happen
	fmt.Println(err)
} else {
	// return info here just like in List
	fmt.Println(bob.GetName())
}
_, _, _ = cstore.CreateMnemonic("Alice", English, "secret", sec)
_, _, _ = cstore.CreateMnemonic("Carl", English, "mitm", sec)
info, _ := cstore.List()
for _, i := range info {
	fmt.Println(i.GetName())
}

// We need to use passphrase to generate a signature
tx := []byte("deadbeef")
sig, pub, err := cstore.Sign("Bob", "friend", tx)
if err != nil {
	fmt.Println("don't accept real passphrase")
}

// and we can validate the signature with publicly available info
binfo, _ := cstore.Get("Bob")
if !binfo.GetPubKey().Equals(bob.GetPubKey()) {
	fmt.Println("Get and Create return different keys")
}

if pub.Equals(binfo.GetPubKey()) {
	fmt.Println("signed by Bob")
}
if !pub.VerifyBytes(tx, sig) {
	fmt.Println("invalid signature")
}

Output:

Bob
Alice
Bob
Carl
signed by Bob

func NewInMemory 

func NewInMemory(opts ...KeybaseOption) Keybase

NewInMemory creates a transient keybase on top of in-memory storage instance useful for testing purposes and on-the-fly key generation. Keybase options can be applied when generating this new Keybase.

func NewKeyring 

func NewKeyring(
	appName, backend, rootDir string, userInput io.Reader, opts ...KeybaseOption,
) (Keybase, error)

NewKeyring creates a new instance of a keyring. Keybase options can be applied when generating this new Keybase. Available backends are "os", "file", "test".

type KeybaseOption 

type KeybaseOption func(*kbOptions)

KeybaseOption overrides options for the db

func WithDeriveFunc 

func WithDeriveFunc(f DeriveKeyFunc) KeybaseOption

WithDeriveFunc applies an overridden key derivation function to generate the private key.

func WithKeygenFunc 

func WithKeygenFunc(f PrivKeyGenFunc) KeybaseOption

WithKeygenFunc applies an overridden key generation function to generate the private key.

func WithSupportedAlgos 

func WithSupportedAlgos(algos []SigningAlgo) KeybaseOption

WithSupportedAlgos defines the list of accepted SigningAlgos.

func WithSupportedAlgosLedger 

func WithSupportedAlgosLedger(algos []SigningAlgo) KeybaseOption

WithSupportedAlgosLedger defines the list of accepted SigningAlgos compatible with Ledger.

type Language 

type Language int

Language is a language to create the BIP 39 mnemonic in. Currently, only english is supported though. Find a list of all supported languages in the BIP 39 spec (word lists). 

const (
	// English is the default language to create a mnemonic.
	// It is the only supported language by this package.
	English Language = iota + 1
	// Japanese is currently not supported.
	Japanese
	// Korean is currently not supported.
	Korean
	// Spanish is currently not supported.
	Spanish
	// ChineseSimplified is currently not supported.
	ChineseSimplified
	// ChineseTraditional is currently not supported.
	ChineseTraditional
	// French is currently not supported.
	French
	// Italian is currently not supported.
	Italian
)

noinspection ALL

type PrivKeyGenFunc 

type PrivKeyGenFunc func(bz []byte, algo SigningAlgo) (crypto.PrivKey, error)

PrivKeyGenFunc defines the function to convert derived key bytes to a tendermint private key

type SigningAlgo 

type SigningAlgo string

SigningAlgo defines an algorithm to derive key-pairs which can be used for cryptographic signing.

Source Files

View all Source files

Directories

Path Synopsis
Package hd provides basic functionality Hierarchical Deterministic Wallets.
 Package hd provides basic functionality Hierarchical Deterministic Wallets.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.