Lines Matching refs:key
18 `fscryptctl <https://github.com/google/fscryptctl>`_ or `Android's key
46 userspace provides the key, all regular files, directories, and
56 Provided that userspace chooses a strong encryption key, fscrypt
89 After an encryption key has been added, fscrypt does not hide the
94 (For the reasoning behind this, understand that while the key is
115 encryption key from kernel memory. If it does so, it will also try to
116 evict all cached inodes which had been "unlocked" using the key,
124 encrypted files and directories before removing a master key, as
128 - The kernel cannot magically wipe copies of the master key(s) that
130 copies of the master key(s) it makes as well; normally this should
133 to all higher levels in the key hierarchy. Userspace should also
139 recoverable from freed memory, even after the corresponding key(s)
154 - There is no verification that the provided master key is correct.
155 Therefore, a malicious user can temporarily associate the wrong key
157 access. Because of filesystem caching, the wrong key will then be
159 user has the correct key in their own keyring. This violates the
162 - A compromise of a per-file key also compromises the master key from
177 Each encrypted directory tree is protected by a *master key*. Master
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
186 appropriate master key. There can be any number of master keys, each
192 **must not** directly use a password as a master key, zero-pad a
193 shorter key, or repeat a shorter key. Security cannot be guaranteed
199 (Key Derivation Function). The kernel does not do any key stretching;
200 therefore, if userspace derives the key from a low-entropy secret such
207 With one exception, fscrypt never uses the master key(s) for
211 The KDF used for a particular master key differs depending on whether
212 the key is used for v1 encryption policies or for v2 encryption
213 policies. Users **must not** use the same key for both v1 and v2
215 specific case of key reuse, but its security cannot be guaranteed
219 encryption keys. It works by encrypting the master key with
220 AES-128-ECB, using the file's 16-byte nonce as the AES key. The
221 resulting ciphertext is used as the derived key. If the ciphertext is
224 For v2 encryption policies, the KDF is HKDF-SHA512. The master key is
227 key to be derived. For example, when a per-file encryption key is
234 entropy from the master key. HKDF is also standardized and widely
240 Since each master key can protect many files, it is necessary to
247 derivation function`_) to derive the file's key from the master key
250 Key derivation was chosen over key wrapping because wrapped keys would
253 significant advantages to key wrapping. In particular, currently
265 and a 16-byte per-file nonce. Also, the overhead of each Adiantum key
266 is greater than that of an AES-256-XTS key.
269 "direct key" configuration is supported. When the user has enabled
276 master key. Because of this, users **must not** use the same master
277 key for any other purpose, even for other v1 policies.
280 key derived using the KDF. Users may use the same master key for
287 the encryption keys are derived from the master key, encryption mode
289 protected by the same master key sharing a single contents encryption
290 key and a single filenames encryption key. To still encrypt different
303 SipHash key is derived from the master key) and added to the file
315 For master keys used for v2 encryption policies, a unique 16-byte "key
317 the clear, since it is needed to reliably identify the key itself.
324 SipHash-2-4 key per directory in order to hash filenames. This works
325 just like deriving a per-file encryption key, except that a different
388 is encrypted with AES-256 where the AES-256 key is the SHA-256 hash
389 of the file's data encryption key.
414 However, each encrypted directory still uses a unique key, or
511 to find the master key in a keyring; see `Adding keys`_. It is up
513 master key. The e4crypt and fscrypt tools use the first 8 bytes of
515 required. Also, the master key need not be in the keyring yet when
521 be arbitrarily chosen. Instead, the key must first be added using
531 corresponding master key as described in `Adding keys`_, all regular
543 required that either the specified key has been added by the current
546 another user's key.) The key must remain added while
549 key can be removed right away afterwards.
553 filesystem with one key should consider using dm-crypt instead.
566 - ``ENOKEY``: a v2 encryption policy was specified, but the key with
666 value is intended to used as a salt when deriving an encryption key
689 The FS_IOC_ADD_ENCRYPTION_KEY ioctl adds a master encryption key to
691 encrypted using that key appear "unlocked", i.e. in plaintext form.
726 - If the key is being added for use by v1 encryption policies, then
728 ``key_spec.u.descriptor`` must contain the descriptor of the key
731 To add this type of key, the calling process must have the
734 Alternatively, if the key is being added for use by v2 encryption
738 hash of the key. To add this type of key, the calling process does
743 - ``raw_size`` must be the size of the ``raw`` key provided, in bytes.
745 in that case the size is implied by the specified Linux keyring key.
747 - ``key_id`` is 0 if the raw key is given directly in the ``raw``
748 field. Otherwise ``key_id`` is the ID of a Linux keyring key of
751 the raw key and whose ``type`` field matches ``key_spec.type``.
752 Since ``raw`` is variable-length, the total size of this key's
754 plus the raw key size. The process must have Search permission on
755 this key.
757 Most users should leave this 0 and specify the raw key directly.
758 The support for specifying a Linux keyring key is intended mainly to
763 key, ``raw_size`` bytes long. Alternatively, if ``key_id`` is
767 by effective user ID) added the key, and only allows the key to be
771 However, if another user has added the key, it may be desirable to
773 FS_IOC_ADD_ENCRYPTION_KEY may also be used to add a v2 policy key
775 FS_IOC_ADD_ENCRYPTION_KEY will just install a claim to the key for the
776 current user, rather than actually add the key again (but the raw key
779 FS_IOC_ADD_ENCRYPTION_KEY returns 0 if either the key or a claim to
780 the key was either added or already exists.
786 user namespace; or the raw key was specified by Linux key ID but the
787 process lacks Search permission on the key.
788 - ``EDQUOT``: the key quota for this user would be exceeded by adding
789 the key
790 - ``EINVAL``: invalid key size or key specifier type, or reserved bits
792 - ``EKEYREJECTED``: the raw key was specified by Linux key ID, but the
793 key has the wrong type
794 - ``ENOKEY``: the raw key was specified by Linux key ID, but no key
804 For v1 encryption policies, a master encryption key can also be
812 so for removing a key a workaround such as keyctl_unlink() in
821 Nevertheless, to add a key to one of the process-subscribed keyrings,
823 ``Documentation/security/keys/core.rst``). The key type must be
825 read back by userspace. The key description must be "fscrypt:"
828 key payload must conform to the following structure::
838 ``mode`` is ignored; just set it to 0. The actual key is provided in
840 bytes ``raw[0..size-1]`` (inclusive) are the actual key.
842 The key description prefix "fscrypt:" may alternatively be replaced
850 Two ioctls are available for removing a key that was added by
870 encryption key from the filesystem, and possibly removes the key
886 - The key to remove is specified by ``key_spec``:
888 - To remove a key used by v1 encryption policies, set
890 in ``key_spec.u.descriptor``. To remove this type of key, the
894 - To remove a key used by v2 encryption policies, set
900 claim to the key, undoing a single call to FS_IOC_ADD_ENCRYPTION_KEY.
901 Only after all claims are removed is the key really removed.
904 then the key will be "claimed" by uid 1000, and
906 both uids 1000 and 2000 added the key, then for each uid
908 once *both* are removed is the key really removed. (Think of it like
911 If FS_IOC_REMOVE_ENCRYPTION_KEY really removes the key, it will also
912 try to "lock" all files that had been unlocked with the key. It won't
918 FS_IOC_REMOVE_ENCRYPTION_KEY returns 0 if either the key was removed
920 the key was removed, or the key was already removed but had files
927 the user's claim to the key was removed.
929 user's claim to the key was removed, not the key itself
933 - ``EACCES``: The FSCRYPT_KEY_SPEC_TYPE_DESCRIPTOR key specifier type
936 - ``EINVAL``: invalid key specifier type, or reserved bits were set
937 - ``ENOKEY``: the key object was not found at all, i.e. it was never
939 files locked; or, the user does not have a claim to the key (but
952 key, not just the current user's. I.e., the key itself will always be
960 Getting key status
967 master encryption key. It can be executed on any file or directory on
990 - To get the status of a key for v1 encryption policies, set
994 - To get the status of a key for v2 encryption policies, set
1000 - ``status`` indicates whether the key is absent, present, or
1008 - ``FSCRYPT_KEY_STATUS_FLAG_ADDED_BY_SELF`` indicates that the key
1012 - ``user_count`` specifies the number of users who have added the key.
1018 - ``EINVAL``: invalid key specifier type, or reserved bits were set
1025 for determining whether the key for a given encrypted directory needs
1027 derive the key.
1032 cannot get the status of a key that has only been added for use by v1
1039 With the key
1042 With the encryption key, encrypted regular files, directories, and
1048 policy (i.e. different key, modes, or flags), cannot be renamed or
1087 Without the key
1091 files, directories, and symlinks even before their encryption key has
1092 been added, or after their encryption key has been removed:
1116 Without the key, regular files cannot be opened or truncated.
1121 Also without the key, files of any type (including directories) cannot
1128 without the encryption key. This would require special APIs which
1294 without the encryption key. Clearly, it would not work to hash the
1296 without the key. (Hashing the plaintext filenames would also make it
1300 asked to do a ->lookup() with the key, the filesystem just encrypts
1303 Lookups without the key are more complicated. The raw ciphertext may
1321 without the key is subject to change in the future. It is only meant
1354 encrypted with a dummy key, without having to make any API calls.