1 /* *****************************************************************
3 * Copyright 2015 Samsung Electronics All Rights Reserved.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 ******************************************************************/
24 * This file contains the Security APIs for Resource Model to use.
27 #ifndef CA_SECURITY_INTERFACE_H_
28 #define CA_SECURITY_INTERFACE_H_
32 #endif //__WITH_X509__
37 #include "byte_array.h"
46 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
48 * @enum CADtlsPskCredType_t
49 * Type of PSK credential required during DTLS handshake
50 * It does not make much sense in bringing in all definitions from dtls.h into here.
51 * Therefore, redefining them here.
58 } CADtlsPskCredType_t;
61 * This internal callback is used by CA layer to
62 * retrieve PSK credentials from SRM.
64 * @param[in] type type of PSK data required by CA layer during DTLS handshake set.
65 * @param[in] desc Additional request information.
66 * @param[in] desc_len The actual length of desc.
67 * @param[out] result Must be filled with the requested information.
68 * @param[in] result_length Maximum size of @p result.
70 * @return The number of bytes written to @p result or a value
71 * less than zero on error.
73 typedef int (*CAGetDTLSPskCredentialsHandler)(CADtlsPskCredType_t type,
74 const uint8_t *desc, size_t desc_len,
75 uint8_t *result, size_t result_length);
76 #endif // __WITH_DTLS__ or __WITH_TLS__
80 * Register callback to receive the result of DTLS handshake.
81 * @param[in] dtlsHandshakeCallback callback for get dtls handshake result
82 * @return ::CA_STATUS_OK
84 CAResult_t CARegisterDTLSHandshakeCallback(CAErrorCallback dtlsHandshakeCallback);
87 * Register callback to get DTLS PSK credentials.
88 * @param[in] GetDTLSCredentials GetDTLS Credetials callback.
89 * @return ::CA_STATUS_OK
91 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSPskCredentialsHandler GetDTLSCredentials);
93 #endif //__WITH_DTLS__
98 * Binary structure containing PKIX related info
99 * own certificate chain, public key, CA's and CRL's
103 // own certificate chain
114 * Register callback to receive the result of TLS handshake.
115 * @param[in] tlsHandshakeCallback callback for get tls handshake result
116 * @return ::CA_STATUS_OK
118 CAResult_t CAregisterTlsHandshakeCallback(CAErrorCallback tlsHandshakeCallback);
121 * Register callback to get TLS PSK credentials.
122 * @param[in] getTLSCredentials GetDTLS Credetials callback.
123 * @return ::CA_STATUS_OK
125 CAResult_t CAregisterTlsCredentialsHandler(CAGetDTLSPskCredentialsHandler getTlsCredentials);
128 * @brief Callback function type for getting PKIX info
130 * @param inf[out] PKIX related info
134 typedef void (*CAgetPkixInfoHandler)(PkiInfo_t * inf);
137 void GetPkixInfo(PkiInfo_t * inf);
138 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
139 #endif //__WITH_TLS__
143 * Binary structure containing certificate chain and certificate credentials
148 // certificate message for DTLS
149 unsigned char certificateChain[MAX_CERT_MESSAGE_LEN];
150 // length of the certificate message
151 uint32_t certificateChainLen;
152 // number of certificates in certificate message
154 // x component of EC public key
155 uint8_t rootPublicKeyX[PUBLIC_KEY_SIZE / 2];
156 // y component of EC public key
157 uint8_t rootPublicKeyY[PUBLIC_KEY_SIZE / 2];
159 uint8_t devicePrivateKey[PRIVATE_KEY_SIZE];
164 * @brief Callback function type for getting certificate credentials.
165 * @param credInfo [OUT] Certificate credentials info. Handler has to allocate new memory for
166 * credInfo which is then freed by CA
169 typedef int (*CAGetDTLSX509CredentialsHandler)(CADtlsX509Creds_t *credInfo);
171 * @brief Callback function type for getting CRL.
172 * @param crlInfo [OUT] Certificate credentials info. Handler has to allocate new memory for
173 * credInfo which is then freed by CA
176 typedef void (*CAGetDTLSCrlHandler)(ByteArray* crlInfo);
179 * @brief Register callback to get DTLS Cert credentials.
180 * @param GetCertCredentials [IN] GetCert Credetials callback
181 * @return #CA_STATUS_OK
183 CAResult_t CARegisterDTLSX509CredentialsHandler(CAGetDTLSX509CredentialsHandler GetX509Credentials);
185 * @brief Register callback to get CRL.
186 * @param GetCrl [IN] GetCrl callback
187 * @return #CA_STATUS_OK
189 CAResult_t CARegisterDTLSCrlHandler(CAGetDTLSCrlHandler GetCrl);
190 #endif //__WITH_X509__
196 * Select the cipher suite for dtls handshake.
198 * @param[in] cipher cipher suite (Note : Make sure endianness).
199 * 0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
200 * 0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
201 * 0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
203 * @retval ::CA_STATUS_OK Successful.
204 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
205 * @retval ::CA_STATUS_FAILED Operation failed.
207 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
210 * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
212 * @param[in] enable TRUE/FALSE enables/disables anonymous cipher suite.
214 * @retval ::CA_STATUS_OK Successful.
215 * @retval ::CA_STATUS_FAILED Operation failed.
217 * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
219 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
223 * Generate ownerPSK using PRF.
224 * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
225 * 'ID of new device(Resource Server)',
226 * 'ID of owner smart-phone(Provisioning Server)')
228 * @param[in] endpoint information of network address.
229 * @param[in] label Ownership transfer method e.g)"oic.sec.doxm.jw".
230 * @param[in] labelLen Byte length of label.
231 * @param[in] rsrcServerDeviceID ID of new device(Resource Server).
232 * @param[in] rsrcServerDeviceIDLen Byte length of rsrcServerDeviceID.
233 * @param[in] provServerDeviceID label of previous owner.
234 * @param[in] provServerDeviceIDLen byte length of provServerDeviceID.
235 * @param[in,out] ownerPSK Output buffer for owner PSK.
236 * @param[in] ownerPSKSize Byte length of the ownerPSK to be generated.
238 * @retval ::CA_STATUS_OK Successful.
239 * @retval ::CA_STATUS_FAILED Operation failed.
241 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
242 const uint8_t* label, const size_t labelLen,
243 const uint8_t* rsrcServerDeviceID,
244 const size_t rsrcServerDeviceIDLen,
245 const uint8_t* provServerDeviceID,
246 const size_t provServerDeviceIDLen,
247 uint8_t* ownerPSK, const size_t ownerPSKSize);
250 * Initiate DTLS handshake with selected cipher suite.
252 * @param[in] endpoint information of network address.
254 * @retval ::CA_STATUS_OK Successful.
255 * @retval ::CA_STATUS_FAILED Operation failed.
257 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
260 * Close the DTLS session.
262 * @param[in] endpoint information of network address.
264 * @retval ::CA_STATUS_OK Successful.
265 * @retval ::CA_STATUS_FAILED Operation failed.
267 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
269 #endif /* __WITH_DTLS__ */
274 * Initiate TLS handshake with selected cipher suite.
276 * @param[in] endpoint information of network address.
278 * @retval ::CA_STATUS_OK Successful.
279 * @retval ::CA_STATUS_FAILED Operation failed.
281 CAResult_t CAinitiateTlsHandshake(const CAEndpoint_t *endpoint);
284 * Close the DTLS session.
286 * @param[in] endpoint information of network address.
288 * @retval ::CA_STATUS_OK Successful.
289 * @retval ::CA_STATUS_FAILED Operation failed.
291 CAResult_t CAcloseTlsConnection(const CAEndpoint_t *endpoint);
293 #endif /* __WITH_TLS__ */
300 #endif /* CA_SECURITY_INTERFACE_H_ */