rpc

Documentation

Index

• Variables
• func GetPeerCertificate(ctx context.Context) (*x509.Certificate, error)
• func NewAuthenticatedCredentials(cert tls.Certificate, opts ...CredentialsOpt) credentials.TransportCredentials
• func NewAuthenticatedTLSConfig(cert tls.Certificate, opts ...CredentialsOpt) *tls.Config
• func NewEphemeralCredentials(private ed25519.PrivateKey, opts ...CredentialsOpt) (credentials.TransportCredentials, error)
• func RetrieveOwnerCertificate(ctx context.Context, aaa apb.AAAClient, private ed25519.PrivateKey) (*tls.Certificate, error)
• type CredentialsOpt
  • func WantInsecure() CredentialsOpt
  • func WantRemoteCluster(ca *x509.Certificate) CredentialsOpt
  • func WantRemoteNode(id string) CredentialsOpt
• type PeerInfo
  • func GetPeerInfo(ctx context.Context) *PeerInfo
  • func (p *PeerInfo) CheckPermissions(need Permissions) error
  • func (p *PeerInfo) String() string
• type PeerInfoNode
• type PeerInfoUnauthenticated
• type PeerInfoUser
• type Permissions
  • func (p Permissions) String() string
• type ServerSecurity
  • func (s *ServerSecurity) GRPCOptions(logger logging.Leveled) []grpc.ServerOption
• type Span
  • func Trace(ctx context.Context) Span

Variables

var UnknownNotAfter = time.Unix(253402300799, 0)

UnknownNotAfter is a copy of //metroplis/pkg/pki.UnknownNotAfter.

We copy it so that we can decouple the rpc package from the pki package, the former being used by metroctl (and thus needing to be portable), the latter having a dependency on fileargs (which isn't portable). The correct solution here is to clarify portability policy of each workspace path, and apply it. But this will do for now.

TODO(issues/252): clean up and merge this back.

Functions

func GetPeerCertificate

func GetPeerCertificate(ctx context.Context) (*x509.Certificate, error)

GetPeerCertificate returns the x509 certificate associated with the given gRPC connection's context and ensures that it is a certificate for an Ed25519 keypair. The certificate is _not_ checked against the cluster CA.

A gRPC status is returned if the certificate is invalid / unauthenticated for any reason.

func NewAuthenticatedCredentials

func NewAuthenticatedCredentials(cert tls.Certificate, opts ...CredentialsOpt) credentials.TransportCredentials

NewAuthenticatedCredentials returns gRPC TransportCredentials that can be used to dial a cluster with a given TLS certificate (from node or manager credentials).

The provided CredentialsOpt specify the verification of the remote side of the connection. When connecting to a cluster (any node), use WantRemoteCluster. If you also want to verify the connection to a particular node, specify WantRemoteNode alongside it. If no verification should be performed use WantInsecure.

The given options are parsed on a first-wins basis.

func NewAuthenticatedTLSConfig

func NewAuthenticatedTLSConfig(cert tls.Certificate, opts ...CredentialsOpt) *tls.Config

NewAuthenticatedTLSConfig returns a tls.Config that can be used to dial a cluster with a given TLS certificate (from node or manager credentials).

The provided CredentialsOpt specify the verification of the remote side of the connection. When connecting to a cluster (any node), use WantRemoteCluster. If you also want to verify the connection to a particular node, specify WantRemoteNode alongside it. If no verification should be performed use WantInsecure.

The given options are parsed on a first-wins basis.

func NewEphemeralCredentials

func NewEphemeralCredentials(private ed25519.PrivateKey, opts ...CredentialsOpt) (credentials.TransportCredentials, error)

NewEphemeralCredentials returns gRPC TransportCredentials that can be used to dial a cluster without authenticating with a certificate, but instead authenticating by proving the possession of a private key, via an ephemeral self-signed certificate.

Currently these credentials are used in two flows:

1. Registration of nodes into a cluster, after which a node receives a proper node certificate

2. Escrow of initial owner credentials into a proper manager certificate

The given opts can be used to lock down the remote side of the connection, eg. expecting a given cluster CA certificate or disabling remote side verification by using WantInsecure().

func RetrieveOwnerCertificate

func RetrieveOwnerCertificate(ctx context.Context, aaa apb.AAAClient, private ed25519.PrivateKey) (*tls.Certificate, error)

RetrieveOwnerCertificate uses AAA.Escrow to retrieve a cluster manager certificate for the initial owner of the cluster, authenticated by the public/private key set in the clusters NodeParameters.ClusterBoostrap.

The retrieved certificate can be used to dial further cluster RPCs.

Types

type CredentialsOpt

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

CredentialsOpt are created using WantXXX functions and used in NewCredentials.

func WantInsecure

func WantInsecure() CredentialsOpt

WantInsecure disables the verification of the remote side of the connection via NewCredentials. This is unsafe.

func WantRemoteCluster

func WantRemoteCluster(ca *x509.Certificate) CredentialsOpt

WantRemoteCluster enables the verification of the remote cluster identity when using NewAuthanticatedCredentials. If the connection is not terminated at a cluster with the given CA certificate, an error will be returned.

This is the bare minimum option required to implement secure connections to clusters.

func WantRemoteNode

func WantRemoteNode(id string) CredentialsOpt

WantRemoteNode enables the verification of the remote node identity when using NewCredentials. If the connection is not terminated at the node ID 'id', an error will be returned. For this function to work, WantRemoteCluster must also be set.

type PeerInfo

type PeerInfo struct {
	// Node is the information about a peer Node, and identifies that the other side
	// of the connection is either a Node servicng gRPC requests for a cluster, or a
	// Node connecting to a gRPC service.
	Node *PeerInfoNode
	// User is the information about a peer User, and identifies that the other side
	// of the connection is a Metropolis user or manager (eg. owner). This will only
	// be set in service handlers, as users cannot serve gRPC connections.
	User *PeerInfoUser
	// Unauthenticated is set for incoming gRPC connections which that have the
	// Unauthenticated authorization extension set to true, and mark that the other
	// side of the connection has not been verified at all.
	Unauthenticated *PeerInfoUnauthenticated
}

PeerInfo represents the Metropolis-level information about the remote side of a gRPC RPC, ie. about the calling client in server handlers and about the handling server in client code.

Exactly one of {Node, User, Unauthenticated} will be non-nil.

func GetPeerInfo

func GetPeerInfo(ctx context.Context) *PeerInfo

GetPeerInfo returns the PeerInfo of the peer of a gRPC connection, or nil if this connection does not carry any PeerInfo.

func (*PeerInfo) CheckPermissions

func (p *PeerInfo) CheckPermissions(need Permissions) error

func (*PeerInfo) String

func (p *PeerInfo) String() string

type PeerInfoNode

type PeerInfoNode struct {
	// ID is the node identifier.
	ID string

	// Permissions are the set of permissions this node has.
	Permissions Permissions
}

PeerInfoNode contains information about a Node on the other side of a gRPC connection.

type PeerInfoUnauthenticated

type PeerInfoUnauthenticated struct {
	// SelfSignedPublicKey is the ED25519 public key bytes of the other side of the
	// connection, if that side presented a self-signed certificate to prove control
	// of a private key corresponding to this public key. If it did not present a
	// self-signed certificate that can be parsed for such a key, this will be nil.
	//
	// This can be used by code with expects Unauthenticated RPCs but wants to
	// authenticate the connection based on ownership of some keypair, for example
	// in the AAA.Escrow method.
	SelfSignedPublicKey []byte
}

type PeerInfoUser

type PeerInfoUser struct {
	// Identity is an opaque identifier for the user. MVP: Currently this is always
	// "manager".
	Identity string
}

PeerInfoUser contains information about a user on the other side of a gRPC connection.

type Permissions

type Permissions map[epb.Permission]bool

func (Permissions) String

func (p Permissions) String() string

type ServerSecurity

type ServerSecurity struct {
	// NodeCredentials which will be used to run the gRPC server, and whose CA
	// certificate will be used to authenticate incoming requests.
	NodeCredentials *identity.NodeCredentials
	// contains filtered or unexported fields
}

ServerSecurity are the security options of a RPC server that will run cluster services on a Metropolis node. It contains all the data for the server implementation to authenticate itself to the clients and authenticate and authorize clients connecting to it.

func (*ServerSecurity) GRPCOptions

func (s *ServerSecurity) GRPCOptions(logger logging.Leveled) []grpc.ServerOption

GRPCOptions returns a list of gRPC ServerOptions used to run a Metropolis gRPC server with security and logging middleware enabled.

Under the hood, this configures gRPC interceptors that verify metropolis.proto.ext.authorization options and authenticate/authorize incoming connections. It also runs the gRPC server with the correct TLS settings for authenticating itself to callers.

type Span

type Span interface {

	// AddEvent adds an event with the provided name.
	//
	// Changed from otel/trace.Span: no options.
	AddEvent(name string)

	// IsRecording returns the recording state of the Span. It will return true if
	// the Span is active and events can be recorded.
	IsRecording() bool

	// Printf adds an event via AddEvent after performing a string format expansion
	// via fmt.Sprintf. The formatting is performed during the call if the span is
	// recording, or never if it isn't.
	Printf(format string, a ...interface{})
}

Span is used in place of trace.Span until opentelemetry support is fully implemented and thus the library is pulled in. Once that happens, all relevant methods will be replace with an embedding of the trace.Span interface.

func Trace

func Trace(ctx context.Context) Span

Trace returns the active Span for the current Go context. If no Span was set up for this context, an inactive/empty span object is returned, on which every operation is a no-op.