Extended Diagnostic Notation (EDN) Use with Transport Layer Security (TLS) Presentation Language (PL) Objects

Introduction Extended Diagnostic Notation (EDN) is a text format, that was originally described to represent CBOR messages as diagnostic notation in and then expanded in . It is a superset of JSON (all valid JSON is valid EDN) that can natively represent binary content, non-finite floating point values, and additional data types (tags and simple values). Since then it has been used to represent YAML messages, especially those that contain binary content or tags. This document defines a convention to represent instances of binary sequences--encoded using the TLS Presentation Language (TLS PL) defined in --using EDN. TLS encoding is used in several other protocols, for example in the Messaging Layer Security (MLS) protocol and the MIMI protocol . TLS PL has a very limited set of patterns. It deals primarily with structs and enums. As a result, it is relatively straightforward to represent TLS encoded data if the TLS PL definitions are available.

Representation of TLS PL in EDN EDN Representations of TLS-encoded instance data always start with the following comment line: # ~~~ tls followed by the struct name, and end with the following comment line: # ~~~. This allows a processor that knows TLS to convert an EDN document back into TLS-encoded binary data. Instances of TLS-encoded structs are represented in EDN as maps with the keys equal to the names of the members. If an enum appears that contains only the values false (0) and true (1), its values are represented in EDN as the simple values false and true. Instances of other TLS-encoded enums are represented as their decimal integer values with an EDN end-of-line comment naming the enum name and the item name. Instances of the following predefined TLS numeric types: uint16, uint32, uint64, plus any variable-length integers (widely used, for example in MLS ) are represented as unsigned decimal integers in EDN. Likewise a single instance of uint8 is represented as an unsigned decimal integer in EDN. Vectors of uint8 (or the opaque type) are represented by single quoted strings in EDN. Likewise fixed-length arrays of uint8 are represented by single quoted strings in EDN. By default, they are presented as hex-encoded single-quoted strings. If such sequences consist primarily of printable characters Vectors of any other type are represented by an array of that type. For example given the FooBar struct defined below: ; opaque reason; } FooBar; ]]> an instance of that struct could be represented as follows in EDN:

Representation of Variants The optional keyword () is represented as a struct. For example given the following structs: component; } Foo; ]]> An instance of Foo which has an optional Component would be represented by the following snippet of EDN: When absent it would be represented as: In general, the presence of a select construction in TLS PL indicates the conditional presence of additional values in the struct. For example, the struct below: ; }; Extension extensions; } PartialLeafNode; ~~ would be represented as follows in EDN: ~~~ cbor-diag { "leaf_node_source": 1, # enum LeafNodeSource.key_package "lifetime": { "not_before": 1777979674, # 05-May-2026T13:14:34Z "not_after": 1780312474 # 05-Jun-2026T13:14:34Z }, "extensions": [] } ]]> The notation struct {} in TLS PL refers to the absense of a value. It is ignored in the representation of an EDN instance.

Examples

MLS LeafNode The following detailed example represents the LeafNode struct from and embedded structs. It includes additional types from , , and . Given the following TLS structures: ; }; Extension extensions; /* SignWithLabel(., "LeafNodeTBS", LeafNodeTBS) */ opaque signature; } LeafNode; enum { reserved(0), key_package(1), update(2), commit(3), (255) } LeafNodeSource; struct { ProtocolVersion versions; CipherSuite cipher_suites; ExtensionType extensions; ProposalType proposals; CredentialType credentials; } Capabilities; struct { uint64 not_before; uint64 not_after; } Lifetime; struct { ExtensionType extension_type; opaque extension_data; } Extension; struct { CredentialType credential_type; select (Credential.credential_type) { ... case sd_jwt: SdJwt sd_jwt; }; } Credential; struct { Bool compacted; select (compacted) { case true: opaque protected; opaque payload; opaque signature; SdJwtDisclosure disclosures; opaque sd_jwt_key_binding; case false: opaque sd_jwt_kb; }; } SdJwt; enum { false(0), true(1) } Bool; struct { ComponentID component_id; opaque data; } ComponentData; struct { ComponentData component_data; } AppDataDictionary; AppDataDictionary app_data_dictionary; opaque HPKEPublicKey; opaque SignaturePublicKey; /* See the "Messaging Layer Security (MLS)" IANA registries for values */ uint16 CipherSuite; uint16 ExtensionType; uint16 ProposalType; uint16 CredentialType; uint16 ComponentID; ]]> below is an example instance represented in EDN: