密码学组件规范
与Dapr接口兼容的密码学组件
Table headers to note:
| Header | Description | Example |
|---|
| Status | Component certification status | Alpha
Beta
Stable
|
| Component version | The version of the component | v1 |
| Since runtime version | The version of the Dapr runtime when the component status was set or updated | 1.11 |
Using the Dapr cryptography engine
Microsoft Azure
| Component | Status | Component version | Since runtime version |
|---|
| Azure Key Vault | Alpha | v1 | 1.11 |
1 - Azure Key Vault
Azure Key Vault 加密组件的详细信息
组件格式
一个 Dapr crypto.yaml 组件文件具有以下结构：
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: azurekeyvault
spec:
type: crypto.azure.keyvault
metadata:
- name: vaultName
value: mykeyvault
# 请参阅下文的身份验证部分以了解所有配置选项
- name: azureTenantId
value: ${{AzureKeyVaultTenantId}}
- name: azureClientId
value: ${{AzureKeyVaultServicePrincipalClientId}}
- name: azureClientSecret
value: ${{AzureKeyVaultServicePrincipalClientSecret}}
警告
上述示例中使用了明文字符串来表示密钥。建议使用密钥存储来保护密钥，详情请参阅
此处。
通过 Microsoft Entra ID 进行身份验证
Azure Key Vault 加密组件仅支持通过 Microsoft Entra ID 进行身份验证。在启用此组件之前：
- 阅读 Azure 身份验证 文档。
- 创建一个 Microsoft Entra ID 应用程序（也称为服务主体）。
- 或者，为您的应用程序平台创建一个 托管身份。
元数据字段说明
| 字段 | 必需 | 详情 | 示例 |
|---|
vaultName | 是 | Azure Key Vault 的名称 | "mykeyvault" |
| 身份验证元数据 | 是 | 更多信息请参阅 Azure 身份验证 | |
相关链接
2 - JSON Web Key Sets (JWKS)
JWKS 加密组件的详细信息
组件格式
该组件用于从 JSON Web Key Set (RFC 7517) 中加载密钥。JSON Web Key Set 是包含一个或多个密钥的 JSON 文档，密钥以 JWK (JSON Web Key) 格式表示；这些密钥可以是公钥、私钥或共享密钥。
该组件支持从以下来源加载 JWKS：
- 本地文件；在这种情况下，Dapr 会监视文件的变化并自动重新加载。
- HTTP(S) URL，定期刷新。
- 通过
jwks 元数据属性直接传递实际的 JWKS，作为字符串（可以选择使用 base64 编码）。
注意
此组件使用 Dapr 的加密引擎来执行操作。虽然密钥不会直接暴露给您的应用程序，但 Dapr 可以访问原始密钥数据。一个 Dapr crypto.yaml 组件文件的结构如下：
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: jwks
spec:
type: crypto.dapr.jwks
version: v1
metadata:
# 示例 1：从文件加载 JWKS
- name: "jwks"
value: "fixtures/crypto/jwks/jwks.json"
# 示例 2：从 HTTP(S) URL 加载 JWKS
# 仅 "jwks" 是必需的
- name: "jwks"
value: "https://example.com/.well-known/jwks.json"
- name: "requestTimeout"
value: "30s"
- name: "minRefreshInterval"
value: "10m"
# 示例 3：直接包含实际的 JWKS
- name: "jwks"
value: |
{
"keys": [
{
"kty": "RSA",
"use": "sig",
"kid": "…",
"n": "…",
"e": "…",
"issuer": "https://example.com"
}
]
}
# 示例 3b：包含 base64 编码的 JWKS
- name: "jwks"
value: |
eyJrZXlzIjpbeyJ…
警告
上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保护密钥，详情请参阅
此处。
规格元数据字段
| 字段 | 必需 | 详情 | 示例 |
|---|
jwks | 是 | JWKS 文档的路径 | 本地文件: "fixtures/crypto/jwks/jwks.json"
HTTP(S) URL: "https://example.com/.well-known/jwks.json"
嵌入的 JWKS: {"keys": […]} (可以是 base64 编码) |
requestTimeout | 否 | 从 HTTP(S) URL 获取 JWKS 文档时的网络请求超时时间，格式为 Go duration。默认值: “30s” | "5s" |
minRefreshInterval | 否 | 从 HTTP(S) 源刷新 JWKS 文档前的最小等待时间，格式为 Go duration。默认值: “10m” | "1h" |
相关链接
加密构建块
3 - Kubernetes Secrets
关于Kubernetes secret加密组件的详细信息
组件格式
此组件旨在加载以密钥名称命名的Kubernetes secret。
注意
此组件依赖于Dapr的加密引擎进行操作。虽然密钥不会直接暴露给您的应用程序，但Dapr可以访问原始密钥材料。一个Dapr crypto.yaml组件文件的结构如下：
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <NAME>
spec:
type: crypto.dapr.kubernetes.secrets
version: v1
metadata:[]
警告
上述示例中使用了明文字符串形式的secrets。建议使用secret存储来保存secrets，具体方法请参见
此处。
规格元数据字段
| 字段 | 必需 | 详情 | 示例 | |
|---|
defaultNamespace | 否 | 用于检索secrets的默认命名空间。如果未设置，必须为每个密钥指定命名空间，例如namespace/secretName/key | "default-ns" | |
kubeconfigPath | 否 | kubeconfig文件的路径。如果未指定，组件将使用默认的集群内配置 | "/path/to/kubeconfig" | |
相关链接
加密构建块
4 - 本地存储
本地存储加密组件的详细信息
组件格式
该组件用于从本地目录加载密钥。
组件接受文件夹名称作为输入，并从该文件夹加载密钥。每个密钥存储在单独的文件中，当用户请求某个名称的密钥时，Dapr 会加载对应名称的文件。
支持的文件格式：
- 包含公钥和私钥的 PEM（支持：PKCS#1, PKCS#8, PKIX）
- 包含公钥、私钥或对称密钥的 JSON Web Key (JWK)
- 对称密钥的原始密钥数据
注意
此组件使用 Dapr 的加密引擎进行操作。尽管密钥从未直接暴露给您的应用程序，但 Dapr 可以访问原始密钥数据。一个 Dapr crypto.yaml 组件文件的结构如下：
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: mycrypto
spec:
type: crypto.dapr.localstorage
metadata:
version: v1
- name: path
value: /path/to/folder/
警告
上述示例中使用了明文字符串作为密钥。建议使用密钥存储来保存密钥，具体方法请参见
此处。
规格元数据字段
| 字段 | 必需 | 详情 | 示例 |
|---|
path | Y | 包含要加载的密钥的文件夹。加载密钥时，密钥的名称将用作此文件夹中文件的名称。 | /path/to/folder |
示例
假设您设置了 path=/mnt/keys，其中包含以下文件：
/mnt/keys/mykey1.pem/mnt/keys/mykey2
使用组件时，您可以将密钥引用为 mykey1.pem 和 mykey2。
相关链接
加密构建块