Mistake on this page? Email us
pal_plat_TLS.h
Go to the documentation of this file.
1 /*******************************************************************************
2  * Copyright 2016, 2017 ARM Ltd.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *******************************************************************************/
16 
17 #ifndef _PAL_PLAT_TLS_H_
18 #define _PAL_PLAT_TLS_H_
19 #include "pal_TLS.h"
20 
21 
27 /***************************************************/
28 /**** PAL DTLS internal data structures ************/
29 /***************************************************/
30 typedef enum palDTLSSide{
31 #ifdef PAL_TLS_SUPPORT_SERVER_MODE
32  PAL_TLS_IS_SERVER,
33 #endif // PAL_TLS_SUPPORT_SERVER_MODE
36 
39 typedef enum palTLSAuthMode{
44 
50 typedef enum palTLSSuites{
58 
59 typedef void* palTLSSocketHandle_t;
60 typedef void* palTimerCtx_t;
61 
62 // This prototype can be re-defined by the platform side.
63 // Consider moving them to separate header.
64 typedef int (*palBIOSend_f)(palTLSSocketHandle_t socket, const unsigned char *buf, size_t len);
65 typedef int (*palBIORecv_f)(palTLSSocketHandle_t socket, unsigned char *buf, size_t len);
66 typedef int (*palVerifyCallback_f)(void *, void *, int, uint32_t *);
67 typedef void (*palSetTimer_f)( void *data, uint32_t intMs, uint32_t finMs );
68 typedef int (*palGetTimer_f)(void* data);
69 typedef void (*palLogFunc_f)(void *context, int debugLevel, const char *fileName, int line, const char *message);
70 
71 
81 
88 
98 
106 
115 
123 
132 
141 
151 palStatus_t pal_plat_sslGetVerifyResultExtended(palTLSHandle_t palTLSHandle, int32_t* verifyResult);
152 
162 palStatus_t pal_plat_sslRead(palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t* actualLen);
163 
173 palStatus_t pal_plat_sslWrite(palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten);
174 
184 palStatus_t pal_plat_setHandShakeTimeOut(palTLSConfHandle_t palTLSConf, uint32_t minTimeout, uint32_t maxTimeout);
185 
194 
202 
210 palStatus_t pal_plat_handShake(palTLSHandle_t palTLSHandle, uint64_t* serverTime);
211 
212 #if PAL_USE_SECURE_TIME
213 
220 palStatus_t pal_plat_renegotiate(palTLSHandle_t palTLSHandle, uint64_t serverTime);
221 #endif //PAL_USE_SECURE_TIME
222 
231 
240 
249 
259 
270 palStatus_t pal_plat_setPSK(palTLSConfHandle_t sslConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes);
271 
272 
282 
283 
293 palStatus_t pal_plat_sslSetDebugging(palTLSConfHandle_t palTLSConf, uint8_t turnOn);
294 
305 
315 palStatus_t pal_plat_setTimeCB(palTLSHandle_t* palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer);
316 
325 palStatus_t pal_plat_SetLoggingCb(palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext);
326 
334 void pal_plat_SetDTLSSocketCallback(palTLSConfHandle_t palTLSConf, palSocketCallback_f cb, void *argument);
335 
336 #if (PAL_USE_SSL_SESSION_RESUME == 1)
337 
345 uint8_t* pal_plat_GetSslSessionBuffer(palTLSHandle_t palTLSHandle, size_t *buffer_size);
346 
353 void pal_plat_SetSslSession(palTLSHandle_t palTLSHandle, const uint8_t *session_buffer);
354 
361 int32_t pal_plat_saveSslSessionBuffer(palTLSHandle_t palTLSHandle);
362 
369 int32_t pal_plat_loadSslSession(palTLSHandle_t palTLSHandle);
370 
374 void pal_plat_removeSslSession();
375 
380 bool pal_plat_sslSessionAvailable();
381 
387 const uint8_t* pal_plat_get_cid(size_t *size);
388 
394 void pal_plat_set_cid(const uint8_t* context, const size_t length);
395 #endif //PAL_USE_SSL_SESSION_RESUME
396 #endif //_PAL_PLAT_TLS_H_
397 
398 
palStatus_t pal_plat_initTLSConf(palTLSConfHandle_t *confCtx, palTLSTransportMode_t transportVersion, palDTLSSide_t methodType)
Initiate a new configuration context.
palStatus_t pal_plat_setOwnCertChain(palTLSConfHandle_t palTLSConf, palX509_t *ownCert)
Set your own certificate chain.
int(* palEntropySource_f)(void *data, unsigned char *output, size_t len, size_t *olen)
This callback is useful ONLY when mbed TLS is used as TLS platform library.
Definition: pal_TLS.h:73
palStatus_t pal_plat_initTLSLibrary(void)
Initiate the TLS library.
palStatus_t pal_plat_handShake(palTLSHandle_t palTLSHandle, uint64_t *serverTime)
Perform the TLS handshake.
palStatus_t pal_plat_setTimeCB(palTLSHandle_t *palTLSHandle, palTimerCtx_t timerCtx, palSetTimer_f setTimer, palGetTimer_f getTimer)
Set the timer callbacks.
int(* palBIORecv_f)(palTLSSocketHandle_t socket, unsigned char *buf, size_t len)
Definition: pal_plat_TLS.h:65
palStatus_t pal_plat_setCipherSuites(palTLSConfHandle_t sslConf, palTLSSuites_t palSuite)
Set the supported cipher suites to the configuration context.
Definition: pal_TLS.h:48
int(* palGetTimer_f)(void *data)
Definition: pal_plat_TLS.h:68
uintptr_t palTLSConfHandle_t
Definition: pal_TLS.h:39
palStatus_t pal_plat_tlsSetSocket(palTLSConfHandle_t palTLSConf, palTLSSocket_t *socket)
Set the socket for the TLS configuration context.
palStatus_t pal_plat_SetLoggingCb(palTLSConfHandle_t palTLSConf, palLogFunc_f palLogFunction, void *logContext)
Set the logging function.
palStatus_t pal_plat_setPSK(palTLSConfHandle_t sslConf, const unsigned char *identity, uint32_t maxIdentityLenInBytes, const unsigned char *psk, uint32_t maxPskLenInBytes)
Set the Pre-Shared Key (PSK) and the expected identity name.
uintptr_t palTLSHandle_t
Definition: pal_TLS.h:38
void(* palLogFunc_f)(void *context, int debugLevel, const char *fileName, int line, const char *message)
Definition: pal_plat_TLS.h:69
palStatus_t pal_plat_sslSetIOCallBacks(palTLSConfHandle_t palTLSConf, palTLSSocket_t *palIOCtx, palBIOSend_f palBIOSend, palBIORecv_f palBIORecv)
Set the IO callbacks for the TLS context.
palStatus_t pal_plat_sslRead(palTLSHandle_t palTLSHandle, void *buffer, uint32_t len, uint32_t *actualLen)
Read at most 'len' application data bytes.
palStatus_t pal_plat_setCAChain(palTLSConfHandle_t palTLSConf, palX509_t *caChain, palX509CRL_t *caCRL)
Set the data required to verify a peer certificate.
The peer certificate is not verified. For client mode, this is insecure!
Definition: pal_plat_TLS.h:40
Definition: pal_plat_TLS.h:34
palDTLSSide
Definition: pal_plat_TLS.h:30
Definition: pal_plat_TLS.h:54
palStatus_t pal_plat_cleanupTLS(void)
Free resources for the TLS library.
enum palTLSAuthMode palTLSAuthMode_t
Server mode.
PAL TLS/DTLS. This file contains TLS and DTLS APIs and is a part of the PAL service API...
enum palTLSSuites palTLSSuites_t
This is the list of the available cipher suites.
Definition: pal_plat_TLS.h:51
void * palTimerCtx_t
Definition: pal_plat_TLS.h:60
palStatus_t pal_plat_setHandShakeTimeOut(palTLSConfHandle_t palTLSConf, uint32_t minTimeout, uint32_t maxTimeout)
Set the retransmit timeout values for the DTLS handshake. DTLS only, no effect on TLS...
The handshake continues even if the peer certificate verification fails.
Definition: pal_plat_TLS.h:41
enum palDTLSSide palDTLSSide_t
palStatus_t pal_plat_sslSetDebugging(palTLSConfHandle_t palTLSConf, uint8_t turnOn)
Turn the TLS library debugging on or off for the given configuration handle.
palStatus_t pal_plat_sslGetVerifyResultExtended(palTLSHandle_t palTLSHandle, int32_t *verifyResult)
Return the result of the certificate verification. The handshake API calls this.
void(* palSetTimer_f)(void *data, uint32_t intMs, uint32_t finMs)
Definition: pal_plat_TLS.h:67
palStatus_t pal_plat_initTLS(palTLSConfHandle_t palTLSConf, palTLSHandle_t *palTLSHandle)
Initiate a new TLS context.
Definition: pal_TLS.h:56
palTLSSuites
This is the list of the available cipher suites.
Definition: pal_plat_TLS.h:50
palStatus_t pal_plat_tlsConfigurationFree(palTLSConfHandle_t *palTLSConf)
Destroy and release resources for the TLS configuration context.
enum palTLSTranportMode palTLSTransportMode_t
palStatus_t pal_plat_setOwnPrivateKey(palTLSConfHandle_t palTLSConf, palPrivateKey_t *privateKey)
Set your own private key.
void(* palSocketCallback_f)(void *)
Definition: pal_TLS.h:75
palStatus_t pal_plat_freeTLS(palTLSHandle_t *palTLSHandle)
Destroy and release resources for the TLS context.
palTLSAuthMode
Server mode.
Definition: pal_plat_TLS.h:39
void pal_plat_SetDTLSSocketCallback(palTLSConfHandle_t palTLSConf, palSocketCallback_f cb, void *argument)
Set the socket callback.
void * palTLSSocketHandle_t
Definition: pal_plat_TLS.h:59
Definition: pal_plat_TLS.h:55
palStatus_t pal_plat_sslSetup(palTLSHandle_t palTLSHandle, palTLSConfHandle_t palTLSConf)
Set up a TLS context for use.
int(* palVerifyCallback_f)(void *, void *, int, uint32_t *)
Definition: pal_plat_TLS.h:66
The peer certificate verification MUST pass.
Definition: pal_plat_TLS.h:42
palStatus_t pal_plat_addEntropySource(palEntropySource_f entropyCallback)
Add an entropy source to the TLS/DTLS library.
Definition: pal_plat_TLS.h:53
int32_t palStatus_t
Definition: pal_types.h:55
palStatus_t pal_plat_sslWrite(palTLSHandle_t palTLSHandle, const void *buffer, uint32_t len, uint32_t *bytesWritten)
Try to write exactly 'len' application data bytes.
int(* palBIOSend_f)(palTLSSocketHandle_t socket, const unsigned char *buf, size_t len)
Definition: pal_plat_TLS.h:64
palStatus_t pal_plat_setAuthenticationMode(palTLSConfHandle_t sslConf, palTLSAuthMode_t authMode)
Set the certificate verification mode.
palStatus_t pal_plat_handShake_ping(palTLSHandle_t palTLSHandle)
Perform the TLS handshake ping.
Definition: pal_plat_TLS.h:52