Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
pal_plat_TLS.h
Go to the documentation of this file.
00001 /******************************************************************************* 00002 * Copyright 2016, 2017 ARM Ltd. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 *******************************************************************************/ 00016 00017 #ifndef _PAL_PLAT_TLS_H_ 00018 #define _PAL_PLAT_TLS_H_ 00019 #include "pal_TLS.h" 00020 00021 /*! \file pal_plat_TLS.h 00022 * \brief PAL TLS/DTLS - platform. 00023 * This file contains TLS/DTLS APIs that need to be implemented in the platform layer. 00024 */ 00025 00026 /***************************************************/ 00027 /**** PAL DTLS internal data structures ************/ 00028 /***************************************************/ 00029 typedef enum palDTLSSide{ 00030 #ifdef PAL_TLS_SUPPORT_SERVER_MODE 00031 PAL_TLS_IS_SERVER, 00032 #endif // PAL_TLS_SUPPORT_SERVER_MODE 00033 PAL_TLS_IS_CLIENT 00034 } palDTLSSide_t; 00035 00036 typedef enum palTLSAuthMode { 00037 PAL_TLS_VERIFY_NONE, //! Server mode: The peer certificate is not verified. For client mode, this is insecure! 00038 PAL_TLS_VERIFY_OPTIONAL, //! The peer certificate verification can be failed and handshake continues. 00039 PAL_TLS_VERIFY_REQUIRED //! The peer certificate verification MUST pass. 00040 }palTLSAuthMode_t; 00041 00042 //! This is the list of the available cipher suites, this code MUST be 00043 //! defined in the `pal_plat_TLS.c` with the proper values for the SSL platform: 00044 typedef enum palTLSSuites{ 00045 PAL_TLS_PSK_WITH_AES_128_CBC_SHA256, 00046 PAL_TLS_PSK_WITH_AES_128_CCM_8, 00047 PAL_TLS_PSK_WITH_AES_256_CCM_8, 00048 PAL_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8, 00049 PAL_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, 00050 PAL_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 00051 }palTLSSuites_t; 00052 00053 typedef void* palTLSSocketHandle_t; 00054 typedef void* palTimerCtx_t; 00055 00056 //! This prototype can be re-defined by the platform side. 00057 //! Consider moving them to separate header. 00058 typedef int (*palBIOSend_f)(palTLSSocketHandle_t socket, const unsigned char *buf, size_t len); 00059 typedef int (*palBIORecv_f)(palTLSSocketHandle_t socket, unsigned char *buf, size_t len); 00060 typedef int (*palVerifyCallback_f)(void *, void *, int, uint32_t *); 00061 typedef void (*palSetTimer_f)( void *data, uint32_t intMs, uint32_t finMs ); 00062 typedef int (*palGetTimer_f)(void* data); 00063 typedef void (*palLogFunc_f)(void *context, int debugLevel, const char *fileName, int line, const char *message); 00064 00065 00066 /*! Initiate the TLS library. This API is not required for each TLS library. 00067 * For example for mbed TLS, it will be an empty function. 00068 * 00069 \note You must call this function in the general PAL initializtion function. 00070 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00071 */ 00072 palStatus_t pal_plat_initTLSLibrary (void); 00073 00074 /*! Free resources for the TLS library. 00075 * 00076 \note You must call this function in the general PAL cleanup function. 00077 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00078 */ 00079 palStatus_t pal_plat_cleanupTLS (void); 00080 00081 /*! Initiate new configuration context. 00082 * 00083 * @param[out] palTLSConf: The TLS configuration context. 00084 * @param[in] tranportVersion: The `palTLSTransportMode_t` type deciding the transportation version (for example tlsv1.2). 00085 * @param[in] methodType: The `palDTLSSide_t` type deciding the endpoint type (server or client). 00086 * 00087 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00088 */ 00089 palStatus_t pal_plat_initTLSConf (palTLSConfHandle_t* confCtx, palTLSTransportMode_t transportVersion, palDTLSSide_t methodType); 00090 00091 /*! Destroy and release resources for the TLS configuration context. 00092 * 00093 * @param[inout] palTLSConf: The TLS configuration context to free. 00094 * 00095 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00096 */ 00097 palStatus_t pal_plat_tlsConfigurationFree (palTLSConfHandle_t* palTLSConf); 00098 00099 /*! Initiate a new TLS context. 00100 * 00101 * @param[in] palTLSConf: The TLS configuration context. 00102 * @param[out] palTLSHandle: The index to the TLS context. 00103 * 00104 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00105 */ 00106 palStatus_t pal_plat_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t* palTLSHandle); 00107 00108 /*! Destroy and release resources for the TLS context. 00109 * 00110 * @param[inout] ssl: The TLS context to free. 00111 * 00112 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00113 */ 00114 palStatus_t pal_plat_freeTLS (palTLSHandle_t* palTLSHandle); 00115 00116 /*! Add an entropy source to the TLS/DTLS library (this API may NOT be available in all TLS/DTLS platforms, see the note). 00117 * 00118 * @param[in] entropyCallback: The entropy callback to be used in the TLS/DTLS handshake. 00119 * 00120 \note This function is available ONLY when the TLS/DTLS platform supports this functionality. In other platforms, 00121 PAL_ERR_NOT_SUPPORTED should be returned. 00122 \return PAL_SUCCESS on success. A negative value indicating a specific error code or PAL_ERR_NOT_SUPPORTED in case of failure. 00123 */ 00124 palStatus_t pal_plat_addEntropySource (palEntropySource_f entropyCallback); 00125 00126 /*! Set the supported cipher suites to the configuration context. 00127 * 00128 * @param[in] palTLSConf: The TLS configuration context. 00129 * @param[in] palSuites: The supported cipher suites to be added. 00130 * 00131 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00132 */ 00133 palStatus_t pal_plat_setCipherSuites (palTLSConfHandle_t sslConf, palTLSSuites_t palSuite); 00134 00135 /*! Return the result of the certificate verification. The handshake API calls this. 00136 * 00137 * @param[in] ssl: The TLS context. 00138 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is 00139 * relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`. 00140 * 00141 \note In case platform doesn't support multipule errors for certificate verification, please return `PAL_ERR_X509_CERT_VERIFY_FAILED` and the reason should be specified in the `verifyResult` 00142 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00143 */ 00144 palStatus_t pal_plat_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t* verifyResult); 00145 00146 /*! Read at most 'len' application data bytes. 00147 * 00148 * @param[in] ssl: The TLS context. 00149 * @param[out] buffer: A buffer holding the data. 00150 * @param[in] len: The maximum number of bytes to read. 00151 * @param[out] actualLen: The actual number of bytes read. 00152 * 00153 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00154 */ 00155 palStatus_t pal_plat_sslRead (palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen); 00156 00157 /*! Try to write exactly 'len' application data bytes. 00158 * 00159 * @param[in] ssl: The TLS context. 00160 * @param[in] buffer: A buffer holding the data. 00161 * @param[in] len: The number of bytes to be written. 00162 * @param[out] bytesWritten: The number of bytes actually written. 00163 * 00164 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00165 */ 00166 palStatus_t pal_plat_sslWrite (palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten); 00167 00168 /*! Set the retransmit timeout values for the DTLS handshake. 00169 * (DTLS only, no effect on TLS.) 00170 * 00171 * @param[in] palTLSConf: The TLS configuration context. 00172 * @param[in] timeoutInMilliSec: The maximum timeout value in milliseconds. 00173 * 00174 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00175 */ 00176 palStatus_t pal_plat_setHandShakeTimeOut (palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec); 00177 00178 /*! Set up a TLS context for use. 00179 * 00180 * @param[in/out] ssl: The TLS context. 00181 * @param[in] palTLSConf: The TLS configuration context. 00182 * 00183 \return The function returns `palTLSHandle_t`, the index to the TLS context. 00184 */ 00185 palStatus_t pal_plat_sslSetup (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf); 00186 00187 /*! Perform the TLS handshake. 00188 * 00189 * @param[in] ssl: The TLS context. 00190 * @param[out] serverTime: The server time recieved in the server hello message during handshake. 00191 * 00192 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00193 */ 00194 palStatus_t pal_plat_handShake (palTLSHandle_t palTLSHandle, uint64_t* serverTime); 00195 00196 #if PAL_USE_SECURE_TIME 00197 /*! Perform the TLS handshake renegotiation. 00198 * 00199 * @param[in] ssl: The TLS context. 00200 * @param[in] serverTime: The server time used to update the TLS time during handshake renegotiate. 00201 * 00202 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00203 */ 00204 palStatus_t pal_plat_renegotiate (palTLSHandle_t palTLSHandle, uint64_t sreverTime); 00205 #endif //PAL_USE_SECURE_TIME 00206 00207 /*! Set the socket for the TLS configuration context. 00208 * 00209 * @param[in] palTLSConf: The TLS configuration context. 00210 * @param[in] socket: The socket for the TLS context. 00211 * 00212 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00213 */ 00214 palStatus_t pal_plat_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t* socket); 00215 00216 /*! Set your own certificate chain and private key. 00217 * 00218 * @param[in] palTLSConf: The TLS configuration context. 00219 * @param[in] ownCert: Your own public certificate chain. 00220 * @param[in] privateKey: Your own private key. 00221 * 00222 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00223 */ 00224 palStatus_t pal_plat_setOwnCertAndPrivateKey (palTLSConfHandle_t palTLSConf, palX509_t* ownCert, palPrivateKey_t* privateKey); 00225 00226 /*! Set the data required to verify a peer certificate. 00227 * 00228 * @param[in] palTLSConf: The TLS configuration context. 00229 * @param[in] caChain: The trusted CA chain. 00230 * @param[in] caCRL: The trusted CA CRLs. 00231 * 00232 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00233 */ 00234 palStatus_t pal_plat_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t* caChain, palX509CRL_t* caCRL); 00235 00236 /*! Set the Pre-Shared Key (PSK) and the expected identity name. 00237 * 00238 * @param[in] sslConf: The TLS configuration context. 00239 * @param[in] identity: A pointer to the pre-shared key identity. 00240 * @param[in] maxIdentityLenInBytes: The maximum length of the identity key. 00241 * @param[in] psk: A pointer to the pre-shared key. 00242 * @param[in] maxPskLenInBytes: The maximum length of the pre-shared key. 00243 * 00244 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00245 */ 00246 palStatus_t pal_plat_setPSK (palTLSConfHandle_t sslConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes); 00247 00248 00249 /*! Set the certificate verification mode. 00250 * 00251 * @param[in] sslConf: The TLS configuration context. 00252 * @param[in] authMode: The authentication mode. 00253 * 00254 \note In some platforms, a verification callback MAY be needed. In this case, it must be provided by the porting side. 00255 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00256 */ 00257 palStatus_t pal_plat_setAuthenticationMode (palTLSConfHandle_t sslConf, palTLSAuthMode_t authMode); 00258 00259 /*! Turn on or off debugging from the TLS library. If the debugging is on, the logs will be sent via the PAL Logger (mbedTrace?!). 00260 * In release mode, an error will be returned. 00261 * 00262 * @param[in] turnOn: Sets the status of the debugging prints. 00263 * 00264 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00265 */ 00266 palStatus_t pal_plat_sslDebugging (uint8_t turnOn); 00267 00268 /*! Set the IO callbacks for the TLS context. 00269 * 00270 * @param[in] palTLSConf: The TLS configuration context. 00271 * @param[in] palIOCtx: The shared context by BIO callbacks. 00272 * @param[in] palBIOSend: A pointer to send BIO function. 00273 * @param[in] palBIORecv: A pointer to receive BIO function. 00274 * 00275 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00276 */ 00277 palStatus_t pal_plat_sslSetIOCallBacks (palTLSConfHandle_t palTLSConf, palTLSSocket_t* palIOCtx, palBIOSend_f palBIOSend, palBIORecv_f palBIORecv); 00278 00279 /*! Set the timer callbacks. 00280 * 00281 * @param[in] palTLSHandle: The TLS context. 00282 * @param[in] timerCtx: The shared context by BIO callbacks. 00283 * @param[in] setTimer: The set timer callback. 00284 * @param[in] getTimer: The get timer callback. 00285 * 00286 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00287 */ 00288 palStatus_t pal_plat_setTimeCB (palTLSHandle_t* palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer); 00289 00290 /*! Set the logging function. 00291 * 00292 * @param[in] palTLSConf: The TLS configuration context. 00293 * @param[in] palLogFunction: A pointer to the logging function. 00294 * @param[in] logContext: The context for the logging function. 00295 * 00296 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00297 */ 00298 palStatus_t pal_plat_SetLoggingCb (palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext); 00299 00300 #endif //_PAL_PLAT_TLS_H_
Generated on Tue Jul 12 2022 19:01:36 by 1.7.2