Amazon Kinesis Webrtc C SDK
Dtls.h
Go to the documentation of this file.
1 //
2 // Dtls
3 //
4 
5 #ifndef __KINESIS_VIDEO_WEBRTC_CLIENT_DTLS_DTLS__
6 #define __KINESIS_VIDEO_WEBRTC_CLIENT_DTLS_DTLS__
7 
8 #pragma once
9 
10 #ifdef __cplusplus
11 extern "C" {
12 #endif
13 
14 #define MAX_SRTP_MASTER_KEY_LEN 16
15 #define MAX_SRTP_SALT_KEY_LEN 14
16 #define MAX_DTLS_RANDOM_BYTES_LEN 32
17 #define MAX_DTLS_MASTER_KEY_LEN 48
18 
19 #define GENERATED_CERTIFICATE_MAX_SIZE 4096
20 #define GENERATED_CERTIFICATE_BITS 2048
21 #define DTLS_CERT_MIN_SERIAL_NUM_SIZE 8
22 #define DTLS_CERT_MAX_SERIAL_NUM_SIZE 20
23 #define GENERATED_CERTIFICATE_DAYS 365
24 #define GENERATED_CERTIFICATE_NAME "KVS-WebRTC-Client"
25 #define KEYING_EXTRACTOR_LABEL "EXTRACTOR-dtls_srtp"
26 
27 /*
28  * DTLS transmission interval timer (in 100ns)
29  */
30 #define DTLS_TRANSMISSION_INTERVAL (200 * HUNDREDS_OF_NANOS_IN_A_MILLISECOND)
31 
32 #define DTLS_SESSION_TIMER_START_DELAY (100 * HUNDREDS_OF_NANOS_IN_A_MILLISECOND)
33 
34 #define SECONDS_IN_A_DAY (24 * 60 * 60LL)
35 
36 #define HUNDREDS_OF_NANOS_IN_A_DAY (HUNDREDS_OF_NANOS_IN_AN_HOUR * 24LL)
37 
38 typedef enum {
40  RTC_DTLS_TRANSPORT_STATE_CONNECTING, /* DTLS is in the process of negotiating a secure connection and verifying the remote fingerprint. */
41  RTC_DTLS_TRANSPORT_STATE_CONNECTED, /* DTLS has completed negotiation of a secure connection and verified the remote fingerprint. */
42  RTC_DTLS_TRANSPORT_STATE_CLOSED, /* The transport has been closed intentionally as the result of receipt of a close_notify alert */
43  RTC_DTLS_TRANSPORT_STATE_FAILED, /* The transport has failed as the result of an error */
45 
46 typedef enum {
52 
53 /* Callback that is fired when Dtls Server wishes to send packet */
54 typedef VOID (*DtlsSessionOutboundPacketFunc)(UINT64, PBYTE, UINT32);
55 
56 /* Callback that is fired when Dtls state has changed */
58 
59 typedef struct {
65 
66 // DtlsKeyingMaterial is information extracted via https://tools.ietf.org/html/rfc5705
67 // also includes the use_srtp value from Handshake
68 typedef struct {
71  UINT8 key_length;
72 
73  KVS_SRTP_PROFILE srtpProfile;
75 
76 #ifdef KVS_USE_OPENSSL
77 typedef struct {
78  BOOL created;
79  X509* pCert;
80  EVP_PKEY* pKey;
81 } DtlsSessionCertificateInfo, *PDtlsSessionCertificateInfo;
82 
83 #elif KVS_USE_MBEDTLS
84 typedef struct {
85  mbedtls_x509_crt cert;
86  mbedtls_pk_context privateKey;
87  CHAR fingerprint[CERTIFICATE_FINGERPRINT_LENGTH + 1];
88 } DtlsSessionCertificateInfo, *PDtlsSessionCertificateInfo;
89 
90 typedef struct {
91  UINT64 updatedTime;
92  UINT32 intermediateDelay, finalDelay;
93 } DtlsSessionTimer, *PDtlsSessionTimer;
94 
95 typedef struct {
96  BYTE masterSecret[MAX_DTLS_MASTER_KEY_LEN];
97  // client random bytes + server random bytes
98  BYTE randBytes[2 * MAX_DTLS_RANDOM_BYTES_LEN];
99  mbedtls_tls_prf_types tlsProfile;
100 } TlsKeys, *PTlsKeys;
101 #else
102 #error "A Crypto implementation is required."
103 #endif
104 
107  volatile ATOMIC_BOOL isStarted;
108  volatile ATOMIC_BOOL isShutdown;
109  volatile ATOMIC_BOOL isCleanUp;
112  TIMER_QUEUE_HANDLE timerQueueHandle;
113  UINT32 timerId;
118  MUTEX sslLock;
119 
120 #ifdef KVS_USE_OPENSSL
121  volatile ATOMIC_BOOL sslInitFinished;
122  volatile SIZE_T objRefCount;
123  CVAR receivePacketCvar;
124  // dtls message must fit into a UDP packet
125  BYTE outgoingDataBuffer[MAX_UDP_PACKET_SIZE];
126  UINT32 outgoingDataLen;
128  SSL_CTX* pSslCtx;
129  SSL* pSsl;
130 #elif KVS_USE_MBEDTLS
131  DtlsSessionTimer transmissionTimer;
132  TlsKeys tlsKeys;
133  PIOBuffer pReadBuffer;
134 
135  mbedtls_entropy_context entropy;
136  mbedtls_ctr_drbg_context ctrDrbg;
137  mbedtls_ssl_config sslCtxConfig;
138  mbedtls_ssl_context sslCtx;
139  DtlsSessionCertificateInfo certificates[MAX_RTCCONFIGURATION_CERTIFICATES];
140 #else
141 #error "A Crypto implementation is required."
142 #endif
143 };
144 
156 STATUS createDtlsSession(PDtlsSessionCallbacks, TIMER_QUEUE_HANDLE, INT32, BOOL, PRtcCertificate, PDtlsSession*);
157 
164 
171 STATUS dtlsSessionStart(PDtlsSession, BOOL);
172 STATUS dtlsSessionProcessPacket(PDtlsSession, PBYTE, PINT32);
177 STATUS dtlsSessionPutApplicationData(PDtlsSession, PBYTE, INT32);
179 
183 
184 /******** Internal Functions **********/
187 
188 STATUS dtlsFillPseudoRandomBits(PBYTE, UINT32);
189 
190 #ifdef KVS_USE_OPENSSL
192 STATUS dtlsCertificateFingerprint(X509*, PCHAR);
193 STATUS dtlsGenerateCertificateFingerprints(PDtlsSession, PDtlsSessionCertificateInfo);
194 STATUS createCertificateAndKey(INT32, BOOL, X509** ppCert, EVP_PKEY** ppPkey);
195 STATUS freeCertificateAndKey(X509** ppCert, EVP_PKEY** ppPkey);
197 STATUS createSslCtx(PDtlsSessionCertificateInfo, UINT32, SSL_CTX**);
198 #elif KVS_USE_MBEDTLS
199 STATUS dtlsCertificateFingerprint(mbedtls_x509_crt*, PCHAR);
200 STATUS copyCertificateAndKey(mbedtls_x509_crt*, mbedtls_pk_context*, PDtlsSessionCertificateInfo);
201 STATUS createCertificateAndKey(INT32, BOOL, mbedtls_x509_crt*, mbedtls_pk_context*);
202 STATUS freeCertificateAndKey(mbedtls_x509_crt*, mbedtls_pk_context*);
203 
204 // following are required callbacks for mbedtls
205 // NOTE: const is not a pure C qualifier, they're here because there's no way to type cast
206 // a callback signature.
207 INT32 dtlsSessionSendCallback(PVOID, const unsigned char*, ULONG);
208 INT32 dtlsSessionReceiveCallback(PVOID, unsigned char*, ULONG);
209 VOID dtlsSessionSetTimerCallback(PVOID, UINT32, UINT32);
210 INT32 dtlsSessionGetTimerCallback(PVOID);
211 INT32 dtlsSessionKeyDerivationCallback(PVOID, const unsigned char*, const unsigned char*, ULONG, ULONG, ULONG,
212  const unsigned char[MAX_DTLS_RANDOM_BYTES_LEN], const unsigned char[MAX_DTLS_RANDOM_BYTES_LEN],
213  mbedtls_tls_prf_types);
214 #else
215 #error "A Crypto implementation is required."
216 #endif
217 
218 #ifdef __cplusplus
219 }
220 #endif
221 #endif //__KINESIS_VIDEO_WEBRTC_CLIENT_DTLS_DTLS__
STATUS dtlsFillPseudoRandomBits(PBYTE, UINT32)
Definition: Dtls.c:88
DTLS_HANDSHAKE_STATE
Definition: Dtls.h:46
@ DTLS_STATE_HANDSHAKE_ERROR
Definition: Dtls.h:50
@ DTLS_STATE_HANDSHAKE_COMPLETED
Definition: Dtls.h:49
@ DTLS_STATE_HANDSHAKE_IN_PROGRESS
Definition: Dtls.h:48
@ DTLS_STATE_HANDSHAKE_NEW
Definition: Dtls.h:47
VOID(* DtlsSessionOnStateChange)(UINT64, RTC_DTLS_TRANSPORT_STATE)
Definition: Dtls.h:57
struct __DtlsSession * PDtlsSession
Definition: Dtls.h:105
STATUS dtlsSessionVerifyRemoteCertificateFingerprint(PDtlsSession, PCHAR)
Definition: Dtls_mbedtls.c:447
#define MAX_SRTP_MASTER_KEY_LEN
Definition: Dtls.h:14
STATUS dtlsSessionPopulateKeyingMaterial(PDtlsSession, PDtlsKeyingMaterial)
Definition: Dtls_mbedtls.c:474
STATUS dtlsSessionGetLocalCertificateFingerprint(PDtlsSession, PCHAR, UINT32)
Definition: Dtls_mbedtls.c:423
#define MAX_SRTP_SALT_KEY_LEN
Definition: Dtls.h:15
STATUS dtlsSessionChangeState(PDtlsSession, RTC_DTLS_TRANSPORT_STATE)
Definition: Dtls.c:62
#define MAX_DTLS_MASTER_KEY_LEN
Definition: Dtls.h:17
struct DtlsSessionCallbacks * PDtlsSessionCallbacks
struct DtlsKeyingMaterial * PDtlsKeyingMaterial
STATUS dtlsSessionProcessPacket(PDtlsSession, PBYTE, PINT32)
Definition: Dtls_mbedtls.c:325
#define MAX_DTLS_RANDOM_BYTES_LEN
Definition: Dtls.h:16
RTC_DTLS_TRANSPORT_STATE
Definition: Dtls.h:38
@ RTC_DTLS_TRANSPORT_STATE_CLOSED
Definition: Dtls.h:42
@ RTC_DTLS_TRANSPORT_STATE_CONNECTING
Definition: Dtls.h:40
@ RTC_DTLS_TRANSPORT_STATE_NEW
Definition: Dtls.h:39
@ RTC_DTLS_TRANSPORT_STATE_FAILED
Definition: Dtls.h:43
@ RTC_DTLS_TRANSPORT_STATE_CONNECTED
Definition: Dtls.h:41
STATUS dtlsSessionStart(PDtlsSession, BOOL)
Definition: Dtls_mbedtls.c:257
STATUS dtlsSessionShutdown(PDtlsSession)
Definition: Dtls_mbedtls.c:528
STATUS dtlsValidateRtcCertificates(PRtcCertificate, PUINT32)
Definition: Dtls.c:36
STATUS createDtlsSession(PDtlsSessionCallbacks, TIMER_QUEUE_HANDLE, INT32, BOOL, PRtcCertificate, PDtlsSession *)
Definition: Dtls_mbedtls.c:11
STATUS dtlsSessionIsInitFinished(PDtlsSession, PBOOL)
Definition: Dtls_mbedtls.c:311
STATUS dtlsSessionOnOutBoundData(PDtlsSession, UINT64, DtlsSessionOutboundPacketFunc)
Definition: Dtls.c:4
STATUS dtlsSessionPutApplicationData(PDtlsSession, PBYTE, INT32)
Definition: Dtls_mbedtls.c:383
VOID(* DtlsSessionOutboundPacketFunc)(UINT64, PBYTE, UINT32)
Definition: Dtls.h:54
STATUS dtlsSessionOnStateChange(PDtlsSession, UINT64, DtlsSessionOnStateChange)
Definition: Dtls.c:19
STATUS freeDtlsSession(PDtlsSession *)
Definition: Dtls_mbedtls.c:75
STATUS dtlsSessionHandshakeInThread(PDtlsSession, BOOL)
Definition: Dtls_mbedtls.c:251
INT32 dtlsSessionReceiveCallback(PVOID customData, unsigned char *pBuf, ULONG len)
Definition: Dtls_mbedtls.c:125
INT32 dtlsSessionGetTimerCallback(PVOID customData)
Definition: Dtls_mbedtls.c:170
VOID dtlsSessionSetTimerCallback(PVOID customData, UINT32 intermediateDelayInMs, UINT32 finalDelayInMs)
Definition: Dtls_mbedtls.c:148
STATUS freeCertificateAndKey(mbedtls_x509_crt *pCert, mbedtls_pk_context *pKey)
Definition: Dtls_mbedtls.c:705
INT32 dtlsSessionSendCallback(PVOID customData, const unsigned char *pBuf, ULONG len)
Definition: Dtls_mbedtls.c:112
STATUS dtlsCertificateFingerprint(mbedtls_x509_crt *pCert, PCHAR pBuff)
Definition: Dtls_mbedtls.c:721
INT32 dtlsSessionKeyDerivationCallback(PVOID customData, const unsigned char *pMasterSecret, const unsigned char *pKeyBlock, ULONG maclen, ULONG keylen, ULONG ivlen, const unsigned char clientRandom[32], const unsigned char serverRandom[32], mbedtls_tls_prf_types tlsProfile)
Definition: Dtls_mbedtls.c:232
STATUS copyCertificateAndKey(mbedtls_x509_crt *pCert, mbedtls_pk_context *pKey, PDtlsSessionCertificateInfo pDst)
Definition: Dtls_mbedtls.c:557
STATUS createCertificateAndKey(INT32 certificateBits, BOOL generateRSACertificate, mbedtls_x509_crt *pCert, mbedtls_pk_context *pKey)
Definition: Dtls_mbedtls.c:606
STATUS dtlsGenerateCertificateFingerprints(PDtlsSession pDtlsSession, PDtlsSessionCertificateInfo pDtlsSessionCertificateInfo)
Definition: Dtls_openssl.c:366
STATUS dtlsCheckOutgoingDataBuffer(PDtlsSession pDtlsSession)
Definition: Dtls_openssl.c:756
STATUS createSslCtx(PDtlsSessionCertificateInfo pCertificates, UINT32 certCount, SSL_CTX **ppSslCtx)
Definition: Dtls_openssl.c:167
#define MAX_UDP_PACKET_SIZE
Definition: Include_i.h:92
#define CERTIFICATE_FINGERPRINT_LENGTH
Definition: Include_i.h:90
#define MAX_RTCCONFIGURATION_CERTIFICATES
Definition: Include.h:496
Definition: Dtls.h:68
KVS_SRTP_PROFILE srtpProfile
Definition: Dtls.h:73
UINT8 key_length
Definition: Dtls.h:71
Definition: Dtls.h:59
DtlsSessionOutboundPacketFunc outboundPacketFn
Definition: Dtls.h:61
DtlsSessionOnStateChange stateChangeFn
Definition: Dtls.h:63
UINT64 outBoundPacketFnCustomData
Definition: Dtls.h:60
UINT64 stateChangeFnCustomData
Definition: Dtls.h:62
Specifies the certificate and the private key used by the certificate. The Certificates are in the fo...
Definition: Include.h:1149
Definition: Dtls.h:106
TIMER_QUEUE_HANDLE timerQueueHandle
Definition: Dtls.h:112
UINT64 dtlsSessionSetupTime
Definition: Dtls.h:115
RTC_DTLS_TRANSPORT_STATE state
Definition: Dtls.h:116
UINT32 timerId
Definition: Dtls.h:113
volatile ATOMIC_BOOL isStarted
Definition: Dtls.h:107
DTLS_HANDSHAKE_STATE handshakeState
Definition: Dtls.h:117
UINT32 certificateCount
Definition: Dtls.h:110
UINT64 dtlsSessionStartTime
Definition: Dtls.h:114
volatile ATOMIC_BOOL isCleanUp
Definition: Dtls.h:109
MUTEX sslLock
Definition: Dtls.h:118
volatile ATOMIC_BOOL isShutdown
Definition: Dtls.h:108
DtlsSessionCallbacks dtlsSessionCallbacks
Definition: Dtls.h:111
Definition: IOBuffer.h:11