From 8f5aa452e99bb5549f9158d47001792161c608aa Mon Sep 17 00:00:00 2001 From: ID Bot Date: Mon, 21 Oct 2024 16:36:50 +0000 Subject: [PATCH] Script updating gh-pages from 02cbd2f. [ci skip] --- draft-ietf-mls-extensions.html | 600 +++++++++++++++++++++------------ draft-ietf-mls-extensions.txt | 288 +++++++++++----- 2 files changed, 584 insertions(+), 304 deletions(-) diff --git a/draft-ietf-mls-extensions.html b/draft-ietf-mls-extensions.html index f0533d3..650c8c0 100644 --- a/draft-ietf-mls-extensions.html +++ b/draft-ietf-mls-extensions.html @@ -1135,35 +1135,36 @@

2. Safe Extensions

-

The MLS specification is extensible in a variety of ways (see Section 13 of the +

The MLS specification is extensible in a variety of ways (see Section 13 of [RFC9420]) and describes the negotiation and other handling of extensions and their data within the protocol. However, it does not provide guidance on how extensions can or should safely interact with the base MLS protocol. The goal of @@ -1419,7 +1426,7 @@

built on top of the Safe Extension API alongside the built-in mechanisms of the base MLS protocol, defines a number of labels registered in IANA which can be safely used by extensions, so that the only value an extension developer must -add to the IANA registry themselves is a unique ExtensionType.

+add to the IANA registry itself is a unique ExtensionType.

@@ -1444,8 +1451,13 @@

an epoch.

  • -

    Anchor extension-specific state in an MLS group to ensure agreement and manage -state acces authorization across extensions.

    +

    Define new WireFormat, Proposal, Credential, GroupContext, GroupInfo, +KeyPackage, and LeafNode extensions which can interact safely with arbitrary +sets of other current or future Safe Extensions.

    +
    • +
  • +

    Anchor extension-specific state in an MLS group to ensure agreement and manage +state acces authorization across extensions.

    • The Safe Extension API is not an extension itself, it only defines components @@ -1474,43 +1486,153 @@

    extensions or the base MLS.

    -
    +
    +

    +2.1.2. Core Struct Extensions +

    +

    Every type of MLS extension can have data associated with it. The "MLS +Extensions Types" registry historically represented extensibility of four +core structs (GroupContext, GroupInfo, KeyPackage, and LeafNode) +that have far reaching effects on the use of the protocol. The majority of +MLS extensions registered at the time of this writing extend one or more +of these core structs.

    +
      +
    • +

      GroupContext Extensions: Any data in a group context extension is agreed-upon +by all members of the group in the same way as the rest of the group state. As +part of the GroupContext, it is also sent encrypted to new joiners via Welcome +messages and (depending on the architecture of the application) may be +available to external joiners. Note that in some scenarios, the GroupContext +may also be visible to components that implement the delivery service. While +MLS extensions can define arbitrary GroupContext extensions, it is recommended +to make use of ExtensionState extensions to store state in the group's +GroupContext.

      +
      • +
    • +

      GroupInfo Extensions: GroupInfo extensions are included in the GroupInfo +struct and thus sent encrypted and authenticated by the signer of the +GroupInfo to new joiners as part of Welcome messages. It can thus be used as a +confidential and authenticated channel from the inviting group member to new +joiners. Just like GroupContext extensions, they may also be visible to +external joiners or even parts of the delivery service. Unlike GroupContext +extensions, the GroupInfo struct is not part of the group state that all group +members agree on.

      +
      • +
    • +

      KeyPackage Extensions: KeyPackages (and the extensions they include) are +pre-published by individual clients for asynchronous group joining. They are +included in Add proposals and become part of the group state once the Add +proposal is committed. They are, however, removed from the group state when +the owner of the KeyPackage does the first commit with a path. As such, +KeyPackage extensions can be used to communicate data to anyone who wants to +invite the owner to a group, as well as the other members of the group the +owner is added to. Note that KeyPackage extensions are visible to the server +that provides the KeyPackages for download, as well as any part of the +delivery service that can see the public group state.

      +
      • +
    • +

      LeafNode Extensions: LeafNodes are a part of every KeyPackage and thus follow +the same lifecycle. However, they are also part of any commit that includes an +UpdatePath and clients generally have a leaf node in each group they are a member +of. Leaf node extensions can thus be used to include member-specific data in a +group state that can be updated by the owner at any time.

      +
      • +
    +
    +
    +
    +

    -2.1.2. Common Data Structures +2.1.3. Common Data Structures

    -

    Most components of the Safe Extension API use the value ExtensionType which is a -unique uint16 identifier assigned to an extension in the MLS Extension Types -IANA registry (see Section 17.3 of [RFC9420]).

    -

    Most Safe Extension API components also use the following data structure, which -provides domain separation by extension_type of various extension_data.

    -
    +

    The Safe Extension API reuses the ExtensionType and the "MLS Extension +Types" IANA registry used for these core structs (see Section 17.3 of +[RFC9420]), even for safe extensions with no core struct changes. +This is because many extensions modify a core struct, either primarily or +to store state (related to the group or a client) associated with another +aspect of that extension.

    +

    Most Safe Extension API components also use the following data structure, which +provides domain separation by extension_type of various extension_data.

    +
     struct {
   ExtensionType extension_type;
   opaque extension_data<V>;
 } ExtensionContent;
-
    +
    -

    Where extension_type is set to the type of the extension to which the -extension_data belongs.

    -

    If in addition a label is required, the following data structure is used.

    -
    +

    Where extension_type is set to the type of the extension to which the +extension_data belongs.

    +

    When a label is required for an extension, the following data structure is +used.

    +
     struct {
   opaque label;
   ExtensionContent extension_content;
 } LabeledExtensionContent;
-
    + +
    +
    +
    +
    +
    +

    +2.1.4. Negotiating Support for Safe Extensions +

    +

    MLS defines a Capabilities struct for LeafNodes (in turn used in +KeyPackages), which describes which extensions are supported by the +associated node. +However, that struct (defined in Section 7.2 of [RFC9420]) only has +fields for a subset of the extensions possible in MLS, as reproduced below.

    +
    +
    +...
+struct {
+    ProtocolVersion versions<V>;
+    CipherSuite cipher_suites<V>;
+    ExtensionType extensions<V>;
+    ProposalType proposals<V>;
+    CredentialType credentials<V>;
+} Capabilities;
+...
+
    +
    +

    Therefore, all safe extensions MUST be represented by their extension_type +in the extensions vector (originally intended for core struct extensions), +regardless of their type.

    +

    If the LeafNode supports any safe extension Credentials, the credentials +vector will contain any non-safe credentials supported, plus the extension_credential defined in {extension-credential}.

    +

    If the LeafNode supports any safe extension Proposals, then proposals will +contain any non-default non-safe extensions, and whichever safe extension +proposal types defined in {mls-proposal-types} are relevant to the supported +safe proposals.

    +

    Likewise, the required_capabilities GroupContext extension (defined +in Section 11.1 of [RFC9420] and reproduced below) contains all +mandatory to support non-default non-safe, and safe extensions in its +extension_types vector. Its credential_types vector contains any +mandatory non-safe credential types, plus extensions_credential if any +safe credential is required. Its proposal_types vector contains any +mandatory to support non-default non-safe Proposals, and the relevant safe +proposal type or types corresponding to any required safe proposals.

    +
    +
    +struct {
+    ExtensionType extension_types<V>;
+    ProposalType proposal_types<V>;
+    CredentialType credential_types<V>;
+} RequiredCapabilities;
+
    -
    +

    -2.1.3. Hybrid Public Key Encryption (HPKE) +2.1.5. Hybrid Public Key Encryption (HPKE)

    -

    This component of the Safe Extension API allows extensions to make use of all +

    This component of the Safe Extension API allows extensions to make use of all HPKE key pairs generated by MLS. An extension identified by an ExtensionType can use any HPKE key pair for any operation defined in [RFC9180], such as encryption, exporting keys and the PSK mode, as long as the info input to @@ -1518,148 +1640,148 @@

    extension_type set to ExtensionType. The extension_data can be set to an arbitrary Context specified by the extension designer (and can be empty if not needed). For example, an extension can use a key pair PublicKey, PrivateKey to -encrypt data as follows:

    -
    +encrypt data as follows:

    +
     SafeEncryptWithContext(ExtensionType, PublicKey, Context, Plaintext) =
     SealBase(PublicKey, LabeledExtensionContent, "", Plaintext)
 
 SafeDecryptWithContext(ExtensionType, PrivateKey, Context, KEMOutput, Ciphertext) =
     OpenBase(KEMOutput, PrivateKey, LabeledExtensionContent, "", Ciphertext)
-
    +
    -

    Where the fields of LabeledExtensionContent are set to

    -
    +

    Where the fields of LabeledExtensionContent are set to

    +
     label = "MLS 1.0 ExtensionData"
 extension_type = ExtensionType
 extension_data = Context
-
    +
    -

    For operations involving the secret key, ExtensionType MUST be set to the +

    For operations involving the secret key, ExtensionType MUST be set to the ExtensionType of the implemented extension, and not to the type of any other extension. In particular, this means that an extension cannot decrypt data meant -for another extension, while extensions can encrypt data to other extensions.

    -

    In general, a ciphertext encrypted with a PublicKey can be decrypted by any +for another extension, while extensions can encrypt data to other extensions.

    +

    In general, a ciphertext encrypted with a PublicKey can be decrypted by any entity who has the corresponding PrivateKey at a given point in time according to the MLS protocol (or extension). For convenience, the following list -summarizes lifetimes of MLS key pairs.

    +summarizes lifetimes of MLS key pairs.

      -
    • -

      The key pair of a non-blank ratchet tree node. The PrivateKey of such a key pair +

    • +

      The key pair of a non-blank ratchet tree node. The PrivateKey of such a key pair is known to all members in the node’s subtree. In particular, a PrivateKey of a leaf node is known only to the member in that leaf. A member in the subtree stores the PrivateKey for a number of epochs, as long as the PublicKey does not change. The key pair of the root node SHOULD NOT be used, since the external key -pair recalled below gives better security.

      +pair recalled below gives better security.

      • -
    • -

      The external_priv, external_pub key pair used for external initialization. The +

    • +

      The external_priv, external_pub key pair used for external initialization. The external_priv key is known to all group members in the current epoch. A member stores external_priv only for the current epoch. Using this key pair gives better security guarantees than using the key pair of the root of the ratchet -tree and should always be preferred.

      +tree and should always be preferred.

      • -
    • -

      The init_key in a KeyPackage and the corresponding secret key. The secret key +

    • +

      The init_key in a KeyPackage and the corresponding secret key. The secret key is known only to the owner of the KeyPackage and is deleted immediately after it -is used to join a group.

      +is used to join a group.

    -
    +

    -2.1.4. Signature Keys +2.1.6. Signature Keys

    -

    MLS session states contain a number of signature keys including the ones in the +

    MLS session states contain a number of signature keys including the ones in the LeafNode structs. Extensions can safely sign content and verify signatures using these keys via the SafeSignWithLabel and SafeVerifyWithLabel functions, respectively, much like how the basic MLS protocol uses SignWithLabel and -VerifyWithLabel.

    -

    In more detail, an extension identified by ExtensionType should sign and verify using:

    -
    +VerifyWithLabel.

    +

    In more detail, an extension identified by ExtensionType should sign and verify using:

    +
     SafeSignWithLabel(ExtensionType, SignatureKey, Label, Content) =
     SignWithLabel(SignatureKey, "LabeledExtensionContent", LabeledExtensionContent)
 
 SafeVerifyWithLabel(ExtensionType, VerificationKey, Label, Content, SignatureValue) =
     VerifyWithLabel(VerificationKey, "LabeledExtensionContent", LabeledExtensionContent, SignatureValue)
-
    +
    -

    Where the fields of LabeledExtensionContent are set to

    -
    +

    Where the fields of LabeledExtensionContent are set to

    +
     label = Label
 extension_type = ExtensionType
 extension_data = Content
-
    +
    -

    For signing operations, the ExtensionType MUST be set to the ExtensionType of +

    For signing operations, the ExtensionType MUST be set to the ExtensionType of the implemented extension, and not to the type of any other extension. In particular, this means that an extension cannot produce signatures in place of other extensions. However, extensions can verify signatures computed by other extensions. Note that domain separation is ensured by explicitly including the -ExtensionType with every operation.

    +ExtensionType with every operation.

    -
    +

    -2.1.5. Exporting Secrets +2.1.7. Exporting Secrets

    -

    An extension can use MLS as a group key agreement protocol by exporting symmetric keys. +

    An extension can use MLS as a group key agreement protocol by exporting symmetric keys. Such keys can be exported (i.e. derived from MLS key material) in two phases per epoch: Either at the start of the epoch, or during the epoch. Derivation at the start of the epoch has the added advantage that the source key material is deleted after use, allowing the derived key material to be deleted later even during the same MLS epoch to achieve forward secrecy. The following protocol -secrets can be used to derive key from for use by extensions:

    +secrets can be used to derive key from for use by extensions:

      -
    • -

      epoch_secret at the beginning of an epoch

      +
    • +

      epoch_secret at the beginning of an epoch

      • -
    • -

      extension_secret during an epoch

      +
    • +

      extension_secret during an epoch

    -

    The extension_secret is an additional secret derived from the epoch_secret at +

    The extension_secret is an additional secret derived from the epoch_secret at the beginning of the epoch in the same way as the other secrets listed in Table -4 of [RFC9420] using the label "extension".

    -

    Any derivation performed by an extension either from the epoch_secret or the -extension_secret has to use the following function:

    -
    +4 of [RFC9420] using the label "extension".

    +

    Any derivation performed by an extension either from the epoch_secret or the +extension_secret has to use the following function:

    +
     DeriveExtensionSecret(Secret, Label) =
   ExpandWithLabel(Secret, "ExtensionExport " + ExtensionType + " " + Label)
-
    +
    -

    Where ExpandWithLabel is defined in Section 8 of [RFC9420] and where ExtensionType -MUST be set to the ExtensionType of the implemented extension.

    +

    Where ExpandWithLabel is defined in Section 8 of [RFC9420] and where ExtensionType +MUST be set to the ExtensionType of the implemented extension.

    -
    +

    -2.1.6. Pre-Shared Keys (PSKs) +2.1.8. Pre-Shared Keys (PSKs)

    -

    PSKs represent key material that is injected into the MLS key schedule when +

    PSKs represent key material that is injected into the MLS key schedule when creating or processing a commit as defined in Section 8.4 of [RFC9420]. Its injection into the key schedule means that all group members have to agree on -the value of the PSK.

    -

    While PSKs are typically cryptographic keys which due to their properties add to +the value of the PSK.

    +

    While PSKs are typically cryptographic keys which due to their properties add to the overall security of the group, the PSK mechanism can also be used to ensure that all members of a group agree on arbitrary pieces of data represented as octet strings (without the necessity of sending the data itself over the wire). For example, an extension can use the PSK mechanism to enforce that all group -members have access to and agree on a password or a shared file.

    -

    This is achieved by creating a new epoch via a PSK proposal. Transitioning to -the new epoch requires using the information agreed upon.

    -

    To facilitate using PSKs in a safe way, this document defines a new PSKType for +members have access to and agree on a password or a shared file.

    +

    This is achieved by creating a new epoch via a PSK proposal. Transitioning to +the new epoch requires using the information agreed upon.

    +

    To facilitate using PSKs in a safe way, this document defines a new PSKType for extensions. This provides domain separation between pre-shared keys used by the -core MLS protocol and applications, and between those used by different extensions.

    -
    +core MLS protocol and applications, and between those used by different extensions.

    +
     enum {
   reserved(0),
@@ -1686,56 +1808,66 @@ 
    
   };
   opaque psk_nonce<V>;
 } PreSharedKeyID;
-
    +
    -
    +

    -2.1.7. Extension Designer Tools +2.1.9. Extension Designer Tools

    -

    The safe extension API allows extension designers to sign and encrypt payloads +

    The safe extension API allows extension designers to sign and encrypt payloads without the need to register their own IANA labels. Following the same pattern, this document also provides ways for extension designers to define their own wire formats, proposals, credentials, and for structured data in the -Additional Authenticated Data.

    +Additional Authenticated Data.

    +
    +
    +
    +2.1.9.1. Core Struct Extensions +
    +

    Each extension of the GroupContext, GroupInfo, KeyPackage, and/or LeafNode +structs is required to define the format of its data. These types of +extensions SHOULD NOT use the ExtensionContent struct since the extension_type is already in the parent data structure.

    +
    +
    -
    +
    -2.1.7.1. Wire Formats +2.1.9.2. Wire Formats
    -

    Extensions can define their own MLS messages by using the mls_extension_message +

    Extensions can define their own MLS messages by using the mls_extension_message MLS Wire Format. The mls_extension_message Wire Format is IANA registered specifically for this purpose and extends the select statement in the MLSMessage -struct as follows:

    -
    +struct as follows:

    +
     case mls_extension_message:
     ExtensionContent extension_content;
-
    +
    -

    The extension_type in extension_content MUST be set to the type of the +

    The extension_type in extension_content MUST be set to the type of the extension in question. -Processing of self-defined wire formats has to be defined by the extension.

    +Processing of self-defined wire formats has to be defined by the extension.

    -
    +
    -2.1.7.2. Proposals +2.1.9.3. Proposals
    -

    Similar to wire formats, extensions can define their own proposals by using one +

    Similar to wire formats, extensions can define their own proposals by using one of three dedicated extension proposal types: extension_proposal, extension_path_proposal and extension_external_propsal. Each type contains the same ExtensionContent struct, but is validated differently: extension_proposal requires no UpdatePath and can not be sent by an external sender extension_path_proposal requires an UpdatePath and can not be sent by an external sender extensions_external_proposal requires no UpdatePath and can be sent by an -external sender.

    -

    Each of the three proposal types is IANA registered and extends the select -statement in the Proposal struct as follows:

    -
    +external sender.

    +

    Each of the three proposal types is IANA registered and extends the select +statement in the Proposal struct as follows:

    +
     case extension_proposal:
     ExtensionContent extension_content;
@@ -1743,54 +1875,54 @@ 
    
     ExtensionContent extension_content;
 case extension_external_proposal:
     ExtensionContent extension_content;
-
    +
    -

    The extension_type MUST be set to the type of the extension in question.

    -

    Processing and validation of self-defined proposals has to be defined by the +

    The extension_type MUST be set to the type of the extension in question.

    +

    Processing and validation of self-defined proposals has to be defined by the extension. However, validation rules can lead to a previously valid commit to become invalid, not the other way around. This is with the exception of proposal validation for external commits, where self-defined proposals can be declared valid for use in external commits. More concretely, if an external commit is invalid, only because the self-defined proposal is part of it (the last rule in external commit proposal validation in Section 12.2 of [RFC9420]), then the -self-defined validation rules may rule that the commit is instead valid.

    +self-defined validation rules may rule that the commit is instead valid.

    -
    +
    -2.1.7.3. Credentials +2.1.9.4. Credentials
    -

    Extension designers can also define their own credential types via the IANA +

    Extension designers can also define their own credential types via the IANA registered extension_credential credential type. The extension_credential -extends the select statement in the Credential struct as follows:

    -
    +extends the select statement in the Credential struct as follows:

    +
     case extension_credential:
     ExtensionContent extension_content;
-
    +
    -

    The extension_type in the extension_content must be set to that of the extension +

    The extension_type in the extension_content must be set to that of the extension in question with the extension_data containing all other relevant data. Note that any credential defined in this way has to meet the requirements detailed in -Section 5.3 of the MLS specification.

    +Section 5.3 of the MLS specification.

    -
    +
    -2.1.7.4. Additional Authenticated Data (AAD) +2.1.9.5. Additional Authenticated Data (AAD)
    -

    The PrivateContentAAD struct in MLS can contain arbitrary additional +

    The PrivateContentAAD struct in MLS can contain arbitrary additional application-specific AAD in its authenticated_data field. This framework defines a framing used to allow multiple extensions to add AAD safely -without conflicts or ambiguity.

    -

    When any AAD safe extension is included in the authenticated_data field, +without conflicts or ambiguity.

    +

    When any AAD safe extension is included in the authenticated_data field, the "safe" AAD items MUST come before any non-safe data in the authenticated_data field. Safe AAD items are framed using the SafeAAD struct and are sorted in increasing numerical order of the ExtensionType -as described below:

    -
    +as described below:

    +
     struct {
   ExtensionType extension_type;
@@ -1800,33 +1932,33 @@ 
    
 struct {
   SafeAADItem aad_items<V>;
 } SafeAAD;
-
    +
    -

    If the SafeAAD is present or not is determined by the presence of the +

    If the SafeAAD is present or not is determined by the presence of the extension_aad GroupContext extension in the required_capabilities of the group. If extension_aad is present in required_capabilities but no -"safe" AAD items are present, the aad_items is a zero-length vector.

    -

    Each extension which include a SafeAADItem needs to advertise its +"safe" AAD items are present, the aad_items is a zero-length vector.

    +

    Each extension which include a SafeAADItem needs to advertise its ExtensionType in its LeafNode capabilities.extensions. Extensions MAY require an ExtensionType to be included in required_capabilities, but members which encounter a SafeAADItem they do not recognize can safely -ignore it.

    +ignore it.

    -
    +

    -2.1.8. Extension state: anchoring, storage and agreement +2.1.10. Extension state: anchoring, storage and agreement

    -

    The safe extension framework can help an MLS extension ensure that all group +

    The safe extension framework can help an MLS extension ensure that all group members agree on a piece of extension-specific state by using the ExtensionState GroupContext extension. The ownership of an ExtensionState extension in the context of the safe extension framework is determined by the extension_type field. The extension with a matching extension_type is called -the owning extension.

    -
    +the owning extension.

    +
     enum {
   reserved(0),
@@ -1856,46 +1988,46 @@ 
    
   Permissions read;
   ExtensionPayload payload;
 } ExtensionState;
-
    -
    -

    The ExtensionState GroupContext extension contains data either directly (if -hash_or_data = data) or inditectly via a hash (if hash_or_data = hash).

    -

    The owning extension can read and write the state stored in an ExtensionState -extension using an extension-defined proposal (see Section 2.1.7.2). The semantics -of the proposal determines how the state is changed.

    -

    The read variable determines the permissions that other MLS extensions have + +

    +

    The ExtensionState GroupContext extension contains data either directly (if +hash_or_data = data) or inditectly via a hash (if hash_or_data = hash).

    +

    The owning extension can read and write the state stored in an ExtensionState +extension using an extension-defined proposal (see Section 2.1.9.3). The semantics +of the proposal determines how the state is changed.

    +

    The read variable determines the permissions that other MLS extensions have w.r.t. the data stored within. read allows other MLS extensions to read that data via their own proposals, while none marks the data as private to the -owning MLS extension.

    -

    Other extensions may never write to the ExtensionState of the owning MLS -extension.

    +owning MLS extension.

    +

    Other extensions may never write to the ExtensionState of the owning MLS +extension.

    -
    +
    -2.1.8.1. Direct vs. hash-based storage +2.1.10.1. Direct vs. hash-based storage
    -

    Storing the data directly in the ExtensionState means the data becomes part of +

    Storing the data directly in the ExtensionState means the data becomes part of the group state. Depending on the application design, this can be advantageous, because it is distributed via Welcome messages. However, it could also mean that the data is visible to the delivery service. Additionally, if the application makes use of GroupContextExtension proposals, it may be necessary to send all of -the data with each such extension.

    -

    Including the data by hash only allows group members to agree on the data +the data with each such extension.

    +

    Including the data by hash only allows group members to agree on the data indirectly, relying on the collision resistance of the associated hash function. -The data itself, however, may have to be transmitted out-of-band to new joiners.

    +The data itself, however, may have to be transmitted out-of-band to new joiners.

    -
    +
    -2.1.8.2. GroupContextExtensions +2.1.10.2. GroupContextExtensions
    -

    MLS allows applications to modify GroupContext extensions via the +

    MLS allows applications to modify GroupContext extensions via the GroupContextExtension proposal. However, control via that proposal involves including all GroupContext extensions in each such proposal. This makes data management more costly than via extension-specific proposals, which can, for example, include only the data to be changed for a given GroupContext extension, -or define semantics that allow modification based on local data only.

    +or define semantics that allow modification based on local data only.

    @@ -1912,60 +2044,6 @@

    functionalities that extensions can use without modifying MLS itself. Extension authors should consider using these built-in mechanisms before employing more intrusive changes to the protocol.

    -
    -
    -

    -2.2.1. Storing State in Extensions -

    -

    Every type of MLS extension can have data associated with it and, depending on -the type of extension (KeyPackage Extension, GroupContext Extension, etc.) that -data is included in the corresponding MLS struct. This allows the authors of an -extension to make use of any authentication or confidentiality properties that -the struct is subject to as part of the protocol flow.

    -
      -
    • -

      GroupContext Extensions: Any data in a group context extension is agreed-upon -by all members of the group in the same way as the rest of the group state. As -part of the GroupContext, it is also sent encrypted to new joiners via Welcome -messages and (depending on the architecture of the application) may be -available to external joiners. Note that in some scenarios, the GroupContext -may also be visible to components that implement the delivery service. While -MLS extensions can define arbitrary GroupContext extensions, it is recommended -to make use of ExtensionState extensions to store state in the group's -GroupContext.

      -
      • -
    • -

      GroupInfo Extensions: GroupInfo extensions are included in the GroupInfo -struct and thus sent encrypted and authenticated by the signer of the -GroupInfo to new joiners as part of Welcome messages. It can thus be used as a -confidential and authenticated channel from the inviting group member to new -joiners. Just like GroupContext extensions, they may also be visible to -external joiners or even parts of the delivery service. Unlike GroupContext -extensions, the GroupInfo struct is not part of the group state that all group -members agree on.

      -
      • -
    • -

      KeyPackage Extensions: KeyPackages (and the extensions they include) are -pre-published by individual clients for asynchronous group joining. They are -included in Add proposals and become part of the group state once the Add -proposal is committed. They are, however, removed from the group state when -the owner of the KeyPackage does the first commit with a path. As such, -KeyPackage extensions can be used to communicate data to anyone who wants to -invite the owner to a group, as well as the other members of the group the -owner is added to. Note that KeyPackage extensions are visible to the server -that provides the KeyPackages for download, as well as any part of the -delivery service that can see the public group state.

      -
      • -
    • -

      LeafNode Extensions: LeafNodes are a part of every KeyPackage and thus follow -the same lifecycle. However, they are also part of any commit that includes an -UpdatePath and clients generally have a leaf node in each group they are a member -of. Leaf node extensions can thus be used to include member-specific data in a -group state that can be updated by the owner at any time.

      -
      • -
    -
    -

    @@ -2076,7 +2154,7 @@

    3.2.2. Format

    This extension uses the mls_extension_message WireFormat as defined in Section -Section 2.1.7.1, where the content is a TargetedMessage.

    +Section 2.1.9.2, where the content is a TargetedMessage.

     struct {
@@ -2213,7 +2291,7 @@

    The functions SealAuth and OpenAuth defined in [hpke] are used as -described in Section 2.1.3 with an empty context. Other functions are defined in +described in Section 2.1.5 with an empty context. Other functions are defined in [mls-protocol].

    @@ -2222,7 +2300,7 @@

    The sender MUST set the authentication scheme to TargetedMessageAuthScheme.HPKEAuthPsk.

    -

    As described in Section 2.1.3 the hpke_context is a LabeledExtensionContent struct +

    As described in Section 2.1.5 the hpke_context is a LabeledExtensionContent struct with the following content, where group_context is the serialized context of the group.

    @@ -2654,6 +2732,31 @@

    4.2. MLS Extension Types

    +

    This document updates the MLS Extension Types registry to insert a new +column ("Safe") between the "Recommended" column and the "Reference" +column. The value of the "Safe" column for the first (0x0000) and last +(0xF000-0xFFFF) rows is "-" while the value of all other existing rows is +"N".

    +
      +
    • +

      Safe: Whether the extension is a Safe Extension as defined in Section 2 of + RFC XXXX. Valid values are:

      +
        +
      • +

        "Y", indicating the extension is a Safe Extension;

        +
        • +
      • +

        "N", indicating the extension is not a Safe Extension; or

        +
        • +
      • +

        "-", indicating a reserved value which is not a single extension.

        +
        • +
      +
      • +
    +

    This document also extends the list of allowable values for the "Message(s)" +column, such that the list may be empty (represented by "-") if the +extension is a Safe Extension.

    @@ -2815,6 +2918,63 @@

    +
    +
    +

    +4.2.7. safe_extensions MLS Extension +

    +

    The safe_extensions MLS Extension Type is used to signal support for the +Safe Extensions Framework in LeafNode capabilities, and in GroupContext +required_capabilities. It contains no additional data.

    +
      +
    • +

      Value: 0x000C

      +
      • +
    • +

      Name: safe_extensions

      +
      • +
    • +

      Message(s): LN,GC: This extension may appear in LeafNode and GroupContext +objects.

      +
      • +
    • +

      Recommended: Y

      +
      • +
    • +

      Reference: RFC XXXX

      +
      • +
    +
    +
    +
    +
    +

    +4.2.8. core_struct_extensions MLS Extension +

    +

    The core_struct_extensions MLS Extension Type is used to signal support +for one or more Core Struct Extensions using the Safe Extensions Framework. +It appears in LeafNode capabilities, and in GroupContext +required_capabilities. It contains no additional data.

    +
      +
    • +

      Value: 0x000D

      +
      • +
    • +

      Name: core_struct_extensions

      +
      • +
    • +

      Message(s): LN,GC: This extension may appear in LeafNode and GroupContext +objects.

      +
      • +
    • +

      Recommended: Y

      +
      • +
    • +

      Reference: RFC XXXX

      +
      • +
    +
    +
    @@ -2968,7 +3128,7 @@

    • -

      Value: 0x0000

      +

      Value: 0x0003

    • Name: extension_credential

      @@ -3022,7 +3182,7 @@

    The AD Message type refers to an ExtensionType used inside the -SafeAADItem structure defined in Section 2.1.7.4.

    +SafeAADItem structure defined in Section 2.1.9.5.

    diff --git a/draft-ietf-mls-extensions.txt b/draft-ietf-mls-extensions.txt index ea8fe08..8d2de65 100644 --- a/draft-ietf-mls-extensions.txt +++ b/draft-ietf-mls-extensions.txt @@ -61,15 +61,16 @@ Table of Contents 2. Safe Extensions 2.1. Safe Extension API 2.1.1. Security - 2.1.2. Common Data Structures - 2.1.3. Hybrid Public Key Encryption (HPKE) - 2.1.4. Signature Keys - 2.1.5. Exporting Secrets - 2.1.6. Pre-Shared Keys (PSKs) - 2.1.7. Extension Designer Tools - 2.1.8. Extension state: anchoring, storage and agreement + 2.1.2. Core Struct Extensions + 2.1.3. Common Data Structures + 2.1.4. Negotiating Support for Safe Extensions + 2.1.5. Hybrid Public Key Encryption (HPKE) + 2.1.6. Signature Keys + 2.1.7. Exporting Secrets + 2.1.8. Pre-Shared Keys (PSKs) + 2.1.9. Extension Designer Tools + 2.1.10. Extension state: anchoring, storage and agreement 2.2. Extension Design Guidance - 2.2.1. Storing State in Extensions 3. Extensions 3.1. AppAck 3.1.1. Description @@ -99,6 +100,8 @@ Table of Contents 4.2.4. required_media_types MLS Extension 4.2.5. last_resort_key_package MLS Extension 4.2.6. extension_aad MLS Extension + 4.2.7. safe_extensions MLS Extension + 4.2.8. core_struct_extensions MLS Extension 4.3. MLS Proposal Types 4.3.1. Extension Proposal 4.3.2. Extension Path Proposal @@ -159,7 +162,7 @@ Table of Contents 2. Safe Extensions The MLS specification is extensible in a variety of ways (see - Section 13 of the [RFC9420]) and describes the negotiation and other + Section 13 of [RFC9420]) and describes the negotiation and other handling of extensions and their data within the protocol. However, it does not provide guidance on how extensions can or should safely interact with the base MLS protocol. The goal of this section is to @@ -173,7 +176,7 @@ Table of Contents the Safe Extension API alongside the built-in mechanisms of the base MLS protocol, defines a number of labels registered in IANA which can be safely used by extensions, so that the only value an extension - developer must add to the IANA registry themselves is a unique + developer must add to the IANA registry itself is a unique ExtensionType. 2.1. Safe Extension API @@ -193,6 +196,11 @@ Table of Contents export functionality of MLS, preserves forward secrecy of the exported secrets within an epoch. + * Define new WireFormat, Proposal, Credential, GroupContext, + GroupInfo, KeyPackage, and LeafNode extensions which can interact + safely with arbitrary sets of other current or future Safe + Extensions. + * Anchor extension-specific state in an MLS group to ensure agreement and manage state acces authorization across extensions. @@ -223,11 +231,64 @@ Table of Contents security vulnerabilities introduced by one extension do not spread to other extensions or the base MLS. -2.1.2. Common Data Structures +2.1.2. Core Struct Extensions + + Every type of MLS extension can have data associated with it. The + "MLS Extensions Types" registry historically represented + extensibility of four core structs (GroupContext, GroupInfo, + KeyPackage, and LeafNode) that have far reaching effects on the use + of the protocol. The majority of MLS extensions registered at the + time of this writing extend one or more of these core structs. + + * GroupContext Extensions: Any data in a group context extension is + agreed-upon by all members of the group in the same way as the + rest of the group state. As part of the GroupContext, it is also + sent encrypted to new joiners via Welcome messages and (depending + on the architecture of the application) may be available to + external joiners. Note that in some scenarios, the GroupContext + may also be visible to components that implement the delivery + service. While MLS extensions can define arbitrary GroupContext + extensions, it is recommended to make use of ExtensionState + extensions to store state in the group's GroupContext. + + * GroupInfo Extensions: GroupInfo extensions are included in the + GroupInfo struct and thus sent encrypted and authenticated by the + signer of the GroupInfo to new joiners as part of Welcome + messages. It can thus be used as a confidential and authenticated + channel from the inviting group member to new joiners. Just like + GroupContext extensions, they may also be visible to external + joiners or even parts of the delivery service. Unlike + GroupContext extensions, the GroupInfo struct is not part of the + group state that all group members agree on. + + * KeyPackage Extensions: KeyPackages (and the extensions they + include) are pre-published by individual clients for asynchronous + group joining. They are included in Add proposals and become part + of the group state once the Add proposal is committed. They are, + however, removed from the group state when the owner of the + KeyPackage does the first commit with a path. As such, KeyPackage + extensions can be used to communicate data to anyone who wants to + invite the owner to a group, as well as the other members of the + group the owner is added to. Note that KeyPackage extensions are + visible to the server that provides the KeyPackages for download, + as well as any part of the delivery service that can see the + public group state. + + * LeafNode Extensions: LeafNodes are a part of every KeyPackage and + thus follow the same lifecycle. However, they are also part of + any commit that includes an UpdatePath and clients generally have + a leaf node in each group they are a member of. Leaf node + extensions can thus be used to include member-specific data in a + group state that can be updated by the owner at any time. + +2.1.3. Common Data Structures - Most components of the Safe Extension API use the value ExtensionType - which is a unique uint16 identifier assigned to an extension in the - MLS Extension Types IANA registry (see Section 17.3 of [RFC9420]). + The Safe Extension API reuses the ExtensionType and the "MLS + Extension Types" IANA registry used for these core structs (see + Section 17.3 of [RFC9420]), even for safe extensions with no core + struct changes. This is because many extensions modify a core + struct, either primarily or to store state (related to the group or a + client) associated with another aspect of that extension. Most Safe Extension API components also use the following data structure, which provides domain separation by extension_type of @@ -241,15 +302,62 @@ Table of Contents Where extension_type is set to the type of the extension to which the extension_data belongs. - If in addition a label is required, the following data structure is - used. + When a label is required for an extension, the following data + structure is used. struct { opaque label; ExtensionContent extension_content; } LabeledExtensionContent; -2.1.3. Hybrid Public Key Encryption (HPKE) +2.1.4. Negotiating Support for Safe Extensions + + MLS defines a Capabilities struct for LeafNodes (in turn used in + KeyPackages), which describes which extensions are supported by the + associated node. However, that struct (defined in Section 7.2 of + [RFC9420]) only has fields for a subset of the extensions possible in + MLS, as reproduced below. + + ... + struct { + ProtocolVersion versions; + CipherSuite cipher_suites; + ExtensionType extensions; + ProposalType proposals; + CredentialType credentials; + } Capabilities; + ... + + Therefore, all safe extensions MUST be represented by their + extension_type in the extensions vector (originally intended for core + struct extensions), regardless of their type. + + If the LeafNode supports any safe extension Credentials, the + credentials vector will contain any non-safe credentials supported, + plus the extension_credential defined in {extension-credential}. + + If the LeafNode supports any safe extension Proposals, then proposals + will contain any non-default non-safe extensions, and whichever safe + extension proposal types defined in {mls-proposal-types} are relevant + to the supported safe proposals. + + Likewise, the required_capabilities GroupContext extension (defined + in Section 11.1 of [RFC9420] and reproduced below) contains all + mandatory to support non-default non-safe, and safe extensions in its + extension_types vector. Its credential_types vector contains any + mandatory non-safe credential types, plus extensions_credential if + any safe credential is required. Its proposal_types vector contains + any mandatory to support non-default non-safe Proposals, and the + relevant safe proposal type or types corresponding to any required + safe proposals. + + struct { + ExtensionType extension_types; + ProposalType proposal_types; + CredentialType credential_types; + } RequiredCapabilities; + +2.1.5. Hybrid Public Key Encryption (HPKE) This component of the Safe Extension API allows extensions to make use of all HPKE key pairs generated by MLS. An extension identified @@ -305,7 +413,7 @@ Table of Contents The secret key is known only to the owner of the KeyPackage and is deleted immediately after it is used to join a group. -2.1.4. Signature Keys +2.1.6. Signature Keys MLS session states contain a number of signature keys including the ones in the LeafNode structs. Extensions can safely sign content and @@ -336,7 +444,7 @@ Table of Contents that domain separation is ensured by explicitly including the ExtensionType with every operation. -2.1.5. Exporting Secrets +2.1.7. Exporting Secrets An extension can use MLS as a group key agreement protocol by exporting symmetric keys. Such keys can be exported (i.e. derived @@ -367,7 +475,7 @@ Table of Contents ExtensionType MUST be set to the ExtensionType of the implemented extension. -2.1.6. Pre-Shared Keys (PSKs) +2.1.8. Pre-Shared Keys (PSKs) PSKs represent key material that is injected into the MLS key schedule when creating or processing a commit as defined in @@ -418,7 +526,7 @@ Table of Contents opaque psk_nonce; } PreSharedKeyID; -2.1.7. Extension Designer Tools +2.1.9. Extension Designer Tools The safe extension API allows extension designers to sign and encrypt payloads without the need to register their own IANA labels. @@ -427,7 +535,14 @@ Table of Contents credentials, and for structured data in the Additional Authenticated Data. -2.1.7.1. Wire Formats +2.1.9.1. Core Struct Extensions + + Each extension of the GroupContext, GroupInfo, KeyPackage, and/or + LeafNode structs is required to define the format of its data. These + types of extensions SHOULD NOT use the ExtensionContent struct since + the extension_type is already in the parent data structure. + +2.1.9.2. Wire Formats Extensions can define their own MLS messages by using the mls_extension_message MLS Wire Format. The mls_extension_message @@ -441,7 +556,7 @@ Table of Contents the extension in question. Processing of self-defined wire formats has to be defined by the extension. -2.1.7.2. Proposals +2.1.9.3. Proposals Similar to wire formats, extensions can define their own proposals by using one of three dedicated extension proposal types: @@ -477,7 +592,7 @@ Table of Contents then the self-defined validation rules may rule that the commit is instead valid. -2.1.7.3. Credentials +2.1.9.4. Credentials Extension designers can also define their own credential types via the IANA registered extension_credential credential type. The @@ -493,7 +608,7 @@ Table of Contents has to meet the requirements detailed in Section 5.3 of the MLS specification. -2.1.7.4. Additional Authenticated Data (AAD) +2.1.9.5. Additional Authenticated Data (AAD) The PrivateContentAAD struct in MLS can contain arbitrary additional application-specific AAD in its authenticated_data field. This @@ -527,7 +642,7 @@ Table of Contents but members which encounter a SafeAADItem they do not recognize can safely ignore it. -2.1.8. Extension state: anchoring, storage and agreement +2.1.10. Extension state: anchoring, storage and agreement The safe extension framework can help an MLS extension ensure that all group members agree on a piece of extension-specific state by @@ -571,7 +686,7 @@ Table of Contents The owning extension can read and write the state stored in an ExtensionState extension using an extension-defined proposal (see - Section 2.1.7.2). The semantics of the proposal determines how the + Section 2.1.9.3). The semantics of the proposal determines how the state is changed. The read variable determines the permissions that other MLS @@ -582,7 +697,7 @@ Table of Contents Other extensions may never write to the ExtensionState of the owning MLS extension. -2.1.8.1. Direct vs. hash-based storage +2.1.10.1. Direct vs. hash-based storage Storing the data directly in the ExtensionState means the data becomes part of the group state. Depending on the application @@ -597,7 +712,7 @@ Table of Contents associated hash function. The data itself, however, may have to be transmitted out-of-band to new joiners. -2.1.8.2. GroupContextExtensions +2.1.10.2. GroupContextExtensions MLS allows applications to modify GroupContext extensions via the GroupContextExtension proposal. However, control via that proposal @@ -616,56 +731,6 @@ Table of Contents using these built-in mechanisms before employing more intrusive changes to the protocol. -2.2.1. Storing State in Extensions - - Every type of MLS extension can have data associated with it and, - depending on the type of extension (KeyPackage Extension, - GroupContext Extension, etc.) that data is included in the - corresponding MLS struct. This allows the authors of an extension to - make use of any authentication or confidentiality properties that the - struct is subject to as part of the protocol flow. - - * GroupContext Extensions: Any data in a group context extension is - agreed-upon by all members of the group in the same way as the - rest of the group state. As part of the GroupContext, it is also - sent encrypted to new joiners via Welcome messages and (depending - on the architecture of the application) may be available to - external joiners. Note that in some scenarios, the GroupContext - may also be visible to components that implement the delivery - service. While MLS extensions can define arbitrary GroupContext - extensions, it is recommended to make use of ExtensionState - extensions to store state in the group's GroupContext. - - * GroupInfo Extensions: GroupInfo extensions are included in the - GroupInfo struct and thus sent encrypted and authenticated by the - signer of the GroupInfo to new joiners as part of Welcome - messages. It can thus be used as a confidential and authenticated - channel from the inviting group member to new joiners. Just like - GroupContext extensions, they may also be visible to external - joiners or even parts of the delivery service. Unlike - GroupContext extensions, the GroupInfo struct is not part of the - group state that all group members agree on. - - * KeyPackage Extensions: KeyPackages (and the extensions they - include) are pre-published by individual clients for asynchronous - group joining. They are included in Add proposals and become part - of the group state once the Add proposal is committed. They are, - however, removed from the group state when the owner of the - KeyPackage does the first commit with a path. As such, KeyPackage - extensions can be used to communicate data to anyone who wants to - invite the owner to a group, as well as the other members of the - group the owner is added to. Note that KeyPackage extensions are - visible to the server that provides the KeyPackages for download, - as well as any part of the delivery service that can see the - public group state. - - * LeafNode Extensions: LeafNodes are a part of every KeyPackage and - thus follow the same lifecycle. However, they are also part of - any commit that includes an UpdatePath and clients generally have - a leaf node in each group they are a member of. Leaf node - extensions can thus be used to include member-specific data in a - group state that can be updated by the owner at any time. - 3. Extensions 3.1. AppAck @@ -757,7 +822,7 @@ Table of Contents 3.2.2. Format This extension uses the mls_extension_message WireFormat as defined - in Section Section 2.1.7.1, where the content is a TargetedMessage. + in Section Section 2.1.9.2, where the content is a TargetedMessage. struct { opaque group_id; @@ -876,7 +941,7 @@ Table of Contents = DeriveExtensionSecret(extension_secret, "targeted message psk") The functions SealAuth and OpenAuth defined in [hpke] are used as - described in Section 2.1.3 with an empty context. Other functions + described in Section 2.1.5 with an empty context. Other functions are defined in [mls-protocol]. 3.2.4.1. Authentication with HPKE @@ -884,7 +949,7 @@ Table of Contents The sender MUST set the authentication scheme to TargetedMessageAuthScheme.HPKEAuthPsk. - As described in Section 2.1.3 the hpke_context is a + As described in Section 2.1.5 the hpke_context is a LabeledExtensionContent struct with the following content, where group_context is the serialized context of the group. @@ -1246,6 +1311,26 @@ Table of Contents 4.2. MLS Extension Types + This document updates the MLS Extension Types registry to insert a + new column ("Safe") between the "Recommended" column and the + "Reference" column. The value of the "Safe" column for the first + (0x0000) and last (0xF000-0xFFFF) rows is "-" while the value of all + other existing rows is "N". + + * Safe: Whether the extension is a Safe Extension as defined in + Section 2 of RFC XXXX. Valid values are: + + - "Y", indicating the extension is a Safe Extension; + + - "N", indicating the extension is not a Safe Extension; or + + - "-", indicating a reserved value which is not a single + extension. + + This document also extends the list of allowable values for the + "Message(s)" column, such that the list may be empty (represented by + "-") if the extension is a Safe Extension. + 4.2.1. targeted_messages_capability MLS Extension The targeted_messages_capability MLS Extension Type is used in the @@ -1345,6 +1430,41 @@ Table of Contents * Reference: RFC XXXX +4.2.7. safe_extensions MLS Extension + + The safe_extensions MLS Extension Type is used to signal support for + the Safe Extensions Framework in LeafNode capabilities, and in + GroupContext required_capabilities. It contains no additional data. + + * Value: 0x000C + + * Name: safe_extensions + + * Message(s): LN,GC: This extension may appear in LeafNode and + GroupContext objects. + + * Recommended: Y + + * Reference: RFC XXXX + +4.2.8. core_struct_extensions MLS Extension + + The core_struct_extensions MLS Extension Type is used to signal + support for one or more Core Struct Extensions using the Safe + Extensions Framework. It appears in LeafNode capabilities, and in + GroupContext required_capabilities. It contains no additional data. + + * Value: 0x000D + + * Name: core_struct_extensions + + * Message(s): LN,GC: This extension may appear in LeafNode and + GroupContext objects. + + * Recommended: Y + + * Reference: RFC XXXX + 4.3. MLS Proposal Types 4.3.1. Extension Proposal @@ -1421,7 +1541,7 @@ Table of Contents 4.4.1. Extension Credential - * Value: 0x0000 + * Value: 0x0003 * Name: extension_credential @@ -1447,7 +1567,7 @@ Table of Contents * AD: Authenticated Additional Data The AD Message type refers to an ExtensionType used inside the - SafeAADItem structure defined in Section 2.1.7.4. + SafeAADItem structure defined in Section 2.1.9.5. 5. Security considerations