api

package
v0.2300.1 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2023 License: Apache-2.0 Imports: 19 Imported by: 2

Documentation

Overview

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

Index

Constants

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

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

	// KeyPairIDSize is the size of a key pair ID in bytes.
	KeyPairIDSize = 32
)
View Source 
const (
	// GasOpUpdatePolicy is the gas operation identifier for policy updates
	// costs.
	GasOpUpdatePolicy transaction.Op = "update_policy"
	// GasOpPublishMasterSecret is the gas operation identifier for publishing
	// key manager master secret.
	GasOpPublishMasterSecret transaction.Op = "publish_master_secret"
	// GasOpPublishEphemeralSecret is the gas operation identifier for publishing
	// key manager ephemeral secret.
	GasOpPublishEphemeralSecret transaction.Op = "publish_ephemeral_secret"
)

Variables

View Source 
var (
	// ErrInvalidArgument is the error returned on malformed arguments.
	ErrInvalidArgument = errors.New(ModuleName, 1, "keymanager: invalid argument")

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

	// ErrNoSuchMasterSecret is the error returned when a key manager master secret does not exist.
	ErrNoSuchMasterSecret = errors.New(ModuleName, 3, "keymanager: no such master secret")

	// ErrNoSuchEphemeralSecret is the error returned when a key manager ephemeral secret
	// does not exist.
	ErrNoSuchEphemeralSecret = errors.New(ModuleName, 4, "keymanager: no such ephemeral secret")

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

	// MethodPublishMasterSecret is the method name for publishing master secret.
	MethodPublishMasterSecret = transaction.NewMethodName(ModuleName, "PublishMasterSecret", SignedEncryptedMasterSecret{})

	// MethodPublishEphemeralSecret is the method name for publishing ephemeral secret.
	MethodPublishEphemeralSecret = transaction.NewMethodName(ModuleName, "PublishEphemeralSecret", SignedEncryptedEphemeralSecret{})

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

	// InsecureREK is the insecure hardcoded key manager public key, used
	// in insecure builds when a REK is unavailable.
	InsecureREK x25519.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,
		MethodPublishMasterSecret,
		MethodPublishEphemeralSecret,
	}

	// RPCMethodInit is the name of the `init` method.
	RPCMethodInit = "init"

	// RPCMethodGetPublicKey is the name of the `get_public_key` method.
	RPCMethodGetPublicKey = "get_public_key"

	// RPCMethodGetPublicEphemeralKey is the name of the `get_public_ephemeral_key` method.
	RPCMethodGetPublicEphemeralKey = "get_public_ephemeral_key" // #nosec G101

	// RPCMethodGenerateMasterSecret is the name of the `generate_master_secret` RPC method.
	RPCMethodGenerateMasterSecret = "generate_master_secret"

	// RPCMethodGenerateEphemeralSecret is the name of the `generate_ephemeral_secret` RPC method.
	RPCMethodGenerateEphemeralSecret = "generate_ephemeral_secret"

	// RPCMethodLoadMasterSecret is the name of the `load_master_secret` RPC method.
	RPCMethodLoadMasterSecret = "load_master_secret"

	// RPCMethodLoadEphemeralSecret is the name of the `load_ephemeral_secret` RPC method.
	RPCMethodLoadEphemeralSecret = "load_ephemeral_secret"
)
View Source 
var DefaultGasCosts = transaction.Costs{
	GasOpUpdatePolicy:           1000,
	GasOpPublishMasterSecret:    1000,
	GasOpPublishEphemeralSecret: 1000,
}

DefaultGasCosts are the "default" gas costs for operations.

View Source 
var EncryptedEphemeralSecretSignatureContext = signature.NewContext("oasis-core/keymanager: encrypted ephemeral secret")

EncryptedEphemeralSecretSignatureContext is the context used to sign encrypted key manager ephemeral secrets.

View Source 
var EncryptedMasterSecretSignatureContext = signature.NewContext("oasis-core/keymanager: encrypted master secret")

EncryptedMasterSecretSignatureContext is the context used to sign encrypted key manager master secrets.

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

PolicySGXSignatureContext is the context used to sign PolicySGX documents.

Functions

func NewPublishEphemeralSecretTx added in v0.2300.0 

func NewPublishEphemeralSecretTx(nonce uint64, fee *transaction.Fee, sigSec *SignedEncryptedEphemeralSecret) *transaction.Transaction

NewPublishEphemeralSecretTx creates a new publish ephemeral secret transaction.

func NewPublishMasterSecretTx added in v0.2300.0 

func NewPublishMasterSecretTx(nonce uint64, fee *transaction.Fee, sigSec *SignedEncryptedMasterSecret) *transaction.Transaction

NewPublishMasterSecretTx creates a new publish master secret transaction.

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)

	// GetMasterSecret returns the key manager master secret.
	GetMasterSecret(context.Context, *registry.NamespaceQuery) (*SignedEncryptedMasterSecret, error)

	// WatchMasterSecrets returns a channel that produces a stream of master secrets.
	WatchMasterSecrets() (<-chan *SignedEncryptedMasterSecret, *pubsub.Subscription)

	// GetEphemeralSecret returns the key manager ephemeral secret.
	GetEphemeralSecret(context.Context, *registry.NamespaceQuery) (*SignedEncryptedEphemeralSecret, error)

	// WatchEphemeralSecrets returns a channel that produces a stream of ephemeral secrets.
	WatchEphemeralSecrets() (<-chan *SignedEncryptedEphemeralSecret, *pubsub.Subscription)
}

Backend is a key manager management implementation.

type ConsensusParameterChanges added in v0.2300.0 

type ConsensusParameterChanges struct {
	// GasCosts are the new gas costs.
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`
}

ConsensusParameterChanges are allowed key manager consensus parameter changes.

func (*ConsensusParameterChanges) Apply added in v0.2300.0 

func (c *ConsensusParameterChanges) Apply(params *ConsensusParameters) error

Apply applies changes to the given consensus parameters.

func (*ConsensusParameterChanges) SanityCheck added in v0.2300.0 

func (c *ConsensusParameterChanges) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameter changes.

type ConsensusParameters added in v0.2300.0 

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

ConsensusParameters are the key manager consensus parameters.

func (*ConsensusParameters) SanityCheck added in v0.2300.0 

func (p *ConsensusParameters) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameters.

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

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

	// Epoch is the epoch to which the secret belongs.
	Epoch beacon.EpochTime `json:"epoch"`

	// Secret is the encrypted secret.
	Secret EncryptedSecret `json:"secret"`
}

EncryptedEphemeralSecret is an encrypted ephemeral secret.

func (*EncryptedEphemeralSecret) SanityCheck added in v0.2300.0 

func (s *EncryptedEphemeralSecret) SanityCheck(epoch beacon.EpochTime, reks map[x25519.PublicKey]struct{}) error

SanityCheck performs a sanity check on the ephemeral secret.

type EncryptedMasterSecret added in v0.2300.0 

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

	// Generation is the generation of the secret.
	Generation uint64 `json:"generation"`

	// Epoch is the epoch in which the secret was created.
	Epoch beacon.EpochTime `json:"epoch"`

	// Secret is the encrypted secret.
	Secret EncryptedSecret `json:"secret"`
}

EncryptedMasterSecret is an encrypted master secret.

func (*EncryptedMasterSecret) SanityCheck added in v0.2300.0 

func (s *EncryptedMasterSecret) SanityCheck(generation uint64, epoch beacon.EpochTime, reks map[x25519.PublicKey]struct{}) error

SanityCheck performs a sanity check on the master secret.

type EncryptedSecret added in v0.2300.0 

type EncryptedSecret struct {
	// Checksum is the secret verification checksum.
	Checksum []byte `json:"checksum"`

	// PubKey is the public key used to derive the symmetric key for decryption.
	PubKey x25519.PublicKey `json:"pub_key"`

	// Ciphertexts is the map of REK encrypted secrets.
	Ciphertexts map[x25519.PublicKey][]byte `json:"ciphertexts"`
}

EncryptedSecret is a secret encrypted with Deoxys-II MRAE algorithm.

func (*EncryptedSecret) SanityCheck added in v0.2300.0 

func (s *EncryptedSecret) SanityCheck(reks map[x25519.PublicKey]struct{}) error

SanityCheck performs a sanity check on the encrypted secret.

type EphemeralKeyRequest added in v0.2300.0 

type EphemeralKeyRequest struct {
	Height    *uint64          `json:"height"`
	ID        common.Namespace `json:"runtime_id"`
	KeyPairID KeyPairID        `json:"key_pair_id"`
	Epoch     beacon.EpochTime `json:"epoch"`
}

EphemeralKeyRequest is the ephemeral key RPC request, sent to the key manager enclave.

type EphemeralSecretPublishedEvent added in v0.2300.0 

type EphemeralSecretPublishedEvent struct {
	Secret *SignedEncryptedEphemeralSecret
}

EphemeralSecretPublishedEvent is the key manager ephemeral secret published event.

func (*EphemeralSecretPublishedEvent) EventKind added in v0.2300.0 

func (ev *EphemeralSecretPublishedEvent) EventKind() string

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

type GenerateEphemeralSecretRequest added in v0.2300.0 

type GenerateEphemeralSecretRequest struct {
	Epoch beacon.EpochTime `json:"epoch"`
}

GenerateEphemeralSecretRequest is the generate ephemeral secret RPC request, sent to the key manager enclave.

type GenerateEphemeralSecretResponse added in v0.2300.0 

type GenerateEphemeralSecretResponse struct {
	SignedSecret SignedEncryptedEphemeralSecret `json:"signed_secret"`
}

GenerateEphemeralSecretResponse is the RPC response, returned as part of a GenerateEphemeralSecretRequest from the key manager enclave.

type GenerateMasterSecretRequest added in v0.2300.0 

type GenerateMasterSecretRequest struct {
	Generation uint64           `json:"generation"`
	Epoch      beacon.EpochTime `json:"epoch"`
}

GenerateMasterSecretRequest is the generate master secret RPC request, sent to the key manager enclave.

type GenerateMasterSecretResponse added in v0.2300.0 

type GenerateMasterSecretResponse struct {
	SignedSecret SignedEncryptedMasterSecret `json:"signed_secret"`
}

GenerateMasterSecretResponse is the RPC response, returned as part of a GenerateMasterSecretRequest from the key manager enclave.

type Genesis 

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

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

type InitRequest struct {
	Status      *Status `json:"status,omitempty"`       // TODO: Change in PR-5205.
	Checksum    []byte  `json:"checksum,omitempty"`     // TODO: Remove in PR-5205.
	Policy      []byte  `json:"policy,omitempty"`       // TODO: Remove in PR-5205.
	MayGenerate bool    `json:"may_generate,omitempty"` // TODO: Remove in PR-5205.
}

InitRequest is the initialization RPC request, sent to the key manager enclave.

type InitResponse 

type InitResponse struct {
	IsSecure       bool                 `json:"is_secure"`
	Checksum       []byte               `json:"checksum"`
	NextChecksum   []byte               `json:"next_checksum,omitempty"`
	PolicyChecksum []byte               `json:"policy_checksum"`
	RSK            *signature.PublicKey `json:"rsk,omitempty"`
	NextRSK        *signature.PublicKey `json:"next_rsk,omitempty"`
}

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

type KeyPairID [KeyPairIDSize]byte

KeyPairID is a 256-bit key pair identifier.

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

func (c *KeymanagerClient) GetEphemeralSecret(ctx context.Context, query *registry.NamespaceQuery) (*SignedEncryptedEphemeralSecret, error)

func (*KeymanagerClient) GetMasterSecret added in v0.2300.0 

func (c *KeymanagerClient) GetMasterSecret(ctx context.Context, query *registry.NamespaceQuery) (*SignedEncryptedMasterSecret, error)

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)

func (*KeymanagerClient) WatchEphemeralSecrets added in v0.2300.0 

func (c *KeymanagerClient) WatchEphemeralSecrets(ctx context.Context) (<-chan *SignedEncryptedEphemeralSecret, pubsub.ClosableSubscription, error)

func (*KeymanagerClient) WatchMasterSecrets added in v0.2300.0 

func (c *KeymanagerClient) WatchMasterSecrets(ctx context.Context) (<-chan *SignedEncryptedMasterSecret, pubsub.ClosableSubscription, error)

func (*KeymanagerClient) WatchStatuses added in v0.2300.0 

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

type LoadEphemeralSecretRequest added in v0.2300.0 

type LoadEphemeralSecretRequest struct {
	SignedSecret SignedEncryptedEphemeralSecret `json:"signed_secret"`
}

LoadEphemeralSecretRequest is the load ephemeral secret RPC request, sent to the key manager enclave.

type LoadMasterSecretRequest added in v0.2300.0 

type LoadMasterSecretRequest struct {
	SignedSecret SignedEncryptedMasterSecret `json:"signed_secret"`
}

LoadMasterSecretRequest is the load master secret RPC request, sent to the key manager enclave.

type LongTermKeyRequest added in v0.2300.0 

type LongTermKeyRequest struct {
	Height     *uint64          `json:"height"`
	ID         common.Namespace `json:"runtime_id"`
	KeyPairID  KeyPairID        `json:"key_pair_id"`
	Generation uint64           `json:"generation"`
}

LongTermKeyRequest is the long-term key RPC request, sent to the key manager enclave.

type MasterSecretPublishedEvent added in v0.2300.0 

type MasterSecretPublishedEvent struct {
	Secret *SignedEncryptedMasterSecret
}

MasterSecretPublishedEvent is the key manager master secret published event.

func (*MasterSecretPublishedEvent) EventKind added in v0.2300.0 

func (ev *MasterSecretPublishedEvent) EventKind() string

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

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

	// MasterSecretRotationInterval is the time interval in epochs between master secret rotations.
	// Zero disables rotations.
	MasterSecretRotationInterval beacon.EpochTime `json:"master_secret_rotation_interval,omitempty"`

	// MaxEphemeralSecretAge is the maximum age of an ephemeral secret in the number of epochs.
	MaxEphemeralSecretAge beacon.EpochTime `json:"max_ephemeral_secret_age,omitempty"`
}

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

type SignedEncryptedEphemeralSecret added in v0.2300.0 

type SignedEncryptedEphemeralSecret struct {
	// Secret is the encrypted ephemeral secret.
	Secret EncryptedEphemeralSecret `json:"secret"`

	// Signature is a signature of the ephemeral secret.
	Signature signature.RawSignature `json:"signature"`
}

SignedEncryptedEphemeralSecret is a RAK signed encrypted ephemeral secret.

func (*SignedEncryptedEphemeralSecret) Verify added in v0.2300.0 

func (s *SignedEncryptedEphemeralSecret) Verify(epoch beacon.EpochTime, reks map[x25519.PublicKey]struct{}, rak *signature.PublicKey) error

Verify sanity checks the encrypted ephemeral secret and verifies its signature.

type SignedEncryptedMasterSecret added in v0.2300.0 

type SignedEncryptedMasterSecret struct {
	// Secret is the encrypted master secret.
	Secret EncryptedMasterSecret `json:"secret"`

	// Signature is a signature of the master secret.
	Signature signature.RawSignature `json:"signature"`
}

SignedEncryptedMasterSecret is a RAK signed encrypted master secret.

func (*SignedEncryptedMasterSecret) Verify added in v0.2300.0 

func (s *SignedEncryptedMasterSecret) Verify(generation uint64, epoch beacon.EpochTime, reks map[x25519.PublicKey]struct{}, rak *signature.PublicKey) error

Verify sanity checks the encrypted master secret and verifies its signature.

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

func SignInitResponse(signer signature.Signer, response *InitResponse) (*SignedInitResponse, error)

SignInitResponse signs the given init response.

func (*SignedInitResponse) Verify 

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

Verify verifies the signature of the init response using the given key.

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

type SignedPublicKey struct {
	Key        x25519.PublicKey       `json:"key"`
	Checksum   []byte                 `json:"checksum"`
	Signature  signature.RawSignature `json:"signature"`
	Expiration *beacon.EpochTime      `json:"expiration,omitempty"`
}

SignedPublicKey is the RPC response, returned as part of an EphemeralKeyRequest from the key manager enclave.

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

	// Generation is the generation of the latest master secret.
	Generation uint64 `json:"generation,omitempty"`

	// RotationEpoch is the epoch of the last master secret rotation.
	RotationEpoch beacon.EpochTime `json:"rotation_epoch,omitempty"`

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

	// RSK is the runtime signing key of the key manager.
	RSK *signature.PublicKey `json:"rsk,omitempty"`
}

Status is the current key manager status.

func (*Status) NextGeneration added in v0.2300.0 

func (s *Status) NextGeneration() uint64

NextGeneration returns the generation of the next master secret.

func (*Status) VerifyRotationEpoch added in v0.2300.0 

func (s *Status) VerifyRotationEpoch(epoch beacon.EpochTime) error

VerifyRotationEpoch verifies if rotation can be performed in the given epoch.

type StatusUpdateEvent added in v0.2200.0 

type StatusUpdateEvent struct {
	Statuses []*Status
}

StatusUpdateEvent is the keymanager status update event.

func (*StatusUpdateEvent) EventKind added in v0.2200.0 

func (ev *StatusUpdateEvent) EventKind() string

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

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.