Deployed 0958e5a with MkDocs version: 1.5.3

APIs/Core/Server-Client API/WebSockets/gateway_events/index.html

@@ -75,6 +75,11 @@
     <label class="md-overlay" for="__drawer"></label>
     <div data-md-component="skip">
 
+
+        <a href="#key_change" class="md-skip">
+          Skip to content
+        </a>
+
     </div>
     <div data-md-component="announce">
 
@@ -819,6 +824,17 @@
 
 
 
+        <label class="md-nav__link md-nav__link--active" for="__toc">
+
+
+  <span class="md-ellipsis">
+    Gateway Events
+  </span>
+
+
+          <span class="md-nav__icon md-icon"></span>
+        </label>
+
       <a href="./" class="md-nav__link md-nav__link--active">
 
 
@@ -829,6 +845,32 @@
 
       </a>
 
+
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+
+
+
+
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+
+        <li class="md-nav__item">
+  <a href="#key_change" class="md-nav__link">
+    <span class="md-ellipsis">
+      KEY_CHANGE
+    </span>
+  </a>
+
+</li>
+
+    </ul>
+
+</nav>
+
     </li>
 
 
@@ -941,6 +983,23 @@
 
 
 
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+
+        <li class="md-nav__item">
+  <a href="#key_change" class="md-nav__link">
+    <span class="md-ellipsis">
+      KEY_CHANGE
+    </span>
+  </a>
+
+</li>
+
+    </ul>
+
 </nav>
                   </div>
                 </div>
@@ -960,6 +1019,7 @@
   <h1>Gateway Events</h1>
 
 <p>TODO</p>
+<h2 id="key_change"><code>KEY_CHANGE</code><a class="headerlink" href="#key_change" title="Permanent link">&para;</a></h2>
 
 
 
@@ -982,7 +1042,7 @@ <h1>Gateway Events</h1>
     <span class="md-icon" title="Last update">
       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1-2.1-2M12.5 7v5.2l4 2.4-1 1L11 13V7h1.5M11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2v1.8Z"/></svg>
     </span>
-    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-01-07T18:28:53+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-01-07</span>
+    <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago"><span class="timeago" datetime="2024-01-08T20:07:01+00:00" locale="en"></span></span><span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-iso_date">2024-01-08</span>
   </span>
 
 

specification/index.html

@@ -1814,7 +1814,8 @@ <h2 id="6-encryption">6. Encryption<a class="headerlink" href="#6-encryption" ti
 <p>Note, that in the below sequence diagrams, the MLS Welcome message and the MLS Group notify message are all encrypted using the identity key of the recipient.</p>
 <h3 id="61-encrypted-guild-channels">6.1 Encrypted guild channels<a class="headerlink" href="#61-encrypted-guild-channels" title="Permanent link">&para;</a></h3>
 <p>Encrypting a guild channel is done by a client with the <code>MANAGE_CHANNEL</code> permission. Upon successfully requesting enabling encryption of a channel, all future messages in it will be encrypted. Joining an encrypted channel is done by sending a join request to the server. The server will then notify the channels' members of the join request. The members will then decide whether to accept or reject the join request. If the join request is accepted by any member, that member will initiate the MLS welcoming process. If the member finds that the join request is invalid (perhaps due to an invalid <code>KeyPackage</code>), the join request must be denied. It is imperative that join requests are verified correctly by the server.</p>
-<p><div class="language-text highlight"><span class="filename">Text Only</span><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>     Charlie                                        Server                                            Alice                         Bob
+<p><a id="fig-3"/>
+<div class="language-text highlight"><span class="filename">Text Only</span><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a>     Charlie                                        Server                                            Alice                         Bob
 <a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>     |                                              |                                                 |                             |
 <a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a>     | Channel join request + KeyPackage            |                                                 |                             |
 <a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a>     |---------------------------------------------&gt;|                                                 |                             |
@@ -1975,12 +1976,12 @@ <h4 id="711-last-resort-keypackages">7.1.1 Last resort KeyPackages<a class="head
 <p>Once a server has given out a "last resort" <code>KeyPackage</code> to a client, the server should request a new "last resort" <code>KeyPackage</code> from the client from the user, once they connect to the server again. The old "last resort" <code>KeyPackage</code> should then be deleted.</p>
 <h3 id="72-user-identity-keys-and-message-signing">7.2 User identity keys and message signing<a class="headerlink" href="#72-user-identity-keys-and-message-signing" title="Permanent link">&para;</a></h3>
 <p>As mentioned section #3, users must hold on to an identity key pair at all times. This key pair is used to represent a user's identity and to verify message integrity, by having a user sign all messages they send with their private identity key. The key pair is generated by the user, and the respective public key is sent to the user's home server when first registering on the server, or when rotating keys. The key is stored in the client's local storage. Upon receiving a new identity key pair, a home server will generate a new certificate containing the clients' public identity key and the corresponding users' federation ID, and send it to the client. This certificate is proof that the home server attests to the clients key.</p>
-<p>A client may choose to rotate their identity key at any time. This is done by generating a new identity key pair, and sending the new public identity key to their home server. The home server will then also generate a new certificate for the client.</p>
+<p>A client may choose to rotate their identity key at any time. This is done by generating a new identity key pair, and sending the new public identity key to their home server. The home server will then also generate a new certificate and send it to the client. Before sending any messages to a server, a client should inform the server of the key change, to ensure that the server has the correct public identity key cached for the client. The server lets clients connected to it know, that a client has changed their identity key, by sending a <a href="/docs/APIs/Core/Server-Client%20API/WebSockets/gateway_events.md#key_change"><code>KEY_CHANGE</code></a> gateway event to every client connected to the server. </p>
 <p>Even though section 7.1 defines that a <code>KeyPackage</code> should be deleted by the server after it has been given out once, servers must keep track of the identity keys of all users that are registered on the server, and must be able to provide a users' identity key (or keys, in the case of multi-device users) for a given timestamp, when requested. This is to ensure messages sent by users, even ones sent a long time ago, can be verified by other servers and their users. This is because the public key of a user may change over time and users must sign all messages they send to other servers. Likewise, a client should also keep track of all of its own identity keys, to potentially verify their identity in case of a migration.</p>
 <p>Signing messages prevents a malicious foreign server from impersonating a user.</p>
 <h4 id="721-message-verification">7.2.1 Message verification<a class="headerlink" href="#721-message-verification" title="Permanent link">&para;</a></h4>
 <p>Of course, in order for message signing to actually verify message integrity, clients <strong>must</strong> verify the signatures of all messages they receive. This is done by verifying the signature of the message with the public key and certificate of the sender, which both can be obtained from the home server the message was sent on. Clients must also verify that the certificate attached to the message is valid and that the public key in the certificate matches the public key of the sender. </p>
-<p><strong>Example:</strong> Given a signed message from Alice, like Bob would receive it from Server B in <a href="">Fig. 3</a>, Bob's client would verify the signature of the message like so:</p>
+<p><strong>Example:</strong> Given a signed message from Alice, like Bob would receive it from Server B in <a href="#fig-3">Fig. 3</a>, Bob's client would verify the signature of the message like so:</p>
 <p><div class="language-text highlight"><span class="filename">Text Only</span><pre><span></span><code><a id="__codelineno-7-1" name="__codelineno-7-1" href="#__codelineno-7-1"></a>Server B                                        Bob                                         Server A
 <a id="__codelineno-7-2" name="__codelineno-7-2" href="#__codelineno-7-2"></a>|                                               |                                           |
 <a id="__codelineno-7-3" name="__codelineno-7-3" href="#__codelineno-7-3"></a>| Alice&#39;s signed message                        |                                           |
@@ -2010,7 +2011,7 @@ <h4 id="721-message-verification">7.2.1 Message verification<a class="headerlink
 <p class="admonition-title">TODO</p>
 <p>TODO: What about multiple devices? Should the client cache all public identity keys and certificates for a user? Should the client cache the public identity key and certificate for the device that sent the message? How would the client know which device sent the message? Session IDs? hmm</p>
 </div>
-<p>If the verification fails, Bob's client may try to request Alice's public identity key and certificate from Server A (Alice's home server), and try to verify the signature again. Should the verification fails again, the message should be treated with extreme caution.</p>
+<p>If the verification fails, Bob's client should try to re-request the key from Server B first. If the verification fails again, Bob's client may try to request Alice's public identity key and certificate from Server A (Alice's home server), and try to verify the signature again. Should the verification still not succeed, the message should be treated with extreme caution.</p>
 <div class="admonition question">
 <p class="admonition-title">Why does Bob's client not request Alice's public identity key from Server A?</p>
 <p>Bob's client could request Alice's public identity key from Server A, instead of Server B. However, this is discouraged, as it</p>