pal_TLS.h

00001 // ----------------------------------------------------------------------------
00002 // Copyright 2016-2019 ARM Ltd.
00003 //
00004 // SPDX-License-Identifier: Apache-2.0
00005 //
00006 // Licensed under the Apache License, Version 2.0 (the "License");
00007 // you may not use this file except in compliance with the License.
00008 // You may obtain a copy of the License at
00009 //
00010 //     http://www.apache.org/licenses/LICENSE-2.0
00011 //
00012 // Unless required by applicable law or agreed to in writing, software
00013 // distributed under the License is distributed on an "AS IS" BASIS,
00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00015 // See the License for the specific language governing permissions and
00016 // limitations under the License.
00017 // ----------------------------------------------------------------------------
00018 
00019 #ifndef _PAL_DTLS_H_
00020 #define _PAL_DTLS_H_
00021 
00022 #ifndef _PAL_H
00023     #error "Please do not include this file directly, use pal.h instead"
00024 #endif
00025 
00026 /*! \file pal_TLS.h
00027 *  \brief PAL TLS/DTLS.
00028 *   This file contains TLS and DTLS APIs and is a part of the PAL service API.
00029 *
00030 *   It provides Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) handshake functionalities, allowing read and write from peers in a secure way.
00031 */
00032 
00033 /***************************************************/
00034 /**** PAL DTLS data structures *********************/
00035 /***************************************************/
00036 
00037 // Index in the static array of the TLSs.
00038 typedef uintptr_t palTLSHandle_t;
00039 typedef uintptr_t palTLSConfHandle_t;
00040 
00041 typedef enum palTLSTranportMode{
00042 #ifdef PAL_NET_TCP_AND_TLS_SUPPORT
00043     PAL_TLS_MODE, //(STREAM)
00044 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
00045     PAL_DTLS_MODE //(DATAGRAM)
00046 }palTLSTransportMode_t;
00047 
00048 typedef struct palTLSSocket{
00049     palSocket_t socket;
00050     palSocketAddress_t* socketAddress;
00051     palSocketLength_t addressLength;
00052     palTLSTransportMode_t transportationMode;
00053 }palTLSSocket_t;
00054 
00055 
00056 typedef struct palTLSBuffer{
00057     const void* buffer;
00058     uint32_t size;
00059 }palTLSBuffer_t;
00060 
00061 typedef palTLSBuffer_t palX509_t;
00062 typedef palTLSBuffer_t palX509CRL_t;
00063 typedef palTLSBuffer_t palPrivateKey_t;
00064 
00065 /*! \brief This callback is useful ONLY when mbed TLS is used as TLS platform library.
00066  *
00067  * In other platforms, you should NOT use this callback in the code.
00068  * The related function is not supported in other platforms than mbedTLS.
00069  */
00070 typedef int(*palEntropySource_f)(void *data, unsigned char *output, size_t len, size_t *olen);
00071 
00072 /***************************************************/
00073 /**** PAL DTLS Client APIs *************************/
00074 /***************************************************/
00075 
00076 /*! \brief Initiate the TLS library.
00077  *
00078  * \note You must call this function in the general PAL initializtion function.
00079  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00080  */
00081 palStatus_t pal_initTLSLibrary(void);
00082 
00083 /*! \brief Free resources for the TLS library.
00084  *
00085  * \note You must call this function in the general PAL cleanup function.
00086  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00087  */
00088 palStatus_t pal_cleanupTLS(void);
00089 
00090 /*! \brief Initiate a new TLS context.
00091  *
00092  * @param[in] palTLSConf: The TLS configuration context.
00093  * @param[out] palTLSHandle: The index to the TLS context.
00094  *
00095  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00096  */
00097 palStatus_t pal_initTLS(palTLSConfHandle_t palTLSConf, palTLSHandle_t* palTLSHandle);
00098 
00099 /*! \brief Destroy and free the resources of the TLS context.
00100  *
00101  * @param[in] palTLSHandle: The index to the TLS context.
00102  *
00103  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00104  */
00105 palStatus_t pal_freeTLS(palTLSHandle_t* palTLSHandle);
00106 
00107 /*! \brief Add an entropy source to the TLS/DTLS library. NOT available in all TLS/DTLS platforms, see note.
00108  *
00109  * @param[in] entropyCallback: The entropy callback to be used in the TLS or DTLS handshake.
00110  *
00111  * \note This function is available ONLY when the TLS or DTLS platform supports this functionality. In other platforms,
00112  *      PAL_ERR_NOT_SUPPORTED should be returned.
00113  * \note This function MUST be called (if needed) before calling the `pal_initTLSConfiguration()` function.
00114  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure, or PAL_ERR_NOT_SUPPORTED.
00115  */
00116 palStatus_t pal_addEntropySource(palEntropySource_f entropyCallback);
00117 
00118 /*! \brief Initiate a new configuration context.
00119 *
00120 * @param[out] palTLSConf: The context that holds the TLS configuration.
00121 * @param[in] transportationMode: The connection type: TLS or DTLS. See `palTranportVersion_t`.
00122 *
00123 * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00124 */
00125 palStatus_t pal_initTLSConfiguration(palTLSConfHandle_t* palTLSConf, palTLSTransportMode_t transportationMode);
00126 
00127 /*! \brief Destroy and free the resources of the TLS configurtion context.
00128  *
00129  * @param[in] palTLSConf: The TLS configuration context to free.
00130  *
00131  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00132  */
00133 palStatus_t pal_tlsConfigurationFree(palTLSConfHandle_t* palTLSConf);
00134 
00135 /*! \brief Set your own certificate chain and private key.
00136  *
00137  * @deprecated This function has been split into two separate functions, `pal_setOwnCertChain()` and `pal_setOwnPrivateKey()`.
00138  * @param[in] palTLSConf: The TLS configuration context.
00139  * @param[in] ownCert: Your own public certificate chain.
00140  * @param[in] privateKey: Your own private key.
00141  *
00142  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00143  */
00144 palStatus_t pal_setOwnCertAndPrivateKey(palTLSConfHandle_t palTLSConf, palX509_t* ownCert, palPrivateKey_t* privateKey);
00145 
00146 /*! \brief Set your own certificate chain.
00147  *
00148  * @param[in] palTLSConf: The TLS configuration context.
00149  * @param[in] ownCert: Your own public certificate chain.
00150  *
00151  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00152  */
00153 palStatus_t pal_setOwnCertChain(palTLSConfHandle_t palTLSConf, palX509_t* ownCert);
00154 
00155 /*! \brief Set your own private key.
00156  *
00157  * @param[in] palTLSConf: The TLS configuration context.
00158  * @param[in] privateKey: Your own private key.
00159  *
00160  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00161  */
00162 palStatus_t pal_setOwnPrivateKey(palTLSConfHandle_t palTLSConf, palPrivateKey_t* privateKey);
00163 
00164 /*! \brief Set the data required to verify the peer certificate.
00165  *
00166  * @param[in] palTLSConf: The TLS configuration context.
00167  * @param[in] caChain: The trusted CA chain.
00168  * @param[in] caCRL: The trusted CA CRLs.
00169  *
00170  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00171  */
00172 palStatus_t pal_setCAChain(palTLSConfHandle_t palTLSConf, palX509_t* caChain, palX509CRL_t* caCRL);
00173 
00174 /*! \brief Set the Pre-Shared Key (PSK) and the expected identity name.
00175  *
00176  * @param[in] palTLSConf: The TLS configuration context.
00177  * @param[in] identity: A pointer to the pre-shared key identity.
00178  * @param[in] maxIdentityLenInBytes: The length of the key identity.
00179  * @param[in] psk: A pointer to the pre-shared key.
00180  * @param[in] maxPskLenInBytes: The length of the pre-shared key.
00181  *
00182  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00183  */
00184 palStatus_t pal_setPSK(palTLSConfHandle_t palTLSConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes);
00185 
00186 /*! \brief Set the socket used by the TLS configuration context.
00187  *
00188  * @param[in] palTLSConf: The TLS configuration context.
00189  * @param[in] socket: The socket to be used by the TLS context.
00190  *
00191  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00192  */
00193 palStatus_t pal_tlsSetSocket(palTLSConfHandle_t palTLSConf, palTLSSocket_t* socket);
00194 
00195 /*! \brief Perform the TLS handshake. This function is blocking.
00196  *
00197  * This function sets the TLS configuration context into the TLS context and performs the handshake
00198  * with the peer.
00199  * @param[in] palTLSHandle: The TLS context.
00200  * @param[in] palTLSConf: The TLS configuration context.
00201  *
00202  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00203  */
00204 palStatus_t pal_handShake(palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf);
00205 
00206 /*! \brief Set the retransmit timeout values for the DTLS handshake.
00207  *  DTLS only, no effect on TLS.
00208  *
00209  * @param[in] palTLSConf: The DTLS configuration context.
00210  * @param[in] timeoutInMilliSec: The timeout value in milliseconds.
00211  *
00212  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00213  */
00214 palStatus_t pal_setHandShakeTimeOut(palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec);
00215 
00216 /*! \brief Return the result of the certificate verification.
00217  *
00218  * @param[in] palTLSHandle: The TLS context.
00219  *
00220  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00221  */
00222 palStatus_t pal_sslGetVerifyResult(palTLSHandle_t palTLSHandle);
00223 
00224 /*! \brief Return the result of the certificate verification.
00225  *
00226  * @param[in] palTLSHandle: The TLS context.
00227  * @param[out] verifyResult: Bitmask of errors that cause the failure. This value is
00228  *                           relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00229  *
00230  * \return PAL_SUCCESS on success.
00231  * \return PAL_ERR_X509_CERT_VERIFY_FAILED in case of failure.
00232  */
00233 palStatus_t pal_sslGetVerifyResultExtended(palTLSHandle_t palTLSHandle, int32_t* verifyResult);
00234 
00235 /*! \brief Read the application data bytes (the max number of bytes).
00236  *
00237  * @param[in] palTLSHandle: The TLS context.
00238  * @param[out] buffer: A buffer that holds the data.
00239  * @param[in] len: The maximum number of bytes to read.
00240  * @param[out] actualLen: The the actual number of bytes read.
00241  *
00242  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00243  */
00244 palStatus_t pal_sslRead(palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen);
00245 
00246 /*! \brief Write the exact length of application data bytes.
00247  *
00248  * @param[in] palTLSHandle: The TLS context.
00249  * @param[in] buffer: A buffer holding the data.
00250  * @param[in] len: The number of bytes to be written.
00251  * @param[out] bytesWritten: The number of bytes actually written.
00252  *
00253  * \return PAL_SUCCESS on success, or a negative value indicating a specific error code in case of failure.
00254  */
00255 palStatus_t pal_sslWrite(palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten);
00256 
00257 /*! \brief Turn the debugging on or off for the given TLS library configuration handle. The logs are sent via the `mbedTrace`.
00258  *   In case of release mode, an error will be returned.
00259  *
00260  * @param[in] palTLSConf : The TLS confuguraiton to modify.
00261  * @param[in] turnOn: If greater than 0, turn on debugging. Otherwise turn it off.
00262  *
00263  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00264  */
00265 palStatus_t pal_sslSetDebugging(palTLSConfHandle_t palTLSConf,uint8_t turnOn);
00266 
00267 /*! Turn debugging on or off for the whole TLS library. The logs are sent via the `mbedTrace`.
00268  *   In case of release mode, an error will be returned.
00269  *
00270  * @param[in] turnOn: If greater than 0, turn on debugging. Otherwise turn it off.
00271  *
00272  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00273  */
00274 palStatus_t pal_sslDebugging(uint8_t turnOn);
00275 
00276 #endif // _PAL_DTLS_H_