支持 Vault 的秘密引擎

Spring Vault 提供了多种扩展来支持 Vault 的各种秘密引擎。

具体来说，Spring Vault 提供了以下秘密引擎的扩展：

Key-Value 版本 1（"非版本化秘密"）
Key-Value 版本 2（"版本化秘密"）
PKI（公钥基础设施）
Token（令牌）身份验证后端
Transform（转换）（企业版功能）
Transit 后端
System 后端

你也可以通过 VaultTemplate 上的方法直接使用所有其他后端（VaultTemplate.read(…), VaultTemplate.write(…)）。

Key-Value 版本 1（"非版本化秘密"）

kv 秘密引擎用于在配置的 Vault 物理存储中存储任意秘密。

以非版本化方式运行 kv 秘密引擎时，只会保留键的最新写入值。非版本化 kv 的优点是每个键所需的存储空间更小，因为不会存储额外的元数据或历史记录。此外，以此方式配置的后端处理请求时性能更高，因为存储调用更少，且对任何给定请求都没有锁。

Spring Vault 提供了一个专用的 Key-Value API，用于封装不同 Key-Value API 实现之间的差异。VaultKeyValueOperations 遵循 Vault CLI 的设计。Vault CLI 是 Vault 的主要命令行工具，提供了诸如 vault kv get、vault kv put 等命令。

你也可以通过指定版本和挂载路径将此 API 用于两种 Key-Value 引擎版本。以下示例使用 Key-Value 版本 1

VaultOperations operations = new VaultTemplate(new VaultEndpoint());
VaultKeyValueOperations keyValueOperations = operations.opsForKeyValue("secret",
							VaultKeyValueOperationsSupport.KeyValueBackend.KV_1);

keyValueOperations.put("elvis", Collections.singletonMap("password", "409-52-2002"));

VaultResponse read = keyValueOperations.get("elvis");
read.getRequiredData().get("social-security-number");

VaultKeyValueOperations 支持所有 Key-Value 操作，例如 put、get、delete、list。

或者，也可以通过 VaultTemplate 使用此 API，因为它具有直接映射和简单用法，键和响应直接映射到输入和输出键。以下示例演示了在 mykey 处写入和读取秘密。kv 秘密引擎挂载在 secret

VaultOperations operations = new VaultTemplate(new VaultEndpoint());

operations.write("secret/elvis", Collections.singletonMap("social-security-number", "409-52-2002"));

VaultResponse read = operations.read("secret/elvis");
read.getRequiredData().get("social-security-number");

你可以在 Vault 参考文档中找到有关 Vault Key-Value 版本 1 API 的更多详细信息。

Key-Value 版本 2（"版本化秘密"）

你可以将 kv 秘密引擎运行在两个版本之一。本节介绍如何使用版本 2。运行版本 2 的 kv 后端时，一个键可以保留可配置数量的版本。你可以检索旧版本的元数据和数据。此外，你可以使用检查并设置（check-and-set）操作来避免意外覆盖数据。

与 Key-Value 版本 1（"非版本化秘密"）类似，Spring Vault 提供了一个专用的 Key-Value API，用于封装不同 Key-Value API 实现之间的差异。VaultKeyValueOperations 遵循 Vault CLI 的设计，Vault CLI 是 Vault 的主要命令行工具，提供了诸如 vault kv get、vault kv put 等命令。

你也可以通过指定版本和挂载路径将此 API 用于两种 Key-Value 引擎版本。以下示例使用 Key-Value 版本 2

VaultOperations operations = new VaultTemplate(new VaultEndpoint());
VaultKeyValueOperations keyValueOperations = operations.opsForKeyValue("secret",
							VaultKeyValueOperationsSupport.KeyValueBackend.KV_2);

keyValueOperations.put("elvis", Collections.singletonMap("social-security-number", "409-52-2002"));

VaultResponse read = keyValueOperations.get("elvis");
read.getRequiredData().get("social-security-number");

VaultKeyValueOperations 支持所有 Key-Value 操作，例如 put、get、delete、list。

你也可以与版本化 Key-Value API 的具体细节进行交互。如果你想获取特定的秘密或需要访问元数据，这将非常有用。

VaultOperations operations = new VaultTemplate(new VaultEndpoint());
VaultVersionedKeyValueOperations versionedOperations = operations.opsForVersionedKeyValue("secret");

Versioned.Metadata metadata = versionedOperations.put("elvis",							(1)
					Collections.singletonMap("social-security-number", "409-52-2002"));

Version version = metadata.getVersion();												(2)

Versioned<Object> ssn = versionedOperations.get("elvis", Version.from(42));				(3)

Versioned<SocialSecurityNumber> mappedSsn = versionedOperations.get("elvis",			(4)
											Version.from(42), SocialSecurityNumber.class);

Versioned<Map<String,String>> versioned = Versioned.create(Collections					(5)
						.singletonMap("social-security-number", "409-52-2002"),
						Version.from(42));

versionedOperations.put("elvis", version);

1	在 `elvis` 处存储秘密，该位置在 `secret/` 挂载路径下可用。
2	在版本化后端存储数据会返回元数据，例如版本号。
3	版本化 Key-Value API 允许检索由版本号标识的特定版本。
4	版本化 Key-Value 秘密可以映射到值对象中。
5	使用 CAS 更新版本化秘密时，输入必须引用先前获取的版本。

虽然可以通过 VaultTemplate 使用 kv v2 秘密引擎，但这并不是最便捷的方式，因为该 API 在上下文路径和输入/输出表示方式上有所不同。具体来说，与实际秘密的交互需要对数据部分进行包装和解包装，并在挂载路径和秘密键之间引入一个 data/ 路径段。

VaultOperations operations = new VaultTemplate(new VaultEndpoint());

operations.write("secret/data/elvis", Collections.singletonMap("data",
			Collections.singletonMap("social-security-number", "409-52-2002")));

VaultResponse read = operations.read("secret/data/ykey");
Map<String,String> data = (Map<String, String>) read.getRequiredData().get("data");
data.get("social-security-number");

你可以在 Vault 参考文档中找到有关 Vault Key-Value 版本 2 API 的更多详细信息。

PKI（公钥基础设施）

pki 秘密引擎是一个证书后端，通过实现证书颁发机构操作来提供服务。

PKI 秘密引擎生成动态的 X.509 证书。使用此秘密引擎，服务无需经过通常手动生成私钥和 CSR、提交给 CA 并等待验证和签名过程完成的流程即可获取证书。Vault 内置的身份验证和授权机制提供了验证功能。

Spring Vault 通过 VaultPkiOperations 支持证书的颁发、签名、吊销和 CRL 检索。所有其他 PKI 功能都可以通过 VaultOperations 使用。

以下示例简要说明了如何颁发和吊销证书

VaultOperations operations = new VaultTemplate(new VaultEndpoint());
VaultPkiOperations pkiOperations = operations.opsForPki("pki");

VaultCertificateRequest request = VaultCertificateRequest.builder()								(1)
			.ttl(Duration.ofHours(48))
			.altNames(Arrays.asList("prod.dc-1.example.com", "prod.dc-2.example.com"))
			.withIpSubjectAltName("1.2.3.4")
			.commonName("hello.example.com")
			.build();

VaultCertificateResponse response = pkiOperations.issueCertificate("production", request); 		(2)
CertificateBundle certificateBundle = response.getRequiredData();

KeyStore keyStore = certificateBundle.createKeyStore("my-keystore");							(3)

KeySpec privateKey = certificateBundle.getPrivateKeySpec();										(4)
X509Certificate certificate = certificateBundle.getX509Certificate();
X509Certificate caCertificate = certificateBundle.getX509IssuerCertificate();

pkiOperations.revoke(certificateBundle.getSerialNumber());										(5)

1	使用 `VaultCertificateRequest` 构建器构造证书请求。
2	从 Vault 请求证书。Vault 作为证书颁发机构，返回一个已签名的 X.509 证书。实际响应是一个 `CertificateBundle` 对象。
3	你可以直接将生成的证书获取为 Java KeyStore，它包含公钥、私钥以及颁发者证书。KeyStore 用途广泛，此格式适用于配置（例如 HTTP 客户端、数据库驱动程序或 SSL 安全的 HTTP 服务器）。
4	`CertificateBundle` 允许通过 Java Cryptography Extension API 直接访问私钥以及公钥和颁发者证书。
5	证书不再使用（或已泄露）后，你可以通过其序列号吊销它。Vault 会将吊销的证书包含在其 CRL 中。

你可以在 Vault 参考文档中找到有关 Vault PKI secrets API 的更多详细信息。

Token（令牌）身份验证后端

这个后端是一个身份验证后端，它不与实际的秘密交互。相反，它提供了访问令牌管理功能。你可以在身份验证方法章节中阅读更多关于基于令牌的身份验证的信息。

token 身份验证方法是内置的，并自动在 /auth/token 处可用。它允许用户使用令牌进行身份验证，还可以创建新令牌、通过令牌撤销秘密等。

当任何其他身份验证方法返回一个身份时，Vault core 会调用令牌方法为该身份创建一个新的唯一令牌。

你还可以使用令牌存储绕过任何其他身份验证方法。你可以直接创建令牌，并对令牌执行各种其他操作，例如续订和吊销。

Spring Vault 使用此后端来续订和吊销由配置的身份验证方法提供的会话令牌。

以下示例展示了如何在应用程序中请求、续订和吊销 Vault 令牌

VaultOperations operations = new VaultTemplate(new VaultEndpoint());
VaultTokenOperations tokenOperations = operations.opsForToken();

VaultTokenResponse tokenResponse = tokenOperations.create();                          (1)
VaultToken justAToken = tokenResponse.getToken();

VaultTokenRequest tokenRequest = VaultTokenRequest.builder().withPolicy("policy-for-myapp")
									.displayName("Access tokens for myapp")
									.renewable()
									.ttl(Duration.ofHours(1))
									.build();

VaultTokenResponse appTokenResponse = tokenOperations.create(tokenRequest);          (2)
VaultToken appToken = appTokenResponse.getToken();

tokenOperations.renew(appToken);                                                     (3)

tokenOperations.revoke(appToken);                                                    (4)

1	通过应用角色默认值创建一个令牌。
2	使用构建器 API，你可以定义要请求的令牌的细粒度设置。请求令牌会返回一个 `VaultToken` 对象，该对象用作 Vault 令牌的值对象。
3	你可以通过 Token API 续订令牌。通常，这由 `SessionManager` 完成，用于跟踪 Vault 会话令牌。
4	如果需要，可以通过 Token API 吊销令牌。通常，这由 `SessionManager` 完成，用于跟踪 Vault 会话令牌。

你可以在 Vault 参考文档中找到有关 Vault Token 身份验证方法 API 的更多详细信息。

Transit 后端

Transit 秘密引擎处理传输中数据的加密功能。Vault 不存储发送到此秘密引擎的数据。它也可以被视为“密码学即服务”或“加密即服务”。Transit 秘密引擎还可以签名和验证数据，生成数据的哈希和 HMAC，并作为随机字节源。

Transit 的主要用例是加密来自应用程序的数据，同时仍将加密数据存储在某个主要数据存储中。这减轻了应用程序开发人员正确处理加密和解密流程的负担，并将负担转移给了 Vault 的运维人员。

Spring Vault 支持广泛的 Transit 操作

密钥创建
密钥重新配置
加密/解密/重打包
HMAC 计算
签名和签名验证

transit 中的所有操作都围绕着密钥。Transit 引擎支持密钥的版本控制和多种密钥类型。请注意，密钥类型可能会限制可使用的操作。

以下示例展示了如何创建密钥以及如何加密和解密数据

VaultOperations operations = new VaultTemplate(new VaultEndpoint());
VaultTransitOperations transitOperations = operations.opsForTransit("transit");

transitOperations.createKey("my-aes-key", VaultTransitKeyCreationRequest.ofKeyType("aes128-gcm96"));	(1)

String ciphertext = transitOperations.encrypt("my-aes-key", "plaintext to encrypt");					(2)

String plaintext = transitOperations.decrypt("my-aes-key", ciphertext);									(3)

1	首先，我们需要一个密钥。每个密钥都需要指定类型。`aes128-gcm96` 支持加密、解密、密钥派生和会聚加密，本示例中我们需要加密和解密。
2	接下来，我们加密包含应被加密的明文的 `String`。输入的 `String` 使用默认的 `Charset` 将字符串编码为其二进制表示形式。请求令牌会返回一个 `VaultToken`，该对象用作 Vault 令牌的值对象。`encrypt` 方法返回 Base64 编码的密文，通常以 `vault:` 开头。
3	要将密文解密为明文，请调用 `decrypt` 方法。它解密密文并返回一个使用默认字符集解码的 `String`。

前面的示例对加密操作使用了简单的字符串。虽然这是一种简单的方法，但存在字符集配置错误的风险，并且不是二进制安全的。当明文使用二进制表示形式表示图像、压缩数据或二进制数据结构等数据时，需要二进制安全。

要加密和解密二进制数据，请使用可以保存二进制值的 Plaintext 和 Ciphertext 值对象。

byte [] plaintext = "plaintext to encrypt".getBytes();

Ciphertext ciphertext = transitOperations.encrypt("my-aes-key", Plaintext.of(plaintext));			(1)

Plaintext decrypttedPlaintext = transitOperations.decrypt("my-aes-key", ciphertext);				(2)

1	假设密钥 `my-aes-key` 已经存在，我们正在加密 `Plaintext` 对象。相应地，`encrypt` 方法返回一个 `Ciphertext` 对象。
2	`Ciphertext` 对象可以直接用于解密，并返回一个 `Plaintext` 对象。

Plaintext 和 Ciphertext 附带一个上下文对象 VaultTransitContext。它用于为会聚加密提供 nonce 值，并用于提供上下文值以利用密钥派生。

Transit 允许对明文进行签名并验证给定明文的签名。签名操作需要非对称密钥，通常使用椭圆曲线密码学或 RSA。

签名使用公钥/私钥对来确保真实性。
签名者使用其私钥创建签名。否则，任何人都可以在你的名义下签署消息。验证者使用公钥部分来验证签名。实际签名通常是一个哈希值。

在内部，计算哈希值并使用私钥对其进行加密以创建最终签名。验证过程解密签名消息，计算明文的哈希值，并比较两个哈希值以检查签名是否有效。

byte [] plaintext = "plaintext to sign".getBytes();

transitOperations.createKey("my-ed25519-key", VaultTransitKeyCreationRequest.ofKeyType("ed25519"));	(1)

Signature signature = transitOperations.sign("my-ed25519-key", Plaintext.of(plaintext));			(2)

boolean valid = transitOperations.verify("my-ed25519-key", Plaintext.of(plaintext), signature);		(3)

1	签名需要非对称密钥。你可以使用任何椭圆曲线密码学或 RSA 密钥类型。一旦密钥创建完成，你就具备了创建签名的所有先决条件。
2	为明文消息创建签名。返回的 `Signature` 包含一个使用 Base64 字符的 ASCII 安全字符串。
3	要验证签名，验证过程需要一个 `Signature` 对象和明文消息。返回值为签名是否有效。

你可以在 Vault 参考文档中找到有关 Vault Transit 后端的更多详细信息。