node

package
v0.2402.0 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2024 License: Apache-2.0 Imports: 21 Imported by: 14

Documentation

Overview

Package node implements common node identity routines.

Index

Constants

View Source 
const (
	// RoleEmpty is the roles bitmask that specifies no roles.
	RoleEmpty RolesMask = 0
	// RoleComputeWorker is the compute worker role.
	RoleComputeWorker RolesMask = 1 << 0
	// RoleObserver is the observer role.
	RoleObserver RolesMask = 1 << 1
	// RoleKeyManager is the the key manager role.
	RoleKeyManager RolesMask = 1 << 2
	// RoleValidator is the validator role.
	RoleValidator RolesMask = 1 << 3

	// 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) | roleReserved3

	RoleComputeWorkerName = "compute"
	RoleObserverName      = "observer"
	RoleKeyManagerName    = "key-manager"
	RoleValidatorName     = "validator"
	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 = 3
)
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")

	// 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")
)
View Source 
var EndorseCapabilityTEESignatureContext = signature.NewContext("oasis-core/node: endorse TEE capability")

EndorseCapabilityTEESignatureContext is the signature context used for TEE capability endorsement.

Functions

func HashAttestation added in v0.2202.0 

func HashAttestation(reportData []byte, nodeID signature.PublicKey, height uint64, rek *x25519.PublicKey) []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, *rek)

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) MultiAddress added in v0.2300.0 

func (a Address) MultiAddress() (multiaddr.Multiaddr, error)

MultiAddress returns a multi address representation of the address.

func (Address) MultiAddressStr added in v0.2300.0 

func (a Address) MultiAddressStr() string

MultiAddressStr returns a multi address string representation of the address.

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"`

	// Runtime encryption key.
	REK *x25519.PublicKey `json:"rek,omitempty"`

	// 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 CometBFT 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 EndorsedCapabilityTEE added in v0.2400.0 

type EndorsedCapabilityTEE struct {
	// CapabilityTEE is the TEE capability structure to be endorsed.
	CapabilityTEE CapabilityTEE `json:"capability_tee"`

	// NodeEndorsement is the node endorsement signature.
	NodeEndorsement signature.Signature `json:"node_endorsement"`
}

EndorsedCapabilityTEE is the endorsed CapabilityTEE structure.

Endorsement is needed for off-chain runtime components where their RAK is not published in the consensus layer and verification is part of the runtime itself. Via endorsement one can enforce policies like "only components executed by the current compute committee are authorized".

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"`

	// 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 SoftwareVersion `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 V2 and V3 Node descriptors.

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) IsEmptyRole added in v0.2401.0 

func (m RolesMask) IsEmptyRole() bool

IsEmptyRole returns true if RolesMask encodes no roles (e.g. is equal to RoleEmpty).

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,
	rek *x25519.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 SoftwareVersion added in v0.2300.0 

type SoftwareVersion string

SoftwareVersion is the node's oasis-node software version.

func (SoftwareVersion) ValidateBasic added in v0.2300.0 

func (sw SoftwareVersion) ValidateBasic() error

ValidateBasic performs basic software version 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"`
}

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.

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.