Compact TLS 1.3

2.1.1.1. profile

This element identifies the profile being defined. Its binary value is:¶

opaque ProfileID<1..2^8-1>

This encodes the profile ID, if one is specified. IDs whose decoded length is 4 bytes or less are reserved (see Section 6.5). When a reserved value is used (including the default value), other keys MUST NOT appear in the template, and a client MUST NOT accept the template unless it recognizes the ID.¶

In JSON, the profile ID is represented as a hexadecimal-encoded string.¶

2.1.1.2. version

Value: a single ProtocolVersion ([RFC8446], Section 4.1.2) that both parties agree to use. For TLS 1.3, the ProtocolVersion is 0x0304.¶

When this element is included, the supported_versions extension is omitted from ClientHello.extensions.¶

In JSON, the version is represented as an integer (772 = 0x0304 for TLS 1.3).¶

2.1.1.3. cipher_suite

Value: a single CipherSuite ([RFC8446], Section 4.1.2) that both parties agree to use.¶

When this element is included, the ClientHello.cipher_suites and ServerHello.cipher_suite fields are omitted.¶

In JSON, the cipher suite is represented using the "TLS_AEAD_HASH" syntax defined in [RFC8446], Section 8.4.¶

2.1.1.4. dh_group

Value: a single CTLSKeyShareGroup to use for key establishment.¶

struct {
    NamedGroup group_name;
    uint16 key_share_length;
} CTLSKeyShareGroup;

This is equivalent to adding a "supported_groups" extension to every message where that is allowed (i.e. ClientHello and EncryptedExtensions, in TLS 1.3) consisting solely of the group CTLSKeyShareGroup.group_name.¶

Static vectors (see Section 2.1.2):¶

• KeyShareClientHello.client_shares¶

• KeyShareEntry.key_exchange, if CTLSKeyShareGroup.key_share_length is non-zero.¶

In JSON, this value is represented as a dictionary with two keys:¶

• groupName: a string containing the code point name from the TLS Supported Groups registry (e.g., "x25519").¶

• keyShareLength: an integer, defaulting to zero if omitted.¶

2.1.1.5. signature_algorithm

Value: a single CTLSSignatureAlgorithm to use for authentication.¶

struct {
    SignatureScheme signature_scheme;
    uint16 signature_length;
} CTLSSignatureAlgorithm;

This is equivalent to a placing a literal "signature_algorithms" extension consisting solely of CTLSSignatureAlgorithm.signature_scheme in every extensions field where the "signature_algorithms" extension is permitted to appear (i.e. ClientHello and CertificateRequest, in TLS 1.3). When this element is included, CertificateVerify.algorithm is omitted.¶

Static vectors (see Section 2.1.2):¶

• CertificateVerify.signature, if CTLSSignatureAlgorithm.signature_length is non-zero.¶

In JSON, the signature algorithm is listed by the code point name in [RFC8446], Section 4.2.3. (e.g., ecdsa_secp256r1_sha256). In JSON, this value is represented as a dictionary with two keys:¶

• signatureScheme: a string containing the code point name in the TLS SignatureScheme registry (e.g., "ecdsa_secp256r1_sha256").¶

• signatureLength: an integer, defaulting to zero if omitted.¶

2.1.1.6. random

Value: a single uint8.¶

The ClientHello.Random and ServerHello.Random values are truncated to the given length. Where a 32-byte Random is required, the Random is padded to the right with 0s and the anti-downgrade mechanism in [RFC8446], Section 4.1.3 is disabled. IMPORTANT: Using short Random values can lead to potential attacks. The Random length MUST be less than or equal to 32 bytes.¶

• OPEN ISSUE: Karthik Bhargavan suggested the idea of hashing ephemeral public keys and to use the result (truncated to 32 bytes) as random values. Such a change would require a security analysis.¶

In JSON, the length is represented as an integer.¶

2.1.1.7. mutual_auth

Value: a single uint8, with 1 representing "true" and 0 representing "false". All other values are forbidden.¶

If set to true, this element indicates that the client must authenticate with a certificate by sending Certificate and a CertificateVerify message. If the CertificateRequest message does not add information not already conveyed in the template, the server SHOULD omit it.¶

In JSON, this value is represented as true or false.¶

• TODO: It seems like there was an intent to elide the Certificate.certificate_request_context field, but this is not stated explicitly anywhere.¶

2.1.1.8. handshake_framing

Value: uint8, with 0 indicating "false" and 1 indicating "true". If true, handshake messages MUST be conveyed inside a Handshake ([RFC8446], Section 4) struct on reliable, ordered transports, or a DTLSHandshake ([RFC9147], Section 5.2) struct otherwise, and MAY be broken into multiple records as in TLS and DTLS. If false, each handshake message is conveyed in a CTLSHandshake or CTLSDatagramHandshake struct (Section 2.3), which MUST be the payload of a single record.¶

In JSON, this value is represented as true or false.¶

2.1.1.9. client_hello_extensions, server_hello_extensions, encrypted_extensions, and certificate_request_extensions

Value: a single CTLSExtensionTemplate struct:¶

struct {
  Extension predefined_extensions<0..2^16-1>;
  ExtensionType expected_extensions<0..2^16-1>;
  ExtensionType self_delimiting_extensions<0..2^16-1>;
  uint8 allow_additional;
} CTLSExtensionTemplate;

The predefined_extensions field indicates extensions that should be treated as if they were included in the corresponding message. This allows these extensions to be omitted entirely.¶

The expected_extensions field indicates extensions that must be included in the corresponding message, at the beginning of its extensions field. The types of these extensions are omitted when serializing the extensions field of the corresponding message.¶

The self_delimiting_extensions field indicates extensions whose data is self-delimiting. The cTLS implementation MUST be able to parse all these extensions, and all extensions listed in Section 4.2 of [RFC8446].¶

The allow_additional field MUST be 0 (false) or 1 (true), indicating whether additional extensions are allowed here.¶

predefined_extensions and expected_extensions MUST be in strictly ascending order by ExtensionType, and a single ExtensionType MUST NOT appear in both lists. If the version, dh_group, or signature_algorithm element appears in the template, the corresponding ExtensionType MUST NOT appear here. The pre_shared_key ExtensionType MUST NOT appear in either list.¶

• OPEN ISSUE: Are there other extensions that would benefit from special treatment, as opposed to hex values.¶

Static vectors (see Section 2.1.2):¶

• Extension.extension_data for any extension whose type is in self_delimiting_extensions, or is listed in Section 4.2 of [RFC8446] except padding. This applies only to the corresponding message.¶

• The extensions field of the corresponding message, if allow_additional is false.¶

In JSON, this value is represented as a dictionary with three keys:¶

• predefinedExtensions: a dictionary mapping ExtensionType names ([RFC8446], Section 4.2) to values encoded as hexadecimal strings.¶

• expectedExtensions: an array of ExtensionType names.¶

• selfDelimitingExtensions: an array of ExtensionType names.¶

• allowAdditional: true or false.¶

If predefinedExtensions or expectedExtensions is empty, it MAY be omitted.¶

• OPEN ISSUE: Should we have a certificate_entry_extensions element?¶

2.1.1.10. finished_size

Value: uint8, indicating that the Finished value is to be truncated to the given length.¶

• OPEN ISSUE: How short should we allow this to be? TLS 1.3 uses the native hash and TLS 1.2 used 12 bytes. More analysis is needed to know the minimum safe Finished size. See [RFC8446], Appendix E.1 for more on this, as well as https://mailarchive.ietf.org/arch/msg/tls/TugB5ddJu3nYg7chcyeIyUqWSbA. The minimum safe size may vary depending on whether the template was learned via a trusted channel.¶

In JSON, this length is represented as an integer.¶

2.1.1.11. optional

Value: a CTLSTemplate containing elements that are not required to be understood by the client. Server operators MUST NOT place an element in this section unless the server is able to determine whether the client is using it from the client data it receives. A key MUST NOT appear in both the main template and the optional section.¶

In JSON, this value is represented in the same way as the CTLSTemplate itself.¶

2.1.1.12. known_certificates

Value: a CertificateMap struct:¶

struct {
  opaque id<1..2^8-1>;
  opaque cert_data<1..2^16-1>;
} CertificateMapEntry;

struct {
  CertificateMapEntry entries<2..2^24-1>;
} CertificateMap;

Entries in the certificate map must appear in strictly ascending lexicographic order by ID.¶

In JSON, CertificateMap is represented as a dictionary from id to cert_data, which are both represented as hexademical strings:¶

{
  "00": "3082...",
  "01": "3082...",
}

Certificates are a major contributor to the size of a TLS handshake. In order to avoid this overhead when the parties to a handshake have already exchanged certificates, a compression profile can specify a dictionary of "known certificates" that effectively acts as a compression dictionary on certificates.¶

When compressing a Certificate message, the sender examines the cert_data field of each CertificateEntry. If the cert_data matches a value in the known certificates object, then the sender replaces the cert_data with the corresponding key. Decompression works the opposite way, replacing keys with values.¶

Note that in this scheme, there is no signaling on the wire for whether a given cert_data value is compressed or uncompressed. Known certificates objects SHOULD be constructed in such a way as to avoid a uncompressed object being mistaken for compressed one and erroneously decompressed. For X.509, it is sufficient for the first byte of the compressed value (key) to have a value other than 0x30, since every X.509 certificate starts with this byte.¶

This element can be used to compress both client and server certificates. However, in most deployments where client certificates are used, it would be inefficient to encode all client certificates into a single profile. Instead, deployments can define a unique profile for each client, distinguished by the profile ID. Note that the profile ID is sent in cleartext, so this strategy has significant privacy implications.¶