How to move stack vars to the heap?

[ounsworth]

This task might be due to my ignorance more than anything.

When you design for no_std, that means that everything is on the stack, which can cause you to blow your stack limit. Research
how an application that itself is not no_std can put our large structs (like key objects) on the heap. Is this what
Box is for? It would be nice to throw an example of that into the crate docs somewhere.

[romen]

AFAIK the idiomatic way is to add a new feature to gate the heap APIs: often the convention is alloc if you only need that part of std.

Then you do something like this:

#[cfg(feature = "alloc")]
use alloc::{boxed::Box, vec};

#[cfg(feature = "alloc")]
pub fn keypair_boxed(seed: &[u8]) -> (Box<[u8; PK_LEN]>, Box<[u8; SK_LEN]>) {
    // vec![0u8; N] -> alloc_zeroed: a fresh zeroed heap allocation, no stack temporary.
    // into_boxed_slice() trims capacity to exactly N (no realloc since len == cap).
    // try_into() converts Box<[u8]> -> Box<[u8; N]>: a pointer cast, no copy.
    let mut pk: Box<[u8; PK_LEN]> = vec![0u8; PK_LEN]
        .into_boxed_slice()
        .try_into()
        .unwrap();
    let mut sk: Box<[u8; SK_LEN]> = vec![0u8; SK_LEN]
        .into_boxed_slice()
        .try_into()
        .unwrap();

    keypair_out(seed, &mut pk, &mut sk);
    (pk, sk)
}

We already have the _out versions so we are already halfway there!

The advantage compared to letting the caller Box the result of the stack-return functions or letting them create a boxed buffer and pass it to keygen_out is that we can make the life easy for our users and use patterns that guarantee no intermediate value ever lives in the stack.

[npajkovsky]

From Rust doc.

For non-zero-sized values, a Box will use the Global allocator for its allocation.

With no_std, it's up to the programmer to implement GlobalAlloc, and the project will eventually have to implement it anyway.

[ounsworth]

Thanks @romen and @npajkovsky . Sounds like being able to optionally use heap when available is a larger project.

I guess it's twofold:

1. That the large objects we return (like private keys) can be heap-allocated, and
2. That our algorithms internally use heap for temporary variables, when available. For example, ML-DSA.sign uses like 160 kb