1 /*
2   ROM functions for hardware Digital Signature peripheral verification
3 */
4 // Copyright 2019 Espressif Systems (Shanghai) PTE LTD
5 //
6 // Licensed under the Apache License, Version 2.0 (the "License");
7 // you may not use this file except in compliance with the License.
8 // You may obtain a copy of the License at
9 
10 //     http://www.apache.org/licenses/LICENSE-2.0
11 //
12 // Unless required by applicable law or agreed to in writing, software
13 // distributed under the License is distributed on an "AS IS" BASIS,
14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 // See the License for the specific language governing permissions and
16 // limitations under the License.
17 
18 #pragma once
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 #include <stdint.h>
25 #include <stdbool.h>
26 
27 #define ETS_DS_IV_LEN 16
28 
29 /* Length of parameter 'C' stored in flash */
30 #define ETS_DS_C_LEN (12672 / 8)
31 
32 /* Encrypted ETS data. Recommended to store in flash in this format.
33  */
34 typedef struct {
35     /* RSA LENGTH register parameters
36      * (number of words in RSA key & operands, minus one).
37      *
38      * Max value 127 (for RSA 4096).
39      *
40      * This value must match the length field encrypted and stored in 'c',
41      * or invalid results will be returned. (The DS peripheral will
42      * always use the value in 'c', not this value, so an attacker can't
43      * alter the DS peripheral results this way, it will just truncate or
44      * extend the message and the resulting signature in software.)
45      */
46     unsigned rsa_length;
47 
48     /* IV value used to encrypt 'c' */
49     uint8_t iv[ETS_DS_IV_LEN];
50 
51     /* Encrypted Digital Signature parameters. Result of AES-CBC encryption
52        of plaintext values. Includes an encrypted message digest.
53     */
54     uint8_t c[ETS_DS_C_LEN];
55 } ets_ds_data_t;
56 
57 typedef enum {
58     ETS_DS_OK,
59     ETS_DS_INVALID_PARAM,   /* Supplied parameters are invalid */
60     ETS_DS_INVALID_KEY,     /* HMAC peripheral failed to supply key */
61     ETS_DS_INVALID_PADDING, /* 'c' decrypted with invalid padding */
62     ETS_DS_INVALID_DIGEST,  /* 'c' decrypted with invalid digest */
63 } ets_ds_result_t;
64 
65 void ets_ds_enable(void);
66 
67 void ets_ds_disable(void);
68 
69 
70 /*
71  * @brief Start signing a message (or padded message digest) using the Digital Signature peripheral
72  *
73  * - @param message Pointer to message (or padded digest) containing the message to sign. Should be
74  *   (data->rsa_length + 1)*4 bytes long.  @param data Pointer to DS data. Can be a pointer to data
75  *   in flash.
76  *
77  * Caller must have already called ets_ds_enable() and ets_hmac_calculate_downstream() before calling
78  * this function, and is responsible for calling ets_ds_finish_sign() and then
79  * ets_hmac_invalidate_downstream() afterwards.
80  *
81  * @return ETS_DS_OK if signature is in progress, ETS_DS_INVALID_PARAM if param is invalid,
82  * EST_DS_INVALID_KEY if key or HMAC peripheral is configured incorrectly.
83  */
84 ets_ds_result_t ets_ds_start_sign(const void *message, const ets_ds_data_t *data);
85 
86 
87 /*
88  * @brief Returns true if the DS peripheral is busy following a call to ets_ds_start_sign()
89  *
90  * A result of false indicates that a call to ets_ds_finish_sign() will not block.
91  *
92  * Only valid if ets_ds_enable() has been called.
93  */
94 bool ets_ds_is_busy(void);
95 
96 
97 /* @brief Finish signing a message using the Digital Signature peripheral
98  *
99  * Must be called after ets_ds_start_sign(). Can use ets_ds_busy() to wait until
100  * peripheral is no longer busy.
101  *
102  * - @param signature Pointer to buffer to contain the signature. Should be
103  *   (data->rsa_length + 1)*4 bytes long.
104  * - @param data Should match the 'data' parameter passed to ets_ds_start_sign()
105  *
106  * @param ETS_DS_OK if signing succeeded, ETS_DS_INVALID_PARAM if param is invalid,
107  * ETS_DS_INVALID_DIGEST or ETS_DS_INVALID_PADDING if there is a problem with the
108  * encrypted data digest or padding bytes (in case of ETS_DS_INVALID_PADDING, a
109  * digest is produced anyhow.)
110  */
111 ets_ds_result_t ets_ds_finish_sign(void *signature, const ets_ds_data_t *data);
112 
113 
114 /* Plaintext parameters used by Digital Signature.
115 
116    Not used for signing with DS peripheral, but can be encrypted
117    in-device by calling ets_ds_encrypt_params()
118 */
119 typedef struct {
120     uint32_t Y[4096/32];
121     uint32_t M[4096/32];
122     uint32_t Rb[4096/32];
123     uint32_t M_prime;
124     uint32_t length;
125 } ets_ds_p_data_t;
126 
127 typedef enum {
128     ETS_DS_KEY_HMAC, /* The HMAC key (as stored in efuse) */
129     ETS_DS_KEY_AES,  /* The AES key (as derived from HMAC key by HMAC peripheral in downstream mode) */
130 } ets_ds_key_t;
131 
132 /* @brief Encrypt DS parameters suitable for storing and later use with DS peripheral
133  *
134  * @param data Output buffer to store encrypted data, suitable for later use generating signatures.
135  * @param iv Pointer to 16 byte IV buffer, will be copied into 'data'. Should be randomly generated bytes each time.
136  * @param p_data Pointer to input plaintext key data. The expectation is this data will be deleted after this process is done and 'data' is stored.
137  * @param key Pointer to 32 bytes of key data. Type determined by key_type parameter. The expectation is the corresponding HMAC key will be stored to efuse and then permanently erased.
138  * @param key_type Type of key stored in 'key' (either the AES-256 DS key, or an HMAC DS key from which the AES DS key is derived using HMAC peripheral)
139  *
140  * @return ETS_DS_INVALID_PARAM if any parameter is invalid, or ETS_DS_OK if 'data' is successfully generated from the input parameters.
141  */
142 ets_ds_result_t ets_ds_encrypt_params(ets_ds_data_t *data, const void *iv, const ets_ds_p_data_t *p_data, const void *key, ets_ds_key_t key_type);
143 
144 
145 #ifdef __cplusplus
146 }
147 #endif
148