node

package
v0.2202.3 Latest Latest
Warning

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

Go to latest
Published: Nov 23, 2022 License: Apache-2.0 Imports: 19 Imported by: 14

Documentation

Overview

Package node implements common node identity routines.

Index

Constants

View Source
const (
	// RoleComputeWorker is the compute worker role.
	RoleComputeWorker RolesMask = 1 << 0

	// RoleKeyManager is the the key manager role.
	RoleKeyManager RolesMask = 1 << 2
	// RoleValidator is the validator role.
	RoleValidator RolesMask = 1 << 3
	// RoleConsensusRPC is the public consensus RPC services worker role.
	RoleConsensusRPC RolesMask = 1 << 4
	// RoleStorageRPC is the public storage RPC services worker role.
	RoleStorageRPC RolesMask = 1 << 5

	// RoleReserved are all the bits of the Oasis node roles bitmask
	// that are reserved and must not be used.
	RoleReserved RolesMask = ((1<<32)-1) & ^((RoleStorageRPC<<1)-1) | roleReserved2

	RoleComputeWorkerName = "compute"
	RoleKeyManagerName    = "key-manager"
	RoleValidatorName     = "validator"
	RoleConsensusRPCName  = "consensus-rpc"
	RoleStorageRPCName    = "storage-rpc"
)
View Source
const (
	// LatestNodeDescriptorVersion is the latest node descriptor version that should be used for all
	// new descriptors. Using earlier versions may be rejected.
	LatestNodeDescriptorVersion = 2
)
View Source
const (
	// LatestSGXAttestationVersion is the latest SGX attestation structure version that should be
	// used for all new descriptors.
	LatestSGXAttestationVersion = 1
)
View Source
const (
	// LatestSGXConstraintsVersion is the latest SGX constraints structure version that should be
	// used for all new descriptors.
	LatestSGXConstraintsVersion = 1
)

Variables

View Source
var (
	// ErrInvalidAddress is the error returned when a transport address is
	// invalid.
	ErrInvalidAddress = errors.New("node: invalid transport address")
	// ErrConsensusAddressNoID is the error returned when a consensus address
	// doesn't have the ID@ part.
	ErrConsensusAddressNoID = errors.New("node: consensus address doesn't have ID@ part")
	// ErrTLSAddressNoPubKey is the error returned when a TLS address doesn't have the PubKey@ part.
	ErrTLSAddressNoPubKey = errors.New("node: TLS address missing PubKey@ part")
)
View Source
var (
	// ErrInvalidRole is the error returned when a node role is invalid.
	ErrInvalidRole = errors.New("node: invalid role")
	// ErrDuplicateRole is the error returned when a node role is duplicated.
	ErrDuplicateRole = errors.New("node: duplicate role")

	// ErrInvalidTEEHardware is the error returned when a TEE hardware
	// implementation is invalid.
	ErrInvalidTEEHardware = errors.New("node: invalid TEE implementation")

	// ErrRAKHashMismatch is the error returned when the TEE attestation
	// does not contain the node's RAK hash.
	ErrRAKHashMismatch = errors.New("node: RAK hash mismatch")

	// ErrBadEnclaveIdentity is the error returned when the TEE enclave
	// identity doesn't match the required values.
	ErrBadEnclaveIdentity = errors.New("node: bad TEE enclave identity")

	// ErrInvalidAttestationSignature is the error returned when the TEE attestation
	// signature fails verification.
	ErrInvalidAttestationSignature = errors.New("node: invalid TEE attestation signature")

	// ErrAttestationNotFresh is the error returned when the TEE attestation is
	// not fresh enough.
	ErrAttestationNotFresh = errors.New("node: TEE attestation not fresh enough")
	// ErrAttestationFromFuture is the error returned when the TEE attestation appears
	// to be from the future.
	ErrAttestationFromFuture = errors.New("node: TEE attestation from the future")

	// AttestationSignatureContext is the signature context used for TEE attestation signatures.
	AttestationSignatureContext = signature.NewContext("oasis-core/node: TEE attestation signature")
)

Functions

func HashAttestation added in v0.2202.0

func HashAttestation(reportData []byte, nodeID signature.PublicKey, height uint64) []byte

HashAttestation hashes the required data that needs to be signed by RAK producing the attestation signature. The hash is computed as follows:

TupleHash[AttestationSignatureContext](reportData, nodeID, height)

func HashRAK added in v0.2202.0

func HashRAK(rak signature.PublicKey) hash.Hash

HashRAK computes the expected report data hash bound to a given public RAK.

Types

type Address

type Address struct {
	IP   net.IP `json:"IP"`
	Port int64  `json:"Port"`
	Zone string `json:"Zone"`
}

Address represents a TCP address for the purpose of node descriptors.

func (*Address) Equal

func (a *Address) Equal(other *Address) bool

Equal compares vs another address for equality.

func (*Address) FromIP

func (a *Address) FromIP(ip net.IP, port uint16) error

FromIP populates the address from a net.IP and port.

func (*Address) IsRoutable

func (a *Address) IsRoutable() bool

IsRoutable returns true iff the address is likely to be globally routable.

func (*Address) MarshalText

func (a *Address) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (Address) String

func (a Address) String() string

String returns the string representation of an address.

func (*Address) ToTCPAddr added in v0.2202.0

func (a *Address) ToTCPAddr() *net.TCPAddr

ToTCPAddr returns a net TCP address.

func (*Address) UnmarshalText

func (a *Address) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

type Capabilities

type Capabilities struct {
	// TEE is the capability of a node executing batches in a TEE.
	TEE *CapabilityTEE `json:"tee,omitempty"`
}

Capabilities represents a node's capabilities.

type CapabilityTEE

type CapabilityTEE struct {
	// TEE hardware type.
	Hardware TEEHardware `json:"hardware"`

	// Runtime attestation key.
	RAK signature.PublicKey `json:"rak"`

	// Attestation.
	Attestation []byte `json:"attestation"`
}

CapabilityTEE represents the node's TEE capability.

func (*CapabilityTEE) Verify

func (c *CapabilityTEE) Verify(teeCfg *TEEFeatures, ts time.Time, height uint64, constraints []byte, nodeID signature.PublicKey) error

Verify verifies the node's TEE capabilities, at the provided timestamp and height.

type ConsensusAddress

type ConsensusAddress struct {
	// ID is public key identifying the node.
	ID signature.PublicKey `json:"id"`
	// Address is the address at which the node can be reached.
	Address Address `json:"address"`
}

ConsensusAddress represents a Tendermint consensus address that includes an ID and a TCP address. NOTE: The consensus address ID could be different from the consensus ID to allow using a sentry node's ID and address instead of the validator's.

func (*ConsensusAddress) MarshalText

func (ca *ConsensusAddress) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (*ConsensusAddress) String

func (ca *ConsensusAddress) String() string

String returns a string representation of a consensus address.

func (*ConsensusAddress) UnmarshalText

func (ca *ConsensusAddress) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

type ConsensusInfo

type ConsensusInfo struct {
	// ID is the unique identifier of the node as a consensus member.
	ID signature.PublicKey `json:"id"`

	// Addresses is the list of addresses at which the node can be reached.
	Addresses []ConsensusAddress `json:"addresses"`
}

ConsensusInfo contains information for connecting to this node as a consensus member.

type MultiSignedNode

type MultiSignedNode struct {
	signature.MultiSigned
}

MultiSignedNode is a multi-signed blob containing a CBOR-serialized Node.

func MultiSignNode

func MultiSignNode(signers []signature.Signer, context signature.Context, node *Node) (*MultiSignedNode, error)

MultiSignNode serializes the Node and multi-signs the result.

func (*MultiSignedNode) Open

func (s *MultiSignedNode) Open(context signature.Context, node *Node) error

Open first verifies the blob signatures and then unmarshals the blob.

func (MultiSignedNode) PrettyPrint

func (s MultiSignedNode) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of the type to the given writer.

func (MultiSignedNode) PrettyType

func (s MultiSignedNode) PrettyType() (interface{}, error)

PrettyType returns a representation of the type that can be used for pretty printing.

type Node

type Node struct {
	cbor.Versioned

	// ID is the public key identifying the node.
	ID signature.PublicKey `json:"id"`

	// EntityID is the public key identifying the Entity controlling
	// the node.
	EntityID signature.PublicKey `json:"entity_id"`

	// Expiration is the epoch in which this node's commitment expires.
	Expiration uint64 `json:"expiration"`

	// TLS contains information for connecting to this node via TLS.
	TLS TLSInfo `json:"tls"`

	// P2P contains information for connecting to this node via P2P.
	P2P P2PInfo `json:"p2p"`

	// Consensus contains information for connecting to this node as a
	// consensus member.
	Consensus ConsensusInfo `json:"consensus"`

	// VRF contains information for this node's participation in VRF
	// based elections.
	VRF *VRFInfo `json:"vrf,omitempty"`

	// DeprecatedBeacon contains information for this node's
	// participation in the old PVSS based random beacon protocol.
	DeprecatedBeacon cbor.RawMessage `json:"beacon,omitempty"`

	// Runtimes are the node's runtimes.
	Runtimes []*Runtime `json:"runtimes"`

	// Roles is a bitmask representing the node roles.
	Roles RolesMask `json:"roles"`

	// SoftwareVersion is the node's oasis-node software version.
	SoftwareVersion string `json:"software_version,omitempty"`
}

Node represents public connectivity information about an Oasis node.

func (*Node) AddOrUpdateRuntime

func (n *Node) AddOrUpdateRuntime(id common.Namespace, version version.Version) *Runtime

AddOrUpdateRuntime searches for an existing supported runtime descriptor in Runtimes with the specified version and returns it. In case a runtime descriptor for the given runtime and version doesn't exist yet, a new one is created appended to the list of supported runtimes and returned.

func (*Node) AddRoles

func (n *Node) AddRoles(r RolesMask)

AddRoles adds a new node role to the existing roles mask.

func (*Node) GetRuntime

func (n *Node) GetRuntime(id common.Namespace, version version.Version) *Runtime

GetRuntime searches for an existing supported runtime descriptor in Runtimes with the specified version and returns it.

func (*Node) HasRoles

func (n *Node) HasRoles(r RolesMask) bool

HasRoles checks if the node has the specified roles.

func (*Node) HasRuntime added in v0.2200.0

func (n *Node) HasRuntime(id common.Namespace) bool

HasRuntime returns true iff the node supports a runtime (ignoring version).

func (*Node) IsExpired

func (n *Node) IsExpired(epoch uint64) bool

IsExpired returns true if the node expiration epoch is strictly smaller than the passed (current) epoch.

func (*Node) OnlyHasRoles

func (n *Node) OnlyHasRoles(r RolesMask) bool

OnlyHasRoles checks if the node only has the specified roles and no others.

func (*Node) String

func (n *Node) String() string

String returns a string representation of itself.

func (*Node) UnmarshalCBOR added in v0.2200.0

func (n *Node) UnmarshalCBOR(data []byte) error

UnmarshalCBOR is a custom deserializer that handles both v1 and v2 Node structures.

func (*Node) ValidateBasic

func (n *Node) ValidateBasic(strictVersion bool) error

ValidateBasic performs basic descriptor validity checks.

type P2PInfo

type P2PInfo struct {
	// ID is the unique identifier of the node on the P2P transport.
	ID signature.PublicKey `json:"id"`

	// Addresses is the list of addresses at which the node can be reached.
	Addresses []Address `json:"addresses"`
}

P2PInfo contains information for connecting to this node via P2P transport.

type RolesMask

type RolesMask uint32

RolesMask is Oasis node roles bitmask.

func Roles added in v0.2012.3

func Roles() (roles []RolesMask)

Roles returns a list of available valid roles.

func (RolesMask) IsSingleRole

func (m RolesMask) IsSingleRole() bool

IsSingleRole returns true if RolesMask encodes a single valid role.

func (RolesMask) MarshalText added in v0.2103.0

func (m RolesMask) MarshalText() ([]byte, error)

MarshalText encodes a RolesMask into text form.

func (RolesMask) String

func (m RolesMask) String() string

func (*RolesMask) UnmarshalText added in v0.2103.0

func (m *RolesMask) UnmarshalText(text []byte) error

UnmarshalText decodes a text slice into a RolesMask.

type Runtime

type Runtime struct {
	// ID is the public key identifying the runtime.
	ID common.Namespace `json:"id"`

	// Version is the version of the runtime.
	Version version.Version `json:"version"`

	// Capabilities are the node's capabilities for a given runtime.
	Capabilities Capabilities `json:"capabilities"`

	// ExtraInfo is the extra per node + per runtime opaque data associated
	// with the current instance.
	ExtraInfo []byte `json:"extra_info"`
}

Runtime represents the runtimes supported by a given Oasis node.

type SGXAttestation added in v0.2202.0

type SGXAttestation struct {
	cbor.Versioned

	// Quote is an Intel SGX quote.
	Quote quote.Quote `json:"quote"`

	// Height is the runtime's view of the consensus layer height at the time of attestation.
	Height uint64 `json:"height"`

	// Signature is the signature of the attestation by the enclave (RAK).
	Signature signature.RawSignature `json:"signature"`
}

SGXAttestation is an Intel SGX remote attestation.

func (*SGXAttestation) MarshalCBOR added in v0.2202.0

func (sa *SGXAttestation) MarshalCBOR() ([]byte, error)

MarshalCBOR is a custom serializer that handles different structure versions.

func (*SGXAttestation) UnmarshalCBOR added in v0.2202.0

func (sa *SGXAttestation) UnmarshalCBOR(data []byte) error

UnmarshalCBOR is a custom deserializer that handles different structure versions.

func (*SGXAttestation) ValidateBasic added in v0.2202.0

func (sa *SGXAttestation) ValidateBasic(cfg *TEEFeatures) error

ValidateBasic performs basic structure validity checks.

func (*SGXAttestation) Verify added in v0.2202.0

func (sa *SGXAttestation) Verify(
	cfg *TEEFeatures,
	ts time.Time,
	height uint64,
	sc *SGXConstraints,
	rak signature.PublicKey,
	nodeID signature.PublicKey,
) error

Verify verifies the SGX attestation.

type SGXConstraints added in v0.2200.0

type SGXConstraints struct {
	cbor.Versioned

	// Enclaves is the allowed MRENCLAVE/MRSIGNER pairs.
	Enclaves []sgx.EnclaveIdentity `json:"enclaves,omitempty"`

	// Policy is the quote policy.
	Policy *quote.Policy `json:"policy,omitempty"`

	// MaxAttestationAge is the maximum attestation age (in blocks).
	MaxAttestationAge uint64 `json:"max_attestation_age,omitempty"`
}

SGXConstraints are the Intel SGX TEE constraints.

func (*SGXConstraints) ContainsEnclave added in v0.2202.0

func (sc *SGXConstraints) ContainsEnclave(eid sgx.EnclaveIdentity) bool

ContainsEnclave returns true iff the allowed enclave list in SGX constraints contain the given enclave identity.

func (*SGXConstraints) MarshalCBOR added in v0.2202.0

func (sc *SGXConstraints) MarshalCBOR() ([]byte, error)

MarshalCBOR is a custom serializer that handles different structure versions.

func (*SGXConstraints) UnmarshalCBOR added in v0.2202.0

func (sc *SGXConstraints) UnmarshalCBOR(data []byte) error

UnmarshalCBOR is a custom deserializer that handles different structure versions.

func (*SGXConstraints) ValidateBasic added in v0.2202.0

func (sc *SGXConstraints) ValidateBasic(cfg *TEEFeatures) error

ValidateBasic performs basic structure validity checks.

type TEEFeatures added in v0.2202.0

type TEEFeatures struct {
	// SGX contains the supported TEE features for Intel SGX.
	SGX TEEFeaturesSGX `json:"sgx"`

	// FreshnessProofs is a feature flag specifying whether ProveFreshness transactions are
	// supported and processed, or ignored and handled as non-existing transactions.
	FreshnessProofs bool `json:"freshness_proofs"`
}

TEEFeatures are the supported TEE features as advertised by the consensus layer.

type TEEFeaturesSGX added in v0.2202.0

type TEEFeaturesSGX struct {
	// PCS is a feature flag specifying whether support for Platform Certification Service-based
	// remote attestation is supported for Intel SGX-based TEEs.
	PCS bool `json:"pcs"`

	// SignedAttestations is a feature flag specifying whether attestations need to include an
	// additional signature binding it to a specific node.
	SignedAttestations bool `json:"signed_attestations,omitempty"`

	// DefaultPolicy is the default quote policy.
	DefaultPolicy *quote.Policy `json:"default_policy,omitempty"`

	// DefaultMaxAttestationAge is the default maximum attestation age (in blocks).
	DefaultMaxAttestationAge uint64 `json:"max_attestation_age,omitempty"`
}

TEEFeaturesSGX are the supported Intel SGX-specific TEE features.

func (*TEEFeaturesSGX) ApplyDefaultConstraints added in v0.2202.0

func (fs *TEEFeaturesSGX) ApplyDefaultConstraints(sc *SGXConstraints)

ApplyDefaultConstraints applies configured SGX constraint defaults to the given structure.

type TEEHardware

type TEEHardware uint8

TEEHardware is a TEE hardware implementation.

const (
	// TEEHardwareInvalid is a non-TEE implementation.
	TEEHardwareInvalid TEEHardware = 0
	// TEEHardwareIntelSGX is an Intel SGX TEE implementation.
	TEEHardwareIntelSGX TEEHardware = 1

	// TEEHardwareReserved is the first reserved hardware implementation
	// identifier. All equal or greater identifiers are reserved.
	TEEHardwareReserved TEEHardware = TEEHardwareIntelSGX + 1
)

TEE Hardware implementations.

func (*TEEHardware) FromString

func (h *TEEHardware) FromString(str string) error

FromString deserializes a string into a TEEHardware.

func (TEEHardware) String

func (h TEEHardware) String() string

String returns the string representation of a TEEHardware.

type TLSAddress

type TLSAddress struct {
	// PubKey is the public key used for establishing TLS connections.
	PubKey signature.PublicKey `json:"pub_key"`

	// Address is the address at which the node can be reached.
	Address Address `json:"address"`
}

TLSAddress represents an Oasis committee address that includes a TLS public key and a TCP address.

NOTE: The address TLS public key can be different from the actual node TLS public key to allow using a sentry node's addresses.

func (*TLSAddress) Equal

func (ta *TLSAddress) Equal(other *TLSAddress) bool

Equal compares vs another TLSAddress for equality.

func (*TLSAddress) MarshalText

func (ta *TLSAddress) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (*TLSAddress) String

func (ta *TLSAddress) String() string

String returns a string representation of a TLS address.

func (*TLSAddress) UnmarshalText

func (ta *TLSAddress) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

type TLSInfo

type TLSInfo struct {
	// PubKey is the public key used for establishing TLS connections.
	PubKey signature.PublicKey `json:"pub_key"`

	// NextPubKey is the public key that will be used for establishing TLS connections after
	// certificate rotation (if enabled).
	NextPubKey signature.PublicKey `json:"next_pub_key,omitempty"`

	// Addresses is the list of addresses at which the node can be reached.
	Addresses []TLSAddress `json:"addresses"`
}

TLSInfo contains information for connecting to this node via TLS.

func (*TLSInfo) Equal

func (t *TLSInfo) Equal(other *TLSInfo) bool

Equal compares vs another TLSInfo for equality.

type VRFInfo added in v0.2200.0

type VRFInfo struct {
	// ID is the unique identifier of the node used to generate VRF proofs.
	ID signature.PublicKey `json:"id"`
}

VRFInfo contains information for this node's participation in VRF based elections.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL