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