Integrated Software for ZFS ZS3-x Arrays
 
Integrated Software for ZFS ZS5-x Arrays
 
Integrated Software for ZFS 7xx0 Arrays
 
Oracle Key Manager
 
Integrated Software for ZFS ZS4-x Arrays
 

PLA-Support>Sun Systems>DISK>ZFS Storage>SN-DK: ZS
 

Understanding how add the ZFS Appliance as an Agent to OKM/KMA/KMS
How to configure ZFS Appliance to use OKM encryption on shares.

In this Document

Goal

Solution

Purpose

Scope

Details

Creating Keys:

Now you can create encrypted shares using the key created from above.

<Internal_Only>

Internal only troubleshooting section:

</Internal_Only>

References

Applies to:

Goal

 Provide steps needed to enroll ZFSSA as agent of OKM.

Solution

Purpose

Below you will find the needed steps to configure your ZFS-SA to be used with OKM.

This will include standalone ZFS-SAs as well as clustered ZFS-SAs.

Scope

This document should assist both the ZFS-SA administrators as well as OKM administrators.

This document does not describe how to configure KMA's using the OKM GUI, only creating Agents related to ZFS-SA.

Details

Items you will need to know:

1. The IP address of the service network interface of the KMA (Key Management Appliance) you will enroll the ZFS-SA into.
2. If there is any firewall between the ZFS-SA & KMA the following port need to be opened (3331, 3332, 3334, 3335).
3. If on different subnets the router/routing will need to be configured.
   
   From the CLI on the appliance you can confirm ports are open using below command for each port listed above.
   ZFFS5-1:> confirm shell nc -v 10.80.53.175 3331
   Connection to 10.80.53.175 3331 port [tcp/*] succeeded!
   A failure will look like this or time out if connection can not be made
   ZFS5-1:> confirm shell nc -v 10.80.53.175 3339
   nc: connect to 10.80.53.175 port 3339 [host 10.80.53.175] (tcp) failed: Connection refused
    

The KMA should already be configured with Key Policies, Key Groups and Sites if they are to be used.
The OKM administrator should create a new agent using the OKM GUI.  By default the "Use one time passphrase" is checked, make sure to uncheck it.

To configure the appliance use the BUI or CLI.
From CLI go to:
shares -> encrtiption -> okm

 
Set the following fields

From the BUI click on Shares then Encryption then OKM.

Populate the 3 fields below, then click apply.
   agent_id This much match the Agent in the OKM GUI.
   registration_pin is the PassPhrase used when creating the agent in the OKM GUI.
   server_addr is IP address of KMA's ServiceNetwork Interface of the KMA you are Enrolling on.
  

After successful enrollment, the OKM GUI should show the agent as enrolled.

Creating Keys:

After enrollment is complete you must create keys to be used when you create a share.
From the CLI go to shares -> encryption -> okm -> keys.
The only cipher for OKM is AES, no need to set this property.
ZFS5-1:shares (pool-1) encryption okm keys> create
ZFS5-1:shares (pool-1) encryption okm keys> set keyname=<KEY-NAME>
ZFS5-1:shares (pool-1) encryption okm keys> commit

From the BUI click on Shares then Encryption then OKM then + next to keys

The key will be generated on the OKM/KMA with the Data unit name from above.

Now you can create encrypted shares using the key created from above.

ZFS5-1:> shares select <PROJECT>
ZFS5-1:> filesystem <NAME>
ZFS5-1:> set encryption=aes-256-gcm
ZFS5-1:> set keystore=OKM
ZFS5-1:> set keyname=<KEY-NAME>
Below steps are optional and should be set to values per your site.
ZFS5-1:> set share<nfs|smb|dav|ftp|sftp|tftp>=rw/ro....
ZFS5-1:> set root_permissions=777.....
ZFS5-1:> commit

Keys will be requested each time the filesystem needs to be mounted.

Only one KMA IP address was entered, however during the enrollment process the ZFS-SA will learn and store the IP address of other KMA's in the OKM cluster.

This is for failover purposes when one KMA is down the ZFS-SA will failover to another KMA in the cluster.

Internal only troubleshooting section:

After a successful enrollment in /var/ak/keystores/OKM/ you will find the following files and a directory with the Agent name.
If enrollment is failing the KMSAgentLog.log file will be present and should provide clues for failure.
# ls
KMSAgentLog.log ZFS5-1 kmstoken.cfg objlabels.lst
The KMSAgentLog.log contains failures of one type or another and you will most likely see SOAP errors, those are generally related to network issues, unable to connect to KMA.
The objlabels.lst is a file that contains the key wrap key names.
The kmstoken.cfg file contains the Agent name used to enroll into the KMA and the IP of the KMA and some timeout failover values.

The <Agetn-Name-Directory> contains the following files
# ls
ca.crt clientkey.p12 cluster.cfg profile.cfg
The ca.crt is the certificate used to communicate with the KMA, that will be the same on both heads in a cluster.
The clientkey.pXX is the binary key.
The cluster.cfg file contains the information about the KMAs in the OKM cluster like (KMA-Name, SiteID, KMA-Build, KMA-IP..).
The profile.cfg contains information about the ZFSSA agent and what ports it uses to talk to the KMAs, fail-over timeouts and limits.

You can verify connectivity from the ZFSSA to the KMA using netcat, verify each port number found in profile.cfg above.
# nc -v 10.80.53.175 3331
Connection to 10.80.53.175 3331 port [tcp/*] succeeded!
A failure look like this or will just hang or time out if a connection can not be made.
# nc -v 10.80.53.175 3331
nc: connect to 10.80.53.175 port 3331 [host 10.80.53.175] (tcp) failed: Connection refused

The customer can also provide you a system dump from the KMA, similar to our bundle.
or at least have the customer look through the audit event list on the OKM GUI
The auditevent list will be the log containing all information about what connection have been made to the KMA and success/failures.

Now about the stash object:
There is a stash object for OKM encryption, it is located at
/var/ak/stash/com/sun/ak/xmlrpc/keystore/
You will need to determine which is your OKM stash as SFTP, Local and other encryption keystores are here.
You can use the down and dirty aknv -r like below to quickly find the OKM stash object.
# aknv -r */obj | grep OKM
426d87d2-7dab-4bfa-ea0b-e63e7fa14252/obj: name = OKM
426d87d2-7dab-4bfa-ea0b-e63e7fa14252/obj: path = /var/ak/keystores/OKM

From aksh CLI you can use below raw commands to display extra information:
zs4-4-:raw> keystore.getKeys('OKM')
result = [{
expire: Thu Jan 01 1970 00:00:00 GMT+0000 (UTC),
modified: Fri Jul 28 2017 19:30:56 GMT+0000 (UTC),
keyname: 'OKM-Test1',
comment: '',
cipher: 'AES',
user: '',
key: ''
}]
zs4-4-brm06-a-0:raw> keystore.getProfile('OKM')
result = {
ciphers: ['AES'],
format: 'okm',
type: 2
}
zs4-4:raw> keystore.getConfigProps("OKM")
result = {
server_addr: '10.10.10.175',
registration_pin: 'xxxxxxxxxx',
agent_id: 'zs4-4-brm06-a'
}

It is difficult to change the pass_phrase on the ZFSSA, see Bug 21569401 - Cannot change OKM registration PIN after creating keys for encrypted shares.
However, the below work around steps can be used to accomplish this.
1. First change the agent passphrase on the KMA to the desired pass_phrase for the agent, our example was set to "test1234!".
Use below command to get current values set:
zs5-4:> raw
zs5-4:raw> keystore.getConfigProps('OKM')
result = {
agent_id: 'zs5-4-brm06-b',
registration_pin: '$upport1',
server_addr: '10.80.53.175'
}
2. Then, on the ZFSSA, manually use the raw command to set the values for the configuration, but you must use the wrong IP address so that the configuration is not valid:
zs5-4:raw> keystore.setConfigProps('OKM', [{name: 'server_addr', value: '10.80.53.1'},{name: 'registration_pin', value: 'test1234!'},{name: 'agent_id', value: 'zs5-4-brm06-b'}])
result = 0
3. Then, update the configuration using raw command:
zs5-4:raw> keystore.updateConfig('OKM')
exception = {
faultMethod: 'keystore.updateConfig',
faultString: '{txtid: "AKTXT_XMLRPC_KEYSTORE_BADPROFILE", args: ["OKM"]}',
faultData: {
args: ['OKM'],
txtid: 'AKTXT_XMLRPC_KEYSTORE_BADPROFILE'
},
faultCode: 598
}
This will actually clear out the /var/ak/keystores/OKM/<agent_id> directory.
4. Then, set the configuration manually again, but this time use the correct IP and pass_phrase that was set in step 1:
zs5-4:raw> keystore.setConfigProps('OKM', [{name: 'server_addr', value: '10.80.53.175'},{name: 'registration_pin', value: 'test1234!'},{name: 'agent_id', value: 'zs5-4-brm06-b'}])
result = 0
5. Update the configuration again. This will recreate the /var/ak/keystores/OKM/<agent_id> using new certificates.
zs5-4:raw> keystore.updateConfig('OKM')
result = 0

References

This solution has no attachment