From: Sebastien Buisson <sbuisson@ddn.com>
Date: Mon, 31 Jan 2022 17:03:37 +0000 (+0100)
Subject: LUDOC-502 sec: doc update for filename encryption
X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=refs%2Fchanges%2F94%2F46394%2F5;p=doc%2Fmanual.git

LUDOC-502 sec: doc update for filename encryption

This patch updates the "Encrypting files and directories" section of
the Lustre Operations Manual to reflect filename encryption support
as implemented by LU-13717.

Signed-off-by: Sebastien Buisson <sbuisson@ddn.com>
Change-Id: I59cae29db3dfff6552d46c752870ade76c06d89f
Reviewed-on: https://review.whamcloud.com/46394
Tested-by: jenkins <devops@whamcloud.com>
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
---

diff --git a/ManagingSecurity.xml b/ManagingSecurity.xml
index 4d2b16e..8806cf0 100644
--- a/ManagingSecurity.xml
+++ b/ManagingSecurity.xml
@@ -603,6 +603,16 @@ mgs# lctl set_param -P nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58c
               <listitem><para>DAX (Direct Access) is not supported on encrypted
                 files.</para>
               </listitem>
+              <listitem><para condition='l2F'>The st_size of an encrypted
+                symlink will not necessarily give the length of the symlink
+                target as required by POSIX. It will actually give the length of
+                the ciphertext, which will be slightly longer than the plaintext
+                due to NUL-padding and an extra 2-byte overhead.</para>
+              </listitem>
+              <listitem><para condition='l2F'>The maximum length of an encrypted
+                symlink is 2 bytes shorter than the maximum length of an
+                unencrypted symlink.</para>
+              </listitem>
               <listitem><para><literal>mmap</literal> is supported.  This is
                 possible because the pagecache for an encrypted file contains
                 the plaintext, not the ciphertext.</para>
@@ -621,9 +631,15 @@ mgs# lctl set_param -P nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58c
                   <literal>stat()</literal>.</para>
               </listitem>
               <listitem>
-                <para>Directories may be listed, and the whole namespace tree
-                  may be walked through.
-                </para>
+                <para condition='l2F'>Directories may be listed, in which case
+                  the filenames will be listed in an encoded form derived from
+                  their ciphertext. The algorithm is subject to change but it is
+                  guaranteed that the presented filenames will be no longer than
+                  NAME_MAX bytes, will not contain the <literal>/</literal> or
+                  <literal>\0</literal> characters, and will uniquely identify
+                  directory entries. The <literal>.</literal> and
+                  <literal>..</literal> directory entries are special. They are
+                  always present and are not encrypted or encoded.</para>
               </listitem>
               <listitem>
                 <para>Files may be deleted.  That is, nondirectory files may be
@@ -705,6 +721,14 @@ mgs# lctl set_param -P nodemap.restricted.sepol=1:mls:31:40afb76d077c441b69af58c
        content encryption mode will be taken into account, and filename
        encryption mode will be ignored to leave filenames in clear text.</para>
       </warning>
+      <warning><para condition='l2F'>In Lustre 2.15, filename encryption mode
+       will be taken into account for new files and directories, if they are
+       under a parent encrypted directory created with Lustre 2.15. This means
+       new files and directories under a parent encrypted directory created with
+       Lustre 2.14 will not have their names encrypted.
+       Also, because files created with Lustre 2.14 did not have their names
+       encrypted, they will remain so after upgrade to 2.15.</para>
+      </warning>
     </section>
     <section xml:id="managingSecurity.clientencryption.threatmodel" remap="h3">
       <title><indexterm><primary>encryption threat model</primary>