1 // Copyright 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 #pragma once
16 
17 #include <esp_err.h>
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 /**
24  * @brief   Proof Of Possession for authenticating a secure session
25  */
26 typedef struct protocomm_security_pop {
27     /**
28      * Pointer to buffer containing the proof of possession data
29      */
30     const uint8_t *data;
31 
32     /**
33      * Length (in bytes) of the proof of possession data
34      */
35     uint16_t len;
36 } protocomm_security_pop_t;
37 
38 typedef void * protocomm_security_handle_t;
39 
40 /**
41  * @brief   Protocomm security object structure.
42  *
43  * The member functions are used for implementing secure
44  * protocomm sessions.
45  *
46  * @note    This structure should not have any dynamic
47  *          members to allow re-entrancy
48  */
49 typedef struct protocomm_security {
50     /**
51      * Unique version number of security implementation
52      */
53     int ver;
54 
55     /**
56      * Function for initializing/allocating security
57      * infrastructure
58      */
59     esp_err_t (*init)(protocomm_security_handle_t *handle);
60 
61     /**
62      * Function for deallocating security infrastructure
63      */
64     esp_err_t (*cleanup)(protocomm_security_handle_t handle);
65 
66     /**
67      * Starts new secure transport session with specified ID
68      */
69     esp_err_t (*new_transport_session)(protocomm_security_handle_t handle,
70                                        uint32_t session_id);
71 
72     /**
73      * Closes a secure transport session with specified ID
74      */
75     esp_err_t (*close_transport_session)(protocomm_security_handle_t handle,
76                                          uint32_t session_id);
77 
78     /**
79      * Handler function for authenticating connection
80      * request and establishing secure session
81      */
82     esp_err_t (*security_req_handler)(protocomm_security_handle_t handle,
83                                       const protocomm_security_pop_t *pop,
84                                       uint32_t session_id,
85                                       const uint8_t *inbuf, ssize_t inlen,
86                                       uint8_t **outbuf, ssize_t *outlen,
87                                       void *priv_data);
88 
89     /**
90      * Function which implements the encryption algorithm
91      */
92     esp_err_t (*encrypt)(protocomm_security_handle_t handle,
93                          uint32_t session_id,
94                          const uint8_t *inbuf, ssize_t inlen,
95                          uint8_t *outbuf, ssize_t *outlen);
96 
97     /**
98      * Function which implements the decryption algorithm
99      */
100     esp_err_t (*decrypt)(protocomm_security_handle_t handle,
101                          uint32_t session_id,
102                          const uint8_t *inbuf, ssize_t inlen,
103                          uint8_t *outbuf, ssize_t *outlen);
104 } protocomm_security_t;
105 
106 #ifdef __cplusplus
107 }
108 #endif
109