**WebRTC Nuts and Bolts**
[](https://www.linkedin.com/in/alper-dalkiran/)
[](https://twitter.com/aalperdalkiran)
@@ -14,9 +13,7 @@ You can track which steps taken during this journey by debugging or tracking the
-- ## **3.1. Initialization of RTC object** -
In the constructor of the *RTC* class, calls the "createLocalPeerConnection" function which creates a [RTCPeerConnection](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection), which represents a connection between the local device and a remote peer. This is a native browser API object. @@ -43,6 +41,7 @@ The [constructor of *RTCPeerConnection*](https://developer.mozilla.org/en-US/doc We assign some event handlers for some events, which we will discuss further. We assign handlers to some of them only to print to console, to be informed: "This event was fired". from [ui/src/app.ts](../ui/src/app.ts) + ```ts ... createLocalPeerConnection() { @@ -86,22 +85,18 @@ We assign some event handlers for some events, which we will discuss further. We ... ``` -
- ## **3.2. Let the show begin!** -
We discussed lots of boring stuff so far (unfortunately there is more)... Now, we click on the "Create PeerConnection" button to start the show! -
- ### **3.2.1 Creating streams, connecting to Signaling Server WebSocket** -
The button click will call "rtc.start()" function which: + * Calls "createLocalTracks" method, that says to the browser, "I want a video stream of default webcam, if it can be, should be in height 720p, also I want an audio stream of default microphone". The browser returns a [Promise<MediaStream>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), which we should wait for asking for permissions and (if available and permitted) initialization of camera and microphone devices. from [ui/src/app.ts](../ui/src/app.ts) + ```ts createLocalTracks(): Promise
- ### **3.2.2 The Signaling Server welcomes the client** -
When we make the first contact with the backend WebSocket with connecting, "serveWs" function in [backend/src/signaling/httpserver.go](../backend/src/signaling/httpserver.go) will be triggered. This function creates a WsClient object (defined in [backend/src/signaling/wsclient.go](../backend/src/signaling/wsclient.go)) and it forwards to the wsHub's "register" [channel](https://go.dev/tour/concurrency/2). This channel is listened by run() function of WsHub object, shown below: from [backend/src/signaling/httpserver.go](../backend/src/signaling/httpserver.go) + ```go func (s *HttpServer) serveWs(w http.ResponseWriter, r *http.Request) { ... @@ -196,6 +191,7 @@ func (s *HttpServer) serveWs(w http.ResponseWriter, r *http.Request) { This method in an infinite loop, when a message forwarded to "register" channel, it registers the new incoming client object itself, and sends a "ClientWelcomeMessage" with message type "Welcome". from [backend/src/signaling/wshub.go](../backend/src/signaling/wshub.go) + ```go func (h *WsHub) run() { for { @@ -216,10 +212,7 @@ func (h *WsHub) run() { } ``` -
- ### **3.2.3 The client receives the *Welcome* message of Signaling Server, then sends *JoinConference* request** -
When any data is received by the WebSocket client, the "ws.onmessage" event will be fired. @@ -228,6 +221,7 @@ When any data is received by the WebSocket client, the "ws.onmessage" event will The "Welcome message" coming from the server is processed by switch case for "Welcome" "data.type". The code below sends a JSON message that says "I want to join the conference named 'defaultConference'". Generated and sent JSON: + ```json { "type": "JoinConference", @@ -238,6 +232,7 @@ The "Welcome message" coming from the server is processed by switch case for "We ``` from [ui/src/app.ts](../ui/src/app.ts) + ```ts this.ws.onmessage = (message) => { const data = message.data ? JSON.parse(message.data) : null; @@ -257,14 +252,13 @@ The "Welcome message" coming from the server is processed by switch case for "We } ``` -
- ### **3.2.4 The client receives the *Welcome* message of Signaling Server, sends *JoinConference* request, then server sends SDP Offer** -
This method in an infinite loop, when a message forwarded to "messageReceived" channel, it [Unmarshalls](https://pkg.go.dev/encoding/json#Unmarshal) it, looks the type attribute of the JSON.
+ If it is "JoinConference": + * It calls "processJoinConference" function of WsHub object. * After, "EnsureConference" function in [backend/src/conference/conferencemanager.go](../backend/src/conference/conferencemanager.go) is called to create a conference object if not exists.
@@ -273,12 +267,13 @@ This function calls "NewConference", which creates a conference object and a new This agent will store signaled SDP data and UDP sockets related with the conference. Every ICE Agent has a unique Ufrag and Pwd string, which randomly generated while creating the instance. This Ufrag and Pwd data will be sent to the client inside SDP Offer.
-**Note:** By these Conference and ServerAgent objects per conference, we are able to manage multiple different conference rooms, but in this sample project we use only one conference name "defaultConference", and it doesn't count as a complete conference anyways :) +**Note:** By these Conference and ServerAgent objects per conference, we are able to manage multiple different conference rooms, but in this sample project we use only one conference name "defaultConference", and it doesn't count as a complete conference anyways :blush: * Then, "GenerateSdpOffer" function in [backend/src/sdp/sdp.go](../backend/src/sdp/sdp.go) is called to create an SDP Offer data, containing media types, ICE candidates' IP and port data, etc...
The generated SDP Offer data is sent to the client as JSON via Signaling WebSocket. from [backend/src/conference/conference.go](../backend/src/conference/conference.go) + ```go func NewConference(conferenceName string, candidateIPs []string, udpPort int) *Conference { result := &Conference{ @@ -290,6 +285,7 @@ func NewConference(conferenceName string, candidateIPs []string, udpPort int) *C ``` from [backend/src/signaling/wshub.go](../backend/src/signaling/wshub.go) + ```go func (h *WsHub) run() { for { @@ -313,10 +309,7 @@ During this process, our server console will be similar to this:  -
- ### **3.2.5 The client receives the *SdpOffer* message of Signaling Server** -
When any data was received by the WebSocket client, the "ws.onmessage" event will be fired. @@ -327,6 +320,7 @@ The "SDP Offer message" coming from the server is processed by switch case for " * This message came as JSON, we need to convert it to [SDP format](https://en.wikipedia.org/wiki/Session_Description_Protocol) via [sdp-transform](https://www.npmjs.com/package/sdp-transform) library. from [ui/src/app.ts](../ui/src/app.ts) + ```ts this.ws.onmessage = (message) => { ... @@ -395,6 +389,7 @@ The "SDP Offer message" coming from the server is processed by switch case for " } } ``` + * The JSON message converted to the SDP format as:  @@ -402,6 +397,7 @@ The "SDP Offer message" coming from the server is processed by switch case for " * We give the SDP Offer string to "acceptOffer" function of our *RTC* object. This function calls [setRemoteDescription](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/setRemoteDescription) function of our RTCPeerConnection object. By this, we say our the localConnection (RTCPeerConnection) that "You fired the 'onnegotiationneeded' event and wanted us to SDP Offer/Answer negotiation, we did it and please take it then create an SDP Answer for us". from [ui/src/app.ts](../ui/src/app.ts) + ```ts acceptOffer(offerSdp: string) { return this.localConnection.setRemoteDescription({ @@ -434,22 +430,22 @@ The "SDP Offer message" coming from the server is processed by switch case for " * On onicecandidate event fired when our localConnection object's iceGatheringState value comes 'complete', it's time to parse *localConnection.localDescription.sdp* value (generated SDP Answer above), give it to "sendSdpToSignaling" function, converts this SDP Answer to JSON and sends to the client via Signaling. from [ui/src/app.ts](../ui/src/app.ts) + ```ts sendSdpToSignaling(parsedSdp: sdpTransform.SessionDescription) { console.log('sendSdpToSignaling', parsedSdp); signaling.ws.send(JSON.stringify({type: "SdpOfferAnswer", data: parsedSdp})); } ``` - -
+ ### **3.2.6 The server receives the *SdpAnswer* message of Signaling Server** -
The client generated the SDP Answer corresponding to the SDP Offer the server sent. Then we forward it to ConferenceManager's ChanSdpOffer channel. from [backend/src/signaling/wshub.go](../backend/src/signaling/wshub.go) + ```go func (h *WsHub) run() { for { @@ -474,6 +470,7 @@ func (h *WsHub) run() { This method in an infinite loop, when a message forwarded to "ChanSdpOffer" channel, it loops over the incoming SDP Answer's media items, gives items to "EnsureSignalingMediaComponent" function of ServerAgent in [backend/src/agent/serveragent.go](../backend/src/agent/serveragent.go). This function creates SignalingMediaComponent objects per media item, then adds them to "SignalingMediaComponents" property of the ServerAgent. When UDP connection started, the UDP listener compares the ICE information coming from UDP and previously came "SignalingMediaComponents" via Signaling. from [backend/src/conference/conferencemanager.go](../backend/src/conference/conferencemanager.go) + ```go func (m *ConferenceManager) Run(waitGroup *sync.WaitGroup) { defer waitGroup.Done() diff --git a/docs/04-STUN-BINDING-REQUEST-FROM-CLIENT.md b/docs/04-STUN-BINDING-REQUEST-FROM-CLIENT.md index 6e86123..f7a2875 100644 --- a/docs/04-STUN-BINDING-REQUEST-FROM-CLIENT.md +++ b/docs/04-STUN-BINDING-REQUEST-FROM-CLIENT.md @@ -1,6 +1,7 @@ # **4. STUN BINDING REQUEST FROM CLIENT** In previous chapters: + * The client joined the conference room * Initialized webcam and microphone devices, created media stream, video and audio tracks * The client and the server exchanged SDP Offer and Answer via Signaling WebSocket @@ -8,10 +9,7 @@ In previous chapters: Note: For detailed information about STUN Protocol, you can find at "2.4.2. Implementing STUN Protocol (as Client)" chapter in [2. BACKEND INITIALIZATION](./02-BACKEND-INITIALIZATION.md) -
- ## **4.1. UDP Demultiplexing** -
First of all, this is our first "expected" packet incoming via UDP. " Demultiplexing" mechanism on sockets are implemented in a different (well architected) way, but in this project, we implemented the plain way. Let's explain our demultiplexing mechanism: @@ -21,6 +19,7 @@ First of all, this is our first "expected" packet incoming via UDP. " Demultiple * The "AddBuffer" function checks which protocol the packet can be related with: from [backend/src/agent/udpclientsocket.go](../backend/src/agent/udpclientsocket.go) + ```go func (ms *UDPClientSocket) AddBuffer(buf []byte, offset int, arrayLen int) { logging.Descf(logging.ProtoUDP, "A packet received. The byte array (%d bytes) not parsed yet. Demultiplexing via if-else blocks.", arrayLen) @@ -44,22 +43,25 @@ func (ms *UDPClientSocket) AddBuffer(buf []byte, offset int, arrayLen int) { ``` In this context, we can check out stun.IsMessage function. This function checks: - * Data length (arrayLen) is greater than messageHeaderSize (20 bytes) -
and - * 4 bytes after 4. byte (between 4. and 8. indices) equals to STUN magicCookie (constant value, 0x2112A442). + +* Data length (arrayLen) is greater than messageHeaderSize (20 bytes) +
and +* 4 bytes after 4. byte (between 4. and 8. indices) equals to STUN magicCookie (constant value, 0x2112A442). If this buffer part complies with these conditions, we can say "this packet is a STUN protocol packet", then we can process it with STUN protocol's methods. from [backend/src/stun/message.go](../backend/src/stun/message.go) + ```go func IsMessage(buf []byte, offset int, arrayLen int) bool { return arrayLen >= messageHeaderSize && binary.BigEndian.Uint32(buf[offset+4:offset+8]) == magicCookie } ``` -
+
+
-
+
Here is the console output when the server received an "expected" STUN Binding Request.
After we determined that this packet is STUN packet, our steps will be:
+
* Decode the byte array as stun.Message object via "DecodeMessage" function [backend/src/stun/message.go](../backend/src/stun/message.go)
* Validate the STUN packet's integrity via HMAC and fingerprint via CRC32, by "Validate" function [backend/src/stun/message.go](../backend/src/stun/message.go)
* We only support "Binding Request" message type as incoming STUN packet, because of this, we have only one case.
@@ -128,6 +130,7 @@ After we determined that this packet is STUN packet, our steps will be:
* If everything is OK, we create a STUN Binding Response packet (by calling "createBindingResponse" function) and send it. This means "I accept your request, we can communicate by this channel, send me DTLS ClientHello message".
from [backend/src/agent/udpclientsocket.go](../backend/src/agent/udpclientsocket.go)
+
```go
switch stunMessage.MessageType {
case stun.MessageTypeBindingRequest:
@@ -159,10 +162,10 @@ After we determined that this packet is STUN packet, our steps will be:
}
```
-Click to expand Wireshark capture (Received): STUN Binding Request
-``` +```console Frame 414: 140 bytes on wire (1120 bits), 140 bytes captured (1120 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -111,15 +113,15 @@ Session Traversal Utilities for NAT Attribute Length: 4 CRC-32: 0xaaff24d0 ``` -+
+
-
+
Now, the client will send a [ClientHello](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.1.2) message and we can start the [DTLS Handshake](https://datatracker.ietf.org/doc/html/rfc4347#section-4.2) process.
diff --git a/docs/05-DTLS-HANDSHAKE.md b/docs/05-DTLS-HANDSHAKE.md
index 09dea68..70f4b62 100644
--- a/docs/05-DTLS-HANDSHAKE.md
+++ b/docs/05-DTLS-HANDSHAKE.md
@@ -6,7 +6,7 @@ In previous chapter, we received first "expected" UDP packet (STUN Binding Reque
DTLS Handshake consists of some "flights" between client and server, schematized [here](https://tools.ietf.org/html/rfc4347#section-4.2.4) as:
-```
+```console
------ ------
ClientHello --------> Flight 1
@@ -33,23 +33,23 @@ DTLS Handshake consists of some "flights" between client and server, schematized
```
Sources:
-* [Breaking Down the TLS Handshake](https://www.youtube.com/watch?v=cuR05y_2Gxc&list=PLyqga7AXMtPMXgn1NwDqnSlgU05cnl4PA) (Before continuing, it's highly recommended to watch this Youtube playlist to understand TLS Handshake process, ciphers, curves, hashing, algorithms, etc... In videos, they tell about TLS v1.2 and v1.3, but we don't use v1.3).
-Click to expand Wireshark capture (Sent): STUN Binding Response
-``` +```console Frame 451: 144 bytes on wire (1152 bits), 144 bytes captured (1152 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -217,9 +220,8 @@ Session Traversal Utilities for NAT Attribute Length: 4 CRC-32: 0x8387d149 ``` -+
+* [Breaking Down the TLS Handshake](https://www.youtube.com/watch?v=cuR05y_2Gxc&list=PLyqga7AXMtPMXgn1NwDqnSlgU05cnl4PA) (Before continuing, it's highly recommended to watch this Youtube playlist to understand TLS Handshake process, ciphers, curves, hashing, algorithms, etc... In videos, they tell about TLS v1.2 and v1.3, but we don't use v1.3). ## **5.1. Client sends first ClientHello message (Flight 0)** -
When a new packet comes in, the "AddBuffer" function in [backend/src/agent/udpclientsocket.go](../backend/src/agent/udpclientsocket.go) looks for which protocol standard this packet to rely on. In this context, we can check out dtls.IsDtlsPacket function. This function checks: - * Data length (arrayLen) is greater than zero -
and - * First byte of data (ordinally) is between 20 and 63. This byte represents the DTLS Record Header's ContentType value. + +* Data length (arrayLen) is greater than zero +
and +* First byte of data (ordinally) is between 20 and 63. This byte represents the DTLS Record Header's ContentType value. If this buffer part complies with these conditions, we can say "this packet is a DTLS protocol packet", then we can process it with DTLS protocol's methods. from [backend/src/dtls/dtlsmessage.go](../backend/src/dtls/dtlsmessage.go) + ```go func IsDtlsPacket(buf []byte, offset int, arrayLen int) bool { return arrayLen > 0 && buf[offset] >= 20 && buf[offset] <= 63 @@ -64,12 +64,10 @@ We determined that this packet is DTLS packet. A DTLS packet consists of a Recor The ClientHello packet we received is a "Handshake" message, so we should discuss the structure of a Handshake packet. -
- ## **5.1.1. DTLS Record Header** -
from [backend/src/dtls/recordheader.go](../backend/src/dtls/recordheader.go) + ```go type RecordHeader struct { ContentType ContentType @@ -81,6 +79,7 @@ type RecordHeader struct { ``` You can find: + * Detailed information about attributes of this record in [WebRTC for the Curious: Securing - DTLS](https://webrtcforthecurious.com/docs/04-securing/#dtls) * ContentType constants in [backend/src/stun/messagetype.go](../backend/src/dtls/recordheader.go) * DtlsVersion constants in [backend/src/stun/messagetype.go](../backend/src/dtls/recordheader.go) @@ -89,12 +88,10 @@ If Epoch is zero, the contents of the packet is in clear text, not encrypted. If Source: [Generic header structure of the DTLS record layer](https://github.com/eclipse/tinydtls/blob/706888256c3e03d9fcf1ec37bb1dd6499213be3c/dtls.h#L320) -
- ## **5.1.2. DTLS Record Header** -
from [backend/src/dtls/handshakeheader.go](../backend/src/dtls/handshakeheader.go) + ```go type HandshakeHeader struct { HandshakeType HandshakeType @@ -109,6 +106,7 @@ type HandshakeHeader struct { * "uint24" is defined in [backend/src/dtls/dtlsmessage.go](../backend/src/dtls/dtlsmessage.go), to represent 24 byte unsigned integer values in handshake data structure. from [backend/src/dtls/dtlsmessage.go](../backend/src/dtls/dtlsmessage.go) + ```go type uint24 [3]byte ``` @@ -120,15 +118,12 @@ DTLS fragmentation is not supported in this project, so we ignore these fragment Source: [Header structure for the DTLS handshake protocol](https://github.com/eclipse/tinydtls/blob/706888256c3e03d9fcf1ec37bb1dd6499213be3c/dtls.h#L344) - -
- ## **5.1.3. ClientHello Message Content (Flight 0)** -
The ClientHello message is the first message of the first flight. The RFC counts flights starting from 1, we count them starting from 0, because we assume the Flight 0 is "waiting for ClientHello" state, Flight 1 is after receiving the first ClientHello. So, you can track the flight numbers this way. from [backend/src/dtls/clienthello.go](../backend/src/dtls/clienthello.go) + ```go type ClientHello struct { Version DtlsVersion @@ -141,10 +136,10 @@ type ClientHello struct { } ``` -
+
-
+
This message is bootstrapper of a new DTLS Handshake process. Client says to us, "I want to make a DTLS handshake with you, these are my security data to share".
@@ -264,6 +258,7 @@ This message is bootstrapper of a new DTLS Handshake process. Client says to us,
* Random: Each part (the client and the server) generates random values for themselves, we call them as "Client Random" and "Server Random". In DTLS v1.2, random byte array consists of 32 bytes. The first 4 bytes are for current system time, remaining 28 bytes are randomly generated.
from [backend/src/dtls/random.go](../backend/src/dtls/random.go)
+
```go
type Random struct {
GMTUnixTime time.Time
@@ -278,6 +273,7 @@ Source: [Pion WebRTC: DTLS Random](https://github.com/pion/dtls/blob/b3e235f54b6
* CipherSuiteIDs: Each party has implemented and supported a set of [Cipher Suite](https://en.wikipedia.org/wiki/Cipher_suite)s, in DTLS and TLS each of them coded with uint16 constant value. With this information, the client informs us "I support these cipher suites, choose one of them which you support too, then we can continue using it."
Click to expand Wireshark capture (Received): DTLS ClientHello (first, without cookie)
-``` +```console Frame 458: 189 bytes on wire (1512 bits), 189 bytes captured (1512 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -254,9 +249,8 @@ Datagram Transport Layer Security [JA3 Fullstring: 65277,49195-49199-52393-52392-49161-49171-49162-49172-156-47-53,23-65281-10-11-35-13-14,29-23-24,0] [JA3: c14667d7da3e6f7a7ab5519ef78c2452] ``` -+
A "Cipher Suite" is a set of algorithms, usually consists of a key exchange algorithm, a hash algorithm and signature/authentication algorithm. You can find cipher suites and values [here](https://www.rfc-editor.org/rfc/rfc8422.html#section-6), and our only one supported cipher suite constant at [backend/src/dtls/ciphersuites.go](../backend/src/dtls/ciphersuites.go). + * CompressionMethodIDs: We only support Uncompressed mode with value zero. * Extensions: Client can send a list of extension data with the ClientHello message. Some of them which we support: * UseExtendedMasterSecret: In encryption, we use a "master secret". Each party generates their own "master secret" and don't share it with others. There are some ways to generate it, a standard way and an extended way. We will discuss about this, but if ClientHello contains a UseExtendedMasterSecret extension, it means "the client uses extended master secret generation method, you should use it too". @@ -289,19 +285,18 @@ A "Cipher Suite" is a set of algorithms, usually consists of a key exchange algo
After receiving the first ClientHello (which doesn't contain a Cookie value), we: + * Set our DTLS Handshake Context's (HandshakeContext defined in [backend/src/dtls/handshakecontext.go](../backend/src/dtls/handshakecontext.go)) state as "Connecting" * Set the context's ProtocolVersion as incoming ClientHello's Version. We should check it, but in this project we assume two parties speak with DTLS v1.2. * Generate a 20 bytes DTLS Cookie by calling "generateDtlsCookie" function, and set the context's Cookie property. * Set the context's Flight to "Flight 2" -
- ## **5.2. Server sends HelloVerifyRequest message (Flight 2)** -
We generate a HelloVerifyRequest message by calling "createDtlsHelloVerifyRequest" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). We share the Cookie data which we generated previously (in context.Cookie) with the client. from [backend/src/dtls/helloverifyrequest.go](../backend/src/dtls/helloverifyrequest.go) + ```go type HelloVerifyRequest struct { Version DtlsVersion @@ -309,10 +304,10 @@ type HelloVerifyRequest struct { } ``` -
+
-
+
Now we are waiting for another (nearly the same) ClientHello message, but with a Cookie that has the same value as our HelloVerifyRequest.
Click to expand Wireshark capture (Sent): DTLS HelloVerifyRequest
-``` +```console Frame 483: 80 bytes on wire (640 bits), 80 bytes captured (640 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -334,24 +329,19 @@ Datagram Transport Layer Security Cookie Length: 20 Cookie: b130316a0e21459cd54d85062f2fb018c4f78be0 ``` -+
-
-- ## **5.3. Client sends second ClientHello message (Flight 2)** -
-
+
-
+
Click to expand Wireshark capture (Received): DTLS ClientHello (second, with cookie)
-``` +```console Frame 484: 209 bytes on wire (1672 bits), 209 bytes captured (1672 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -462,15 +452,15 @@ Datagram Transport Layer Security [JA3 Fullstring: 65277,49195-49199-52393-52392-49161-49171-49162-49172-156-47-53,23-65281-10-11-35-13-14,29-23-24,0] [JA3: c14667d7da3e6f7a7ab5519ef78c2452] ``` -+
We received second ClientHello from the client, with nearl same content but with a Cookie.
We:
+
* Know we are in Flight 2, we check if the incoming ClientHello's Cookie value and we sent via HelloVerifyRequest (stored in our context object). If it is empty, we should return to Flight 0 state and wait for a new ClientHello message. If not empty, we should compare two values.
* Find a cipher suite ID which mutually supported by each peer, via calling "negotiateOnCipherSuiteIDs" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go), then set it to context.CipherSuite. In our example, negotiated on TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (0xc02b) cipher suite.
* Loop through ClientHello message's extensions. We process the known and supported ones, and ignore unknown ones. Tracking the order at console output below:
@@ -480,15 +470,12 @@ We:
-
-- ### **5.3.1. Generating cryptographic keys** -
Now, server chose one from each cryptographic methods, algorithms etc... which client offered as alternatives. The server knows which methods they will use while encrypting, the client will learn further. The server should generate some secrets and keys, for it's side. We: + * Set incoming ClientHello.Random to context.ClientRandom * Generate a Server Random via calling "Generate" function in [backend/src/dtls/random.go](../backend/src/dtls/random.go) and set it to context.ServerRandom. * Generate a server private and server public key, by using [X25519 curve](https://pkg.go.dev/golang.org/x/crypto@v0.0.0-20220411220226-7b82a4e95df4/curve25519), via calling "GenerateCurveKeypair" function in [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go). These private and public keys are different from and not related with previously generated Server Certificate keys. @@ -512,6 +499,7 @@ We: * We set this calculated signature to context.ServerKeySignature from [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go) + ```go context.ServerKeySignature, err = GenerateKeySignature( clientRandomBytes, @@ -523,6 +511,7 @@ context.ServerKeySignature, err = GenerateKeySignature( ``` from [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) + ```go func GenerateKeySignature(clientRandom []byte, serverRandom []byte, publicKey []byte, curve Curve, privateKey crypto.PrivateKey, hashAlgorithm HashAlgorithm) ([]byte, error) { msg := generateValueKeyMessage(clientRandom, serverRandom, publicKey, curve) @@ -543,16 +532,15 @@ func GenerateKeySignature(clientRandom []byte, serverRandom []byte, publicKey [] Now we are ready to send a group of messages: A ServerHello, a Certificate, a ServerKeyExchange, a CertificateRequest, and a ServerHelloDone message. These messages can be sent in same packet (by fragmenting) or one by one. We prefer to send them individually, one by one. Sources: -* [Pion WebRTC: DTLS, Generating Elliptic Keypair](https://github.com/pion/dtls/blob/bee42643f57a7f9c85ee3aa6a45a4fa9811ed122/pkg/crypto/elliptic/elliptic.go#L70) -
+* [Pion WebRTC: DTLS, Generating Elliptic Keypair](https://github.com/pion/dtls/blob/bee42643f57a7f9c85ee3aa6a45a4fa9811ed122/pkg/crypto/elliptic/elliptic.go#L70) ## **5.4. Server sends ServerHello message (Flight 4)** -
We generate a ServerHello message by calling "createDtlsServerHello" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/serverhello.go](../backend/src/dtls/serverhello.go) + ```go type ServerHello struct { Version DtlsVersion @@ -565,10 +553,10 @@ type ServerHello struct { } ``` -
+
-
+
* Set Version to context.ProtocolVersion
* Set Random to context.ServerRandom
@@ -633,24 +620,22 @@ Datagram Transport Layer Security
ServerHello message was sent.
-Click to expand Wireshark capture (Sent): DTLS ServerHello
-``` +```console Frame 511: 121 bytes on wire (968 bits), 121 bytes captured (968 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -617,9 +605,8 @@ Datagram Transport Layer Security [JA3S Fullstring: 65277,49195,65281-14-11-23] [JA3S: eeb7a12006b679344c81e682d2ae5951] ``` -+
- ## **5.5. Server sends Certificate message (Flight 4)** -
We generate a Certificate message by calling "createDtlsCertificate" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/certificate.go](../backend/src/dtls/certificate.go) + ```go type Certificate struct { Certificates [][]byte } ``` -
+
-
+
* Set Certificates to ServerCertificate.Certificate
@@ -748,14 +732,12 @@ We shared our X.509 Server Certificate data with the client.
Certificate message was sent.
-Click to expand Wireshark capture (Sent): DTLS Certificate
-``` +```console Frame 513: 483 bytes on wire (3864 bits), 483 bytes captured (3864 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -736,9 +721,8 @@ Datagram Transport Layer Security Padding: 0 encrypted: 304502206b40cd413f21a016d5aa53325b2029e1a5ee3bddc2e49a9dadf97a5040718ff8… ``` -+
- ## **5.6. Server sends ServerKeyExchange message (Flight 4)** -
We generate a ServerKeyExchange message by calling "createDtlsServerKeyExchange" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/serverkeyexchange.go](../backend/src/dtls/serverkeyexchange.go) + ```go type ServerKeyExchange struct { EllipticCurveType CurveType @@ -766,10 +748,10 @@ type ServerKeyExchange struct { } ``` -
+
-
+
* Set EllipticCurveType to context.CurveType (CurveTypeNamedCurve 0x03)
* Set NamedCurve to context.Curve (CurveX25519 0x001d)
@@ -818,14 +799,12 @@ Datagram Transport Layer Security
ServerKeyExchange message was sent.
-Click to expand Wireshark capture (Sent): DTLS ServerKeyExchange
-``` +```console Frame 514: 169 bytes on wire (1352 bits), 169 bytes captured (1352 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -798,9 +780,8 @@ Datagram Transport Layer Security Signature Length: 72 Signature: 3046022100b8609b89a48945bee8ccad168c935466c2dcf46c8539bbf0f81ac6641e5db2… ``` -+
- ## **5.7. Server sends CertificateRequest message (Flight 4)** -
We generate a CertificateRequest message by calling "createDtlsCertificateRequest" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/certificaterequest.go](../backend/src/dtls/certificaterequest.go) + ```go type CertificateRequest struct { CertificateTypes []CertificateType @@ -833,10 +812,10 @@ type CertificateRequest struct { } ``` -
+
-
+
* Set CertificateTypes to [CertificateTypeECDSASign (0x40)]
* Set AlgoPairs to [AlgoPair{
@@ -883,23 +861,21 @@ We requested for a client certificate which ECDSASign type, generated using hash
CertificateRequest message was sent.
-Click to expand Wireshark capture (Sent): DTLS CertificateRequest
-``` +```console Frame 515: 65 bytes on wire (520 bits), 65 bytes captured (520 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -864,9 +843,8 @@ Datagram Transport Layer Security Signature Hash Algorithm Signature: ECDSA (3) Distinguished Names Length: 0 ``` -+
- ## **5.8. Server sends ServerHelloDone message (Flight 4)** -
We generate a ServerHelloDone message by calling "createDtlsServerHelloDone" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/serverhellodone.go](../backend/src/dtls/serverhellodone.go) + ```go type ServerHelloDone struct { } ``` -
+
-
+
The message doesn't carry any data.
@@ -930,25 +905,22 @@ ServerHelloDone message was sent.
Now we are waiting for a group of messages: A Certificate, a ClientKeyExchange, a CertificateVerify, a ChangeCipherSpec, a Finished message. For e.g., if our client is Chrome, it will send these messages in one packet.
-
-Click to expand Wireshark capture (Sent): DTLS ServerHelloDone
-``` +```console Frame 516: 57 bytes on wire (456 bits), 57 bytes captured (456 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -918,9 +894,8 @@ Datagram Transport Layer Security Fragment Offset: 0 Fragment Length: 0 ``` -+
- ## **5.9. Client sends Certificate message (Flight 4)** -
 from [backend/src/dtls/certificate.go](../backend/src/dtls/certificate.go) + ```go type Certificate struct { Certificates [][]byte } ``` -
+
-
+
The client shared their X.509 Server Certificate data with the server.
@@ -1018,25 +989,22 @@ The client shared their X.509 Server Certificate data with the server.
* Call "GetCertificateFingerprintFromBytes" function in [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) to generate the fingerprint hash from the certificate byte array
* Compare the calculated fingerprint hash with context.ExpectedFingerprintHash which came with SDP data previously. So we can ensure that "the sender of SDP via Signaling" and "the sender of these handshake messages" are the same person/machine, not another man in the middle.
-
-Click to expand Wireshark capture (Received): DTLS Certificate (came in combined packet)
-``` +```console Frame 522: 579 bytes on wire (4632 bits), 579 bytes captured (4632 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1008,9 +980,8 @@ Datagram Transport Layer Security ... ``` -+
- ## **5.9. Client sends ClientKeyExchange message (Flight 4)** -
 from [backend/src/dtls/clientkeyexchange.go](../backend/src/dtls/clientkeyexchange.go) + ```go type ClientKeyExchange struct { PublicKey []byte } ``` -
+
-
+
* Set context.ClientKeyExchangePublic to message.PublicKey
* If context.IsCipherSuiteInitialized is false (our cipher suite is not initialized yet), we are ready to initialize our cipher suite, call "initCipherSuite" function in from [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go)
-
-Click to expand Wireshark capture (Received): DTLS ClientKeyExchange (came in combined packet)
-``` +```console Frame 522: 579 bytes on wire (4632 bits), 579 bytes captured (4632 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1063,30 +1031,22 @@ Datagram Transport Layer Security ... ``` -+
- ### **5.9.1. Initialization of cipher suite** -
We need to generate a master secret. Then using this master secret, client random, and server random, we will initialize our keys. We will use these keys while encrypting/decrypting the SRTP packets further. - -
- #### **5.9.1.1. Generate a Pre-Master Secret** -
We call "GeneratePreMasterSecret" function in [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) from [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go) + ```go preMasterSecret, err := GeneratePreMasterSecret(context.ClientKeyExchangePublic, context.ServerPrivateKey, context.Curve) ``` @@ -1096,13 +1056,10 @@ We call "GeneratePreMasterSecret" function in [backend/src/dtls/crypto.go](../ba ***Attention Note:** Public key was the ClientKeyExchange message's Public Key, the ServerPrivateKey was generated via "GenerateCurveKeypair". Sources: -* [Differences between the terms "pre-master secret", "master secret", "private key", and "shared secret"? (Stackoverflow)](https://crypto.stackexchange.com/questions/27131/differences-between-the-terms-pre-master-secret-master-secret-private-key) - -
+* [Differences between the terms "pre-master secret", "master secret", "private key", and "shared secret"? (Stackoverflow)](https://crypto.stackexchange.com/questions/27131/differences-between-the-terms-pre-master-secret-master-secret-private-key) #### **5.9.1.2. Generate a Master Secret** -
We look to our context.UseExtendedMasterSecret boolean value. Remember that, if ClientHello message has UseExtendedMasterSecret extension, we should generate our master secret in extended way. @@ -1126,6 +1083,7 @@ Order should be like: * Call "GenerateExtendedMasterSecret" function in [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) with our *preMasterSecret*, *handshakeHash*, *context.CipherSuite.HashAlgorithm*. from [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) + ```go func GenerateExtendedMasterSecret(preMasterSecret []byte, handshakeHash []byte, hashAlgorithm HashAlgorithm) ([]byte, error) { seed := append([]byte("extended master secret"), handshakeHash...) @@ -1148,7 +1106,6 @@ func GenerateExtendedMasterSecret(preMasterSecret []byte, handshakeHash []byte,  - **If context.UseExtendedMasterSecret is false:** **Note:** In current context, our code won't come this state, because (I think) Chrome always sends the UseExtendedMasterSecret extension with ClientHello message. But we can discuss on generating non-extended master secret: @@ -1162,20 +1119,15 @@ func GenerateExtendedMasterSecret(preMasterSecret []byte, handshakeHash []byte, * Set the result of "GenerateMasterSecret" function to context.ServerMasterSecret. - - Sources: + * [RFC 7627: Transport Layer Security (TLS) Session Hash and Extended Master Secret Extension - The Extended Master Secret](https://datatracker.ietf.org/doc/html/rfc7627#section-4) * [WebRTC for the Curious: Securing - Pseudorandom Function](https://webrtcforthecurious.com/docs/04-securing/#pseudorandom-function) * [Pseudorandom function family (Wikipedia)](https://en.wikipedia.org/wiki/Pseudorandom_function_family) * [RFC 4346: The Transport Layer Security (TLS) Protocol Version 1.1 - HMAC and the Pseudorandom Function](https://datatracker.ietf.org/doc/html/rfc4346#section-5) * [Pion WebRTC DTLS project, PHash function (Github)](https://github.com/pion/dtls/blob/a6397ff7282bc56dc37a68ea9211702edb4de1de/pkg/crypto/prf/prf.go#L155) - -
- #### **5.9.1.3. Initialize GCM** -
[GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) is abbreviation for "Galois/Counter Mode" and is a type of [block cipher mode of operation ](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation). In our project, we only implemented the TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 cipher suite, and it uses [AES-GCM](https://www.cryptosys.net/pki/manpki/pki_aesgcmauthencryption.html) authenticated encryption. @@ -1187,6 +1139,7 @@ This struct was defined in "dtls" package specifically to process DTLS messages. You can find the original code on [Pion WebRTC DTLS project, GCM struct (Github)](https://github.com/pion/dtls/blob/b3e235f54b60ccc31aa10193807b5e8e394f17ff/pkg/crypto/ciphersuite/gcm.go#L20). from [backend/src/dtls/cryptogcm.go](../backend/src/dtls/cryptogcm.go) + ```go type GCM struct { localGCM, remoteGCM cipher.AEAD @@ -1200,7 +1153,7 @@ type GCM struct { * prfMacLen: 0 bytes * prfKeyLen: 16 bytes (our keys will be 16 bytes length) * prfIvLen: 4 bytes (our [Initialization Vectors](https://en.wikipedia.org/wiki/Initialization_vector) will be 4 bytes length) - +
**Note:** These constant length values can vary for different cipher suites. Due to our chosen suite's MAC length is zero, we didn't include things related with MAC in our code. @@ -1218,10 +1171,11 @@ Because we want: * A key for server (serverWriteKey) (16 bytes) * An initialization vector for client (clientWriteIV) (4 bytes) * An initialization vector for server (serverWriteIV) (4 bytes) -
+ So we need (16+16+4+4) = 40 bytes array which is generated by PHash with our masterSecret and seed. Then we extract our key and IV values from these 40 bytes sequentially. from [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) + ```go func GenerateEncryptionKeys(masterSecret []byte, clientRandom []byte, serverRandom []byte, keyLen int, ivLen int, hashAlgorithm HashAlgorithm) (*EncryptionKeys, error) { logging.Descf(logging.ProtoCRYPTO, "Generating encryption keys with Key Length: %d, IV Length: %d via %s, using Master Secret, Server Random, Client Random...", keyLen, ivLen, hashAlgorithm) @@ -1264,11 +1218,13 @@ We are ready to create our GCM object, which contains our ciphers and IVs. We pa * While creating our ciphers, we create new instances by [aes.NewCipher](https://pkg.go.dev/crypto/aes#NewCipher) and [cipher.NewGCM](https://pkg.go.dev/crypto/cipher#NewGCM) from [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go) + ```go gcm, err := NewGCM(keys.ServerWriteKey, keys.ServerWriteIV, keys.ClientWriteKey, keys.ClientWriteIV) ``` from [backend/src/dtls/cryptogcm.go](../backend/src/dtls/cryptogcm.go) + ```go func NewGCM(localKey, localWriteIV, remoteKey, remoteWriteIV []byte) (*GCM, error) { localBlock, err := aes.NewCipher(localKey) @@ -1287,27 +1243,24 @@ func NewGCM(localKey, localWriteIV, remoteKey, remoteWriteIV []byte) (*GCM, erro remoteWriteIV: remoteWriteIV, }, nil } - ``` * We set returned GCM object to context.GCM and set context.IsCipherSuiteInitialized as true. Sources: + * [What is the main difference between a key, an IV and a nonce? (Stackoverflow)](https://crypto.stackexchange.com/questions/3965/what-is-the-main-difference-between-a-key-an-iv-and-a-nonce) * [Initialization vector](https://en.wikipedia.org/wiki/Initialization_vector) * [Keying material (NIST)](https://csrc.nist.gov/glossary/term/keying_material) * [Secret keying material (NIST)](https://csrc.nist.gov/glossary/term/secret_keying_material) * [Key material (Mozilla)](https://infosec.mozilla.org/guidelines/key_management#key-material) - -
- ## **5.10. Client sends CertificateVerify message (Flight 4)** -
 from [backend/src/dtls/certificateverify.go](../backend/src/dtls/certificateverify.go) + ```go type CertificateVerify struct { AlgoPair AlgoPair @@ -1315,10 +1268,10 @@ type CertificateVerify struct { } ``` -
+
-
+
* Compare hash algorithm ID of incoming *message.AlgoPair.HashAlgorithm* and *context.CipherSuite.HashAlgorithm*
* Compare signature algorithm ID of incoming *message.AlgoPair.SignatureAlgorithm* and *context.CipherSuite.SignatureAlgorithm*
@@ -1370,27 +1322,26 @@ Order should be like:
* Check the validity of the X.509 certificate which came with Certificate message from the client, by [ecdsa.Verify](https://pkg.go.dev/crypto/ecdsa#Verify).
from [backend/src/dtls/crypto.go](../backend/src/dtls/crypto.go)
+
```go
ecdsa.Verify(clientCertificatePublicKey, hash, ecdsaSign.R, ecdsaSign.S)
```
-Click to expand Wireshark capture (Received): DTLS CertificateVerify (came in combined packet)
-``` +```console Frame 522: 579 bytes on wire (4632 bits), 579 bytes captured (4632 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1347,9 +1300,8 @@ Datagram Transport Layer Security ... ``` -+
- ## **5.11. Client sends ChangeCipherSpec message (Flight 4)** -
from [backend/src/dtls/changecipherspec.go](../backend/src/dtls/changecipherspec.go)
+
```go
type ChangeCipherSpec struct {
}
```
-
+
-
+
This type of message contains only a byte with value 1. We don't do anything for this message.
**Important note:** Epoch of Record Header were 0 and contents were in clear text (not encrypted) until (and including) this ChangeCipherSpec message. But the messages that will come after this, will have Epoch with 1 and will be encrypted.
-
-Click to expand Wireshark capture (Received): DTLS ChangeCipherSpec (came in combined packet)
-``` +```console Frame 522: 579 bytes on wire (4632 bits), 579 bytes captured (4632 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1409,36 +1360,31 @@ Datagram Transport Layer Security ... ``` -+
- ## **5.12. Client sends Finished message (Flight 4)** -
 from [backend/src/dtls/finished.go](../backend/src/dtls/finished.go) + ```go type Finished struct { VerifyData []byte } ``` -
+
**Important note:** As you can see at the end of the block, latest handshake message (Finished) has Epoch: 1, and content was encrypted. Because of this, we can't see contents of it as clear text in Wireshark. -``` +```console Frame 522: 579 bytes on wire (4632 bits), 579 bytes captured (4632 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1456,9 +1402,8 @@ Datagram Transport Layer Security Handshake Protocol (Encrypted content: 0x0001000000000000e22c7b2609d96a7d3a98c7b80e32ea03868231eb419623ce8af27b5ab97b16df143e8743ab0cb6ba) ``` -
-
+
**Important note:** Epoch of Record Header is 1 and, this Finished message is the first message which was encrypted. If we can decode and decrypt contents of this message successfully, then verify the VerifyData successfully, it means that, the handshake process for our side succeeded! After that we will send two other messages, then it will be "completely" finished!
@@ -1482,25 +1427,24 @@ Order should be like (attention to CertificateVerify and Finished were addded de
* Set the context's Flight to "Flight 6"
Sources:
-* [RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 - Finished](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.9)
-Click to expand Wireshark capture (Received): DTLS Finished (came in combined packet)
-**Important note:** As you can see at the end of the block, latest handshake message (Finished) has Epoch: 1, and content was encrypted. Because of this, we can't see contents of it as clear text in Wireshark. -``` +```console Frame 522: 579 bytes on wire (4632 bits), 579 bytes captured (4632 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1456,9 +1402,8 @@ Datagram Transport Layer Security Handshake Protocol (Encrypted content: 0x0001000000000000e22c7b2609d96a7d3a98c7b80e32ea03868231eb419623ce8af27b5ab97b16df143e8743ab0cb6ba) ``` -
+
+* [RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 - Finished](https://datatracker.ietf.org/doc/html/rfc5246#section-7.4.9) ## **5.13. Server sends ChangeCipherSpec message (Flight 6)** -
We generate a ChangeCipherSpec message by calling "createDtlsChangeCipherSpec" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/changecipherspec.go](../backend/src/dtls/changecipherspec.go) + ```go type ChangeCipherSpec struct { } ``` -
+
-
+
This type of message contains only a byte with value 1.
@@ -1528,28 +1471,24 @@ This type of message contains only a byte with value 1.
* Called "IncreaseServerEpoch" function in [backend/src/dtls/handshakecontext.go](../backend/src/dtls/handshakecontext.go) to increase context.ServerEpoch to 1, and set context.ServerSequenceNumber = 0.
-Click to expand Wireshark capture (Sent): DTLS ChangeCipherSpec
-``` +```console Frame 549: 46 bytes on wire (368 bits), 46 bytes captured (368 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1514,9 +1458,8 @@ Datagram Transport Layer Security Length: 1 Change Cipher Spec Message ``` -+
- ## **5.14. Server sends Finished message (Flight 6)** -
We generate a Finished message by calling "createDtlsFinished" function in [backend/src/dtls/handshakemanager.go](../backend/src/dtls/handshakemanager.go). from [backend/src/dtls/finished.go](../backend/src/dtls/finished.go) + ```go type Finished struct { VerifyData []byte } ``` -
+
- **Important note:** As you can see at the end of the block, the handshake message (Finished) has Epoch: 1, and content was encrypted. Because of this, we can't see contents of it as clear text in Wireshark. -``` +```console Frame 550: 93 bytes on wire (744 bits), 93 bytes captured (744 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1564,9 +1503,8 @@ Datagram Transport Layer Security Handshake Protocol (Encrypted content: 0x61c244d15307ccaf237e2ef34fdd5bddff3d7d17cf3fcb837a80db65f777a2496c609b03d7a35b772754cc206bb16db2) ``` -
-
+
Click to expand Wireshark capture (Sent): DTLS Finished
-- **Important note:** As you can see at the end of the block, the handshake message (Finished) has Epoch: 1, and content was encrypted. Because of this, we can't see contents of it as clear text in Wireshark. -``` +```console Frame 550: 93 bytes on wire (744 bits), 93 bytes captured (744 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -1564,9 +1503,8 @@ Datagram Transport Layer Security Handshake Protocol (Encrypted content: 0x61c244d15307ccaf237e2ef34fdd5bddff3d7d17cf3fcb837a80db65f777a2496c609b03d7a35b772754cc206bb16db2) ``` -
+
diff --git a/docs/06-SRTP-INITIALIZATION.md b/docs/06-SRTP-INITIALIZATION.md
index 9c80fe6..e8ee555 100644
--- a/docs/06-SRTP-INITIALIZATION.md
+++ b/docs/06-SRTP-INITIALIZATION.md
@@ -38,6 +38,7 @@ Although our project was designed as a monolith and one package, in real-world D
* The orchestrator gives the byte array to SRTP side for extracting keys and salts from given [keying material](https://csrc.nist.gov/glossary/term/keying_material)
from [backend/src/dtls/finished.go](../backend/src/dtls/finished.go)
+
```go
func (ms *UDPClientSocket) OnDTLSStateChangeEvent(dtlsState dtls.DTLSState) {
logging.Infof(logging.ProtoDTLS, "State Changed: %s [%v:%v].\n", dtlsState, ms.HandshakeContext.Addr.IP, ms.HandshakeContext.Addr.Port)
@@ -62,6 +63,7 @@ func (ms *UDPClientSocket) OnDTLSStateChangeEvent(dtlsState dtls.DTLSState) {
* It calls "extractEncryptionKeys" function in [backend/src/srtp/srtpmanager.go](../backend/src/srtp/srtpmanager.go) to extract key and salt values from this 56 bytes keying material sequentially. you can find further information [here](https://github.com/pion/srtp/blob/82008b58b1e7be7a0cb834270caafacc7ba53509/keying.go#L14)
from [backend/src/srtp/srtpmanager.go](../backend/src/srtp/srtpmanager.go)
+
```go
func (m *SRTPManager) extractEncryptionKeys(protectionProfile ProtectionProfile, keyingMaterial []byte) (*EncryptionKeys, error) {
keyLength, err := protectionProfile.KeyLength()
@@ -92,12 +94,7 @@ func (m *SRTPManager) extractEncryptionKeys(protectionProfile ProtectionProfile,
-
-
-- ## **6.1. Initialize GCM** -
[GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) is the abbreviation for "Galois/Counter Mode" and is a type of [Block cipher mode of operation ](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation). @@ -107,12 +104,13 @@ We discussed what is GCM and why we call our object as GCM, in initialization of So, we call the object that makes encryption/decryption over our SRTP and SCTP packets as GCM. from [backend/src/srtp/cryptogcm.go](../backend/src/srtp/cryptogcm.go) + ```go type GCM struct { srtpGCM, srtcpGCM cipher.AEAD srtpSalt, srtcpSalt []byte } -```` +``` * Now, we have an "EncryptionKeys" object defined in [backend/src/srtp/protectionprofiles.go](../backend/src/srtp/protectionprofiles.go).
@@ -126,11 +124,13 @@ We are ready to create our GCM object, which contains our ciphers and salt value * While creating our ciphers, we create new instances by [aes.NewCipher](https://pkg.go.dev/crypto/aes#NewCipher) and [cipher.AEAD](https://pkg.go.dev/crypto/cipher#AEAD) from [backend/src/srtp/srtpmanager.go](../backend/src/srtp/srtpmanager.go) + ```go gcm, err := InitGCM(keys.ClientMasterKey, keys.ClientMasterSalt) ``` from [backend/src/srtp/cryptogcm.go](../backend/src/srtp/cryptogcm.go) + ```go func NewGCM(masterKey, masterSalt []byte) (*GCM, error) { srtpSessionKey, err := aesCmKeyDerivation(labelSRTPEncryption, masterKey, masterSalt, 0, len(masterKey)) @@ -184,7 +184,7 @@ func NewGCM(masterKey, masterSalt []byte) (*GCM, error) { * We set returned GCM object to context.GCM and set context.IsCipherSuiteInitialized as true. -Now, we are ready to receive and decrypt incoming SRTP and SRTCP packets. We are not ready to encrypt, because we don't need and implemented this part :) +Now, we are ready to receive and decrypt incoming SRTP and SRTCP packets. We are not ready to encrypt, because we don't need and implemented this part :blush:
diff --git a/docs/07-SRTP-PACKETS-COME.md b/docs/07-SRTP-PACKETS-COME.md index f236c5e..0388ba2 100644 --- a/docs/07-SRTP-PACKETS-COME.md +++ b/docs/07-SRTP-PACKETS-COME.md @@ -5,7 +5,8 @@ In previous chapter, we completed the initialization of SRTP ciphers process suc When a new packet comes in, the "AddBuffer" function in [backend/src/agent/udpclientsocket.go](../backend/src/agent/udpclientsocket.go) looks for which protocol standard this packet rely on. RTP packet structure -``` + +```console 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ @@ -25,6 +26,7 @@ When a new packet comes in, the "AddBuffer" function in [backend/src/agent/udpcl Our RTP packet struct in [backend/src/srtp/header.go](../backend/src/srtp/header.go) and [backend/src/srtp/packet.go](../backend/src/srtp/packet.go): from [backend/src/srtp/header.go](../backend/src/srtp/header.go) and [backend/src/srtp/packet.go](../backend/src/srtp/packet.go) + ```go type PayloadType byte @@ -57,13 +59,12 @@ type Packet struct { } ``` -
+
**Important note:** As you can see at the end of the block, Wireshark couldn't specify the protocol of the packet as RTP. It shows RTP/SRTP packets as raw UDP packets. -``` +```console Frame 568: 1068 bytes on wire (8544 bits), 1068 bytes captured (8544 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -72,20 +73,21 @@ Data (1036 bytes) Data: 806010d66b18660546dfb57f81a378739249bef2f2f5552907340c6229373297f3c52e7e… [Length: 1036] ``` -
-
+
**Important notice:** You can ask "The chapter is about SRTP but you show me RTP without the 'S'?". Because [SRTP (Secure Real-time Transport Protocol)](https://en.wikipedia.org/wiki/Secure_Real-time_Transport_Protocol), a secure version of [RTP (Real-time Transport Protocol)](https://en.wikipedia.org/wiki/Real-time_Transport_Protocol). Header is in clear text, Payload part is encrypted and authenticated we will discuss further.
In this context, we can check out rtp.IsRtpPacket function. This function checks:
- * Take the second byte (with index 1) which contains M (1 bit) (marker) and PT (7 bits) (PayloadType)
- * Use "and" bitwise operator on this byte and 0b01111111 (it sets 8. bit as zero, takes other 7 bits)
- * This result byte data (ordinally) is between 0 and 35, or between 96 and 127. This byte represents the SRTP Header's PayloadType value.
+
+* Take the second byte (with index 1) which contains M (1 bit) (marker) and PT (7 bits) (PayloadType)
+* Use "and" bitwise operator on this byte and 0b01111111 (it sets 8. bit as zero, takes other 7 bits)
+* This result byte data (ordinally) is between 0 and 35, or between 96 and 127. This byte represents the SRTP Header's PayloadType value.
If this buffer part complies with these conditions, we can say "this packet is an SRTP protocol packet", then we can process it with SRTP protocol's methods.
from [backend/src/rtp/rtpheader.go](../backend/src/rtp/rtpheader.go)
+
```go
func IsRtpPacket(buf []byte, offset int, arrayLen int) bool {
// Initial segment of RTP header; 7 bit payload
@@ -100,13 +102,10 @@ Here is the console output when the server received first "expected" SRTP packet
Sources:
-* [Multiplexing RTP and RTCP on a Single Port](https://csperkins.org/standards/ietf-67/2006-11-07-IETF67-AVT-rtp-rtcp-mux.pdf)
-
-Click to expand Wireshark capture (Received): First SRTP Packet
-**Important note:** As you can see at the end of the block, Wireshark couldn't specify the protocol of the packet as RTP. It shows RTP/SRTP packets as raw UDP packets. -``` +```console Frame 568: 1068 bytes on wire (8544 bits), 1068 bytes captured (8544 bits) on interface lo0, id 0 Null/Loopback Internet Protocol Version 4, Src: 192.168.***.***, Dst: 192.168.***.*** @@ -72,20 +73,21 @@ Data (1036 bytes) Data: 806010d66b18660546dfb57f81a378739249bef2f2f5552907340c6229373297f3c52e7e… [Length: 1036] ``` -
+
+* [Multiplexing RTP and RTCP on a Single Port](https://csperkins.org/standards/ietf-67/2006-11-07-IETF67-AVT-rtp-rtcp-mux.pdf) ## **7.1. Processing incoming SRTP package** -
We have determined that incoming packet is an RTP packet via rtp.IsRtpPacket function at "AddBuffer" function. @@ -114,6 +113,7 @@ We have determined that incoming packet is an RTP packet via rtp.IsRtpPacket fun * Forward the decoded RTP packet to the UDPClientSocket's "RtpDepacketizer" [channel](https://go.dev/tour/concurrency/2). This channel is listened by runRtpDepacketizer() function of UDPClientSocket object, shown below: from [backend/src/agent/udpclientsocket.go](../backend/src/agent/udpclientsocket.go) + ```go func (ms *UDPClientSocket) AddBuffer(buf []byte, offset int, arrayLen int) { logging.Descf(logging.ProtoUDP, "A packet received. The byte array (%d bytes) not parsed yet. Demultiplexing via if-else blocks.", arrayLen) @@ -134,6 +134,7 @@ func (ms *UDPClientSocket) AddBuffer(buf []byte, offset int, arrayLen int) { * Sets the decrypted payload to rtpPacket.Payload property from [backend/src/agent/udpclientsocket.go](../backend/src/agent/udpclientsocket.go) + ```go func (ms *UDPClientSocket) runRtpDepacketizer() { defer close(ms.RtpDepacketizer) @@ -154,15 +155,12 @@ func (ms *UDPClientSocket) runRtpDepacketizer() { } ``` - -
- ## **7.2. Decoding the SRTP package** -
We use "DecryptRTPPacket" function in [backend/src/srtp/srtpcontext.go](../backend/src/srtp/srtpcontext.go) to decrypt the SRTP payload. You can find the original code [here](https://github.com/pion/srtp/blob/3c34651fa0c6de900bdc91062e7ccb5992409643/srtp.go#L8). from [backend/src/srtp/srtpcontext.go](../backend/src/srtp/srtpcontext.go) + ```go func (c *SRTPContext) DecryptRTPPacket(packet *rtp.Packet) ([]byte, error) { s := c.getSRTPSSRCState(packet.Header.SSRC) @@ -191,6 +189,7 @@ func (c *SRTPContext) DecryptRTPPacket(packet *rtp.Packet) ([]byte, error) { * At this "srtpSSRCState" struct, we store the *ssrc*, *index*, and *rolloverHasProcessed* values: from [backend/src/srtp/srtpcontext.go](../backend/src/srtp/srtpcontext.go) + ```go type srtpSSRCState struct { ssrc uint32 @@ -217,6 +216,7 @@ type srtpSSRCState struct { * **Important notice:** It will decrypt the encrypted payload part, but with checking AEAD authentication with additional header data. This will give an "authentication error" if you give wrong or missing parameters. For example, on my first try, I didn't copy the ciphertext into dst variable, passed an allocated but empty byte array. But I realized that, the [AEAD.Open](https://pkg.go.dev/crypto/cipher#AEAD.Open) checks authentication in the dst parameter. from [backend/src/srtp/cryptogcm.go](../backend/src/srtp/cryptogcm.go) + ```go if _, err := g.srtpGCM.Open( dst[packet.HeaderSize:packet.HeaderSize], iv, ciphertext[packet.HeaderSize:], ciphertext[:packet.HeaderSize], @@ -225,8 +225,8 @@ type srtpSSRCState struct { } ``` - from [backend/src/srtp/cryptogcm.go](../backend/src/srtp/cryptogcm.go) + ```go func (g *GCM) Decrypt(packet *rtp.Packet, roc uint32) ([]byte, error) { ciphertext := packet.RawData @@ -253,14 +253,9 @@ func (g *GCM) Decrypt(packet *rtp.Packet, roc uint32) ([]byte, error) { ``` * Call the "updateROC" function which we get previously - * Our encrypted Payload is now decrypted and as clear text. - -
- ## **7.2. Decoding the VP8 Video Content** -
* If the packet's PayloadType is in PayloadTypeVP8 type, it forwards to the UDPClientSocket's "vp8Depacketizer" [channel](https://go.dev/tour/concurrency/2). This channel is listened by Run() function of VP8Decoder object in [backend/src/transcoding/vp8.go](../backend/src/transcoding/vp8.go), discussed in chapter [8. VP8 PACKET DECODE](./08-VP8-PACKET-DECODE.md). diff --git a/docs/08-VP8-PACKET-DECODE.md b/docs/08-VP8-PACKET-DECODE.md index b2d92c9..fb1e6b2 100644 --- a/docs/08-VP8-PACKET-DECODE.md +++ b/docs/08-VP8-PACKET-DECODE.md @@ -7,7 +7,8 @@ In previous chapter, we decoded the SRTP packet and decrypted it successfully, a * Our VP8Decoder aims to process incoming VP8 RTP packets, catch and concatenate keyframe packets then convert the result to an image object and save it as a JPEG image file. VP8 Payload Descriptor -``` + +```console 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+ |X|R|N|S|PartID | (REQUIRED) @@ -25,6 +26,7 @@ T/K: |TID|Y| KEYIDX | (OPTIONAL) Our VP8 packet struct in [backend/src/transcoding/vp8.go](../backend/src/transcoding/vp8.go) from [backend/src/transcoding/vp8.go](../backend/src/transcoding/vp8.go) + ```go type VP8Packet struct { // Required Header @@ -53,6 +55,7 @@ type VP8Packet struct { * We used [libvpx-go](https://github.com/xlab/libvpx-go) as codec, we didn't implement the VP8 codec. from [backend/src/transcoding/vp8.go](../backend/src/transcoding/vp8.go) + ```go func (d *VP8Decoder) Run() { @@ -116,24 +119,26 @@ func (d *VP8Decoder) Run() { ``` * If the function call succeeds, + ```go img := vpx.CodecGetFrame(d.context, &iter) ``` + * We call img.Deref() to convert decoded C structures as Go wrapper variables + ```go img.Deref() ``` + * If everything has gone OK, save the image as a JPEG file by [jpeg.Encode](https://pkg.go.dev/image/jpeg#Encode) * You can see your caught keyframes at /backend/output/ folder as shoot1.jpg, shoot2.jpg, etc... if multiple keyframes were caught. - * As you can see below, we received multiple RTP packets containing VP8 video data, in different packet lengths, then we caught a keyframe from these packets, concatenate them, then created and saved image. - * At the end of our journey, we saw the "[INFO] Image file saved: ../output/shoot1.jpg" log line! All of our these efforts are to achieve this....  - Sources: + * [How to convert VP8 interframe into image with Pion/Webrtc? (Stackoverflow)](https://stackoverflow.com/questions/68859120/how-to-convert-vp8-interframe-into-image-with-pion-webrtc) * [RFC: RTP Payload Format for VP8 Video](https://tools.ietf.org/id/draft-ietf-payload-vp8-05.html) diff --git a/docs/09-CONCLUSION.md b/docs/09-CONCLUSION.md index f7cc712..57a38ff 100644 --- a/docs/09-CONCLUSION.md +++ b/docs/09-CONCLUSION.md @@ -1,8 +1,8 @@ # **9. CONCLUSION** -If you really read all of my journey in this walkthrough documentation, I want to congratulate you for your perseverance, patience, and durability :) Also, I want to thank you for your interest. +If you really read all of my journey in this walkthrough documentation, I want to congratulate you for your perseverance, patience, and durability :blush: Also, I want to thank you for your interest. -If you liked this repo, you can give a star on Github :) +If you liked this repo, you can give a star :star: on GitHub. Your support and feedback not only help the project improve and grow but also contribute to reaching a wider audience within the community. Additionally, it motivates me to create even more innovative projects in the future. Also thanks to contributors of the awesome sources which were referred during development of this project and writing this documentation. You can find these sources in [README](../README.md), also in between the lines. diff --git a/docs/images/icon.svg b/docs/images/icon.svg new file mode 100644 index 0000000..00d9327 --- /dev/null +++ b/docs/images/icon.svg @@ -0,0 +1,4 @@ + \ No newline at end of file diff --git a/docs/mkdocs/.gitignore b/docs/mkdocs/.gitignore new file mode 100644 index 0000000..ec32b66 --- /dev/null +++ b/docs/mkdocs/.gitignore @@ -0,0 +1,12 @@ +* +!.gitignore +!mkdocs.yml.template +!*.sh +!stylesheets +!stylesheets/**/* +!javascripts +!javascripts/**/* +!assets +!assets/**/* +!extra-content +!extra-content/**/* diff --git a/docs/mkdocs/assets/icon.png b/docs/mkdocs/assets/icon.png new file mode 100644 index 0000000000000000000000000000000000000000..546b66b30cac403a0fdc4b809ee54a63ee955a68 GIT binary patch literal 24913 zcmcG$WmHse{4cs^qy*_yBm^WSl#*@{kS>W~=tjD01VI5QLAs
**WebRTC Nuts and Bolts**
+
+[](https://www.linkedin.com/in/alper-dalkiran/)
+[](https://twitter.com/aalperdalkiran)
+
+
+
+!!! info "Welcome!"
+
+ This documentation website is a customized version of original documentation of the [:fontawesome-brands-github: WebRTC Nuts and Bolts repository](https://github.com/adalkiran/webrtc-nuts-and-bolts). You can find the running Go implementation of the project codes in this repository.
+
+A holistic way of understanding how WebRTC and its protocols run in practice, **with code and detailed documentation**. "The nuts and bolts" (practical side instead of theoretical facts, pure implementation details) of required protocols without using external dependencies or libraries.
+
+When you run the project and follow the instructions, web page initializes the webcam, does handshake with the backend application (executes several WebRTC processes), at the end, the backend catches keyframe images and saves them as JPEG image files. You can see your caught keyframes at /backend/output/ folder as shoot1.jpg, shoot2.jpg etc... if multiple keyframes were caught.
+
+You can track which steps taken during this journey by debugging or tracking the output at console.
+
+
+
+## :thought_balloon: **WHY THIS PROJECT?**
+
+This project was initially started to learn Go language and was made for experimental and educational purposes only, not for production use.
+
+After some progress on the development, I decided to pivot my experimental work to a walkthrough document. Because although there are lots of resources that exist already on the Internet, they cover small chunks of WebRTC concepts or protocols atomically. And they use the standard way of inductive method which teach in pieces then assemble them.
+
+But my style of learning leans on the deductive method instead of others, so instead of learning atomic pieces and concepts first, going linearly from beginning to the end, and learning an atomic piece on the time when learning this piece is required.
+
+## :dart: **COVERAGE**
+
+Web front-end side: Pure TypeScript implementation:
+
+* Communicate with signaling backend WebSocket,
+* Gathering webcam streaming track from browser and send this track to backend via UDP.
+
+Server back-end side: Pure Go language implementation:
+
+* A simple signaling back-end WebSocket to transfer [SDP (Session Description Protocol)](https://en.wikipedia.org/wiki/Session_Description_Protocol) using [Gorilla WebSocket](https://github.com/gorilla/websocket) library.
+* Single port UDP listener, supports demultiplexing different data packet types (STUN, DTLS handshake, SRTP, SRTCP) coming from the same UDP connection.
+* Protocol implementations of (only required parts):
+ * [STUN (Session Traversal Utilities for NAT)](https://en.wikipedia.org/wiki/STUN) for discovering external IP behind NAT by a STUN server and replying to the client's STUN binding request came by UDP connection.
+ * [DTLS (Datagram Transport Layer Security)](https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security) for secure handshake, authenticating each oter, and crypto key exchange process. DTLS is similar to [TLS (Transport Layer Security)](https://tr.wikipedia.org/wiki/Transport_Layer_Security), DTLS runs over UDP instead of TCP. This project supports only DTLS v1.2.
+ * [RTP (Real-time Transport Protocol)](https://en.wikipedia.org/wiki/Real-time_Transport_Protocol) for transferring media packets in fragments.
+ * [SRTP (Secure Real-time Transport Protocol)](https://en.wikipedia.org/wiki/Secure_Real-time_Transport_Protocol), a secure version of RTP.
+* Only header parsing for [VP8 video format](https://en.wikipedia.org/wiki/VP8) to depacketizing fragmented packets to construct a video frame. [libvpx-go](https://github.com/xlab/libvpx-go) was used for decoding VP8 keyframe as image.
+* [github.com/fatih/color](https://github.com/fatih/color) was used while printing colored output on console while logging.
+* Implementation of TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 [cipher suite](https://www.keyfactor.com/blog/cipher-suites-explained/) support using [Go Cryptography](https://pkg.go.dev/golang.org/x/crypto) library.
+
+## :package: **INSTALLATION and RUNNING**
+
+Installation and building instructions are described at [:fontawesome-brands-github: GitHub README](https://github.com/adalkiran/webrtc-nuts-and-bolts#package-installation-and-running).
+
+## :bricks: **ASSUMPTIONS**
+
+Full-compliant WebRTC libraries should support a wide range of protocol details defined in RFC documents, client/server implementation differences, fallbacks for different protocol versions, a wide variety of cipher suites and media encoders/decoders. Also should be implemented as state machines, because WebRTC contains has some parts which managed as state machines, eg: [ICE (Interactive Connectivity Establishment)](https://en.wikipedia.org/wiki/Interactive_Connectivity_Establishment), [DTLS (Datagram Transport Layer Security)](https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security) handshake, etc...
+
+In **WebRTC Nuts and Bolts** scenario, some assumptions have been made to focus only on required set of details.
+
+| Full-compliant WebRTC libraries | WebRTC Nuts and Bolts |
+|---|---|
+| WebRTC has no client or server concepts in its [peer-to-peer](https://tr.wikipedia.org/wiki/Peer-to-peer) nature, there are controlling or controlled peers. | This project aims to act as listener server and it only receives media, not sends. To make the code more simplistic and cleaner; the concepts "client" instead of "local peer" and "server" instead of "remote peer" has been used. |
+| Should support both controlling and controlled roles. | Go language side will act only as server (ICE controlling), SDP offer will come from this side, then SDP answer will be expected from the client. |
+| For separation of concerns and to maintain architectural extensibility, all WebRTC libraries were implemented as separate packages/repos (STUN package, DTLS package, SRTP package, etc...) | To keep it simple, this project was designed as [monorepo](https://en.wikipedia.org/wiki/Monorepo) but separated into packages. This choice depends on architectural needs and technical maintenance needs. |
+| Should support DTLS fragmentation. | DTLS fragmentation is not supported. |
+| Should support multiple cipher suites for compatibility with different types of peers. More cipher suites can be found at [here](https://developers.cloudflare.com/ssl/ssl-tls/cipher-suites/). | Only TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 is supported. |
+| Should implement packet reply detection, handling corrupted packets, handling unordered packet sequences and packet losses, byte array length checks, lots of security protections against cyberattacks, etc... | This project was developed to run in only ideal conditions. Incoming malicious packets were not considered. |
+
+## :star: **CONTRIBUTING and SUPPORTING the PROJECT**
+
+You are welcome to [create issues](https://github.com/adalkiran/webrtc-nuts-and-bolts/issues/new) to report any bugs or problems you encounter. At present, I'm not sure whether this project should be expanded to cover more concepts or not. Only time will tell :blush:.
+
+If you liked and found my project helpful and valuable, I would greatly appreciate it if you could give the repo a star :star: on [:fontawesome-brands-github: GitHub](https://github.com/adalkiran/webrtc-nuts-and-bolts). Your support and feedback not only help the project improve and grow but also contribute to reaching a wider audience within the community. Additionally, it motivates me to create even more innovative projects in the future.
+
+## :book: **RESOURCES**
+
+I want to thank to contributors of the awesome sources which were referred during development of this project and writing this documentation. You can find these sources below, also in between the lines in code and documentation.
+
+* [Wikipedia](https://en.wikipedia.org)
+* [WebRTC For The Curious](https://webrtcforthecurious.com): Awesome resource on theoretical concepts of WebRTC. It is vendor agnostic. Created by creators of [Pion project](https://github.com/pion)
+* [Pion project](https://github.com/pion)
+ * [Pion DTLS](https://github.com/pion/dtls): A library for DTLS protocol, developed in Go. Some parts about cryptography used with from this project, with modifications.
+ * [Pion SRTP](https://github.com/pion/srtp): A library for SRTP protocol, developed in Go. Some parts about cryptography used with from this project, with modifications.
+* [Jitsi](https://github.com/jitsi)
+ * [Jitsi ice4j](https://github.com/jitsi/ice4j): A library for ICE processes including gathering ICE candidates, developed in Java and Kotlin. You can start to explore from [here](https://github.com/jitsi/ice4j/blob/d7c0e27a1cde7b877b34d8bb68dc39f18dc45f16/src/main/java/org/ice4j/ice/harvest/SinglePortUdpHarvester.java) and [here](https://github.com/jitsi/ice4j/blob/d7c0e27a1cde7b877b34d8bb68dc39f18dc45f16/src/main/java/org/ice4j/ice/harvest/AbstractUdpListener.java#L47)
+ * [Jitsi Media Transform](https://github.com/jitsi/jitsi-media-transform): A library for ICE processes including gathering ICE candidates, developed in Java and Kotlin. You can find different protocol implementations [here](https://github.com/jitsi/jitsi-media-transform/tree/master/src/main/kotlin/org/jitsi/nlj)
+ * [Jitsi Videobridge](https://github.com/jitsi/jitsi-videobridge): A server application that orchestrates these processes and serves API interfaces, developed in Java and Kotlin
+* [The Bouncy Castle Crypto Package For Java](https://github.com/bcgit/bc-java): A library for TLS processes and cryptography, developed in Java.
+* [Tinydtls](https://github.com/eclipse/tinydtls): A library for DTLS processes, developed in C.
+* [Mozilla Web Docs: WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API): A documentation on WebRTC API at browser side.
+* Several RFC Documents: In code and documentation of this project, you can find several RFC document links cited.
+
+## :scroll: **LICENSE**
+
+WebRTC Nuts and Bolts is licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/adalkiran/webrtc-nuts-and-bolts/blob/main/LICENSE) for the full license text.
diff --git a/docs/mkdocs/javascripts/mathjax.js b/docs/mkdocs/javascripts/mathjax.js
new file mode 100644
index 0000000..421c6a0
--- /dev/null
+++ b/docs/mkdocs/javascripts/mathjax.js
@@ -0,0 +1,20 @@
+window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+ };
+
+ document$.subscribe(() => {
+ MathJax.startup.output.clearCache()
+ MathJax.typesetClear()
+ MathJax.texReset()
+ MathJax.typesetPromise()
+ })
+
\ No newline at end of file
diff --git a/docs/mkdocs/mkdocs.yml.template b/docs/mkdocs/mkdocs.yml.template
new file mode 100644
index 0000000..7fa0970
--- /dev/null
+++ b/docs/mkdocs/mkdocs.yml.template
@@ -0,0 +1,102 @@
+site_name: WebRTC Nuts and Bolts
+site_url: https://adalkiran.github.io/webrtc-nuts-and-bolts/
+site_author: Adil Alper DALKIRAN
+site_description: A holistic way of understanding how WebRTC and its protocols run in practice, with code and detailed documentation.
+copyright: Copyright © 2022 - present, Adil Alper DALKIRAN. All rights reserved.
+repo_url: https://github.com/adalkiran/webrtc-nuts-and-bolts
+repo_name: adalkiran/webrtc-nuts-and-bolts
+
+theme:
+ name: 'material'
+ logo: 'assets/icon.svg'
+ favicon: 'assets/icon.png'
+ features:
+ - toc.follow
+ - toc.integrate
+ - navigation.tabs
+ - navigation.tabs.sticky
+ - navigation.top
+ - navigation.tracking
+ - navigation.footer
+ - content.code.copy
+ icon:
+ repo: fontawesome/brands/github
+ palette:
+ # Palette toggle for automatic mode
+ - media: "(prefers-color-scheme)"
+ toggle:
+ icon: material/brightness-auto
+ name: Switch to light mode
+
+ # Palette toggle for light mode
+ - media: "(prefers-color-scheme: light)"
+ scheme: default
+ toggle:
+ icon: material/weather-night
+ name: Switch to dark mode
+
+ # Palette toggle for dark mode
+ - media: "(prefers-color-scheme: dark)"
+ scheme: slate
+ toggle:
+ icon: material/weather-sunny
+ name: Switch to system preference
+
+extra_css:
+ - stylesheets/custom.css
+
+nav:
+ - LLaMA Nuts and Bolts: '../llama-nuts-and-bolts'
+ - 'WebRTC Nuts and Bolts':
+{{navigation_placeholder}}
+ - 'Contact': 'https://www.linkedin.com/in/alper-dalkiran/'
+
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ name: 'adalkiran'
+ link: https://github.com/adalkiran
+ - icon: fontawesome/brands/x-twitter
+ name: '@aadalkiran'
+ link: https://www.linkedin.com/in/alper-dalkiran/
+ - icon: fontawesome/brands/linkedin
+ name: 'in/alper-dalkiran'
+ link: https://www.linkedin.com/in/alper-dalkiran/
+ analytics:
+ provider: google
+ property: G-05VMCF3NF0
+# consent:
+# title: Cookie consent
+# description: >-
+# We use cookies to recognize your repeated visits and preferences, as well
+# as to measure the effectiveness of our documentation and whether users
+# find what they're searching for. With your consent, you're helping us to
+# make our documentation better.
+
+markdown_extensions:
+ - admonition
+ - toc:
+ permalink: true
+ - md_in_html
+ - pymdownx.arithmatex:
+ generic: true
+ inline_syntax: ['dollar']
+ - pymdownx.highlight:
+ anchor_linenums: true
+ line_spans: __span
+ pygments_lang_class: true
+ use_pygments: true
+ - pymdownx.inlinehilite
+ - pymdownx.snippets
+ - pymdownx.superfences
+ - pymdownx.emoji:
+ emoji_index: !!python/name:material.extensions.emoji.twemoji
+ emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+plugins:
+ - social
+
+extra_javascript:
+ - javascripts/mathjax.js
+ - https://polyfill.io/v3/polyfill.min.js?features=es6
+ - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
diff --git a/docs/mkdocs/prepare-mkdocs.sh b/docs/mkdocs/prepare-mkdocs.sh
new file mode 100755
index 0000000..0821be0
--- /dev/null
+++ b/docs/mkdocs/prepare-mkdocs.sh
@@ -0,0 +1,66 @@
+#!/bin/sh
+
+set -e
+
+cd mkdocs
+rm -rf docs && mkdir -p docs
+cp -r ../*.md ../images ./stylesheets ./javascripts ./assets ./docs
+
+rm ./docs/README.md
+cp ./extra-content/*.md ./docs
+
+GITHUB_URL="https://github.com/adalkiran/webrtc-nuts-and-bolts"
+
+GITHUB_CONTENT_PREFIX="$GITHUB_URL/blob/main"
+
+nav_items=""
+
+for file in ./docs/*.md; do
+
+ # Remove footer navigation
+ sed -i -e ':a;N;$!ba; s/\s*\s*---*.*//g; ta' "$file" + + # Edit same level paths + sed -i -e 's/\](\.\//\](/g' "$file" + + # Edit upper level paths + sed -i -e "s,\(\[[^\[]*\]\)(\.\.\/\([^)]*\)),\1($GITHUB_CONTENT_PREFIX\/\2),g" "$file" + sed -i -e "s,\(\[.*\]\)(\.\.\/\([^)]*\)),\1($GITHUB_CONTENT_PREFIX\/\2),g" "$file" + sed -i -e "s,\(\[.*\]\)(\([^)]*\.ipynb\)),\1($GITHUB_CONTENT_PREFIX\/docs\/\2),g" "$file" + + # Edit img tag paths + sed -i -e 's/src="images\//src="..\/images\//g' "$file" + + # Edit external links + sed -i -e "/\!\[/!s,\[\([^\[]*\)\](http\([^)]*\)),\\1\<\/a\>,g" "$file" + sed -i -e "/\!\[/!s,\[\(.*\)\](http\([^)]*\)),\\1\<\/a\>,g" "$file" + + file_name=$(basename "$file") + first_line=$(head -1 "$file") + title=$(echo "$first_line" | sed -e 's/^[^\.]*\. \(.*\)\*\*/\1/g') + chapter_num=$(echo "$first_line" | sed -e 's/^[^0-9]*\([0-9]*\)\..*/\1/g') + case $first_line in + "---"*) + nav_items="\n - '$file_name'${nav_items}" + ;; + *) + if [ ${#chapter_num} -lt 3 ]; then + chapter_num=$(expr $chapter_num + 1) + nav_items="${nav_items}\n - '$file_name'" + else + chapter_num=0 + nav_items="\n - '$file_name'${nav_items}" + fi + echo "--- +title: $title +type: docs +menus: + - main +weight: $chapter_num +--- +" | cat - "$file" > temp && mv temp "$file" + ;; + esac +done + +cat mkdocs.yml.template | sed -e "s/{{navigation_placeholder}}/${nav_items}/g" > mkdocs.yml diff --git a/docs/mkdocs/stylesheets/custom.css b/docs/mkdocs/stylesheets/custom.css new file mode 100644 index 0000000..bfe7afb --- /dev/null +++ b/docs/mkdocs/stylesheets/custom.css @@ -0,0 +1,3 @@ +mjx-container { + font-size: 16px!important; +} \ No newline at end of file