OpenSolaris

1. Project: ZFS on disk encryption support
   1. Announcements
   2. Blogs
   3. Discussions
   4. Leaders
   5. Observers
   6. Files
   7. Phase 1
      1. IV Generation
      2. Encryption Cipher Modes
      3. Using KCF
      4. Encryption by DMU Object Type
      5. Phase 1 Alpha Release Notes
      6. libzfs API additions
      7. CLI
      8. L2ARC Encryption
      9. Test Plan
      10. Test Assertions
   8. Project Plan
   9. Design Review
   10. Phase 1 Codereview

Phase 1 Alpha Release

IMPORTANT

• The alpha release is NOT for production use
• Do NOT assume that a later set of ZFS Crypto binaries can read pools/datasets generated by these binaries.
• Assume (though we hope not) that the binaries could be toxic even to clear text datasets in other pools.

Phase 1 Functionality implemented

• Per pool wrapping key (DSKEK)
• per dataset keytype.
  • pwrap: Randomly generated per dataset key wrapped by DSKEK
  • pool: Use DSKEK directly. Will likely NOT be supported in final release.
• zpool keymgr load|unload|status
  • passphrase & key in file only
• Per dataset encryption
  • NOTE: use only aes-128-cbc, aes-256-cbc
  • aes-192-cbc is broken
• Encrypted snapshots
• Clones "inherit" crypto properties regardless of path hierarchy clone promotion also works
• Encryption is a create time only property
• Encrypted datasets don't mount with 'zfs mount -a' unless key is present
• pool history records key creation/clone.

Known issues

• CCM mode doesn't work
• aes-192-cbc/aes-192-ccm fails to generate dataset key
• HMAC-SHA256 not yet implemented
• per dataset key load not yet implemented Note this is keytype=dataset, keytype=pwrap which gives per dataset keys does work and is the default.
• key change not yet implemented
• no validation passphrase is correct key.
• Reads from an encrypted data set after key removal will succeed if the data is in the ARC otherwise fail with EACCES
• No policy on who can load/unload keys.

Getting the binaries

Only bfu archives are supplied, if you aren't comfortable with using bfu then please wait for a later release.

The files for the alpha release are covered by either the OpenSolaris Binary License (OBL) or the Common Development and Distribution License (CDDL).

The pre-built BFU archives contain binaries/source for high key-strength crypto, known as the Encryption Kit (SUNWcry, SUNWcryr). Please note that certain countries restrict the redistribution of high key-strength crypto. If you live in one of these countries, it is your responsibility to ensure that you are complying with your country's laws in this area.

NOTICE PURSUANT TO SECTION 9 OF THE COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL)

The OpenSolaris code released under the CDDL shall be governed by the laws of the State of California (excluding conflict-of-law provisions). Any litigation relating to this License shall be subject to the jurisdiction of the Federal Courts of the Northern District of California and the state courts of the State of California, with venue lying in Santa Clara County, California.

x86/x64 Debug

x86/x64 Non Debug

SPARC Alpha binaries are not yet available

NOTE bfu does not correctly resolve the /etc/crypto/kcf.conf conflict. You MUST do this if you use dataset or dskek with a keylength other than 128. Your /etc/kcf.conf should have an entry for "aes256" not "aes". Manually edit it and then run cryptoadm refresh. Failing to do this will cause a panic if you use aes-256-cbc with zfs.

Alpha Release source:

Tagged as "zc_alpha" in the mercurial repository: hg.opensolaris.org/hg/zfs-crypto/zfs-crypto-gate/

Creating an encrypted pool

After the pool has been created, the following commands can be run.

Using a key file for your encrypted pool

For generating a key in a file, use pktool(1) thus:

# pktool genkey keystore=file keytype=aes keylen=256 outfile=<file>

Note that with pktool outfile can not be a full path, use the dir= option to store the key somewhere other than the current directory.

Set the DSKEK to the key file and load the key

# zpool set dskek=file:<path> <pool>
# zpool keymgr load <pool>

Using a passphrase for your encrypted pool.

# zpool set dskek=passphrase <pool>
# zpool keymgr load <pool>
Enter key:
Re-enter key:

Create an encrypted dataset

This command will create an encrypted dataset to use in your pool.

# zfs create -o encryption=aes-128-cbc <pool>/<dataset>

If you leave off the "encryption", you will get an unencrypted dataset that can live in the pool just as normal.

Encryption & User delegation

Users need the "encryption" property delegated to them to be able to change wither or not encryption is enabled in a dataset they create as themselves. This allows enabling encryption at say tank/home and having it inherited to all datasets created for any by users and ensures they can not change that policy.

Mounting encrypted datasets

Note that encrypted datasets will NOT mount unless the pool key is present. During boot if the key isn't found they will be skipped by 'zfs mount -a'.

To manually mount later: 'zpool keymgr load <pool> && zfs mount -a'

Destroying datasets and pools

You can use the normal zfs and zpool commands to umount and destroy encrypted datasets and pools.