Configuring KMIP Keystore Encryption (CLI)

To configure encryption using KMIP, upload the key and certificates, and specify the KMIP server.

Before You Begin

Before setting up KMIP keystore on clustered controllers, perform the following procedures:

For each cluster node, configure a private network resource that is able to reach the KMIP servers. This private network interface ensures that each cluster node can communicate with the KMIP server in case the data service network interfaces failover. For information about private resources, see Cluster Resource Management.
Appropriately configure a route to each KMIP server for the private network link. For information about route configuration, see Configuring Network Routing.

Caution:

Failure to meet these prerequisites results in service interruption during takeover and failback operations.

Go to configuration settings certificates system.
Upload the private key.
1. Copy the contents of the PEM-format file that contains the private key.
  
  For Oracle Key Vault, the key and certificates are contained in a jar file that you received from your Oracle Key Vault administrator. The private key file is the key.pem file.
2. Enter the import command. Paste the key as prompted.
```
hostname:configuration settings certificates system> import
("." to end)> -----BEGIN RSA PRIVATE KEY-----
...
("." to end)> -----END RSA PRIVATE KEY-----
("." to end)> .
```
3. Enter the list command.
  The system certificates table has a new row with a TYPE value of key.
```
hostname:configuration settings certificates system> list
CERT     TYPE SUBJECT COMMON NAME       ISSUER COMMON NAME        NOT AFTER
cert-001 key  RSA-2048
```
Upload the system certificate.
The system certificate is the PEM-format file that contains the client certificate for this system. For Oracle Key Vault, this is the cert.pem file.

Copy the contents of the certificate file, enter the import command, and paste the certificate.
```
hostname:configuration settings certificates system> import
("." to end)> -----BEGIN CERTIFICATE-----
...
("." to end)> -----END CERTIFICATE-----
("." to end)> .
```
Upload the trust anchor certificate.

The CA certificate is the issuer of the client certificate. For Oracle Key Vault, this is the CA.pem file.

If your KMIP deployment uses multiple CA certificates, repeat this step to upload each certificate, and set the services property to kmip. Multiple CA certificates might be necessary if the client certificate for Oracle ZFS Storage Appliance and the KMIP server certificate are issued from different CAs, or when there are intermediate CAs in the chain to the CA root certificate.
1. Enter the up trusted command.
2. Copy the contents of the certificate authority file, enter the import command, and paste the CA certificate.
  The trusted certificates table has a new row.
```
hostname:configuration settings certificates trusted> list
CERT     TYPE SUBJECT COMMON NAME       ISSUER COMMON NAME        NOT AFTER
cert-001 cert CA                        CA                        2022-8-11
```
3. Set the services property of the certificate to kmip.
```
hostname:configuration settings certificates trusted> select cert-001
hostname:configuration settings certificates cert-001> get services
                      services =
hostname:configuration settings certificates cert-001> set services=kmip
                      services = kmip (uncommitted)
hostname:configuration settings certificates cert-001> commit
hostname:configuration settings certificates cert-001> done
```

Go to shares encryption kmip.

hostname:shares encryption kmip> get
                   server_list =
                   client_cert =
                    host_match = true
         destroy_key_on_remove = true

Set client_cert to the certificate that you just uploaded.

By default, the list command lists KMIP servers. Use the list certs command to list available certificates.

hostname:shares encryption kmip> list certs
CERT     TYPE SUBJECT COMMON NAME       ISSUER COMMON NAME        NOT AFTER
cert-001 cert iogo7PmhIY                CA                        2023-1-25

Set the value of client_cert by using either the set command or the client_cert command.

hostname:shares encryption kmip> set client_cert=cert-001
hostname:shares encryption kmip> client_cert cert-001

For scripting, you need a persistent identifier for the certificate. Use the client_cert command with tab completion to list properties of certificates.

hostname:shares encryption kmip> client_cert tab
cert-001                        notafter
cert-002                        notbefore
comment                         sha1fingerprint
dns                             sha256fingerprint
ip                              subject_commonname
issuer_commonname               subject_countryname
issuer_countryname              subject_localityname
issuer_localityname             subject_organizationalunitname
issuer_organizationalunitname   subject_organizationname
issuer_organizationname         subject_stateorprovincename
issuer_stateorprovincename      type
key_bits                        uri
key_type                        uuid

Every certificate has a unique subject_commonname, so you can use the value of that property to set the client_cert property.

hostname:shares encryption kmip> client_cert subject_commonname=tab
                  ip-addr                         iogo7PmhIY
hostname:shares encryption kmip> client_cert subject_commonname=iogo7PmhIY
hostname:shares encryption kmip> get client_cert
                   client_cert = cert-001 (uncommitted)

Set server_list to the hostname or IP address of the KMIP server.
The recommended value for this property is the KMIP server's hostname. See the discussion of hostname validation in Key Management Interoperability Protocol (KMIP) Keystore.

If you specify an IP address, check with your KMIP server administrator regarding whether you need to include the port number.
```
hostname:shares encryption kmip> set server_list=kmip-server-hostname-or-IP-address
                   server_list = kmip-server-hostname-or-IP-address (uncommitted)
hostname:shares encryption kmip> commit
```
If you receive a warning that the server failed to validate in the certificate, check whether you specified the correct server hostname in server_list. If you specify an IP address for server_list, and the CA-signed certificate subject common name only has a domain name, then host validation for the certificate fails.

If you set the value of host_match to false, host validation is not performed, and security is weaker.
Verify the host_match and destroy_key_on_remove options.

By default, both of these options are true. See Key Management Interoperability Protocol (KMIP) Keystore for information about what these options do.

Give the key a name.

Create a key, and set the keyname property.

hostname:shares encryption kmip> keys
hostname:shares encryption keys> list
NAME     CREATED               CIPHER KEYNAME
hostname:shares encryption keys> create
hostname:shares encryption kmip key-000 (uncommitted)> set keyname=atz-1-27-2021
                       keyname = atz-1-27-2021 (uncommitted)
hostname:shares encryption kmip key-000 (uncommitted)> commit
hostname:shares encryption keys> list
NAME     CREATED               CIPHER KEYNAME
key-000  2021-1-27 07:14:31    AES    atz-1-27-2021

Optional: Identify pools, projects, and shares that are encrypted with this key.
To identify which pools, projects, and shares are encrypted with this key, start the process of deleting the key, but cancel the key delete operation after you view the list of data that will be affected. When you initiate deleting the key, a warning is displayed that all data that is encrypted with this key will become inaccessible. The warning displays a list of all pools, projects, and shares that are encrypted with this key. Enter n to cancel deleting the key.
```
hostname:shares encryption keys> destroy key-000
This key has the following dependents:
  pool-0/local/default/fs-enc
Destroying this key will render the data inaccessible. Are you sure? (Y/N) n
```