remote

Documentation

Overview

Package remote defines an implementation of an on-disk, EIP-2335 keystore.json approach towards defining validator accounts in Prysm. A validating private key is encrypted using a passphrase and its resulting encrypted file is stored as a keystore.json file under a unique, human-readable, account namespace. This imported keymanager approach relies on storing account information on-disk, making it trivial to import, backup and list all associated accounts for a user.

Package remote defines a keymanager implementation which connects to a remote signer server via gRPC. The connection is established via TLS using supplied paths to certificates and key files and allows for submitting remote signing requests for Ethereum data structures as well as retrieving the available signing public keys from the remote server.

Remote sign requests are defined by the following protobuf schema:

 // SignRequest is a message type used by a keymanager
 // as part of Prysm's accounts implementation.
 message SignRequest {
     // 48 byte public key corresponding to an associated private key
     // being requested to sign data.
     bytes public_key = 1;

     // Raw bytes signing root the client is requesting to sign. The client is
	 // expected to determine these raw bytes from the appropriate BLS
     // signing domain as well as the signing root of the data structure
	 // the bytes represent.
     bytes signing_root = 2;
 }

Remote signing responses will contain a BLS12-381 signature along with the status of the signing response from the remote server, signifying the request either failed, was denied, or completed successfully.

message SignResponse {
    enum Status {
        UNKNOWN = 0;
        SUCCEEDED = 1;
        DENIED = 2;
        FAILED = 3;
    }

    // BLS12-381 signature for the data specified in the request.
    bytes signature = 1;
}

The remote keymanager can be customized via a keymanageropts.json file which requires the following schema:

{
  "remote_address": "remoteserver.com:4000", // Remote gRPC server address.
  "remote_cert": {
    "crt_path": "/home/eth2/certs/client.crt", // Client certificate path.
    "ca_crt_path": "/home/eth2/certs/ca.crt",  // Certificate authority cert path.
    "key_path": "/home/eth2/certs/client.key", // Client key path.
  }
}

Index

• Variables
• func MarshalOptionsFile(_ context.Context, cfg *KeymanagerOpts) ([]byte, error)
• type CertificateConfig
• type Keymanager
  • func NewKeymanager(_ context.Context, cfg *SetupConfig) (*Keymanager, error)
  • func (km *Keymanager) FetchValidatingPublicKeys(ctx context.Context) ([][48]byte, error)
  • func (km *Keymanager) KeymanagerOpts() *KeymanagerOpts
  • func (km *Keymanager) ReloadPublicKeys(ctx context.Context) ([][48]byte, error)
  • func (km *Keymanager) Sign(ctx context.Context, req *validatorpb.SignRequest) (bls.Signature, error)
  • func (km *Keymanager) SubscribeAccountChanges(pubKeysChan chan [][48]byte) event.Subscription
• type KeymanagerOpts
  • func UnmarshalOptionsFile(r io.ReadCloser) (*KeymanagerOpts, error)
  • func (opts *KeymanagerOpts) String() string
• type MockKeymanager
  • func NewMock() MockKeymanager
  • func (m *MockKeymanager) FetchValidatingPublicKeys(context.Context) ([][48]byte, error)
  • func (m *MockKeymanager) ReloadPublicKeys(context.Context) ([][48]byte, error)
  • func (*MockKeymanager) Sign(context.Context, *validatorpb.SignRequest) (bls.Signature, error)
  • func (m *MockKeymanager) SubscribeAccountChanges(chan [][48]byte) event.Subscription
• type RemoteKeymanager
• type SetupConfig

Variables

var (
	// ErrSigningFailed defines a failure from the remote server
	// when performing a signing operation.
	ErrSigningFailed = errors.New("signing failed in the remote server")
	// ErrSigningDenied defines a failure from the remote server when
	// performing a signing operation was denied by a remote server.
	ErrSigningDenied = errors.New("signing request was denied by remote server")
)

Functions

func MarshalOptionsFile

func MarshalOptionsFile(_ context.Context, cfg *KeymanagerOpts) ([]byte, error)

MarshalOptionsFile for the keymanager.

Types

type CertificateConfig

type CertificateConfig struct {
	RequireTls     bool   `json:"require_tls"`
	ClientCertPath string `json:"crt_path"`
	ClientKeyPath  string `json:"key_path"`
	CACertPath     string `json:"ca_crt_path"`
}

CertificateConfig defines configuration options for certificate authority certs, client certs, and client keys for TLS gRPC connections.

type Keymanager

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

Keymanager implementation using remote signing keys via gRPC.

func NewKeymanager

func NewKeymanager(_ context.Context, cfg *SetupConfig) (*Keymanager, error)

NewKeymanager instantiates a new imported keymanager from configuration options.

func (*Keymanager) FetchValidatingPublicKeys

func (km *Keymanager) FetchValidatingPublicKeys(ctx context.Context) ([][48]byte, error)

FetchValidatingPublicKeys fetches the list of public keys that should be used to validate with.

func (*Keymanager) KeymanagerOpts

func (km *Keymanager) KeymanagerOpts() *KeymanagerOpts

KeymanagerOpts for the remote keymanager.

func (*Keymanager) ReloadPublicKeys

func (km *Keymanager) ReloadPublicKeys(ctx context.Context) ([][48]byte, error)

ReloadPublicKeys reloads public keys.

func (*Keymanager) Sign

func (km *Keymanager) Sign(ctx context.Context, req *validatorpb.SignRequest) (bls.Signature, error)

Sign signs a message for a validator key via a gRPC request.

func (*Keymanager) SubscribeAccountChanges

func (km *Keymanager) SubscribeAccountChanges(pubKeysChan chan [][48]byte) event.Subscription

SubscribeAccountChanges creates an event subscription for a channel to listen for public key changes at runtime, such as when new validator accounts are imported into the keymanager while the validator process is running.

type KeymanagerOpts

type KeymanagerOpts struct {
	RemoteCertificate *CertificateConfig `json:"remote_cert"`
	RemoteAddr        string             `json:"remote_address"`
}

KeymanagerOpts for a remote keymanager.

func UnmarshalOptionsFile

func UnmarshalOptionsFile(r io.ReadCloser) (*KeymanagerOpts, error)

UnmarshalOptionsFile attempts to JSON unmarshal a keymanager options file into a struct.

func (*KeymanagerOpts) String

func (opts *KeymanagerOpts) String() string

String pretty-print of a remote keymanager options.

type MockKeymanager

type MockKeymanager struct {
	PublicKeys             [][48]byte
	ReloadPublicKeysChan   chan [][48]byte
	ReloadPublicKeysCalled bool
	// contains filtered or unexported fields
}

MockKeymanager --

func NewMock

func NewMock() MockKeymanager

func (*MockKeymanager) FetchValidatingPublicKeys

func (m *MockKeymanager) FetchValidatingPublicKeys(context.Context) ([][48]byte, error)

FetchValidatingPublicKeys --

func (*MockKeymanager) ReloadPublicKeys

func (m *MockKeymanager) ReloadPublicKeys(context.Context) ([][48]byte, error)

ReloadPublicKeys --

func (*MockKeymanager) Sign

func (*MockKeymanager) Sign(context.Context, *validatorpb.SignRequest) (bls.Signature, error)

Sign --

func (*MockKeymanager) SubscribeAccountChanges

func (m *MockKeymanager) SubscribeAccountChanges(chan [][48]byte) event.Subscription

SubscribeAccountChanges --

type RemoteKeymanager

type RemoteKeymanager interface {
	keymanager.IKeymanager
	ReloadPublicKeys(ctx context.Context) ([][48]byte, error)
}

RemoteKeymanager defines the interface for remote Prysm wallets.

type SetupConfig

type SetupConfig struct {
	Opts           *KeymanagerOpts
	MaxMessageSize int
}

SetupConfig includes configuration values for initializing a keymanager, such as passwords, the wallet, and more.