Tls 1.3 client hello structure. in C supported on Linux Userspace. Can anyone please tell what struct should look like to represent client hello

Question

I like to understand tls by code. tls 1.3 and cipher suits so I started and at first I found in tls 1.3 handshake is client initiate the handshake with the server with hello message. On the documentation on this page https://datatracker.ietf.org/doc/html/rfc8446#section-4.1.2

It says this

Structure of this message:

  uint16 ProtocolVersion;
  opaque Random[32];

  uint8 CipherSuite[2];    /* Cryptographic suite selector */

  struct {
      ProtocolVersion legacy_version = 0x0303;    /* TLS v1.2 */
      Random random;
      opaque legacy_session_id<0..32>;
      CipherSuite cipher_suites<2..2^16-2>;
      opaque legacy_compression_methods<1..2^8-1>;
      Extension extensions<8..2^16-1>;
  } ClientHello;

And so I never seen in C's types called opaque is it supported by gcc or do I need to include any glibc header .h file or what do I need?

So I believe there should be another structure struct CipherSuite how to represent this struct what fileds this struct contains. do u know this? Searching about how to represent this on google I found some library I could not understand what it is. wasnt in C. and other search result II could not understand, but what I understood is

Put simply, a cipher suite is a collection of different algorithms, protocols, and all the other good stuff that encrypts and decrypts data between two communicating parties 

so struct CipherSuite contains algorithon(s) means multiple algorithms so array of some algorithms whats the size of this two D array means leaght and breath of array so

struct CipherSuite { char some_algorithms[unknow][unknow]

so how many algorithms and what is the size of each of these algorithms in bytes or are there any other struct included to also represent CipherSuite? can anyone please tell me this? thanks

and what is Extension in struct Clienthello whats this Extension extensions<8..2^16-1>; ?

Answer 1

This structure is defined in RFC 8446 and it is pseudo code, it does not map as is directly to any kind of programming language, so it is not C.

See https://datatracker.ietf.org/doc/html/rfc8446#section-3 that explains the model used and the vocabulary.

And so I never seen in C's types called opaque

opaque here means that for the TLS "engine", the content does not matter, it can be considered gibberish (random). It certainly makes sense for other parts, but not for TLS. Take for example this sentence in the specification:

Application Data messages contain data that is opaque to TLS.

So opaque means "unstructured" at this level.

So I believe there should be another structure struct CipherSuite how to represent this struct what fileds this struct contains. do u know this?

cipherSuite appears like that:

      uint8 CipherSuite[2];    /* Cryptographic suite selector */

      struct {
          ProtocolVersion legacy_version = 0x0303;    /* TLS v1.2 */
          Random random;
          opaque legacy_session_id<0..32>;
          CipherSuite cipher_suites<2..2^16-2>;
          opaque legacy_compression_methods<1..2^8-1>;
          Extension extensions<8..2^16-1>;
      } ClientHello;

in ClientHello message defined in §4.1.2

uint8 CipherSuite[2] means that a ciphersuite is 2 items, each one being an unsigned byte (uint8).

You can see values at "B.4. Cipher Suites" which is:

              +------------------------------+-------------+
              | Description                  | Value       |
              +------------------------------+-------------+
              | TLS_AES_128_GCM_SHA256       | {0x13,0x01} |
              |                              |             |
              | TLS_AES_256_GCM_SHA384       | {0x13,0x02} |
              |                              |             |
              | TLS_CHACHA20_POLY1305_SHA256 | {0x13,0x03} |
              |                              |             |
              | TLS_AES_128_CCM_SHA256       | {0x13,0x04} |
              |                              |             |
              | TLS_AES_128_CCM_8_SHA256     | {0x13,0x05} |
              +------------------------------+-------------+

So each of the 5 defined cipher suite in TLS 1.3 is mapped to 2 bytes, first one always being with value 0x13 for all 5 cases.

so how many algorithms and what is the size of each of these algorithms in bytes or are there any other struct included to also represent CipherSuite?

If you really want to implement TLS 1.3 at a low level you really need to read RFC 8446 fully. Multiple times. From top to bottom and bottom to top. There are even sections specifically with advices on implementation. BUT do this only if you want to learn, otherwise any language today should have already a proper library handling all the low level details of TLS 1.3 and you should use that library in your code, not reinvent it.

and what is Extension in struct Clienthello whats this Extension extensions<8..2^16-1>;?

It is explained later on in the text:

extensions: Clients request extended functionality from servers by sending data in the extensions field. The actual "Extension" format is defined in Section 4.2. In TLS 1.3, the use of certain extensions is mandatory, as functionality has moved into extensions to preserve ClientHello compatibility with previous versions of TLS. Servers MUST ignore unrecognized extensions.

With the syntax explained in Section 3, Extension extensions<8..2^16-1> is a variable length vector which means the "extensions" field is a content whose size is from 8 to 2^16-1 bytes, and the content is of type Extension defined elsewhere in the document in section 4.2 as such:

    struct {
        ExtensionType extension_type;
        opaque extension_data<0..2^16-1>;
    } Extension;