Software APIs
keymgr.h
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 #ifndef OPENTITAN_SW_DEVICE_LIB_CRYPTO_DRIVERS_KEYMGR_H_
6 #define OPENTITAN_SW_DEVICE_LIB_CRYPTO_DRIVERS_KEYMGR_H_
7 
8 #include <stdbool.h>
9 #include <stddef.h>
10 #include <stdint.h>
11 
12 #include "sw/device/lib/base/macros.h"
13 #include "sw/device/lib/crypto/impl/status.h"
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 enum {
20  /**
21  * Number of 32-bit words for the salt.
22  */
23  kKeymgrSaltNumWords = 8,
24  /**
25  * Number of 32-bit words for each output key share.
26  */
27  kKeymgrOutputShareNumWords = 8,
28 };
29 
30 /**
31  * Data used to differentiate a generated keymgr key.
32  */
33 typedef struct keymgr_diversification {
34  /**
35  * Salt value to use for key generation.
36  */
37  uint32_t salt[kKeymgrSaltNumWords];
38  /**
39  * Version for key generation (anti-rollback protection).
40  */
41  uint32_t version;
42 } keymgr_diversification_t;
43 
44 /**
45  * Generated key from keymgr.
46  *
47  * The output key material is 256 bits, generated in two shares.
48  */
49 typedef struct keymgr_output {
50  uint32_t share0[kKeymgrOutputShareNumWords];
51  uint32_t share1[kKeymgrOutputShareNumWords];
52 } keymgr_output_t;
53 
54 /**
55  * Derive a key manager key that is visible to software.
56  *
57  * @param diversification Diversification input for the key derivation.
58  * @param[out] key Destination key struct.
59  * @return OK or error.
60  */
61 OT_WARN_UNUSED_RESULT
62 status_t keymgr_generate_key_sw(const keymgr_diversification_t diversification,
63  keymgr_output_t *key);
64 
65 /**
66  * Derive a key manager key for the AES block.
67  *
68  * Calls the key manager to sideload a key into the AES hardware block and
69  * waits until the operation is complete before returning.
70  *
71  * @param diversification Diversification input for the key derivation.
72  * @return OK or error.
73  */
74 OT_WARN_UNUSED_RESULT
75 status_t keymgr_generate_key_aes(
76  const keymgr_diversification_t diversification);
77 
78 /**
79  * Derive a key manager key for the KMAC block.
80  *
81  * Calls the key manager to sideload a key into the KMAC hardware block and
82  * waits until the operation is complete before returning.
83  *
84  * @param diversification Diversification input for the key derivation.
85  * @return OK or error.
86  */
87 OT_WARN_UNUSED_RESULT
88 status_t keymgr_generate_key_kmac(
89  const keymgr_diversification_t diversification);
90 
91 /**
92  * Derive a key manager key for the OTBN block.
93  *
94  * Calls the key manager to sideload a key into the OTBN hardware block and
95  * waits until the operation is complete before returning.
96  *
97  * @param diversification Diversification input for the key derivation.
98  * @return OK or error.
99  */
100 OT_WARN_UNUSED_RESULT
101 status_t keymgr_generate_key_otbn(
102  const keymgr_diversification_t diversification);
103 
104 /**
105  * Clear the sideloaded AES key.
106  *
107  * @return OK or error.
108  */
109 OT_WARN_UNUSED_RESULT
110 status_t keymgr_sideload_clear_aes(void);
111 
112 /**
113  * Clear the sideloaded KMAC key.
114  *
115  * @return OK or error.
116  */
117 OT_WARN_UNUSED_RESULT
118 status_t keymgr_sideload_clear_kmac(void);
119 
120 /**
121  * Clear the sideloaded OTBN key.
122  *
123  * @return OK or error.
124  */
125 OT_WARN_UNUSED_RESULT
126 status_t keymgr_sideload_clear_otbn(void);
127 
128 #ifdef __cplusplus
129 }
130 #endif
131 
132 #endif // OPENTITAN_SW_DEVICE_LIB_CRYPTO_DRIVERS_KEYMGR_H_
Return to OpenTitan Documentation