2023-03-15 19:00:52 +03:00
|
|
|
// Copyright (c) HashiCorp, Inc.
|
2024-01-02 21:36:20 +03:00
|
|
|
// SPDX-License-Identifier: BUSL-1.1
|
2023-03-15 19:00:52 +03:00
|
|
|
|
2015-03-06 00:27:35 +03:00
|
|
|
package vault
|
|
|
|
|
2015-03-15 23:52:43 +03:00
|
|
|
import (
|
2018-01-19 09:44:44 +03:00
|
|
|
"context"
|
2015-03-15 23:52:43 +03:00
|
|
|
"errors"
|
2019-10-17 20:33:00 +03:00
|
|
|
"io"
|
2015-05-28 03:25:36 +03:00
|
|
|
"time"
|
2015-03-15 23:52:43 +03:00
|
|
|
|
2019-04-13 00:54:35 +03:00
|
|
|
"github.com/hashicorp/vault/sdk/logical"
|
2015-03-15 23:52:43 +03:00
|
|
|
)
|
2015-03-06 00:27:35 +03:00
|
|
|
|
|
|
|
var (
|
|
|
|
// ErrBarrierSealed is returned if an operation is performed on
|
|
|
|
// a sealed barrier. No operation is expected to succeed before unsealing
|
|
|
|
ErrBarrierSealed = errors.New("Vault is sealed")
|
|
|
|
|
|
|
|
// ErrBarrierAlreadyInit is returned if the barrier is already
|
|
|
|
// initialized. This prevents a re-initialization.
|
|
|
|
ErrBarrierAlreadyInit = errors.New("Vault is already initialized")
|
|
|
|
|
|
|
|
// ErrBarrierNotInit is returned if a non-initialized barrier
|
|
|
|
// is attempted to be unsealed.
|
|
|
|
ErrBarrierNotInit = errors.New("Vault is not initialized")
|
2015-03-12 21:27:32 +03:00
|
|
|
|
|
|
|
// ErrBarrierInvalidKey is returned if the Unseal key is invalid
|
|
|
|
ErrBarrierInvalidKey = errors.New("Unseal failed, invalid key")
|
2020-06-25 19:22:13 +03:00
|
|
|
|
|
|
|
// ErrPlaintextTooLarge is returned if a plaintext is offered for encryption
|
|
|
|
// that is too large to encrypt in memory
|
|
|
|
ErrPlaintextTooLarge = errors.New("plaintext value too large")
|
2015-03-06 00:27:35 +03:00
|
|
|
)
|
|
|
|
|
|
|
|
const (
|
|
|
|
// barrierInitPath is the path used to store our init sentinel file
|
|
|
|
barrierInitPath = "barrier/init"
|
2015-05-28 01:23:43 +03:00
|
|
|
|
|
|
|
// keyringPath is the location of the keyring data. This is encrypted
|
2021-12-07 04:12:20 +03:00
|
|
|
// by the root key.
|
2017-11-30 17:43:07 +03:00
|
|
|
keyringPath = "core/keyring"
|
|
|
|
keyringPrefix = "core/"
|
2015-05-29 01:52:26 +03:00
|
|
|
|
|
|
|
// keyringUpgradePrefix is the path used to store keyring update entries.
|
|
|
|
// When running in HA mode, the active instance will install the new key
|
|
|
|
// and re-write the keyring. For standby instances, they need an upgrade
|
2021-12-07 04:12:20 +03:00
|
|
|
// path from key N to N+1. They cannot just use the root key because
|
|
|
|
// in the event of a rekey, that root key can no longer decrypt the keyring.
|
2015-05-29 01:52:26 +03:00
|
|
|
// When key N+1 is installed, we create an entry at "prefix/N" which uses
|
|
|
|
// encryption key N to provide the N+1 key. The standby instances scan
|
|
|
|
// for this periodically and refresh their keyring. The upgrade keys
|
|
|
|
// are deleted after a few minutes, but this provides enough time for the
|
|
|
|
// standby instances to upgrade without causing any disruption.
|
|
|
|
keyringUpgradePrefix = "core/upgrade/"
|
2015-05-30 00:29:55 +03:00
|
|
|
|
2021-12-07 04:12:20 +03:00
|
|
|
// rootKeyPath is the location of the root key. This is encrypted
|
2015-05-30 00:29:55 +03:00
|
|
|
// by the latest key in the keyring. This is only used by standby instances
|
|
|
|
// to handle the case of a rekey. If the active instance does a rekey,
|
|
|
|
// the standby instances can no longer reload the keyring since they
|
2021-12-07 04:12:20 +03:00
|
|
|
// have the old root key. This key can be decrypted if you have the
|
|
|
|
// keyring to discover the new root key. The new root key is then
|
2015-05-30 00:29:55 +03:00
|
|
|
// used to reload the keyring itself.
|
2021-12-07 04:12:20 +03:00
|
|
|
rootKeyPath = "core/master"
|
2019-10-18 21:46:00 +03:00
|
|
|
|
|
|
|
// shamirKekPath is used with Shamir in v1.3+ to store a copy of the
|
2021-12-07 04:12:20 +03:00
|
|
|
// unseal key behind the barrier. As with rootKeyPath this is primarily
|
2019-10-18 21:46:00 +03:00
|
|
|
// used by standbys to handle rekeys. It also comes into play when restoring
|
|
|
|
// raft snapshots.
|
|
|
|
shamirKekPath = "core/shamir-kek"
|
2015-03-06 00:27:35 +03:00
|
|
|
)
|
|
|
|
|
|
|
|
// SecurityBarrier is a critical component of Vault. It is used to wrap
|
|
|
|
// an untrusted physical backend and provide a single point of encryption,
|
|
|
|
// decryption and checksum verification. The goal is to ensure that any
|
|
|
|
// data written to the barrier is confidential and that integrity is preserved.
|
|
|
|
// As a real-world analogy, this is the steel and concrete wrapper around
|
|
|
|
// a Vault. The barrier should only be Unlockable given its key.
|
|
|
|
type SecurityBarrier interface {
|
|
|
|
// Initialized checks if the barrier has been initialized
|
2021-12-07 04:12:20 +03:00
|
|
|
// and has a root key set.
|
2018-01-19 09:44:44 +03:00
|
|
|
Initialized(ctx context.Context) (bool, error)
|
2015-03-06 00:27:35 +03:00
|
|
|
|
|
|
|
// Initialize works only if the barrier has not been initialized
|
2021-12-07 04:12:20 +03:00
|
|
|
// and makes use of the given root key. When sealKey is provided
|
|
|
|
// it's because we're using a new-style Shamir seal, and rootKey
|
2019-10-18 21:46:00 +03:00
|
|
|
// is to be stored using sealKey to encrypt it.
|
2021-12-07 04:12:20 +03:00
|
|
|
Initialize(ctx context.Context, rootKey []byte, sealKey []byte, random io.Reader) error
|
2015-03-06 00:27:35 +03:00
|
|
|
|
|
|
|
// GenerateKey is used to generate a new key
|
2019-10-17 20:33:00 +03:00
|
|
|
GenerateKey(io.Reader) ([]byte, error)
|
2015-03-06 00:27:35 +03:00
|
|
|
|
2015-03-12 21:20:27 +03:00
|
|
|
// KeyLength is used to sanity check a key
|
|
|
|
KeyLength() (int, int)
|
|
|
|
|
2015-03-06 00:27:35 +03:00
|
|
|
// Sealed checks if the barrier has been unlocked yet. The Barrier
|
|
|
|
// is not expected to be able to perform any CRUD until it is unsealed.
|
|
|
|
Sealed() (bool, error)
|
|
|
|
|
2021-12-07 04:12:20 +03:00
|
|
|
// Unseal is used to provide the unseal key which permits the barrier
|
2015-03-06 00:27:35 +03:00
|
|
|
// to be unsealed. If the key is not correct, the barrier remains sealed.
|
2018-01-19 09:44:44 +03:00
|
|
|
Unseal(ctx context.Context, key []byte) error
|
2015-03-06 00:27:35 +03:00
|
|
|
|
2021-12-07 04:12:20 +03:00
|
|
|
// VerifyRoot is used to check if the given key matches the root key
|
|
|
|
VerifyRoot(key []byte) error
|
2015-05-28 21:28:33 +03:00
|
|
|
|
2021-12-07 04:12:20 +03:00
|
|
|
// SetRootKey is used to directly set a new root key. This is used in
|
2018-03-20 21:54:10 +03:00
|
|
|
// replicated scenarios due to the chicken and egg problem of reloading the
|
2021-12-07 04:12:20 +03:00
|
|
|
// keyring from disk before we have the root key to decrypt it.
|
|
|
|
SetRootKey(key []byte) error
|
2017-02-17 07:09:39 +03:00
|
|
|
|
2015-05-29 02:09:15 +03:00
|
|
|
// ReloadKeyring is used to re-read the underlying keyring.
|
|
|
|
// This is used for HA deployments to ensure the latest keyring
|
|
|
|
// is present in the leader.
|
2018-01-19 09:44:44 +03:00
|
|
|
ReloadKeyring(ctx context.Context) error
|
2015-05-29 02:09:15 +03:00
|
|
|
|
2021-12-07 04:12:20 +03:00
|
|
|
// ReloadRootKey is used to re-read the underlying root key.
|
|
|
|
// This is used for HA deployments to ensure the latest root key
|
2015-05-30 00:29:55 +03:00
|
|
|
// is available for keyring reloading.
|
2021-12-07 04:12:20 +03:00
|
|
|
ReloadRootKey(ctx context.Context) error
|
2015-05-30 00:29:55 +03:00
|
|
|
|
2015-03-06 00:27:35 +03:00
|
|
|
// Seal is used to re-seal the barrier. This requires the barrier to
|
|
|
|
// be unsealed again to perform any further operations.
|
|
|
|
Seal() error
|
|
|
|
|
2015-05-28 03:05:02 +03:00
|
|
|
// Rotate is used to create a new encryption key. All future writes
|
|
|
|
// should use the new key, while old values should still be decryptable.
|
2019-10-17 20:33:00 +03:00
|
|
|
Rotate(ctx context.Context, reader io.Reader) (uint32, error)
|
2015-05-28 03:05:02 +03:00
|
|
|
|
2015-05-29 02:42:32 +03:00
|
|
|
// CreateUpgrade creates an upgrade path key to the given term from the previous term
|
2018-01-19 09:44:44 +03:00
|
|
|
CreateUpgrade(ctx context.Context, term uint32) error
|
2015-05-29 02:42:32 +03:00
|
|
|
|
|
|
|
// DestroyUpgrade destroys the upgrade path key to the given term
|
2018-01-19 09:44:44 +03:00
|
|
|
DestroyUpgrade(ctx context.Context, term uint32) error
|
2015-05-29 02:42:32 +03:00
|
|
|
|
|
|
|
// CheckUpgrade looks for an upgrade to the current term and installs it
|
2018-01-19 09:44:44 +03:00
|
|
|
CheckUpgrade(ctx context.Context) (bool, uint32, error)
|
2015-05-29 01:52:26 +03:00
|
|
|
|
2015-05-28 03:25:36 +03:00
|
|
|
// ActiveKeyInfo is used to inform details about the active key
|
|
|
|
ActiveKeyInfo() (*KeyInfo, error)
|
|
|
|
|
2021-02-25 23:27:25 +03:00
|
|
|
// RotationConfig returns the auto-rotation config for the barrier key
|
|
|
|
RotationConfig() (KeyRotationConfig, error)
|
|
|
|
|
|
|
|
// SetRotationConfig updates the auto-rotation config for the barrier key
|
|
|
|
SetRotationConfig(ctx context.Context, config KeyRotationConfig) error
|
|
|
|
|
2015-05-28 03:13:40 +03:00
|
|
|
// Rekey is used to change the master key used to protect the keyring
|
2018-01-19 09:44:44 +03:00
|
|
|
Rekey(context.Context, []byte) error
|
2015-05-28 03:13:40 +03:00
|
|
|
|
2017-02-17 07:09:39 +03:00
|
|
|
// For replication we must send over the keyring, so this must be available
|
|
|
|
Keyring() (*Keyring, error)
|
|
|
|
|
2021-02-25 23:27:25 +03:00
|
|
|
// For encryption count shipping, a function which handles updating local encryption counts if the consumer succeeds.
|
|
|
|
// This isolates the barrier code from the replication system
|
|
|
|
ConsumeEncryptionCount(consumer func(int64) error) error
|
|
|
|
|
|
|
|
// Add encryption counts from a remote source (downstream cluster node)
|
|
|
|
AddRemoteEncryptions(encryptions int64)
|
|
|
|
|
|
|
|
// Check whether an automatic rotation is due
|
|
|
|
CheckBarrierAutoRotate(ctx context.Context) (string, error)
|
|
|
|
|
2015-04-11 02:43:35 +03:00
|
|
|
// SecurityBarrier must provide the storage APIs
|
2019-01-31 17:25:18 +03:00
|
|
|
logical.Storage
|
2017-02-17 07:09:39 +03:00
|
|
|
|
|
|
|
// SecurityBarrier must provide the encryption APIs
|
|
|
|
BarrierEncryptor
|
2015-04-11 02:43:35 +03:00
|
|
|
}
|
|
|
|
|
|
|
|
// BarrierStorage is the storage only interface required for a Barrier.
|
|
|
|
type BarrierStorage interface {
|
2015-03-06 00:27:35 +03:00
|
|
|
// Put is used to insert or update an entry
|
2019-01-31 17:25:18 +03:00
|
|
|
Put(ctx context.Context, entry *logical.StorageEntry) error
|
2015-03-06 00:27:35 +03:00
|
|
|
|
|
|
|
// Get is used to fetch an entry
|
2019-01-31 17:25:18 +03:00
|
|
|
Get(ctx context.Context, key string) (*logical.StorageEntry, error)
|
2015-03-06 00:27:35 +03:00
|
|
|
|
|
|
|
// Delete is used to permanently delete an entry
|
2018-01-19 09:44:44 +03:00
|
|
|
Delete(ctx context.Context, key string) error
|
2015-03-06 00:27:35 +03:00
|
|
|
|
|
|
|
// List is used ot list all the keys under a given
|
|
|
|
// prefix, up to the next prefix.
|
2018-01-19 09:44:44 +03:00
|
|
|
List(ctx context.Context, prefix string) ([]string, error)
|
2015-03-06 00:27:35 +03:00
|
|
|
}
|
|
|
|
|
2017-02-17 07:09:39 +03:00
|
|
|
// BarrierEncryptor is the in memory only interface that does not actually
|
|
|
|
// use the underlying barrier. It is used for lower level modules like the
|
|
|
|
// Write-Ahead-Log and Merkle index to allow them to use the barrier.
|
|
|
|
type BarrierEncryptor interface {
|
2018-01-19 13:28:47 +03:00
|
|
|
Encrypt(ctx context.Context, key string, plaintext []byte) ([]byte, error)
|
|
|
|
Decrypt(ctx context.Context, key string, ciphertext []byte) ([]byte, error)
|
2017-02-17 07:09:39 +03:00
|
|
|
}
|
|
|
|
|
2015-05-28 03:25:36 +03:00
|
|
|
// KeyInfo is used to convey information about the encryption key
|
|
|
|
type KeyInfo struct {
|
|
|
|
Term int
|
|
|
|
InstallTime time.Time
|
2021-02-25 23:27:25 +03:00
|
|
|
Encryptions int64
|
2015-05-28 03:25:36 +03:00
|
|
|
}
|