Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅
中国的 Amazon Web Services 服务入门
(PDF)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
检索密钥值
使用密钥管理器IPC服务从核心设备上的密钥中检索机密值。您可以使用密钥管理器组件将加密密钥部署至核心设备。然后,您可以使用IPC操作来解密密密钥并在您的自定义组件中使用其值。
最低SDK版本
下表列出了从核心设备上的密钥中检索密钥值时必须使用的最低版本。 Amazon IoT Device SDK
授权
要在自定义组件中使用密钥管理器,必须定义授权策略,允许您的组件获取存储在核心设备上的密钥值。有关定义授权策略的信息,请参阅授权组件执行IPC操作。
密钥管理器授权策略具有以下属性。
IPC服务标识符:aws.greengrass.SecretManager
操作 |
描述 |
资源 |
aws.greengrass#GetSecretValue 或 *
|
允许组件获取在核心设备上加密的密钥值。
|
Secrets Manager 密钥ARN,或者用于* 允许访问所有密钥。
|
授权策略示例
您可以参考以下授权策略示例,帮助您为组件配置授权策略。
例 示例授权策略
以下示例授权策略允许组件获取核心设备上的任何密钥值。
我们建议在生产环境中缩小授权策略的范围,以便组件仅检索其使用的密钥。部署组件ARNs时,您可以将*
通配符更改为密钥列表。
{
"accessControl": {
"aws.greengrass.SecretManager": {
"com.example.MySecretComponent
:secrets:1": {
"policyDescription": "Allows access to a secret.",
"operations": [
"aws.greengrass#GetSecretValue"
],
"resources": [
"*"
]
}
}
}
}
GetSecretValue
获取您存储在核心设备上的密钥值。
此操作与 Secrets Manager 操作类似,您可以使用该操作来获取 Amazon Web Services 云中的密钥值。有关更多信息,请参阅 Amazon Secrets Manager API 参考中的 GetSecretValue。
请求
此操作的请求包含以下参数:
refresh
(Python:refresh
)
-
(可选):是否将请求的密钥与 Amazon Secrets Manager 服务中的最新值同步。
设置为 true 时,密钥管理器将请求 Amazon Secrets Manager 服务提供指定机密标签的最新值,并将该值作为响应返回。否则,将返回存储在本地的密钥值。
此参数不能与请求中的 versionId
参数一起使用。该参数与 Nucleus 2.13.0 及更高版本配合使用。
secretId
(Python:secret_id
)
-
密钥名称。您可以指定 Amazon 资源名称 (ARN) 或密钥的友好名称。
versionId
(Python:version_id
)
-
(可选)版本 ID。
您可指定 versionId
或 versionStage
。
若未指定 versionId
或 versionStage
,则此操作默认为带有 AWSCURRENT
标签的版本。
versionStage
(Python:version_stage
)
-
(可选)要获取的版本的暂存标签。
您可指定 versionId
或 versionStage
。
若未指定 versionId
或 versionStage
,则此操作默认为带有 AWSCURRENT
标签的版本。
响应
此操作的响应包含以下信息:
secretId
(Python: secret_id
)
-
密钥 ID。
versionId
(Python: version_id
)
-
此版本密钥 ID。
versionStage
(Python: version_stage
)
-
附加至此版本密钥的暂存标签列表。
secretValue
(Python:secret_value
)
-
此版本密钥值。该对象 SecretValue
包含以下信息。
secretString
(Python:secret_string
)
-
您以字符串形式提供给 Secrets Manager 的受保护密钥信息的解密部分。
secretBinary
(Python:secret_binary
)
-
(可选)您以字节数组形式作为二进制数据提供给 Secrets Manager 的受保护密钥信息的解密部分。此属性包含以 base64 编码字符串的字符串形式提供的二进制数据。
如果您在 Secrets Manager 控制台中创建密钥,则不会使用此属性。
示例
以下示例演示了如何在自定义组件代码中调用该操作。
- Java (IPC client V1)
-
例 示例:获取密钥值
package com.aws.greengrass.docs.samples.ipc;
import com.aws.greengrass.docs.samples.ipc.util.IPCUtils;
import software.amazon.awssdk.aws.greengrass.GetSecretValueResponseHandler;
import software.amazon.awssdk.aws.greengrass.GreengrassCoreIPCClient;
import software.amazon.awssdk.aws.greengrass.model.GetSecretValueRequest;
import software.amazon.awssdk.aws.greengrass.model.GetSecretValueResponse;
import software.amazon.awssdk.aws.greengrass.model.UnauthorizedError;
import software.amazon.awssdk.eventstreamrpc.EventStreamRPCConnection;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
public class GetSecretValue {
public static final int TIMEOUT_SECONDS = 10;
public static void main(String[] args) {
String secretArn = args[0];
String versionStage = args[1];
try (EventStreamRPCConnection eventStreamRPCConnection =
IPCUtils.getEventStreamRpcConnection()) {
GreengrassCoreIPCClient ipcClient =
new GreengrassCoreIPCClient(eventStreamRPCConnection);
GetSecretValueResponseHandler responseHandler =
GetSecretValue.getSecretValue(ipcClient, secretArn, versionStage);
CompletableFuture<GetSecretValueResponse> futureResponse =
responseHandler.getResponse();
try {
GetSecretValueResponse response = futureResponse.get(TIMEOUT_SECONDS, TimeUnit.SECONDS);
response.getSecretValue().postFromJson();
String secretString = response.getSecretValue().getSecretString();
System.out.println("Successfully retrieved secret value: " + secretString);
} catch (TimeoutException e) {
System.err.println("Timeout occurred while retrieving secret: " + secretArn);
} catch (ExecutionException e) {
if (e.getCause() instanceof UnauthorizedError) {
System.err.println("Unauthorized error while retrieving secret: " + secretArn);
} else {
throw e;
}
}
} catch (InterruptedException e) {
System.out.println("IPC interrupted.");
} catch (ExecutionException e) {
System.err.println("Exception occurred when using IPC.");
e.printStackTrace();
System.exit(1);
}
}
public static GetSecretValueResponseHandler getSecretValue(GreengrassCoreIPCClient greengrassCoreIPCClient, String secretArn, String versionStage) {
GetSecretValueRequest getSecretValueRequest = new GetSecretValueRequest();
getSecretValueRequest.setSecretId(secretArn);
getSecretValueRequest.setVersionStage(versionStage);
return greengrassCoreIPCClient.getSecretValue(getSecretValueRequest, Optional.empty());
}
}
- Python (IPC client V1)
-
例 示例:获取密钥值
此示例假设您使用的是 Python v2 版本的 1.5.4 或更高版本。 Amazon IoT Device SDK
import json
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
GetSecretValueRequest,
GetSecretValueResponse,
UnauthorizedError
)
secret_id = 'arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-abcdef'
TIMEOUT = 10
ipc_client = awsiot.greengrasscoreipc.connect()
request = GetSecretValueRequest()
request.secret_id = secret_id
request.version_stage = 'AWSCURRENT'
operation = ipc_client.new_get_secret_value()
operation.activate(request)
future_response = operation.get_response()
response = future_response.result(TIMEOUT)
secret_json = json.loads(response.secret_value.secret_string)
# Handle secret value.
- JavaScript
-
例 示例:获取密钥值
import {
GetSecretValueRequest,
} from 'aws-iot-device-sdk-v2/dist/greengrasscoreipc/model';
import * as greengrasscoreipc from "aws-iot-device-sdk-v2/dist/greengrasscoreipc";
class GetSecretValue {
private readonly secretId : string;
private readonly versionStage : string;
private ipcClient : greengrasscoreipc.Client
constructor() {
this.secretId = "<define_your_own_secretId>"
this.versionStage = "<define_your_own_versionStage>"
this.getSecretValue().then(r => console.log("Started workflow"));
}
private async getSecretValue() {
try {
this.ipcClient = await getIpcClient();
const getSecretValueRequest : GetSecretValueRequest = {
secretId: this.secretId,
versionStage: this.versionStage,
};
const result = await this.ipcClient.getSecretValue(getSecretValueRequest);
const secretString = result.secretValue.secretString;
console.log("Successfully retrieved secret value: " + secretString)
} catch (e) {
// parse the error depending on your use cases
throw e
}
}
}
export async function getIpcClient(){
try {
const ipcClient = greengrasscoreipc.createClient();
await ipcClient.connect()
.catch(error => {
// parse the error depending on your use cases
throw error;
});
return ipcClient
} catch (err) {
// parse the error depending on your use cases
throw err
}
}
const getSecretValue = new GetSecretValue();
示例
使用以下示例来学习如何在组件中使用密钥管理器IPC服务。
此示例组件打印您部署至核心设备的密钥值。
此示例组件会打印密钥值,因此请仅将其与存储测试数据的密钥一起使用。不要使用此组件来打印存储重要信息的密钥值。
配方
以下示例配方定义了一个秘密ARN配置参数,并允许组件获取核心设备上任何密钥的值。
我们建议在生产环境中缩小授权策略的范围,以便组件仅检索其使用的密钥。部署组件ARNs时,您可以将*
通配符更改为密钥列表。
- JSON
-
{
"RecipeFormatVersion": "2020-01-25",
"ComponentName": "com.example.PrintSecret",
"ComponentVersion": "1.0.0",
"ComponentDescription": "Prints the value of an Amazon Secrets Manager secret.",
"ComponentPublisher": "Amazon",
"ComponentDependencies": {
"aws.greengrass.SecretManager": {
"VersionRequirement": "^2.0.0",
"DependencyType": "HARD"
}
},
"ComponentConfiguration": {
"DefaultConfiguration": {
"SecretArn": "",
"accessControl": {
"aws.greengrass.SecretManager": {
"com.example.PrintSecret:secrets:1": {
"policyDescription": "Allows access to a secret.",
"operations": [
"aws.greengrass#GetSecretValue"
],
"resources": [
"*"
]
}
}
}
}
},
"Manifests": [
{
"Platform": {
"os": "linux"
},
"Lifecycle": {
"install": "python3 -m pip install --user awsiotsdk",
"Run": "python3 -u {artifacts:path}/print_secret.py \"{configuration:/SecretArn}\""
}
},
{
"Platform": {
"os": "windows"
},
"Lifecycle": {
"install": "py -3 -m pip install --user awsiotsdk",
"Run": "py -3 -u {artifacts:path}/print_secret.py \"{configuration:/SecretArn}\""
}
}
]
}
- YAML
-
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PrintSecret
ComponentVersion: 1.0.0
ComponentDescription: Prints the value of a Secrets Manager secret.
ComponentPublisher: Amazon
ComponentDependencies:
aws.greengrass.SecretManager:
VersionRequirement: "^2.0.0"
DependencyType: HARD
ComponentConfiguration:
DefaultConfiguration:
SecretArn: ''
accessControl:
aws.greengrass.SecretManager:
com.example.PrintSecret:secrets:1:
policyDescription: Allows access to a secret.
operations:
- aws.greengrass#GetSecretValue
resources:
- "*"
Manifests:
- Platform:
os: linux
Lifecycle:
install: python3 -m pip install --user awsiotsdk
Run: python3 -u {artifacts:path}/print_secret.py "{configuration:/SecretArn}"
- Platform:
os: windows
Lifecycle:
install: py -3 -m pip install --user awsiotsdk
Run: py -3 -u {artifacts:path}/print_secret.py "{configuration:/SecretArn}"
构件
以下示例 Python 应用程序演示了如何使用密钥管理器IPC服务在核心设备上获取密钥的值。
import concurrent.futures
import json
import sys
import traceback
import awsiot.greengrasscoreipc
from awsiot.greengrasscoreipc.model import (
GetSecretValueRequest,
GetSecretValueResponse,
UnauthorizedError
)
TIMEOUT = 10
if len(sys.argv) == 1:
print('Provide SecretArn in the component configuration.', file=sys.stdout)
exit(1)
secret_id = sys.argv[1]
try:
ipc_client = awsiot.greengrasscoreipc.connect()
request = GetSecretValueRequest()
request.secret_id = secret_id
operation = ipc_client.new_get_secret_value()
operation.activate(request)
future_response = operation.get_response()
try:
response = future_response.result(TIMEOUT)
secret_json = json.loads(response.secret_value.secret_string)
print('Successfully got secret: ' + secret_id)
print('Secret value: ' + str(secret_json))
except concurrent.futures.TimeoutError:
print('Timeout occurred while getting secret: ' + secret_id, file=sys.stderr)
except UnauthorizedError as e:
print('Unauthorized error while getting secret: ' + secret_id, file=sys.stderr)
raise e
except Exception as e:
print('Exception while getting secret: ' + secret_id, file=sys.stderr)
raise e
except Exception:
print('Exception occurred when using IPC.', file=sys.stderr)
traceback.print_exc()
exit(1)
使用量
您可以将此示例组件与密钥管理器组件一起使用,在核心设备上部署和打印密钥值。
创建、部署和打印测试密钥
-
使用测试数据创建 Secrets Manager 密钥。
- Linux or Unix
-
aws secretsmanager create-secret \
--name MyTestGreengrassSecret \
--secret-string '{"my-secret-key": "my-secret-value"}'
- Windows Command Prompt (CMD)
-
aws secretsmanager create-secret ^
--name MyTestGreengrassSecret ^
--secret-string '{"my-secret-key": "my-secret-value"}'
- PowerShell
-
aws secretsmanager create-secret `
--name MyTestGreengrassSecret `
--secret-string '{"my-secret-key": "my-secret-value"}'
保存密钥以便在以下步骤中使用。ARN
有关更多信息,请参阅《Amazon Secrets Manager 用户指南》中的创建密钥。
-
使用以下配置合并更新部署密钥管理器组件 (aws.greengrass.SecretManager
)。指定您之前创建ARN的密钥。
{
"cloudSecrets": [
{
"arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-abcdef
"
}
]
}
有关更多信息,请参阅将 Amazon IoT Greengrass 组件部署至设备或 Greengrass 部署命令CLI。
-
使用以下配置合并更新创建和部署本节中的示例组件。指定您之前创建ARN的密钥。
{
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret
",
"accessControl": {
"aws.greengrass.SecretManager": {
"com.example.PrintSecret:secrets:1": {
"policyDescription": "Allows access to a secret.",
"operations": [
"aws.greengrass#GetSecretValue"
],
"resources": [
"arn:aws:secretsmanager:us-west-2:123456789012:secret:MyTestGreengrassSecret-abcdef
"
]
}
}
}
}
有关更多信息,请参阅 创建 Amazon IoT Greengrass 组件
-
查看 Amazon IoT Greengrass 核心软件日志以验证部署是否成功,并查看com.example.PrintSecret
组件日志以查看打印的密钥值。有关更多信息,请参阅 监控 Amazon IoT Greengrass 日志。