privval

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Jul 18, 2024 License: Apache-2.0 Imports: 26 Imported by: 0

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 *cmtproto.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 *cmtproto.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 cmtbytes.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 *cmtproto.Proposal) error

func (*RetrySignerClient) SignVote 

func (sc *RetrySignerClient) SignVote(chainID string, vote *cmtproto.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 *cmtproto.Proposal) error

SignProposal requests a remote signer to sign a proposal

func (*SignerClient) SignVote 

func (sc *SignerClient) SignVote(chainID string, vote *cmtproto.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 

func (sl *SignerListenerEndpoint) SendRequest(request privvalproto.Message) (*privvalproto.Message, error)

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 standardize 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 standardize 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

Source Files

View all Source files

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.