Rename master key to root key (hashicorp#13324)

* See what it looks like to replace "master key" with "root key".  There are two places that would require more challenging code changes: the storage path `core/master`, and its contents (the JSON-serialized EncodedKeyringtructure.)

* Restore accidentally deleted line

* Add changelog

* Update root->recovery

* Fix test

Co-authored-by: Nick Cabatoff <ncabatoff@hashicorp.com>

Author: 2 people

changelog/13324.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+core: Replace "master key" terminology with "root key"
+```

command/operator_init.go

@@ -57,10 +57,10 @@ Usage: vault operator init [options]
   same storage backend in HA mode, you only need to initialize one Vault to
   initialize the storage backend.
 
-  During initialization, Vault generates an in-memory master key and applies
-  Shamir's secret sharing algorithm to disassemble that master key into a
+  During initialization, Vault generates an in-memory root key and applies
+  Shamir's secret sharing algorithm to disassemble that root key into a
   configuration number of key shares such that a configurable subset of those
-  key shares must come together to regenerate the master key. These keys are
+  key shares must come together to regenerate the root key. These keys are
   often called "unseal keys" in Vault's documentation.
 
   This command cannot be run against an already-initialized Vault cluster.
@@ -105,7 +105,7 @@ func (c *OperatorInitCommand) Flags() *FlagSets {
 		Target:     &c.flagKeyShares,
 		Default:    defKeyShares,
 		Completion: complete.PredictAnything,
-		Usage: "Number of key shares to split the generated master key into. " +
+		Usage: "Number of key shares to split the generated root key into. " +
 			"This is the number of \"unseal keys\" to generate.",
 	})
 
@@ -115,7 +115,7 @@ func (c *OperatorInitCommand) Flags() *FlagSets {
 		Target:     &c.flagKeyThreshold,
 		Default:    defKeyThreshold,
 		Completion: complete.PredictAnything,
-		Usage: "Number of key shares required to reconstruct the master key. " +
+		Usage: "Number of key shares required to reconstruct the root key. " +
 			"This must be less than or equal to -key-shares.",
 	})
 
@@ -447,8 +447,8 @@ func (c *OperatorInitCommand) init(client *api.Client, req *api.InitRequest) int
 
 		c.UI.Output("")
 		c.UI.Output(wrapAtLength(fmt.Sprintf(
-			"Vault does not store the generated master key. Without at least %d "+
-				"keys to reconstruct the master key, Vault will remain permanently "+
+			"Vault does not store the generated root key. Without at least %d "+
+				"keys to reconstruct the root key, Vault will remain permanently "+
 				"sealed!",
 			req.SecretThreshold)))
 

command/operator_rekey.go

@@ -51,7 +51,7 @@ Usage: vault operator rekey [options] [KEY]
 
   Generates a new set of unseal keys. This can optionally change the total
   number of key shares or the required threshold of those key shares to
-  reconstruct the master key. This operation is zero downtime, but it requires
+  reconstruct the root key. This operation is zero downtime, but it requires
   the Vault is unsealed and a quorum of existing unseal keys are provided.
 
   An unseal key may be provided directly on the command line as an argument to
@@ -129,7 +129,7 @@ func (c *OperatorRekeyCommand) Flags() *FlagSets {
 		Target:     &c.flagKeyShares,
 		Default:    5,
 		Completion: complete.PredictAnything,
-		Usage: "Number of key shares to split the generated master key into. " +
+		Usage: "Number of key shares to split the generated root key into. " +
 			"This is the number of \"unseal keys\" to generate.",
 	})
 
@@ -139,7 +139,7 @@ func (c *OperatorRekeyCommand) Flags() *FlagSets {
 		Target:     &c.flagKeyThreshold,
 		Default:    3,
 		Completion: complete.PredictAnything,
-		Usage: "Number of key shares required to reconstruct the master key. " +
+		Usage: "Number of key shares required to reconstruct the root key. " +
 			"This must be less than or equal to -key-shares.",
 	})
 

command/operator_seal.go

@@ -27,11 +27,11 @@ Usage: vault operator seal [options]
 
   Seals the Vault server. Sealing tells the Vault server to stop responding
   to any operations until it is unsealed. When sealed, the Vault server
-  discards its in-memory master key to unlock the data, so it is physically
+  discards its in-memory root key to unlock the data, so it is physically
   blocked from responding to operations unsealed.
 
   If an unseal is in progress, sealing the Vault will reset the unsealing
-  process. Users will have to re-enter their portions of the master key again.
+  process. Users will have to re-enter their portions of the root key again.
 
   This command does nothing if the Vault server is already sealed.
 

command/operator_unseal.go

@@ -34,9 +34,9 @@ func (c *OperatorUnsealCommand) Help() string {
 	helpText := `
 Usage: vault operator unseal [options] [KEY]
 
-  Provide a portion of the master key to unseal a Vault server. Vault starts
+  Provide a portion of the root key to unseal a Vault server. Vault starts
   in a sealed state. It cannot perform operations until it is unsealed. This
-  command accepts a portion of the master key (an "unseal key").
+  command accepts a portion of the root key (an "unseal key").
 
   The unseal key can be supplied as an argument to the command, but this is
   not recommended as the unseal key will be available in your history:

physical/raft/raft.go

@@ -1144,7 +1144,7 @@ func (b *RaftBackend) SnapshotHTTP(out *logical.HTTPResponseWriter, access *seal
 
 // Snapshot takes a raft snapshot, packages it into a archive file and writes it
 // to the provided writer. Seal access is used to encrypt the SHASUM file so we
-// can validate the snapshot was taken using the same master keys or not.
+// can validate the snapshot was taken using the same root keys or not.
 func (b *RaftBackend) Snapshot(out io.Writer, access *seal.Access) error {
 	b.l.RLock()
 	defer b.l.RUnlock()
@@ -1167,7 +1167,7 @@ func (b *RaftBackend) Snapshot(out io.Writer, access *seal.Access) error {
 // WriteSnapshotToTemp reads a snapshot archive off the provided reader,
 // extracts the data and writes the snapshot to a temporary file. The seal
 // access is used to decrypt the SHASUM file in the archive to ensure this
-// snapshot has the same master key as the running instance. If the provided
+// snapshot has the same root key as the running instance. If the provided
 // access is nil then it will skip that validation.
 func (b *RaftBackend) WriteSnapshotToTemp(in io.ReadCloser, access *seal.Access) (*os.File, func(), raft.SnapshotMeta, error) {
 	b.l.RLock()

vault/barrier.go

@@ -35,33 +35,33 @@ const (
 	barrierInitPath = "barrier/init"
 
 	// keyringPath is the location of the keyring data. This is encrypted
-	// by the master key.
+	// by the root key.
 	keyringPath   = "core/keyring"
 	keyringPrefix = "core/"
 
 	// 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
-	// path from key N to N+1. They cannot just use the master key because
-	// in the event of a rekey, that master key can no longer decrypt the keyring.
+	// 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.
 	// 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/"
 
-	// masterKeyPath is the location of the master key. This is encrypted
+	// rootKeyPath is the location of the root key. This is encrypted
 	// 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
-	// have the old master key. This key can be decrypted if you have the
-	// keyring to discover the new master key. The new master key is then
+	// 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
 	// used to reload the keyring itself.
-	masterKeyPath = "core/master"
+	rootKeyPath = "core/master"
 
 	// shamirKekPath is used with Shamir in v1.3+ to store a copy of the
-	// unseal key behind the barrier.  As with masterKeyPath this is primarily
+	// unseal key behind the barrier.  As with rootKeyPath this is primarily
 	// used by standbys to handle rekeys.  It also comes into play when restoring
 	// raft snapshots.
 	shamirKekPath = "core/shamir-kek"
@@ -75,14 +75,14 @@ const (
 // a Vault. The barrier should only be Unlockable given its key.
 type SecurityBarrier interface {
 	// Initialized checks if the barrier has been initialized
-	// and has a master key set.
+	// and has a root key set.
 	Initialized(ctx context.Context) (bool, error)
 
 	// Initialize works only if the barrier has not been initialized
-	// and makes use of the given master key.  When sealKey is provided
-	// it's because we're using a new-style Shamir seal, and masterKey
+	// 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
 	// is to be stored using sealKey to encrypt it.
-	Initialize(ctx context.Context, masterKey []byte, sealKey []byte, random io.Reader) error
+	Initialize(ctx context.Context, rootKey []byte, sealKey []byte, random io.Reader) error
 
 	// GenerateKey is used to generate a new key
 	GenerateKey(io.Reader) ([]byte, error)
@@ -94,27 +94,27 @@ type SecurityBarrier interface {
 	// is not expected to be able to perform any CRUD until it is unsealed.
 	Sealed() (bool, error)
 
-	// Unseal is used to provide the master key which permits the barrier
+	// Unseal is used to provide the unseal key which permits the barrier
 	// to be unsealed. If the key is not correct, the barrier remains sealed.
 	Unseal(ctx context.Context, key []byte) error
 
-	// VerifyMaster is used to check if the given key matches the master key
-	VerifyMaster(key []byte) error
+	// VerifyRoot is used to check if the given key matches the root key
+	VerifyRoot(key []byte) error
 
-	// SetMasterKey is used to directly set a new master key. This is used in
+	// SetRootKey is used to directly set a new root key. This is used in
 	// replicated scenarios due to the chicken and egg problem of reloading the
-	// keyring from disk before we have the master key to decrypt it.
-	SetMasterKey(key []byte) error
+	// keyring from disk before we have the root key to decrypt it.
+	SetRootKey(key []byte) error
 
 	// 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.
 	ReloadKeyring(ctx context.Context) error
 
-	// ReloadMasterKey is used to re-read the underlying masterkey.
-	// This is used for HA deployments to ensure the latest master key
+	// ReloadRootKey is used to re-read the underlying root key.
+	// This is used for HA deployments to ensure the latest root key
 	// is available for keyring reloading.
-	ReloadMasterKey(ctx context.Context) error
+	ReloadRootKey(ctx context.Context) error
 
 	// Seal is used to re-seal the barrier. This requires the barrier to
 	// be unsealed again to perform any further operations.