forked from ~ljy/RK356X_SDK_RELEASE
blame | history | patch | commit | commitdiff
hc
2024-02-20 ea08eeccae9297f7aabd2ef7f0c2517ac4549acc 
 kernel/Documentation/filesystems/fscrypt.rst
....@@ -176,11 +176,11 @@
176176 
177177 Each encrypted directory tree is protected by a *master key*.  Master
178178 keys can be up to 64 bytes long, and must be at least as long as the
179
-greater of the key length needed by the contents and filenames
180
-encryption modes being used.  For example, if AES-256-XTS is used for
181
-contents encryption, the master key must be 64 bytes (512 bits).  Note
182
-that the XTS mode is defined to require a key twice as long as that
183
-required by the underlying block cipher.
179
+greater of the security strength of the contents and filenames
180
+encryption modes being used.  For example, if any AES-256 mode is
181
+used, the master key must be at least 256 bits, i.e. 32 bytes.  A
182
+stricter requirement applies if the key is used by a v1 encryption
183
+policy and AES-256-XTS is used; such keys must be 64 bytes.
184184 
185185 To "unlock" an encrypted directory tree, userspace must provide the
186186 appropriate master key.  There can be any number of master keys, each
....@@ -366,8 +366,8 @@
366366 -------------------
367367 
368368 For file contents, each filesystem block is encrypted independently.
369
-Currently, only the case where the filesystem block size is equal to
370
-the system's page size (usually 4096 bytes) is supported.
369
+Starting from Linux kernel 5.5, encryption of filesystems with block
370
+size less than system's page size is supported.
371371 
372372 Each block's IV is set to the logical block number within the file as
373373 a little endian number, except that:
....@@ -436,9 +436,9 @@
436436 
437437 The FS_IOC_SET_ENCRYPTION_POLICY ioctl sets an encryption policy on an
438438 empty directory or verifies that a directory or regular file already
439
-has the specified encryption policy.  It takes in a pointer to a
440
-:c:type:`struct fscrypt_policy_v1` or a :c:type:`struct
441
-fscrypt_policy_v2`, defined as follows::
439
+has the specified encryption policy.  It takes in a pointer to
440
+struct fscrypt_policy_v1 or struct fscrypt_policy_v2, defined as
441
+follows::
442442 
443443     #define FSCRYPT_POLICY_V1               0
444444     #define FSCRYPT_KEY_DESCRIPTOR_SIZE     8
....@@ -464,11 +464,11 @@
464464 
465465 This structure must be initialized as follows:
466466 
467
-- ``version`` must be FSCRYPT_POLICY_V1 (0) if the struct is
468
-  :c:type:`fscrypt_policy_v1` or FSCRYPT_POLICY_V2 (2) if the struct
469
-  is :c:type:`fscrypt_policy_v2`.  (Note: we refer to the original
470
-  policy version as "v1", though its version code is really 0.)  For
471
-  new encrypted directories, use v2 policies.
467
+- ``version`` must be FSCRYPT_POLICY_V1 (0) if
468
+  struct fscrypt_policy_v1 is used or FSCRYPT_POLICY_V2 (2) if
469
+  struct fscrypt_policy_v2 is used. (Note: we refer to the original
470
+  policy version as "v1", though its version code is really 0.)
471
+  For new encrypted directories, use v2 policies.
472472 
473473 - ``contents_encryption_mode`` and ``filenames_encryption_mode`` must
474474   be set to constants from ``<linux/fscrypt.h>`` which identify the
....@@ -508,9 +508,9 @@
508508   replaced with ``master_key_identifier``, which is longer and cannot
509509   be arbitrarily chosen.  Instead, the key must first be added using
510510   `FS_IOC_ADD_ENCRYPTION_KEY`_.  Then, the ``key_spec.u.identifier``
511
-  the kernel returned in the :c:type:`struct fscrypt_add_key_arg` must
512
-  be used as the ``master_key_identifier`` in the :c:type:`struct
513
-  fscrypt_policy_v2`.
511
+  the kernel returned in the struct fscrypt_add_key_arg must
512
+  be used as the ``master_key_identifier`` in
513
+  struct fscrypt_policy_v2.
514514 
515515 If the file is not yet encrypted, then FS_IOC_SET_ENCRYPTION_POLICY
516516 verifies that the file is an empty directory.  If so, the specified
....@@ -590,7 +590,7 @@
590590 The FS_IOC_GET_ENCRYPTION_POLICY_EX ioctl retrieves the encryption
591591 policy, if any, for a directory or regular file.  No additional
592592 permissions are required beyond the ability to open the file.  It
593
-takes in a pointer to a :c:type:`struct fscrypt_get_policy_ex_arg`,
593
+takes in a pointer to struct fscrypt_get_policy_ex_arg,
594594 defined as follows::
595595 
596596     struct fscrypt_get_policy_ex_arg {
....@@ -637,9 +637,8 @@
637637 encryption policy, if any, for a directory or regular file.  However,
638638 unlike `FS_IOC_GET_ENCRYPTION_POLICY_EX`_,
639639 FS_IOC_GET_ENCRYPTION_POLICY only supports the original policy
640
-version.  It takes in a pointer directly to a :c:type:`struct
641
-fscrypt_policy_v1` rather than a :c:type:`struct
642
-fscrypt_get_policy_ex_arg`.
640
+version.  It takes in a pointer directly to struct fscrypt_policy_v1
641
+rather than struct fscrypt_get_policy_ex_arg.
643642 
644643 The error codes for FS_IOC_GET_ENCRYPTION_POLICY are the same as those
645644 for FS_IOC_GET_ENCRYPTION_POLICY_EX, except that
....@@ -680,8 +679,7 @@
680679 encrypted using that key appear "unlocked", i.e. in plaintext form.
681680 It can be executed on any file or directory on the target filesystem,
682681 but using the filesystem's root directory is recommended.  It takes in
683
-a pointer to a :c:type:`struct fscrypt_add_key_arg`, defined as
684
-follows::
682
+a pointer to struct fscrypt_add_key_arg, defined as follows::
685683 
686684     struct fscrypt_add_key_arg {
687685             struct fscrypt_key_specifier key_spec;
....@@ -710,17 +708,16 @@
710708             __u8 raw[];
711709     };
712710 
713
-:c:type:`struct fscrypt_add_key_arg` must be zeroed, then initialized
711
+struct fscrypt_add_key_arg must be zeroed, then initialized
714712 as follows:
715713 
716714 - If the key is being added for use by v1 encryption policies, then
717715   ``key_spec.type`` must contain FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR, and
718716   ``key_spec.u.descriptor`` must contain the descriptor of the key
719717   being added, corresponding to the value in the
720
-  ``master_key_descriptor`` field of :c:type:`struct
721
-  fscrypt_policy_v1`.  To add this type of key, the calling process
722
-  must have the CAP_SYS_ADMIN capability in the initial user
723
-  namespace.
718
+  ``master_key_descriptor`` field of struct fscrypt_policy_v1.
719
+  To add this type of key, the calling process must have the
720
+  CAP_SYS_ADMIN capability in the initial user namespace.
724721 
725722   Alternatively, if the key is being added for use by v2 encryption
726723   policies, then ``key_spec.type`` must contain
....@@ -737,12 +734,13 @@
737734 
738735 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
739736   field.  Otherwise ``key_id`` is the ID of a Linux keyring key of
740
-  type "fscrypt-provisioning" whose payload is a :c:type:`struct
741
-  fscrypt_provisioning_key_payload` whose ``raw`` field contains the
742
-  raw key and whose ``type`` field matches ``key_spec.type``.  Since
743
-  ``raw`` is variable-length, the total size of this key's payload
744
-  must be ``sizeof(struct fscrypt_provisioning_key_payload)`` plus the
745
-  raw key size.  The process must have Search permission on this key.
737
+  type "fscrypt-provisioning" whose payload is
738
+  struct fscrypt_provisioning_key_payload whose ``raw`` field contains
739
+  the raw key and whose ``type`` field matches ``key_spec.type``.
740
+  Since ``raw`` is variable-length, the total size of this key's
741
+  payload must be ``sizeof(struct fscrypt_provisioning_key_payload)``
742
+  plus the raw key size.  The process must have Search permission on
743
+  this key.
746744 
747745   Most users should leave this 0 and specify the raw key directly.
748746   The support for specifying a Linux keyring key is intended mainly to
....@@ -860,8 +858,8 @@
860858 encryption key from the filesystem, and possibly removes the key
861859 itself.  It can be executed on any file or directory on the target
862860 filesystem, but using the filesystem's root directory is recommended.
863
-It takes in a pointer to a :c:type:`struct fscrypt_remove_key_arg`,
864
-defined as follows::
861
+It takes in a pointer to struct fscrypt_remove_key_arg, defined
862
+as follows::
865863 
866864     struct fscrypt_remove_key_arg {
867865             struct fscrypt_key_specifier key_spec;
....@@ -956,8 +954,8 @@
956954 The FS_IOC_GET_ENCRYPTION_KEY_STATUS ioctl retrieves the status of a
957955 master encryption key.  It can be executed on any file or directory on
958956 the target filesystem, but using the filesystem's root directory is
959
-recommended.  It takes in a pointer to a :c:type:`struct
960
-fscrypt_get_key_status_arg`, defined as follows::
957
+recommended.  It takes in a pointer to
958
+struct fscrypt_get_key_status_arg, defined as follows::
961959 
962960     struct fscrypt_get_key_status_arg {
963961             /* input */
....@@ -1052,9 +1050,9 @@
10521050 - Direct I/O is not supported on encrypted files.  Attempts to use
10531051   direct I/O on such files will fall back to buffered I/O.
10541052 
1055
-- The fallocate operations FALLOC_FL_COLLAPSE_RANGE,
1056
-  FALLOC_FL_INSERT_RANGE, and FALLOC_FL_ZERO_RANGE are not supported
1057
-  on encrypted files and will fail with EOPNOTSUPP.
1053
+- The fallocate operations FALLOC_FL_COLLAPSE_RANGE and
1054
+  FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will
1055
+  fail with EOPNOTSUPP.
10581056 
10591057 - Online defragmentation of encrypted files is not supported.  The
10601058   EXT4_IOC_MOVE_EXT and F2FS_IOC_MOVE_RANGE ioctls will fail with
....@@ -1148,17 +1146,17 @@
11481146 Encryption context
11491147 ------------------
11501148 
1151
-An encryption policy is represented on-disk by a :c:type:`struct
1152
-fscrypt_context_v1` or a :c:type:`struct fscrypt_context_v2`.  It is
1153
-up to individual filesystems to decide where to store it, but normally
1154
-it would be stored in a hidden extended attribute.  It should *not* be
1149
+An encryption policy is represented on-disk by
1150
+struct fscrypt_context_v1 or struct fscrypt_context_v2.  It is up to
1151
+individual filesystems to decide where to store it, but normally it
1152
+would be stored in a hidden extended attribute.  It should *not* be
11551153 exposed by the xattr-related system calls such as getxattr() and
11561154 setxattr() because of the special semantics of the encryption xattr.
11571155 (In particular, there would be much confusion if an encryption policy
11581156 were to be added to or removed from anything other than an empty
11591157 directory.)  These structs are defined as follows::
11601158 
1161
-    #define FS_KEY_DERIVATION_NONCE_SIZE 16
1159
+    #define FSCRYPT_FILE_NONCE_SIZE 16
11621160 
11631161     #define FSCRYPT_KEY_DESCRIPTOR_SIZE  8
11641162     struct fscrypt_context_v1 {
....@@ -1167,7 +1165,7 @@
11671165             u8 filenames_encryption_mode;
11681166             u8 flags;
11691167             u8 master_key_descriptor[FSCRYPT_KEY_DESCRIPTOR_SIZE];
1170
-            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
1168
+            u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
11711169     };
11721170 
11731171     #define FSCRYPT_KEY_IDENTIFIER_SIZE  16
....@@ -1178,7 +1176,7 @@
11781176             u8 flags;
11791177             u8 __reserved[4];
11801178             u8 master_key_identifier[FSCRYPT_KEY_IDENTIFIER_SIZE];
1181
-            u8 nonce[FS_KEY_DERIVATION_NONCE_SIZE];
1179
+            u8 nonce[FSCRYPT_FILE_NONCE_SIZE];
11821180     };
11831181 
11841182 The context structs contain the same information as the corresponding
....@@ -1203,6 +1201,18 @@
12031201 buffer.  Some filesystems, such as UBIFS, already use temporary
12041202 buffers regardless of encryption.  Other filesystems, such as ext4 and
12051203 F2FS, have to allocate bounce pages specially for encryption.
1204
+
1205
+Fscrypt is also able to use inline encryption hardware instead of the
1206
+kernel crypto API for en/decryption of file contents.  When possible,
1207
+and if directed to do so (by specifying the 'inlinecrypt' mount option
1208
+for an ext4/F2FS filesystem), it adds encryption contexts to bios and
1209
+uses blk-crypto to perform the en/decryption instead of making use of
1210
+the above read/write path changes.  Of course, even if directed to
1211
+make use of inline encryption, fscrypt will only be able to do so if
1212
+either hardware inline encryption support is available for the
1213
+selected encryption algorithm or CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK
1214
+is selected.  If neither is the case, fscrypt will fall back to using
1215
+the above mentioned read/write path changes for en/decryption.
12061216 
12071217 Filename hashing and encoding
12081218 -----------------------------
....@@ -1237,8 +1247,8 @@
12371247 filesystem-specific hash(es) needed for directory lookups.  This
12381248 allows the filesystem to still, with a high degree of confidence, map
12391249 the filename given in ->lookup() back to a particular directory entry
1240
-that was previously listed by readdir().  See :c:type:`struct
1241
-fscrypt_nokey_name` in the source for more details.
1250
+that was previously listed by readdir().  See
1251
+struct fscrypt_nokey_name in the source for more details.
12421252 
12431253 Note that the precise way that filenames are presented to userspace
12441254 without the key is subject to change in the future.  It is only meant
....@@ -1250,11 +1260,14 @@
12501260 
12511261 To test fscrypt, use xfstests, which is Linux's de facto standard
12521262 filesystem test suite.  First, run all the tests in the "encrypt"
1253
-group on the relevant filesystem(s).  For example, to test ext4 and
1263
+group on the relevant filesystem(s).  One can also run the tests
1264
+with the 'inlinecrypt' mount option to test the implementation for
1265
+inline encryption support.  For example, to test ext4 and
12541266 f2fs encryption using `kvm-xfstests
12551267 <https://github.com/tytso/xfstests-bld/blob/master/Documentation/kvm-quickstart.md>`_::
12561268 
12571269     kvm-xfstests -c ext4,f2fs -g encrypt
1270
+    kvm-xfstests -c ext4,f2fs -g encrypt -m inlinecrypt
12581271 
12591272 UBIFS encryption can also be tested this way, but it should be done in
12601273 a separate command, and it takes some time for kvm-xfstests to set up
....@@ -1276,6 +1289,7 @@
12761289 kvm-xfstests, use the "encrypt" filesystem configuration::
12771290 
12781291     kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1292
+    kvm-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt
12791293 
12801294 Because this runs many more tests than "-g encrypt" does, it takes
12811295 much longer to run; so also consider using `gce-xfstests
....@@ -1283,3 +1297,4 @@
12831297 instead of kvm-xfstests::
12841298 
12851299     gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto
1300
+    gce-xfstests -c ext4/encrypt,f2fs/encrypt -g auto -m inlinecrypt