1 /* 2 Copyright (c) 2021 Fraunhofer AISEC. See the COPYRIGHT 3 file at the top-level directory of this distribution. 4 5 Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or 6 http://www.apache.org/licenses/LICENSE-2.0> or the MIT license 7 <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your 8 option. This file may not be copied, modified, or distributed 9 except according to those terms. 10 */ 11 12 #ifndef EDHOC_H 13 #define EDHOC_H 14 15 #include <stdint.h> 16 17 #include "edhoc/edhoc_method_type.h" 18 #include "edhoc/messages.h" 19 #include "edhoc/suites.h" 20 #include "edhoc/hkdf_info.h" 21 22 #include "common/oscore_edhoc_error.h" 23 #include "common/byte_array.h" 24 #include "common/print_util.h" 25 26 #ifdef _WIN32 27 #define WEAK 28 #else 29 #define WEAK __attribute__((weak)) 30 #endif 31 32 struct other_party_cred { 33 struct byte_array id_cred; /*ID_CRED_x of the other party*/ 34 struct byte_array cred; /*CBOR encoded credentials*/ 35 struct byte_array pk; /*authentication pub key of the other party */ 36 struct byte_array g; /*authentication static DH pub key of other party */ 37 struct byte_array ca; /*use only when certificates are used*/ 38 struct byte_array ca_pk; /*use only when certificates are used*/ 39 }; 40 41 struct cred_array { 42 uint32_t len; 43 struct other_party_cred *ptr; 44 }; 45 46 struct edhoc_responder_context { 47 struct byte_array c_r; /*connection identifier of the responder*/ 48 struct byte_array suites_r; 49 struct byte_array g_y; /*ephemeral dh public key*/ 50 struct byte_array y; /*ephemeral dh secret key*/ 51 struct byte_array g_r; /* static DH pk -> use only with method 1 or 3*/ 52 struct byte_array r; /* static DH sk -> use only with method 1 or 3*/ 53 struct byte_array ead_2; /*EAD to be send in message 2*/ 54 struct byte_array ead_4; /*EAD to be send in message 4*/ 55 struct byte_array id_cred_r; 56 struct byte_array cred_r; 57 struct byte_array sk_r; /*sign key -use with method 0 and 2*/ 58 struct byte_array pk_r; /*coresp. pk to sk_r -use with method 0 and 2*/ 59 void *sock; /*pointer used as handler for sockets by tx/rx */ 60 void *params_ead_process; /*parameters for processing EAD1 and EAD3 */ 61 }; 62 63 struct edhoc_initiator_context { 64 struct byte_array c_i; /*connection identifier of the initiator*/ 65 enum method_type method; 66 struct byte_array suites_i; 67 struct byte_array ead_1; 68 struct byte_array ead_3; 69 struct byte_array id_cred_i; 70 struct byte_array cred_i; 71 struct byte_array g_x; /*ephemeral dh public key*/ 72 struct byte_array x; /*ephemeral dh secret key*/ 73 struct byte_array g_i; /* static DH pk -> use only with method 2 or 3*/ 74 struct byte_array i; /* static DH sk -> use only with method 2 or 3*/ 75 struct byte_array sk_i; /*sign key use with method 0 and 2*/ 76 struct byte_array pk_i; /*coresp. pk to sk_r -use with method 0 and 2*/ 77 void *sock; /*pointer used as handler for sockets by tx/rx */ 78 void *params_ead_process; /*parameters for processing EAD2 and EAD4 */ 79 }; 80 81 /** 82 * @brief Generates ephemeral DH keys from a random seed. 83 * 84 * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 85 * IMPORTANT!!! PROVIDE A GOOD RANDOM SEED! 86 * !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 87 * 88 * @param alg The ECDH algorithm to be used. 89 * @param seed A random seed. 90 * @param[out] sk The newly generated private key. 91 * @param[out] pk The newly private private key. 92 * @return Ok or error code. 93 */ 94 enum err WEAK ephemeral_dh_key_gen(enum ecdh_alg alg, uint32_t seed, 95 struct byte_array *sk, 96 struct byte_array *pk); 97 98 /** 99 * @brief Executes EDHOC on the initiator side. 100 * 101 * @param[in] c Initialization parameters. 102 * @param[in] cred_r_array Trust anchors for authenticating the responder. 103 * @param[out] err_msg A buffer for an error message. 104 * @param[out] prk_out The derived shared secret. 105 * @param tx A callback function for sending messages. 106 * @param rx A callback function for receiving messages. 107 * @param ead_process A callback function for processing EAD. 108 * @return Ok or error code. 109 */ 110 enum err edhoc_initiator_run( 111 const struct edhoc_initiator_context *c, 112 struct cred_array *cred_r_array, struct byte_array *err_msg, 113 struct byte_array *prk_out, 114 enum err (*tx)(void *sock, struct byte_array *data), 115 enum err (*rx)(void *sock, struct byte_array *data), 116 enum err (*ead_process)(void *params, struct byte_array *ead24)); 117 118 /** 119 * @brief Executes EDHOC on the initiator side and 120 * provides access to the received C_R 121 * 122 * @param[in] c Initialization parameters. 123 * @param[in] cred_r_array Trust anchors for authenticating the responder. 124 * @param[out] err_msg A buffer for an error message. 125 * @param[out] c_r_bytes Connection identifier of requester. 126 * @param[out] prk_out The derived shared secret. 127 * @param tx A callback function for sending messages. 128 * @param rx A callback function for receiving messages. 129 * @param ead_process A callback function for processing EAD. 130 * @return Ok or error code. 131 */ 132 enum err edhoc_initiator_run_extended( 133 const struct edhoc_initiator_context *c, 134 struct cred_array *cred_r_array, struct byte_array *err_msg, 135 struct byte_array *c_r_bytes, struct byte_array *prk_out, 136 enum err (*tx)(void *sock, struct byte_array *data), 137 enum err (*rx)(void *sock, struct byte_array *data), 138 enum err (*ead_process)(void *params, struct byte_array *ead24)); 139 140 /** 141 * @brief Executes EDHOC on the responder side. 142 * 143 * @param[in] c Initialization parameters. 144 * @param[in] cred_i_array Trust anchors for authenticating the initiator. 145 * @param[out] err_msg A buffer for an error message. 146 * @param[out] prk_out The derived shared secret. 147 * @param tx A callback function for sending messages. 148 * @param rx A callback function for receiving messages. 149 * @param ead_process A callback function for processing EAD. 150 * @return Ok or error code. 151 */ 152 enum err edhoc_responder_run( 153 struct edhoc_responder_context *c, struct cred_array *cred_i_array, 154 struct byte_array *err_msg, struct byte_array *prk_out, 155 enum err (*tx)(void *sock, struct byte_array *data), 156 enum err (*rx)(void *sock, struct byte_array *data), 157 enum err (*ead_process)(void *params, struct byte_array *ead13)); 158 159 /** 160 * @brief Executes EDHOC on the responder side and 161 * provides access to the received C_I 162 * 163 * @param[in] c Initialization parameters. 164 * @param[in] cred_i_array Trust anchors for authenticating the initiator. 165 * @param[out] err_msg A buffer for an error message. 166 * @param[out] prk_out The derived shared secret. 167 * @param[out] initiator_pk Public key of the initiator. 168 * @param[out] c_i_bytes Connection identifier of the initiator. 169 * @param tx A callback function for sending messages. 170 * @param rx A callback function for receiving messages. 171 * @param ead_process A callback function for processing EAD. 172 * @return Ok or error code. 173 */ 174 enum err edhoc_responder_run_extended( 175 struct edhoc_responder_context *c, struct cred_array *cred_i_array, 176 struct byte_array *err_msg, struct byte_array *prk_out, 177 struct byte_array *initiator_pk, struct byte_array *c_i_bytes, 178 enum err (*tx)(void *sock, struct byte_array *data), 179 enum err (*rx)(void *sock, struct byte_array *data), 180 enum err (*ead_process)(void *params, struct byte_array *ead13)); 181 182 /** 183 * @brief Computes PRK_exporter from PRK_out. 184 * 185 * @param app_hash_alg The EDHOC hash algorithm. 186 * @param[in] prk_out The product of a successful EDHOC execution. 187 * @param[out] prk_exporter The result. 188 * @return Ok or error code. 189 */ 190 enum err prk_out2exporter(enum hash_alg app_hash_alg, 191 struct byte_array *prk_out, 192 struct byte_array *prk_exporter); 193 194 /** 195 * @brief Updates PRK_out. 196 * 197 * @param app_hash_alg The EDHOC hash algorithm. 198 * @param[in] prk_out The product of a successful EDHOC execution. 199 * @param[in] context A common context known by initiator & responder. 200 * @param[out] prk_out_new The new prk_out value. 201 * @return Ok or error code. 202 */ 203 enum err prk_out_update(enum hash_alg app_hash_alg, struct byte_array *prk_out, 204 struct byte_array *context, 205 struct byte_array *prk_out_new); 206 207 enum export_label { 208 OSCORE_MASTER_SECRET = 0, 209 OSCORE_MASTER_SALT = 1, 210 }; 211 212 /** 213 * @brief Computes key material to be used within the 214 * application, e.g., OSCORE master secret or 215 * OSCORE master salt. 216 * 217 * @param app_hash_alg The application hash algorithm. 218 * @param label An uint value defined by the application. 219 * @param[in] prk_exporter PRK computed with prk_out2exporter(). 220 * @param[out] out The result of the computation, e.g., OSCORE 221 * master secret or OSCORE master salt. 222 * @return Ok or error code. 223 */ 224 enum err edhoc_exporter(enum hash_alg app_hash_alg, enum export_label label, 225 struct byte_array *prk_exporter, 226 struct byte_array *out); 227 228 #endif 229
