1+ //! Module for sanitizing the stack, sometimes referred to as "Stack Bleaching."
2+
3+ use core:: arch:: asm;
4+ use core:: ptr;
5+
6+ use crate :: Zeroize ;
7+
8+ #[ cfg( feature = "alloc" ) ]
9+ use alloc:: {
10+ vec,
11+ vec:: { Vec }
12+ } ;
13+
14+ /// Gets the current stack pointer
15+ #[ inline( never) ]
16+ fn get_stack_pointer ( ) -> * mut u8 {
17+ let sp: * mut u8 ;
18+ #[ cfg( target_arch = "x86_64" ) ]
19+ unsafe {
20+ asm ! ( "mov {}, rsp" , out( reg) sp, options( nomem, nostack, preserves_flags) ) ;
21+ }
22+ #[ cfg( target_arch = "aarch64" ) ]
23+ unsafe {
24+ asm ! ( "mov {}, sp" , out( reg) sp, options( nomem, nostack, preserves_flags) ) ;
25+ }
26+ #[ cfg( target_arch = "x86" ) ]
27+ unsafe {
28+ asm ! ( "mov {}, esp" , out( reg) sp, options( nomem, nostack, preserves_flags) ) ;
29+ }
30+ sp
31+ }
32+
33+ /// Clears stack memory between two stack pointers using volatile writes
34+ #[ inline( never) ]
35+ unsafe fn clear_stack_range ( start_sp : * mut u8 , end_sp : * mut u8 ) {
36+ let start = start_sp. min ( end_sp) as usize ;
37+ let end = start_sp. max ( end_sp) as usize ;
38+ let size = end - start;
39+
40+ if size == 0 || size > 1024 * 1024 { // Sanity check
41+ return ;
42+ }
43+
44+ // Clear using volatile writes to prevent optimization
45+ let mut ptr = start as * mut u64 ;
46+ // Align to 8-byte boundary to clear 8 bytes at a time
47+ let end_ptr = ( end & !7 ) as * mut u64 ;
48+
49+ while ptr < end_ptr {
50+ unsafe {
51+ ptr:: write_volatile ( ptr, 0 ) ;
52+ ptr = ptr. add ( 1 ) ;
53+ }
54+ }
55+
56+ // Clear remaining bytes
57+ let mut byte_ptr = ptr as * mut u8 ;
58+ let byte_end = end as * mut u8 ;
59+ while byte_ptr < byte_end {
60+ unsafe {
61+ ptr:: write_volatile ( byte_ptr, 0 ) ;
62+ byte_ptr = byte_ptr. add ( 1 ) ;
63+ }
64+ }
65+ }
66+
67+ /// Wrapper function that captures stack state and clears after crypto operation
68+ ///
69+ /// # Safety
70+ ///
71+ /// * `crypto_fn` should be marked as `#[inline(never)]`, preventing register
72+ /// reuse or stack layout changes
73+ #[ inline( never) ]
74+ pub unsafe fn secure_crypto_call < F , R > ( crypto_fn : F ) -> R
75+ where
76+ F : FnOnce ( ) -> R ,
77+ {
78+ // Get initial stack pointer
79+ let initial_sp = get_stack_pointer ( ) ;
80+ assert ! ( !initial_sp. is_null( ) ) ;
81+
82+ // Call the crypto function (this will use more stack)
83+ let result = crypto_fn ( ) ;
84+
85+ // Get stack pointer after crypto operation
86+ let final_sp = psm:: stack_pointer ( ) ;
87+ assert ! ( !final_sp. is_null( ) ) ;
88+ debug_assert_ne ! ( initial_sp, final_sp) ;
89+
90+ // Clear the stack range used by the crypto function
91+ unsafe {
92+ clear_stack_range ( initial_sp, final_sp) ;
93+ }
94+
95+ result
96+ }
97+
98+ /// Wrapper function that captures stack state and clears after crypto operation
99+ /// by using an allocation on the heap as the stack.
100+ ///
101+ /// If you wish to clear the registers, it is recommended to clear them from
102+ /// within `crypto_fn()`. This function does not clear them for you.
103+ ///
104+ /// # Safety
105+ ///
106+ /// * `crypto_fn` should be marked as `#[inline(never)]`, preventing register
107+ /// reuse and stack layout changes.
108+ /// * The stack start address needs to be aligned for the target architecture, which is
109+ /// typically 16 bytes for x86_64.
110+ /// * The stack size needs to be a multiple of stack alignment required by
111+ /// the target.
112+ /// * The stack size must not overflow `isize`.
113+ /// * The stack needs to be large enough for `crypto_fn()` to execute without
114+ /// overflow.
115+ /// * `crypto_fn()` must not unwind or return control flow by any other means
116+ /// than by directly returning.
117+ pub unsafe fn secure_crypto_call_heap < F , R > ( crypto_fn : F , stack : & mut [ u8 ] ) -> R
118+ where
119+ F : FnOnce ( ) -> R ,
120+ {
121+ let res = unsafe {
122+ psm:: on_stack ( stack. as_mut_ptr ( ) , stack. len ( ) , || {
123+ let res = crypto_fn ( ) ;
124+ res
125+ } )
126+ } ;
127+ stack. zeroize ( ) ;
128+ res
129+ }
130+
131+ /// Round up to the nearest multiple of alignment
132+ const fn align_up ( value : usize , alignment : usize ) -> usize {
133+ ( value + alignment - 1 ) & !( alignment - 1 )
134+ }
135+
136+ /// Creates an aligned Vec<u8> with the specified size in KB and alignment.
137+ ///
138+ /// This helps ensure that the safety requirements are met when using
139+ /// `fn secure_crypto_call_heap()`.
140+ ///
141+ /// Both the data pointer and length will be aligned to the specified boundary.
142+ #[ cfg( feature = "alloc" ) ]
143+ pub fn create_aligned_vec ( size_kb : usize , alignment : usize ) -> Vec < u8 > {
144+ let size_bytes = size_kb * 1024 ;
145+ // checking one of the safety conditions of `psm::on_stack()`
146+ assert ! ( size_bytes <= isize :: MAX as usize ) ;
147+
148+ let aligned_size = align_up ( size_bytes, alignment) ;
149+
150+ // Allocate extra space to ensure we can find an aligned region
151+ let mut vec = vec ! [ 0u8 ; aligned_size + alignment] ;
152+
153+ // Find the aligned position within the vec
154+ let ptr_addr = vec. as_ptr ( ) as usize ;
155+ let aligned_addr = align_up ( ptr_addr, alignment) ;
156+ let offset = aligned_addr - ptr_addr;
157+
158+ // Remove elements from the beginning to align the start
159+ vec. drain ( 0 ..offset) ;
160+
161+ // Truncate to the exact aligned size we want
162+ vec. truncate ( aligned_size) ;
163+
164+ // Verify alignment (these will be optimized out in release builds)
165+ debug_assert_eq ! ( vec. as_ptr( ) as usize % alignment, 0 ) ;
166+ debug_assert_eq ! ( vec. len( ) % alignment, 0 ) ;
167+ debug_assert_eq ! ( vec. len( ) , aligned_size) ;
168+
169+ vec
170+ }
0 commit comments