--- zfs.orig Thu Jan 10 15:17:16 2008 +++ zfs.1m Wed Jan 30 10:48:50 2008 @@ -124,8 +124,15 @@ zfs unallow [-r] -c [perm|@setname[ ... ]] filesystem|volume + zfs key -l filesystem|volume + zfs key -u filesystem|volume + + + zfs key -c [-o property=value] ... filesystem|volume + + SunOS 5.11 Last change: 30 Oct 2007 2 @@ -350,6 +357,16 @@ global administrator should verify that all the mount points are acceptable before clearing the property. + Encryption + Encryption is a creation-time only operation. One cannot + make a non-encrypted dataset into an encrypted dataset or + vice versa. The encryption property cannot be changed, but + the keyscope and key properties can via the 'zfs key' command. + + There are two types of keyscopes for encrypted datasets: + "pool" and "dataset". If not specified at creation time, the + default is "pool". + Native Properties Properties are divided into two types, native properties and user defined properties. Native properties either export @@ -429,6 +446,12 @@ The time this dataset was created. + keystatus + + This is the status of the encryption key for the dataset. + The availability of dataset's key is indicate by showing + the status of "available" or "unavailable". + mounted For file systems, indicates whether the file system is @@ -1084,6 +1107,56 @@ non-privileged users by using the ZFS delegated administra- tion feature. + The following properties must be specifed at creation time and + can modified via special commands: + + + keysource=, + + Defines how the keysource that wraps the dataset keys is stored + and entered into the zfs command. The key will need to be + present at the time of creation or load time ('zfs key -l'). + + There are two values given to a keysource property. The format, + which the way the key is being presented, and the locator, + which is where the key is coming from. + + The format accepts 3 values: + _raw_ : the raw bytes of the key. + _hex_ : a hexidecimal character string of the key. + _passphrase_ : a character string that a key + will be generated from. + + The locator accepts 2 values: + _prompt_ : This will prompt the user for the key during + creation or loading of the pool or dataset. + _file:///_ : The file location of the key. + + + To change the key the 'zfs key -c' command is used. + + + keyscope=pool | dataset + + Defines what type of key method will be used to secure + the datsaet keys. 'pool' signifies that the keysource property + on the pool wraps with the dataset key. 'dataset' signifies + that the dataset key will wrap the dataset key. The default + is "pool". + + To change the key the 'zfs key -c' command is used. + + + The following properties must be set a creation time and cannot + be changed: + + encryption=off | on | aes-128-ccm | aes-256-ccm + + Defines what encryption algorithm and key length will be + used for the encrypted dataset. "on" is equal to aes-256-ccm. + The default is "off". + + Temporary Mount Point Properties When a file system is mounted, either through mount(1M) for legacy mounts or the "zfs mount" command for normal file @@ -2053,7 +2126,10 @@ copies property devices property + encryption property exec property + keysource property + keyscope property mountpoint property quota property readonly property @@ -2136,6 +2212,39 @@ thus removing the set entirely. + zfs key -l filesystem|volume + + Loads the key to unlock the encrypted dataset, if the + keyscope is defined as 'dataset'. The command will load + the key based on what is defined by the dataset's keysource + property. + + + zfs key -u filesystem|volume + + Unloads the key for an encrypted dataset, if the keyscope + is defined as 'dataset'. After this operation the + dataset will not be accessable. + + + zfs key -c [-o property=value] filesystem|volume + + Changes the key for an encrypted dataset, if the keyscope + is defined as a 'dataset'. The existing key will need to + be entered or available to access before the key change + operation can occur. + + If the keyscope property is included, it will change the wrapping + for the dataset's encryption key to the new keysource property. + If the keyscope is being changed to "pool", the key will + keysource property of the pool will be used. If the keyscope is + being changed to "dataset", the keysource property should be + included with the command. + + The user must have access to change the keyscope and + keysource properties. + + EXAMPLES Example 1 Creating a ZFS File System Hierarchy @@ -2293,12 +2402,12 @@ pool/home/bob refreservation none default pool/home/bob copies 1 default pool/home/bob version 1 - + pool/home/bob encryption off default + pool/home/bob keyscope pool default + pool/home/bob keysource default + pool/home/bob keystatus unavailable default - - - - The following command gets a single property value. @@ -2702,11 +2811,69 @@ SunOS 5.11 Last change: 30 Oct 2007 41 + Example 24 Creating an encrypted dataset with a keyscope of pool, + with the pool key already loaded via zpool: + # zfs create -o keyscope=pool -o encryption=aes-256-ccm \ + tank/home/bob + # + Example 25 Creating an encrypted dataset with a keyscope of dataset + using a raw key, generated by pktool, in a file: + # pktool genkey keystore=file outfile=mykey outdir=/rmdisk/stick-1 \ + keytype=aes keylen=256 + # zfs create -o keyscope=dataset -o encryption=aes-256-ccm \ + -o keysource=raw,file:///rmdisk/stick-1/mykey tank/home/bob + # zfs key -l tank/home/bob + # + + + Example 26 Creating an encrypted dataset with a keyscope of dataset + passphrase that we prompt for: + + $ zfs create -o keyscope=dataset -o encryption=aes-256-ccm \ + -o keysource=passphrase,prompt tank/home/bob + Enter passphrase: + Re-enter passphrase: + $ + + + Example 27 Changing a dataset from keyscope pool to dataset + + This changes the wrapping key to a new key defined by the + dataset's keysource property from the pool keysource property. + + $ zfs get keyscope tank/home/bob + NAME PROPERTY VALUE SOURCE + tank keyscope pool default + $ zfs key -c -o keyscope=dataset -o keysource=passphrase,prompt \ + tank/home/bob/ + Enter passphrase: ********** + Re-enter passphrase: ********** + $ + + The user must have access to change the keyscope property. + + + Example 28 Changing a dataset from keyscope dataset to pool + + This changes the wrapping key defined on the dataset's + keysource property to the wrapping key defined on the keysource + property of the pool. The dataset key property must be present. + The pool key must be loaded. + + $ zfs get keyscope tank/home/bob + NAME PROPERTY VALUE SOURCE + tank keyscope dataset default + $ zfs key -c -o keyscope=pool tank/home/bob/ + $ + + The user must have access to change the keyscope property. + + System Administration Commands zfs(1M)