infra

Documentation

Overview

Package infra contains common definitions for the SCION infrastructure messaging layer.

Index

• Constants
• Variables
• func NewContextWithResponseWriter(ctx context.Context, rw ResponseWriter) context.Context
• type ASInspector
• type ASInspectorOpts
• type Attribute
• type ChainOpts
• type CryptoHandlerFactory
• type CryptoMaterialProvider
• type Error
  • func (e *Error) Error() string
• type ExtendedCryptoHandlerFactory
• type ExtendedTrustStore
• type Handler
  • func NewResourceAwareHandler(handler Handler, resources ...ResourceHealth) Handler
• type HandlerFunc
  • func (f HandlerFunc) Handle(r *Request) *HandlerResult
• type HandlerResult
  • func MetricsErrMsger(err error) *HandlerResult
  • func MetricsErrRevCache(err error) *HandlerResult
  • func MetricsErrTrustDB(err error) *HandlerResult
  • func MetricsErrTrustStore(err error) *HandlerResult
  • func MetricsErrWithTimeout(err error, timeoutResult, result *HandlerResult) *HandlerResult
• type MessageType
  • func (mt MessageType) MetricLabel() string
  • func (mt MessageType) String() string
• type Messenger
• type Request
  • func NewRequest(ctx context.Context, msg, fullMsg proto.Cerealizable, peer net.Addr, id uint64) *Request
  • func (r *Request) Context() context.Context
• type ResourceHealth
• type ResponseWriter
  • func ResponseWriterFromContext(ctx context.Context) (ResponseWriter, bool)
• type SignatureTimestampRange
• type Signer
• type SignerMeta
• type TRCOpts
• type Transport
• type TrustStore
• type TrustStoreOpts
• type VerificationFactory
• type Verifier

Constants

const (
	ErrLayerClosed common.ErrMsg = "layer closed"
	ErrAdapter     common.ErrMsg = "msg adapter error"
	ErrInternal    common.ErrMsg = "internal error"
	ErrTransport   common.ErrMsg = "transport error"
)

const (
	PromSrcASLocal   = "as_local"
	PromSrcISDLocal  = "isd_local"
	PromSrcISDRemote = "isd_remote"
	PromSrcUnknown   = "unknown"
)

Variables

var (
	// NullSigner is a Signer that creates SignedPld's with no signature.
	NullSigner Signer = nullSigner{}
	// NullSigVerifier ignores signatures on all messages.
	NullSigVerifier Verifier = nullSigVerifier{}
)

var (
	MetricsErrInternal = &HandlerResult{Result: "err_internal", Status: prom.StatusErr}
	MetricsErrInvalid  = &HandlerResult{Result: "err_invalid_req", Status: prom.StatusErr}

	MetricsResultOk = &HandlerResult{Result: prom.Success, Status: prom.StatusOk}
)

Functions

func NewContextWithResponseWriter

func NewContextWithResponseWriter(ctx context.Context, rw ResponseWriter) context.Context

Types

type ASInspector

type ASInspector interface {
	// ByAttributes returns a list of primary ASes in the specified ISD that
	// hold all the requested attributes.
	ByAttributes(ctx context.Context, isd addr.ISD, args ASInspectorOpts) ([]addr.IA, error)
	// HasAttributes indicates whether an AS holds all the specified attributes.
	// The first return value is always false for non-primary ASes.
	HasAttributes(ctx context.Context, ia addr.IA, args ASInspectorOpts) (bool, error)
}

ASInspector provides information about primary ASes.

type ASInspectorOpts

type ASInspectorOpts struct {
	TrustStoreOpts
	// RequiredAttributes is a list off all attributes the primary AS must have.
	RequiredAttributes []Attribute
}

ASInspectorOpts contains the options for request about primary ASes.

type Attribute

type Attribute int

Attribute is a place holder for new the primary AS attributes. TODO(roosd): remove

const (
	Authoritative Attribute = iota
	Core
	Issuing
	Voting
)

Core is the place holder core attribute. TODO(roosd): remove

type ChainOpts

type ChainOpts struct {
	TrustStoreOpts
	// AllowInactiveTRC allows retrieving chains authenticated by no longer
	// active TRCs.
	AllowInactiveTRC bool
}

ChainOpts contains the options when fetching certificate chains.

type CryptoHandlerFactory

type CryptoHandlerFactory interface {
	NewTRCReqHandler(recurseAllowed bool) Handler
	NewChainReqHandler(recurseAllowed bool) Handler
}

CryptoHandlerFactory provides handlers for incoming crypto material requests.

type CryptoMaterialProvider

type CryptoMaterialProvider interface {
	// GetChain returns a valid certificate chain or an error. If the chain is
	// not found locally, it is requested over the network unless LocalOnly is set.
	GetChain(ctx context.Context, ia addr.IA, version scrypto.Version, opts ChainOpts) (
		*cert.Chain, error)
	// GetTRC returns a valid and active TRC or an error. If the TRC is not
	// found locally, it is requested over the network unless LocalOnly is set.
	GetTRC(ctx context.Context, isd addr.ISD, version scrypto.Version, opts TRCOpts) (
		*trc.TRC, error)
}

CryptoMaterialProvider provides crypto material.

type Error

type Error struct {
	Message *ack.Ack
}

func (*Error) Error

func (e *Error) Error() string

type ExtendedCryptoHandlerFactory

type ExtendedCryptoHandlerFactory interface {
	CryptoHandlerFactory
	NewChainPushHandler() Handler
	NewTRCPushHandler() Handler
}

ExtendedCryptoHandlerFactory provides handlers for incoming crypto material requests, and crypto material pushes.

type ExtendedTrustStore

type ExtendedTrustStore interface {
	ASInspector
	VerificationFactory
	ExtendedCryptoHandlerFactory
	CryptoMaterialProvider
}

ExtendedTrustStore extends the TrustStore interface to allow for more interactions. Regular infra services should use the TrustStore interface instead.

type Handler

type Handler interface {
	Handle(*Request) *HandlerResult
}

Handler is implemented by objects that can handle a request coming from a remote SCION network node.

func NewResourceAwareHandler

func NewResourceAwareHandler(handler Handler, resources ...ResourceHealth) Handler

NewResourceAwareHandler creates a decorated handler that calls the underlying handler if all resources are healthy, otherwise it replies with an error message.

type HandlerFunc

type HandlerFunc func(r *Request) *HandlerResult

Constructs a handler for request r. Handle() can be called on the resulting object to process the message.

func (HandlerFunc) Handle

func (f HandlerFunc) Handle(r *Request) *HandlerResult

type HandlerResult

type HandlerResult struct {
	// Result is the label used for the result metric.
	Result string
	// Status is one of prom.StatusOk, prom.StatusErr, prom.StatusTimeout it is used for the latency
	// histogram. This is a reduced view of the result, so that we don't get too many timeseries on
	// the histogram.
	Status string
}

HandlerResult contains a result label and a status label.

func MetricsErrMsger

func MetricsErrMsger(err error) *HandlerResult

func MetricsErrRevCache

func MetricsErrRevCache(err error) *HandlerResult

func MetricsErrTrustDB

func MetricsErrTrustDB(err error) *HandlerResult

func MetricsErrTrustStore

func MetricsErrTrustStore(err error) *HandlerResult

func MetricsErrWithTimeout

func MetricsErrWithTimeout(err error, timeoutResult, result *HandlerResult) *HandlerResult

MetricsErrWithTimeout checks if the error is a timeout and if so returns timeoutResult otherwise returns result.

type MessageType

type MessageType int

const (
	None MessageType = iota
	TRC
	TRCRequest
	Chain
	ChainRequest
	IfId
	IfStateInfos
	IfStateReq
	Seg
	SegChangesReq
	SegChangesReply
	SegChangesIdReq
	SegChangesIdReply
	SegReg
	SegRequest
	SegReply
	SignedRev
	SegSync
	ChainIssueRequest
	ChainIssueReply
	Ack
	HPSegReg
	HPSegRequest
	HPSegReply
	HPCfgRequest
	HPCfgReply
)

func (MessageType) MetricLabel

func (mt MessageType) MetricLabel() string

MetricLabel returns the label for metrics for a given message type. The postfix for requests is always "req" and for replies and push messages it is always "push".

func (MessageType) String

func (mt MessageType) String() string

type Messenger

type Messenger interface {
	SendAck(ctx context.Context, msg *ack.Ack, a net.Addr, id uint64) error
	// GetTRC sends a cert_mgmt.TRCReq request to address a, blocks until it receives a
	// reply and returns the reply.
	GetTRC(ctx context.Context, msg *cert_mgmt.TRCReq, a net.Addr,
		id uint64) (*cert_mgmt.TRC, error)
	// SendTRC sends a reliable cert_mgmt.TRC to address a.
	SendTRC(ctx context.Context, msg *cert_mgmt.TRC, a net.Addr, id uint64) error
	// GetCertChain sends a cert_mgmt.ChainReq to address a, blocks until it
	// receives a reply and returns the reply.
	GetCertChain(ctx context.Context, msg *cert_mgmt.ChainReq, a net.Addr,
		id uint64) (*cert_mgmt.Chain, error)
	// SendCertChain sends a reliable cert_mgmt.Chain to address a.
	SendCertChain(ctx context.Context, msg *cert_mgmt.Chain, a net.Addr, id uint64) error
	// SendIfId sends a reliable ifid.IFID to address a.
	SendIfId(ctx context.Context, msg *ifid.IFID, a net.Addr, id uint64) error
	// SendIfStateInfos sends a reliable path_mgmt.IfStateInfos to address a.
	SendIfStateInfos(ctx context.Context, msg *path_mgmt.IFStateInfos, a net.Addr, id uint64) error
	// SendRev sends a reliable revocation to a.
	SendRev(ctx context.Context, msg *path_mgmt.SignedRevInfo, a net.Addr, id uint64) error
	// SendSegReg sends a reliable path_mgmt.SegReg to a.
	SendSegReg(ctx context.Context, msg *path_mgmt.SegReg, a net.Addr, id uint64) error
	// GetSegs asks the server at the remote address for the path segments that
	// satisfy msg, and returns a verified reply.
	GetSegs(ctx context.Context, msg *path_mgmt.SegReq, a net.Addr,
		id uint64) (*path_mgmt.SegReply, error)
	// SendSegReply sends a reliable path_mgmt.SegReply to address a.
	SendSegReply(ctx context.Context, msg *path_mgmt.SegReply, a net.Addr, id uint64) error
	// SendSegSync sends a reliable path_mgmt.SegSync to address a.
	SendSegSync(ctx context.Context, msg *path_mgmt.SegSync, a net.Addr, id uint64) error
	GetSegChangesIds(ctx context.Context, msg *path_mgmt.SegChangesIdReq,
		a net.Addr, id uint64) (*path_mgmt.SegChangesIdReply, error)
	SendSegChangesIdReply(ctx context.Context,
		msg *path_mgmt.SegChangesIdReply, a net.Addr, id uint64) error
	GetSegChanges(ctx context.Context, msg *path_mgmt.SegChangesReq,
		a net.Addr, id uint64) (*path_mgmt.SegChangesReply, error)
	SendSegChangesReply(ctx context.Context,
		msg *path_mgmt.SegChangesReply, a net.Addr, id uint64) error
	SendHPSegReg(ctx context.Context, msg *path_mgmt.HPSegReg, a net.Addr, id uint64) error
	GetHPSegs(ctx context.Context, msg *path_mgmt.HPSegReq, a net.Addr,
		id uint64) (*path_mgmt.HPSegReply, error)
	SendHPSegReply(ctx context.Context, msg *path_mgmt.HPSegReply, a net.Addr, id uint64) error
	GetHPCfgs(ctx context.Context, msg *path_mgmt.HPCfgReq, a net.Addr,
		id uint64) (*path_mgmt.HPCfgReply, error)
	SendHPCfgReply(ctx context.Context, msg *path_mgmt.HPCfgReply, a net.Addr, id uint64) error
	RequestChainIssue(ctx context.Context, msg *cert_mgmt.ChainIssReq, a net.Addr,
		id uint64) (*cert_mgmt.ChainIssRep, error)
	SendChainIssueReply(ctx context.Context, msg *cert_mgmt.ChainIssRep, a net.Addr,
		id uint64) error
	SendBeacon(ctx context.Context, msg *seg.Beacon, a net.Addr, id uint64) error
	UpdateSigner(signer Signer, types []MessageType)
	UpdateVerifier(verifier Verifier)
	AddHandler(msgType MessageType, h Handler)
	ListenAndServe()
	CloseServer() error
}

type Request

type Request struct {
	// Message is the inner proto.Cerealizable message, as supported by
	// messenger.Messenger (e.g., a *cert_mgmt.ChainReq). For information about
	// possible messages, see the package documentation for that package.
	Message proto.Cerealizable
	// FullMessage is the top-level SignedCtrlPld message read from the wire
	FullMessage proto.Cerealizable
	// Peer is the node that sent this request
	Peer net.Addr
	// ID is the CtrlPld top-level ID.
	ID uint64
	// contains filtered or unexported fields
}

Request describes an object received from the network that is not part of an exchange initiated by the local node. A Request includes its associated context.

func NewRequest

func NewRequest(ctx context.Context, msg, fullMsg proto.Cerealizable, peer net.Addr,
	id uint64) *Request

func (*Request) Context

func (r *Request) Context() context.Context

Context returns the request's context.

type ResourceHealth

type ResourceHealth interface {
	// Name returns the name of this resource.
	Name() string
	// IsHealthy returns whether the resource is considered healthy currently.
	// This method must not be blocking and should have the result cached and return ~immediately.
	IsHealthy() bool
}

ResourceHealth indicates the health of a resource. A resource could for example be a database. The resource health can be added to a handler, so that the handler only replies if all it's resources are healthy.

type ResponseWriter

type ResponseWriter interface {
	SendAckReply(ctx context.Context, msg *ack.Ack) error
	SendTRCReply(ctx context.Context, msg *cert_mgmt.TRC) error
	SendCertChainReply(ctx context.Context, msg *cert_mgmt.Chain) error
	SendChainIssueReply(ctx context.Context, msg *cert_mgmt.ChainIssRep) error
	SendSegReply(ctx context.Context, msg *path_mgmt.SegReply) error
	SendIfStateInfoReply(ctx context.Context, msg *path_mgmt.IFStateInfos) error
	SendHPSegReply(ctx context.Context, msg *path_mgmt.HPSegReply) error
	SendHPCfgReply(ctx context.Context, msg *path_mgmt.HPCfgReply) error
}

func ResponseWriterFromContext

func ResponseWriterFromContext(ctx context.Context) (ResponseWriter, bool)

type SignatureTimestampRange

type SignatureTimestampRange struct {
	// MaxPldAge determines the maximum age of a control payload signature.
	MaxPldAge time.Duration
	// MaxInFuture determines the maximum time a timestamp may be in the future.
	MaxInFuture time.Duration
}

SignatureTimestampRange configures the range a signature timestamp is considered valid. This allows for small clock drifts in the network.

type Signer

type Signer interface {
	ctrl.Signer
	Meta() SignerMeta
}

Signer is a signer leveraging the control-plane PKI certificates.

type SignerMeta

type SignerMeta struct {
	// Src is the signature source, containing the certificate chain version.
	Src ctrl.SignSrcDef
	// ExpTime indicates the expiration time of the certificate chain.
	ExpTime time.Time
	// Algo indicates the signing algorithm.
	Algo string
}

SignerMeta indicates what signature metadata the signer uses as a basis when creating signatures.

type TRCOpts

type TRCOpts struct {
	TrustStoreOpts
	// AllowInactive allows retrieving verified TRCs that are no longer active.
	AllowInactive bool
}

TRCOpts contains the options when fetching TRCs.

type Transport

type Transport interface {
	// Send an unreliable message. Unreliable transport layers do not request
	// an ACK. For reliable transport layers, this is the same as SendMsgTo.
	SendUnreliableMsgTo(context.Context, common.RawBytes, net.Addr) error
	// Send a reliable message. Unreliable transport layers block here waiting
	// for the message to be ACK'd. Reliable transport layers return
	// immediately.
	SendMsgTo(context.Context, common.RawBytes, net.Addr) error
	// Receive a message.
	RecvFrom(context.Context) (common.RawBytes, net.Addr, error)
	// Clean up.
	Close(context.Context) error
}

Interface Transport wraps around low-level networking objects to provide reliable and unreliable delivery of network packets, together with context-aware networking that can be used to construct handlers with timeouts.

Transport layers must be safe for concurrent use by multiple goroutines.

type TrustStore

type TrustStore interface {
	ASInspector
	CryptoHandlerFactory
	VerificationFactory
}

TrustStore is the interface to interact with the control-plane PKI.

type TrustStoreOpts

type TrustStoreOpts struct {
	// Server provides an address where the store should send crypto material
	// request, if they are not available locally. If it is not set, the
	// trust store does its own server resolution.
	Server net.Addr
	// LocalOnly indicates that the store should only check locally.
	LocalOnly bool
}

TrustStoreOpts contains the base options when interacting with the trust store.

type VerificationFactory

type VerificationFactory interface {
	NewSigner(key common.RawBytes, meta SignerMeta) (Signer, error)
	NewVerifier() Verifier
}

VerificationFactory provides objects for message signing and verification based on control-plane PKI certificates.

type Verifier

type Verifier interface {
	ctrl.Verifier
	Verify(ctx context.Context, msg common.RawBytes, sign *proto.SignS) error
	// WithServer returns a verifier that fetches the necessary crypto
	// objects from the specified server.
	WithServer(server net.Addr) Verifier
	// WithIA returns a verifier that only accepts signatures from the
	// specified AS. Zero values in the ISD-AS pair are considered a wild
	// card.
	WithIA(ia addr.IA) Verifier
	// WithSrc returns a verifier that is bound to the specified source.
	// It verifies against the specified source, and not the value
	// provided by the sign meta data.
	WithSrc(src ctrl.SignSrcDef) Verifier
	// WithSignatureTimestampRange returns a verifier that uses the specified
	// signature timestamp range configuration.
	WithSignatureTimestampRange(timestampRange SignatureTimestampRange) Verifier
}

Verifier is used to verify payloads signed with control-plane PKI certificates.