secrets

package
v0.2400.0 Latest Latest
Warning

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

 Go to latest Published: May 13, 2024 License: Apache-2.0 Imports: 14 Imported by: 1

Documentation

Overview

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

Index

Constants

View Source 
const (

	// 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{})

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

	// RPCMethodGetOrCreateKeys is the name of the `get_or_create_keys` method.
	RPCMethodGetOrCreateKeys = "get_or_create_keys"

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

	// RPCMethodGetOrCreateEphemeralKeys is the name of the `get_or_create_ephemeral_keys` method.
	RPCMethodGetOrCreateEphemeralKeys = "get_or_create_ephemeral_keys"

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

	// RPCMethodReplicateMasterSecret is the name of the `replicate_master_secret` method.
	RPCMethodReplicateMasterSecret = "replicate_master_secret"

	// RPCMethodReplicateEphemeralSecret is the name of the `replicate_ephemeral_secret` method.
	RPCMethodReplicateEphemeralSecret = "replicate_ephemeral_secret"

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

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

NewPublishEphemeralSecretTx creates a new publish ephemeral secret transaction.

func NewPublishMasterSecretTx 

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 secrets 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 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 secrets client service.

func (*Client) GetEphemeralSecret 

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

func (*Client) GetMasterSecret 

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

func (*Client) GetStatus 

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

func (*Client) GetStatuses 

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

func (*Client) WatchEphemeralSecrets 

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

func (*Client) WatchMasterSecrets 

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

func (*Client) WatchStatuses 

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

type ConsensusParameterChanges 

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 

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

Apply applies changes to the given consensus parameters.

func (*ConsensusParameterChanges) SanityCheck 

func (c *ConsensusParameterChanges) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameter changes.

type ConsensusParameters 

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

ConsensusParameters are the key manager consensus parameters.

func (*ConsensusParameters) SanityCheck 

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 

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 

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

SanityCheck performs a sanity check on the ephemeral secret.

type EncryptedMasterSecret 

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 

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 

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 

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

SanityCheck performs a sanity check on the encrypted secret.

type EphemeralKeyRequest 

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 

type EphemeralSecretPublishedEvent struct {
	Secret *SignedEncryptedEphemeralSecret
}

EphemeralSecretPublishedEvent is the key manager ephemeral secret published event.

func (*EphemeralSecretPublishedEvent) EventKind 

func (ev *EphemeralSecretPublishedEvent) EventKind() string

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

type GenerateEphemeralSecretRequest 

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

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

type GenerateEphemeralSecretResponse 

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 

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 

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 

type InitRequest struct {
	Status Status `json:"status,omitempty"`
}

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.

type KeyPairID 

type KeyPairID [KeyPairIDSize]byte

KeyPairID is a 256-bit key pair identifier.

type LoadEphemeralSecretRequest 

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

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

type LoadMasterSecretRequest 

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

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

type LongTermKeyRequest 

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 

type MasterSecretPublishedEvent struct {
	Secret *SignedEncryptedMasterSecret
}

MasterSecretPublishedEvent is the key manager master secret published event.

func (*MasterSecretPublishedEvent) EventKind 

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 

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 

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 

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 

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 

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 

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 

func (s *Status) NextGeneration() uint64

NextGeneration returns the generation of the next master secret.

func (*Status) VerifyRotationEpoch 

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

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

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.

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.