network

Documentation

Index

• Variables
• type DirectoryManager
• type KeyManager
• type Network
  • func New(conf config.TRISAConfig) (_ Network, err error)
  • func NewMocked(conf *config.TRISAConfig) (_ Network, err error)
• type PeerConstructor
• type PeerDialer
  • func BufnetDialer(bufnet *bufconn.Listener) (_ PeerDialer, err error)
  • func TRISADialer(conf config.TRISAConfig) (_ PeerDialer, err error)
• type PeerManager
• type TRISANetwork
  • func (n *TRISANetwork) Cache(commonName string, pubkey keys.Key) error
  • func (n *TRISANetwork) Close() (err error)
  • func (n *TRISANetwork) Contains(commonName string) (ok bool)
  • func (n *TRISANetwork) Directory() (directory.Directory, error)
  • func (n *TRISANetwork) ExchangeKey(commonName string) (pubkey keys.PublicKey, err error)
  • func (n *TRISANetwork) FromContext(ctx context.Context) (peers.Peer, error)
  • func (n *TRISANetwork) KeyChain() (keychain.KeyChain, error)
  • func (n *TRISANetwork) KeyExchange(ctx context.Context, peer peers.Peer) (seal keys.Key, err error)
  • func (n *TRISANetwork) LookupPeer(ctx context.Context, commonNameOrID, registeredDirectory string) (peer peers.Peer, err error)
  • func (n *TRISANetwork) NPeers() int
  • func (n *TRISANetwork) PeerDialer() PeerDialer
  • func (n *TRISANetwork) Refresh() (err error)
  • func (n *TRISANetwork) Reset()
  • func (n *TRISANetwork) SealingKey(commonName string) (pubkey keys.PublicKey, err error)
  • func (n *TRISANetwork) StorageKey(signature, commonName string) (pubkey keys.PublicKey, err error)
  • func (n *TRISANetwork) String() string
  • func (n *TRISANetwork) UnsealingKey(signature, commonName string) (privkey keys.PrivateKey, err error)

Variables

var (
	ErrNoGRPCPeer             = errors.New("no grpc remote peer info found in context")
	ErrNoKeyChain             = errors.New("no key chain available on network")
	ErrNoDirectory            = errors.New("no directory configured on the network")
	ErrUnknownPeerCertificate = errors.New("could not verify peer certificate subject info")
	ErrUnknownPeerSubject     = errors.New("could not identify common name on certificate subject")
)

Types

type DirectoryManager

type DirectoryManager interface {
	Refresh() error
	Directory() (directory.Directory, error)
}

DirectoryManager provides a high-level interface to a specific directory service.

type KeyManager

type KeyManager interface {
	SealingKey(commonName string) (pubkey keys.PublicKey, err error)
	UnsealingKey(signature, commonName string) (privkey keys.PrivateKey, err error)
	StorageKey(signature, commonName string) (pubkey keys.PublicKey, err error)
	ExchangeKey(commonName string) (pubkey keys.PublicKey, err error)
	Cache(commonName string, pubkey keys.Key) error
	KeyChain() (keychain.KeyChain, error)
}

KeyManager provides a high-level interface to key interactions based on polices and serves as a wrapper for a KeyChain object.

type Network

type Network interface {
	DirectoryManager
	PeerManager
	KeyManager
	io.Closer
	fmt.Stringer
}

Network is a large scale interface that represents the TRISA network by embedding interactions with the TRISA Directory Service, a Peer Manager, and a Key Chain. Both incoming and outgoing TRISA interactions go through the TRISA Network interface.

func New

func New(conf config.TRISAConfig) (_ Network, err error)

New returns a Network object which manages the entire TRISA network including remote peers, public and private key management, and interactions with the Directory Service.

func NewMocked

func NewMocked(conf *config.TRISAConfig) (_ Network, err error)

NewMocked returns a mocked network that is suitable both for testing network functionality as well as testing external packages that depend on the Network, e.g. this isn't a mock network object but rather a mocked network object. The underlying mocking is as follows: a test TRISA config is created, the internal directory is replaced with a MockGDS object and the PeerManager methods return a MockPeer object because the PeerConstructor method is replaced with peers.MockPeer. The KeyChain object and the PeerDialer using mTLS are not mocked and all TRISANetwork functions should be functional using the mocked network.

type PeerConstructor

type PeerConstructor func(info *peers.Info) (peers.Peer, error)

PeerConstructor is used to determine what type of Peer to make. In normal operations a TRISAPeer is created to connect over a real grpc connection to a remote server. In tests, a MockPeer is created to connect to a RemotePeer universal mock object via a bufconn to ensure that the network is correctly creating peers.

type PeerDialer

type PeerDialer func(endpoint string) ([]grpc.DialOption, error)

PeerDialer is used by networks to specify how to connect the Peer object. In normal operation the PeerDialer establishes an mTLS connection using the configuration on the network. For tests, the PeerDialer connects to a RemotePeer universal mock object via a bufconn to ensure the network code is correctly being called.

func BufnetDialer

func BufnetDialer(bufnet *bufconn.Listener) (_ PeerDialer, err error)

BufnetDialer returns a closure that is able to connect the peer to via the bufconn socket. This method is currently unused and is kept for documentation purposes.

func TRISADialer

func TRISADialer(conf config.TRISAConfig) (_ PeerDialer, err error)

TRISADialer returns a closure that is able to dial arbitrary endpoints using mTLS authentication loaded via the certs and pool in the TRISA config. Using a factory method to create the dialer allows us to mock the dialer for testing purposes. NOTE: if the certs change during runtime, the dialer will have to be recreated since the mTLS authority stays on the stack of the closure and is not accessible elsewhere.

type PeerManager

type PeerManager interface {
	FromContext(context.Context) (peers.Peer, error)
	LookupPeer(ctx context.Context, commonNameOrID, registeredDirectory string) (peers.Peer, error)
	KeyExchange(context.Context, peers.Peer) (keys.Key, error)
	PeerDialer() PeerDialer
}

PeerManager is an object that can create connections to remote TRISA peers either from an incoming request context or via unique lookup parameters. All PeerManager methods should return fully resolved (contains valid counterparty info) and connected (using mTLS) peers ready for TRISA network interactions.

type TRISANetwork

type TRISANetwork struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

TRISANetwork implements the Network interface managing TRISA peers.

func (*TRISANetwork) Cache

func (n *TRISANetwork) Cache(commonName string, pubkey keys.Key) error

Cache a public key received from the remote Peer during a key exchange.

func (*TRISANetwork) Close

func (n *TRISANetwork) Close() (err error)

Close connections to directory service, all peer connections, and cleanup. The network is unusable after it is closed and could panic if calls are made to it.

func (*TRISANetwork) Contains

func (n *TRISANetwork) Contains(commonName string) (ok bool)

Contains returns true if the common name is in the cache, used primarily for testing.

func (*TRISANetwork) Directory

func (n *TRISANetwork) Directory() (directory.Directory, error)

func (*TRISANetwork) ExchangeKey

func (n *TRISANetwork) ExchangeKey(commonName string) (pubkey keys.PublicKey, err error)

Get the local public seal key to send to the remote in a key exchange so that the remote Peer can seal envelopes being sent to this node.

func (*TRISANetwork) FromContext

func (n *TRISANetwork) FromContext(ctx context.Context) (peers.Peer, error)

FromContext is used to fetch a resolved and connected Peer object from an incoming mTLS request by parsing the TLSInfo in the gRPC connection to get the common name of the counterparty making the request.

func (*TRISANetwork) KeyChain

func (n *TRISANetwork) KeyChain() (keychain.KeyChain, error)

func (*TRISANetwork) KeyExchange

func (n *TRISANetwork) KeyExchange(ctx context.Context, peer peers.Peer) (seal keys.Key, err error)

KeyExchange conducts a KeyExchange request with the remote peer and then caches the response in the keychain for future use. The key is returned if available.

func (*TRISANetwork) LookupPeer

func (n *TRISANetwork) LookupPeer(ctx context.Context, commonNameOrID, registeredDirectory string) (peer peers.Peer, err error)

LookupPeer by common name or vasp ID, returning a cached peer if one has already been resolved, otherwise performing a directory service lookup and creating the new peer, connecting it so that it's ready for use any time the peer is fetched. This is the primary entry point for all Peer lookups - it can be used directly to get a remote connection for an outgoing peer and is called FromContext to lookup an incoming peer.

NOTE: registeredDirectory is currently unused and can be safely ignored, but is added here for future proofing for the possibility of a distributed directory service.

func (*TRISANetwork) NPeers

func (n *TRISANetwork) NPeers() int

NPeers returns the number of peers in the cache, used primarily for testing.

func (*TRISANetwork) PeerDialer

func (n *TRISANetwork) PeerDialer() PeerDialer

func (*TRISANetwork) Refresh

func (n *TRISANetwork) Refresh() (err error)

Refresh the cached peers by performing a directory members listing and populating the internal cache with connected peers. Routinely refreshing the network listing improves the performance of lookups by preventing per-RPC GDS queries.

func (*TRISANetwork) Reset

func (n *TRISANetwork) Reset()

Reset and empty the cache of peers

func (*TRISANetwork) SealingKey

func (n *TRISANetwork) SealingKey(commonName string) (pubkey keys.PublicKey, err error)

func (*TRISANetwork) StorageKey

func (n *TRISANetwork) StorageKey(signature, commonName string) (pubkey keys.PublicKey, err error)

Get the storage key associated with an unsealing key.

func (*TRISANetwork) String

func (n *TRISANetwork) String() string

String returns the last part of the configured endpoint usually returning vaspdirectory.net or trisatest.net depending on the configuration.

func (*TRISANetwork) UnsealingKey

func (n *TRISANetwork) UnsealingKey(signature, commonName string) (privkey keys.PrivateKey, err error)

Get the private unsealing key either by public key signature on the envelope or by common name from the mTLS certificates in the RPC to unseal an incoming secure envelope sealed by the remote.