--- zpool.orig Thu Jan 10 15:18:25 2008 +++ zpool.1m Wed Jan 30 10:48:01 2008 @@ -91,6 +91,15 @@ zpool upgrade [-V version] -a | pool ... + zpool key -l pool ... + + + zpool key -u pool ... + + + zpool key -c [-o property=value] pool ... + + zpool history [-il] [pool] ... @@ -473,6 +482,18 @@ The content of the cache devices is considered volatile, as is the case with other system caches. + Encryption + Encryption can be added to a pool after it has been created, + for enabling encrypted datasets. But to have the encryption + in the pool level dataset, it must be specified during pool + creation time. + + The pool creates centralized key control for all encrypted + datasets of keyscope "pool". If the key has not been loaded, + none of the encrypted datasets will be available. Any + non-encrypted datasets will be accessable regardless if the + key is loaded. + Properties Each pool has several properties associated with it. Some properties are read-only statistics while others are confi- @@ -653,7 +674,6 @@ is needed for backwards compatibility. This property - SunOS 5.11 Last change: 13 Nov 2007 10 @@ -670,6 +690,43 @@ "current" is an alias for the latest supported version. + The following properties can be set at creation time or + modified afterwards: + + keysource=, > + + Defines how the keysource that wraps the dataset keys is stored. + The key will need to be present at the time of creation or + load time ('zpool 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. + _file:///_ : The file location of the key. + + + To change the key the 'zpool key -c' command is used. + + + The following properties must be specified at creation time: + + encryption=off | on | aes-128-ccm | aes-256-ccm + + Defines what encryption algorithm and key length will be + used for the encrypted pool level dataset. "on" is equal + to aes-256-ccm. The default value is "off" + + Subcommands All subcommands that modify state are logged persistently to the pool in their original form. @@ -1294,7 +1351,37 @@ recent version supported by this software. + zpool key -l pool + If the keysource property is defined, this command will load the + wrapping key to unlock the encrypted dataset in the pool that have + the keyscope property set to 'pool' + + The key method loaded is defined by the value of the keysource + property. If the locator for the keysource property is set to + 'prompt', the user will be prompted for the key. Otherwise the + key will from the defined location. + + + zpool key -u pool + + This will unload the keys for all the dataset in that pool and + unload the pool's wrapping key. No data will be able to be + read or written to the encrypted datasets or pool. + + + zpool key -c [-o property] pool + + Changes the wrapping keysource property for an encrypted pool. + The existing key will need to be entered or available to access + before the key change operation can occur. + + The operation will not cause a interruption is service if + the pool and datasets in the pool are in use. This will + not affect the wrapping key of any datasets that is of + keyscope "dataset". + + zpool history [-il] [pool] ... Displays the command history of the specified pools or @@ -1607,7 +1694,73 @@ # zpool iostat -v pool 5 + Example 14 Creating an encrypted pool with a hexidecimal key file + To create and enable an encrypted pool with a file as a keysource + property, do the following: + + # pktool genkey keystore=file outkey=/rmdisk/stick-1/key keytype=aes \ + keylen=128 print=y + Key Value ="1f583b49af35eaef7058e6893efd2cb0" + # zpool create -o encryption=aes-128-ccm -o \ + keysource=hex,file:///rmdisk/stick-1/key tank /dev/dsk/c0t0d0s1 + # zpool key -l tank + # + + + Example 15 Changing a passphrase wrapping key for the encrypted pool + + First we take an existing encrypted pool that has it keysource + property set to passphrase and prompt. + + # zpool get keyscope tank + NAME PROPERTY VALUE SOURCE + tank keysource passphrase,prompt default + + Then change the key using the 'zpool key -c' command + + # zpool key -c tank + Enter existing passphrase: ********** + Enter passphrase: ********** + Re-enter passphrase: ********** + # + + + Example 16 Changing a file wrapping key for the encrypted pool + + First we take an existing encrypted pool, in this example the + keysource property is set to raw and a file. + + # zpool get keyscope tank + NAME PROPERTY VALUE SOURCE + tank keysource raw,file:///rmdisk/stick-1/oldkey default + + Then we want to change the format of the file and the file locator. + + # zpool key -c -o raw,file:///rmdisk/stick-1/key tank + # + + + + Example 17 Changing the wrapping key and keysource property for the + encrypted pool + + First we take an existing encrypted pool has been set to use a file + for storing a wrapping key. + + # zpool get keyscope tank + NAME PROPERTY VALUE SOURCE + tank keysource raw,file:///rmdisk/stick-1/key default + + To change the key storage method, add the property as an option to + the command: + + # zpool key -c -o keysource=passphrase,prompt tank + Enter passphrase: ********** + Re-enter passphrase: ********** + # + + EXIT STATUS The following exit values are returned: