[IOT-1947][IOT-2761][IOT-3228] Rm PEM/DER convert
[iotivity.git] / resource / csdk / connectivity / api / casecurityinterface.h
1 /* *****************************************************************
2  *
3  * Copyright 2015 Samsung Electronics All Rights Reserved.
4  *
5  *
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  *      http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  ******************************************************************/
20
21 /**
22  * @file
23  *
24  * This file contains the Security APIs for Resource Model to use.
25  */
26
27 #ifndef CA_SECURITY_INTERFACE_H_
28 #define CA_SECURITY_INTERFACE_H_
29
30
31 #include "cacommon.h"
32 #include "experimental/ocrandom.h"
33 #include "experimental/byte_array.h"
34
35 #ifdef __cplusplus
36 extern "C"
37 {
38 #endif
39
40 /**
41  * @enum CADtlsPskCredType_t
42  * Type of PSK credential required during DTLS handshake
43  * It does not make much sense in bringing in all definitions from dtls.h into here.
44  * Therefore, redefining them here.
45  */
46 typedef enum
47 {
48     CA_DTLS_PSK_HINT,
49     CA_DTLS_PSK_IDENTITY,
50     CA_DTLS_PSK_KEY
51 } CADtlsPskCredType_t;
52
53 /**
54  * This internal callback is used by CA layer to
55  * retrieve PSK credentials from SRM.
56  *
57  * @param[in]  type type of PSK data required by CA layer during DTLS handshake set.
58  * @param[in]  desc    Additional request information.
59  * @param[in]  desc_len The actual length of desc.
60  * @param[out] result  Must be filled with the requested information.
61  * @param[in]  result_length  Maximum size of @p result.
62  *
63  * @return The number of bytes written to @p result or a value
64  *         less than zero on error.
65  */
66 typedef int (*CAgetPskCredentialsHandler)(CADtlsPskCredType_t type,
67               const uint8_t *desc, size_t desc_len,
68               uint8_t *result, size_t result_length);
69
70 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
71
72 /**
73  * API to get security information about a connected peer
74  *
75  * @param[in] peer peer information includs IP address and port.
76  * @param[out] sep copy of secure endpoint info
77  *
78  * @return  CA_STATUS_OK on success; other error otherwise
79  */
80 CAResult_t CAGetSecureEndpointData(const CAEndpoint_t *peer, CASecureEndpoint_t *sep);
81
82 /**
83  * Adds a bit to the attributes field of a secure endpoint.
84  *
85  * @param[in]  peer         remote address
86  * @param[in]  newAttribute bit to be added to the attributes field
87  *
88  * @return  true if the secure endpoint has been found, false otherwise.
89  */
90 bool CASetSecureEndpointAttribute(const CAEndpoint_t* peer, uint32_t newAttribute);
91
92 /**
93  * Gets the attributes field of a secure endpoint.
94  *
95  * @param[in]  peer          remote address
96  * @param[out] allAttributes all the attributes bits for that remote address
97  *
98  * @return  true if the secure endpoint has been found, false otherwise.
99  */
100 bool CAGetSecureEndpointAttributes(const CAEndpoint_t* peer, uint32_t* allAttributes);
101 #endif // #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
102
103 /**
104  * This internal callback is used by CA layer to
105  * retrieve all credential types from SRM
106  *
107  * @param[out]  list of enabled credential types for CA handshake.
108  * @param[in]   device uuid.
109  *
110  */
111 typedef void (*CAgetCredentialTypesHandler)(bool * list, const char* deviceId);
112
113 /**
114  * Binary structure containing PKIX related info
115  * own certificate chain, public key, CA's and CRL's
116  * The data member of each ByteArray_t must be allocated with OICMalloc or OICCalloc.
117  * The SSL adapter takes ownership of this memory and will free it internally after use.
118  * Callers should not reference this memory after it has been provided to the SSL adapter via the
119  * callback.
120  */
121 typedef struct
122 {
123     ByteArrayLL_t crt;  /**< own certificate chain as a null-terminated PEM string of certificates */
124     ByteArray_t key;    /**< own private key as binary-encoded DER */
125     ByteArrayLL_t ca;   /**< trusted CAs as a null-terminated PEM string of certificates */
126     ByteArray_t crl;    /**< trusted CRLs as binary-encoded DER */
127 } PkiInfo_t;
128
129 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
130
131 /**
132  * Node structure for UUID linked list
133  */
134
135 typedef struct UuidInfo_s
136 {
137     char uuid[UUID_STRING_SIZE];
138     struct UuidInfo_s * next;
139 } UuidInfo_t;
140
141 /**
142  * Context with UUID linked list to populate
143  */
144
145 typedef struct
146 {
147     UuidInfo_t* list;
148 } UuidContext_t;
149
150 /**
151  * Populates UUID linked list in the context with all
152  * UUIDs retrieved from OCF Device /oic/sec/cred/ entries.
153  * This is done to match allowed UUIDs against presented
154  * UUID in the leaf certificate during TLS handshake
155  */
156
157 typedef void (*CAgetIdentityHandler)(UuidContext_t* list, unsigned char* p, size_t len);
158
159 /**
160  * Registers UUID population callback
161  */
162
163 CAResult_t CAregisterIdentityHandler(CAgetIdentityHandler getIdentityHandler);
164
165 /**
166  * Callback is used by application layer to check peer's certificate CN field.
167  * If set, this callback will be invoked during handshake after certificate verification.
168  *
169  * @param[out] cn     peer's certificate Common Name field.
170  *                    If common name was not found, cn will be set to NULL.
171  * @param[out] cnLen  peer's certificate Common Name field length.
172  *                    If CN was not found, cnLen will be set to 0.
173  *
174  * @return  CA_STATUS_OK or CA_STATUS_FAIL. In case CA_STATUS_FAIL is returned,
175  *          handshake will be dropped.
176  */
177 typedef CAResult_t (*PeerCNVerifyCallback)(const unsigned char *cn, size_t cnLen);
178
179 /**
180  * API to set callback that checks peer's certificate Common Name field
181  * @param[in] cb callback to utilize certificate Common Name field
182  */
183 void CAsetPeerCNVerifyCallback(PeerCNVerifyCallback cb);
184 #endif
185
186 /**
187  * Register callback to get types of TLS suites.
188  * @param[in]   getCredTypesHandler    Get types of TLS suites callback.
189  * @return  ::CA_STATUS_OK or appropriate error code.
190  */
191 CAResult_t CAregisterGetCredentialTypesHandler(CAgetCredentialTypesHandler getCredTypesHandler);
192
193 /**
194  * Register callback to receive the result of TLS handshake.
195  * @param[in] tlsHandshakeCallback callback for get tls handshake result
196  * @return ::CA_STATUS_OK
197  */
198 CAResult_t CAregisterSslHandshakeCallback(CAHandshakeErrorCallback tlsHandshakeCallback);
199
200 /**
201  * Register callback to get TLS PSK credentials.
202  * @param[in]   getTlsCredentials    GetDTLS Credetials callback.
203  * @return  ::CA_STATUS_OK
204  */
205 CAResult_t CAregisterPskCredentialsHandler(CAgetPskCredentialsHandler getTlsCredentials);
206
207 /**
208  * @brief   Callback function type for getting PKIX info
209  *
210  * @param   inf[out]   PKIX related info
211  *
212  * @return  NONE
213  */
214 typedef void (*CAgetPkixInfoHandler)(PkiInfo_t * inf);
215
216 /**
217  * Register callback to get PKIX related info.
218  * @param[in]   getPkixInfoHandler    Get PKIX related info callback.
219  * @return  ::CA_STATUS_OK or appropriate error code.
220  */
221 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
222
223 /**
224  * Select the cipher suite for dtls handshake.
225  *
226  * @param[in] cipher  cipher suite (Note : Make sure endianness).
227  *                        TLS_RSA_WITH_AES_256_CBC_SHA256          0x3D
228  *                        TLS_RSA_WITH_AES_128_GCM_SHA256          0x009C
229  *                        TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256  0xC02B
230  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8       0xC0AE
231  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM         0xC0AC
232  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256  0xC023
233  *                        TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384  0xC024
234  *                        TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384  0xC02C
235  *                        TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256    0xC037
236  *                        TLS_ECDH_anon_WITH_AES_128_CBC_SHA       0xC018
237  * @param[in] adapter  transport adapter (TCP/IP/BLE)
238  *
239  * @retval  ::CA_STATUS_OK    Successful.
240  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
241  * @retval  ::CA_STATUS_FAILED Operation failed.
242  */
243 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
244
245 /**
246  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
247  *
248  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
249  *
250  * @retval  ::CA_STATUS_OK    Successful.
251  * @retval  ::CA_STATUS_FAILED Operation failed.
252  *
253  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
254  */
255 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
256
257
258 /**
259  * Generate ownerPSK using PRF.
260  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
261  *                    'ID of new device(Resource Server)',
262  *                    'ID of owner smart-phone(Provisioning Server)')
263  *
264  * @param[in] endpoint  information of network address.
265  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
266  * @param[in] labelLen  Byte length of label.
267  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
268  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
269  * @param[in] provServerDeviceID  label of previous owner.
270  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
271  * @param[in,out] ownerPSK  Output buffer for owner PSK.
272  * @param[in] ownerPskSize  Byte length of the ownerPSK to be generated.
273  *
274  * @retval  ::CA_STATUS_OK    Successful.
275  * @retval  ::CA_STATUS_FAILED Operation failed.
276  */
277 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
278                               const uint8_t* label, const size_t labelLen,
279                               const uint8_t* rsrcServerDeviceID,
280                               const size_t rsrcServerDeviceIDLen,
281                               const uint8_t* provServerDeviceID,
282                               const size_t provServerDeviceIDLen,
283                               uint8_t* ownerPSK, const size_t ownerPskSize);
284
285 /**
286  * Initiate DTLS handshake with selected cipher suite.
287  *
288  * @param[in] endpoint  information of network address.
289  *
290  * @retval  ::CA_STATUS_OK    Successful.
291  * @retval  ::CA_STATUS_FAILED Operation failed.
292  */
293 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
294
295 /**
296  * Close the DTLS session.
297  *
298  * @param[in] endpoint  information of network address.
299  *
300  * @retval  ::CA_STATUS_OK    Successful.
301  * @retval  ::CA_STATUS_FAILED Operation failed.
302  */
303 CAResult_t CAcloseSslSession(const CAEndpoint_t *endpoint);
304
305 /**
306  * Initiate TLS handshake with selected cipher suite.
307  *
308  * @param[in] endpoint information of network address.
309  *
310  * @retval  ::CA_STATUS_OK    Successful.
311  * @retval  ::CA_STATUS_FAILED Operation failed.
312  */
313 CAResult_t CAinitiateSslHandshake(const CAEndpoint_t *endpoint);
314
315 /**
316  * Close the DTLS session.
317  *
318  * @param[in] endpoint  information of network address.
319  *
320  * @retval  ::CA_STATUS_OK    Successful.
321  * @retval  ::CA_STATUS_FAILED Operation failed.
322  */
323 CAResult_t CAcloseSslConnection(const CAEndpoint_t *endpoint);
324
325
326 /**
327  * Close All of DTLS sessions.
328  */
329 void CAcloseSslConnectionAll(CATransportAdapter_t transportType);
330
331 #ifdef __cplusplus
332 } /* extern "C" */
333 #endif
334
335
336 #endif /* CA_SECURITY_INTERFACE_H_ */