kernel/linux.git/Documentation/crypto/api-samples.rst, branch v6.6.132

crypto: doc - improve the skcipher API example code

2019-06-13T06:31:40+00:00

Rewrite the skcipher API example, changing it to encrypt a buffer with AES-256-XTS. This addresses various problems with the previous example: - It requests a specific driver "cbc-aes-aesni", which is unusual. Normally users ask for "cbc(aes)", not a specific driver. - It encrypts only a single AES block. For the reader, that doesn't clearly distinguish the "skcipher" API from the "cipher" API. - Showing how to encrypt something with bare CBC is arguably a poor choice of example, as it doesn't follow modern crypto trends. Now, usually authenticated encryption is recommended, in which case the user would use the AEAD API, not skcipher. Disk encryption is still a legitimate use for skcipher, but for that usually XTS is recommended. - Many other bugs and poor coding practices, such as not setting CRYPTO_TFM_REQ_MAY_SLEEP, unnecessarily allocating a heap buffer for the IV, unnecessary NULL checks, using a pointless wrapper struct, and forgetting to set an error code in one case. Signed-off-by: Eric Biggers Acked-by: Ard Biesheuvel Signed-off-by: Herbert Xu

crypto: shash - remove shash_desc::flags

2019-04-25T07:38:12+00:00

The flags field in 'struct shash_desc' never actually does anything. The only ostensibly supported flag is CRYPTO_TFM_REQ_MAY_SLEEP. However, no shash algorithm ever sleeps, making this flag a no-op. With this being the case, inevitably some users who can't sleep wrongly pass MAY_SLEEP. These would all need to be fixed if any shash algorithm actually started sleeping. For example, the shash_ahash_*() functions, which wrap a shash algorithm with the ahash API, pass through MAY_SLEEP from the ahash API to the shash API. However, the shash functions are called under kmap_atomic(), so actually they're assumed to never sleep. Even if it turns out that some users do need preemption points while hashing large buffers, we could easily provide a helper function crypto_shash_update_large() which divides the data into smaller chunks and calls crypto_shash_update() and cond_resched() for each chunk. It's not necessary to have a flag in 'struct shash_desc', nor is it necessary to make individual shash algorithms aware of this at all. Therefore, remove shash_desc::flags, and document that the crypto_shash_*() functions can be called from any context. Signed-off-by: Eric Biggers Signed-off-by: Herbert Xu

crypto: remove redundant type flags from tfm allocation

2018-07-08T16:30:29+00:00

Some crypto API users allocating a tfm with crypto_alloc_$FOO() are also specifying the type flags for $FOO, e.g. crypto_alloc_shash() with CRYPTO_ALG_TYPE_SHASH. But, that's redundant since the crypto API will override any specified type flag/mask with the correct ones. So, remove the unneeded flags. This patch shouldn't change any actual behavior. Signed-off-by: Eric Biggers Signed-off-by: Herbert Xu

crypto: doc - adapt api sample to use async. op wait

2017-11-03T14:11:23+00:00

The code sample is waiting for an async. crypto op completion. Adapt sample to use the new generic infrastructure to do the same. This also fixes a possible data coruption bug created by the use of wait_for_completion_interruptible() without dealing correctly with an interrupt aborting the wait prior to the async op finishing. Signed-off-by: Gilad Ben-Yossef Signed-off-by: Herbert Xu

crypto: doc - Fixed bugs, added example usage of calc_hash().

2017-06-19T06:11:56+00:00

- Fixed bugs in example for shash and rng (added missing "*" and " *"). - Corrected pr_info() in calc_hash(). - Added example usage of calc_hash(). - No need for negate PTR_ERR to get error code, as crypto_alloc_rng already returns negative values like ERR_PTR(-ENOMEM). Fixed. Signed-off-by: Kamil Konieczny Signed-off-by: Herbert Xu

crypto: doc - fix typo (struct sdesc)

2017-03-16T09:58:57+00:00

Add missing " " in api-samples.rst Signed-off-by: Fabien Dessenne Signed-off-by: Herbert Xu

crypto: doc - convert crypto API documentation to Sphinx

2016-12-13T23:37:54+00:00

With the conversion of the kernel crypto API DocBook to Sphinx, the monolithic document is broken up into individual documents. The documentation is unchanged with the exception of a slight reordering to keep the individual document parts self-contained. Signed-off-by: Stephan Mueller Signed-off-by: Jonathan Corbet