sec_prot.h

00001 /*
00002  * Copyright (c) 2016-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 SEC_PROT_H_
00019 #define SEC_PROT_H_
00020 
00021 /*
00022  * Interface between KMP API and key management security protocols. Interface
00023  * provides abstraction for different security protocols for KMP API module.
00024  *
00025  * For security protocols it provides access to network, timing, callback
00026  * security keys and network address services.
00027  *
00028  */
00029 
00030 typedef enum {
00031     SEC_RESULT_OK = 0,
00032     SEC_RESULT_ERR_NO_MEM = -1,
00033     SEC_RESULT_ERR_TX_NO_ACK = -2,
00034     SEC_RESULT_ERR_UNSPEC = -3,
00035     SEC_RESULT_TIMEOUT = -4,
00036     SEC_RESULT_ERROR = -5,
00037     SEC_RESULT_CONF_ERROR = -6
00038 } sec_prot_result_e;
00039 
00040 typedef enum {
00041     SEC_STATE_INIT = 0,
00042     SEC_STATE_CREATE_REQ,
00043     SEC_STATE_CREATE_RESP,
00044     SEC_STATE_CREATE_IND,
00045     SEC_STATE_FINISH,
00046     SEC_STATE_FINISHED,
00047     SEC_STATE_FIRST
00048 } sec_prot_state_e;
00049 
00050 typedef enum {
00051     SEC_PROT_TYPE_EAP_TLS = 0,
00052     SEC_PROT_TYPE_TLS
00053 } sec_prot_type_e;
00054 
00055 typedef enum {
00056     SEC_PROT_TX_OK = 0,                       // Successful
00057     SEC_PROT_TX_ERR_TX_NO_ACK = -1,           // No acknowledge was received
00058     SEC_PROT_TX_ERR_UNSPEC = -2,              // Other reason
00059 } sec_prot_tx_status_e;
00060 
00061 /**
00062  * sec_prot_create_request KMP-CREATE.request to security protocol
00063  *
00064  * \param prot protocol
00065  * \param sec_keys security keys
00066  *
00067  */
00068 typedef void sec_prot_create_request(sec_prot_t *prot, sec_prot_keys_t *sec_keys);
00069 
00070 /**
00071  * sec_prot_create_response KMP-CREATE.response from security protocol
00072  *
00073  * \param prot protocol
00074  * \param result result
00075  *
00076  */
00077 typedef void sec_prot_create_response(sec_prot_t *prot, sec_prot_result_e result);
00078 
00079 /**
00080  * sec_prot_create_confirm KMP-CREATE.confirm from security protocol
00081  *
00082  * \param prot protocol
00083  * \param result result
00084  *
00085  */
00086 typedef void sec_prot_create_confirm(sec_prot_t *prot, sec_prot_result_e result);
00087 
00088 /**
00089  * sec_prot_create_indication KMP-CREATE.indication from security protocol
00090  *
00091  * \param prot protocol
00092  *
00093  */
00094 typedef void sec_prot_create_indication(sec_prot_t *prot);
00095 
00096 /**
00097  * sec_prot_finished_indication KMP-FINISHED.indication from security protocol
00098  *
00099  * \param prot protocol
00100  * \param result result
00101  * \param sec_keys security keys
00102  *
00103  */
00104 typedef void sec_prot_finished_indication(sec_prot_t *prot, sec_prot_result_e result, sec_prot_keys_t *sec_keys);
00105 
00106 /**
00107  * sec_prot_finished Security protocol has finished and is ready for delete
00108  *
00109  * \param prot protocol
00110  *
00111  */
00112 typedef void sec_prot_finished(sec_prot_t *prot);
00113 
00114 /**
00115  * sec_prot_finished_send Security protocol finished send
00116  *
00117  * \param prot protocol
00118  *
00119  */
00120 typedef void sec_prot_finished_send(sec_prot_t *prot);
00121 
00122 /**
00123  * sec_prot_receive receive a message
00124  *
00125  * \param prot protocol
00126  * \param pdu pdu
00127  * \param size pdu size
00128  *
00129  * \return < 0 failure
00130  * \return >= 0 success
00131  *
00132  */
00133 typedef int8_t sec_prot_receive(sec_prot_t *prot, void *pdu, uint16_t size);
00134 
00135 /**
00136  * sec_prot_send send a message
00137  *
00138  * \param prot protocol
00139  * \param pdu pdu
00140  * \param size pdu size
00141  *
00142  * \return < 0 failure
00143  * \return >= 0 success
00144  *
00145  */
00146 typedef int8_t sec_prot_send(sec_prot_t *prot, void *pdu, uint16_t size);
00147 
00148 /**
00149  * sec_prot_tx_status_ind tx status indication
00150  *
00151  * \param prot protocol
00152  * \param tx_status tx status
00153  *
00154  * \return < 0 failure
00155  * \return >= 0 success
00156  *
00157  */
00158 typedef int8_t sec_prot_tx_status_ind(sec_prot_t *prot, sec_prot_tx_status_e tx_status);
00159 
00160 /**
00161  * sec_prot_delete delete the protocol data
00162  *
00163  * \param prot protocol
00164  *
00165  */
00166 typedef void sec_prot_delete(sec_prot_t *prot);
00167 
00168 /**
00169  * sec_prot_state_machine protocol state machine
00170  *
00171  * \param prot protocol
00172  *
00173  */
00174 typedef void sec_prot_state_machine(sec_prot_t *prot);
00175 
00176 /**
00177  * sec_prot_state_machine_call call protocol state machine
00178  *
00179  * \param prot protocol
00180  *
00181  */
00182 typedef void sec_prot_state_machine_call(sec_prot_t *prot);
00183 
00184 /**
00185  * sec_prot_timer_start start timer
00186  *
00187  * \param prot protocol
00188  *
00189  */
00190 typedef void sec_prot_timer_start(sec_prot_t *prot);
00191 
00192 /**
00193  * sec_prot_timer_stop stop timer
00194  *
00195  * \param prot protocol
00196  *
00197  */
00198 typedef void sec_prot_timer_stop(sec_prot_t *prot);
00199 
00200 /**
00201  * sec_prot_timer_timeout timer timeout
00202  *
00203  * \param prot protocol
00204  * \param ticks timer ticks
00205  *
00206  */
00207 typedef void sec_prot_timer_timeout(sec_prot_t *prot, uint16_t ticks);
00208 
00209 /**
00210  * sec_prot_eui64_addr_get gets EUI-64 addresses
00211  *
00212  * \param prot protocol
00213  * \param local_eui64 local EUI-64
00214  * \param remote_eui64 remote EUI-64
00215  *
00216  */
00217 typedef void sec_prot_eui64_addr_get(sec_prot_t *prot, uint8_t *local_eui64, uint8_t *remote_eui64);
00218 
00219 /**
00220  * sec_prot_by_type_get gets security protocol
00221  *
00222  * \param prot protocol
00223  * \param type security protocol type
00224  *
00225  * \return security protocol or NULL
00226  *
00227  */
00228 typedef sec_prot_t *sec_prot_by_type_get(sec_prot_t *prot, uint8_t type);
00229 
00230 /**
00231  * sec_prot_receive_disable disables receiving of messages
00232  *
00233  * \param prot protocol
00234  *
00235  * \return security protocol or NULL
00236  *
00237  */
00238 typedef void sec_prot_receive_disable(sec_prot_t *prot);
00239 
00240 typedef struct sec_prot_int_data_s sec_prot_int_data_t;
00241 
00242 // Security protocol data
00243 struct sec_prot_s {
00244     sec_prot_create_request       *create_req;           /**< Create request */
00245     sec_prot_create_response      *create_resp;          /**< Create response */
00246 
00247     sec_prot_create_confirm       *create_conf;          /**< Create confirm */
00248     sec_prot_create_indication    *create_ind;           /**< Create indication */
00249     sec_prot_finished_indication  *finished_ind;         /**< Finished indication */
00250     sec_prot_finished             *finished;             /**< Finished i.e. ready to be deleted */
00251     sec_prot_finished_send        *finished_send;        /**< Send finished */
00252 
00253     sec_prot_send                 *send;                 /**< Protocol send */
00254     sec_prot_receive              *receive;              /**< Protocol receive */
00255     sec_prot_tx_status_ind        *tx_status_ind;        /**< TX status indication */
00256 
00257     sec_prot_delete               *delete;               /**< Protocol delete */
00258 
00259     sec_prot_state_machine_call   *state_machine_call;   /**< Call state machine */
00260     sec_prot_state_machine        *state_machine;        /**< Protocol state machine */
00261 
00262     sec_prot_timer_start          *timer_start;          /**< Start timer */
00263     sec_prot_timer_stop           *timer_stop;           /**< Stop timer */
00264     sec_prot_timer_timeout        *timer_timeout;        /**< Timer timeout */
00265 
00266     sec_prot_eui64_addr_get       *addr_get;             /**< Gets EUI-64 addresses */
00267     sec_prot_by_type_get          *type_get;             /**< Gets security protocol by type */
00268     sec_prot_receive_disable      *receive_disable;      /**< Disable receiving of messages */
00269 
00270     sec_prot_keys_t               *sec_keys;             /**< Security keys storage pointer */
00271     uint8_t                       header_size;           /**< Header size */
00272     sec_prot_int_data_t           *data;                 /**< Protocol internal data */
00273 };
00274 
00275 #endif /* SEC_PROT_H_ */