rscrypto 0.3.0

Pure Rust cryptography: RSA, Ed25519, X25519, SHA-2/3, BLAKE3, AES-GCM, ChaCha20-Poly1305, Argon2, HMAC/HKDF, CRC. no_std, WASM, hardware acceleration.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264

use super::{EXPANDED_KEY_WORDS, EXPANDED_KEY_WORDS_128};

/// AES-256 key for the KM (Cipher Message) instruction.
///
/// Caches the raw 32-byte key (extracted once at key-expansion time)
/// alongside the full expanded schedule. This avoids 8 BE serializations
/// per `encrypt_block` call — critical for GCM-SIV which does 7 AES
/// calls for even a 0-byte message.
#[derive(Clone)]
#[repr(C, align(8))]
pub(in crate::aead) struct KmKey {
  /// Raw 32-byte AES-256 key, ready for the KM parameter block.
  raw: [u8; 32],
  /// Full expanded schedule (kept for potential future use / uniform sizing).
  rk: [u32; EXPANDED_KEY_WORDS],
}

impl KmKey {
  /// Wrap an already-expanded portable round key schedule for KM.
  pub(super) fn from_portable(rk: [u32; EXPANDED_KEY_WORDS]) -> Self {
    // Extract the raw 32-byte key from the first 8 big-endian u32 words.
    let mut raw = [0u8; 32];
    let mut i = 0usize;
    while i < 8 {
      let off = i.strict_mul(4);
      let bytes = rk[i].to_be_bytes();
      raw[off] = bytes[0];
      raw[off.strict_add(1)] = bytes[1];
      raw[off.strict_add(2)] = bytes[2];
      raw[off.strict_add(3)] = bytes[3];
      i = i.strict_add(1);
    }
    Self { raw, rk }
  }

  /// Zeroize both the raw key and the full key schedule.
  pub(super) fn zeroize(&mut self) {
    crate::traits::ct::zeroize(&mut self.raw);
    // SAFETY: [u32; 60] is layout-compatible with [u8; 240].
    let bytes =
      unsafe { core::slice::from_raw_parts_mut(self.rk.as_mut_ptr().cast::<u8>(), EXPANDED_KEY_WORDS.strict_mul(4)) };
    crate::traits::ct::zeroize(bytes);
  }
}

/// Encrypt a single 16-byte block using a raw AES-256 key and the KM instruction.
///
/// This avoids rebuilding a portable key schedule when the caller already has
/// the derived 32-byte key material and only needs KM's raw parameter block.
///
/// # Safety
/// Caller must ensure the MSA (CPACF) facility is available.
pub(super) unsafe fn encrypt_block_raw(raw_key: &[u8; 32], block: &mut [u8; 16]) {
  // KM requires non-overlapping source and destination. Copy the
  // plaintext to a stack buffer, encrypt from there into `block`.
  let mut src: [u8; 16] = *block;

  let parm = raw_key.as_ptr();
  let src_ptr = src.as_ptr();
  let dest_ptr = block.as_mut_ptr();

  // KM function code 20 = AES-256 encrypt.
  //
  // Instruction: .insn rre, 0xB92E0000, R1, R2
  //   R0  = function code (20)
  //   R1  = parameter block pointer (32-byte key)
  //   R2  = destination address (updated)
  //   R4  = source address (updated)
  //   R5  = source length in bytes (decremented)
  //
  // CC=0: complete. CC=2: partial (kernel preemption) - retry.
  //
  // SAFETY: MSA verified by caller. Parameter block is the raw
  // 32-byte AES-256 key. Source and destination are valid,
  // non-overlapping 16-byte buffers.
  unsafe {
    core::arch::asm!(
      "0:",
      ".insn rre, 0xB92E0000, 2, 4",
      "jo 0b",
      inout("r0") 20u64 => _,
      in("r1") parm,
      inout("r2") dest_ptr => _,
      inout("r3") 16u64 => _,
      inout("r4") src_ptr => _,
      inout("r5") 16u64 => _,
      options(nostack),
    );
  }

  crate::traits::ct::zeroize(&mut src);
}

/// Encrypt a single 16-byte block using the KM instruction (AES-256 ECB).
///
/// # Safety
/// Caller must ensure the MSA (CPACF) facility is available.
pub(super) unsafe fn encrypt_block(key: &KmKey, block: &mut [u8; 16]) {
  // SAFETY: caller guarantees MSA; KmKey stores a raw 32-byte AES-256 key.
  unsafe { encrypt_block_raw(&key.raw, block) }
}

/// Encrypt multiple independent 16-byte blocks using a single KM call.
///
/// KM in ECB mode (function code 20) processes `count` contiguous blocks
/// in one instruction invocation. This is critical for GCM-SIV key
/// derivation which requires 6 independent AES-ECB encryptions.
///
/// # Safety
/// Caller must ensure the MSA (CPACF) facility is available.
/// `blocks` must contain exactly `count * 16` bytes.
pub(super) unsafe fn encrypt_blocks(key: &KmKey, blocks: &mut [u8], count: usize) {
  debug_assert_eq!(blocks.len(), count.strict_mul(16));

  // KM requires non-overlapping source and destination.
  // Allocate a stack buffer for the source copy.
  let len = count.strict_mul(16);
  let mut src = [0u8; 16 * 8]; // max 8 blocks (128 bytes), enough for GCM-SIV's 6
  src[..len].copy_from_slice(&blocks[..len]);

  let parm = key.raw.as_ptr();
  let src_ptr = src.as_ptr();
  let dest_ptr = blocks.as_mut_ptr();

  // SAFETY: Same as encrypt_block. len = count*16 bytes, all within bounds.
  unsafe {
    core::arch::asm!(
      "0:",
      ".insn rre, 0xB92E0000, 2, 4",
      "jo 0b",
      inout("r0") 20u64 => _,
      in("r1") parm,
      inout("r2") dest_ptr => _,
      inout("r3") len as u64 => _,
      inout("r4") src_ptr => _,
      inout("r5") len as u64 => _,
      options(nostack),
    );
  }

  crate::traits::ct::zeroize(&mut src[..len]);
}

// ---------------------------------------------------------------------------
// AES-128 (KM function code 18)
// ---------------------------------------------------------------------------

/// AES-128 key for the KM (Cipher Message) instruction.
#[derive(Clone)]
#[repr(C, align(8))]
pub(in crate::aead) struct Km128Key {
  /// Raw 16-byte AES-128 key, ready for the KM parameter block.
  raw: [u8; 16],
  /// Full expanded schedule (kept for parity with [`KmKey`]).
  rk: [u32; EXPANDED_KEY_WORDS_128],
}

impl Km128Key {
  /// Wrap an already-expanded portable round key schedule for KM.
  pub(super) fn from_portable(rk: [u32; EXPANDED_KEY_WORDS_128]) -> Self {
    let mut raw = [0u8; 16];
    let mut i = 0usize;
    while i < 4 {
      let off = i.strict_mul(4);
      let bytes = rk[i].to_be_bytes();
      raw[off] = bytes[0];
      raw[off.strict_add(1)] = bytes[1];
      raw[off.strict_add(2)] = bytes[2];
      raw[off.strict_add(3)] = bytes[3];
      i = i.strict_add(1);
    }
    Self { raw, rk }
  }

  /// Zeroize both the raw key and the full key schedule.
  pub(super) fn zeroize(&mut self) {
    crate::traits::ct::zeroize(&mut self.raw);
    // SAFETY: [u32; 44] is layout-compatible with [u8; 176].
    let bytes = unsafe {
      core::slice::from_raw_parts_mut(self.rk.as_mut_ptr().cast::<u8>(), EXPANDED_KEY_WORDS_128.strict_mul(4))
    };
    crate::traits::ct::zeroize(bytes);
  }
}

/// Encrypt a single 16-byte block using a raw AES-128 key and the KM instruction.
///
/// # Safety
/// Caller must ensure the MSA (CPACF) facility is available.
pub(super) unsafe fn encrypt_block_raw_128(raw_key: &[u8; 16], block: &mut [u8; 16]) {
  let mut src: [u8; 16] = *block;

  let parm = raw_key.as_ptr();
  let src_ptr = src.as_ptr();
  let dest_ptr = block.as_mut_ptr();

  // KM function code 18 = AES-128 encrypt. Same encoding as AES-256
  // (.insn rre, 0xB92E0000); only the function code in r0 differs.
  //
  // SAFETY: MSA verified by caller. Parameter block is the raw
  // 16-byte AES-128 key. Source and destination are valid,
  // non-overlapping 16-byte buffers.
  unsafe {
    core::arch::asm!(
      "0:",
      ".insn rre, 0xB92E0000, 2, 4",
      "jo 0b",
      inout("r0") 18u64 => _,
      in("r1") parm,
      inout("r2") dest_ptr => _,
      inout("r3") 16u64 => _,
      inout("r4") src_ptr => _,
      inout("r5") 16u64 => _,
      options(nostack),
    );
  }

  crate::traits::ct::zeroize(&mut src);
}

/// Encrypt a single 16-byte block using the KM instruction (AES-128 ECB).
///
/// # Safety
/// Caller must ensure the MSA (CPACF) facility is available.
pub(super) unsafe fn encrypt_block_128(key: &Km128Key, block: &mut [u8; 16]) {
  // SAFETY: caller guarantees MSA; Km128Key stores a raw 16-byte AES-128 key.
  unsafe { encrypt_block_raw_128(&key.raw, block) }
}

/// Encrypt multiple independent 16-byte blocks using a single KM call (AES-128 ECB).
///
/// # Safety
/// Caller must ensure the MSA (CPACF) facility is available.
/// `blocks` must contain exactly `count * 16` bytes.
#[cfg(any(feature = "aes-gcm", feature = "aes-gcm-siv"))]
pub(super) unsafe fn encrypt_blocks_128(key: &Km128Key, blocks: &mut [u8], count: usize) {
  debug_assert_eq!(blocks.len(), count.strict_mul(16));

  let len = count.strict_mul(16);
  let mut src = [0u8; 16 * 8];
  src[..len].copy_from_slice(&blocks[..len]);

  let parm = key.raw.as_ptr();
  let src_ptr = src.as_ptr();
  let dest_ptr = blocks.as_mut_ptr();

  // SAFETY: MSA verified by caller; src/dest are non-overlapping len-byte spans.
  unsafe {
    core::arch::asm!(
      "0:",
      ".insn rre, 0xB92E0000, 2, 4",
      "jo 0b",
      inout("r0") 18u64 => _,
      in("r1") parm,
      inout("r2") dest_ptr => _,
      inout("r3") len as u64 => _,
      inout("r4") src_ptr => _,
      inout("r5") len as u64 => _,
      options(nostack),
    );
  }

  crate::traits::ct::zeroize(&mut src[..len]);
}