churp

Documentation

Index

• Constants
• type Application
• type ApplicationRequest
• type Client
• type ConfirmationRequest
• type ConsensusParameters
• type CreateEvent
• type CreateRequest
• type FetchRequest
• type FetchResponse
• type HandoffKind
  • func (h HandoffKind) String() string
• type HandoffRequest
• type Identity
• type PolicySGX
• type SignedApplicationRequest
• type SignedConfirmationRequest
• type SignedPolicySGX
• type Status
• type StatusQuery
• type UpdateEvent
• type UpdateRequest

Constants

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

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
)

const (
	// ModuleName is the module name for CHURP extension.
	ModuleName = "keymanager/churp"
)

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
)

const (
	// StakeClaimScheme is the stake claim template used for creating
	// new CHURP schemes.
	StakeClaimScheme = "keymanager.churp.Scheme.%s.%d"
)

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 Client

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

Client is a gRPC keymanager secrets client.

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.

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.

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 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 handouts.
	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"`
}

PolicySGX represents an SGX access control policy used to authenticate key manager enclaves during handoffs.

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).

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).

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.

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.

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.

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.