linux/Documentation/security/keys-ecryptfs.txt
<<
>>
Prefs
   1                Encrypted keys for the eCryptfs filesystem
   2
   3ECryptfs is a stacked filesystem which transparently encrypts and decrypts each
   4file using a randomly generated File Encryption Key (FEK).
   5
   6Each FEK is in turn encrypted with a File Encryption Key Encryption Key (FEFEK)
   7either in kernel space or in user space with a daemon called 'ecryptfsd'.  In
   8the former case the operation is performed directly by the kernel CryptoAPI
   9using a key, the FEFEK, derived from a user prompted passphrase;  in the latter
  10the FEK is encrypted by 'ecryptfsd' with the help of external libraries in order
  11to support other mechanisms like public key cryptography, PKCS#11 and TPM based
  12operations.
  13
  14The data structure defined by eCryptfs to contain information required for the
  15FEK decryption is called authentication token and, currently, can be stored in a
  16kernel key of the 'user' type, inserted in the user's session specific keyring
  17by the userspace utility 'mount.ecryptfs' shipped with the package
  18'ecryptfs-utils'.
  19
  20The 'encrypted' key type has been extended with the introduction of the new
  21format 'ecryptfs' in order to be used in conjunction with the eCryptfs
  22filesystem.  Encrypted keys of the newly introduced format store an
  23authentication token in its payload with a FEFEK randomly generated by the
  24kernel and protected by the parent master key.
  25
  26In order to avoid known-plaintext attacks, the datablob obtained through
  27commands 'keyctl print' or 'keyctl pipe' does not contain the overall
  28authentication token, which content is well known, but only the FEFEK in
  29encrypted form.
  30
  31The eCryptfs filesystem may really benefit from using encrypted keys in that the
  32required key can be securely generated by an Administrator and provided at boot
  33time after the unsealing of a 'trusted' key in order to perform the mount in a
  34controlled environment.  Another advantage is that the key is not exposed to
  35threats of malicious software, because it is available in clear form only at
  36kernel level.
  37
  38Usage:
  39   keyctl add encrypted name "new ecryptfs key-type:master-key-name keylen" ring
  40   keyctl add encrypted name "load hex_blob" ring
  41   keyctl update keyid "update key-type:master-key-name"
  42
  43name:= '<16 hexadecimal characters>'
  44key-type:= 'trusted' | 'user'
  45keylen:= 64
  46
  47
  48Example of encrypted key usage with the eCryptfs filesystem:
  49
  50Create an encrypted key "1000100010001000" of length 64 bytes with format
  51'ecryptfs' and save it using a previously loaded user key "test":
  52
  53    $ keyctl add encrypted 1000100010001000 "new ecryptfs user:test 64" @u
  54    19184530
  55
  56    $ keyctl print 19184530
  57    ecryptfs user:test 64 490045d4bfe48c99f0d465fbbbb79e7500da954178e2de0697
  58    dd85091f5450a0511219e9f7cd70dcd498038181466f78ac8d4c19504fcc72402bfc41c2
  59    f253a41b7507ccaa4b2b03fff19a69d1cc0b16e71746473f023a95488b6edfd86f7fdd40
  60    9d292e4bacded1258880122dd553a661
  61
  62    $ keyctl pipe 19184530 > ecryptfs.blob
  63
  64Mount an eCryptfs filesystem using the created encrypted key "1000100010001000"
  65into the '/secret' directory:
  66
  67    $ mount -i -t ecryptfs -oecryptfs_sig=1000100010001000,\
  68      ecryptfs_cipher=aes,ecryptfs_key_bytes=32 /secret /secret
  69
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.