--- /dev/null
- Nettle (http://www.lysator.liu.se/~nisse/nettle/)
+ .. SPDX-License-Identifier: GPL-2.0
+
+ =============================
+ Scatterlist Cryptographic API
+ =============================
+
+ Introduction
+ ============
+
+ The Scatterlist Crypto API takes page vectors (scatterlists) as
+ arguments, and works directly on pages. In some cases (e.g. ECB
+ mode ciphers), this will allow for pages to be encrypted in-place
+ with no copying.
+
+ One of the initial goals of this design was to readily support IPsec,
+ so that processing can be applied to paged skb's without the need
+ for linearization.
+
+
+ Details
+ =======
+
+ At the lowest level are algorithms, which register dynamically with the
+ API.
+
+ 'Transforms' are user-instantiated objects, which maintain state, handle all
+ of the implementation logic (e.g. manipulating page vectors) and provide an
+ abstraction to the underlying algorithms. However, at the user
+ level they are very simple.
+
+ Conceptually, the API layering looks like this::
+
+ [transform api] (user interface)
+ [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
+ [algorithm api] (for registering algorithms)
+
+ The idea is to make the user interface and algorithm registration API
+ very simple, while hiding the core logic from both. Many good ideas
+ from existing APIs such as Cryptoapi and Nettle have been adapted for this.
+
+ The API currently supports five main types of transforms: AEAD (Authenticated
+ Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
+ Hashes.
+
+ Please note that Block Ciphers is somewhat of a misnomer. It is in fact
+ meant to support all ciphers including stream ciphers. The difference
+ between Block Ciphers and Ciphers is that the latter operates on exactly
+ one block while the former can operate on an arbitrary amount of data,
+ subject to block size requirements (i.e., non-stream ciphers can only
+ process multiples of blocks).
+
+ Here's an example of how to use the API::
+
+ #include <crypto/hash.h>
+ #include <linux/err.h>
+ #include <linux/scatterlist.h>
+
+ struct scatterlist sg[2];
+ char result[128];
+ struct crypto_ahash *tfm;
+ struct ahash_request *req;
+
+ tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
+ if (IS_ERR(tfm))
+ fail();
+
+ /* ... set up the scatterlists ... */
+
+ req = ahash_request_alloc(tfm, GFP_ATOMIC);
+ if (!req)
+ fail();
+
+ ahash_request_set_callback(req, 0, NULL, NULL);
+ ahash_request_set_crypt(req, sg, result, 2);
+
+ if (crypto_ahash_digest(req))
+ fail();
+
+ ahash_request_free(req);
+ crypto_free_ahash(tfm);
+
+
+ Many real examples are available in the regression test module (tcrypt.c).
+
+
+ Developer Notes
+ ===============
+
+ Transforms may only be allocated in user context, and cryptographic
+ methods may only be called from softirq and user contexts. For
+ transforms with a setkey method it too should only be called from
+ user context.
+
+ When using the API for ciphers, performance will be optimal if each
+ scatterlist contains data which is a multiple of the cipher's block
+ size (typically 8 bytes). This prevents having to do any copying
+ across non-aligned page fragment boundaries.
+
+
+ Adding New Algorithms
+ =====================
+
+ When submitting a new algorithm for inclusion, a mandatory requirement
+ is that at least a few test vectors from known sources (preferably
+ standards) be included.
+
+ Converting existing well known code is preferred, as it is more likely
+ to have been reviewed and widely tested. If submitting code from LGPL
+ sources, please consider changing the license to GPL (see section 3 of
+ the LGPL).
+
+ Algorithms submitted must also be generally patent-free (e.g. IDEA
+ will not be included in the mainline until around 2011), and be based
+ on a recognized standard and/or have been subjected to appropriate
+ peer review.
+
+ Also check for any RFCs which may relate to the use of specific algorithms,
+ as well as general application notes such as RFC2451 ("The ESP CBC-Mode
+ Cipher Algorithms").
+
+ It's a good idea to avoid using lots of macros and use inlined functions
+ instead, as gcc does a good job with inlining, while excessive use of
+ macros can cause compilation problems on some platforms.
+
+ Also check the TODO list at the web site listed below to see what people
+ might already be working on.
+
+
+ Bugs
+ ====
+
+ Send bug reports to:
+ linux-crypto@vger.kernel.org
+
+ Cc:
+ Herbert Xu <herbert@gondor.apana.org.au>,
+ David S. Miller <davem@redhat.com>
+
+
+ Further Information
+ ===================
+
+ For further patches and various updates, including the current TODO
+ list, see:
+ http://gondor.apana.org.au/~herbert/crypto/
+
+
+ Authors
+ =======
+
+ - James Morris
+ - David S. Miller
+ - Herbert Xu
+
+
+ Credits
+ =======
+
+ The following people provided invaluable feedback during the development
+ of the API:
+
+ - Alexey Kuznetzov
+ - Rusty Russell
+ - Herbert Valerio Riedel
+ - Jeff Garzik
+ - Michael Richardson
+ - Andrew Morton
+ - Ingo Oeser
+ - Christoph Hellwig
+
+ Portions of this API were derived from the following projects:
+
+ Kerneli Cryptoapi (http://www.kerneli.org/)
+ - Alexander Kjeldaas
+ - Herbert Valerio Riedel
+ - Kyle McMartin
+ - Jean-Luc Cooke
+ - David Bryson
+ - Clemens Fruhwirth
+ - Tobias Ringstrom
+ - Harald Welte
+
+ and;
+
++ Nettle (https://www.lysator.liu.se/~nisse/nettle/)
+ - Niels Möller
+
+ Original developers of the crypto algorithms:
+
+ - Dana L. How (DES)
+ - Andrew Tridgell and Steve French (MD4)
+ - Colin Plumb (MD5)
+ - Steve Reid (SHA1)
+ - Jean-Luc Cooke (SHA256, SHA384, SHA512)
+ - Kazunori Miyazawa / USAGI (HMAC)
+ - Matthew Skala (Twofish)
+ - Dag Arne Osvik (Serpent)
+ - Brian Gladman (AES)
+ - Kartikey Mahendra Bhatt (CAST6)
+ - Jon Oberheide (ARC4)
+ - Jouni Malinen (Michael MIC)
+ - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
+
+ SHA1 algorithm contributors:
+ - Jean-Francois Dive
+
+ DES algorithm contributors:
+ - Raimar Falke
+ - Gisle Sælensminde
+ - Niels Möller
+
+ Blowfish algorithm contributors:
+ - Herbert Valerio Riedel
+ - Kyle McMartin
+
+ Twofish algorithm contributors:
+ - Werner Koch
+ - Marc Mutz
+
+ SHA256/384/512 algorithm contributors:
+ - Andrew McDonald
+ - Kyle McMartin
+ - Herbert Valerio Riedel
+
+ AES algorithm contributors:
+ - Alexander Kjeldaas
+ - Herbert Valerio Riedel
+ - Kyle McMartin
+ - Adam J. Richter
+ - Fruhwirth Clemens (i586)
+ - Linus Torvalds (i586)
+
+ CAST5 algorithm contributors:
+ - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
+
+ TEA/XTEA algorithm contributors:
+ - Aaron Grothe
+ - Michael Ringe
+
+ Khazad algorithm contributors:
+ - Aaron Grothe
+
+ Whirlpool algorithm contributors:
+ - Aaron Grothe
+ - Jean-Luc Cooke
+
+ Anubis algorithm contributors:
+ - Aaron Grothe
+
+ Tiger algorithm contributors:
+ - Aaron Grothe
+
+ VIA PadLock contributors:
+ - Michal Ludvig
+
+ Camellia algorithm contributors:
+ - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
+
+ Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com>
+
+ Please send any credits updates or corrections to:
+ Herbert Xu <herbert@gondor.apana.org.au>
=============
- ====================== ============================================================
- background_gc=%s Turn on/off cleaning operations, namely garbage
- collection, triggered in background when I/O subsystem is
- idle. If background_gc=on, it will turn on the garbage
- collection and if background_gc=off, garbage collection
- will be turned off. If background_gc=sync, it will turn
- on synchronous garbage collection running in background.
- Default value for this option is on. So garbage
- collection is on by default.
- disable_roll_forward Disable the roll-forward recovery routine
- norecovery Disable the roll-forward recovery routine, mounted read-
- only (i.e., -o ro,disable_roll_forward)
- discard/nodiscard Enable/disable real-time discard in f2fs, if discard is
- enabled, f2fs will issue discard/TRIM commands when a
- segment is cleaned.
- no_heap Disable heap-style segment allocation which finds free
- segments for data from the beginning of main area, while
- for node from the end of main area.
- nouser_xattr Disable Extended User Attributes. Note: xattr is enabled
- by default if CONFIG_F2FS_FS_XATTR is selected.
- noacl Disable POSIX Access Control List. Note: acl is enabled
- by default if CONFIG_F2FS_FS_POSIX_ACL is selected.
- active_logs=%u Support configuring the number of active logs. In the
- current design, f2fs supports only 2, 4, and 6 logs.
- Default number is 6.
- disable_ext_identify Disable the extension list configured by mkfs, so f2fs
- does not aware of cold files such as media files.
- inline_xattr Enable the inline xattrs feature.
- noinline_xattr Disable the inline xattrs feature.
- inline_xattr_size=%u Support configuring inline xattr size, it depends on
- flexible inline xattr feature.
- inline_data Enable the inline data feature: New created small(<~3.4k)
- files can be written into inode block.
- inline_dentry Enable the inline dir feature: data in new created
- directory entries can be written into inode block. The
- space of inode block which is used to store inline
- dentries is limited to ~3.4k.
- noinline_dentry Disable the inline dentry feature.
- flush_merge Merge concurrent cache_flush commands as much as possible
- to eliminate redundant command issues. If the underlying
- device handles the cache_flush command relatively slowly,
- recommend to enable this option.
- nobarrier This option can be used if underlying storage guarantees
- its cached data should be written to the novolatile area.
- If this option is set, no cache_flush commands are issued
- but f2fs still guarantees the write ordering of all the
- data writes.
- fastboot This option is used when a system wants to reduce mount
- time as much as possible, even though normal performance
- can be sacrificed.
- extent_cache Enable an extent cache based on rb-tree, it can cache
- as many as extent which map between contiguous logical
- address and physical address per inode, resulting in
- increasing the cache hit ratio. Set by default.
- noextent_cache Disable an extent cache based on rb-tree explicitly, see
- the above extent_cache mount option.
- noinline_data Disable the inline data feature, inline data feature is
- enabled by default.
- data_flush Enable data flushing before checkpoint in order to
- persist data of regular and symlink.
- reserve_root=%d Support configuring reserved space which is used for
- allocation from a privileged user with specified uid or
- gid, unit: 4KB, the default limit is 0.2% of user blocks.
- resuid=%d The user ID which may use the reserved blocks.
- resgid=%d The group ID which may use the reserved blocks.
- fault_injection=%d Enable fault injection in all supported types with
- specified injection rate.
- fault_type=%d Support configuring fault injection type, should be
- enabled with fault_injection option, fault type value
- is shown below, it supports single or combined type.
+ ======================== ============================================================
+ background_gc=%s Turn on/off cleaning operations, namely garbage
+ collection, triggered in background when I/O subsystem is
+ idle. If background_gc=on, it will turn on the garbage
+ collection and if background_gc=off, garbage collection
+ will be turned off. If background_gc=sync, it will turn
+ on synchronous garbage collection running in background.
+ Default value for this option is on. So garbage
+ collection is on by default.
+ disable_roll_forward Disable the roll-forward recovery routine
+ norecovery Disable the roll-forward recovery routine, mounted read-
+ only (i.e., -o ro,disable_roll_forward)
+ discard/nodiscard Enable/disable real-time discard in f2fs, if discard is
+ enabled, f2fs will issue discard/TRIM commands when a
+ segment is cleaned.
+ no_heap Disable heap-style segment allocation which finds free
+ segments for data from the beginning of main area, while
+ for node from the end of main area.
+ nouser_xattr Disable Extended User Attributes. Note: xattr is enabled
+ by default if CONFIG_F2FS_FS_XATTR is selected.
+ noacl Disable POSIX Access Control List. Note: acl is enabled
+ by default if CONFIG_F2FS_FS_POSIX_ACL is selected.
+ active_logs=%u Support configuring the number of active logs. In the
+ current design, f2fs supports only 2, 4, and 6 logs.
+ Default number is 6.
+ disable_ext_identify Disable the extension list configured by mkfs, so f2fs
+ does not aware of cold files such as media files.
+ inline_xattr Enable the inline xattrs feature.
+ noinline_xattr Disable the inline xattrs feature.
+ inline_xattr_size=%u Support configuring inline xattr size, it depends on
+ flexible inline xattr feature.
+ inline_data Enable the inline data feature: New created small(<~3.4k)
+ files can be written into inode block.
+ inline_dentry Enable the inline dir feature: data in new created
+ directory entries can be written into inode block. The
+ space of inode block which is used to store inline
+ dentries is limited to ~3.4k.
+ noinline_dentry Disable the inline dentry feature.
+ flush_merge Merge concurrent cache_flush commands as much as possible
+ to eliminate redundant command issues. If the underlying
+ device handles the cache_flush command relatively slowly,
+ recommend to enable this option.
+ nobarrier This option can be used if underlying storage guarantees
+ its cached data should be written to the novolatile area.
+ If this option is set, no cache_flush commands are issued
+ but f2fs still guarantees the write ordering of all the
+ data writes.
+ fastboot This option is used when a system wants to reduce mount
+ time as much as possible, even though normal performance
+ can be sacrificed.
+ extent_cache Enable an extent cache based on rb-tree, it can cache
+ as many as extent which map between contiguous logical
+ address and physical address per inode, resulting in
+ increasing the cache hit ratio. Set by default.
+ noextent_cache Disable an extent cache based on rb-tree explicitly, see
+ the above extent_cache mount option.
+ noinline_data Disable the inline data feature, inline data feature is
+ enabled by default.
+ data_flush Enable data flushing before checkpoint in order to
+ persist data of regular and symlink.
+ reserve_root=%d Support configuring reserved space which is used for
+ allocation from a privileged user with specified uid or
+ gid, unit: 4KB, the default limit is 0.2% of user blocks.
+ resuid=%d The user ID which may use the reserved blocks.
+ resgid=%d The group ID which may use the reserved blocks.
+ fault_injection=%d Enable fault injection in all supported types with
+ specified injection rate.
+ fault_type=%d Support configuring fault injection type, should be
+ enabled with fault_injection option, fault type value
+ is shown below, it supports single or combined type.
- =================== ===========
- Type_Name Type_Value
- =================== ===========
- FAULT_KMALLOC 0x000000001
- FAULT_KVMALLOC 0x000000002
- FAULT_PAGE_ALLOC 0x000000004
- FAULT_PAGE_GET 0x000000008
- FAULT_ALLOC_BIO 0x000000010
- FAULT_ALLOC_NID 0x000000020
- FAULT_ORPHAN 0x000000040
- FAULT_BLOCK 0x000000080
- FAULT_DIR_DEPTH 0x000000100
- FAULT_EVICT_INODE 0x000000200
- FAULT_TRUNCATE 0x000000400
- FAULT_READ_IO 0x000000800
- FAULT_CHECKPOINT 0x000001000
- FAULT_DISCARD 0x000002000
- FAULT_WRITE_IO 0x000004000
- =================== ===========
- mode=%s Control block allocation mode which supports "adaptive"
- and "lfs". In "lfs" mode, there should be no random
- writes towards main area.
- io_bits=%u Set the bit size of write IO requests. It should be set
- with "mode=lfs".
- usrquota Enable plain user disk quota accounting.
- grpquota Enable plain group disk quota accounting.
- prjquota Enable plain project quota accounting.
- usrjquota=<file> Appoint specified file and type during mount, so that quota
- grpjquota=<file> information can be properly updated during recovery flow,
- prjjquota=<file> <quota file>: must be in root directory;
- jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1].
- offusrjquota Turn off user journelled quota.
- offgrpjquota Turn off group journelled quota.
- offprjjquota Turn off project journelled quota.
- quota Enable plain user disk quota accounting.
- noquota Disable all plain disk quota option.
- whint_mode=%s Control which write hints are passed down to block
- layer. This supports "off", "user-based", and
- "fs-based". In "off" mode (default), f2fs does not pass
- down hints. In "user-based" mode, f2fs tries to pass
- down hints given by users. And in "fs-based" mode, f2fs
- passes down hints with its policy.
- alloc_mode=%s Adjust block allocation policy, which supports "reuse"
- and "default".
- fsync_mode=%s Control the policy of fsync. Currently supports "posix",
- "strict", and "nobarrier". In "posix" mode, which is
- default, fsync will follow POSIX semantics and does a
- light operation to improve the filesystem performance.
- In "strict" mode, fsync will be heavy and behaves in line
- with xfs, ext4 and btrfs, where xfstest generic/342 will
- pass, but the performance will regress. "nobarrier" is
- based on "posix", but doesn't issue flush command for
- non-atomic files likewise "nobarrier" mount option.
+ =================== ===========
+ Type_Name Type_Value
+ =================== ===========
+ FAULT_KMALLOC 0x000000001
+ FAULT_KVMALLOC 0x000000002
+ FAULT_PAGE_ALLOC 0x000000004
+ FAULT_PAGE_GET 0x000000008
+ FAULT_ALLOC_BIO 0x000000010
+ FAULT_ALLOC_NID 0x000000020
+ FAULT_ORPHAN 0x000000040
+ FAULT_BLOCK 0x000000080
+ FAULT_DIR_DEPTH 0x000000100
+ FAULT_EVICT_INODE 0x000000200
+ FAULT_TRUNCATE 0x000000400
+ FAULT_READ_IO 0x000000800
+ FAULT_CHECKPOINT 0x000001000
+ FAULT_DISCARD 0x000002000
+ FAULT_WRITE_IO 0x000004000
+ =================== ===========
+ mode=%s Control block allocation mode which supports "adaptive"
+ and "lfs". In "lfs" mode, there should be no random
+ writes towards main area.
+ io_bits=%u Set the bit size of write IO requests. It should be set
+ with "mode=lfs".
+ usrquota Enable plain user disk quota accounting.
+ grpquota Enable plain group disk quota accounting.
+ prjquota Enable plain project quota accounting.
+ usrjquota=<file> Appoint specified file and type during mount, so that quota
+ grpjquota=<file> information can be properly updated during recovery flow,
+ prjjquota=<file> <quota file>: must be in root directory;
+ jqfmt=<quota type> <quota type>: [vfsold,vfsv0,vfsv1].
+ offusrjquota Turn off user journelled quota.
+ offgrpjquota Turn off group journelled quota.
+ offprjjquota Turn off project journelled quota.
+ quota Enable plain user disk quota accounting.
+ noquota Disable all plain disk quota option.
+ whint_mode=%s Control which write hints are passed down to block
+ layer. This supports "off", "user-based", and
+ "fs-based". In "off" mode (default), f2fs does not pass
+ down hints. In "user-based" mode, f2fs tries to pass
+ down hints given by users. And in "fs-based" mode, f2fs
+ passes down hints with its policy.
+ alloc_mode=%s Adjust block allocation policy, which supports "reuse"
+ and "default".
+ fsync_mode=%s Control the policy of fsync. Currently supports "posix",
+ "strict", and "nobarrier". In "posix" mode, which is
+ default, fsync will follow POSIX semantics and does a
+ light operation to improve the filesystem performance.
+ In "strict" mode, fsync will be heavy and behaves in line
+ with xfs, ext4 and btrfs, where xfstest generic/342 will
+ pass, but the performance will regress. "nobarrier" is
+ based on "posix", but doesn't issue flush command for
+ non-atomic files likewise "nobarrier" mount option.
test_dummy_encryption
test_dummy_encryption=%s
- Enable dummy encryption, which provides a fake fscrypt
- context. The fake fscrypt context is used by xfstests.
- The argument may be either "v1" or "v2", in order to
- select the corresponding fscrypt policy version.
- checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable"
- to reenable checkpointing. Is enabled by default. While
- disabled, any unmounting or unexpected shutdowns will cause
- the filesystem contents to appear as they did when the
- filesystem was mounted with that option.
- While mounting with checkpoint=disabled, the filesystem must
- run garbage collection to ensure that all available space can
- be used. If this takes too much time, the mount may return
- EAGAIN. You may optionally add a value to indicate how much
- of the disk you would be willing to temporarily give up to
- avoid additional garbage collection. This can be given as a
- number of blocks, or as a percent. For instance, mounting
- with checkpoint=disable:100% would always succeed, but it may
- hide up to all remaining free space. The actual space that
- would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable
- This space is reclaimed once checkpoint=enable.
- compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo",
- "lz4", "zstd" and "lzo-rle" algorithm.
- compress_log_size=%u Support configuring compress cluster size, the size will
- be 4KB * (1 << %u), 16KB is minimum size, also it's
- default size.
- compress_extension=%s Support adding specified extension, so that f2fs can enable
- compression on those corresponding files, e.g. if all files
- with '.ext' has high compression rate, we can set the '.ext'
- on compression extension list and enable compression on
- these file by default rather than to enable it via ioctl.
- For other files, we can still enable compression via ioctl.
- inlinecrypt
- When possible, encrypt/decrypt the contents of encrypted
- files using the blk-crypto framework rather than
- filesystem-layer encryption. This allows the use of
- inline encryption hardware. The on-disk format is
- unaffected. For more details, see
- Documentation/block/inline-encryption.rst.
- ====================== ============================================================
+ Enable dummy encryption, which provides a fake fscrypt
+ context. The fake fscrypt context is used by xfstests.
+ The argument may be either "v1" or "v2", in order to
+ select the corresponding fscrypt policy version.
+ checkpoint=%s[:%u[%]] Set to "disable" to turn off checkpointing. Set to "enable"
+ to reenable checkpointing. Is enabled by default. While
+ disabled, any unmounting or unexpected shutdowns will cause
+ the filesystem contents to appear as they did when the
+ filesystem was mounted with that option.
+ While mounting with checkpoint=disabled, the filesystem must
+ run garbage collection to ensure that all available space can
+ be used. If this takes too much time, the mount may return
+ EAGAIN. You may optionally add a value to indicate how much
+ of the disk you would be willing to temporarily give up to
+ avoid additional garbage collection. This can be given as a
+ number of blocks, or as a percent. For instance, mounting
+ with checkpoint=disable:100% would always succeed, but it may
+ hide up to all remaining free space. The actual space that
+ would be unusable can be viewed at /sys/fs/f2fs/<disk>/unusable
+ This space is reclaimed once checkpoint=enable.
+ compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo",
+ "lz4", "zstd" and "lzo-rle" algorithm.
+ compress_log_size=%u Support configuring compress cluster size, the size will
+ be 4KB * (1 << %u), 16KB is minimum size, also it's
+ default size.
+ compress_extension=%s Support adding specified extension, so that f2fs can enable
+ compression on those corresponding files, e.g. if all files
+ with '.ext' has high compression rate, we can set the '.ext'
+ on compression extension list and enable compression on
+ these file by default rather than to enable it via ioctl.
+ For other files, we can still enable compression via ioctl.
++inlinecrypt When possible, encrypt/decrypt the contents of encrypted
++ files using the blk-crypto framework rather than
++ filesystem-layer encryption. This allows the use of
++ inline encryption hardware. The on-disk format is
++ unaffected. For more details, see
++ Documentation/block/inline-encryption.rst.
+ ======================== ============================================================
Debugfs Entries
===============
projects / kernel.git / commitdiff