支持 Vault 的秘密引擎
Spring Vault 提供了多种扩展来支持 Vault 的各种秘密引擎。
具体来说,Spring Vault 提供了以下秘密引擎的扩展:
-
Transform(转换)(企业版功能)
-
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)
你可以在 Vault 参考文档中找到有关 Vault Transit 后端的更多详细信息。