Encrypting ZFS File Systems

Encryption is the process where data is encoded for privacy and a key is needed by the data owner to access the encoded data. The benefits of using ZFS encryption are as follows:

ZFS encryption is integrated with the ZFS command set. Like other ZFS operations, encryption operations such as key changes and rekey are performed online.
You can use your existing storage pools as long as they are upgraded. You have the flexibility of encrypting specific file systems.
ZFS encryption is inheritable to descendent file systems. Key management can be delegated through ZFS delegated administration.
Data is encrypted using AES (Advanced Encryption Standard) with key lengths of 128, 192, and 256 in the CCM and GCM operation modes.
ZFS encryption uses the Oracle Solaris Cryptographic Framework, which gives it access to any available hardware acceleration or optimized software implementations of the encryption algorithms automatically.
Currently, you cannot encrypt the ZFS root file system or other OS components, such as the /var directory, even if it is a separate file system.

You can set an encryption policy when a ZFS file system is created, but the policy cannot be changed. For example, the tank/home/darren file system is created with the encryption property enabled. The default encryption policy is to prompt for a passphrase, which must be a minimum of 8 characters in length.

# zfs create -o encryption=on tank/home/darren
Enter passphrase for 'tank/home/darren': xxxxxxx
Enter again: xxxxxxxx

Confirm that the file system has encryption enabled. For example:

# zfs get encryption tank/home/darren
NAME              PROPERTY    VALUE        SOURCE
tank/home/darren  encryption  on           local

The default encryption algorithm is aes-128-ccm when a file system's encryption value is on.

A wrapping key is used to encrypt the actual data encryption keys. The wrapping key is passed from the zfs command, as in the above example when the encrypted file system is created, to the kernel. A wrapping key is either in a file (in raw or hex format) or it is derived from a passphrase.

The format and location of the wrapping key are specified in the keysource property as follows:

keysource=format,location

Format is one of the following:
- raw – The raw key bytes
- hex – A hexadecimal key string
- passphrase – A character string that generates a key
Location is one of the following:
- prompt – You are prompted for a key or a passphrase when the file system is created or mounted
- file:///filename – The key or a passphrase file location in a file system
- pkcs11 – A URI describing the location of a key or a passphrase in a PKCS#11 token
- https://location – The key or a passphrase file location on a secure server. Transporting key information in the clear using this method is not recommended. A GET on the URL returns just the key value or the passphrase, according to what was requested in the format part of the keysource property.
  
  When using an https:// locator for the keysource, the certificate that the server presents must be one that is trusted by libcurl and OpenSSL. Add your own trust anchor or self signed certificate to the certificate store in /etc/openssl/certs. Place the PEM format certificate into the /etc/certs/CA directory and run the following command:
```
# svcadm refresh ca-certificates
```

If the keysource format is passphrase, then the wrapping key is derived from the passphrase. Otherwise, the keysource property value points to the actual wrapping key, as raw bytes or in hexidecimal format. You can specify that the passphrase is stored in a file or stored in a raw stream of bytes that are prompted for, which is likely only suitable for scripting.

When a file system's keysource property values identifies passphrase, then the wrapping key is derived from the passphrase using PKCS#5 PBKD2 and a per file system randomly generated salt. This means that the same passphrase generates a different wrapping key if used on descendent file systems.

A file system's encryption policy is inherited by descendent file systems and cannot be removed. For example:

# zfs snapshot tank/home/darren@now
# zfs clone tank/home/darren@now tank/home/darren-new
Enter passphrase for 'tank/home/darren-new': xxxxxxx
Enter again: xxxxxxxx
# zfs set encryption=off tank/home/darren-new
cannot set property for 'tank/home/darren-new': 'encryption' is readonly

If you need to copy or migrate encrypted or unencrypted ZFS file systems, then consider the following points:

Currently, you cannot send an unencrypted dataset stream and receive it as an encrypted stream even if the receiving pool's dataset has encryption enabled.
You can use the following commands to migrate unencrypted data to a pool/file system with encryption enabled:
- cp -r
- find | cpio
- tar
- rsync
A replicated encrypted file system stream can be received into a encrypted file system and the data remains encrypted. For more information, see Example 5-4.

Changing an Encrypted ZFS File System's Keys

You can change an encrypted file system's wrapping key by using the zfs key -c command. The existing wrapping key must have been loaded first, either at boot time or by explicitly loading the file system key (zfs key -l) or by mounting the file system (zfs mount filesystem). For example:

# zfs key -c tank/home/darren
Enter new passphrase for 'tank/home/darren': xxxxxxxx
Enter again: xxxxxxxx

In the following example, the wrapping key is changed and the keysource property value is changed to specify that the wrapping key comes from a file.

# zfs key -c -o keysource=raw,file:///media/stick/key tank/home/darren

The data encryption key for an encrypted file system can be changed by using the zfs key -K command, but the new encryption key is only used for newly written data. This feature can be used to provide compliance with NIST 800-57 guidelines on a data encryption key's time limit. For example:

# zfs key -K tank/home/darren

In the above example, the data encryption key is not visible nor is it directly managed by you. In addition, you need the keychange delegation to perform a key change operation.

The following encryption algorithms are available:

aes-128-ccm, aes-192-ccm, aes-256-ccm
aes-128-gcm, aes-192-gcm, aes-256-gcm

The ZFS keysource property identifies the format and location of the key that wraps the file system's data encryption keys. For example:

# zfs get keysource tank/home/darren
NAME              PROPERTY   VALUE              SOURCE
tank/home/darren  keysource  passphrase,prompt  local

The ZFS rekeydate property identifies the date of the last zfs key -K operation. For example:

# zfs get rekeydate tank/home/darren
NAME              PROPERTY   VALUE                  SOURCE
tank/home/darren  rekeydate  Wed Jul 25 16:54 2012  local

If an encrypted file system's creation and rekeydate properties have the same value, the file system has never been rekeyed by an zfs key -K operation.

Managing ZFS Encryption Keys

ZFS encryption keys can be managed in different ways, depending on your needs, either on the local system or remotely, if a centralized location is needed.

Locally – The above examples illustrate that the wrapping key can be either a passphrase prompt or a raw key that is stored in a file on the local system.
Remotely – Key information can be stored remotely by using a centralized key management system like Oracle Key Manager or by using a web service that supports a simple GET request on an http or https URI. Oracle Key Manager key information is accessible to an Oracle Solaris system by using a PKCS#11 token.

For more information about managing ZFS encryption keys, see

http://www.oracle.com/technetwork/articles/servers-storage-admin/manage-zfs-encryption-1715034.html

For information about using Oracle Key Manager to manage key information, see:

http://docs.oracle.com/cd/E24472_02/

Delegating ZFS Key Operation Permissions

Review the following permission descriptions for delegating key operations:

Loading or unloading a file system key by using the zfs key -l and zfs key -u commands require the key permission. In most cases, you will need the mount permission as well.
Changing a file system key by using the zfs key -c and zfs key -K commands require the keychange permission.

Consider delegating separate permissions for key use (load or unload) and key change, which allows you to have a two-person key operation model. For example, determine which users can use the keys verses which users can change them. Or, both users need to be present for a key change. This model also allows you to build a key escrow system.

Mounting an Encrypted ZFS File System

Review the following considerations when attempting to mount an encrypted ZFS file system:

If an encrypted file system key is not available during boot time, the file system is not mounted automatically. For example, a file system with an encryption policy set to passphrase,prompt will not mount during boot time because the boot process is not interrupted to prompt for a passphrase.
If you want to mount a file system with an encryption policy set to passphrase,prompt at boot time, you will need to either explicitly mount it with the zfs mount command and specify the passphrase or use the zfs key -l command to be prompted for the key after the system is booted.

For example:
```
# zfs mount -a
Enter passphrase for 'tank/home/darren': xxxxxxxx
Enter passphrase for 'tank/home/ws': xxxxxxxx
Enter passphrase for 'tank/home/mark': xxxxxxxx
```
If an encrypted file system's keysource property points to a file in another file system, the mount order of the file systems can impact whether the encrypted file system is mounted at boot, particularly if the file is on removable media.

Upgrading Encrypted ZFS File Systems

Before you upgrade a Solaris 11 system to Solaris 11.1, ensure that your encrypted file systems are mounted. Mount the encrypted file systems and provide the passphrases, if prompted.

# zfs mount -a
Enter passphrase for 'pond/amy': xxxxxxxx
Enter passphrase for 'pond/rory': xxxxxxxx
# zfs mount | grep pond
pond                            /pond
pond/amy                        /pond/amy
pond/rory                       /pond/rory

Then, upgrade the encrypted file systems.

# zfs upgrade -a

If you attempt to upgrade encrypted ZFS file systems that are unmounted, a message similar to the following is displayed:

# zfs upgrade -a
cannot set property for 'pond/amy': key not present

In addition, the zpool status output might show corrupted data.

# zpool status -v pond
.
.
.
        pond/amy:<0x1>
        pond/rory:<0x1>

If the above errors occur, remount the encrypted file systems as directed above. Then, scrub and clear the pool errors.

# zpool scrub pond
# zpool clear pond

For more information about upgrading file systems, see Upgrading ZFS File Systems.

Interactions Between ZFS Compression, Deduplication, and Encryption Properties

Review the following considerations when using the ZFS compression, deduplication, and encryption properties:

When a file is written, the data is compressed, encrypted, and the checksum is verified. Then, the data is deduplicated, if possible.
When a file is read, the checksum is verified and the data is decrypted. Then, the data is decompressed, if required.
If the dedup property is enabled on an encrypted file system that is also cloned and the zfs key -Kor zfs clone -K commands have not been used on the clones, data from all the clones will be deduplicated, if possible.

Examples of Encrypting ZFS File Systems

Example 5-1 Encrypting a ZFS File System by Using a Raw Key

In the following example, an aes-256-ccm encryption key is generated by using the pktool command and is written to a file, /cindykey.file.

# pktool genkey keystore=file outkey=/cindykey.file keytype=aes keylen=256

Then, the /cindykey.file is specified when the tank/home/cindy file system is created.

# zfs create -o encryption=aes-256-ccm -o keysource=raw,file:///cindykey.file 
tank/home/cindy

Example 5-2 Encrypting a ZFS File System With a Different Encryption Algorithm

You can create a ZFS storage pool and have all the file systems in the storage pool inherit an encryption algorithm. In this example, the users pool is created and the users/home file system is created and encrypted by using a passphrase. The default encryption algorithm is aes-128-ccm.

Then, the users/home/mark file system is created and encrypted by using the aes-256-ccm encryption algorithm.

# zpool create -O encryption=on users mirror c0t1d0 c1t1d0 mirror c2t1d0 c3t1d0
Enter passphrase for 'users': xxxxxxxx
Enter again: xxxxxxxx
# zfs create users/home
# zfs get encryption users/home
NAME        PROPERTY    VALUE        SOURCE
users/home  encryption  on           inherited from users
# zfs create -o encryption=aes-256-ccm users/home/mark
# zfs get encryption users/home/mark
NAME               PROPERTY    VALUE        SOURCE
users/home/mark    encryption  aes-256-ccm  local

Example 5-3 Cloning an Encrypted ZFS File System

If the clone file system inherits the keysource property from the same file system as its origin snapshot, then a new keysource is not necessary, and you are not prompted for a new passphrase if keysource=passphrase,prompt. The same keysource is used for the clone. For example:

By default, you are not prompted for a key when cloning a descendent of an encrypted file system.

# zfs create -o encryption=on tank/ws
Enter passphrase for 'tank/ws': xxxxxxxx
Enter again: xxxxxxxx
# zfs create tank/ws/fs1
# zfs snapshot tank/ws/fs1@snap1
# zfs clone tank/ws/fs1@snap1 tank/ws/fs1clone

If you want to create a new key for the clone file system, use the zfs clone -K command.

If you clone an encrypted file system rather than a descendent encrypted file system, you are prompted to provide a new key. For example:

# zfs create -o encryption=on tank/ws
Enter passphrase for 'tank/ws': xxxxxxxx
Enter again: xxxxxxxx
# zfs snapshot tank/ws@1
# zfs clone tank/ws@1 tank/ws1clone
Enter passphrase for 'tank/ws1clone': xxxxxxxx
Enter again: xxxxxxxx

Example 5-4 Sending and Receiving an Encrypted ZFS File System

In the following example, the tank/home/darren@snap1 snapshot is created from the encrypted /tank/home/darren file system. Then, the snapshot is sent to bpool/snaps, with the encryption property enabled so the resulting received data is encrypted. However, the tank/home/darren@snap1 stream is not encrypted during the send process.

# zfs get encryption tank/home/darren
NAME              PROPERTY    VALUE        SOURCE
tank/home/darren  encryption  on           local
# zfs snapshot tank/home/darren@snap1
# zfs get encryption bpool/snaps
NAME         PROPERTY    VALUE        SOURCE
bpool/snaps  encryption  on           inherited from bpool
# zfs send tank/home/darren@snap1 | zfs receive bpool/snaps/darren1012
# zfs get encryption bpool/snaps/darren1012
NAME                    PROPERTY    VALUE        SOURCE
bpool/snaps/darren1012  encryption  on           inherited from bpool

In this case, a new key is automatically generated for the received encrypted file system.

Skip Navigation Links
Exit Print View
	Oracle Solaris 11.1 Administration: ZFS File Systems Oracle Solaris 11.1 Information Library