tls_sec_prot_lib.h

00001 /*
00002  * Copyright (c) 2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef TLS_SEC_PROT_LIB_H_
00019 #define TLS_SEC_PROT_LIB_H_
00020 
00021 /*
00022  * TLS security protocol library to connect to mbed TLS
00023  *
00024  */
00025 
00026 typedef struct tls_security_s tls_security_t;
00027 
00028 typedef enum {
00029     TLS_SEC_PROT_LIB_ERROR = -2,
00030     TLS_SEC_PROT_LIB_NO_DATA = -1,
00031     TLS_SEC_PROT_LIB_CONTINUE = 0,
00032     TLS_SEC_PROT_LIB_CALCULATING,
00033     TLS_SEC_PROT_LIB_HANDSHAKE_OVER,
00034 } tls_sec_prot_lib_ret_e;
00035 
00036 typedef enum {
00037     TLS_SEC_PROT_LIB_TIMER_CANCELLED = -1,
00038     TLS_SEC_PROT_LIB_TIMER_NO_EXPIRY = 0,
00039     TLS_SEC_PROT_LIB_TIMER_INT_EXPIRY = 1,
00040     TLS_SEC_PROT_LIB_TIMER_FIN_EXPIRY = 2,
00041 } tls_sec_prot_lib_timer_e;
00042 
00043 // Maximum operations made on one round of ECC calculation
00044 #define ECC_CALCULATION_MAX_OPS            200
00045 
00046 /**
00047  * tls_sec_prot_lib_init initialize security library
00048  *
00049  * \param sec security library instance
00050  *
00051  * \return < 0 failure
00052  * \return >= 0 success
00053  */
00054 int8_t tls_sec_prot_lib_init(tls_security_t *sec);
00055 
00056 /**
00057  * tls_sec_prot_lib_size get security library instance size
00058  *
00059  * \return size
00060  */
00061 uint16_t tls_sec_prot_lib_size(void);
00062 
00063 /**
00064  * tls_sec_prot_lib_send send data callback
00065  *
00066  * \param handle caller defined handle
00067  * \param buf buffer to be send
00068  * \param len length of the buffer
00069  *
00070  * \return length of the send data
00071  */
00072 typedef int16_t tls_sec_prot_lib_send(void *handle, const void *buf, size_t len);
00073 
00074 /**
00075  * tls_sec_prot_lib_receive receive data callback
00076  *
00077  * \param handle caller defined handle
00078  * \param buf receive buffer
00079  * \param len receive buffer length
00080  *
00081  * \return length of the received data written to receive buffer
00082  * \return TLS_SEC_PROT_LIB_NO_DATA no more data received
00083  */
00084 typedef int16_t tls_sec_prot_lib_receive(void *handle, unsigned char *buf, size_t len);
00085 
00086 /**
00087  * tls_sec_prot_lib_set_timer set timer callback
00088  *
00089  * \param handle caller defined handle
00090  * \param inter intermediate timeout
00091  * \param fin final timeout
00092  *
00093  */
00094 typedef void tls_sec_prot_lib_set_timer(void *handle, uint32_t inter, uint32_t fin);
00095 
00096 /**
00097  * tls_sec_prot_lib_get_timer get timer callback
00098  *
00099  * \param handle caller defined handle
00100  *
00101  * \return TLS_SEC_PROT_LIB_TIMER_CANCELLED timer cancelled
00102  * \return TLS_SEC_PROT_LIB_TIMER_FIN_EXPIRY final timeout has expired
00103  * \return TLS_SEC_PROT_LIB_TIMER_INT_EXPIRY intermediate timeout has expired
00104  * \retunt TLS_SEC_PROT_LIB_TIMER_NO_EXPIRY timer has not expired
00105  *
00106  */
00107 typedef int8_t tls_sec_prot_lib_get_timer(void *handle);
00108 
00109 /**
00110  * tls_sec_prot_lib_export_keys export key material after handshake is completed
00111  *
00112  * \param handle caller defined handle
00113  * \param master_secret TLS master secret, 48 bytes
00114  * \param eap_tls_key_material EAP TLS key material, 128 bytes
00115  *
00116  */
00117 typedef void tls_sec_prot_lib_export_keys(void *handle, const uint8_t *master_secret, const uint8_t *eap_tls_key_material);
00118 
00119 /**
00120  * tls_sec_prot_lib_set_cb_register register callbacks to library
00121  *
00122  * \param sec security library instance
00123  * \param handle caller defined handle
00124  * \param send send data callback
00125  * \param receive receive data callback
00126  * \param export_keys export keys callback
00127  * \param set_timer set timer callback
00128  * \param get_timer get timer callback
00129  *
00130  */
00131 void tls_sec_prot_lib_set_cb_register(tls_security_t *sec, void *handle,
00132                                       tls_sec_prot_lib_send *send, tls_sec_prot_lib_receive *receive,
00133                                       tls_sec_prot_lib_export_keys *export_keys, tls_sec_prot_lib_set_timer *set_timer,
00134                                       tls_sec_prot_lib_get_timer *get_timer);
00135 
00136 /**
00137  * tls_sec_prot_lib_free free security library internal data (e.g. TLS data)
00138  *
00139  * \param sec security library instance
00140  *
00141  */
00142 void tls_sec_prot_lib_free(tls_security_t *sec);
00143 
00144 /**
00145  * tls_sec_prot_lib_connect start TLS handshake
00146  *
00147  * \param sec security library instance
00148  * \param is_server TRUE if TLS server, FALSE for TLS client
00149  * \param certs certificates
00150  *
00151  * \return < 0 failure
00152  * \return >= 0 success
00153  */
00154 int8_t tls_sec_prot_lib_connect(tls_security_t *sec, bool is_server, const sec_prot_certs_t *certs);
00155 
00156 /**
00157  * tls_sec_prot_lib_process process TLS (call e.g. after incoming message)
00158  *
00159  * \param sec Security library instance
00160  *
00161  * \return TLS_SEC_PROT_LIB_ERROR failure, failure, stop TLS negotiation
00162  * \return TLS_SEC_PROT_LIB_CONTINUE continue processing (send output message)
00163  * \return TLS_SEC_PROT_LIB_CALCULATING calculation ongoing, call process again
00164  * \return TLS_SEC_PROT_LIB_HANDSHAKE_OVER handshake completed successfully
00165  *
00166  */
00167 int8_t tls_sec_prot_lib_process(tls_security_t *sec);
00168 
00169 #endif /* TLS_SEC_PROT_LIB_H_ */