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 * @deprecated This function has been splitted into two separate functions, pal_setOwnCertChain() and pal_setOwnPrivateKey().
00133 * @param[in] palTLSConf: The TLS configuration context.
00134 * @param[in] ownCert: Your own public certificate chain.
00135 * @param[in] privateKey: Your own private key.
00136 *
00137 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00138 */
00139 palStatus_t pal_setOwnCertAndPrivateKey(palTLSConfHandle_t palTLSConf, palX509_t* ownCert, palPrivateKey_t* privateKey);
00140 
00141 /*! Set your own certificate chain.
00142 *
00143 * @param[in] palTLSConf: The TLS configuration context.
00144 * @param[in] ownCert: Your own public certificate chain.
00145 *
00146 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00147 */
00148 palStatus_t pal_setOwnCertChain(palTLSConfHandle_t palTLSConf, palX509_t* ownCert);
00149 
00150 /*! Set your own private key.
00151 *
00152 * @param[in] palTLSConf: The TLS configuration context.
00153 * @param[in] privateKey: Your own private key.
00154 *
00155 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00156 */
00157 palStatus_t pal_setOwnPrivateKey(palTLSConfHandle_t palTLSConf, palPrivateKey_t* privateKey);
00158 
00159 /*! Set the data required to verify the peer certificate.
00160 *
00161 * @param[in] palTLSConf: The TLS configuration context.
00162 * @param[in] caChain: The trusted CA chain.
00163 * @param[in] caCRL: The trusted CA CRLs.
00164 *
00165 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00166 */
00167 palStatus_t pal_setCAChain(palTLSConfHandle_t palTLSConf, palX509_t* caChain, palX509CRL_t* caCRL);
00168 
00169 /*! Set the Pre-Shared Key (PSK) and the expected identity name.
00170 *
00171 * @param[in] palTLSConf: The TLS configuration context.
00172 * @param[in] identity: A pointer to the pre-shared key identity.
00173 * @param[in] maxIdentityLenInBytes: The length of the key identity.
00174 * @param[in] psk: A pointer to the pre-shared key.
00175 * @param[in] maxPskLenInBytes: The length of the pre-shared key.
00176 *
00177 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00178 */
00179 palStatus_t pal_setPSK(palTLSConfHandle_t palTLSConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes);
00180 
00181 /*! Set the socket used by the TLS configuration context.
00182 *
00183 * @param[in] palTLSConf: The TLS configuration context.
00184 * @param[in] socket: The socket to be used by the TLS context.
00185 *
00186 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00187 */
00188 palStatus_t pal_tlsSetSocket(palTLSConfHandle_t palTLSConf, palTLSSocket_t* socket);
00189 
00190 /*! Perform the TLS handshake (blocking).
00191 *
00192 * This function sets the TLS configuration context into the TLS context and performs the handshake
00193 * with the peer.
00194 * @param[in] palTLSHandle: The TLS context.
00195 * @param[in] palTLSConf: The TLS configuration context.
00196 *
00197 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00198 */
00199 palStatus_t pal_handShake(palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf);
00200 
00201 /*! Set the retransmit timeout values for the DTLS handshake.
00202 *   (DTLS only, no effect on TLS.)
00203 *
00204 * @param[in] palTLSConf: The TLS configuration context.
00205 * @param[in] timeoutInMilliSec: The timeout value in seconds.
00206 *
00207 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00208 */
00209 palStatus_t pal_setHandShakeTimeOut(palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec);
00210 
00211 /*! Return the result of the certificate verification.
00212 *
00213 * @param[in] ssl: The SSL context.
00214 *
00215 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00216 */
00217 palStatus_t pal_sslGetVerifyResult(palTLSHandle_t palTLSHandle);
00218 
00219 /*! Return the result of the certificate verification.
00220 *
00221 * @param[in] ssl: The SSL context.
00222 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is
00223 *                           relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00224 *
00225 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00226 */
00227 palStatus_t pal_sslGetVerifyResultExtended(palTLSHandle_t palTLSHandle, int32_t* verifyResult);
00228 
00229 /*! Read the application data bytes (the max number of bytes).
00230 *
00231 * @param[in] palTLSHandle: The TLS context.
00232 * @param[out] buffer: A buffer that holds the data.
00233 * @param[in] len: The maximum number of bytes to read.
00234 * @param[out] actualLen: The the actual number of bytes read.
00235 *
00236 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00237 */
00238 palStatus_t pal_sslRead(palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen);
00239 
00240 /*! Write the exact length of application data bytes.
00241 *
00242 * @param[in] palTLSHandle: The TLS context.
00243 * @param[in] buffer: A buffer holding the data.
00244 * @param[in] len: The number of bytes to be written.
00245 * @param[out] bytesWritten: The number of bytes actually written.
00246 *
00247 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00248 */
00249 palStatus_t pal_sslWrite(palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten);
00250 
00251 /*! Turn on/off the TLS library debugging for the given configuration handle. The logs are sent via the mbedTrace.
00252 *   In case of release mode, an error will be returned.
00253 *
00254 * @param[in] palTLSConf : the TLS confuguraiton to modify
00255 * @param[in] turnOn: if greater than 0 turn on debugging, otherwise turn it off
00256 *
00257 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00258 */
00259 palStatus_t pal_sslSetDebugging(palTLSConfHandle_t palTLSConf,uint8_t turnOn);
00260 
00261 
00262 
00263 /*! Turn on/off debugging from the TLS library. The logs are sent via the mbedTrace.
00264 *   In case of release mode, an error will be returned.
00265 *
00266 * @param[in] turnOn if greater than 0 turn on debugging, otherwise turn it off
00267 *
00268 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00269 */
00270 palStatus_t pal_sslDebugging(uint8_t turnOn);
00271 
00272 #endif // _PAL_DTLS_H_