Software APIs
aes.c
1 // Copyright lowRISC contributors (OpenTitan project).
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #include "sw/device/lib/crypto/drivers/aes.h"
6 
7 #include "sw/device/lib/base/abs_mmio.h"
8 #include "sw/device/lib/base/bitfield.h"
9 #include "sw/device/lib/base/hardened.h"
10 #include "sw/device/lib/base/macros.h"
11 #include "sw/device/lib/base/memory.h"
12 #include "sw/device/lib/crypto/drivers/entropy.h"
13 #include "sw/device/lib/crypto/impl/status.h"
14 
15 #include "aes_regs.h" // Generated.
16 #include "hw/top_earlgrey/sw/autogen/top_earlgrey.h"
17 
18 // Module ID for status codes.
19 #define MODULE_ID MAKE_MODULE_ID('d', 'a', 'e')
20 
21 enum {
22  kBase = TOP_EARLGREY_AES_BASE_ADDR,
23 
24  kAesKeyWordLen128 = 128 / (sizeof(uint32_t) * 8),
25  kAesKeyWordLen192 = 192 / (sizeof(uint32_t) * 8),
26  kAesKeyWordLen256 = 256 / (sizeof(uint32_t) * 8),
27 };
28 
29 /**
30  * Spins until the AES hardware reports a specific status bit.
31  */
32 static status_t spin_until(uint32_t bit) {
33  while (true) {
34  uint32_t reg = abs_mmio_read32(kBase + AES_STATUS_REG_OFFSET);
35  if (bitfield_bit32_read(reg, AES_STATUS_ALERT_RECOV_CTRL_UPDATE_ERR_BIT) ||
36  bitfield_bit32_read(reg, AES_STATUS_ALERT_FATAL_FAULT_BIT)) {
37  return OTCRYPTO_RECOV_ERR;
38  }
39  if (bitfield_bit32_read(reg, bit)) {
40  return OTCRYPTO_OK;
41  }
42  }
43 }
44 
45 /**
46  * Write the key to the AES hardware block.
47  *
48  * If the key is sideloaded, this is a no-op.
49  *
50  * @param key AES key.
51  * @return result, OK or error.
52  */
53 static status_t aes_write_key(aes_key_t key) {
54  if (key.sideload != kHardenedBoolFalse) {
55  HARDENED_CHECK_EQ(key.sideload, kHardenedBoolTrue);
56  // Nothing to be done; key must be separately loaded from keymgr.
57  return OTCRYPTO_OK;
58  }
59  HARDENED_CHECK_EQ(key.sideload, kHardenedBoolFalse);
60 
61  uint32_t share0 = kBase + AES_KEY_SHARE0_0_REG_OFFSET;
62  uint32_t share1 = kBase + AES_KEY_SHARE1_0_REG_OFFSET;
63 
64  // Handle key shares in two separate loops to avoid dealing with
65  // corresponding parts too close together, which could risk power
66  // side-channel leakage in the ALU.
67  // TODO: randomize iteration order.
68  size_t i = 0;
69  for (; i < key.key_len; ++i) {
70  abs_mmio_write32(share0 + i * sizeof(uint32_t), key.key_shares[0][i]);
71  }
72  HARDENED_CHECK_EQ(i, key.key_len);
73  for (i = 0; i < key.key_len; ++i) {
74  abs_mmio_write32(share1 + i * sizeof(uint32_t), key.key_shares[1][i]);
75  }
76  HARDENED_CHECK_EQ(i, key.key_len);
77 
78  // NOTE: all eight share registers must be written; in the case we don't have
79  // enough key data, we fill it with zeroes.
80  for (size_t i = key.key_len; i < 8; ++i) {
81  abs_mmio_write32(share0 + i * sizeof(uint32_t), 0);
82  abs_mmio_write32(share1 + i * sizeof(uint32_t), 0);
83  }
84  return spin_until(AES_STATUS_IDLE_BIT);
85 }
86 
87 /**
88  * Configure the AES block and write the key and IV if applicable.
89  *
90  * @param key AES key.
91  * @param iv IV to use (ignored if the mode does not require an IV).
92  * @param encrypt True for encryption, false for decryption.
93  * @return result, OK or error.
94  */
95 static status_t aes_begin(aes_key_t key, const aes_block_t *iv,
96  hardened_bool_t encrypt) {
97  // Ensure the entropy complex is in an appropriate state. The AES block seeds
98  // its PRNG from EDN for masking every time a new key is provided.
99  HARDENED_TRY(entropy_complex_check());
100 
101  // Wait for the AES block to be idle.
102  HARDENED_TRY(spin_until(AES_STATUS_IDLE_BIT));
103 
104  uint32_t ctrl_reg = AES_CTRL_SHADOWED_REG_RESVAL;
105 
106  // Set the operation (encrypt or decrypt).
107  hardened_bool_t operation_written = kHardenedBoolFalse;
108  switch (encrypt) {
109  case kHardenedBoolTrue:
110  ctrl_reg =
111  bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_OPERATION_FIELD,
112  AES_CTRL_SHADOWED_OPERATION_VALUE_AES_ENC);
113  operation_written = launder32(kHardenedBoolTrue);
114  break;
115  case kHardenedBoolFalse:
116  ctrl_reg =
117  bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_OPERATION_FIELD,
118  AES_CTRL_SHADOWED_OPERATION_VALUE_AES_DEC);
119  operation_written = launder32(kHardenedBoolTrue);
120  break;
121  default:
122  // Invalid value.
123  return OTCRYPTO_BAD_ARGS;
124  }
125  HARDENED_CHECK_EQ(operation_written, kHardenedBoolTrue);
126 
127  // Indicate whether the key will be sideloaded.
128  hardened_bool_t sideload_written = kHardenedBoolFalse;
129  switch (key.sideload) {
130  case kHardenedBoolTrue:
131  ctrl_reg =
132  bitfield_bit32_write(ctrl_reg, AES_CTRL_SHADOWED_SIDELOAD_BIT, true);
133  sideload_written = launder32(kHardenedBoolTrue);
134  break;
135  case kHardenedBoolFalse:
136  ctrl_reg =
137  bitfield_bit32_write(ctrl_reg, AES_CTRL_SHADOWED_SIDELOAD_BIT, false);
138  sideload_written = launder32(kHardenedBoolTrue);
139  break;
140  default:
141  // Invalid value.
142  return OTCRYPTO_BAD_ARGS;
143  }
144  HARDENED_CHECK_EQ(sideload_written, kHardenedBoolTrue);
145 
146  // Translate the cipher mode to the hardware-encoding value and write the
147  // control reg field.
148  aes_cipher_mode_t mode_written;
149  switch (launder32(key.mode)) {
150  case kAesCipherModeEcb:
151  ctrl_reg = bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_MODE_FIELD,
152  AES_CTRL_SHADOWED_MODE_VALUE_AES_ECB);
153  mode_written = launder32(kAesCipherModeEcb);
154  break;
155  case kAesCipherModeCbc:
156  ctrl_reg = bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_MODE_FIELD,
157  AES_CTRL_SHADOWED_MODE_VALUE_AES_CBC);
158  mode_written = launder32(kAesCipherModeCbc);
159  break;
160  case kAesCipherModeCfb:
161  ctrl_reg = bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_MODE_FIELD,
162  AES_CTRL_SHADOWED_MODE_VALUE_AES_CFB);
163  mode_written = launder32(kAesCipherModeCfb);
164  break;
165  case kAesCipherModeOfb:
166  ctrl_reg = bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_MODE_FIELD,
167  AES_CTRL_SHADOWED_MODE_VALUE_AES_OFB);
168  mode_written = launder32(kAesCipherModeOfb);
169  break;
170  case kAesCipherModeCtr:
171  ctrl_reg = bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_MODE_FIELD,
172  AES_CTRL_SHADOWED_MODE_VALUE_AES_CTR);
173  mode_written = launder32(kAesCipherModeCtr);
174  break;
175  default:
176  // Invalid value.
177  return OTCRYPTO_BAD_ARGS;
178  }
179  HARDENED_CHECK_EQ(mode_written, key.mode);
180 
181  // Translate the key length to the hardware-encoding value and write the
182  // control reg field.
183  switch (key.key_len) {
184  case kAesKeyWordLen128:
185  ctrl_reg =
186  bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_KEY_LEN_FIELD,
187  AES_CTRL_SHADOWED_KEY_LEN_VALUE_AES_128);
188  break;
189  case kAesKeyWordLen192:
190  ctrl_reg =
191  bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_KEY_LEN_FIELD,
192  AES_CTRL_SHADOWED_KEY_LEN_VALUE_AES_192);
193  break;
194  case kAesKeyWordLen256:
195  ctrl_reg =
196  bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_KEY_LEN_FIELD,
197  AES_CTRL_SHADOWED_KEY_LEN_VALUE_AES_256);
198  break;
199  default:
200  // Invalid value.
201  return OTCRYPTO_BAD_ARGS;
202  }
203 
204  // Never enable manual operation.
205  ctrl_reg = bitfield_bit32_write(
206  ctrl_reg, AES_CTRL_SHADOWED_MANUAL_OPERATION_BIT, false);
207 
208  // Always set the PRNG reseed rate to once per 64 blocks.
209  ctrl_reg =
210  bitfield_field32_write(ctrl_reg, AES_CTRL_SHADOWED_PRNG_RESEED_RATE_FIELD,
211  AES_CTRL_SHADOWED_PRNG_RESEED_RATE_VALUE_PER_64);
212 
213  abs_mmio_write32_shadowed(kBase + AES_CTRL_SHADOWED_REG_OFFSET, ctrl_reg);
214  HARDENED_TRY(spin_until(AES_STATUS_IDLE_BIT));
215 
216  // Write the key (if it is not sideloaded).
217  HARDENED_TRY(aes_write_key(key));
218 
219  // All modes except ECB need to set an IV.
220  if (key.mode != launder32(kAesCipherModeEcb)) {
221  HARDENED_CHECK_NE(key.mode, kAesCipherModeEcb);
222  uint32_t iv_offset = kBase + AES_IV_0_REG_OFFSET;
223  for (size_t i = 0; i < ARRAYSIZE(iv->data); ++i) {
224  abs_mmio_write32(iv_offset + i * sizeof(uint32_t), iv->data[i]);
225  }
226  }
227 
228  // Check that AES is ready to receive input data.
229  uint32_t status = abs_mmio_read32(kBase + AES_STATUS_REG_OFFSET);
230  if (!bitfield_bit32_read(launder32(status), AES_STATUS_INPUT_READY_BIT)) {
231  return OTCRYPTO_RECOV_ERR;
232  }
233  HARDENED_CHECK_EQ(
234  bitfield_bit32_read(abs_mmio_read32(kBase + AES_STATUS_REG_OFFSET),
235  AES_STATUS_INPUT_READY_BIT),
236  true);
237 
238  return OTCRYPTO_OK;
239 }
240 
241 status_t aes_encrypt_begin(const aes_key_t key, const aes_block_t *iv) {
242  return aes_begin(key, iv, kHardenedBoolTrue);
243 }
244 
245 status_t aes_decrypt_begin(const aes_key_t key, const aes_block_t *iv) {
246  return aes_begin(key, iv, kHardenedBoolFalse);
247 }
248 
249 status_t aes_update(aes_block_t *dest, const aes_block_t *src) {
250  if (dest != NULL) {
251  // Check that either the output is valid or AES is busy, to avoid spinning
252  // forever if the user passes a non-null `dest` when there is no output
253  // pending.
254  uint32_t reg = abs_mmio_read32(kBase + AES_STATUS_REG_OFFSET);
255  if (bitfield_bit32_read(reg, AES_STATUS_IDLE_BIT) &&
256  !bitfield_bit32_read(reg, AES_STATUS_OUTPUT_VALID_BIT)) {
257  return OTCRYPTO_RECOV_ERR;
258  }
259 
260  HARDENED_TRY(spin_until(AES_STATUS_OUTPUT_VALID_BIT));
261 
262  uint32_t offset = kBase + AES_DATA_OUT_0_REG_OFFSET;
263  for (size_t i = 0; i < ARRAYSIZE(dest->data); ++i) {
264  dest->data[i] = abs_mmio_read32(offset + i * sizeof(uint32_t));
265  }
266  }
267 
268  if (src != NULL) {
269  HARDENED_TRY(spin_until(AES_STATUS_INPUT_READY_BIT));
270 
271  uint32_t offset = kBase + AES_DATA_IN_0_REG_OFFSET;
272  for (size_t i = 0; i < ARRAYSIZE(src->data); ++i) {
273  abs_mmio_write32(offset + i * sizeof(uint32_t), src->data[i]);
274  }
275  }
276 
277  return OTCRYPTO_OK;
278 }
279 
280 status_t aes_end(aes_block_t *iv) {
281  uint32_t ctrl_reg = AES_CTRL_SHADOWED_REG_RESVAL;
282  ctrl_reg = bitfield_bit32_write(ctrl_reg,
283  AES_CTRL_SHADOWED_MANUAL_OPERATION_BIT, true);
284  abs_mmio_write32_shadowed(kBase + AES_CTRL_SHADOWED_REG_OFFSET, ctrl_reg);
285 
286  if (iv != NULL) {
287  // Read back the current IV from the hardware.
288  uint32_t iv_offset = kBase + AES_IV_0_REG_OFFSET;
289  for (size_t i = 0; i < ARRAYSIZE(iv->data); ++i) {
290  iv->data[i] = abs_mmio_read32(iv_offset + i * sizeof(uint32_t));
291  }
292  }
293 
294  uint32_t trigger_reg = 0;
295  trigger_reg = bitfield_bit32_write(
296  trigger_reg, AES_TRIGGER_KEY_IV_DATA_IN_CLEAR_BIT, true);
297  trigger_reg =
298  bitfield_bit32_write(trigger_reg, AES_TRIGGER_DATA_OUT_CLEAR_BIT, true);
299  abs_mmio_write32(kBase + AES_TRIGGER_REG_OFFSET, trigger_reg);
300 
301  return spin_until(AES_STATUS_IDLE_BIT);
302 }
Return to OpenTitan Documentation