Re: [PATCH 02/33] lib/crypto: aes: Add ECB support

[Eric Biggers <ebiggers@kernel.org>]

On Tue, Jul 07, 2026 at 03:59:24PM +0200, Thomas Huth wrote:
> > +Unauthenticated encryption
> > +==========================
> > +
> > +Support for unauthenticated encryption and decryption, including bare stream
> > +ciphers and other length-preserving algorithms such as block ciphers in XTS
> > +mode.
> 
> This sentence no verb?

It's a noun phrase that introduces what the section contains, before
transitioning into full sentences.

I used this in all existing Documentation/crypto/libcrypto-*.rst.  It's
also fairly common in the help text for kconfig symbols (across the
kernel, not just the kconfig help text I've written).

I guess it's a bad practice.  But if we go with something else here,
like "These functions provide support for ...", I should update the
existing libcrypto-*.rst too.

> > +void aes_ecb_encrypt(u8 *dst, const u8 *src, size_t len, aes_encrypt_arg key);
> 
> Other similar functions like aes_encrypt() use the key as first argument ...
> so maybe do the same here, too, for consistency?

For single-block AES, there's indeed already aes_encrypt(key, dst, src)
and aes_decrypt(key, dst, src).  But for actual AEAD encryption there's
already:

    chacha20poly1305_encrypt(dst, src, src_len, ad, ad_len, nonce, key)
    chacha20poly1305_decrypt(dst, src, src_len, ad, ad_len, nonce, key)
    xchacha20poly1305_encrypt(dst, src, src_len, ad, ad_len, nonce, key)
    xchacha20poly1305_decrypt(dst, src, src_len, ad, ad_len, nonce, key)
    chacha20poly1305_encrypt_sg_inplace(src, src_len, ad, ad_len, nonce, key)
    chacha20poly1305_decrypt_sg_inplace(src, src_len, ad, ad_len, nonce, key)

Those follow the convention described by Jason here:
https://lore.kernel.org/linux-crypto/aPT3dImhaI6Dpqs7@zx2c4.com/

This series prioritizes consistency with those (and other functions
taking [dst, src, len]] such as memcpy() and crypto_xor()), adding:

    aes_ecb_encrypt(dst, src, len, key);
    aes_ecb_decrypt(dst, src, len, key);
    aes_cbc_encrypt(dst, src, len, iv, key);
    aes_cbc_decrypt(dst, src, len, iv, key);
    aes_cbc_cts_encrypt(dst, src, len, iv, key);
    aes_cbc_cts_decrypt(dst, src, len, iv, key);
    aes_ctr(dst, src, len, ctr, key);
    aes_xctr(dst, src, len, ctr, iv, key);
    aes_xts_encrypt(dst, src, len, tweak, key, cont);
    aes_xts_decrypt(dst, src, len, tweak, key, cont);
    aes_gcm_encrypt(dst, authtag, src, data_len, ad, ad_len, nonce, key)
    aes_gcm_decrypt(dst, src, authtag, data_len, ad, ad_len, nonce, key)
    aes_ccm_encrypt(dst, authtag, src, data_len, ad, ad_len, nonce, nonce_len, key)
    aes_ccm_decrypt(dst, src, authtag, data_len, ad, ad_len, nonce, nonce_len, key)

(Side note: looking at it again, the last four maybe should all use
[dst, src, data_len, authtag].  In this series, the authtag is instead
grouped with the src or dst to which it's usually concatenated.)

If key is put at the beginning instead, it then raises the question of
why should it be different from nonce/iv/ctr and (ad, ad_len).  So would
it really be:

    aes_gcm_encrypt(key, dst, authtag, src, data_len, ad, ad_len, nonce)

... or would it actually be something like:

    aes_gcm_encrypt(key, nonce, ad, ad_len, dst, authtag, src, data_len)

It's conventional to put "the object being operated on" at the
beginning, which could be argued to apply to the key.  But alternatively
the key could just be considered another input.  crypto_skcipher was
"object-like"; however, with the library the key is a simple struct, or
even just a byte array in the case of ChaCha20Poly1305.

There's no single right answer here.  But we should consider the full
picture including the chacha20poly1305 functions.  The (dst, src, len,
auxiliary stuff) order also helps for things like the AES_CRYPT_SG macro
in crypto/aes.c, as the "auxiliary stuff" is together and at the end.

Note that if we decide we like this order, we could reorder the
arguments of aes_encrypt() and aes_decrypt() to match.

Maybe let's see what other people prefer?

- Eric