churp

package
v0.2403.1 Latest Latest
Warning

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

 Go to latest Published: Nov 29, 2024 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// GasOpCreate is the gas operation identifier for creation costs.
	GasOpCreate transaction.Op = "create"
	// GasOpUpdate is the gas operation identifier for update costs.
	GasOpUpdate transaction.Op = "update"
	// GasOpApply is the gas operation identifier for application costs.
	GasOpApply transaction.Op = "apply"
	// GasOpConfirm is the gas operation identifier for confirmation costs.
	GasOpConfirm transaction.Op = "confirm"
)
View Source 
const (
	// HandoffsDisabled is the epoch of the next handoff when handoffs
	// are disabled, i.e., when the handoff interval is set to zero.
	HandoffsDisabled = beacon.EpochInvalid
)
View Source 
const (
	// ModuleName is the module name for CHURP extension.
	ModuleName = "keymanager/churp"
)
View Source 
const (
	// NistP384Sha3_384 represents the NIST P-384 elliptic curve group with
	// the SHA3-384 hash function used to encode arbitrary-length byte strings
	// to elements of the underlying prime field or elliptic curve points.
	NistP384Sha3_384 uint8 = iota
)
View Source 
const (
	// StakeClaimScheme is the stake claim template used for creating
	// new CHURP schemes.
	StakeClaimScheme = "keymanager.churp.Scheme.%s.%d"
)

Variables

View Source 
var (
	// ErrNoSuchStatus is the error returned when a CHURP status does not exist.
	ErrNoSuchStatus = errors.New(ModuleName, 1, "keymanager: churp: no such status")

	// MethodCreate is the method name for creating a new CHURP instance.
	MethodCreate = transaction.NewMethodName(ModuleName, "Create", CreateRequest{})

	// MethodUpdate is the method name for CHURP updates.
	MethodUpdate = transaction.NewMethodName(ModuleName, "Update", UpdateRequest{})

	// MethodApply is the method name for a node submitting an application
	// to form a new committee.
	MethodApply = transaction.NewMethodName(ModuleName, "Apply", ApplicationRequest{})

	// MethodConfirm is the method name for a node confirming completion
	// of a handoff.
	MethodConfirm = transaction.NewMethodName(ModuleName, "Confirm", ConfirmationRequest{})

	// Methods is the list of all methods supported by the CHURP extension.
	Methods = []transaction.MethodName{
		MethodCreate,
		MethodUpdate,
		MethodApply,
		MethodConfirm,
	}
)
View Source 
var (
	// ApplicationRequestSignatureContext is the signature context used to sign
	// application requests with runtime signing key (RAK).
	ApplicationRequestSignatureContext = signature.NewContext("oasis-core/keymanager/churp: application request")

	// ConfirmationRequestSignatureContext is the signature context used to sign
	// confirmation requests with runtime signing key (RAK).
	ConfirmationRequestSignatureContext = signature.NewContext("oasis-core/keymanager/churp: confirmation request")
)
View Source 
var (
	// RPCMethodApply is the name of the `apply` method.
	RPCMethodApply = "churp/apply"

	// RPCMethodShareReduction is the name of the `share_reduction` method.
	RPCMethodShareReduction = "churp/share_reduction"

	// RPCMethodShareDistribution is the name of the `share_distribution` method.
	RPCMethodShareDistribution = "churp/share_distribution"

	// RPCMethodProactivization is the name of the `proactivization` method.
	RPCMethodProactivization = "churp/proactivization"

	// RPCMethodConfirm is the name of the `confirm` method.
	RPCMethodConfirm = "churp/confirm"

	// RPCMethodFinalize is the name of the `finalize` method.
	RPCMethodFinalize = "churp/finalize"

	// RPCMethodVerificationMatrix is the name of the `verification_matrix` method.
	RPCMethodVerificationMatrix = "churp/verification_matrix"

	// RPCMethodShareReductionPoint is the name of the `share_reduction_point` method.
	RPCMethodShareReductionPoint = "churp/share_reduction_point"

	// RPCMethodShareDistributionPoint is the name of the `share_distribution_point` method.
	RPCMethodShareDistributionPoint = "churp/share_distribution_point"

	// RPCMethodBivariateShare is the name of the `bivariate_share` method.
	RPCMethodBivariateShare = "churp/bivariate_share"

	// RPCMethodSGXPolicyKeyShare is the name of the `sgx_policy_key_share` method.
	RPCMethodSGXPolicyKeyShare = "churp/sgx_policy_key_share"
)
View Source 
var DefaultConsensusParameters = ConsensusParameters{
	GasCosts: DefaultGasCosts,
}

DefaultConsensusParameters are the "default" consensus parameters.

View Source 
var DefaultGasCosts = transaction.Costs{
	GasOpCreate:  1000,
	GasOpUpdate:  1000,
	GasOpApply:   1000,
	GasOpConfirm: 1000,
}

DefaultGasCosts are the "default" gas costs for operations.

View Source 
var PolicySGXSignatureContext = signature.NewContext("oasis-core/keymanager/churp: policy")

PolicySGXSignatureContext is the context used to sign PolicySGX documents.

Functions

func AddStakeClaims 

func AddStakeClaims(statuses []*Status, runtimes []*registry.Runtime, escrows map[staking.Address]*staking.EscrowAccount) error

AddStakeClaims adds stake claims for the given schemes.

func NewApplyTx 

func NewApplyTx(nonce uint64, fee *transaction.Fee, req *SignedApplicationRequest) *transaction.Transaction

NewApplyTx creates a new apply transaction.

func NewConfirmTx 

func NewConfirmTx(nonce uint64, fee *transaction.Fee, req *SignedConfirmationRequest) *transaction.Transaction

NewConfirmTx creates a new confirm transaction.

func NewCreateTx 

func NewCreateTx(nonce uint64, fee *transaction.Fee, req *CreateRequest) *transaction.Transaction

NewCreateTx creates a new create transaction.

func NewUpdateTx 

func NewUpdateTx(nonce uint64, fee *transaction.Fee, req *UpdateRequest) *transaction.Transaction

NewUpdateTx creates a new update transaction.

func RegisterService 

func RegisterService(server *grpc.Server, service Backend)

RegisterService registers a new keymanager CHURP backend service with the given gRPC server.

func StakeClaim 

func StakeClaim(runtimeID common.Namespace, churpID uint8) staking.StakeClaim

StakeClaim generates a new stake claim identifier for a specific scheme creation.

func StakeThresholds 

func StakeThresholds() []staking.StakeThreshold

StakeThresholds returns the staking thresholds.

Types

type Application 

type Application struct {
	// Checksum is the hash of the random verification matrix.
	//
	// In all handoffs, except in the dealer phase, the verification matrix
	// needs to be zero-hole.
	Checksum hash.Hash `json:"checksum"`

	// Reconstructed is true if and only if the node verified all matrices
	// and successfully reconstructed its share during the handoff.
	Reconstructed bool `json:"reconstructed"`
}

Application represents a node's application to form a new committee.

type ApplicationRequest 

type ApplicationRequest struct {
	// Identity of the CHRUP scheme.
	Identity

	// Epoch is the epoch of the handoff for which the node would like
	// to register.
	Epoch beacon.EpochTime `json:"epoch"`

	// Checksum is the hash of the verification matrix.
	Checksum hash.Hash `json:"checksum"`
}

ApplicationRequest contains node's application to form a new committee.

type Backend 

type Backend interface {
	// ConsensusParameters returns the CHURP consensus parameters.
	ConsensusParameters(context.Context, int64) (*ConsensusParameters, error)

	// Status returns the CHURP status for the specified runtime and CHURP
	// scheme.
	Status(context.Context, *StatusQuery) (*Status, error)

	// Statuses returns the CHURP statuses for the specified runtime.
	Statuses(context.Context, *registry.NamespaceQuery) ([]*Status, error)

	// AllStatuses returns the CHURP statuses for all runtimes.
	AllStatuses(context.Context, int64) ([]*Status, error)

	// WatchStatuses returns a channel that produces a stream of messages
	// containing CHURP statuses as they change over time.
	//
	// Upon subscription the current statuses are sent immediately.
	WatchStatuses() (<-chan *Status, *pubsub.Subscription)

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(context.Context, int64) (*Genesis, error)
}

Backend is a CHURP management implementation.

type Client 

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

Client is a gRPC keymanager secrets client.

func NewClient 

func NewClient(c *grpc.ClientConn) *Client

NewClient creates a new gRPC keymanager CHURP client service.

func (*Client) AllStatuses 

func (c *Client) AllStatuses(ctx context.Context, height int64) ([]*Status, error)

func (*Client) ConsensusParameters 

func (c *Client) ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)

func (*Client) Status 

func (c *Client) Status(ctx context.Context, query *StatusQuery) (*Status, error)

func (*Client) Statuses 

func (c *Client) Statuses(ctx context.Context, query *registry.NamespaceQuery) (*Status, error)

func (*Client) WatchStatuses 

func (c *Client) WatchStatuses(ctx context.Context) (<-chan *Status, pubsub.ClosableSubscription, error)

type ConfirmationRequest 

type ConfirmationRequest struct {
	Identity

	// Epoch is the epoch of the handoff for which the node reconstructed
	// the share.
	Epoch beacon.EpochTime `json:"epoch"`

	// Checksum is the hash of the verification matrix.
	Checksum hash.Hash `json:"checksum"`
}

ConfirmationRequest confirms that the node successfully completed the handoff.

type ConsensusParameters 

type ConsensusParameters struct {
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`
}

ConsensusParameters are the key manager CHURP consensus parameters.

type CreateEvent 

type CreateEvent struct {
	Status *Status
}

CreateEvent is the key manager CHURP create event.

func (*CreateEvent) EventKind 

func (ev *CreateEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type CreateRequest 

type CreateRequest struct {
	Identity

	// SuiteID is the identifier of a cipher suite used for verifiable secret
	// sharing and key derivation.
	SuiteID uint8 `json:"suite_id,omitempty"`

	// Threshold is the minimum number of distinct shares required
	// to reconstruct a key.
	Threshold uint8 `json:"threshold,omitempty"`

	// ExtraShares represents the minimum number of shares that can be lost
	// to render the secret unrecoverable.
	ExtraShares uint8 `json:"extra_shares,omitempty"`

	// HandoffInterval is the time interval in epochs between handoffs.
	//
	// A zero value disables handoffs.
	HandoffInterval beacon.EpochTime `json:"handoff_interval,omitempty"`

	// Policy is a signed SGX access control policy.
	Policy SignedPolicySGX `json:"policy,omitempty"`
}

CreateRequest contains the initial configuration.

func (*CreateRequest) ValidateBasic 

func (c *CreateRequest) ValidateBasic() error

ValidateBasic performs basic config validity checks.

type FetchRequest 

type FetchRequest struct {
	Identity

	// Epoch is the epoch of the handoff.
	Epoch beacon.EpochTime `json:"epoch,omitempty"`

	// NodeIDs contains the public keys of nodes from which to fetch data.
	NodeIDs []signature.PublicKey `json:"node_ids"`
}

FetchRequest is a fetch handoff data request.

type FetchResponse 

type FetchResponse struct {
	// Completed indicates whether the data fetching was completed.
	Completed bool `json:"completed,omitempty"`

	// Succeeded contains the public keys of nodes from which data was
	// successfully fetched.
	Succeeded []signature.PublicKey `json:"succeeded,omitempty"`

	// Failed contains the public keys of nodes from which data failed
	// to be fetched.
	Failed []signature.PublicKey `json:"failed,omitempty"`
}

FetchResponse is a fetch handoff data response.

type Genesis added in v0.2403.0 

type Genesis struct {
	// Parameters are the consensus parameters for CHURP.
	Parameters ConsensusParameters `json:"params"`

	// Statuses are the statuses of CHURP instances.
	Statuses []*Status `json:"statuses,omitempty"`
}

Genesis is the key manager management genesis state for CHURP.

type HandoffKind 

type HandoffKind int

HandoffKind represents the kind of a handoff. 

const (
	// HandoffKindDealingPhase represents the initial setup phase.
	HandoffKindDealingPhase HandoffKind = iota
	// HandoffKindCommitteeUnchanged represents a handoff where the committee
	// doesn't change.
	HandoffKindCommitteeUnchanged
	// HandoffKindCommitteeChanged represents a handoff where the committee
	// changes.
	HandoffKindCommitteeChanged
)

func (HandoffKind) String 

func (h HandoffKind) String() string

String returns the string representation of the HandoffKind.

type HandoffRequest 

type HandoffRequest struct {
	Identity

	// Epoch is the epoch of the handoff.
	Epoch beacon.EpochTime `json:"epoch,omitempty"`
}

HandoffRequest represents a handoff request.

type Identity 

type Identity struct {
	// ID is a unique CHURP identifier within the key manager runtime.
	ID uint8 `json:"id"`

	// RuntimeID is the identifier of the key manager runtime.
	RuntimeID common.Namespace `json:"runtime_id"`
}

Identity uniquely identifies a CHURP instance.

type PolicySGX 

type PolicySGX struct {
	Identity

	// Serial is the monotonically increasing policy serial number.
	Serial uint32 `json:"serial"`

	// MayShare is the vector of enclave identities from which a share can be
	// obtained during handoffs.
	MayShare []sgx.EnclaveIdentity `json:"may_share"`

	// MayJoin is the vector of enclave identities that may form the new
	// committee in the next handoffs.
	MayJoin []sgx.EnclaveIdentity `json:"may_join"`

	// MayQuery is the map of runtime identities to the vector of enclave
	// identities that may query key shares.
	MayQuery map[common.Namespace][]sgx.EnclaveIdentity `json:"may_query,omitempty"`
}

PolicySGX represents an SGX access control policy used to authenticate key manager enclaves during handoffs and remote client enclaves when querying key shares.

func (*PolicySGX) SanityCheck 

func (p *PolicySGX) SanityCheck(prev *PolicySGX) error

SanityCheck verifies the validity of the policy.

type SignedApplicationRequest 

type SignedApplicationRequest struct {
	Application ApplicationRequest `json:"application"`

	// Signature is the RAK signature of the application request.
	Signature signature.RawSignature `json:"signature"`
}

SignedApplicationRequest is an application request signed by the key manager enclave using its runtime attestation key (RAK).

func (*SignedApplicationRequest) VerifyRAK 

func (r *SignedApplicationRequest) VerifyRAK(rak *signature.PublicKey) error

VerifyRAK verifies the runtime attestation key (RAK) signature.

type SignedConfirmationRequest 

type SignedConfirmationRequest struct {
	Confirmation ConfirmationRequest `json:"confirmation"`

	// Signature is the RAK signature of the confirmation request.
	Signature signature.RawSignature `json:"signature"`
}

SignedConfirmationRequest is a confirmation request signed by the key manager enclave using its runtime attestation key (RAK).

func (*SignedConfirmationRequest) VerifyRAK 

func (r *SignedConfirmationRequest) VerifyRAK(rak *signature.PublicKey) error

VerifyRAK verifies the runtime attestation key (RAK) signature.

type SignedPolicySGX 

type SignedPolicySGX struct {
	// Policy is an SGX access control policy.
	Policy PolicySGX `json:"policy"`

	// Signatures is a vector of signatures.
	Signatures []signature.Signature `json:"signatures,omitempty"`
}

SignedPolicySGX represents a signed SGX access control policy.

The runtime extension will accept the policy only if all signatures are valid, and a sufficient number of trusted policy signers have signed it.

func (*SignedPolicySGX) SanityCheck 

func (p *SignedPolicySGX) SanityCheck(prev *PolicySGX) error

SanityCheck verifies the validity of the policy and the signatures.

func (*SignedPolicySGX) Sign 

func (p *SignedPolicySGX) Sign(signers []signature.Signer) error

Sign signs the policy with the given signer and appends the signatures.

type Status 

type Status struct {
	Identity

	// SuiteID is the identifier of a cipher suite used for verifiable secret
	// sharing and key derivation.
	SuiteID uint8 `json:"suite_id"`

	// Threshold represents the degree of the secret-sharing polynomial.
	//
	// In a (t,n) secret-sharing scheme, where t represents the threshold,
	// any combination of t+1 or more shares can reconstruct the secret,
	// while losing n-t or fewer shares still allows the secret to be
	// recovered.
	Threshold uint8 `json:"threshold"`

	// ExtraShares represents the minimum number of shares that can be lost
	// to render the secret unrecoverable.
	//
	// If t and e represent the threshold and extra shares, respectively,
	// then the minimum size of the committee is t+e+1.
	ExtraShares uint8 `json:"extra_shares"`

	// HandoffInterval is the time interval in epochs between handoffs.
	//
	// A zero value disables handoffs.
	HandoffInterval beacon.EpochTime `json:"handoff_interval"`

	// Policy is a signed SGX access control policy.
	Policy SignedPolicySGX `json:"policy"`

	// Handoff is the epoch of the last successfully completed handoff.
	//
	// The zero value indicates that no handoffs have been completed so far.
	// Note that the first handoff is special and is called the dealer phase,
	// in which nodes do not reshare or randomize shares but instead construct
	// the secret and shares.
	Handoff beacon.EpochTime `json:"handoff"`

	// The hash of the verification matrix from the last successfully completed
	// handoff.
	Checksum *hash.Hash `json:"checksum,omitempty"`

	// Committee is a vector of nodes holding a share of the secret
	// in the active handoff.
	//
	// A client needs to obtain more than a threshold number of key shares
	// from the nodes in this vector to construct the key.
	Committee []signature.PublicKey `json:"committee,omitempty"`

	// NextHandoff defines the epoch in which the next handoff will occur.
	//
	// If an insufficient number of applications is received, the next handoff
	// will be delayed by one epoch.
	NextHandoff beacon.EpochTime `json:"next_handoff"`

	// NextChecksum is the hash of the verification matrix from the current
	// handoff.
	//
	// The first candidate to confirm share reconstruction is the source
	// of truth for the checksum. All other candidates need to confirm
	// with the same checksum; otherwise, the applications will be annulled,
	// and the nodes will need to apply for the new committee again.
	NextChecksum *hash.Hash `json:"next_checksum,omitempty"`

	// Applications is a map of nodes that wish to form the new committee.
	//
	// Candidates are expected to generate a random bivariate polynomial,
	// construct a verification matrix, compute its checksum, and submit
	// an application one epoch in advance of the next scheduled handoff.
	// Subsequently, upon the arrival of the handoff epoch, nodes must execute
	// the handoff protocol and confirm the reconstruction of its share.
	Applications map[signature.PublicKey]Application `json:"applications,omitempty"`
}

Status represents the current state of a CHURP instance.

func (*Status) HandoffKind 

func (s *Status) HandoffKind() HandoffKind

HandoffKind returns the type of the next handoff depending on which nodes submitted an application to form the next committee.

func (*Status) HandoffsDisabled 

func (s *Status) HandoffsDisabled() bool

HandoffsDisabled returns true iff handoffs are disabled, i.e., when the handoff interval is set to zero.

func (*Status) MinApplicants 

func (s *Status) MinApplicants() int

MinApplicants returns the minimum number of nodes that must participate in a handoff.

func (*Status) MinCommitteeSize 

func (s *Status) MinCommitteeSize() int

MinCommitteeSize returns the minimum number of nodes in the committee.

type StatusQuery 

type StatusQuery struct {
	Height    int64            `json:"height"`
	RuntimeID common.Namespace `json:"runtime_id"`
	ChurpID   uint8            `json:"churp_id"`
}

StatusQuery is a status query by CHURP and runtime ID.

type UpdateEvent 

type UpdateEvent struct {
	Status *Status
}

UpdateEvent is the key manager CHURP update event.

func (*UpdateEvent) EventKind 

func (ev *UpdateEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type UpdateRequest 

type UpdateRequest struct {
	Identity

	// ExtraShares represents the minimum number of shares that can be lost
	// to render the secret unrecoverable.
	ExtraShares *uint8 `json:"extra_shares,omitempty"`

	// HandoffInterval is the time interval in epochs between handoffs.
	//
	// Zero value disables handoffs.
	HandoffInterval *beacon.EpochTime `json:"handoff_interval,omitempty"`

	// Policy is a signed SGX access control policy.
	Policy *SignedPolicySGX `json:"policy,omitempty"`
}

UpdateRequest contains the updated configuration.

func (*UpdateRequest) ValidateBasic 

func (c *UpdateRequest) ValidateBasic() error

ValidateBasic performs basic config validity checks.

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.