crypto: doc - improve the skcipher API example code

Rewrite the skcipher API example, changing it to encrypt a buffer with
AES-256-XTS. This addresses various problems with the previous example:

-

crypto: doc - improve the skcipher API example code

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 <[email protected]>
Acked-by: Ard Biesheuvel <[email protected]>
Signed-off-by: Herbert Xu <[email protected]>

show more ...

crypto: shash - remove shash_desc::flags

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 algori

crypto: shash - remove shash_desc::flags

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 <[email protected]>
Signed-off-by: Herbert Xu <[email protected]>

show more ...

crypto: remove redundant type flags from tfm allocation

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
CR

crypto: remove redundant type flags from tfm allocation

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 <[email protected]>
Signed-off-by: Herbert Xu <[email protected]>

show more ...

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

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 fixe

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

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 <[email protected]>
Signed-off-by: Herbert Xu <[email protected]>

show more ...

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

- Fixed bugs in example for shash and rng (added missing "*" and " *").
- Corrected pr_info() in calc_hash().
- Added example usage of c

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

- 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 <[email protected]>
Signed-off-by: Herbert Xu <[email protected]>

show more ...

crypto: doc - fix typo (struct sdesc)

Add missing " " in api-samples.rst

Signed-off-by: Fabien Dessenne <[email protected]>
Signed-off-by: Herbert Xu <[email protected]>

crypto: doc - convert crypto API documentation to Sphinx

With the conversion of the kernel crypto API DocBook to Sphinx, the
monolithic document is broken up into individual documents. The
documenta

crypto: doc - convert crypto API documentation to Sphinx

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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...