pal_plat_TLS.h

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     PAL_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256,
00052     PAL_TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256
00053 }palTLSSuites_t;
00054 
00055 typedef void* palTLSSocketHandle_t;
00056 typedef void* palTimerCtx_t;
00057 
00058 //! This prototype can be re-defined by the platform side.
00059 //! Consider moving them to separate header.
00060 typedef int (*palBIOSend_f)(palTLSSocketHandle_t socket, const unsigned char *buf, size_t len);
00061 typedef int (*palBIORecv_f)(palTLSSocketHandle_t socket, unsigned char *buf, size_t len);
00062 typedef int (*palVerifyCallback_f)(void *, void *, int, uint32_t *);
00063 typedef void (*palSetTimer_f)( void *data, uint32_t intMs, uint32_t finMs ); 
00064 typedef int (*palGetTimer_f)(void* data);
00065 typedef void (*palLogFunc_f)(void *context, int debugLevel, const char *fileName, int line, const char *message);
00066 
00067 
00068 /*! Initiate the TLS library. This API is not required for each TLS library.
00069 *   For example for mbed TLS, it will be an empty function.
00070 *
00071 \note You must call this function in the general PAL initializtion function.
00072 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00073 */
00074 palStatus_t pal_plat_initTLSLibrary (void);
00075 
00076 /*! Free resources for the TLS library.
00077 *
00078 \note You must call this function in the general PAL cleanup function.
00079 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00080 */
00081 palStatus_t pal_plat_cleanupTLS (void);
00082 
00083 /*! Initiate new configuration context.
00084 *
00085 * @param[out] palTLSConf: The TLS configuration context.
00086 * @param[in] tranportVersion: The `palTLSTransportMode_t` type deciding the transportation version (for example tlsv1.2).
00087 * @param[in] methodType: The `palDTLSSide_t` type deciding the endpoint type (server or client).
00088 *
00089 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00090 */
00091 palStatus_t pal_plat_initTLSConf (palTLSConfHandle_t* confCtx, palTLSTransportMode_t transportVersion, palDTLSSide_t methodType);
00092 
00093 /*! Destroy and release resources for the TLS configuration context.
00094 *
00095 * @param[inout] palTLSConf: The TLS configuration context to free.
00096 *
00097 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00098 */
00099 palStatus_t pal_plat_tlsConfigurationFree (palTLSConfHandle_t* palTLSConf);
00100 
00101 /*! Initiate a new TLS context.
00102 *
00103 * @param[in] palTLSConf: The TLS configuration context.
00104 * @param[out] palTLSHandle: The index to the TLS context.
00105 *
00106 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00107 */
00108 palStatus_t pal_plat_initTLS (palTLSConfHandle_t palTLSConf, palTLSHandle_t* palTLSHandle);
00109 
00110 /*! Destroy and release resources for the TLS context.
00111 *
00112 * @param[inout] ssl: The TLS context to free.
00113 *
00114 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00115 */
00116 palStatus_t pal_plat_freeTLS (palTLSHandle_t* palTLSHandle);
00117 
00118 /*! Add an entropy source to the TLS/DTLS library (this API may NOT be available in all TLS/DTLS platforms, see the note).
00119 *
00120 * @param[in] entropyCallback: The entropy callback to be used in the TLS/DTLS handshake.
00121 *
00122 \note This function is available ONLY when the TLS/DTLS platform supports this functionality. In other platforms,
00123       PAL_ERR_NOT_SUPPORTED should be returned.
00124 \return PAL_SUCCESS on success. A negative value indicating a specific error code or PAL_ERR_NOT_SUPPORTED in case of failure.
00125 */
00126 palStatus_t pal_plat_addEntropySource (palEntropySource_f entropyCallback);
00127 
00128 /*! Set the supported cipher suites to the configuration context.
00129 *
00130 * @param[in] palTLSConf: The TLS configuration context.
00131 * @param[in] palSuites: The supported cipher suites to be added.
00132 *
00133 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00134 */
00135 palStatus_t pal_plat_setCipherSuites (palTLSConfHandle_t sslConf, palTLSSuites_t palSuite);
00136 
00137 /*!  Return the result of the certificate verification. The handshake API calls this.
00138 *
00139 * @param[in] ssl: The TLS context.
00140 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is 
00141 *                           relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00142 *
00143 \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`
00144 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00145 */
00146 palStatus_t pal_plat_sslGetVerifyResultExtended (palTLSHandle_t palTLSHandle, int32_t* verifyResult);
00147 
00148 /*!  Read at most 'len' application data bytes.
00149 *
00150 * @param[in] ssl: The TLS context.
00151 * @param[out] buffer: A buffer holding the data.
00152 * @param[in] len: The maximum number of bytes to read.
00153 * @param[out] actualLen: The actual number of bytes read.
00154 *
00155 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00156 */
00157 palStatus_t pal_plat_sslRead (palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen);
00158 
00159 /*! Try to write exactly 'len' application data bytes.
00160 *
00161 * @param[in] ssl: The TLS context.
00162 * @param[in] buffer: A buffer holding the data.
00163 * @param[in] len: The number of bytes to be written.
00164 * @param[out] bytesWritten: The number of bytes actually written.
00165 *
00166 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00167 */
00168 palStatus_t pal_plat_sslWrite (palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten);
00169 
00170 /*! Set the retransmit timeout values for the DTLS handshake.
00171 *   (DTLS only, no effect on TLS.)
00172 *
00173 * @param[in] palTLSConf: The TLS configuration context.
00174 * @param[in] timeoutInMilliSec: The maximum timeout value in milliseconds.
00175 *
00176 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00177 */
00178 palStatus_t pal_plat_setHandShakeTimeOut (palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec);
00179 
00180 /*! Set up a TLS context for use.
00181 *
00182 * @param[in/out] ssl: The TLS context.
00183 * @param[in] palTLSConf: The TLS configuration context.
00184 *
00185 \return The function returns `palTLSHandle_t`, the index to the TLS context.
00186 */
00187 palStatus_t pal_plat_sslSetup (palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf);
00188 
00189 /*! Perform the TLS handshake.
00190 *
00191 * @param[in] ssl: The TLS context.
00192 * @param[out] serverTime: The server time recieved in the server hello message during handshake.
00193 *
00194 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00195 */
00196 palStatus_t pal_plat_handShake (palTLSHandle_t palTLSHandle, uint64_t* serverTime);
00197 
00198 #if PAL_USE_SECURE_TIME
00199 /*! Perform the TLS handshake renegotiation.
00200 *
00201 * @param[in] ssl: The TLS context.
00202 * @param[in] serverTime: The server time used to update the TLS time during handshake renegotiate.
00203 *
00204 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00205 */
00206 palStatus_t pal_plat_renegotiate (palTLSHandle_t palTLSHandle, uint64_t sreverTime);
00207 #endif //PAL_USE_SECURE_TIME
00208 
00209 /*! Set the socket for the TLS configuration context.
00210 *
00211 * @param[in] palTLSConf: The TLS configuration context.
00212 * @param[in] socket: The socket for the TLS context.
00213 *
00214 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00215 */
00216 palStatus_t pal_plat_tlsSetSocket (palTLSConfHandle_t palTLSConf, palTLSSocket_t* socket);
00217 
00218 /*! Set your own certificate chain and private key.
00219 *
00220 * @param[in] palTLSConf: The TLS configuration context.
00221 * @param[in] ownCert: Your own public certificate chain.
00222 * @param[in] privateKey: Your own private key.
00223 *
00224 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00225 */
00226 palStatus_t pal_plat_setOwnCertAndPrivateKey (palTLSConfHandle_t palTLSConf, palX509_t* ownCert, palPrivateKey_t* privateKey);
00227 
00228 /*! Set your own certificate chain.
00229 *
00230 * @param[in] palTLSConf: The TLS configuration context.
00231 * @param[in] ownCert: Your own public certificate chain.
00232 *
00233 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00234 */
00235 palStatus_t pal_plat_setOwnCertChain (palTLSConfHandle_t palTLSConf, palX509_t* ownCert);
00236 
00237 /*! Set your own private key.
00238 *
00239 * @param[in] palTLSConf: The TLS configuration context.
00240 * @param[in] privateKey: Your own private key.
00241 *
00242 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00243 */
00244 palStatus_t pal_plat_setOwnPrivateKey (palTLSConfHandle_t palTLSConf, palPrivateKey_t* privateKey);
00245 
00246 /*! Set the data required to verify a peer certificate.
00247 *
00248 * @param[in] palTLSConf: The TLS configuration context.
00249 * @param[in] caChain: The trusted CA chain.
00250 * @param[in] caCRL: The trusted CA CRLs.
00251 *
00252 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00253 */
00254 palStatus_t pal_plat_setCAChain (palTLSConfHandle_t palTLSConf, palX509_t* caChain, palX509CRL_t* caCRL);
00255 
00256 /*! Set the Pre-Shared Key (PSK) and the expected identity name.
00257 *
00258 * @param[in] sslConf: The TLS configuration context.
00259 * @param[in] identity: A pointer to the pre-shared key identity.
00260 * @param[in] maxIdentityLenInBytes: The maximum length of the identity key.
00261 * @param[in] psk: A pointer to the pre-shared key.
00262 * @param[in] maxPskLenInBytes: The maximum length of the pre-shared key.
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_setPSK (palTLSConfHandle_t sslConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes);
00267 
00268 
00269 /*! Set the certificate verification mode.
00270 *
00271 * @param[in] sslConf: The TLS configuration context.
00272 * @param[in] authMode: The authentication mode.
00273 *
00274 \note In some platforms, a verification callback MAY be needed. In this case, it must be provided by the porting side.
00275 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00276 */
00277 palStatus_t pal_plat_setAuthenticationMode (palTLSConfHandle_t sslConf, palTLSAuthMode_t authMode);
00278 
00279 
00280 /*! Turn on/off the TLS library debugging for the given configuration handle. The logs are sent via the mbedTrace.
00281 *   In case of release mode, an error will be returned.
00282 *
00283 * @param[in] palTLSConf : the TLS confuguraiton to modify
00284 * @param[in] turnOn: if greater than 0 turn on debugging, otherwise turn it off
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_sslSetDebugging (palTLSConfHandle_t palTLSConf, uint8_t turnOn);
00289 
00290 /*! Set the IO callbacks for the TLS context. 
00291 *
00292 * @param[in] palTLSConf: The TLS configuration context.
00293 * @param[in] palIOCtx: The shared context by BIO callbacks.
00294 * @param[in] palBIOSend: A pointer to send BIO function.
00295 * @param[in] palBIORecv: A pointer to receive BIO function.
00296 *
00297 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00298 */
00299 palStatus_t pal_plat_sslSetIOCallBacks (palTLSConfHandle_t palTLSConf, palTLSSocket_t* palIOCtx, palBIOSend_f palBIOSend, palBIORecv_f palBIORecv);
00300 
00301 /*! Set the timer callbacks.
00302 *
00303 * @param[in] palTLSHandle: The TLS context.
00304 * @param[in] timerCtx: The shared context by BIO callbacks.
00305 * @param[in] setTimer: The set timer callback.
00306 * @param[in] getTimer: The get timer callback.
00307 *
00308 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00309 */
00310 palStatus_t pal_plat_setTimeCB (palTLSHandle_t* palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer);
00311 
00312 /*! Set the logging function.
00313 *
00314 * @param[in] palTLSConf: The TLS configuration context.
00315 * @param[in] palLogFunction: A pointer to the logging function.
00316 * @param[in] logContext: The context for the logging function.
00317 *
00318 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00319 */
00320 palStatus_t pal_plat_SetLoggingCb (palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext);
00321 
00322 #endif //_PAL_PLAT_TLS_H_