Documentation

Overview

Package privval provides different implementations of the types.PrivValidator.

FilePV

FilePV is the simplest implementation and developer default. It uses one file for the private key and another to store state.

SignerListenerEndpoint

SignerListenerEndpoint establishes a connection to an external process, like a Key Management Server (KMS), using a socket. SignerListenerEndpoint listens for the external KMS process to dial in. SignerListenerEndpoint takes a listener, which determines the type of connection (ie. encrypted over tcp, or unencrypted over unix).

SignerDialerEndpoint

SignerDialerEndpoint is a simple wrapper around a net.Conn. It's used by both IPCVal and TCPVal.

SignerClient

SignerClient handles remote validator connections that provide signing services. In production, it's recommended to wrap it with RetrySignerClient to avoid termination in case of temporary errors.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrConnectionTimeout  = EndpointTimeoutError{}
	ErrNoConnection       = errors.New("endpoint is not connected")
	ErrReadTimeout        = errors.New("endpoint read timed out")
	ErrUnexpectedResponse = errors.New("empty response")
	ErrWriteTimeout       = errors.New("endpoint write timed out")
)

    Socket errors.

    View Source
    var (
    	ErrDialRetryMax = errors.New("dialed maximum retries")
    )

      Socket errors.

      Functions

      func DefaultValidationRequestHandler

      func DefaultValidationRequestHandler(
      	privVal types.PrivValidator,
      	req privvalproto.Message,
      	chainID string,
      ) (privvalproto.Message, error)

      func GetFreeLocalhostAddrPort

      func GetFreeLocalhostAddrPort() string

        GetFreeLocalhostAddrPort returns a free localhost:port address

        func IsConnTimeout

        func IsConnTimeout(err error) bool

          IsConnTimeout returns a boolean indicating whether the error is known to report that a connection timeout occurred. This detects both fundamental network timeouts, as well as ErrConnTimeout errors.

          Types

          type EndpointTimeoutError

          type EndpointTimeoutError struct{}

            EndpointTimeoutError occurs when endpoint times out.

            func (EndpointTimeoutError) Error

            func (e EndpointTimeoutError) Error() string

              Implement the net.Error interface.

              func (EndpointTimeoutError) Temporary

              func (e EndpointTimeoutError) Temporary() bool

              func (EndpointTimeoutError) Timeout

              func (e EndpointTimeoutError) Timeout() bool

              type FilePV

              type FilePV struct {
              	Key           FilePVKey
              	LastSignState FilePVLastSignState
              }

                FilePV implements PrivValidator using data persisted to disk to prevent double signing. NOTE: the directories containing pv.Key.filePath and pv.LastSignState.filePath must already exist. It includes the LastSignature and LastSignBytes so we don't lose the signature if the process crashes after signing but before the resulting consensus message is processed.

                func GenFilePV

                func GenFilePV(keyFilePath, stateFilePath string) *FilePV

                  GenFilePV generates a new validator with randomly generated private key and sets the filePaths, but does not call Save().

                  func LoadFilePV

                  func LoadFilePV(keyFilePath, stateFilePath string) *FilePV

                    LoadFilePV loads a FilePV from the filePaths. The FilePV handles double signing prevention by persisting data to the stateFilePath. If either file path does not exist, the program will exit.

                    func LoadFilePVEmptyState

                    func LoadFilePVEmptyState(keyFilePath, stateFilePath string) *FilePV

                      LoadFilePVEmptyState loads a FilePV from the given keyFilePath, with an empty LastSignState. If the keyFilePath does not exist, the program will exit.

                      func LoadOrGenFilePV

                      func LoadOrGenFilePV(keyFilePath, stateFilePath string) *FilePV

                        LoadOrGenFilePV loads a FilePV from the given filePaths or else generates a new one and saves it to the filePaths.

                        func NewFilePV

                        func NewFilePV(privKey crypto.PrivKey, keyFilePath, stateFilePath string) *FilePV

                          NewFilePV generates a new validator from the given key and paths.

                          func (*FilePV) GetAddress

                          func (pv *FilePV) GetAddress() types.Address

                            GetAddress returns the address of the validator. Implements PrivValidator.

                            func (*FilePV) GetPubKey

                            func (pv *FilePV) GetPubKey() (crypto.PubKey, error)

                              GetPubKey returns the public key of the validator. Implements PrivValidator.

                              func (*FilePV) Reset

                              func (pv *FilePV) Reset()

                                Reset resets all fields in the FilePV. NOTE: Unsafe!

                                func (*FilePV) Save

                                func (pv *FilePV) Save()

                                  Save persists the FilePV to disk.

                                  func (*FilePV) SignProposal

                                  func (pv *FilePV) SignProposal(chainID string, proposal *tmproto.Proposal) error

                                    SignProposal signs a canonical representation of the proposal, along with the chainID. Implements PrivValidator.

                                    func (*FilePV) SignVote

                                    func (pv *FilePV) SignVote(chainID string, vote *tmproto.Vote) error

                                      SignVote signs a canonical representation of the vote, along with the chainID. Implements PrivValidator.

                                      func (*FilePV) String

                                      func (pv *FilePV) String() string

                                        String returns a string representation of the FilePV.

                                        type FilePVKey

                                        type FilePVKey struct {
                                        	Address types.Address  `json:"address"`
                                        	PubKey  crypto.PubKey  `json:"pub_key"`
                                        	PrivKey crypto.PrivKey `json:"priv_key"`
                                        	// contains filtered or unexported fields
                                        }

                                          FilePVKey stores the immutable part of PrivValidator.

                                          func (FilePVKey) Save

                                          func (pvKey FilePVKey) Save()

                                            Save persists the FilePVKey to its filePath.

                                            type FilePVLastSignState

                                            type FilePVLastSignState struct {
                                            	Height    int64            `json:"height"`
                                            	Round     int32            `json:"round"`
                                            	Step      int8             `json:"step"`
                                            	Signature []byte           `json:"signature,omitempty"`
                                            	SignBytes tmbytes.HexBytes `json:"signbytes,omitempty"`
                                            	// contains filtered or unexported fields
                                            }

                                              FilePVLastSignState stores the mutable part of PrivValidator.

                                              func (*FilePVLastSignState) CheckHRS

                                              func (lss *FilePVLastSignState) CheckHRS(height int64, round int32, step int8) (bool, error)

                                                CheckHRS checks the given height, round, step (HRS) against that of the FilePVLastSignState. It returns an error if the arguments constitute a regression, or if they match but the SignBytes are empty. The returned boolean indicates whether the last Signature should be reused - it returns true if the HRS matches the arguments and the SignBytes are not empty (indicating we have already signed for this HRS, and can reuse the existing signature). It panics if the HRS matches the arguments, there's a SignBytes, but no Signature.

                                                func (*FilePVLastSignState) Save

                                                func (lss *FilePVLastSignState) Save()

                                                  Save persists the FilePvLastSignState to its filePath.

                                                  type RemoteSignerError

                                                  type RemoteSignerError struct {
                                                  	// TODO(ismail): create an enum of known errors
                                                  	Code        int
                                                  	Description string
                                                  }

                                                    RemoteSignerError allows (remote) validators to include meaningful error descriptions in their reply.

                                                    func (*RemoteSignerError) Error

                                                    func (e *RemoteSignerError) Error() string

                                                    type RetrySignerClient

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

                                                      RetrySignerClient wraps SignerClient adding retry for each operation (except Ping) w/ a timeout.

                                                      func NewRetrySignerClient

                                                      func NewRetrySignerClient(sc *SignerClient, retries int, timeout time.Duration) *RetrySignerClient

                                                        NewRetrySignerClient returns RetrySignerClient. If +retries+ is 0, the client will be retrying each operation indefinitely.

                                                        func (*RetrySignerClient) Close

                                                        func (sc *RetrySignerClient) Close() error

                                                        func (*RetrySignerClient) GetPubKey

                                                        func (sc *RetrySignerClient) GetPubKey() (crypto.PubKey, error)

                                                        func (*RetrySignerClient) IsConnected

                                                        func (sc *RetrySignerClient) IsConnected() bool

                                                        func (*RetrySignerClient) Ping

                                                        func (sc *RetrySignerClient) Ping() error

                                                        func (*RetrySignerClient) SignProposal

                                                        func (sc *RetrySignerClient) SignProposal(chainID string, proposal *tmproto.Proposal) error

                                                        func (*RetrySignerClient) SignVote

                                                        func (sc *RetrySignerClient) SignVote(chainID string, vote *tmproto.Vote) error

                                                        func (*RetrySignerClient) WaitForConnection

                                                        func (sc *RetrySignerClient) WaitForConnection(maxWait time.Duration) error

                                                        type SignerClient

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

                                                          SignerClient implements PrivValidator. Handles remote validator connections that provide signing services

                                                          func NewSignerClient

                                                          func NewSignerClient(endpoint *SignerListenerEndpoint, chainID string) (*SignerClient, error)

                                                            NewSignerClient returns an instance of SignerClient. it will start the endpoint (if not already started)

                                                            func (*SignerClient) Close

                                                            func (sc *SignerClient) Close() error

                                                              Close closes the underlying connection

                                                              func (*SignerClient) GetPubKey

                                                              func (sc *SignerClient) GetPubKey() (crypto.PubKey, error)

                                                                GetPubKey retrieves a public key from a remote signer returns an error if client is not able to provide the key

                                                                func (*SignerClient) IsConnected

                                                                func (sc *SignerClient) IsConnected() bool

                                                                  IsConnected indicates with the signer is connected to a remote signing service

                                                                  func (*SignerClient) Ping

                                                                  func (sc *SignerClient) Ping() error

                                                                    Ping sends a ping request to the remote signer

                                                                    func (*SignerClient) SignProposal

                                                                    func (sc *SignerClient) SignProposal(chainID string, proposal *tmproto.Proposal) error

                                                                      SignProposal requests a remote signer to sign a proposal

                                                                      func (*SignerClient) SignVote

                                                                      func (sc *SignerClient) SignVote(chainID string, vote *tmproto.Vote) error

                                                                        SignVote requests a remote signer to sign a vote

                                                                        func (*SignerClient) WaitForConnection

                                                                        func (sc *SignerClient) WaitForConnection(maxWait time.Duration) error

                                                                          WaitForConnection waits maxWait for a connection or returns a timeout error

                                                                          type SignerDialerEndpoint

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

                                                                            SignerDialerEndpoint dials using its dialer and responds to any signature requests using its privVal.

                                                                            func NewSignerDialerEndpoint

                                                                            func NewSignerDialerEndpoint(
                                                                            	logger log.Logger,
                                                                            	dialer SocketDialer,
                                                                            	options ...SignerServiceEndpointOption,
                                                                            ) *SignerDialerEndpoint

                                                                              NewSignerDialerEndpoint returns a SignerDialerEndpoint that will dial using the given dialer and respond to any signature requests over the connection using the given privVal.

                                                                              func (*SignerDialerEndpoint) Close

                                                                              func (se *SignerDialerEndpoint) Close() error

                                                                                Close closes the underlying net.Conn.

                                                                                func (*SignerDialerEndpoint) DropConnection

                                                                                func (se *SignerDialerEndpoint) DropConnection()

                                                                                  IsConnected indicates if there is an active connection

                                                                                  func (*SignerDialerEndpoint) GetAvailableConnection

                                                                                  func (se *SignerDialerEndpoint) GetAvailableConnection(connectionAvailableCh chan net.Conn) bool

                                                                                    TryGetConnection retrieves a connection if it is already available

                                                                                    func (*SignerDialerEndpoint) IsConnected

                                                                                    func (se *SignerDialerEndpoint) IsConnected() bool

                                                                                      IsConnected indicates if there is an active connection

                                                                                      func (*SignerDialerEndpoint) ReadMessage

                                                                                      func (se *SignerDialerEndpoint) ReadMessage() (msg privvalproto.Message, err error)

                                                                                        ReadMessage reads a message from the endpoint

                                                                                        func (*SignerDialerEndpoint) SetConnection

                                                                                        func (se *SignerDialerEndpoint) SetConnection(newConnection net.Conn)

                                                                                          SetConnection replaces the current connection object

                                                                                          func (*SignerDialerEndpoint) WaitConnection

                                                                                          func (se *SignerDialerEndpoint) WaitConnection(connectionAvailableCh chan net.Conn, maxWait time.Duration) error

                                                                                            TryGetConnection retrieves a connection if it is already available

                                                                                            func (*SignerDialerEndpoint) WriteMessage

                                                                                            func (se *SignerDialerEndpoint) WriteMessage(msg privvalproto.Message) (err error)

                                                                                              WriteMessage writes a message from the endpoint

                                                                                              type SignerListenerEndpoint

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

                                                                                                SignerListenerEndpoint listens for an external process to dial in and keeps the connection alive by dropping and reconnecting.

                                                                                                The process will send pings every ~3s (read/write timeout * 2/3) to keep the connection alive.

                                                                                                func NewSignerListener

                                                                                                func NewSignerListener(listenAddr string, logger log.Logger) (*SignerListenerEndpoint, error)

                                                                                                  NewSignerListener creates a new SignerListenerEndpoint using the corresponding listen address

                                                                                                  func NewSignerListenerEndpoint

                                                                                                  func NewSignerListenerEndpoint(
                                                                                                  	logger log.Logger,
                                                                                                  	listener net.Listener,
                                                                                                  	options ...SignerListenerEndpointOption,
                                                                                                  ) *SignerListenerEndpoint

                                                                                                    NewSignerListenerEndpoint returns an instance of SignerListenerEndpoint.

                                                                                                    func (*SignerListenerEndpoint) Close

                                                                                                    func (se *SignerListenerEndpoint) Close() error

                                                                                                      Close closes the underlying net.Conn.

                                                                                                      func (*SignerListenerEndpoint) DropConnection

                                                                                                      func (se *SignerListenerEndpoint) DropConnection()

                                                                                                        IsConnected indicates if there is an active connection

                                                                                                        func (*SignerListenerEndpoint) GetAvailableConnection

                                                                                                        func (se *SignerListenerEndpoint) GetAvailableConnection(connectionAvailableCh chan net.Conn) bool

                                                                                                          TryGetConnection retrieves a connection if it is already available

                                                                                                          func (*SignerListenerEndpoint) IsConnected

                                                                                                          func (se *SignerListenerEndpoint) IsConnected() bool

                                                                                                            IsConnected indicates if there is an active connection

                                                                                                            func (*SignerListenerEndpoint) OnStart

                                                                                                            func (sl *SignerListenerEndpoint) OnStart() error

                                                                                                              OnStart implements service.Service.

                                                                                                              func (*SignerListenerEndpoint) OnStop

                                                                                                              func (sl *SignerListenerEndpoint) OnStop()

                                                                                                                OnStop implements service.Service

                                                                                                                func (*SignerListenerEndpoint) ReadMessage

                                                                                                                func (se *SignerListenerEndpoint) ReadMessage() (msg privvalproto.Message, err error)

                                                                                                                  ReadMessage reads a message from the endpoint

                                                                                                                  func (*SignerListenerEndpoint) SendRequest

                                                                                                                    SendRequest ensures there is a connection, sends a request and waits for a response

                                                                                                                    func (*SignerListenerEndpoint) SetConnection

                                                                                                                    func (se *SignerListenerEndpoint) SetConnection(newConnection net.Conn)

                                                                                                                      SetConnection replaces the current connection object

                                                                                                                      func (*SignerListenerEndpoint) WaitConnection

                                                                                                                      func (se *SignerListenerEndpoint) WaitConnection(connectionAvailableCh chan net.Conn, maxWait time.Duration) error

                                                                                                                        TryGetConnection retrieves a connection if it is already available

                                                                                                                        func (*SignerListenerEndpoint) WaitForConnection

                                                                                                                        func (sl *SignerListenerEndpoint) WaitForConnection(maxWait time.Duration) error

                                                                                                                          WaitForConnection waits maxWait for a connection or returns a timeout error

                                                                                                                          func (*SignerListenerEndpoint) WriteMessage

                                                                                                                          func (se *SignerListenerEndpoint) WriteMessage(msg privvalproto.Message) (err error)

                                                                                                                            WriteMessage writes a message from the endpoint

                                                                                                                            type SignerListenerEndpointOption

                                                                                                                            type SignerListenerEndpointOption func(*SignerListenerEndpoint)

                                                                                                                              SignerListenerEndpointOption sets an optional parameter on the SignerListenerEndpoint.

                                                                                                                              func SignerListenerEndpointTimeoutReadWrite

                                                                                                                              func SignerListenerEndpointTimeoutReadWrite(timeout time.Duration) SignerListenerEndpointOption

                                                                                                                                SignerListenerEndpointTimeoutReadWrite sets the read and write timeout for connections from external signing processes.

                                                                                                                                Default: 5s

                                                                                                                                type SignerServer

                                                                                                                                type SignerServer struct {
                                                                                                                                	service.BaseService
                                                                                                                                	// contains filtered or unexported fields
                                                                                                                                }

                                                                                                                                func NewSignerServer

                                                                                                                                func NewSignerServer(endpoint *SignerDialerEndpoint, chainID string, privVal types.PrivValidator) *SignerServer

                                                                                                                                func (*SignerServer) OnStart

                                                                                                                                func (ss *SignerServer) OnStart() error

                                                                                                                                  OnStart implements service.Service.

                                                                                                                                  func (*SignerServer) OnStop

                                                                                                                                  func (ss *SignerServer) OnStop()

                                                                                                                                    OnStop implements service.Service.

                                                                                                                                    func (*SignerServer) SetRequestHandler

                                                                                                                                    func (ss *SignerServer) SetRequestHandler(validationRequestHandler ValidationRequestHandlerFunc)

                                                                                                                                      SetRequestHandler override the default function that is used to service requests

                                                                                                                                      type SignerServiceEndpointOption

                                                                                                                                      type SignerServiceEndpointOption func(*SignerDialerEndpoint)

                                                                                                                                        SignerServiceEndpointOption sets an optional parameter on the SignerDialerEndpoint.

                                                                                                                                        func SignerDialerEndpointConnRetries

                                                                                                                                        func SignerDialerEndpointConnRetries(retries int) SignerServiceEndpointOption

                                                                                                                                          SignerDialerEndpointConnRetries sets the amount of attempted retries to acceptNewConnection.

                                                                                                                                          func SignerDialerEndpointRetryWaitInterval

                                                                                                                                          func SignerDialerEndpointRetryWaitInterval(interval time.Duration) SignerServiceEndpointOption

                                                                                                                                            SignerDialerEndpointRetryWaitInterval sets the retry wait interval to a custom value.

                                                                                                                                            func SignerDialerEndpointTimeoutReadWrite

                                                                                                                                            func SignerDialerEndpointTimeoutReadWrite(timeout time.Duration) SignerServiceEndpointOption

                                                                                                                                              SignerDialerEndpointTimeoutReadWrite sets the read and write timeout for connections from client processes.

                                                                                                                                              type SocketDialer

                                                                                                                                              type SocketDialer func() (net.Conn, error)

                                                                                                                                                SocketDialer dials a remote address and returns a net.Conn or an error.

                                                                                                                                                func DialTCPFn

                                                                                                                                                func DialTCPFn(addr string, timeoutReadWrite time.Duration, privKey crypto.PrivKey) SocketDialer

                                                                                                                                                  DialTCPFn dials the given tcp addr, using the given timeoutReadWrite and privKey for the authenticated encryption handshake.

                                                                                                                                                  func DialUnixFn

                                                                                                                                                  func DialUnixFn(addr string) SocketDialer

                                                                                                                                                    DialUnixFn dials the given unix socket.

                                                                                                                                                    type TCPListener

                                                                                                                                                    type TCPListener struct {
                                                                                                                                                    	*net.TCPListener
                                                                                                                                                    	// contains filtered or unexported fields
                                                                                                                                                    }

                                                                                                                                                      TCPListener wraps a *net.TCPListener to standardise protocol timeouts and potentially other tuning parameters. It also returns encrypted connections.

                                                                                                                                                      func NewTCPListener

                                                                                                                                                      func NewTCPListener(ln net.Listener, secretConnKey ed25519.PrivKey) *TCPListener

                                                                                                                                                        NewTCPListener returns a listener that accepts authenticated encrypted connections using the given secretConnKey and the default timeout values.

                                                                                                                                                        func (*TCPListener) Accept

                                                                                                                                                        func (ln *TCPListener) Accept() (net.Conn, error)

                                                                                                                                                          Accept implements net.Listener.

                                                                                                                                                          type TCPListenerOption

                                                                                                                                                          type TCPListenerOption func(*TCPListener)

                                                                                                                                                            TCPListenerOption sets an optional parameter on the tcpListener.

                                                                                                                                                            func TCPListenerTimeoutAccept

                                                                                                                                                            func TCPListenerTimeoutAccept(timeout time.Duration) TCPListenerOption

                                                                                                                                                              TCPListenerTimeoutAccept sets the timeout for the listener. A zero time value disables the timeout.

                                                                                                                                                              func TCPListenerTimeoutReadWrite

                                                                                                                                                              func TCPListenerTimeoutReadWrite(timeout time.Duration) TCPListenerOption

                                                                                                                                                                TCPListenerTimeoutReadWrite sets the read and write timeout for connections from external signing processes.

                                                                                                                                                                type UnixListener

                                                                                                                                                                type UnixListener struct {
                                                                                                                                                                	*net.UnixListener
                                                                                                                                                                	// contains filtered or unexported fields
                                                                                                                                                                }

                                                                                                                                                                  UnixListener wraps a *net.UnixListener to standardise protocol timeouts and potentially other tuning parameters. It returns unencrypted connections.

                                                                                                                                                                  func NewUnixListener

                                                                                                                                                                  func NewUnixListener(ln net.Listener) *UnixListener

                                                                                                                                                                    NewUnixListener returns a listener that accepts unencrypted connections using the default timeout values.

                                                                                                                                                                    func (*UnixListener) Accept

                                                                                                                                                                    func (ln *UnixListener) Accept() (net.Conn, error)

                                                                                                                                                                      Accept implements net.Listener.

                                                                                                                                                                      type UnixListenerOption

                                                                                                                                                                      type UnixListenerOption func(*UnixListener)

                                                                                                                                                                      func UnixListenerTimeoutAccept

                                                                                                                                                                      func UnixListenerTimeoutAccept(timeout time.Duration) UnixListenerOption

                                                                                                                                                                        UnixListenerTimeoutAccept sets the timeout for the listener. A zero time value disables the timeout.

                                                                                                                                                                        func UnixListenerTimeoutReadWrite

                                                                                                                                                                        func UnixListenerTimeoutReadWrite(timeout time.Duration) UnixListenerOption

                                                                                                                                                                          UnixListenerTimeoutReadWrite sets the read and write timeout for connections from external signing processes.

                                                                                                                                                                          type ValidationRequestHandlerFunc

                                                                                                                                                                          type ValidationRequestHandlerFunc func(
                                                                                                                                                                          	privVal types.PrivValidator,
                                                                                                                                                                          	requestMessage privvalproto.Message,
                                                                                                                                                                          	chainID string) (privvalproto.Message, error)

                                                                                                                                                                            ValidationRequestHandlerFunc handles different remoteSigner requests