1 // Copyright 2015-2018 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef _ESP_TRANSPORT_SSL_H_ 16 #define _ESP_TRANSPORT_SSL_H_ 17 18 #include "esp_transport.h" 19 #include "esp_tls.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 26 /** 27 * @brief Create new SSL transport, the transport handle must be release esp_transport_destroy callback 28 * 29 * @return the allocated esp_transport_handle_t, or NULL if the handle can not be allocated 30 */ 31 esp_transport_handle_t esp_transport_ssl_init(void); 32 33 /** 34 * @brief Set SSL certificate data (as PEM format). 35 * Note that, this function stores the pointer to data, rather than making a copy. 36 * So this data must remain valid until after the connection is cleaned up 37 * 38 * @param t ssl transport 39 * @param[in] data The pem data 40 * @param[in] len The length 41 */ 42 void esp_transport_ssl_set_cert_data(esp_transport_handle_t t, const char *data, int len); 43 44 /** 45 * @brief Set SSL certificate data (as DER format). 46 * Note that, this function stores the pointer to data, rather than making a copy. 47 * So this data must remain valid until after the connection is cleaned up 48 * 49 * @param t ssl transport 50 * @param[in] data The der data 51 * @param[in] len The length 52 */ 53 void esp_transport_ssl_set_cert_data_der(esp_transport_handle_t t, const char *data, int len); 54 55 /** 56 * @brief Enable global CA store for SSL connection 57 * 58 * @param t ssl transport 59 */ 60 void esp_transport_ssl_enable_global_ca_store(esp_transport_handle_t t); 61 62 /** 63 * @brief Set SSL client certificate data for mutual authentication (as PEM format). 64 * Note that, this function stores the pointer to data, rather than making a copy. 65 * So this data must remain valid until after the connection is cleaned up 66 * 67 * @param t ssl transport 68 * @param[in] data The pem data 69 * @param[in] len The length 70 */ 71 void esp_transport_ssl_set_client_cert_data(esp_transport_handle_t t, const char *data, int len); 72 73 /** 74 * @brief Set SSL client certificate data for mutual authentication (as DER format). 75 * Note that, this function stores the pointer to data, rather than making a copy. 76 * So this data must remain valid until after the connection is cleaned up 77 * 78 * @param t ssl transport 79 * @param[in] data The der data 80 * @param[in] len The length 81 */ 82 void esp_transport_ssl_set_client_cert_data_der(esp_transport_handle_t t, const char *data, int len); 83 84 /** 85 * @brief Set SSL client key data for mutual authentication (as PEM format). 86 * Note that, this function stores the pointer to data, rather than making a copy. 87 * So this data must remain valid until after the connection is cleaned up 88 * 89 * @param t ssl transport 90 * @param[in] data The pem data 91 * @param[in] len The length 92 */ 93 void esp_transport_ssl_set_client_key_data(esp_transport_handle_t t, const char *data, int len); 94 95 /** 96 * @brief Set SSL client key password if the key is password protected. The configured 97 * password is passed to the underlying TLS stack to decrypt the client key 98 * 99 * @param t ssl transport 100 * @param[in] password Pointer to the password 101 * @param[in] password_len Password length 102 */ 103 void esp_transport_ssl_set_client_key_password(esp_transport_handle_t t, const char *password, int password_len); 104 105 /** 106 * @brief Set SSL client key data for mutual authentication (as DER format). 107 * Note that, this function stores the pointer to data, rather than making a copy. 108 * So this data must remain valid until after the connection is cleaned up 109 * 110 * @param t ssl transport 111 * @param[in] data The der data 112 * @param[in] len The length 113 */ 114 void esp_transport_ssl_set_client_key_data_der(esp_transport_handle_t t, const char *data, int len); 115 116 /** 117 * @brief Set the list of supported application protocols to be used with ALPN. 118 * Note that, this function stores the pointer to data, rather than making a copy. 119 * So this data must remain valid until after the connection is cleaned up 120 * 121 * @param t ssl transport 122 * @param[in] alpn_porot The list of ALPN protocols, the last entry must be NULL 123 */ 124 void esp_transport_ssl_set_alpn_protocol(esp_transport_handle_t t, const char **alpn_protos); 125 126 /** 127 * @brief Skip validation of certificate's common name field 128 * 129 * @note Skipping CN validation is not recommended 130 * 131 * @param t ssl transport 132 */ 133 void esp_transport_ssl_skip_common_name_check(esp_transport_handle_t t); 134 135 /** 136 * @brief Set the ssl context to use secure element (atecc608a) for client(device) private key and certificate 137 * 138 * @note Recommended to be used with ESP32-WROOM-32SE (which has inbuilt ATECC608A a.k.a Secure Element) 139 * 140 * @param t ssl transport 141 */ 142 void esp_transport_ssl_use_secure_element(esp_transport_handle_t t); 143 144 145 /** 146 * @brief Set the ds_data handle in ssl context.(used for the digital signature operation) 147 * 148 * @param t ssl transport 149 * ds_data the handle for ds data params 150 */ 151 152 void esp_transport_ssl_set_ds_data(esp_transport_handle_t t, void *ds_data); 153 154 /** 155 * @brief Set PSK key and hint for PSK server/client verification in esp-tls component. 156 * Important notes: 157 * - This function stores the pointer to data, rather than making a copy. 158 * So this data must remain valid until after the connection is cleaned up 159 * - ESP_TLS_PSK_VERIFICATION config option must be enabled in menuconfig 160 * - certificate verification takes priority so it must not be configured 161 * to enable PSK method. 162 * 163 * @param t ssl transport 164 * @param[in] psk_hint_key psk key and hint structure defined in esp_tls.h 165 */ 166 void esp_transport_ssl_set_psk_key_hint(esp_transport_handle_t t, const psk_hint_key_t* psk_hint_key); 167 168 /** 169 * @brief Set keep-alive status in current ssl context 170 * 171 * @param[in] t ssl transport 172 * @param[in] keep_alive_cfg The handle for keep-alive configuration 173 */ 174 void esp_transport_ssl_set_keep_alive(esp_transport_handle_t t, esp_transport_keep_alive_t *keep_alive_cfg); 175 176 #ifdef __cplusplus 177 } 178 #endif 179 #endif /* _ESP_TRANSPORT_SSL_H_ */ 180
