为可变通用容器资源添加支持¶
关联的 Launchpad 蓝图的 URL
https://blueprints.launchpad.net/barbican/+spec/api-containers-add-put
“通用”容器类型的最初意图是支持收集和引用任意密钥，类似于文件系统文件夹。因此，已经创建的“通用”容器在事后更改此集合是有意义的。此蓝图详细介绍了此 API 的外观。
问题描述¶
当前 Barbican 允许通过 POST 调用创建“通用”类型的容器，但一旦创建该容器，就无法修改它以更改其包含的密钥。 “通用”容器旨在成为收集相关密钥的一种便捷方式，因此应允许在创建后对其进行修改。
例如，持续集成和部署系统可能希望收集给定环境的所有密钥，例如数据库密码和访问令牌，以便在稍后在环境中创建服务器时由自动化脚本使用。如果每个环境都可以拥有自己的 Barbican 容器，自动化脚本可以引用该容器以检索密钥（通过其固定的密钥名称）作为启动该环境中服务器的一部分，这将非常方便。如果稍后密钥被轮换或更新，则可以在容器中更新给定密钥名称的密钥引用，而无需更新自动化脚本。
尝试更新其他类型的容器将被拒绝。
提议的变更¶
此蓝图要求为通用容器添加新的子资源。API 影响部分详细介绍了这些调用相对于客户端的外观。实际的服务实现很简单，允许客户端通过向“通用”容器中的子资源发送 POST 或 DELETE 请求来提供额外的密钥或删除单个密钥。
备选方案¶
先前接受但未实现的此蓝图的版本要求为容器添加 PUT 支持，客户端必须指定要保存在容器中的所有密钥。例如，在向现有容器添加密钥时，PUT 主体必须列出所有现有密钥以及新密钥。但是，在 Newton 周期中，我们讨论了这可能由于潜在的竞争条件而容易出错。
使用 PATCH 调用提供对容器的局部更新。这会增加 API 处理的复杂性，尤其是如果使用 JSONPatch [1]。如果认为此功能是必要的，则应将其作为单独的蓝图提出。
数据模型影响¶
无。
REST API 影响¶
以下文档指定了建议的容器子资源调用，用于从现有的“通用”类型容器中添加或删除密钥。
此调用的访问策略类似于容器资源的 POST 调用，因此具有 Barbican “管理员”或“创建者”角色的用户可以修改容器。
POST /v1/containers/{container_uuid}/secrets¶
将密钥添加到现有容器。仅支持通用容器。
请求属性¶
名称 |
类型 |
描述 |
|---|---|---|
name |
string |
(可选) 用于在容器内标识密钥的可读名称。 |
secret_ref |
uri |
(必需) 现有密钥的完整 URI 引用。 |
请求：¶
POST /v1/containers/{container_uuid}/secrets
Headers:
X-Project-Id: {project_id}
Content:
{
"name": "private_key",
"secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
}
响应：¶
{
"container_ref": "https://{barbican_host}/v1/containers/{container_uuid}"
}
请注意，请求的“container_uuid”与响应中提供的“container_uuid”相同。
HTTP 状态码¶
通常，容器 POST 调用产生的错误代码也适用于此处，尤其是在可以提供的密钥引用方面。
代码 |
描述 |
|---|---|
201 |
容器成功更新 |
400 |
缺少 secret_ref |
401 |
无效的 X-Auth-Token 或令牌没有对此资源的权限 |
DELETE /v1/containers/{container_uuid}/secrets¶
从容器中删除密钥。仅支持通用容器。
请求：¶
DELETE /v1/containers/{container_uuid}/secrets
Headers:
X-Project-Id: {project_id}
Content:
{
"name": "private key",
"secret_ref": "https://{barbican_host}/v1/secrets/{secret_uuid}"
}
响应：¶
204 No Content
HTTP 状态码¶
代码 |
描述 |
|---|---|
204 |
成功从容器中删除密钥。 |
400 |
缺少 secret_ref |
401 |
无效的 X-Auth-Token 或令牌没有对此资源的权限 |
404 |
指定的 secret_ref 在容器中未找到。 |
替代方案¶
或者，我们可以将密钥的删除定义为对包含 secret_uuid 作为 URI 部分的资源的调用，例如
DELETE /v1/containers/{container_uuid}/secrets/{secret_uuid}
但是，这将要求客户端解析密钥 URI 中的 UUID，才能构造正确的删除 URI。由于此原因，应实现上面描述的带有主体的 DELETE。
安全影响¶
拟议的更改不会带来安全影响，因为 (1) 它不会改变底层密钥或其访问限制，并且 (2) 只有“通用”类型的容器可以被修改，因此敏感的分组密钥，例如“证书”和“非对称”类型的容器仍然是不可变的。请参阅性能影响部分，了解有关限制此类蓝图提出的调用的速率限制的建议，以避免拒绝服务攻击。
通知与审计影响¶
拟议的新 POST 和 DELETE 容器请求应像任何其他 Barbican REST 调用一样被记录和审计，因此不需要在此蓝图中专门指出。
其他最终用户影响¶
Barbican Python 客户端也需要进行修改。
性能影响¶
由于此蓝图不需要任何加密操作，并且仅更改了对密钥的数据库引用，因此该提案对性能的影响应该很小。但是，该调用本身没有配额限制，因此部署者可能希望在其 Barbican API 节点前面使用速率限制应用程序，例如 Repose [2]。
其他部署者影响¶
不需要任何配置或依赖项更改来使用建议的操作，但如上文性能影响部分所述，如果部署了速率限制，则应限制容器资源上的 PUT 操作，以避免拒绝服务攻击。
开发人员影响¶
无。
实现¶
负责人¶
- 主要负责人
待定
- 其他贡献者
待定
工作项¶
实施此蓝图需要以下工作项
更新容器控制器以添加新的 POST 和 DELETE 子资源。
在 etc/policy.json 中添加新的策略条目，用于新的操作
添加一个正向测试来修改“通用”类型的容器，并添加一个负向测试来证明非“通用”类型的容器无法被修改。
添加 Barbican Python 客户端对新功能的的支持。
为新的 POST 和 DELETE 操作添加 sphinx 文档。
依赖项¶
无。
测试¶
有关要测试的内容的详细信息，请参阅工作项部分。不需要特殊的第三方系统来测试建议的功能。
文档影响¶
有关要记录的内容的详细信息，请参阅工作项部分。
