RFC: AES Encryption HIL Updates + Virtualizers #4609

tyler-potyondy · 2025-09-19T16:57:53Z

Pull Request Overview

This pull request introduces updates to the AES Symmetric Encryption HIL, adds traits that specify the semantics for each AES encryption mode, and adds a generic AES HW encryption virtualizer. This PR demonstrates these changes across the Nrf5x AES crypto engine and nRF52840dk board file. Importantly, this is currently untested and remains a draft. The primary purpose of this PR is to solicit feedback before spending additional time finalizing / testing / incorporating these changes for the other AES crypto hardware.

The current AES stack uses a combination of virtualizers / overloaded traits to provide the needed crypto interfaces (e.g. ECB, CTR, CCM, GCM, CBC are required for the userspace symmetric encryption capsule, but the kernel 15.4 stack also requires CCM). The current design does not scale well and struggles when building higher level crypto modes (e.g. GCM) from HW supported ECB. This design attempts to provide a single generic AES HW virtualizer (to avoid each mode needing to implement a virtualizer).

Key Changes:

Remove GCM / CCM Client in HIL (use single standard Client)
Add traits at the capsule level to encapsulate the behavior of each crypto mode. This allows us to statically enforce requirements for each crypto mode.
Update the userspace symmetric encryption driver to now use virtualized aes hw. The implementation is greatly simplified as it no longer requires tracking state to correctly overload traits / configure on the fly as this is now abstracted by the virtualizer.
Example AESCtr implementation to demonstrate new HIL's integration with the RustCrypto software AESCtr and AESCtr implementation based upon HW ECB support.

Testing Strategy

N/A, testing will follow based on RFC discussion.

TODO or Help Wanted

This pull request still needs...

update of chip implementations for SAM4L, and Earlgray
update of capsules that use AES128 methods (e.g. 802.15.4)
testing of AESCtr capsule
testing of symmetric encryption capsule

Documentation Updated

Updated the relevant files in /docs, or no updates are required.

Formatting

Ran make prepush.

Refactoring and update of AES encryption HIL to: - remove GCM / CCM clients in favor of a standard AES client - update CCM / GCM traits to correspond to HW ops. The current implementation is inconsistent with HIL and encodes properties beyond what is necessary for an interface with hardware. - update crypt to use `Result` pattern rather than nested `Option`

This updates the nrf5x aes implementation to use the refactored aes symmetric encryption HIL. Additionally, this removes the software implementation of CTR/CCM modes in the HIL. These should not be implemented within the chips directory as they are not related to the hardware.

Provide opinionated interface as traits for each aes mode (e.g. specify if a given mode requires iv and the length of said iv).

Add aes hw virtualizer that exposes generic interface for all aes modes.

Provides a fully SW aes ctr implementation using RustCrypto aes ctr crate in addition to a aes ctr implementation built upon hw ecb support.

Rewrite aes userspace driver for new interface.

(for demonstration purposes only)

bradjc

A couple comments. I think this in the right direction.

bradjc · 2025-09-19T18:48:29Z

capsules/aes_ctr/Cargo.toml

+[dependencies]
+kernel = { path = "../../kernel" }
+capsules-core = { path = "../core"}
+enum_primitive = { path = "../../libraries/enum_primitive" }
+tickv = { path = "../../libraries/tickv" }
+ctr = "0.9.2"
+aes = "0.8.4" 


Suggested change

[dependencies]

kernel = { path = "../../kernel" }

capsules-core = { path = "../core"}

enum_primitive = { path = "../../libraries/enum_primitive" }

tickv = { path = "../../libraries/tickv" }

ctr = "0.9.2"

aes = "0.8.4"

[dependencies]

kernel = { path = "../../kernel" }

capsules-core = { path = "../core"}

ctr = "0.9.2"

aes = "0.8.4"

?

bradjc · 2025-09-19T19:03:41Z

kernel/src/hil/symmetric_encryption.rs

 /// Implement this trait and use `set_client()` in order to receive callbacks from an `AES128`
-/// instance.
+/// instance. This returns the provided source. The `dest` contains the result of the operation
+/// and in both cases the `SubSliceMut` provided to `crypt()` will be returned.
 pub trait Client<'a> {
-    fn crypt_done(&'a self, source: Option<&'static mut [u8]>, dest: &'static mut [u8]);
+    fn crypt_done(
+        &'a self,
+        source: Option<SubSliceMut<'static, u8>>,
+        dest: Result<SubSliceMut<'static, u8>, (ErrorCode, SubSliceMut<'static, u8>)>,
+    );
 }


Wait, what are source and dest?

source and dest are the buffers provided to the crypto function. source is optional, and in the absence of source, dest is used as the input to the crypto and overwritten as the output.

Ah, ok what I don't understand is how dest is a result. The result should just be separate.

bradjc · 2025-09-19T19:47:40Z

capsules/extra/src/symmetric_encryption/aes.rs

+pub struct AesOperators<'a, ECB: Aes128Ecb<'a>, CTR: Aes128Ctr<'a>> {
+    ecb: &'a ECB,
+    ctr: &'a CTR,
+}


Do we need this type?

No we do not, this was used by a prior version of something that was removed.

bradjc · 2025-09-19T19:50:36Z

capsules/extra/src/symmetric_encryption/aes.rs

+impl<'a, ECB: Aes128Ecb<'a>, CTR: Aes128Ctr<'a>> AesDriver<'a, ECB, CTR> {
    pub fn new(
-        aes: &'static A,
-        source_buffer: &'static mut [u8],
-        dest_buffer: &'static mut [u8],
+        aes_ecb: &'a ECB,
+        aes_ctr: &'a CTR,
        grant: Grant<
            App,
-            UpcallCount<1>,
+            UpcallCount<{ upcall::COUNT }>,
            AllowRoCount<{ ro_allow::COUNT }>,
            AllowRwCount<{ rw_allow::COUNT }>,
        >,
-    ) -> AesDriver<'static, A> {
+        kernel_dest_buf: &'static mut [u8],
+        kernel_src_buf: &'static mut [u8],
+    ) -> Self {


What if aes_ecb and aes_ctr are the same reference?

bradjc · 2025-09-19T19:52:26Z

capsules/core/src/aes.rs

There are a lot of files called "aes". This makes it really hard to tell what is actually using what.

I agree. We should try to come up with some other names for the files at the different layers. I'll think some more about this.

bradjc · 2025-09-19T19:53:18Z

boards/nordic/nrf52840dk/src/lib.rs

+    aes: &'static capsules_extra::symmetric_encryption::aes::AesDriver<
+        'static,
+        capsules_core::virtualizers::virtual_aes::AesVirtualHw<
+            'static,
+            nrf52840::aes::AesECB<'static>,
+        >,
+        capsules_aes_ctr::aes_ctr::Aes128CtrEcbBase<
+            'static,
+            capsules_core::virtualizers::virtual_aes::AesVirtualHw<
+                'static,
+                nrf52840::aes::AesECB<'static>,
+            >,
+        >,
+    >,


Please make a type AesDriver = for this.

bradjc · 2025-09-19T19:54:14Z

boards/nordic/nrf52840dk/src/lib.rs

+    let aes_driver = static_init!(
+        capsules_extra::symmetric_encryption::aes::AesDriver<
+            'static,
+            capsules_core::virtualizers::virtual_aes::AesVirtualHw<
+                'static,
+                nrf52840::aes::AesECB<'static>,
+            >,
+            capsules_aes_ctr::aes_ctr::Aes128CtrEcbBase<
+                'static,
+                capsules_core::virtualizers::virtual_aes::AesVirtualHw<
+                    'static,
+                    nrf52840::aes::AesECB<'static>,
+                >,
+            >,
+        >,
+        capsules_extra::symmetric_encryption::aes::AesDriver::new(
+            virtual_aes_ecb,
+            sw_ctr,
+            grant,
+            crypt_dest_buf,
+            crypt_src_buf,
+        )
+    );


We don't have an aes component?

alistair23 · 2025-10-17T02:53:15Z

kernel/src/hil/symmetric_encryption.rs

+    // (todo) likely want to remove enable / disable per discussion on
+    // https://github.com/tock/tock/pull/4500
+    fn enable(&self);
    fn disable(&self);


We should clarify when secrets are deleted (I'm assuming when disable() is called), but it's worth being really clear

alistair23 · 2025-10-17T02:53:21Z

kernel/src/hil/symmetric_encryption.rs

+    // https://github.com/tock/tock/pull/4500
+    fn enable(&self);
    fn disable(&self);
+    fn configure(&self, typer: Self::T);


tyler-potyondy added 7 commits September 17, 2025 16:09

capsules: core: add interface for each aes mode

1bd346a

Provide opinionated interface as traits for each aes mode (e.g. specify if a given mode requires iv and the length of said iv).

capsules: core: aes hw virtualizer

e3ceb0c

Add aes hw virtualizer that exposes generic interface for all aes modes.

capsules: aes_ctr: add aes_ctr crate

aff4032

Provides a fully SW aes ctr implementation using RustCrypto aes ctr crate in addition to a aes ctr implementation built upon hw ecb support.

capsules: extra: symmetric encryption aes driver

774bb97

Rewrite aes userspace driver for new interface.

boards: nrf52840dk: update to new virtual aes

686ad0f

(for demonstration purposes only)

github-actions bot added chips/nrf Change pertains to the nRF5x family of MCUs. HIL This affects a Tock HIL interface. labels Sep 19, 2025

ppannuto added the WG-Crypto In the purview of the crypto working group label Sep 19, 2025

bradjc reviewed Sep 19, 2025

View reviewed changes

alistair23 suggested changes Oct 17, 2025

View reviewed changes

Uh oh!

RFC: AES Encryption HIL Updates + Virtualizers #4609

Are you sure you want to change the base?

RFC: AES Encryption HIL Updates + Virtualizers #4609

Uh oh!

Conversation

tyler-potyondy commented Sep 19, 2025

Pull Request Overview

Testing Strategy

TODO or Help Wanted

Documentation Updated

Formatting

Uh oh!

bradjc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants