kmp_api.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 KMP_API_H_
00019 #define KMP_API_H_
00020 
00021 /*
00022  * KMP API and KMP service module. KMP API offers key management security
00023  * protocols interface towards application.
00024  *
00025  * KMP service provides security protocols access to network, timing
00026  * services and callback services. Application must configure KMP service
00027  * before using KMP API.
00028  *
00029  */
00030 
00031 typedef enum {
00032     KMP_TYPE_NONE = 0,
00033 
00034     IEEE_802_1X_MKA = 1,
00035     IEEE_802_11_4WH = 6,
00036     IEEE_802_11_GKH = 7,
00037     TLS_PROT        = 8,
00038 
00039     IEEE_802_1X_INITIAL_KEY = 10,
00040 
00041     IEEE_802_1X_MKA_KEY = 11,
00042     IEEE_802_11_4WH_KEY = 16,
00043     IEEE_802_11_GKH_KEY = 17
00044 } kmp_type_e;
00045 
00046 typedef enum {
00047     KMP_RESULT_OK = 0,                    // Successful
00048     KMP_RESULT_ERR_NO_MEM = -1,           // No memory
00049     KMP_RESULT_ERR_TX_NO_ACK = -2,        // No acknowledge was received
00050     KMP_RESULT_ERR_UNSPEC = -3            // Other reason
00051 } kmp_result_e;
00052 
00053 typedef enum {
00054     KMP_TX_OK = 0,                         // Successful
00055     KMP_TX_ERR_TX_NO_ACK = -1,             // No acknowledge was received
00056     KMP_TX_ERR_UNSPEC = -2,                // Other reason
00057 } kmp_tx_status_e;
00058 
00059 typedef void kmp_sec_keys_t;
00060 typedef struct sec_prot_s sec_prot_t;
00061 typedef struct kmp_api_s kmp_api_t;
00062 typedef struct kmp_service_s kmp_service_t;
00063 
00064 /**
00065  * kmp_api_create_request KMP-CREATE.request
00066  *
00067  * \param kmp instance
00068  * \param type protocol type
00069  * \param addr address
00070  * \param sec_keys security keys
00071  *
00072  */
00073 void kmp_api_create_request(kmp_api_t *kmp, kmp_type_e type, kmp_addr_t *addr, kmp_sec_keys_t *sec_keys);
00074 
00075 /**
00076  * kmp_api_create_confirm KMP-CREATE.confirm
00077  *
00078  * \param kmp instance
00079  * \param result ok or fail
00080  *
00081  */
00082 typedef void kmp_api_create_confirm(kmp_api_t *kmp, kmp_result_e result);
00083 
00084 /**
00085  * kmp_api_create_indication KMP-CREATE.indication
00086  *
00087  * \param kmp instance
00088  * \param type protocol type
00089  * \param addr address
00090  *
00091  */
00092 typedef void kmp_api_create_indication(kmp_api_t *kmp, kmp_type_e type, kmp_addr_t *addr);
00093 
00094 /**
00095  * kmp_api_create_response KMP-CREATE.response
00096  *
00097  * \param kmp instance
00098  * \param result ok or fail
00099  *
00100  */
00101 void kmp_api_create_response(kmp_api_t *kmp, kmp_result_e result);
00102 
00103 /**
00104  * kmp_api_finished_indication KMP-FINISHED.indication
00105  *
00106  * \param kmp instance
00107  * \param result ok or fail
00108  * \param sec_keys security keys
00109  *
00110  */
00111 typedef void kmp_api_finished_indication(kmp_api_t *kmp, kmp_result_e result, kmp_sec_keys_t *sec_keys);
00112 
00113 /**
00114  * kmp_api_finished will be called when KMP has finished and is ready for delete
00115  *
00116  * \param kmp instance
00117  *
00118  */
00119 typedef void kmp_api_finished(kmp_api_t *kmp);
00120 
00121 /**
00122  * kmp_api_create create KMP api
00123  *
00124  * \param service KMP service
00125  * \param type KMP type
00126  *
00127  * \return KMP instance or NULL
00128  *
00129  */
00130 kmp_api_t *kmp_api_create(kmp_service_t *service, kmp_type_e type);
00131 
00132 /**
00133  * kmp_api_start start KMP api
00134  *
00135  * \param kmp instance
00136  *
00137  * \return < 0 failure
00138  * \return >= 0 success
00139  *
00140  */
00141 int8_t kmp_api_start(kmp_api_t *kmp);
00142 
00143 /**
00144  * kmp_api_create create KMP api
00145  *
00146  * \param kmp instance
00147  *
00148  */
00149 void kmp_api_delete(kmp_api_t *kmp);
00150 
00151 /**
00152  * kmp_api_type_get get KMP type
00153  *
00154  * \param kmp instance
00155  *
00156  * \return kmp_type_e KMP type
00157  *
00158  */
00159 kmp_type_e kmp_api_type_get(kmp_api_t *kmp);
00160 
00161 /**
00162  * kmp_api_type_get get receive disabled status
00163  *
00164  * \param kmp instance
00165  *
00166  * \return true/false true when receiving has been disabled
00167  *
00168  */
00169 bool kmp_api_receive_disable(kmp_api_t *kmp);
00170 
00171 /**
00172  * kmp_api_type_from_id_get get KMP type from KMP id
00173  *
00174  * \param kmp_id KMP identifier
00175  *
00176  * \return kmp_type_e KMP type
00177  *
00178  */
00179 kmp_type_e kmp_api_type_from_id_get(uint8_t kmp_id);
00180 
00181 /**
00182  * kmp_api_service_get get KMP service for KMP instance
00183  *
00184  * \param kmp instance
00185  *
00186  * \return service
00187  *
00188  */
00189 kmp_service_t *kmp_api_service_get(kmp_api_t *kmp);
00190 
00191 /**
00192  * kmp_api_data_set set application data
00193  *
00194  * \param kmp instance
00195  * \param data data
00196  *
00197  */
00198 void kmp_api_data_set(kmp_api_t *kmp, void *data);
00199 
00200 /**
00201  * kmp_api_data_get read application data
00202  *
00203  * \param kmp instance
00204  *
00205  * \return data
00206  *
00207  */
00208 void *kmp_api_data_get(kmp_api_t *kmp);
00209 
00210 /**
00211  * kmp_api_id_get get KMP instance identifier
00212  *
00213  * \param kmp instance
00214  *
00215  * \return instance identifier
00216  *
00217  */
00218 uint8_t kmp_api_instance_id_get(kmp_api_t *kmp);
00219 
00220 /**
00221  * kmp_api_addr_set set address
00222  *
00223  * \param kmp instance
00224  * \param addr addr
00225  *
00226  */
00227 void kmp_api_addr_set(kmp_api_t *kmp, kmp_addr_t *addr);
00228 
00229 /**
00230  * kmp_api_sec_keys_set set security keys
00231  *
00232  * \param kmp instance
00233  * \param sec_keys security keys
00234  *
00235  */
00236 void kmp_api_sec_keys_set(kmp_api_t *kmp, kmp_sec_keys_t *sec_keys);
00237 
00238 /**
00239  * kmp_api_cb_register registers api callbacks
00240  *
00241  * \param kmp instance
00242  * \param create_conf KMP-CREATE.confirm callback
00243  * \param create_ind KMP-CREATE.indication callback
00244  * \param finished_ind KMP-FINISHED.indication
00245  * \param finish KMP has finished and is ready for delete
00246  *
00247  */
00248 void kmp_api_cb_register(kmp_api_t *kmp, kmp_api_create_confirm *create_conf, kmp_api_create_indication *create_ind, kmp_api_finished_indication *finished_ind, kmp_api_finished *finished);
00249 
00250 /**
00251  * kmp_service_create creates KMP service
00252  *
00253  * \return service or NULL
00254  *
00255  */
00256 kmp_service_t *kmp_service_create(void);
00257 
00258 /**
00259  * kmp_service_delete deletes KMP service
00260  *
00261  * \param service KMP service
00262  *
00263  * \return < 0 failure
00264  * \return >= 0 success
00265  *
00266  */
00267 int8_t kmp_service_delete(kmp_service_t *service);
00268 
00269 /**
00270  * kmp_service_incoming_ind Notifies application about incoming KMP frame
00271  *
00272  * \param service KMP service
00273  * \param type protocol type
00274  * \param addr address
00275  *
00276  * \return KMP instance or NULL
00277  *
00278  */
00279 typedef kmp_api_t *kmp_service_incoming_ind(kmp_service_t *service, kmp_type_e type, const kmp_addr_t *addr);
00280 
00281 /**
00282  * kmp_service_tx_status_ind Notifies application about TX status
00283  *
00284  * \param service KMP service
00285  * \param instance_id KMP instance identifier
00286  *
00287  * \return KMP instance or NULL
00288  *
00289  */
00290 typedef kmp_api_t *kmp_service_tx_status_ind(kmp_service_t *service, uint8_t instance_id);
00291 
00292 /**
00293  * kmp_service_addr_get gets addressing information related to KMP
00294  *
00295  * \param service KMP service
00296  * \param kmp KMP instance
00297  * \param local_addr Local address
00298  * \param remote_addr Remote address
00299  *
00300  */
00301 typedef void kmp_service_addr_get(kmp_service_t *service, kmp_api_t *kmp, kmp_addr_t *local_addr, kmp_addr_t *remote_addr);
00302 
00303 /**
00304  * kmp_service_api_get gets KMP API from KMP service
00305  *
00306  * \param service KMP service
00307  * \param kmp KMP instance
00308  * \param type protocol type
00309  *
00310  * \return KMP instance or NULL
00311  *
00312  */
00313 typedef kmp_api_t *kmp_service_api_get(kmp_service_t *service, kmp_api_t *kmp, kmp_type_e type);
00314 
00315 /**
00316  * kmp_service_cb_register registers service callbacks
00317  *
00318  * \param service KMP service
00319  * \param incoming_ind incoming message callback
00320  * \param tx_status tx status callback
00321  * \param addr_get gets addressing information callback
00322  * \param api_get gets KMP API from KMP service
00323  *
00324  * \return < 0 failure
00325  * \return >= 0 success
00326  *
00327  */
00328 int8_t kmp_service_cb_register(kmp_service_t *service, kmp_service_incoming_ind *incoming_ind, kmp_service_tx_status_ind *tx_status_ind, kmp_service_addr_get *addr_get, kmp_service_api_get *api_get);
00329 
00330 /**
00331  * kmp_service_msg_if_receive receive a message
00332  *
00333  * \param service KMP service
00334  * \param type protocol type
00335  * \param addr address
00336  * \param pdu pdu
00337  * \param size pdu size
00338  *
00339  * \return < 0 failure
00340  * \return >= 0 success
00341  *
00342  */
00343 int8_t kmp_service_msg_if_receive(kmp_service_t *service, kmp_type_e kmp_id, const kmp_addr_t *addr, void *pdu, uint16_t size);
00344 
00345 /**
00346  * kmp_service_msg_if_send send a message
00347  *
00348  * \param service KMP service
00349  * \param type protocol type
00350  * \param addr address
00351  * \param pdu pdu
00352  * \param size pdu size
00353  * \param tx_identifier TX identifier
00354  *
00355  * \return < 0 failure
00356  * \return >= 0 success
00357  *
00358  */
00359 typedef int8_t kmp_service_msg_if_send(kmp_service_t *service, kmp_type_e type, const kmp_addr_t *addr, void *pdu, uint16_t size, uint8_t tx_identifier);
00360 
00361 /**
00362  * kmp_service_msg_if_register registers message interface
00363  *
00364  * \param service KMP service
00365  * \param send KMP PDU send callback
00366  * \param header_size header size
00367  *
00368  * \return < 0 failure
00369  * \return >= 0 success
00370  *
00371  */
00372 int8_t kmp_service_msg_if_register(kmp_service_t *service, kmp_service_msg_if_send *send, uint8_t header_size);
00373 
00374 /**
00375  * kmp_service_tx_status tx status indication
00376  *
00377  * \param service KMP service
00378  * \param tx_status tx status
00379  * \param tx_identifier tx identifier
00380  *
00381  * \return < 0 failure
00382  * \return >= 0 success
00383  *
00384  */
00385 int8_t kmp_service_tx_status_indication(kmp_service_t *service, kmp_tx_status_e tx_status, uint8_t tx_identifier);
00386 
00387 /**
00388  * kmp_sec_prot_size security protocol data size
00389  *
00390  * \return size
00391  *
00392  */
00393 typedef uint16_t kmp_sec_prot_size(void);
00394 
00395 /**
00396  * kmp_sec_prot_init security protocol init callback
00397  *
00398  * \param prot protocol data
00399  *
00400  * \return < 0 failure
00401  * \return >= 0 success
00402  *
00403  */
00404 typedef int8_t kmp_sec_prot_init(sec_prot_t *prot);
00405 
00406 /**
00407  * kmp_service_sec_protocol_register register a security protocol to KMP service
00408  *
00409  * \param service KMP service
00410  * \param type protocol type
00411  * \param size size callback
00412  * \param init init callback
00413  *
00414  * \return < 0 failure
00415  * \return >= 0 success
00416  *
00417  */
00418 int8_t kmp_service_sec_protocol_register(kmp_service_t *service, kmp_type_e type, kmp_sec_prot_size *size, kmp_sec_prot_init *init);
00419 
00420 /**
00421  * kmp_service_sec_protocol_unregister unregister a security protocol from KMP service
00422  *
00423  * \param service KMP service
00424  * \param type protocol type
00425  *
00426  * \return < 0 failure
00427  * \return >= 0 success
00428  *
00429  */
00430 int8_t kmp_service_sec_protocol_unregister(kmp_service_t *service, kmp_type_e type);
00431 
00432 /**
00433  * kmp_service_timer_if_timeout timer timeout
00434  *
00435  * \param service KMP instance
00436  *
00437  */
00438 void kmp_service_timer_if_timeout(kmp_api_t *kmp, uint16_t ticks);
00439 
00440 /**
00441  * kmp_service_timer_if_start timer start callback
00442  *
00443  * \param service KMP service
00444  * \param kmp KMP instance
00445  *
00446  * \return < 0 failure
00447  * \return >= 0 success
00448  *
00449  */
00450 typedef int8_t kmp_service_timer_if_start(kmp_service_t *service, kmp_api_t *kmp);
00451 
00452 /**
00453  * kmp_service_timer_if_stop timer stop callback
00454  *
00455  * \param service KMP service
00456  * \param kmp KMP instance
00457  *
00458  * \return < 0 failure
00459  * \return >= 0 success
00460  *
00461  */
00462 typedef int8_t kmp_service_timer_if_stop(kmp_service_t *service, kmp_api_t *kmp);
00463 
00464 /**
00465  * kmp_service_timer_if_register register a timer interface to KMP service
00466  *
00467  * \param service KMP service
00468  * \param start timer start callback
00469  * \param stop timer stop callback
00470  *
00471  * \return < 0 failure
00472  * \return >= 0 success
00473  *
00474  */
00475 int8_t kmp_service_timer_if_register(kmp_service_t *service, kmp_service_timer_if_start start, kmp_service_timer_if_stop stop);
00476 
00477 /**
00478  * kmp_service_event_if_event event callback
00479  *
00480  * \param service KMP service
00481  * \param data opaque callback data
00482  *
00483  */
00484 void kmp_service_event_if_event(kmp_service_t *service, void *data);
00485 
00486 /**
00487  * kmp_service_event_if_event_send event send callback
00488  *
00489  * \param service KMP service
00490  * \param data opaque callback data
00491  *
00492  * \return < 0 failure
00493  * \return >= 0 success
00494  *
00495  */
00496 typedef int8_t kmp_service_event_if_event_send(kmp_service_t *service, void *data);
00497 
00498 /**
00499  * kmp_service_event_if_register register an event interface to KMP service
00500  *
00501  * \param service KMP service
00502  * \param send send event
00503  *
00504  * \return < 0 failure
00505  * \return >= 0 success
00506  *
00507  */
00508 int8_t kmp_service_event_if_register(kmp_service_t *service, kmp_service_event_if_event_send send);
00509 
00510 #endif /* KMP_API_H_ */