Dtls.h

Go to the documentation of this file.

//
// Dtls
//
 
#ifndef __KINESIS_VIDEO_WEBRTC_CLIENT_DTLS_DTLS__
#define __KINESIS_VIDEO_WEBRTC_CLIENT_DTLS_DTLS__
 
#pragma once
 
#include "Tls.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define MAX_SRTP_MASTER_KEY_LEN   16
#define MAX_SRTP_SALT_KEY_LEN     14
#define MAX_DTLS_RANDOM_BYTES_LEN 32
#define MAX_DTLS_MASTER_KEY_LEN   48
 
#define GENERATED_CERTIFICATE_MAX_SIZE 4096
#define GENERATED_CERTIFICATE_BITS     2048
#define DTLS_CERT_MIN_SERIAL_NUM_SIZE  8
#define DTLS_CERT_MAX_SERIAL_NUM_SIZE  20
#define GENERATED_CERTIFICATE_DAYS     365
#define GENERATED_CERTIFICATE_NAME     "KVS-WebRTC-Client"
#define KEYING_EXTRACTOR_LABEL         "EXTRACTOR-dtls_srtp"
 
// All DTLS certificate fingerprints emitted and validated by this SDK use
// SHA-256 (see `dtlsCertificateFingerprint` in both Dtls_mbedtls.c and
// Dtls_openssl.c). The corresponding `a=fingerprint:` SDP attribute value is
// therefore prefixed by "sha-256 " (RFC 8122 §5).
#define DTLS_FINGERPRINT_SHA256_HASH_NAME  "sha-256"
#define DTLS_FINGERPRINT_SHA256_PREFIX     DTLS_FINGERPRINT_SHA256_HASH_NAME " "
#define DTLS_FINGERPRINT_SHA256_PREFIX_LEN (SIZEOF(DTLS_FINGERPRINT_SHA256_PREFIX) - 1)
 
/*
 * DTLS transmission interval timer (in 100ns)
 */
#define DTLS_TRANSMISSION_INTERVAL (200 * HUNDREDS_OF_NANOS_IN_A_MILLISECOND)
 
#define DTLS_SESSION_TIMER_START_DELAY (100 * HUNDREDS_OF_NANOS_IN_A_MILLISECOND)
 
#define SECONDS_IN_A_DAY (24 * 60 * 60LL)
 
#define HUNDREDS_OF_NANOS_IN_A_DAY (HUNDREDS_OF_NANOS_IN_AN_HOUR * 24LL)
 
typedef enum {
    RTC_DTLS_TRANSPORT_STATE_NEW,
    RTC_DTLS_TRANSPORT_STATE_CONNECTING, /* DTLS is in the process of negotiating a secure connection and verifying the remote fingerprint. */
    RTC_DTLS_TRANSPORT_STATE_CONNECTED,  /* DTLS has completed negotiation of a secure connection and verified the remote fingerprint. */
    RTC_DTLS_TRANSPORT_STATE_CLOSED,     /* The transport has been closed intentionally as the result of receipt of a close_notify alert */
    RTC_DTLS_TRANSPORT_STATE_FAILED,     /* The transport has failed as the result of an error */
} RTC_DTLS_TRANSPORT_STATE;
 
typedef enum {
    DTLS_STATE_HANDSHAKE_NEW,
    DTLS_STATE_HANDSHAKE_IN_PROGRESS,
    DTLS_STATE_HANDSHAKE_COMPLETED,
    DTLS_STATE_HANDSHAKE_ERROR,
} DTLS_HANDSHAKE_STATE;
 
/* Callback that is fired when Dtls Server wishes to send packet */
typedef VOID (*DtlsSessionOutboundPacketFunc)(UINT64, PBYTE, UINT32);
 
/*  Callback that is fired when Dtls state has changed */
typedef VOID (*DtlsSessionOnStateChange)(UINT64, RTC_DTLS_TRANSPORT_STATE);
 
typedef struct {
    UINT64 outBoundPacketFnCustomData;
    DtlsSessionOutboundPacketFunc outboundPacketFn;
    UINT64 stateChangeFnCustomData;
    DtlsSessionOnStateChange stateChangeFn;
} DtlsSessionCallbacks, *PDtlsSessionCallbacks;
 
typedef enum {
    DTLS_SESSION_VALIDATION_MODE_RELAXED,       /* Default peer DTLS flow. Identity is validated later via SDP fingerprint and is not
                                                 * recommended for production server certificate validation. */
    DTLS_SESSION_VALIDATION_MODE_STRICT_SERVER, /* Require the remote certificate chain and hostname to validate against
                                                 * pExpectedServerHostname and the configured CA bundle. */
} DTLS_SESSION_VALIDATION_MODE;
 
typedef struct {
    DTLS_SESSION_VALIDATION_MODE validationMode;
    PCHAR pExpectedServerHostname;
} DtlsSessionOptions, *PDtlsSessionOptions;
 
// DtlsKeyingMaterial is information extracted via https://tools.ietf.org/html/rfc5705
// also includes the use_srtp value from Handshake
typedef struct {
    BYTE clientWriteKey[MAX_SRTP_MASTER_KEY_LEN + MAX_SRTP_SALT_KEY_LEN];
    BYTE serverWriteKey[MAX_SRTP_MASTER_KEY_LEN + MAX_SRTP_SALT_KEY_LEN];
    UINT8 key_length;
 
    KVS_SRTP_PROFILE srtpProfile;
} DtlsKeyingMaterial, *PDtlsKeyingMaterial;
 
#ifdef KVS_USE_OPENSSL
typedef struct {
    BOOL created;
    X509* pCert;
    EVP_PKEY* pKey;
} DtlsSessionCertificateInfo, *PDtlsSessionCertificateInfo;
 
#elif KVS_USE_MBEDTLS
typedef struct {
    mbedtls_x509_crt cert;
    mbedtls_pk_context privateKey;
    CHAR fingerprint[CERTIFICATE_FINGERPRINT_LENGTH + 1];
} DtlsSessionCertificateInfo, *PDtlsSessionCertificateInfo;
 
typedef struct {
    UINT64 updatedTime;
    UINT32 intermediateDelay, finalDelay;
} DtlsSessionTimer, *PDtlsSessionTimer;
 
typedef struct {
    BYTE masterSecret[MAX_DTLS_MASTER_KEY_LEN];
    // client random bytes + server random bytes
    BYTE randBytes[2 * MAX_DTLS_RANDOM_BYTES_LEN];
    mbedtls_tls_prf_types tlsProfile;
} TlsKeys, *PTlsKeys;
 
// mbedTLS 4 takes its RNG from PSA, so sessions keep no DRBG of their own
#if MBEDTLS_VERSION_MAJOR < 4
#define KVS_MBEDTLS_DRBG(pSession) (&(pSession)->ctrDrbg)
#else
#define KVS_MBEDTLS_DRBG(pSession) (NULL)
#endif
#else
#error "A Crypto implementation is required."
#endif
 
typedef struct __DtlsSession DtlsSession, *PDtlsSession;
struct __DtlsSession {
    volatile ATOMIC_BOOL isStarted;
    volatile ATOMIC_BOOL isShutdown;
    volatile ATOMIC_BOOL isCleanUp;
    UINT32 certificateCount;
    DtlsSessionCallbacks dtlsSessionCallbacks;
    TIMER_QUEUE_HANDLE timerQueueHandle;
    UINT32 timerId;
    UINT64 dtlsSessionStartTime;
    UINT64 dtlsSessionSetupTime;
    RTC_DTLS_TRANSPORT_STATE state;
    DTLS_HANDSHAKE_STATE handshakeState;
    MUTEX sslLock;
    volatile ATOMIC_BOOL remoteCertVerificationFailed;
    DTLS_SESSION_VALIDATION_MODE validationMode;
    PCHAR pExpectedServerHostname;
 
#ifdef KVS_USE_OPENSSL
    volatile ATOMIC_BOOL sslInitFinished;
    volatile SIZE_T objRefCount;
    CVAR receivePacketCvar;
    // dtls message must fit into a UDP packet
    BYTE outgoingDataBuffer[MAX_UDP_PACKET_SIZE];
    UINT32 outgoingDataLen;
    CHAR certFingerprints[MAX_RTCCONFIGURATION_CERTIFICATES][CERTIFICATE_FINGERPRINT_LENGTH + 1];
    SSL_CTX* pSslCtx;
    SSL* pSsl;
#elif KVS_USE_MBEDTLS
    DtlsSessionTimer transmissionTimer;
    TlsKeys tlsKeys;
    PIOBuffer pReadBuffer;
 
#if MBEDTLS_VERSION_MAJOR < 4
    mbedtls_entropy_context entropy;
    mbedtls_ctr_drbg_context ctrDrbg;
#endif
    mbedtls_ssl_config sslCtxConfig;
    mbedtls_ssl_context sslCtx;
    mbedtls_x509_crt trustedCaCert;
    DtlsSessionCertificateInfo certificates[MAX_RTCCONFIGURATION_CERTIFICATES];
#else
#error "A Crypto implementation is required."
#endif
};

STATUS createDtlsSession(PDtlsSessionCallbacks, TIMER_QUEUE_HANDLE, INT32, BOOL, PRtcCertificate, PDtlsSession*);
STATUS createDtlsSessionWithOptions(PDtlsSessionCallbacks, TIMER_QUEUE_HANDLE, INT32, BOOL, PRtcCertificate, PDtlsSessionOptions, PDtlsSession*);

STATUS freeDtlsSession(PDtlsSession*);

STATUS dtlsSessionStart(PDtlsSession, BOOL);
STATUS dtlsSessionProcessPacket(PDtlsSession, PBYTE, PINT32);
STATUS dtlsSessionIsInitFinished(PDtlsSession, PBOOL);
STATUS dtlsSessionPopulateKeyingMaterial(PDtlsSession, PDtlsKeyingMaterial);
STATUS dtlsSessionGetLocalCertificateFingerprint(PDtlsSession, PCHAR, UINT32);
STATUS dtlsSessionVerifyRemoteCertificateFingerprint(PDtlsSession, PCHAR);
STATUS dtlsSessionPutApplicationData(PDtlsSession, PBYTE, INT32);
STATUS dtlsSessionShutdown(PDtlsSession);
 
STATUS dtlsSessionOnOutBoundData(PDtlsSession, UINT64, DtlsSessionOutboundPacketFunc);
STATUS dtlsSessionOnStateChange(PDtlsSession, UINT64, DtlsSessionOnStateChange);
STATUS dtlsSessionHandshakeInThread(PDtlsSession, BOOL);
 
/******** Internal Functions **********/
STATUS dtlsValidateRtcCertificates(PRtcCertificate, PUINT32);
STATUS dtlsSessionChangeState(PDtlsSession, RTC_DTLS_TRANSPORT_STATE);
STATUS dtlsSessionCopyOptions(PDtlsSession, PDtlsSessionOptions);
 
STATUS dtlsFillPseudoRandomBits(PBYTE, UINT32);
 
#ifdef KVS_USE_OPENSSL
STATUS dtlsCheckOutgoingDataBuffer(PDtlsSession);
STATUS dtlsCertificateFingerprint(X509*, PCHAR);
STATUS dtlsGenerateCertificateFingerprints(PDtlsSession, PDtlsSessionCertificateInfo);
STATUS createCertificateAndKey(INT32, BOOL, X509** ppCert, EVP_PKEY** ppPkey);
STATUS freeCertificateAndKey(X509** ppCert, EVP_PKEY** ppPkey);
STATUS dtlsValidateRtcCertificates(PRtcCertificate, PUINT32);
STATUS createSslCtx(PDtlsSessionCertificateInfo, UINT32, SSL_CTX**);
#elif KVS_USE_MBEDTLS
STATUS dtlsCertificateFingerprint(mbedtls_x509_crt*, PCHAR);
STATUS copyCertificateAndKey(mbedtls_x509_crt*, mbedtls_pk_context*, PDtlsSessionCertificateInfo, mbedtls_ctr_drbg_context*);
STATUS createCertificateAndKey(INT32, BOOL, mbedtls_x509_crt*, mbedtls_pk_context*);
STATUS freeCertificateAndKey(mbedtls_x509_crt*, mbedtls_pk_context*);
 
// following are required callbacks for mbedtls
// NOTE: const is not a pure C qualifier, they're here because there's no way to type cast
//       a callback signature.
INT32 dtlsSessionSendCallback(PVOID, const unsigned char*, ULONG);
INT32 dtlsSessionReceiveCallback(PVOID, unsigned char*, ULONG);
VOID dtlsSessionSetTimerCallback(PVOID, UINT32, UINT32);
INT32 dtlsSessionGetTimerCallback(PVOID);
 
#if MBEDTLS_BEFORE_V3
INT32 dtlsSessionKeyDerivationCallback(PVOID, const unsigned char*, const unsigned char*, ULONG, ULONG, ULONG,
                                       const unsigned char[MAX_DTLS_RANDOM_BYTES_LEN], const unsigned char[MAX_DTLS_RANDOM_BYTES_LEN],
                                       mbedtls_tls_prf_types);
#elif !MBEDTLS_V4_OR_LATER
VOID dtlsSessionKeyDerivationCallback(PVOID customData, mbedtls_ssl_key_export_type secret_type, const unsigned char* pMasterSecret,
                                      size_t pMasterSecretLen, const unsigned char clientRandom[MAX_DTLS_RANDOM_BYTES_LEN],
                                      const unsigned char serverRandom[MAX_DTLS_RANDOM_BYTES_LEN], mbedtls_tls_prf_types tlsProfile);
#endif
/* mbedTLS 4 uses mbedtls_ssl_export_keying_material() in dtlsSessionPopulateKeyingMaterial(),
 * so no key-derivation callback is needed. */
 
#else
#error "A Crypto implementation is required."
#endif
 
#ifdef __cplusplus
}
#endif
#endif //__KINESIS_VIDEO_WEBRTC_CLIENT_DTLS_DTLS__