| fscrypt.rst (03c11eb3b16dc0058589751dfd91f254be2be613) | fscrypt.rst (2f944c66ae73eed4250607ccd3acdf2531afc194) |
|---|---|
| 1===================================== 2Filesystem-level encryption (fscrypt) 3===================================== 4 5Introduction 6============ 7 8fscrypt is a library which filesystems can hook into to support --- 324 unchanged lines hidden (view full) --- 333and one encryption mode to be specified for filenames. Different 334directory trees are permitted to use different encryption modes. 335 336Supported modes 337--------------- 338 339Currently, the following pairs of encryption modes are supported: 340 | 1===================================== 2Filesystem-level encryption (fscrypt) 3===================================== 4 5Introduction 6============ 7 8fscrypt is a library which filesystems can hook into to support --- 324 unchanged lines hidden (view full) --- 333and one encryption mode to be specified for filenames. Different 334directory trees are permitted to use different encryption modes. 335 336Supported modes 337--------------- 338 339Currently, the following pairs of encryption modes are supported: 340 |
| 341- AES-256-XTS for contents and AES-256-CTS-CBC for filenames | 341- AES-256-XTS for contents and AES-256-CBC-CTS for filenames |
| 342- AES-256-XTS for contents and AES-256-HCTR2 for filenames 343- Adiantum for both contents and filenames | 342- AES-256-XTS for contents and AES-256-HCTR2 for filenames 343- Adiantum for both contents and filenames |
| 344- AES-128-CBC-ESSIV for contents and AES-128-CTS-CBC for filenames 345- SM4-XTS for contents and SM4-CTS-CBC for filenames | 344- AES-128-CBC-ESSIV for contents and AES-128-CBC-CTS for filenames 345- SM4-XTS for contents and SM4-CBC-CTS for filenames |
| 346 | 346 |
| 347Note: in the API, "CBC" means CBC-ESSIV, and "CTS" means CBC-CTS. 348So, for example, FSCRYPT_MODE_AES_256_CTS means AES-256-CBC-CTS. 349 |
|
| 347Authenticated encryption modes are not currently supported because of 348the difficulty of dealing with ciphertext expansion. Therefore, 349contents encryption uses a block cipher in `XTS mode 350<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or 351`CBC-ESSIV mode 352<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_, 353or a wide-block cipher. Filenames encryption uses a | 350Authenticated encryption modes are not currently supported because of 351the difficulty of dealing with ciphertext expansion. Therefore, 352contents encryption uses a block cipher in `XTS mode 353<https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS>`_ or 354`CBC-ESSIV mode 355<https://en.wikipedia.org/wiki/Disk_encryption_theory#Encrypted_salt-sector_initialization_vector_(ESSIV)>`_, 356or a wide-block cipher. Filenames encryption uses a |
| 354block cipher in `CTS-CBC mode | 357block cipher in `CBC-CTS mode |
| 355<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block 356cipher. 357 | 358<https://en.wikipedia.org/wiki/Ciphertext_stealing>`_ or a wide-block 359cipher. 360 |
| 358The (AES-256-XTS, AES-256-CTS-CBC) pair is the recommended default. | 361The (AES-256-XTS, AES-256-CBC-CTS) pair is the recommended default. |
| 359It is also the only option that is *guaranteed* to always be supported 360if the kernel supports fscrypt at all; see `Kernel config options`_. 361 362The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that 363upgrades the filenames encryption to use a wide-block cipher. (A 364*wide-block cipher*, also called a tweakable super-pseudorandom 365permutation, has the property that changing one bit scrambles the 366entire result.) As described in `Filenames encryption`_, a wide-block | 362It is also the only option that is *guaranteed* to always be supported 363if the kernel supports fscrypt at all; see `Kernel config options`_. 364 365The (AES-256-XTS, AES-256-HCTR2) pair is also a good choice that 366upgrades the filenames encryption to use a wide-block cipher. (A 367*wide-block cipher*, also called a tweakable super-pseudorandom 368permutation, has the property that changing one bit scrambles the 369entire result.) As described in `Filenames encryption`_, a wide-block |
| 367cipher is the ideal mode for the problem domain, though CTS-CBC is the | 370cipher is the ideal mode for the problem domain, though CBC-CTS is the |
| 368"least bad" choice among the alternatives. For more information about 369HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_. 370 371Adiantum is recommended on systems where AES is too slow due to lack 372of hardware acceleration for AES. Adiantum is a wide-block cipher 373that uses XChaCha12 and AES-256 as its underlying components. Most of 374the work is done by XChaCha12, which is much faster than AES when AES 375acceleration is unavailable. For more information about Adiantum, see 376`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_. 377 | 371"least bad" choice among the alternatives. For more information about 372HCTR2, see `the HCTR2 paper <https://eprint.iacr.org/2021/1441.pdf>`_. 373 374Adiantum is recommended on systems where AES is too slow due to lack 375of hardware acceleration for AES. Adiantum is a wide-block cipher 376that uses XChaCha12 and AES-256 as its underlying components. Most of 377the work is done by XChaCha12, which is much faster than AES when AES 378acceleration is unavailable. For more information about Adiantum, see 379`the Adiantum paper <https://eprint.iacr.org/2018/720.pdf>`_. 380 |
| 378The (AES-128-CBC-ESSIV, AES-128-CTS-CBC) pair exists only to support | 381The (AES-128-CBC-ESSIV, AES-128-CBC-CTS) pair exists only to support |
| 379systems whose only form of AES acceleration is an off-CPU crypto 380accelerator such as CAAM or CESA that does not support XTS. 381 382The remaining mode pairs are the "national pride ciphers": 383 | 382systems whose only form of AES acceleration is an off-CPU crypto 383accelerator such as CAAM or CESA that does not support XTS. 384 385The remaining mode pairs are the "national pride ciphers": 386 |
| 384- (SM4-XTS, SM4-CTS-CBC) | 387- (SM4-XTS, SM4-CBC-CTS) |
| 385 386Generally speaking, these ciphers aren't "bad" per se, but they 387receive limited security review compared to the usual choices such as 388AES and ChaCha. They also don't bring much new to the table. It is 389suggested to only use these ciphers where their use is mandated. 390 391Kernel config options 392--------------------- 393 394Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in 395only the basic support from the crypto API needed to use AES-256-XTS | 388 389Generally speaking, these ciphers aren't "bad" per se, but they 390receive limited security review compared to the usual choices such as 391AES and ChaCha. They also don't bring much new to the table. It is 392suggested to only use these ciphers where their use is mandated. 393 394Kernel config options 395--------------------- 396 397Enabling fscrypt support (CONFIG_FS_ENCRYPTION) automatically pulls in 398only the basic support from the crypto API needed to use AES-256-XTS |
| 396and AES-256-CTS-CBC encryption. For optimal performance, it is | 399and AES-256-CBC-CTS encryption. For optimal performance, it is |
| 397strongly recommended to also enable any available platform-specific 398kconfig options that provide acceleration for the algorithm(s) you 399wish to use. Support for any "non-default" encryption modes typically 400requires extra kconfig options as well. 401 402Below, some relevant options are listed by encryption mode. Note, 403acceleration options not listed below may be available for your 404platform; refer to the kconfig menus. File contents encryption can 405also be configured to use inline encryption hardware instead of the 406kernel crypto API (see `Inline encryption support`_); in that case, 407the file contents mode doesn't need to supported in the kernel crypto 408API, but the filenames mode still does. 409 | 400strongly recommended to also enable any available platform-specific 401kconfig options that provide acceleration for the algorithm(s) you 402wish to use. Support for any "non-default" encryption modes typically 403requires extra kconfig options as well. 404 405Below, some relevant options are listed by encryption mode. Note, 406acceleration options not listed below may be available for your 407platform; refer to the kconfig menus. File contents encryption can 408also be configured to use inline encryption hardware instead of the 409kernel crypto API (see `Inline encryption support`_); in that case, 410the file contents mode doesn't need to supported in the kernel crypto 411API, but the filenames mode still does. 412 |
| 410- AES-256-XTS and AES-256-CTS-CBC | 413- AES-256-XTS and AES-256-CBC-CTS |
| 411 - Recommended: 412 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK 413 - x86: CONFIG_CRYPTO_AES_NI_INTEL 414 415- AES-256-HCTR2 416 - Mandatory: 417 - CONFIG_CRYPTO_HCTR2 418 - Recommended: --- 9 unchanged lines hidden (view full) --- 428 - arm32: CONFIG_CRYPTO_CHACHA20_NEON 429 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON 430 - arm64: CONFIG_CRYPTO_CHACHA20_NEON 431 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON 432 - x86: CONFIG_CRYPTO_CHACHA20_X86_64 433 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 434 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 435 | 414 - Recommended: 415 - arm64: CONFIG_CRYPTO_AES_ARM64_CE_BLK 416 - x86: CONFIG_CRYPTO_AES_NI_INTEL 417 418- AES-256-HCTR2 419 - Mandatory: 420 - CONFIG_CRYPTO_HCTR2 421 - Recommended: --- 9 unchanged lines hidden (view full) --- 431 - arm32: CONFIG_CRYPTO_CHACHA20_NEON 432 - arm32: CONFIG_CRYPTO_NHPOLY1305_NEON 433 - arm64: CONFIG_CRYPTO_CHACHA20_NEON 434 - arm64: CONFIG_CRYPTO_NHPOLY1305_NEON 435 - x86: CONFIG_CRYPTO_CHACHA20_X86_64 436 - x86: CONFIG_CRYPTO_NHPOLY1305_SSE2 437 - x86: CONFIG_CRYPTO_NHPOLY1305_AVX2 438 |
| 436- AES-128-CBC-ESSIV and AES-128-CTS-CBC: | 439- AES-128-CBC-ESSIV and AES-128-CBC-CTS: |
| 437 - Mandatory: 438 - CONFIG_CRYPTO_ESSIV 439 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation 440 - Recommended: 441 - AES-CBC acceleration 442 443fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512 444acceleration is recommended: --- 71 unchanged lines hidden (view full) --- 516filenames of up to 255 bytes, the same IV is used for every filename 517in a directory. 518 519However, each encrypted directory still uses a unique key, or 520alternatively has the file's nonce (for `DIRECT_KEY policies`_) or 521inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. 522Thus, IV reuse is limited to within a single directory. 523 | 440 - Mandatory: 441 - CONFIG_CRYPTO_ESSIV 442 - CONFIG_CRYPTO_SHA256 or another SHA-256 implementation 443 - Recommended: 444 - AES-CBC acceleration 445 446fscrypt also uses HMAC-SHA512 for key derivation, so enabling SHA-512 447acceleration is recommended: --- 71 unchanged lines hidden (view full) --- 519filenames of up to 255 bytes, the same IV is used for every filename 520in a directory. 521 522However, each encrypted directory still uses a unique key, or 523alternatively has the file's nonce (for `DIRECT_KEY policies`_) or 524inode number (for `IV_INO_LBLK_64 policies`_) included in the IVs. 525Thus, IV reuse is limited to within a single directory. 526 |
| 524With CTS-CBC, the IV reuse means that when the plaintext filenames share a | 527With CBC-CTS, the IV reuse means that when the plaintext filenames share a |
| 525common prefix at least as long as the cipher block size (16 bytes for AES), the 526corresponding encrypted filenames will also share a common prefix. This is 527undesirable. Adiantum and HCTR2 do not have this weakness, as they are 528wide-block encryption modes. 529 530All supported filenames encryption modes accept any plaintext length 531>= 16 bytes; cipher block alignment is not required. However, 532filenames shorter than 16 bytes are NUL-padded to 16 bytes before --- 972 unchanged lines hidden --- | 528common prefix at least as long as the cipher block size (16 bytes for AES), the 529corresponding encrypted filenames will also share a common prefix. This is 530undesirable. Adiantum and HCTR2 do not have this weakness, as they are 531wide-block encryption modes. 532 533All supported filenames encryption modes accept any plaintext length 534>= 16 bytes; cipher block alignment is not required. However, 535filenames shorter than 16 bytes are NUL-padded to 16 bytes before --- 972 unchanged lines hidden --- |