1. Oracle ZFS Storage Appliance RESTful API Guide, Release OS8.8.x
  2. Storage Encryption
  3. Manage Encryption Keys

Manage Encryption Keys

Note:

Encryption is a licensed feature for certain models. For details, refer to the "Oracle Software License Agreement ("SLA") and Entitlement for Hardware Systems with Integrated Software Options" and the Licensing Information User Manual for the software release.

Oracle ZFS Storage Appliance offers transparent data encryption for pools, projects, and individual shares (filesystems and LUNs). The appliance includes a built-in Local keystore, and also supports Oracle Key Manager (OKM), and Key Management Interoperability Protocol (KMIP) encryption. Each encrypted project or share requires a wrapping key from the Local, OKM, or KMIP keystore. The data encryption keys are managed by the storage appliance and are stored persistently encrypted by the wrapping key.

The encryption key must be created before you can create an encrypted pool, project, or share.

  • Because the keystore must be configured before the pool is created, you cannot create an encrypted pool at initial system configuration or after factory reset.

  • Before setting up replication for a share or project in a encrypted pool, ensure that the encryption key used at the source is also available at the target.

The following table describes the RESTful API requests available to manage encryption keys. In the table, the value of keystore is local, okm, or kmip. The value of key is the value of the keyname property. Key properties are described in List Encryption Keys.

Table 14-2 Encryption Key Operations

Request Append to Path /api/storage/v{1|2} Description

GET

/encryption/keystore

List all keystore properties

PUT

/encryption/keystore

Modify keystore properties

GET

/encryption/keystore/keys

List all keystore keys

GET

/encryption/keystore/keys/key

Get details about the specified key

POST

/encryption/keystore/keys

Create a key

DELETE

/encryption/keystore/keys/key

Destroy a key

GET

/encryption/keystore/keys/key/dependents

List the shares that are dependent on this key

Configure a Local Keystore

To configure a Local keystore, set the master passphrase. For a Local keystore, master_passphrase is the only property that you can list or modify.

Check whether master_passphrase is set: 

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

Output:

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

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

Specify a value for 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"
}

Confirm that master_passphrase is set: 

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

Output:

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

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

Configure an OKM Keystore

The following table describes the properties that must be set to configure an OKM keystore.

Table 14-3 OKM Keystore Properties

Property Type Description

agent_id

string

Agent ID

registration_pin

string

This value is supplied by your OKM security officer

server_addr

string

IP address of your OKM server

Check whether the above properties are set:

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

Output:

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

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

Specify values for agent_id, registration_pin, and 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"
}

Configure a KMIP Keystore

The KMIP keystore is used in conjunction with KMIP-compliant servers, including Oracle Key Vault. Oracle Key Vault is a software appliance that is installed on a dedicated server and that supports the OASIS KMIP standard.

To configure encryption using KMIP, upload the key and certificates that you received from your KMIP administrator as described in Upload a Key or Certificate.

After you have uploaded the key and certificates, specify the KMIP server, client certificate, and a key name.

The following table describes the properties to set to configure a KMIP keystore.

Table 14-4 KMIP Keystore Properties

Property Type Description

server_list

list

IP address or host name of a KMIP server; this property can have multiple values

client_cert

string

Certificate that you created from files provided by your KMIP server administrator

host_match

boolean

Validate the server hostname against the server's identity in the server certificate

destroy_key_on_remove

boolean

Destroy or preserve a key on the KMIP server when that key is deleted key on the appliance

For more information about host_match and destroy_key_on_remove, see Key Management Interoperability Protocol (KMIP) Keystore in Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x.

Check whether the above properties are set:

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

Output:

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 ...
  }
}

Create an Encryption Key

After the keystore is configured, to create a key, simply set the key name. The following example creates a new KMIP key. See List Encryption Keys for example results.

Example Request:

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"
}

List Encryption Keys

This command lists the properties of all encryption keys. HTTP status 200 (OK) is returned for a successful command. The HTTP body contains an array of keys in JSON format. The following table describes encryption key properties.

Table 14-5 Encryption Key Properties

Property Type Description

cipher

string

AES encryption type

key

string

(Local only) Hex-encoded raw 256-bit key, stored in an encrypted form; this value is generated automatically if you do not specify a value

keyname

string

A specific key

href

string

The path to the key

The following example lists all Local, OKM, and KMIP keys.

Example Request:

GET /api/storage/v2/encryption/local/keys /api/storage/v2/encryption/okm/keys /api/storage/v2/encryption/kmip/keys HTTP/1.1
GET /api/storage/v2/encryption/local/keys /api/storage/v2/encryption/okm/keys HTTP/1.1
Host: zfs-storage.example.com:215
Authorization: Basic Tm8gcGVla2luZyE=
Accept: application/json

Example Result:

This result shows no Local or OKM keys exist on this Oracle ZFS Storage Appliance system, and one KMIP key exists.

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

List Storage that is Encrypted with the Specified Key

The dependents query lists any shares, projects, or pools that are encrypted with the specified key.

The following example shows that only filesystem fs-enc in the default pool is encrypted with the atz-1-27-2021 KMIP key.

Example Request:

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

Example Result:

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

Delete a Key

To delete a key, use the value of the href property of the key (not the key name). Successful deletion returns HTTP Status 204 (No Content).

When a key is deleted, all of the data in all of the pools and shares that use the key becomes inaccessible. This is equivalent to secure data destruction and is permanent and irrevocable unless you have prepared for key restoration by backing up the key.

Example Request:

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