Oracle^® ZFS Storage Appliance RESTful API 指南，发行版 OS8.8.x

管理加密密钥

Oracle ZFS Storage Appliance 为池、项目和单个共享资源（文件系统和 LUN）提供透明数据加密。该设备包括内置本地密钥库，还支持 Oracle Key Manager (OKM) 和密钥管理互操作性协议 (Key Management Interoperability Protocol, KMIP) 加密。每个加密的项目或共享资源都需要一个来自本地、OKM 或 KMIP 密钥库的包装密钥。数据加密密钥由存储设备管理，并使用包装密钥永久加密存储。

必须先创建加密密钥，然后才能创建加密池、项目或共享资源。

• 由于必须先配置密钥库，然后再创建池，因此不能在进行初始系统配置时或在恢复出厂设置后创建加密池。

• 在为加密池中的共享资源或项目设置复制之前，请确保在源上使用的加密密钥在目标上也可用。

下表介绍了可用于管理加密密钥的 RESTful API 请求。在该表中，keystore 的值为 local、okm 或 kmip。key 的值为 keyname 属性的值。列出加密密钥中介绍了密钥属性。

表 67  加密密钥操作

请求 附加到路径 /api/storage/v{1|2} 说明 GET /encryption/keystore 列出所有 keystore 属性。 PUT /encryption/keystore 修改 keystore 属性。 GET /encryption/keystore/keys 列出所有 keystore 密钥。 GET /encryption/keystore/keys/key 获取有关指定密钥的详细信息。 POST /encryption/keystore/keys 创建密钥。 DELETE /encryption/keystore/keys/key 销毁密钥。 GET /encryption/keystore/keys/key/dependents 列出依赖于此密钥的共享资源

配置本地密钥库

要配置本地密钥库，请设置主密码短语。对于本地密钥库，master_passphrase 是唯一可以列出或修改的属性。

检查是否设置了 master_passphrase：

GET /api/storage/v2/encryption/local HTTP/1.1 

输出：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "keystore": {
        "href": "/api/storage/v2/encryption/local",
        "master_passphrase": false,
        "keys": []
    }
}

为 master_passphrase 指定值：

PUT /api/storage/v2/encryption/local HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json
Accept: application/json

{
    "master_passphrase": "passphrase"
}

确认是否设置了 master_passphrase：

GET /api/storage/v2/encryption/local HTTP/1.1

输出：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "keystore": {
        "href": "/api/storage/v2/encryption/local",
        "master_passphrase": true,
        "keys": []
    }
}

配置 OKM 密钥库

下表介绍了配置 OKM 密钥库时必须设置的属性。

表 68  OKM 密钥库属性

属性 类型 说明 agent_id string 代理 ID。 registration_pin string 此值由 OKM 安全官提供。 server_addr string OKM 服务器的 IP 地址。

检查是否设置了上面的属性：

GET /api/storage/v2/encryption/okm HTTP/1.1 

输出：

HTTP/1.1 200 OK
Content-Type: application/json

{
    "keystore": {
        "href": "/api/storage/v2/encryption/okm",
        "agent_id": "",
        "registration_pin": false,
        "server_addr": "",
        "keys": []
    }
}

为 agent_id、registration_pin 和 server_addr 指定值：

PUT /api/storage/v2/encryption/okm HTTP/1.1
Host: zfs-storage.example.com:215
Content-Type: application/json
Accept: application/json

{
    "agent_id": "agent-id",
    "registration_pin": "reg-pin",
    "server_addr": "ipaddr"
}

配置 KMIP 密钥库

KMIP 密钥库与符合 KMIP 的服务器（包括 Oracle Key Vault）结合使用。Oracle Key Vault 是一个安装在专用服务器上的软件设备，支持 OASIS KMIP 标准。

要使用 KMIP 配置加密，请上载从 KMIP 管理员收到的密钥和证书，如上载密钥或证书中所述。

上载密钥和证书后，指定 KMIP 服务器、客户机证书和密钥名称。

下表介绍了配置 KMIP 密钥库时要设置的属性。

表 69  KMIP 密钥库属性

属性 类型 说明 server_list list KMIP 服务器的 IP 地址或主机名。此属性可以有多个值。 client_cert string 从 KMIP 服务器管理员提供的文件创建的证书。 host_match boolean 根据服务器证书中的服务器身份验证服务器主机名。 destroy_key_on_remove boolean 删除设备上的密钥时，销毁或保留 KMIP 服务器上的密钥。

有关 host_match 和 destroy_key_on_remove 的更多信息，请参见Oracle ZFS Storage Appliance 管理指南，发行版 OS8.8.x中的“密钥管理互操作性协议 (Key Management Interoperability Protocol, KMIP) 密钥库”。

检查是否设置了上面的属性：

GET /api/storage/v2/encryption/kmip HTTP/1.1 

输出：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "keystore": {
    "href": "/api/storage/v2/encryption/kmip",
    "server_list": [
      "ipaddr-or-hostname"
    ],
    "client_cert": "134a9138-29a0-4720-80bb-ec2b13457c39",
    "host_match": false,
    "destroy_key_on_remove": true,
    "keys": [],
... detailed information about the private key, certificate, and certificate authority ...
  }
}

创建加密密钥

配置密钥库后，要创建密钥，只需设置密钥名称。以下示例创建一个新的 KMIP 密钥。有关示例结果，请参见列出加密密钥。

请求示例：

POST /api/storage/v2/encryption/kmip/keys HTTP/1.1 
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Content-Type: application/json
Accept: application/json
{
        "keyname": "atz-1-27-2021"
}

列出加密密钥

此命令列出所有加密密钥的属性。命令成功执行后，将返回 HTTP 状态 200 (OK)。HTTP 正文包含 JSON 格式的密钥数组。下表介绍了加密密钥属性。

表 70  加密密钥属性

属性 类型 说明 cipher string AES 加密类型。 key string （仅限本地）十六进制编码的原始 256 位密钥，以加密形式存储。如果未指定值，则会自动生成此值。 keyname string 特定密钥。 href string 密钥的路径。

以下示例列出所有本地、OKM 和 KMIP 密钥。

请求示例：

GET /api/storage/v2/encryption/local/keys /api/storage/v2/encryption/okm/keys /api/storage/v2/encryption/kmip/keys HTTP/1.1

结果示例：

此结果表明此设备上不存在本地或 OKM 密钥，存在一个 KMIP 密钥。

{
    "keys": {
    }
}
{
    "keys": {
    }
}
{
    "keys": [{
        "cipher": "AES",
        "keyname": "atz-1-27-2021",
        "href": "/api/storage/v2/encryption/kmip/keys/key-000"
    }]
}

列出使用指定密钥加密的存储

dependents 查询列出使用指定密钥加密的任何共享资源、项目或池。

以下示例显示，仅默认池中的文件系统 fs-enc 使用 atz-1-27-2021 KMIP 密钥进行了加密。

请求示例：

GET /api/storage/v2/encryption/kmip/keys/atz-1-27-2021/dependents HTTP/1.1

结果示例：

{
  "dependents": [
    "pool-0/local/default/fs-enc"
  ]
}

删除密钥

要删除密钥，请使用密钥的 href 属性值（而非密钥名称）。成功删除后将返回 HTTP 状态 204 (No Content)。

删除密钥后，使用该密钥的所有池和共享资源中的所有数据都将变得无法访问。这相当于永久性安全销毁数据且此操作不可撤消，除非已经准备通过备份密钥来执行密钥恢复。

请求示例：

DELETE /api/storage/v2/encryption/kmip/keys/key-000 HTTP/1.1
Host: zfs-storage.example.com:215
Accept: application/json