api

Documentation

Overview

Package api implements the key manager management API and common data types.

Index

• Constants
• Variables
• func NewUpdatePolicyTx(nonce uint64, fee *transaction.Fee, sigPol *SignedPolicySGX) *transaction.Transaction
• func RegisterService(server *grpc.Server, service Backend)
• func SanityCheckSignedPolicySGX(currentSigPol, newSigPol *SignedPolicySGX) error
• func SanityCheckStatuses(statuses []*Status) error
• type Backend
• type EnclavePolicySGX
• type Genesis
  • func (g *Genesis) SanityCheck() error
• type InitResponse
  • func VerifyExtraInfo(logger *logging.Logger, nodeID signature.PublicKey, rt *registry.Runtime, ...) (*InitResponse, error)
• type KeymanagerClient
  • func NewKeymanagerClient(c *grpc.ClientConn) *KeymanagerClient
  • func (c *KeymanagerClient) GetStatus(ctx context.Context, query *registry.NamespaceQuery) (*Status, error)
  • func (c *KeymanagerClient) GetStatuses(ctx context.Context, height int64) ([]*Status, error)
• type PolicySGX
• type SignedInitResponse
  • func (r *SignedInitResponse) Verify(pk signature.PublicKey) error
• type SignedPolicySGX
• type Status
• type StatusUpdateEvent
  • func (ev *StatusUpdateEvent) EventKind() string

Constants

const (
	// ModuleName is a unique module name for the keymanager module.
	ModuleName = "keymanager"

	// ChecksumSize is the length of checksum in bytes.
	ChecksumSize = 32
)

Variables

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

	// MethodUpdatePolicy is the method name for policy updates.
	MethodUpdatePolicy = transaction.NewMethodName(ModuleName, "UpdatePolicy", SignedPolicySGX{})

	// TestPublicKey is the insecure hardcoded key manager public key, used
	// in insecure builds when a RAK is unavailable.
	TestPublicKey signature.PublicKey

	// TestSigners contains a list of signers with corresponding test keys, used
	// in insecure builds when a RAK is unavailable.
	TestSigners []signature.Signer

	// Methods is the list of all methods supported by the key manager backend.
	Methods = []transaction.MethodName{
		MethodUpdatePolicy,
	}
)

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

PolicySGXSignatureContext is the context used to sign PolicySGX documents.

Functions

func NewUpdatePolicyTx

func NewUpdatePolicyTx(nonce uint64, fee *transaction.Fee, sigPol *SignedPolicySGX) *transaction.Transaction

NewUpdatePolicyTx creates a new policy update transaction.

func RegisterService

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

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

func SanityCheckSignedPolicySGX

func SanityCheckSignedPolicySGX(currentSigPol, newSigPol *SignedPolicySGX) error

SanityCheckSignedPolicySGX verifies a SignedPolicySGX.

func SanityCheckStatuses

func SanityCheckStatuses(statuses []*Status) error

SanityCheckStatuses examines the statuses table.

Types

type Backend

type Backend interface {
	// GetStatus returns a key manager status by key manager ID.
	GetStatus(context.Context, *registry.NamespaceQuery) (*Status, error)

	// GetStatuses returns all currently tracked key manager statuses.
	GetStatuses(context.Context, int64) ([]*Status, error)

	// WatchStatuses returns a channel that produces a stream of messages
	// containing the key manager statuses as it changes over time.
	//
	// Upon subscription the current status is 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 key manager management implementation.

type EnclavePolicySGX

type EnclavePolicySGX struct {
	// MayQuery is the map of runtime IDs to the vector of enclave IDs that
	// may query private key material.
	//
	// TODO: This could be made more sophisticated and seggregate based on
	// contract ID as well, but for now punt on the added complexity.
	MayQuery map[common.Namespace][]sgx.EnclaveIdentity `json:"may_query"`

	// MayReplicate is the vector of enclave IDs that may retrieve the master
	// secret (Note: Each enclave ID may always implicitly replicate from other
	// instances of itself).
	MayReplicate []sgx.EnclaveIdentity `json:"may_replicate"`
}

EnclavePolicySGX is the per-SGX key manager enclave ID access control policy.

type Genesis

type Genesis struct {
	Statuses []*Status `json:"statuses,omitempty"`
}

Genesis is the key manager management genesis state.

func (*Genesis) SanityCheck

func (g *Genesis) SanityCheck() error

SanityCheck does basic sanity checking on the genesis state.

type InitResponse

type InitResponse struct {
	IsSecure       bool   `json:"is_secure"`
	Checksum       []byte `json:"checksum"`
	PolicyChecksum []byte `json:"policy_checksum"`
}

InitResponse is the initialization RPC response, returned as part of a SignedInitResponse from the key manager enclave.

func VerifyExtraInfo

func VerifyExtraInfo(
	logger *logging.Logger,
	nodeID signature.PublicKey,
	rt *registry.Runtime,
	nodeRt *node.Runtime,
	ts time.Time,
	height uint64,
	params *registry.ConsensusParameters,
) (*InitResponse, error)

VerifyExtraInfo verifies and parses the per-node + per-runtime ExtraInfo blob for a key manager.

type KeymanagerClient

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

KeymanagerClient is a gRPC keymanager client.

func NewKeymanagerClient

func NewKeymanagerClient(c *grpc.ClientConn) *KeymanagerClient

NewKeymanagerClient creates a new gRPC keymanager client service.

func (*KeymanagerClient) GetStatus

func (c *KeymanagerClient) GetStatus(ctx context.Context, query *registry.NamespaceQuery) (*Status, error)

func (*KeymanagerClient) GetStatuses

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

type PolicySGX

type PolicySGX struct {
	// Serial is the monotonically increasing policy serial number.
	Serial uint32 `json:"serial"`

	// ID is the runtime ID that this policy is valid for.
	ID common.Namespace `json:"id"`

	// Enclaves is the per-key manager enclave ID access control policy.
	Enclaves map[sgx.EnclaveIdentity]*EnclavePolicySGX `json:"enclaves"`
}

PolicySGX is a key manager access control policy for the replicated SGX key manager.

type SignedInitResponse

type SignedInitResponse struct {
	InitResponse InitResponse `json:"init_response"`
	Signature    []byte       `json:"signature"`
}

SignedInitResponse is the signed initialization RPC response, returned from the key manager enclave.

func (*SignedInitResponse) Verify

func (r *SignedInitResponse) Verify(pk signature.PublicKey) error

type SignedPolicySGX

type SignedPolicySGX struct {
	Policy PolicySGX `json:"policy"`

	Signatures []signature.Signature `json:"signatures"`
}

SignedPolicySGX is a signed SGX key manager access control policy.

type Status

type Status struct {
	// ID is the runtime ID of the key manager.
	ID common.Namespace `json:"id"`

	// IsInitialized is true iff the key manager is done initializing.
	IsInitialized bool `json:"is_initialized"`

	// IsSecure is true iff the key manager is secure.
	IsSecure bool `json:"is_secure"`

	// Checksum is the key manager master secret verification checksum.
	Checksum []byte `json:"checksum"`

	// Nodes is the list of currently active key manager node IDs.
	Nodes []signature.PublicKey `json:"nodes"`

	// Policy is the key manager policy.
	Policy *SignedPolicySGX `json:"policy"`
}

Status is the current key manager status.

type StatusUpdateEvent

type StatusUpdateEvent struct {
	Statuses []*Status
}

StatusUpdateEvent is the keymanager status update event.

func (*StatusUpdateEvent) EventKind

func (ev *StatusUpdateEvent) EventKind() string

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