Initial feature wishlist

[chrysn]

In this project, we will build an abstraction layer (as a Rust trait or family of traits) that provides the best of formally verified implementations and hardware cryptography to Rust programs. The actual operations will be performed through established Rust crypto traits; this is about representing a platform's provided operations. (Comparing to embedded-hal and Ariel OS, the existing traits are what embedded-hal is, whereas this project abstracts over what stm32-hal and nrf52-hal do for setting up GPIO pins etc).

In this issue, we collect wishlists of what this should do – well aware that part of all this will also be setting scope, but that doesn't need to stop us from wishes coming in.

My personal baseline, informed from the project setup, is:

• no_std _{[edit: added; can't believe I missed it, seemed so obvious but thanks Mališa for pointing it out]}
• Provide cryptographic primitives:
  • AEAD encryption/decryption
    • possibly composed of hardware encryption primitives combined with software extension, eg. combining hardware AES with software CCM
    • Ideally streaming AAD
    • Ideally even streaming data (eg. from a scatter-gather buffer), but that might be unrealistic
    • Do we need to split in-place/out-of-place operations? (My focus is on in-place)
  • ECDSA
    • Ideally with streaming AAD
  • ECDH
  • Cryptographic hashes (definitely streaming)
  • HKDF (not sure if extract/expand split is meaningful)
  • Possibly HPKE?
  • Possibly post-quantum mechanisms?
  • Maybe plain symmetric encryption (possibly expressed through COSE's deprecated algorithms mechanism, possibly using an extra mechanism; should have a unified mechanism for group OSCORE)
• Don't impose size limits that the user can not easily tune.
  • Where possible, avoid that the user needs to provide a buffer (through generics or already allocated) for intermediate operations. (👀 ECDSA AAD)
• Query algorithms / curves by COSE number, ideally in a const way.
• Provide associated types that users of the library can use to carry around any intermediate results they need (such that they don't need to know the supported algorithms and thus sizes explicitly).
• Allow backends to only give keys out by handle
• Actually hard decisions:
  • Handle exclusive access? This could be a conflict-heavy point, as users expect that backends to work on a &self (or even a Copy Self, which indeed many backends can provide), whereas some backends need a &mut and can only provide that if they manually and statefully lock themselves, and then enqueue operations (on the stack?) or fail them on reentrancy.
  • Some might want to use eg. signature operations in an async way.
• Maybe out of scope: Provide high-level COSE operations (COSE_Encrypt etc)
• Be usable as a backend for
  • EDHOC (lakers)
  • OSCORE (liboscore)
  • SUIT (Ariel OS)
  • Anything libcose is used for (especially if not listed above)

[chrysn]

It is open (but needs to be decided soon) whether there is to be any form to express particular algorithms in type state.

I lean towards not doing that: Supporting cryptographic agility is state of the art, and needed in all currently listed applications. Initial exploration also shows that this creates verbose and hard to use interfaces, hindering adoption, and that's even assuming that const_generic_exprs is stabilized (which it is far from). Nothing can really need a key in a particular format anyway (as secure elements may keep the key in a non-extractable form), only the output of operations on a key. And if someone really builds their system to support one and only one (say, signature) algorithm, then they can choose / configure the implementation of the interface such that it only has support for a single algorithm, in which case its "signature algorithm" associated type becomes a ZST, and the type for "a signature key in any supported algorithm" just becomes a newtype around the key itself, both resulting in zero-cost abstractions.

[edit:] See https://github.com/lake-rs/experiments-on-interfaces/tree/main/type-algorithms for experiments on that.

[chrysn]

To be explored with hardware examples: Which lower-layer primitives do we expect to be provided?

• AES for sure
• Are CCM and GCM things that there can be acceleration for that is not already tied to AES?
• ECC coordinates (scalars? points?)
  • What's the right abstraction there?

[chrysn]

• It may make sense to have a "user" side that is limited to high-level operations, and an "implementer" side that has all the nitty-gritty low-levels exposed. A user could go directly through the low-level side, but there are advantages for the user:
  • Better API stability. I expect some API churn on the detailed side, but selecting algorithms and running hashes/encryptions can easily be stable early on.
  • That high-level piece might be a convenient place to implement the optional higher-level parts such as "Here's an encoded COSE_Encrypt0, decrypt it with any of those keys" interfaces.
  • Fewer confusing methods that one might use wrong.

[kaspar030]

• Think hard about how to handle buffers.
  This is mentioned somewhat in AEAD, but IMO this should be given an extra portion of thought - on embedded, each extra copy is very painful. E.g., writing to stream sinks should be mandatory for the algos that support it.
  We do see this happening on the higher networking levels, where there are usually multiple
  copies of everything, due to lack of scatter/gather functions e.g., in embedded-nal. Network device needs an MTU sized buffer (even though the data is written in chunks to most network devices. TCP/UDP sockets need another buffer. Application level protocols need another buffer, and then the application using them another. Sometimes some can be removed, but only with painful rearchitecting. So with crypto in the mix, extra buffering

• With all the flexibility, go easy on generics. Monomorphization multiplies code-size, but that usually doesn't show until there are multiple users / more complex applications. Functionality goes first of course but focus should be on embedded use.

[newAM]

This is my high-level usecase based wishlist:

• Abstractions at a level that are usable for implementing client & server TLS. I believe targeting TLS is a good benchmark for general usability of embedded-cal as a component of a complete crypto system. I used feature flags for w5500-tls to swap out the p256 backend, but I think there could be a more elegant solution.
• Abstractions that are suitable for software and hardware. The STM32WL series chip has a public key accelerator (PKA) in hardware, but I found it was slower than a hand written P256 implementation in assembly. I would like an easy way for a consumer of a TLS library to select between software/hardware based on their code size and performance requirements. Reference https://github.com/newAM/p256-cm4?tab=readme-ov-file#comparisons for benchmarks.
• Usability with embedded Linux, for hardware accelerators exposed as files in /dev/.

[chrysn]

Think hard about how to handle buffers.

I plan to make encrypt-in-place the default, and to provide enough information that the caller will allocate and provide output buffers. E.g., there'd be some const max_signature_size (so that a user who wants to send a signed message can get itself a [u8; { APP_MAX_PLAINTEXT + PlatformCrypto::MAX_SIGNATURE_LEN }] buffer) -- no internal and thus limiting buffers exceeding a single block.

There is the component of AAD in signatures and AEAD, which don't naturally come in a buffer at the caller, and for which many existing libraries don't support streaming. It is planned on Rust interfaces (RustCrypto/traits#62 / RustCrypto/traits#1364). Support in hardware accelerators' APIs is mixed -- CC310 supports it for Poly1305 but not for AES-CCM (while the calling sequence and signatures would support it, it explicitly says "This API can be called only once per operation context."). The register level documentation is not too clear about it (neither is the full documentation), but an implementation I found calls a DMA function to feed data in which itself splits up the data, so that means the hardware can do it. Likewise, the STM32WB55 documentation says that sending the AAD is just sending blocks to the engine one after the other. So I'd go for a streaming approach even there, and see where it bites us. For formal verification reasons it might be practical to not pass in an arbitrary AAD producer but a &[&[u8]] which is guaranteed to have the same data when accessed multiple times; that's limiting when it comes to arbitrary streamed data, but should work well with most protocols. (Worst case, as with OSCORE, the user would need to set a limit as to how many of some kind of item should be processable).

Writing to streaming sinks would probably complicate things, I'm conflicted about: It'll depend on the algorithm whether it is available or not. (Not insurmountable, but it creates a two-class society of algorithms, with queries like "Do we support algorithm 10 and can we then stream the output?"). Plus, at least AEAD implementations are often strict about not supporting that, because it creates of parse-before-verification that Rust won't usably protect us from. Is that really something that would be used? With the control we can probably have over AAD streaming, we could probably achieve output to writers, but does it practically beat the simplicity of decrypt-in-place?

[chrysn]

• With all the flexibility, go easy on generics. Monomorphization multiplies code-size, but that usually doesn't show until there are multiple users / more complex applications. Functionality goes first of course but focus should be on embedded use.

Word.

That does also support the direction of not having type-level algorithms.

If we do need const generics in some places (say, if the AAD plan doesn't work out, and we need a wrapper that stack-allocates a user guided buffer), those should be thin #[inline] parts wrapping a non-generic function that takes a slice instead.

[chrysn]

• Abstractions at a level that are usable for implementing client & server TLS. I believe targeting TLS is a good benchmark for general usability of embedded-cal as a component of a complete crypto system. I used feature flags for w5500-tls to swap out the p256 backend, but I think there could be a more elegant solution.

I think that embedded-cal can be a good backend for p256, and I'll also peek into the aes module to see where a suitable boundary there would be.

• Abstractions that are suitable for software and hardware. The STM32WL series chip has a public key accelerator (PKA) in hardware, but I found it was slower than a hand written P256 implementation in assembly. I would like an easy way for a consumer of a TLS library to select between software/hardware based on their code size and performance requirements. Reference https://github.com/newAM/p256-cm4?tab=readme-ov-file#comparisons for benchmarks.

Selection of the backend will happen by whoever provides the type. Deselecting a provided hardware backend because for some reason one prefers the software backend is a good thing to consider.

• Usability with embedded Linux, for hardware accelerators exposed as files in /dev/.

I don't expect that to be troublesome, given that I'd also place having a cryptographically secure RNG covered on the list (ha, I didn't -- edited), and on some OSes that is backed by /dev/; the Lakers Crypto trait (that in some ways is the precursor to this work) supports this well already.

Nonetheless, worth having an eye out for -- is there any concrete hardware accelerator you'd recommend looking over? (The one HSM that comes to my mind that I'd look into is Nitrokey's NetHSM, but that's probably not the kind of device you're thinking of).

[malishav]

My take on this would be to follow similar high-level requirements as those we discussed when first developing lakers. That would be:

• no_std support as an absolute MUST
• close to no dependencies other than PACs for different implementations. Let's think twice before adding each dependency.
• seconding @kaspar030's comment on buffers and agreeing with @chrysn's comment on caller-allocated memory

[chrysn]

From updating prior art section, there's an item that's not quite a feature but also part of the early exploration:

• How parametrized should algorithms be?

  From COSE experience (esp. after fully-specified-algorithms), I think that we can have all algorithms fully specified in all places -- AIU, it's not like anyone should create an AES-CCM-16-64-128 key and later use it for AES-CCM-64-64-128. When there are keys that are really allowed to be taken from one algorithm to the other (Group OSCORE's use of Ed25519/X25519 mixing comes to mind), that can still be an explicit operation.

  It's not like the type would necessarily need to spell out the full variant in an enum -- backends are free to have either per-parametrization variants or a single AesCcm(l, m, keylength) variant.