Toyomasa Watarai / simple-mbed-cloud-client

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:  

mbed-cloud-client/mbed-client-pal/Source/PAL-Impl/Services-API/pal_TLS.h@0:276e7a263c35, 2018-07-02 (annotated)

Committer:
MACRUM
Date:
Mon Jul 02 06:30:39 2018 +0000
Revision:
0:276e7a263c35
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MACRUM 0:276e7a263c35 1 /*******************************************************************************
MACRUM 0:276e7a263c35 2 * Copyright 2016, 2017 ARM Ltd.
MACRUM 0:276e7a263c35 3 *
MACRUM 0:276e7a263c35 4 * Licensed under the Apache License, Version 2.0 (the "License");
MACRUM 0:276e7a263c35 5 * you may not use this file except in compliance with the License.
MACRUM 0:276e7a263c35 6 * You may obtain a copy of the License at
MACRUM 0:276e7a263c35 7 *
MACRUM 0:276e7a263c35 8 * http://www.apache.org/licenses/LICENSE-2.0
MACRUM 0:276e7a263c35 9 *
MACRUM 0:276e7a263c35 10 * Unless required by applicable law or agreed to in writing, software
MACRUM 0:276e7a263c35 11 * distributed under the License is distributed on an "AS IS" BASIS,
MACRUM 0:276e7a263c35 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
MACRUM 0:276e7a263c35 13 * See the License for the specific language governing permissions and
MACRUM 0:276e7a263c35 14 * limitations under the License.
MACRUM 0:276e7a263c35 15 *******************************************************************************/
MACRUM 0:276e7a263c35 16
MACRUM 0:276e7a263c35 17 #ifndef _PAL_DTLS_H_
MACRUM 0:276e7a263c35 18 #define _PAL_DTLS_H_
MACRUM 0:276e7a263c35 19
MACRUM 0:276e7a263c35 20 #ifndef _PAL_H
MACRUM 0:276e7a263c35 21 #error "Please do not include this file directly, use pal.h instead"
MACRUM 0:276e7a263c35 22 #endif
MACRUM 0:276e7a263c35 23
MACRUM 0:276e7a263c35 24 /*! \file pal_TLS.h
MACRUM 0:276e7a263c35 25 * \brief PAL TLS/DTLS.
MACRUM 0:276e7a263c35 26 * This file contains TLS/DTLS APIs and is a part of the PAL service API.
MACRUM 0:276e7a263c35 27 * It provides TLS/DTLS handshake functionalities, read/write from peer in a secure way.
MACRUM 0:276e7a263c35 28 */
MACRUM 0:276e7a263c35 29
MACRUM 0:276e7a263c35 30 /***************************************************/
MACRUM 0:276e7a263c35 31 /**** PAL DTLS data structures *********************/
MACRUM 0:276e7a263c35 32 /***************************************************/
MACRUM 0:276e7a263c35 33
MACRUM 0:276e7a263c35 34 // Index in the static array of the TLSs.
MACRUM 0:276e7a263c35 35 typedef uintptr_t palTLSHandle_t;
MACRUM 0:276e7a263c35 36 typedef uintptr_t palTLSConfHandle_t;
MACRUM 0:276e7a263c35 37
MACRUM 0:276e7a263c35 38 typedef enum palTLSTranportMode{
MACRUM 0:276e7a263c35 39 #ifdef PAL_NET_TCP_AND_TLS_SUPPORT
MACRUM 0:276e7a263c35 40 PAL_TLS_MODE, //(STREAM)
MACRUM 0:276e7a263c35 41 #endif //PAL_NET_TCP_AND_TLS_SUPPORT
MACRUM 0:276e7a263c35 42 PAL_DTLS_MODE //(DATAGRAM)
MACRUM 0:276e7a263c35 43 }palTLSTransportMode_t;
MACRUM 0:276e7a263c35 44
MACRUM 0:276e7a263c35 45 typedef struct palTLSSocket{
MACRUM 0:276e7a263c35 46 palSocket_t socket;
MACRUM 0:276e7a263c35 47 palSocketAddress_t* socketAddress;
MACRUM 0:276e7a263c35 48 palSocketLength_t addressLength;
MACRUM 0:276e7a263c35 49 palTLSTransportMode_t transportationMode;
MACRUM 0:276e7a263c35 50 }palTLSSocket_t;
MACRUM 0:276e7a263c35 51
MACRUM 0:276e7a263c35 52
MACRUM 0:276e7a263c35 53 typedef struct palTLSBuffer{
MACRUM 0:276e7a263c35 54 const void* buffer;
MACRUM 0:276e7a263c35 55 uint32_t size;
MACRUM 0:276e7a263c35 56 }palTLSBuffer_t;
MACRUM 0:276e7a263c35 57
MACRUM 0:276e7a263c35 58 typedef palTLSBuffer_t palX509_t;
MACRUM 0:276e7a263c35 59 typedef palTLSBuffer_t palX509CRL_t;
MACRUM 0:276e7a263c35 60 typedef palTLSBuffer_t palPrivateKey_t;
MACRUM 0:276e7a263c35 61
MACRUM 0:276e7a263c35 62 //! This callback is useful ONLY when mbed TLS used as TLS platform library. In other platforms,
MACRUM 0:276e7a263c35 63 //! you should NOT use this callback in the code. The related function is not supported in other
MACRUM 0:276e7a263c35 64 //! platforms than mbedTLS.
MACRUM 0:276e7a263c35 65 typedef int(*palEntropySource_f)(void *data, unsigned char *output, size_t len, size_t *olen);
MACRUM 0:276e7a263c35 66
MACRUM 0:276e7a263c35 67 /***************************************************/
MACRUM 0:276e7a263c35 68 /**** PAL DTLS Client APIs *************************/
MACRUM 0:276e7a263c35 69 /***************************************************/
MACRUM 0:276e7a263c35 70
MACRUM 0:276e7a263c35 71 /*! Initiate the TLS library.
MACRUM 0:276e7a263c35 72 *
MACRUM 0:276e7a263c35 73 \note You must call this function in the general PAL initializtion function.
MACRUM 0:276e7a263c35 74 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 75 */
MACRUM 0:276e7a263c35 76 palStatus_t pal_initTLSLibrary(void);
MACRUM 0:276e7a263c35 77
MACRUM 0:276e7a263c35 78 /*! Free resources for the TLS library.
MACRUM 0:276e7a263c35 79 *
MACRUM 0:276e7a263c35 80 \note You must call this function in the general PAL cleanup function.
MACRUM 0:276e7a263c35 81 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 82 */
MACRUM 0:276e7a263c35 83 palStatus_t pal_cleanupTLS(void);
MACRUM 0:276e7a263c35 84
MACRUM 0:276e7a263c35 85 /*! Initiate a new TLS context.
MACRUM 0:276e7a263c35 86 *
MACRUM 0:276e7a263c35 87 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 88 * @param[out] palTLSHandle: The index to the TLS context.
MACRUM 0:276e7a263c35 89 *
MACRUM 0:276e7a263c35 90 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 91 */
MACRUM 0:276e7a263c35 92 palStatus_t pal_initTLS(palTLSConfHandle_t palTLSConf, palTLSHandle_t* palTLSHandle);
MACRUM 0:276e7a263c35 93
MACRUM 0:276e7a263c35 94 /*! Destroy and free resources for the TLS context.
MACRUM 0:276e7a263c35 95 *
MACRUM 0:276e7a263c35 96 * @param[in] palTLSHandle: The index to the TLS context.
MACRUM 0:276e7a263c35 97 *
MACRUM 0:276e7a263c35 98 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 99 */
MACRUM 0:276e7a263c35 100 palStatus_t pal_freeTLS(palTLSHandle_t* palTLSHandle);
MACRUM 0:276e7a263c35 101
MACRUM 0:276e7a263c35 102 /*! Add entropy source to the TLS/DTLS library. (This API may NOT be available in all TLS/DTLS platforms, see note.)
MACRUM 0:276e7a263c35 103 *
MACRUM 0:276e7a263c35 104 * @param[in] entropyCallback: The entropy callback to be used in TLS/DTLS handshake.
MACRUM 0:276e7a263c35 105 *
MACRUM 0:276e7a263c35 106 \note This function is available ONLY when the TLS/DTLS platform supports this functionality. In other platforms,
MACRUM 0:276e7a263c35 107 PAL_ERR_NOT_SUPPORTED should be returned.
MACRUM 0:276e7a263c35 108 \note This function MUST be called (if needed) before calling the `pal_initTLSConfiguration()` function.
MACRUM 0:276e7a263c35 109 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure, or PAL_ERR_NOT_SUPPORTED.
MACRUM 0:276e7a263c35 110 */
MACRUM 0:276e7a263c35 111 palStatus_t pal_addEntropySource(palEntropySource_f entropyCallback);
MACRUM 0:276e7a263c35 112
MACRUM 0:276e7a263c35 113 /*! Initiate a new configuration context.
MACRUM 0:276e7a263c35 114 *
MACRUM 0:276e7a263c35 115 * @param[out] palTLSConf: The context that holds the TLS configuration.
MACRUM 0:276e7a263c35 116 * @param[in] transportationMode: The connection type (TLS OR DTLS). See `palTranportVersion_t`.
MACRUM 0:276e7a263c35 117 *
MACRUM 0:276e7a263c35 118 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 119 */
MACRUM 0:276e7a263c35 120 palStatus_t pal_initTLSConfiguration(palTLSConfHandle_t* palTLSConf, palTLSTransportMode_t transportationMode);
MACRUM 0:276e7a263c35 121
MACRUM 0:276e7a263c35 122 /*! Destroy and free resources for the TLS configurtion context.
MACRUM 0:276e7a263c35 123 *
MACRUM 0:276e7a263c35 124 * @param[in] palTLSConf: The TLS configuration context to free.
MACRUM 0:276e7a263c35 125 *
MACRUM 0:276e7a263c35 126 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 127 */
MACRUM 0:276e7a263c35 128 palStatus_t pal_tlsConfigurationFree(palTLSConfHandle_t* palTLSConf);
MACRUM 0:276e7a263c35 129
MACRUM 0:276e7a263c35 130 /*! Set your own certificate chain and private key.
MACRUM 0:276e7a263c35 131 *
MACRUM 0:276e7a263c35 132 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 133 * @param[in] ownCert: Your own public certificate chain.
MACRUM 0:276e7a263c35 134 * @param[in] privateKey: Your own private key.
MACRUM 0:276e7a263c35 135 *
MACRUM 0:276e7a263c35 136 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 137 */
MACRUM 0:276e7a263c35 138 palStatus_t pal_setOwnCertAndPrivateKey(palTLSConfHandle_t palTLSConf, palX509_t* ownCert, palPrivateKey_t* privateKey);
MACRUM 0:276e7a263c35 139
MACRUM 0:276e7a263c35 140 /*! Set the data required to verify the peer certificate.
MACRUM 0:276e7a263c35 141 *
MACRUM 0:276e7a263c35 142 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 143 * @param[in] caChain: The trusted CA chain.
MACRUM 0:276e7a263c35 144 * @param[in] caCRL: The trusted CA CRLs.
MACRUM 0:276e7a263c35 145 *
MACRUM 0:276e7a263c35 146 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 147 */
MACRUM 0:276e7a263c35 148 palStatus_t pal_setCAChain(palTLSConfHandle_t palTLSConf, palX509_t* caChain, palX509CRL_t* caCRL);
MACRUM 0:276e7a263c35 149
MACRUM 0:276e7a263c35 150 /*! Set the Pre-Shared Key (PSK) and the expected identity name.
MACRUM 0:276e7a263c35 151 *
MACRUM 0:276e7a263c35 152 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 153 * @param[in] identity: A pointer to the pre-shared key identity.
MACRUM 0:276e7a263c35 154 * @param[in] maxIdentityLenInBytes: The length of the key identity.
MACRUM 0:276e7a263c35 155 * @param[in] psk: A pointer to the pre-shared key.
MACRUM 0:276e7a263c35 156 * @param[in] maxPskLenInBytes: The length of the pre-shared key.
MACRUM 0:276e7a263c35 157 *
MACRUM 0:276e7a263c35 158 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 159 */
MACRUM 0:276e7a263c35 160 palStatus_t pal_setPSK(palTLSConfHandle_t palTLSConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes);
MACRUM 0:276e7a263c35 161
MACRUM 0:276e7a263c35 162 /*! Set the socket used by the TLS configuration context.
MACRUM 0:276e7a263c35 163 *
MACRUM 0:276e7a263c35 164 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 165 * @param[in] socket: The socket to be used by the TLS context.
MACRUM 0:276e7a263c35 166 *
MACRUM 0:276e7a263c35 167 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 168 */
MACRUM 0:276e7a263c35 169 palStatus_t pal_tlsSetSocket(palTLSConfHandle_t palTLSConf, palTLSSocket_t* socket);
MACRUM 0:276e7a263c35 170
MACRUM 0:276e7a263c35 171 /*! Perform the TLS handshake (blocking).
MACRUM 0:276e7a263c35 172 *
MACRUM 0:276e7a263c35 173 * This function sets the TLS configuration context into the TLS context and performs the handshake
MACRUM 0:276e7a263c35 174 * with the peer.
MACRUM 0:276e7a263c35 175 * @param[in] palTLSHandle: The TLS context.
MACRUM 0:276e7a263c35 176 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 177 *
MACRUM 0:276e7a263c35 178 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 179 */
MACRUM 0:276e7a263c35 180 palStatus_t pal_handShake(palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf);
MACRUM 0:276e7a263c35 181
MACRUM 0:276e7a263c35 182 /*! Set the retransmit timeout values for the DTLS handshake.
MACRUM 0:276e7a263c35 183 * (DTLS only, no effect on TLS.)
MACRUM 0:276e7a263c35 184 *
MACRUM 0:276e7a263c35 185 * @param[in] palTLSConf: The TLS configuration context.
MACRUM 0:276e7a263c35 186 * @param[in] timeoutInMilliSec: The timeout value in seconds.
MACRUM 0:276e7a263c35 187 *
MACRUM 0:276e7a263c35 188 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 189 */
MACRUM 0:276e7a263c35 190 palStatus_t pal_setHandShakeTimeOut(palTLSConfHandle_t palTLSConf, uint32_t timeoutInMilliSec);
MACRUM 0:276e7a263c35 191
MACRUM 0:276e7a263c35 192 /*! Return the result of the certificate verification.
MACRUM 0:276e7a263c35 193 *
MACRUM 0:276e7a263c35 194 * @param[in] ssl: The SSL context.
MACRUM 0:276e7a263c35 195 *
MACRUM 0:276e7a263c35 196 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 197 */
MACRUM 0:276e7a263c35 198 palStatus_t pal_sslGetVerifyResult(palTLSHandle_t palTLSHandle);
MACRUM 0:276e7a263c35 199
MACRUM 0:276e7a263c35 200 /*! Return the result of the certificate verification.
MACRUM 0:276e7a263c35 201 *
MACRUM 0:276e7a263c35 202 * @param[in] ssl: The SSL context.
MACRUM 0:276e7a263c35 203 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is
MACRUM 0:276e7a263c35 204 * relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
MACRUM 0:276e7a263c35 205 *
MACRUM 0:276e7a263c35 206 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`.
MACRUM 0:276e7a263c35 207 */
MACRUM 0:276e7a263c35 208 palStatus_t pal_sslGetVerifyResultExtended(palTLSHandle_t palTLSHandle, int32_t* verifyResult);
MACRUM 0:276e7a263c35 209
MACRUM 0:276e7a263c35 210 /*! Read the application data bytes (the max number of bytes).
MACRUM 0:276e7a263c35 211 *
MACRUM 0:276e7a263c35 212 * @param[in] palTLSHandle: The TLS context.
MACRUM 0:276e7a263c35 213 * @param[out] buffer: A buffer that holds the data.
MACRUM 0:276e7a263c35 214 * @param[in] len: The maximum number of bytes to read.
MACRUM 0:276e7a263c35 215 * @param[out] actualLen: The the actual number of bytes read.
MACRUM 0:276e7a263c35 216 *
MACRUM 0:276e7a263c35 217 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 218 */
MACRUM 0:276e7a263c35 219 palStatus_t pal_sslRead(palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen);
MACRUM 0:276e7a263c35 220
MACRUM 0:276e7a263c35 221 /*! Write the exact length of application data bytes.
MACRUM 0:276e7a263c35 222 *
MACRUM 0:276e7a263c35 223 * @param[in] palTLSHandle: The TLS context.
MACRUM 0:276e7a263c35 224 * @param[in] buffer: A buffer holding the data.
MACRUM 0:276e7a263c35 225 * @param[in] len: The number of bytes to be written.
MACRUM 0:276e7a263c35 226 * @param[out] bytesWritten: The number of bytes actually written.
MACRUM 0:276e7a263c35 227 *
MACRUM 0:276e7a263c35 228 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 229 */
MACRUM 0:276e7a263c35 230 palStatus_t pal_sslWrite(palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten);
MACRUM 0:276e7a263c35 231
MACRUM 0:276e7a263c35 232 /*! Turn on/off debugging from the TLS library. The logs are sent via the mbedTrace.
MACRUM 0:276e7a263c35 233 * In case of release mode, an error will be returned.
MACRUM 0:276e7a263c35 234 *
MACRUM 0:276e7a263c35 235 * @param[in] turnOn
MACRUM 0:276e7a263c35 236 *
MACRUM 0:276e7a263c35 237 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
MACRUM 0:276e7a263c35 238 */
MACRUM 0:276e7a263c35 239 palStatus_t pal_sslDebugging(uint8_t turnOn);
MACRUM 0:276e7a263c35 240
MACRUM 0:276e7a263c35 241 #endif // _PAL_DTLS_H_