s3

README

go-eth2-wallet-store-s3

Amazon S3-based store for the Ethereum 2 wallet.

Table of Contents

• Install
• Usage
• Maintainers
• Contribute

Install

go-eth2-wallet-store-s3 is a standard Go module which can be installed with:

go get github.com/alex-necsoiu/go-eth-wallet/store-s3

Usage

In normal operation this module should not be used directly. Instead, it should be configured to be used as part of go-eth2-wallet.

The S3 store has the following options:

• region: the Amazon S3 region in which the wallet is to be stored. This can be any valid region string as per the Amazon list, for example ap-northeast-2 or eu-north-1
• id: an ID that is used to differentiate multiple stores created by the same account. If this is not configured an empty ID is used
• passphrase: a key used to encrypt all data written to the store. If this is not configured data is written to the store unencrypted (although wallet- and account-specific private information may be protected by their own passphrases)
• bucket: the name of a bucket in which the store will place wallets. If this is not configured it generates one based on the AWS credentials and ID
• path: a path inside the bucket in which to place wallets. If this is not configured it uses the root directory of the bucket
• endpoint: a URL for an S3-compatible service, for example 'https://storage.googleapis.com` for Google Cloud Storage

When initiating a connection to Amazon S3 the Amazon credentials are required. Details on how to make the credentials available to the store are available at the Amazon S3 documentation

Example

package main

import (
	e2wallet "github.com/alex-necsoiu/go-eth-wallet"
	s3 "github.com/alex-necsoiu/go-eth-wallet/store-s3"
)

func main() {
    // Set up and use an encrypted store
    store, err := s3.New(s3.WithPassphrase([]byte("my secret")))
    if err != nil {
        panic(err)
    }
    e2wallet.UseStore(store)

    // Set up and use an encrypted store in the central Canada region
    store, err = s3.New(s3.WithPassphrase([]byte("my secret")), s3.WithRegion("ca-central-1"))
    if err != nil {
        panic(err)
    }
    e2wallet.UseStore(store)

    // Set up and use an encrypted store with a custom ID
    store, err = s3.New(s3.WithPassphrase([]byte("my secret")), s3.WithID([]byte("store 2")))
    if err != nil {
        panic(err)
    }
    e2wallet.UseStore(store)

    // Set up and use a store with a custom bucket and path
    store, err = s3.New(s3.WithBucket("my-store"), s3.WithPath("data/keystore"))
    if err != nil {
        panic(err)
    }
    e2wallet.UseStore(store)

    // Set up and use a store with non-dfeault credentials.
    store, err = s3.New(s3.WithCredentialsID("ABCDEF"), s3.WithCredentialsSecret("XXXXXXXXXXXX"))
    if err != nil {
        panic(err)
    }
    e2wallet.UseStore(store)
}

Maintainers

Alex Necsoiu: @alex-necsoiu.

Contribute

Contributions welcome. Please check out the issues.

Documentation

Index

• func New(opts ...Option) (wtypes.Store, error)
• func TestDecryptIfRequired(t *testing.T)
• func TestEncryptIfRequired(t *testing.T)
• type Option
  • func WithBucket(t string) Option
  • func WithCredentialsID(t string) Option
  • func WithCredentialsSecret(t string) Option
  • func WithEndpoint(t string) Option
  • func WithID(t []byte) Option
  • func WithPassphrase(passphrase []byte) Option
  • func WithPath(t string) Option
  • func WithRegion(t string) Option
• type Store
  • func (s *Store) Location() string
  • func (s *Store) Name() string
  • func (s *Store) RetrieveAccount(walletID uuid.UUID, accountID uuid.UUID) ([]byte, error)
  • func (s *Store) RetrieveAccounts(walletID uuid.UUID) <-chan []byte
  • func (s *Store) RetrieveAccountsIndex(walletID uuid.UUID) ([]byte, error)
  • func (s *Store) RetrieveBatch(_ context.Context, walletID uuid.UUID) ([]byte, error)
  • func (s *Store) RetrieveWallet(walletName string) ([]byte, error)
  • func (s *Store) RetrieveWalletByID(walletID uuid.UUID) ([]byte, error)
  • func (s *Store) RetrieveWallets() <-chan []byte
  • func (s *Store) StoreAccount(walletID uuid.UUID, accountID uuid.UUID, data []byte) error
  • func (s *Store) StoreAccountsIndex(walletID uuid.UUID, data []byte) error
  • func (s *Store) StoreBatch(_ context.Context, walletID uuid.UUID, _ string, data []byte) error
  • func (s *Store) StoreWallet(id uuid.UUID, _ string, data []byte) error

Functions

func New

func New(opts ...Option) (wtypes.Store, error)

New creates a new Amazon S3-compatible store. This takes the following options:

• region: a string specifying the Amazon S3 region, defaults to "us-east-1", set with WithRegion()
• id: a byte array specifying an identifying key for the store, defaults to nil, set with WithID()
• passphrase: a key used to encrypt all data written to the store, defaults to blank and no additional encryption
• bucket: the name of a bucket to create, defaults to one generated using the credentials and ID
• path: a path inside the bucket in which to place wallets, defaults to the root of the bucket
• endpoint: a URL for an S3-compatible service to use in place of S3 itself
• credentials ID: AWS access credentials ID
• credentials secret: AWS access credentials secret

If credentials are not supplied, the access credentials should be in a standard place, e.g. ~/.aws/credentials .

func TestDecryptIfRequired

func TestDecryptIfRequired(t *testing.T)

func TestEncryptIfRequired

func TestEncryptIfRequired(t *testing.T)

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option gives options to New.

func WithBucket

func WithBucket(t string) Option

WithBucket sets the bucket for the store.

func WithCredentialsID

func WithCredentialsID(t string) Option

WithCredentialsID sets the credentials ID.

func WithCredentialsSecret

func WithCredentialsSecret(t string) Option

WithCredentialsSecret sets the credentials secret.

func WithEndpoint

func WithEndpoint(t string) Option

WithEndpoint sets the endpoint for the store.

func WithID

func WithID(t []byte) Option

WithID sets the ID for the store.

func WithPassphrase

func WithPassphrase(passphrase []byte) Option

WithPassphrase sets the passphrase for the store.

func WithPath

func WithPath(t string) Option

WithPath sets the path for the store. If not supplied this will default to an accout-specific path.

func WithRegion

func WithRegion(t string) Option

WithRegion sets the AWS region for the store. This defaults to "us-east-1", and cannot be overridden by an empty string.

type Store

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

Store is the store for the wallet held encrypted on Amazon S3.

func (*Store) Location

func (s *Store) Location() string

Location returns the location of this store.

func (*Store) Name

func (s *Store) Name() string

Name returns the name of this store.

func (*Store) RetrieveAccount

func (s *Store) RetrieveAccount(walletID uuid.UUID, accountID uuid.UUID) ([]byte, error)

RetrieveAccount retrieves account-level data. It will fail if it cannot retrieve the data.

func (*Store) RetrieveAccounts

func (s *Store) RetrieveAccounts(walletID uuid.UUID) <-chan []byte

RetrieveAccounts retrieves all account-level data for a wallet.

func (*Store) RetrieveAccountsIndex

func (s *Store) RetrieveAccountsIndex(walletID uuid.UUID) ([]byte, error)

RetrieveAccountsIndex retrieves the account index.

func (*Store) RetrieveBatch

func (s *Store) RetrieveBatch(_ context.Context, walletID uuid.UUID) ([]byte, error)

RetrieveBatch retrieves the batch of accounts for a given wallet.

func (*Store) RetrieveWallet

func (s *Store) RetrieveWallet(walletName string) ([]byte, error)

RetrieveWallet retrieves wallet-level data. It will fail if it cannot retrieve the data.

func (*Store) RetrieveWalletByID

func (s *Store) RetrieveWalletByID(walletID uuid.UUID) ([]byte, error)

RetrieveWalletByID retrieves wallet-level data. It will fail if it cannot retrieve the data.

func (*Store) RetrieveWallets

func (s *Store) RetrieveWallets() <-chan []byte

RetrieveWallets retrieves wallet-level data for all wallets.

func (*Store) StoreAccount

func (s *Store) StoreAccount(walletID uuid.UUID, accountID uuid.UUID, data []byte) error

StoreAccount stores an account. It will fail if it cannot store the data. Note this will overwrite an existing account with the same ID. It will not, however, allow multiple accounts with the same name to co-exist in the same wallet.

func (*Store) StoreAccountsIndex

func (s *Store) StoreAccountsIndex(walletID uuid.UUID, data []byte) error

StoreAccountsIndex stores the account index.

func (*Store) StoreBatch

func (s *Store) StoreBatch(_ context.Context, walletID uuid.UUID, _ string, data []byte) error

StoreBatch stores wallet batch data. It will fail if it cannot store the data.

func (*Store) StoreWallet

func (s *Store) StoreWallet(id uuid.UUID, _ string, data []byte) error

StoreWallet stores wallet-level data. It will fail if it cannot store the data. Note that this will overwrite any existing data; it is up to higher-level functions to check for the presence of a wallet with the wallet name and handle clashes accordingly.