encryption

Documentation

Index

• Constants
• func AesGcmDecrypt(key []byte, ciphertext []byte, iv IvGCM) (plaintext []byte, err error)
• func CheckEncryptionMethodSupported(method encryptionpb.EncryptionMethod) error
• func DecryptRegion(region *metapb.Region, keyManager KeyManager) error
• func EncryptRegion(region *metapb.Region, keyManager KeyManager) (*metapb.Region, error)
• func KeyLength(method encryptionpb.EncryptionMethod) (int, error)
• func NewDataKey(method encryptionpb.EncryptionMethod, creationTime uint64) (keyID uint64, key *encryptionpb.DataKey, err error)
• type Config
  • func (c *Config) Adjust() error
  • func (c *Config) GetMasterKeyMeta() (*encryptionpb.MasterKey, error)
  • func (c *Config) GetMethod() (encryptionpb.EncryptionMethod, error)
• type IvCTR
  • func NewIvCTR() (IvCTR, error)
• type IvGCM
  • func AesGcmEncrypt(key []byte, plaintext []byte) (ciphertext []byte, iv IvGCM, err error)
  • func NewIvGCM() (IvGCM, error)
• type KeyManager
• type Manager
  • func NewManager(etcdClient *clientv3.Client, config *Config) (*Manager, error)
  • func (m *Manager) GetCurrentKey() (keyID uint64, key *encryptionpb.DataKey, err error)
  • func (m *Manager) GetKey(keyID uint64) (*encryptionpb.DataKey, error)
  • func (m *Manager) SetLeadership(leadership *election.Leadership) error
  • func (m *Manager) StartBackgroundLoop(ctx context.Context)
• type MasterKey
  • func NewCustomMasterKeyForTest(key []byte, ciphertextKey []byte) *MasterKey
  • func NewMasterKey(config *encryptionpb.MasterKey, ciphertextKey []byte) (*MasterKey, error)
  • func (k *MasterKey) CiphertextKey() []byte
  • func (k *MasterKey) Decrypt(ciphertext []byte, iv []byte) (plaintext []byte, err error)
  • func (k *MasterKey) Encrypt(plaintext []byte) (ciphertext []byte, iv []byte, err error)
  • func (k *MasterKey) IsPlaintext() bool
• type MasterKeyConfig
• type MasterKeyFileConfig
• type MasterKeyKMSConfig

Constants

const (
	// EncryptionKeysPath is the path to store keys in etcd.
	EncryptionKeysPath = "encryption_keys"
)

Functions

func AesGcmDecrypt

func AesGcmDecrypt(
	key []byte,
	ciphertext []byte,
	iv IvGCM,
) (plaintext []byte, err error)

AesGcmDecrypt decrypt given ciphertext with given key using aes256-gcm. The method is used to decrypt data keys.

func CheckEncryptionMethodSupported

func CheckEncryptionMethodSupported(method encryptionpb.EncryptionMethod) error

CheckEncryptionMethodSupported check whether the encryption method is currently supported. This is to handle future extension to encryption methods on kvproto side.

func DecryptRegion

func DecryptRegion(region *metapb.Region, keyManager KeyManager) error

DecryptRegion decrypt the region start key and end key, if the region object was encrypted. After decryption, encryption meta is also cleared. Note: Call may need to make deep copy of the object if changing the object is undesired.

func EncryptRegion

func EncryptRegion(region *metapb.Region, keyManager KeyManager) (*metapb.Region, error)

EncryptRegion encrypt the region start key and end key, using the current key return from the key manager. The return is an encypted copy of the region, with Encryption meta updated.

func KeyLength

func KeyLength(method encryptionpb.EncryptionMethod) (int, error)

KeyLength return the encryption key length for supported encryption methods.

func NewDataKey

func NewDataKey(
	method encryptionpb.EncryptionMethod,
	creationTime uint64,
) (keyID uint64, key *encryptionpb.DataKey, err error)

NewDataKey randomly generate a new data key.

Types

type Config

type Config struct {
	// Encryption method to use for PD data.
	DataEncryptionMethod string `toml:"data-encryption-method" json:"data-encryption-method"`
	// Specifies how often PD rotates data encryption key.
	DataKeyRotationPeriod typeutil.Duration `toml:"data-key-rotation-period" json:"data-key-rotation-period"`
	// Specifies master key if encryption is enabled.
	MasterKey MasterKeyConfig `toml:"master-key" json:"master-key"`
}

Config define the encryption config structure.

func (*Config) Adjust

func (c *Config) Adjust() error

Adjust validates the config and sets default values.

func (*Config) GetMasterKeyMeta

func (c *Config) GetMasterKeyMeta() (*encryptionpb.MasterKey, error)

GetMasterKeyMeta gets metadata of master key.

func (*Config) GetMethod

func (c *Config) GetMethod() (encryptionpb.EncryptionMethod, error)

GetMethod gets the encryption method.

type IvCTR

type IvCTR []byte

IvCTR represent IV bytes for CTR mode.

func NewIvCTR

func NewIvCTR() (IvCTR, error)

NewIvCTR randomly generate an IV for CTR mode.

type IvGCM

type IvGCM []byte

IvGCM represent IV bytes for GCM mode.

func AesGcmEncrypt

func AesGcmEncrypt(
	key []byte,
	plaintext []byte,
) (ciphertext []byte, iv IvGCM, err error)

AesGcmEncrypt encrypt given plaintext with given key using aes256-gcm. The method is used to encrypt data keys.

func NewIvGCM

func NewIvGCM() (IvGCM, error)

NewIvGCM randomly generate an IV for GCM mode.

type KeyManager

type KeyManager interface {
	GetCurrentKey() (keyID uint64, key *encryptionpb.DataKey, err error)
	GetKey(keyID uint64) (key *encryptionpb.DataKey, err error)
}

KeyManager maintains the list to encryption keys. It handles encryption key generation and rotation, persisting and loading encryption keys.

type Manager

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

Manager maintains the list to encryption keys. It handles encryption key generation and rotation, persisting and loading encryption keys.

func NewManager

func NewManager(
	etcdClient *clientv3.Client,
	config *Config,
) (*Manager, error)

NewManager creates a new key manager.

func (*Manager) GetCurrentKey

func (m *Manager) GetCurrentKey() (keyID uint64, key *encryptionpb.DataKey, err error)

GetCurrentKey get the current encryption key. The key is nil if encryption is not enabled.

func (*Manager) GetKey

func (m *Manager) GetKey(keyID uint64) (*encryptionpb.DataKey, error)

GetKey gets specific encryption key by key id.

func (*Manager) SetLeadership

func (m *Manager) SetLeadership(leadership *election.Leadership) error

SetLeadership sets the PD leadership of the current node. PD leader is responsible to update encryption keys, e.g. key rotation.

func (*Manager) StartBackgroundLoop

func (m *Manager) StartBackgroundLoop(ctx context.Context)

StartBackgroundLoop start the loop to watch encryption keys changes and perform key rotation if needed.

type MasterKey

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

MasterKey is used to encrypt and decrypt encryption metadata (i.e. data encryption keys).

func NewCustomMasterKeyForTest

func NewCustomMasterKeyForTest(key []byte, ciphertextKey []byte) *MasterKey

NewCustomMasterKeyForTest construct a master key instance from raw key and ciphertext key bytes. Used for test only.

func NewMasterKey

func NewMasterKey(config *encryptionpb.MasterKey, ciphertextKey []byte) (*MasterKey, error)

NewMasterKey obtains a master key from backend specified by given config. The config may be altered to fill in metadata generated when initializing the master key.

func (*MasterKey) CiphertextKey

func (k *MasterKey) CiphertextKey() []byte

CiphertextKey returns the key in encrypted form. KMS key type recover the key by decrypting the ciphertextKey from KMS.

func (*MasterKey) Decrypt

func (k *MasterKey) Decrypt(
	ciphertext []byte,
	iv []byte,
) (plaintext []byte, err error)

Decrypt decrypts given ciphertext using the master key and IV.

func (*MasterKey) Encrypt

func (k *MasterKey) Encrypt(plaintext []byte) (ciphertext []byte, iv []byte, err error)

Encrypt encrypts given plaintext using the master key. IV is randomly generated and included in the result. Caller is expected to pass the same IV back for decryption.

func (*MasterKey) IsPlaintext

func (k *MasterKey) IsPlaintext() bool

IsPlaintext checks if the master key is of plaintext type (i.e. no-op for encryption).

type MasterKeyConfig

type MasterKeyConfig struct {
	// Master key type, one of "plaintext", "kms" or "file".
	Type string `toml:"type" json:"type"`

	MasterKeyKMSConfig
	MasterKeyFileConfig
}

MasterKeyConfig defines master key config structure.

type MasterKeyFileConfig

type MasterKeyFileConfig struct {
	// Master key file path.
	FilePath string `toml:"path" json:"path"`
}

MasterKeyFileConfig defines a file-based master key config structure.

type MasterKeyKMSConfig

type MasterKeyKMSConfig struct {
	// KMS CMK key id.
	KmsKeyID string `toml:"key-id" json:"key-id"`
	// KMS region of the CMK.
	KmsRegion string `toml:"region" json:"region"`
	// Custom endpoint to access KMS.
	KmsEndpoint string `toml:"endpoint" json:"endpoint"`
}

MasterKeyKMSConfig defines a KMS master key config structure.