Documentation
¶
Overview ¶
Package store provides local keystore management for TRON accounts.
Index ¶
- Variables
- func AddressFromAccountName(name string) (string, error)
- func CloseAll()
- func DecryptPQKey(acct PQAccount, password string) (pqc.PrivateKey, error)
- func DefaultLocation() string
- func DescribeLocalAccounts()
- func DoesNamedAccountExist(name string) bool
- func FromAccountName(name string) *keystore.KeyStore
- func FromAddress(addr string) *keystore.KeyStore
- func InitConfigDir()
- func LocalAccounts() []string
- func NameExists(name string) bool
- func PQKeysDir() string
- func RemovePQAccount(name string) error
- func ScanPQAccounts() ([]PQAccount, []UnreadablePQAccount, error)
- func SetDefaultLocation(directory string)
- func SetKeystoreFactory(fn func(string) *keystore.KeyStore)
- func UnlockedKeystore(from, passphrase string) (*keystore.KeyStore, *keystore.Account, error)
- func ValidateAccountName(name string) error
- type PQAccount
- func ImportPQKeystore(name string, keystoreJSON []byte, password string) (PQAccount, error)
- func PQAccountByAddress(addr string) (PQAccount, error)
- func PQAccountByName(name string) (PQAccount, error)
- func PQAccounts() ([]PQAccount, error)
- func SavePQKey(name string, k pqc.PrivateKey, password string, scryptN, scryptP int) (PQAccount, error)
- type Store
- func (s *Store) AddressFromAccountName(name string) (string, error)
- func (s *Store) CloseAll()
- func (s *Store) DecryptPQKey(acct PQAccount, password string) (pqc.PrivateKey, error)
- func (s *Store) DefaultLocation() string
- func (s *Store) DescribeLocalAccounts()
- func (s *Store) DoesNamedAccountExist(name string) bool
- func (s *Store) Forget(ks *keystore.KeyStore)
- func (s *Store) FromAccountName(name string) *keystore.KeyStore
- func (s *Store) FromAddress(addr string) *keystore.KeyStore
- func (s *Store) ImportPQKeystore(name string, keystoreJSON []byte, password string) (PQAccount, error)
- func (s *Store) InitConfigDir()
- func (s *Store) LocalAccounts() []string
- func (s *Store) NameExists(name string) bool
- func (s *Store) PQAccountByAddress(addr string) (PQAccount, error)
- func (s *Store) PQAccountByName(name string) (PQAccount, error)
- func (s *Store) PQAccounts() ([]PQAccount, error)
- func (s *Store) PQKeysDir() string
- func (s *Store) RemovePQAccount(name string) error
- func (s *Store) SavePQKey(name string, k pqc.PrivateKey, password string, scryptN, scryptP int) (PQAccount, error)
- func (s *Store) ScanPQAccounts() ([]PQAccount, []UnreadablePQAccount, error)
- func (s *Store) SetDefaultLocation(directory string)
- func (s *Store) SetKeystoreFactory(fn func(string) *keystore.KeyStore)
- func (s *Store) UnlockedKeystore(from, passphrase string) (*keystore.KeyStore, *keystore.Account, error)
- type UnreadablePQAccount
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNoConfigDir is wrapped by every error caused by a config folder that // cannot be resolved: a relative config dir with no home directory. ErrNoConfigDir = errors.New("the keystore folder cannot be resolved (is $HOME set?)") // ErrKeystoreNotFound is wrapped by UnlockedKeystore when the address has no // ECDSA keystore in the local store. ErrKeystoreNotFound = errors.New("account not found in the local keystore") // ErrNoUnlockBadPassphrase is returned when an account cannot be unlocked with the given passphrase. ErrNoUnlockBadPassphrase = fmt.Errorf("could not unlock account with passphrase, perhaps need different phrase") )
var ( // ErrPQAccountNotFound is returned when no post-quantum account matches // the requested name or address. // // Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change. ErrPQAccountNotFound = errors.New("post-quantum account not found") // ErrAccountNameExists is returned when an account name is already used // in account-keys or pq-keys. // // Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change. ErrAccountNameExists = errors.New("account name already exists") // ErrPQAddressExists is returned when a post-quantum account with the // same address is already stored. // // Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change. ErrPQAddressExists = errors.New("post-quantum address already exists") // ErrInvalidAccountName is returned for an account name that is empty, // contains a path separator or NUL, is "." or "..", or is absolute. // // Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change. ErrInvalidAccountName = errors.New("invalid account name") // ErrInvalidPQKeystore is returned when a post-quantum account folder // exists but does not hold exactly one readable keystore with a supported // scheme and a valid address, or when pq-keys/<name> is not a real folder // (a plain file or a symlink, which is never followed or removed). // // Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change. ErrInvalidPQKeystore = errors.New("invalid post-quantum keystore") )
Functions ¶
func AddressFromAccountName ¶
AddressFromAccountName returns the Base58 address for the named account, or an error if not found. A name that is not a single path element on this OS is rejected before any path is built, so it cannot reach a keystore outside the accounts folder.
func CloseAll ¶ added in v0.24.3
func CloseAll()
CloseAll closes all tracked keystores and resets the factory to production defaults. This is a safety net for test cleanup.
func DecryptPQKey ¶ added in v0.27.0
func DecryptPQKey(acct PQAccount, password string) (pqc.PrivateKey, error)
DecryptPQKey reads acct's keystore and decrypts it with password. The key must match acct's address and scheme, else the error wraps pqc.ErrKeyMismatch. A wrong password returns an error wrapping keystore.ErrDecrypt. The caller owns the returned key and should Destroy it when done.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func DefaultLocation ¶
func DefaultLocation() string
DefaultLocation returns the current default keystore directory path. It returns "" when the config directory cannot be resolved; do not join the empty string with a name and write to it, which would be relative to the current directory.
func DescribeLocalAccounts ¶
func DescribeLocalAccounts()
DescribeLocalAccounts prints all account alias names and their addresses to stdout.
func DoesNamedAccountExist ¶
DoesNamedAccountExist reports whether an account alias with the given name exists locally. It reports false when the config directory cannot be resolved.
func FromAccountName ¶
FromAccountName returns a KeyStore loaded from the named account's directory. It does not check name: the caller must validate it with ValidateAccountName first, or a name such as "../x" addresses a directory outside the store. It returns nil when the config directory cannot be resolved (a relative directory without a home directory), so check the result before use.
func FromAddress ¶
FromAddress will return nil if the Base58 string is not found in the imported accounts. Non-matching keystores are closed to prevent goroutine leaks.
func InitConfigDir ¶
func InitConfigDir()
InitConfigDir creates the account keystore directory if it does not exist. If the config directory cannot be resolved (a relative directory without a home directory) it creates nothing and prints the error.
func LocalAccounts ¶
func LocalAccounts() []string
LocalAccounts returns the alias names of all locally stored accounts. It returns an empty list when the config directory cannot be resolved.
func NameExists ¶ added in v0.27.0
NameExists reports whether name is used in account-keys or pq-keys; see Store.NameExists. New code that creates accounts should use it instead of DoesNamedAccountExist. An invalid name always reports false, so callers should check it with ValidateAccountName first.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func PQKeysDir ¶ added in v0.27.0
func PQKeysDir() string
PQKeysDir returns the post-quantum keystore folder, <configRoot>/pq-keys. It follows SetDefaultLocation and is not created until the first key is stored.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func RemovePQAccount ¶ added in v0.27.0
RemovePQAccount deletes the post-quantum account folder pq-keys/<name>; see Store.RemovePQAccount.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func ScanPQAccounts ¶ added in v0.27.0
func ScanPQAccounts() ([]PQAccount, []UnreadablePQAccount, error)
ScanPQAccounts lists the stored post-quantum accounts and the unusable folders of pq-keys; see Store.ScanPQAccounts.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func SetDefaultLocation ¶
func SetDefaultLocation(directory string)
SetDefaultLocation sets the config root, the folder that holds the account-keys and pq-keys folders, and creates its account-keys folder if needed. A relative directory is resolved against the home directory, not the current one (tronctl makes --ks-dir absolute before calling it). If that cannot be resolved the directory is still recorded, so later operations fail the same way instead of using the previous one; nothing is created and the error is printed.
func SetKeystoreFactory ¶ added in v0.24.3
SetKeystoreFactory replaces the function used to create keystores. Pass keystore.ForPathLight in tests for faster key derivation.
func UnlockedKeystore ¶
UnlockedKeystore finds, unlocks, and returns the keystore and account for the given Base58 address.
func ValidateAccountName ¶ added in v0.27.0
ValidateAccountName reports whether name is a valid account name: a single, plain path element, so that a name can never address a file outside its folder. It returns an error wrapping ErrInvalidAccountName for a name that is empty, contains a path separator ("/" or "\") or NUL, is "." or "..", or is absolute. The same rule applies to ECDSA and post-quantum accounts.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
Types ¶
type PQAccount ¶ added in v0.27.0
type PQAccount struct {
// Name is the account name, which is also its folder under pq-keys.
Name string
// Address is the Base58Check address ("T...") stored in the keystore.
Address string
// Scheme is the TIP-899 signature scheme of the key.
Scheme core.PQScheme
// Path is the absolute path of the keystore file.
Path string
}
PQAccount describes a stored post-quantum keystore. All fields come from the clear part of the keystore file; nothing is decrypted to fill them.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func ImportPQKeystore ¶ added in v0.27.0
ImportPQKeystore stores a wallet-cli post-quantum keystore under name; see Store.ImportPQKeystore.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func PQAccountByAddress ¶ added in v0.27.0
PQAccountByAddress returns the post-quantum account with the Base58 address addr; see Store.PQAccountByAddress.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func PQAccountByName ¶ added in v0.27.0
PQAccountByName returns the post-quantum account stored under name; see Store.PQAccountByName.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func PQAccounts ¶ added in v0.27.0
PQAccounts lists the stored post-quantum accounts; see Store.PQAccounts.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func SavePQKey ¶ added in v0.27.0
func SavePQKey(name string, k pqc.PrivateKey, password string, scryptN, scryptP int) (PQAccount, error)
SavePQKey encrypts and stores k under name; see Store.SavePQKey. The caller owns k and must Destroy it.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
type Store ¶ added in v0.26.0
type Store struct {
// contains filtered or unexported fields
}
Store manages keystores for TRON accounts.
func DefaultStoreInstance ¶ added in v0.26.0
func DefaultStoreInstance() *Store
DefaultStoreInstance creates a Store using the default ~/.tronctl directory. When the home directory cannot be determined, the Store keeps the relative default and every operation that needs the directory reports that error (or, where it cannot return one, does nothing); see the methods of Store.
func (*Store) AddressFromAccountName ¶ added in v0.26.0
AddressFromAccountName returns the Base58 address for the named account, or an error if not found. A name that is not a single path element on this OS is rejected before any path is built, so it cannot reach a keystore outside the accounts folder.
func (*Store) CloseAll ¶ added in v0.26.0
func (s *Store) CloseAll()
CloseAll closes all tracked keystores and resets the factory to production defaults. This is a safety net for test cleanup.
func (*Store) DecryptPQKey ¶ added in v0.27.0
DecryptPQKey decrypts acct's keystore; see the package-level DecryptPQKey.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) DefaultLocation ¶ added in v0.26.0
DefaultLocation returns the current default keystore directory path. It returns "" when the config directory cannot be resolved; do not join the empty string with a name and write to it, which would be relative to the current directory.
func (*Store) DescribeLocalAccounts ¶ added in v0.26.0
func (s *Store) DescribeLocalAccounts()
DescribeLocalAccounts prints all account alias names and their addresses to stdout.
func (*Store) DoesNamedAccountExist ¶ added in v0.26.0
DoesNamedAccountExist reports whether an account alias with the given name exists locally. It reports false when the config directory cannot be resolved.
func (*Store) Forget ¶ added in v0.26.0
Forget removes a keystore from the tracked set. Call this after closing a keystore obtained via FromAccountName to allow garbage collection.
func (*Store) FromAccountName ¶ added in v0.26.0
FromAccountName returns a KeyStore loaded from the named account's directory. It does not check name: the caller must validate it with ValidateAccountName first, or a name such as "../x" addresses a directory outside the store. It returns nil when the config directory cannot be resolved (a relative directory without a home directory), so check the result before use.
func (*Store) FromAddress ¶ added in v0.26.0
FromAddress will return nil if the Base58 string is not found in the imported accounts. Non-matching keystores are closed to prevent goroutine leaks.
func (*Store) ImportPQKeystore ¶ added in v0.27.0
func (s *Store) ImportPQKeystore(name string, keystoreJSON []byte, password string) (PQAccount, error)
ImportPQKeystore stores a wallet-cli post-quantum keystore under name. The keystore must decrypt with password to a key matching its clear scheme and address; the decrypted key is destroyed immediately. The name must be free in both account-keys and pq-keys (ErrAccountNameExists) and the address must not already be in pq-keys (ErrPQAddressExists). The name and the clear address are checked before the keystore is decrypted, so a taken name or address is reported whatever the password, and checked again before writing. The original bytes are written, with mode 0600, to pq-keys/<name>/UTC--<time>--<address>.json. Nothing is written when any check fails.
Name uniqueness holds across processes; address uniqueness is enforced only within one process, so two processes importing the same keystore under different names at the same time can both succeed.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) InitConfigDir ¶ added in v0.26.0
func (s *Store) InitConfigDir()
InitConfigDir creates the account keystore directory if it does not exist. If the config directory cannot be resolved (a relative directory without a home directory) it creates nothing and prints the error.
func (*Store) LocalAccounts ¶ added in v0.26.0
LocalAccounts returns the alias names of all locally stored accounts. It returns an empty list when the config directory cannot be resolved.
func (*Store) NameExists ¶ added in v0.27.0
NameExists reports whether name is used by an ECDSA account (account-keys) or a post-quantum account (pq-keys). New code that creates accounts should use it instead of DoesNamedAccountExist, which only checks account-keys. An invalid name always reports false, so callers should check it with ValidateAccountName first. Any entry counts, including a plain file or a symlink, and a stat error other than "not exist" counts as taken. So does a valid name when the config directory cannot be resolved (a relative directory without a home directory): the name cannot be shown to be free, so a caller that checks before creating stops there.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) PQAccountByAddress ¶ added in v0.27.0
PQAccountByAddress returns the post-quantum account with the Base58 address addr, or an error wrapping ErrPQAccountNotFound.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) PQAccountByName ¶ added in v0.27.0
PQAccountByName returns the post-quantum account stored under name. A name with no entry in pq-keys returns an error wrapping ErrPQAccountNotFound. An entry that is not a real folder (a plain file or a symlink, which is never followed) returns one wrapping ErrInvalidPQKeystore that says to remove it manually, as does a folder without a valid keystore.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) PQAccounts ¶ added in v0.27.0
PQAccounts lists the stored post-quantum accounts, sorted by name. Only the clear scheme and address fields are read; nothing is decrypted. Entries that are not folders, and folders that do not hold exactly one readable keystore with a supported scheme and a valid address, are skipped without an error; use ScanPQAccounts to be told which folders were skipped and why. The error is non-nil only when the pq-keys folder exists but cannot be read, or the config directory cannot be resolved (a relative directory without a home directory); a missing folder yields an empty list.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) PQKeysDir ¶ added in v0.27.0
PQKeysDir returns the post-quantum keystore folder, <configRoot>/pq-keys. It is not created until the first key is stored. It returns "" when the config directory cannot be resolved (a relative directory without a home directory); do not join the empty string with a name and write to it.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) RemovePQAccount ¶ added in v0.27.0
RemovePQAccount deletes the post-quantum account folder pq-keys/<name>. It never touches account-keys. A name with no entry in pq-keys returns an error wrapping ErrPQAccountNotFound. An entry that is not a real folder (a plain file or a symlink) is neither followed nor removed; the error wraps ErrInvalidPQKeystore and says to remove it manually.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) SavePQKey ¶ added in v0.27.0
func (s *Store) SavePQKey(name string, k pqc.PrivateKey, password string, scryptN, scryptP int) (PQAccount, error)
SavePQKey encrypts k with password (see pqc.EncryptKeystore for scryptN and scryptP) and stores it under name, with the same checks and file layout as ImportPQKeystore. The name and the key's address are checked before the slow encryption and again before writing. As with ImportPQKeystore, name uniqueness holds across processes but address uniqueness only within one. The caller owns k and must Destroy it.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) ScanPQAccounts ¶ added in v0.27.0
func (s *Store) ScanPQAccounts() ([]PQAccount, []UnreadablePQAccount, error)
ScanPQAccounts lists the stored post-quantum accounts like PQAccounts, and also the folders of pq-keys that are not usable accounts: a folder with an invalid account name, or one that does not hold exactly one readable keystore with a supported scheme and a valid address. Both lists are sorted by name. Plain files and symlinks in pq-keys (for example a .DS_Store) are ignored. Only the clear scheme and address fields are read; nothing is decrypted and the unreadable entries carry no key material. The error is non-nil only when the pq-keys folder exists but cannot be read, or the config directory cannot be resolved; a missing folder yields empty lists.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.
func (*Store) SetDefaultLocation ¶ added in v0.26.0
SetDefaultLocation updates the config directory and creates the account-keys subdirectory if needed. A relative directory is resolved against the home directory. If that cannot be resolved the directory is still recorded, so later operations fail the same way instead of using the previous one; nothing is created and the error is printed.
func (*Store) SetKeystoreFactory ¶ added in v0.26.0
SetKeystoreFactory replaces the function used to create keystores. Pass keystore.ForPathLight in tests for faster key derivation.
type UnreadablePQAccount ¶ added in v0.27.0
type UnreadablePQAccount struct {
// Name is the folder name.
Name string
// Err is the reason the folder is not an account.
Err error
}
UnreadablePQAccount is a folder in pq-keys that ScanPQAccounts could not read as an account: its name is not a valid account name, or it does not hold exactly one readable keystore with a supported scheme and a valid address. Err says why. It never holds key material.
Experimental: TIP-899 post-quantum support is a draft (Nile only) and may change.