|Skip Navigation Links|
|Exit Print View|
|Oracle Solaris 11.1 Administration: ZFS File Systems Oracle Solaris 11.1 Information Library|
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:
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:
find | cpio
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.
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.
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
For information about using Oracle Key Manager to manage key information, see:
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.
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.
# 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.
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.
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.
Example 5-1 Encrypting a ZFS File System by Using a Raw Key
# 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.