pal_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_DTLS_H_
00018 #define _PAL_DTLS_H_
00019 
00020 #ifndef _PAL_H
00021     #error "Please do not include this file directly, use pal.h instead"
00022 #endif
00023 
00024 /*! \file pal_TLS.h
00025 *  \brief PAL TLS/DTLS.
00026 *   This file contains TLS/DTLS APIs and is a part of the PAL service API.
00027 *   It provides TLS/DTLS handshake functionalities, read/write from peer in a secure way.
00028 */
00029 
00030 /***************************************************/
00031 /**** PAL DTLS data structures *********************/
00032 /***************************************************/
00033 
00034 // Index in the static array of the TLSs.
00035 typedef uintptr_t palTLSHandle_t;
00036 typedef uintptr_t palTLSConfHandle_t;
00037 
00038 typedef enum palTLSTranportMode{
00039 #ifdef PAL_NET_TCP_AND_TLS_SUPPORT
00040     PAL_TLS_MODE, //(STREAM)
00041 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
00042     PAL_DTLS_MODE //(DATAGRAM)
00043 }palTLSTransportMode_t;
00044 
00045 typedef struct palTLSSocket{
00046     palSocket_t socket;
00047     palSocketAddress_t* socketAddress;
00048     palSocketLength_t addressLength;
00049     palTLSTransportMode_t transportationMode;
00050 }palTLSSocket_t;
00051 
00052 
00053 typedef struct palTLSBuffer{
00054     const void* buffer;
00055     uint32_t size;
00056 }palTLSBuffer_t;
00057 
00058 typedef palTLSBuffer_t palX509_t;
00059 typedef palTLSBuffer_t palX509CRL_t;
00060 typedef palTLSBuffer_t palPrivateKey_t;
00061 
00062 //! This callback is useful ONLY when mbed TLS used as TLS platform library. In other platforms,
00063 //! you should NOT use this callback in the code. The related function is not supported in other
00064 //! platforms than mbedTLS.
00065 typedef int(*palEntropySource_f)(void *data, unsigned char *output, size_t len, size_t *olen);
00066 
00067 /***************************************************/
00068 /**** PAL DTLS Client APIs *************************/
00069 /***************************************************/
00070 
00071 /*! Initiate the TLS library.
00072 *
00073 \note You must call this function in the general PAL initializtion function.
00074 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00075 */
00076 palStatus_t pal_initTLSLibrary(void);
00077 
00078 /*! Free resources for the TLS library.
00079 *
00080 \note You must call this function in the general PAL cleanup function.
00081 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00082 */
00083 palStatus_t pal_cleanupTLS(void);
00084 
00085 /*! Initiate a new TLS context.
00086 *
00087 * @param[in] palTLSConf: The TLS configuration context.
00088 * @param[out] palTLSHandle: The index to the TLS context.
00089 *
00090 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00091 */
00092 palStatus_t pal_initTLS(palTLSConfHandle_t palTLSConf, palTLSHandle_t* palTLSHandle);
00093 
00094 /*! Destroy and free resources for the TLS context.
00095 *
00096 * @param[in] palTLSHandle: The index to the TLS context.
00097 *
00098 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00099 */
00100 palStatus_t pal_freeTLS(palTLSHandle_t* palTLSHandle);
00101 
00102 /*! Add entropy source to the TLS/DTLS library. (This API may NOT be available in all TLS/DTLS platforms, see note.) 
00103 *
00104 * @param[in] entropyCallback: The entropy callback to be used in TLS/DTLS handshake.
00105 *
00106 \note This function is available ONLY when the TLS/DTLS platform supports this functionality. In other platforms,
00107       PAL_ERR_NOT_SUPPORTED should be returned.
00108 \note This function MUST be called (if needed) before calling the `pal_initTLSConfiguration()` function.
00109 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure, or PAL_ERR_NOT_SUPPORTED.
00110 */
00111 palStatus_t pal_addEntropySource(palEntropySource_f entropyCallback);
00112 
00113 /*! Initiate a new configuration context.
00114 *
00115 * @param[out] palTLSConf: The context that holds the TLS configuration.
00116 * @param[in] transportationMode: The connection type (TLS OR DTLS). See `palTranportVersion_t`.
00117 *
00118 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00119 */
00120 palStatus_t pal_initTLSConfiguration(palTLSConfHandle_t* palTLSConf, palTLSTransportMode_t transportationMode);
00121 
00122 /*! Destroy and free resources for the TLS configurtion context.
00123 *
00124 * @param[in] palTLSConf: The TLS configuration context to free.
00125 *
00126 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00127 */
00128 palStatus_t pal_tlsConfigurationFree(palTLSConfHandle_t* palTLSConf);
00129 
00130 /*! Set your own certificate chain and private key.
00131 *
00132 * @param[in] palTLSConf: The TLS configuration context.
00133 * @param[in] ownCert: Your own public certificate chain.
00134 * @param[in] privateKey: Your own private key.
00135 *
00136 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00137 */
00138 palStatus_t pal_setOwnCertAndPrivateKey(palTLSConfHandle_t palTLSConf, palX509_t* ownCert, palPrivateKey_t* privateKey);
00139 
00140 /*! Set the data required to verify the peer certificate.
00141 *
00142 * @param[in] palTLSConf: The TLS configuration context.
00143 * @param[in] caChain: The trusted CA chain.
00144 * @param[in] caCRL: The trusted CA CRLs.
00145 *
00146 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00147 */
00148 palStatus_t pal_setCAChain(palTLSConfHandle_t palTLSConf, palX509_t* caChain, palX509CRL_t* caCRL);
00149 
00150 /*! Set the Pre-Shared Key (PSK) and the expected identity name.
00151 *
00152 * @param[in] palTLSConf: The TLS configuration context.
00153 * @param[in] identity: A pointer to the pre-shared key identity.
00154 * @param[in] maxIdentityLenInBytes: The length of the key identity.
00155 * @param[in] psk: A pointer to the pre-shared key.
00156 * @param[in] maxPskLenInBytes: The length of the pre-shared key.
00157 *
00158 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00159 */
00160 palStatus_t pal_setPSK(palTLSConfHandle_t palTLSConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes);
00161 
00162 /*! Set the socket used by the TLS configuration context.
00163 *
00164 * @param[in] palTLSConf: The TLS configuration context.
00165 * @param[in] socket: The socket to be used by the TLS context.
00166 *
00167 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00168 */
00169 palStatus_t pal_tlsSetSocket(palTLSConfHandle_t palTLSConf, palTLSSocket_t* socket);
00170 
00171 /*! Perform the TLS handshake (blocking).
00172 *
00173 * This function sets the TLS configuration context into the TLS context and performs the handshake 
00174 * with the peer.
00175 * @param[in] palTLSHandle: The TLS context.
00176 * @param[in] palTLSConf: The TLS configuration context.
00177 *
00178 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00179 */
00180 palStatus_t pal_handShake(palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf);
00181 
00182 /*! Set the retransmit timeout values for the DTLS handshake.
00183 *   (DTLS only, no effect on TLS.)
00184 *
00185 * @param[in] palTLSConf: The TLS configuration context.
00186 * @param[in] timeoutInMilliSec: The timeout value in seconds.
00187 *
00188 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00189 */
00190 palStatus_t pal_setHandShakeTimeOut(palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec);
00191 
00192 /*! Return the result of the certificate verification.
00193 *
00194 * @param[in] ssl: The SSL context.
00195 *
00196 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00197 */
00198 palStatus_t pal_sslGetVerifyResult(palTLSHandle_t palTLSHandle);
00199 
00200 /*! Return the result of the certificate verification.
00201 *
00202 * @param[in] ssl: The SSL context.
00203 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is 
00204 *                           relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00205 *
00206 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00207 */
00208 palStatus_t pal_sslGetVerifyResultExtended(palTLSHandle_t palTLSHandle, int32_t* verifyResult);
00209 
00210 /*! Read the application data bytes (the max number of bytes).
00211 *
00212 * @param[in] palTLSHandle: The TLS context.
00213 * @param[out] buffer: A buffer that holds the data.
00214 * @param[in] len: The maximum number of bytes to read.
00215 * @param[out] actualLen: The the actual number of bytes read.
00216 *
00217 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00218 */
00219 palStatus_t pal_sslRead(palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen);
00220 
00221 /*! Write the exact length of application data bytes.
00222 *
00223 * @param[in] palTLSHandle: The TLS context.
00224 * @param[in] buffer: A buffer holding the data.
00225 * @param[in] len: The number of bytes to be written.
00226 * @param[out] bytesWritten: The number of bytes actually written.
00227 *
00228 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00229 */
00230 palStatus_t pal_sslWrite(palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten);
00231 
00232 /*! Turn on/off debugging from the TLS library. The logs are sent via the mbedTrace.
00233 *   In case of release mode, an error will be returned.
00234 *
00235 * @param[in] turnOn
00236 *
00237 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00238 */
00239 palStatus_t pal_sslDebugging(uint8_t turnOn);
00240 
00241 #endif // _PAL_DTLS_H_