mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-29 13:54:10 +02:00
Compare commits
No commits in common. "main" and "v1.16" have entirely different histories.
89
.github/workflows/main.yml
vendored
89
.github/workflows/main.yml
vendored
|
|
@ -1,9 +1,8 @@
|
|||
name: "Spec"
|
||||
|
||||
env:
|
||||
HUGO_VERSION: 0.155.3
|
||||
HUGO_VERSION: 0.148.1
|
||||
PYTHON_VERSION: 3.13
|
||||
NODE_VERSION: 24
|
||||
|
||||
on:
|
||||
push:
|
||||
|
|
@ -28,7 +27,7 @@ jobs:
|
|||
- name: "➕ Setup Node"
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
node-version: '20'
|
||||
- name: "🔎 Run validator"
|
||||
run: |
|
||||
npx @redocly/cli@latest lint data/api/*/*.yaml
|
||||
|
|
@ -196,13 +195,11 @@ jobs:
|
|||
needs: [calculate-baseurl, build-openapi, generate-changelog]
|
||||
# run even if generate-changelog was skipped
|
||||
if: ${{ always() }}
|
||||
env:
|
||||
baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
|
||||
steps:
|
||||
- name: "➕ Setup Node"
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
node-version: '20'
|
||||
- name: "➕ Setup Hugo"
|
||||
uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
|
||||
with:
|
||||
|
|
@ -220,10 +217,8 @@ jobs:
|
|||
with:
|
||||
name: changelog-artifact
|
||||
path: content/changelog
|
||||
|
||||
- name: "⚙️ hugo"
|
||||
run: hugo --baseURL "${baseURL}" -d "spec${baseURL}"
|
||||
|
||||
run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
|
||||
# We manually unpack the spec OpenAPI definition JSON to the website tree
|
||||
# to make it available to the world in a canonical place:
|
||||
# https://spec.matrix.org/latest/client-server-api/api.json
|
||||
|
|
@ -234,13 +229,10 @@ jobs:
|
|||
name: openapi-artifact
|
||||
- name: "📝 Unpack the OpenAPI definitions in the right location"
|
||||
run: |
|
||||
tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
|
||||
tar -xzf openapi.tar.gz
|
||||
|
||||
- name: "📦 Tarball creation"
|
||||
run: |
|
||||
cd spec
|
||||
tar -czf ../spec.tar.gz *
|
||||
|
||||
run: tar -czf spec.tar.gz spec
|
||||
- name: "📤 Artifact upload"
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
|
|
@ -251,14 +243,6 @@ jobs:
|
|||
name: "🔎 Validate generated HTML"
|
||||
runs-on: ubuntu-latest
|
||||
needs: [calculate-baseurl, build-spec]
|
||||
# Run even if `generate-changelog` was skipped.
|
||||
#
|
||||
# `build-spec` has a dependency on `generate-changelog` to ensure order of execution
|
||||
# and to access `needs.generate-changelog.result`. However, `generate-changelog` is
|
||||
# skipped on tag builds; even a transient dependency on `generate-changelog` is then
|
||||
# enough for this step to also be skipped by default on tag builds. Hence the need for
|
||||
# this explicit `if`.
|
||||
if: ${{ !failure() && !cancelled() }}
|
||||
steps:
|
||||
- name: "📥 Source checkout"
|
||||
uses: actions/checkout@v4
|
||||
|
|
@ -269,9 +253,14 @@ jobs:
|
|||
name: spec-artifact
|
||||
|
||||
- name: "📝 Unpack the spec"
|
||||
# we have to unpack it into the right path given the baseurl, so that the
|
||||
# links are correct.
|
||||
# eg if baseurl is `/unstable`, we want to put the site in `spec/unstable`.
|
||||
run: |
|
||||
mkdir spec
|
||||
tar -C spec -xvzf spec.tar.gz
|
||||
mkdir -p "spec${baseURL}"
|
||||
tar -C "spec${baseURL}" --strip-components=1 -xvzf spec.tar.gz
|
||||
env:
|
||||
baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
|
||||
|
||||
- name: "Run htmltest"
|
||||
uses: wjdp/htmltest-action@master
|
||||
|
|
@ -281,15 +270,13 @@ jobs:
|
|||
build-historical-spec:
|
||||
name: "📖 Build the historical backup spec"
|
||||
runs-on: ubuntu-latest
|
||||
needs: [calculate-baseurl, build-openapi]
|
||||
needs: [build-openapi]
|
||||
if: ${{ startsWith(github.ref, 'refs/tags/') }}
|
||||
env:
|
||||
baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
|
||||
steps:
|
||||
- name: "➕ Setup Node"
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
node-version: '20'
|
||||
- name: "➕ Setup Hugo"
|
||||
uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
|
||||
with:
|
||||
|
|
@ -304,8 +291,9 @@ jobs:
|
|||
- name: "⚙️ hugo"
|
||||
env:
|
||||
HUGO_PARAMS_VERSION_STATUS: "historical"
|
||||
# Create a baseURL like `/v1.2` out of the `v1.2` tag
|
||||
run: |
|
||||
hugo --baseURL "${baseURL}" -d "spec${baseURL}"
|
||||
hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
|
||||
|
||||
- name: "📥 Spec definition download"
|
||||
uses: actions/download-artifact@v4
|
||||
|
|
@ -313,51 +301,12 @@ jobs:
|
|||
name: openapi-artifact
|
||||
- name: "📝 Unpack the OpenAPI definitions in the right location"
|
||||
run: |
|
||||
tar -C "spec${baseURL}" --strip-components=1 -xzf openapi.tar.gz
|
||||
tar -xzf openapi.tar.gz
|
||||
|
||||
- name: "📦 Tarball creation"
|
||||
run: |
|
||||
cd spec
|
||||
tar -czf ../spec-historical.tar.gz *
|
||||
|
||||
run: tar -czf spec-historical.tar.gz spec
|
||||
- name: "📤 Artifact upload"
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: spec-historical-artifact
|
||||
path: spec-historical.tar.gz
|
||||
|
||||
# If we're building a tag, create a release and publish the artifacts
|
||||
create_release:
|
||||
name: "Create release"
|
||||
if: ${{ !failure() && !cancelled() && startsWith(github.ref, 'refs/tags/') }}
|
||||
needs:
|
||||
- build-spec
|
||||
- build-historical-spec
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: "📥 Check out changelogs"
|
||||
uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
|
||||
with:
|
||||
sparse-checkout: |
|
||||
content/changelog
|
||||
- name: "📥 Download built spec"
|
||||
uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
|
||||
with:
|
||||
name: spec-artifact
|
||||
- name: "📥 Download historical spec artifact"
|
||||
uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
|
||||
with:
|
||||
name: spec-historical-artifact
|
||||
- name: "✨ Create draft release"
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
# Remove front-matter from changelog
|
||||
sed '1,/^---$/d' "content/changelog/${{ github.ref_name }}.md" > changelog.md
|
||||
|
||||
# Create a draft release, using the changelog as release notes, and attaching the spec artifacts.
|
||||
gh release create -d -t "${{ github.ref_name }}" \
|
||||
-F "changelog.md" \
|
||||
"${{ github.ref_name }}" \
|
||||
spec.tar.gz \
|
||||
spec-historical.tar.gz
|
||||
|
|
|
|||
4
.github/workflows/netlify.yaml
vendored
4
.github/workflows/netlify.yaml
vendored
|
|
@ -45,9 +45,7 @@ jobs:
|
|||
name: spec-artifact
|
||||
|
||||
- name: "📦 Extract Artifacts"
|
||||
run: |
|
||||
mkdir spec
|
||||
tar -C spec -xzvf spec.tar.gz && rm spec.tar.gz
|
||||
run: tar -xzvf spec.tar.gz && rm spec.tar.gz
|
||||
|
||||
- name: "📤 Deploy to Netlify"
|
||||
id: netlify
|
||||
|
|
|
|||
15
.github/workflows/release.yaml
vendored
15
.github/workflows/release.yaml
vendored
|
|
@ -12,9 +12,6 @@ jobs:
|
|||
defaults:
|
||||
run:
|
||||
working-directory: packages/npm
|
||||
permissions:
|
||||
contents: read
|
||||
id-token: write
|
||||
steps:
|
||||
- name: 🧮 Checkout code
|
||||
uses: actions/checkout@v4
|
||||
|
|
@ -26,10 +23,6 @@ jobs:
|
|||
cache-dependency-path: packages/npm/yarn.lock
|
||||
registry-url: "https://registry.npmjs.org"
|
||||
|
||||
# Ensure npm 11.5.1 or later is installed
|
||||
- name: Update npm
|
||||
run: sudo npm install -g npm@latest
|
||||
|
||||
- name: 🔨 Install dependencies
|
||||
run: "yarn install --frozen-lockfile"
|
||||
|
||||
|
|
@ -40,4 +33,10 @@ jobs:
|
|||
VERSION: ${{ github.event.release.tag_name }}.0
|
||||
|
||||
- name: 🚀 Publish to npm
|
||||
run: npm publish --provenance --access public --tag latest
|
||||
id: npm-publish
|
||||
uses: JS-DevTools/npm-publish@19c28f1ef146469e409470805ea4279d47c3d35c # v3.1.1
|
||||
with:
|
||||
token: ${{ secrets.NPM_TOKEN }}
|
||||
package: packages/npm
|
||||
access: public
|
||||
ignore-scripts: false
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@ place after an MSC has been accepted, not as part of a proposal itself.
|
|||
|
||||
1. Install the extended version (often the OS default) of Hugo:
|
||||
<https://gohugo.io/getting-started/installing>. Note that at least Hugo
|
||||
v0.155.0 is required.
|
||||
v0.146.0 is required.
|
||||
|
||||
Alternatively, use the Docker image at
|
||||
https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ function getHeadings() {
|
|||
let headings = [];
|
||||
|
||||
// First get the anchors in the ToC.
|
||||
const toc_anchors = document.querySelectorAll("#TableOfContents a");
|
||||
const toc_anchors = document.querySelectorAll("#toc nav a");
|
||||
|
||||
for (const anchor of toc_anchors) {
|
||||
// Then get the heading from its selector in the anchor's href.
|
||||
|
|
@ -122,13 +122,13 @@ function getCurrentHeading(headings, headerOffset) {
|
|||
*/
|
||||
function selectTocEntry(id) {
|
||||
// Deselect previously selected entries.
|
||||
const activeEntries = document.querySelectorAll("#TableOfContents a.active");
|
||||
const activeEntries = document.querySelectorAll("#toc nav a.active");
|
||||
for (const activeEntry of activeEntries) {
|
||||
activeEntry.classList.remove('active');
|
||||
}
|
||||
|
||||
// Find the new entry and select it.
|
||||
const newEntry = document.querySelector(`#TableOfContents a[href="#${id}"]`);
|
||||
const newEntry = document.querySelector(`#toc nav a[href="#${id}"]`);
|
||||
if (!newEntry) {
|
||||
console.error("ToC entry not found for ID:", id);
|
||||
return;
|
||||
|
|
|
|||
|
|
@ -1,114 +0,0 @@
|
|||
/*
|
||||
Copyright 2025 The Matrix.org Foundation C.I.C.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
*/
|
||||
|
||||
// Determine the current version as defined in hugo.toml. This will either be
|
||||
// "unstable" or "vX.X" and doesn't depend on the current URL.
|
||||
//
|
||||
// The oddity below is an attempt at producing a readable Hugo template while
|
||||
// avoiding JS syntax errors in your IDE.
|
||||
const currentVersion = `{{ if eq .Site.Params.version.status "unstable" }}
|
||||
{{- /**/ -}}
|
||||
unstable
|
||||
{{- /**/ -}}
|
||||
{{ else }}
|
||||
{{- /**/ -}}
|
||||
{{ printf "v%s.%s" .Site.Params.version.major .Site.Params.version.minor }}
|
||||
{{- /**/ -}}
|
||||
{{ end }}`;
|
||||
|
||||
// Determine the current version segment by regex matching the URL. This will either
|
||||
// be "unstable", "latest", "vX.X" (production) or undefined (local & netlify).
|
||||
const href = window.location.href;
|
||||
const segmentMatches = href.match(/(?<=\/)unstable|latest|v\d+.\d+(?=\/)/);
|
||||
const currentSegment = segmentMatches ? segmentMatches[0] : undefined;
|
||||
|
||||
// Determine the selected menu element. If we were able to obtain the version
|
||||
// segment from the URL (production), use that. Otherwise (local & netlify),
|
||||
// fall back to the version as defined in Hugo.
|
||||
const selected = currentSegment ?? currentVersion;
|
||||
|
||||
function appendVersion(parent, name, segment, url) {
|
||||
// The list item
|
||||
const li = document.createElement("li");
|
||||
if (segment === selected) {
|
||||
li.classList.add("version-picker-selected");
|
||||
}
|
||||
if (segment === "latest") {
|
||||
li.classList.add("version-picker-latest");
|
||||
}
|
||||
parent.appendChild(li);
|
||||
|
||||
// The link
|
||||
const a = document.createElement("a");
|
||||
a.classList.add("dropdown-item");
|
||||
a.setAttribute("href", url);
|
||||
li.appendChild(a);
|
||||
|
||||
// Handle clicks manually to preserve the current path / fragment
|
||||
a.addEventListener("click", (ev) => {
|
||||
// If the URL is a relative link (i.e. the historical versions changelog), just
|
||||
// let the browser load it
|
||||
if (url.startsWith("/")) {
|
||||
return;
|
||||
}
|
||||
|
||||
// If we couldn't determine the current segment, we cannot safely replace
|
||||
// it and have to let the browser load the (root) URL instead
|
||||
if (!currentSegment) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Otherwise, stop further event handling and replace the segment
|
||||
ev.preventDefault();
|
||||
ev.stopPropagation();
|
||||
window.location.href = href.replace(`/${currentSegment}/`, `/${segment}/`);
|
||||
});
|
||||
|
||||
// The link text
|
||||
const text = document.createTextNode(name);
|
||||
a.appendChild(text);
|
||||
}
|
||||
|
||||
// If we're in the unstable version, we're the latest thing and can just load
|
||||
// versions.json from our own resources. Otherwise, we fall back to loading it
|
||||
// from /unstable/versions.json, assuming we are on the spec.matrix.org deployment.
|
||||
const url = currentVersion === "unstable"
|
||||
? '{{ .Site.Home.Permalink }}versions.json'
|
||||
: "/unstable/versions.json";
|
||||
|
||||
fetch(url)
|
||||
.then(r => r.json())
|
||||
.then(versions => {
|
||||
// Find the surrounding list element
|
||||
const ul = document.querySelector("ul#version-selector");
|
||||
if (!ul) {
|
||||
console.error("Cannot populate version selector: ul element not found");
|
||||
return;
|
||||
}
|
||||
|
||||
// Add a entries for the unstable version and the "latest" shortcut
|
||||
appendVersion(ul, "unstable", "unstable", "https://spec.matrix.org/unstable");
|
||||
const latestName = versions?.length ? `latest (${versions[0].name})` : "latest";
|
||||
appendVersion(ul, latestName, "latest", "https://spec.matrix.org/latest");
|
||||
|
||||
// Add an entry for each proper version
|
||||
for (const version of versions) {
|
||||
appendVersion(ul, version.name, version.name, `https://spec.matrix.org/${version.name}`);
|
||||
}
|
||||
|
||||
// For historical versions, simply link to the changelog
|
||||
appendVersion(ul, "historical", "historical", '{{ (site.GetPage "changelog/historical").RelPermalink }}');
|
||||
});
|
||||
|
|
@ -50,20 +50,6 @@ Custom SCSS for the Matrix spec
|
|||
a {
|
||||
color: $black;
|
||||
}
|
||||
|
||||
/* Make the version dropdown scroll if it's too large */
|
||||
ul#version-selector {
|
||||
max-height: 80vh;
|
||||
overflow-y: auto;
|
||||
}
|
||||
|
||||
ul#version-selector li.version-picker-selected a {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
ul#version-selector li.version-picker-latest a {
|
||||
color: $secondary;
|
||||
}
|
||||
}
|
||||
|
||||
/* Styles for the sidebar nav */
|
||||
|
|
@ -76,10 +62,11 @@ Custom SCSS for the Matrix spec
|
|||
scroll-behavior: smooth;
|
||||
overscroll-behavior: contain;
|
||||
|
||||
& > .td-sidebar-nav__section {
|
||||
&>.td-sidebar-nav__section {
|
||||
margin-top: 1rem;
|
||||
}
|
||||
|
||||
.ul-1 ul {
|
||||
.td-sidebar-nav__section .ul-1 ul {
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
|
|
@ -96,83 +83,8 @@ Custom SCSS for the Matrix spec
|
|||
.ul-2 > li > a {
|
||||
padding-left: 2rem !important;
|
||||
}
|
||||
}
|
||||
|
||||
/* Styles for the table of contents */
|
||||
& > .td-toc {
|
||||
padding-top: 1rem;
|
||||
padding-left: 1.5rem;
|
||||
/* Add border above the toc */
|
||||
border-top: 1px solid var(--bs-tertiary-color);
|
||||
|
||||
ol {
|
||||
padding-left: 1rem;
|
||||
counter-reset: section;
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
#TableOfContents {
|
||||
/* Remove the space between the title and the ToC */
|
||||
margin-top: 0;
|
||||
|
||||
&>ol>li {
|
||||
margin-bottom: .5rem;
|
||||
|
||||
&>a {
|
||||
font-weight: $font-weight-bold;
|
||||
}
|
||||
}
|
||||
|
||||
ol {
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
&>ol>li>a {
|
||||
padding-left: 1rem;
|
||||
}
|
||||
|
||||
&>ol>li>ol>li>a {
|
||||
padding-left: 2rem;
|
||||
}
|
||||
|
||||
&>ol>li>ol>li>ol>li>a {
|
||||
padding-left: 3rem;
|
||||
}
|
||||
|
||||
&>ol>li>ol>li>ol>li>ol>li>a {
|
||||
padding-left: 4rem;
|
||||
}
|
||||
|
||||
&>ol>li>ol>li>ol>li>ol>li>ol>li>a {
|
||||
padding-left: 5rem;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
li a:before {
|
||||
counter-increment: section;
|
||||
content: counters(section, ".") " ";
|
||||
}
|
||||
|
||||
.td-toc-title {
|
||||
font-weight: $font-weight-bold;
|
||||
font-size: 1.3rem;
|
||||
|
||||
/* Remove the border under the title */
|
||||
border-bottom: 0;
|
||||
/* Remove the space under the title */
|
||||
margin-bottom: 0;
|
||||
|
||||
/* Fix the top of page link color */
|
||||
a, a:hover {
|
||||
color: $secondary;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* Apply the same style to links in the navigation and in the ToC */
|
||||
& > .td-sidebar-nav__section, & > .td-toc #TableOfContents {
|
||||
li a.td-sidebar-link.tree-root {
|
||||
a.td-sidebar-link.tree-root {
|
||||
color: $gray-800;
|
||||
font-weight: $font-weight-bold;
|
||||
font-size: 1.3rem;
|
||||
|
|
@ -180,12 +92,13 @@ Custom SCSS for the Matrix spec
|
|||
border-bottom: none;
|
||||
}
|
||||
|
||||
li a, li a.td-sidebar-link {
|
||||
a, a.td-sidebar-link {
|
||||
color: $gray-800;
|
||||
font-weight: $font-weight-normal;
|
||||
padding-top: .2rem;
|
||||
padding-bottom: .2rem;
|
||||
|
||||
display: block;
|
||||
transition: all 100ms ease-in-out;
|
||||
|
||||
&:hover {
|
||||
|
|
@ -197,7 +110,6 @@ Custom SCSS for the Matrix spec
|
|||
background-color: $secondary-background;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@include media-breakpoint-up(md) {
|
||||
|
|
@ -273,67 +185,62 @@ Custom SCSS for the Matrix spec
|
|||
scroll-margin-top: 5.5rem;
|
||||
}
|
||||
|
||||
.endpoints-toc {
|
||||
summary {
|
||||
cursor: pointer;
|
||||
font-weight: $font-weight-bold;
|
||||
font-size: 1.05rem;
|
||||
margin-bottom: 0.5rem;
|
||||
/* Styles for the table of contents */
|
||||
#toc {
|
||||
padding-top: .5rem;
|
||||
padding-left: 1.5rem;
|
||||
|
||||
ol {
|
||||
padding-left: 1rem;
|
||||
counter-reset: section;
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
.endpoint-list {
|
||||
list-style: none;
|
||||
#TableOfContents {
|
||||
&>ol>li {
|
||||
margin-bottom: .5rem;
|
||||
|
||||
&>a {
|
||||
font-weight: $font-weight-bold;
|
||||
}
|
||||
}
|
||||
|
||||
ol {
|
||||
padding-left: 0;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.endpoint-list li {
|
||||
margin: 0.2rem 0;
|
||||
&>ol>li>a {
|
||||
padding-left: 1rem;
|
||||
}
|
||||
|
||||
.endpoint-list a {
|
||||
text-decoration: none;
|
||||
color: inherit;
|
||||
padding: 0.05rem 0.25rem;
|
||||
border-radius: 0.2rem;
|
||||
|
||||
&:hover {
|
||||
background-color: $secondary-background;
|
||||
}
|
||||
&>ol>li>ol>li>a {
|
||||
padding-left: 2rem;
|
||||
}
|
||||
|
||||
.endpoint-list .http-api-method {
|
||||
margin-right: 0.35rem;
|
||||
&>ol>li>ol>li>ol>li>a {
|
||||
padding-left: 3rem;
|
||||
}
|
||||
|
||||
&>ol>li>ol>li>ol>li>ol>li>a {
|
||||
padding-left: 4rem;
|
||||
}
|
||||
|
||||
&>ol>li>ol>li>ol>li>ol>li>ol>li>a {
|
||||
padding-left: 5rem;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
li a:before {
|
||||
counter-increment: section;
|
||||
content: counters(section, ".") " ";
|
||||
}
|
||||
|
||||
#toc-title {
|
||||
font-weight: $font-weight-bold;
|
||||
font-size: 1.3rem;
|
||||
}
|
||||
|
||||
.endpoint-path {
|
||||
font-family: $font-family-monospace;
|
||||
color: $secondary;
|
||||
}
|
||||
|
||||
.endpoint-deprecated {
|
||||
color: $danger;
|
||||
font-weight: $font-weight-bold;
|
||||
margin-left: 0.35rem;
|
||||
}
|
||||
|
||||
.endpoint-module {
|
||||
&:not(:first-child) {
|
||||
margin-top: 0.75rem;
|
||||
}
|
||||
}
|
||||
|
||||
.endpoint-module-title {
|
||||
// font-weight: $font-weight-bold;
|
||||
font-size: 1.20rem;
|
||||
margin-bottom: 0.35rem;
|
||||
}
|
||||
}
|
||||
|
||||
.page-description {
|
||||
margin-bottom: 1rem;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
/* Styles for alert boxes */
|
||||
|
|
@ -595,13 +502,6 @@ Make padding symmetrical (this selector is used in the default styles to apply p
|
|||
}
|
||||
}
|
||||
|
||||
/* Adjust the width of math to match normal paragraphs */
|
||||
@include media-breakpoint-up(lg) {
|
||||
.katex-display {
|
||||
max-width: 80%;
|
||||
}
|
||||
}
|
||||
|
||||
/* Adjust default styles for info banner */
|
||||
.pageinfo-primary {
|
||||
@include media-breakpoint-up(lg) {
|
||||
|
|
|
|||
|
|
@ -18,7 +18,6 @@ $primary: #FFF;
|
|||
$secondary: #0098D4;
|
||||
$dark: #333;
|
||||
$gray-100: #FBFBFB;
|
||||
$code-color: #005b7f;
|
||||
|
||||
$secondary-background: #E5F5FB;
|
||||
$secondary-lighter-background: #F4FAFC;
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify SAS commitment calculation for `m.key.verification.accept` messages.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Specify `unsigned.replaces_state` in client-formatted events. Contributed by @nexy7574.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix ordering of common error codes.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify how to find `via` parameter when following room upgrades.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Specify `m.key_backup` account data, as per [MSC4287](https://github.com/matrix-org/matrix-spec-proposals/pull/4287).
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify formats of string types.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update and fix GitHub Actions.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Upgrade Docsy theme to v0.14.3.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Configure a new changelog section for the Olm & Megolm specs.
|
||||
|
|
@ -1 +0,0 @@
|
|||
!.gitignore
|
||||
|
|
@ -1 +0,0 @@
|
|||
Update links to Olm in the Megolm section to point to the Matrix spec.
|
||||
|
|
@ -57,10 +57,6 @@
|
|||
name = "Room Versions"
|
||||
path = "room_versions"
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "Olm & Megolm"
|
||||
path = "olm_megolm"
|
||||
|
||||
[[tool.towncrier.section]]
|
||||
name = "Appendices"
|
||||
path = "appendices"
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify the behaviour and response format of `GET /_matrix/federation/v1/query/profile`.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Clarify how multiple signatures should be handled during signature verification. Contributed by @nexy7574.
|
||||
|
|
@ -1 +0,0 @@
|
|||
Fix various typos throughout the specification.
|
||||
|
|
@ -43,15 +43,6 @@ description = "Home of the Matrix specification for decentralised communication"
|
|||
[markup.goldmark.renderer]
|
||||
# Enables us to render raw HTML
|
||||
unsafe = true
|
||||
[markup.goldmark.extensions]
|
||||
# Tell Goldmark to pass delimited blocks through the `render-passthrough` render hook.
|
||||
# This is used to render the maths in the Olm spec.
|
||||
# See: https://gohugo.io/functions/transform/tomath/#step-1.
|
||||
[markup.goldmark.extensions.passthrough]
|
||||
enable = true
|
||||
[markup.goldmark.extensions.passthrough.delimiters]
|
||||
block = [['\[', '\]']]
|
||||
inline = [['\(', '\)']]
|
||||
[markup.highlight]
|
||||
# See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
|
||||
# If the style is changed, remember to regenerate the CSS with:
|
||||
|
|
@ -65,22 +56,18 @@ description = "Home of the Matrix specification for decentralised communication"
|
|||
# Everything below this are Site Params
|
||||
|
||||
[params]
|
||||
copyright = "The Matrix.org Foundation C.I.C."
|
||||
copyright = "The Matrix.org Foundation CIC"
|
||||
|
||||
[params.version]
|
||||
# must be one of "unstable", "current", "historical"
|
||||
# this is used to decide whether to show a banner pointing to the current release
|
||||
status = "unstable"
|
||||
status = "stable"
|
||||
# A URL pointing to the latest, stable release of the spec. To be shown in the unstable version warning banner.
|
||||
current_version_url = "https://spec.matrix.org/latest"
|
||||
# The following is used when status = "stable", and is displayed in various UI elements on a released version
|
||||
# of the spec.
|
||||
#major = "1"
|
||||
#minor = "18"
|
||||
|
||||
[[params.versions]]
|
||||
# We must include this parameter to enable docsy's version picker in the navbar. The picker
|
||||
# is populated automatically in navbar-version-selector.html.
|
||||
major = "1"
|
||||
minor = "16"
|
||||
|
||||
# User interface configuration
|
||||
[params.ui]
|
||||
|
|
@ -115,31 +102,16 @@ sidebar_menu_compact = true
|
|||
url = "https://gitlab.matrix.org/matrix-org"
|
||||
icon = "fab fa-gitlab"
|
||||
desc = "Matrix on GitLab"
|
||||
[[params.links.bottom]]
|
||||
name = "Mastodon"
|
||||
url = "https://mastodon.matrix.org/@matrix"
|
||||
icon = "fab fa-mastodon"
|
||||
desc = "Matrix on Mastodon"
|
||||
[[params.links.bottom]]
|
||||
name = "Bluesky"
|
||||
url = "https://bsky.app/profile/matrix.org"
|
||||
icon = "fab fa-bluesky"
|
||||
desc = "Matrix on Bluesky"
|
||||
[[params.links.bottom]]
|
||||
name = "LinkedIn"
|
||||
url = "https://www.linkedin.com/company/matrix-org/"
|
||||
icon = "fab fa-linkedin"
|
||||
desc = "Matrix on LinkedIn"
|
||||
[[params.links.bottom]]
|
||||
name = "YouTube"
|
||||
url = "https://www.youtube.com/channel/UCVFkW-chclhuyYRbmmfwt6w"
|
||||
icon = "fab fa-youtube"
|
||||
desc = "Matrix YouTube channel"
|
||||
[[params.links.bottom]]
|
||||
name = "Matrix.org Blog Feed"
|
||||
url = "https://matrix.org/atom.xml"
|
||||
icon = "fas fa-rss"
|
||||
desc = "Matrix.org Blog Atom Feed"
|
||||
name = "Twitter"
|
||||
url = "https://twitter.com/matrixdotorg"
|
||||
icon = "fab fa-twitter"
|
||||
desc = "Matrix on Twitter"
|
||||
|
||||
|
||||
# configuration for the hugo development server
|
||||
|
|
@ -149,9 +121,7 @@ sidebar_menu_compact = true
|
|||
[[server.headers]]
|
||||
for = '/**'
|
||||
[server.headers.values]
|
||||
# `style-src 'unsafe-inline'` is needed to correctly render the maths in the Olm spec:
|
||||
# https://github.com/KaTeX/KaTeX/issues/4096
|
||||
Content-Security-Policy = "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
|
||||
Content-Security-Policy = "default-src 'self'; style-src 'self'; script-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; media-src 'self'; child-src 'self'; form-action 'self'; object-src 'self'"
|
||||
X-XSS-Protection = "1; mode=block"
|
||||
X-Content-Type-Options = "nosniff"
|
||||
# Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
|
||||
|
|
@ -176,11 +146,3 @@ sidebar_menu_compact = true
|
|||
mediaType = "text/markdown"
|
||||
isPlainText = true
|
||||
baseName = "checklist"
|
||||
|
||||
# Add font media types for downloading KaTeX fonts.
|
||||
# See: https://www.docsy.dev/docs/content/diagrams-and-formulae/#create-media-types-for-katex-fonts
|
||||
[mediaTypes]
|
||||
[mediaTypes.'font/woff']
|
||||
suffixes = ['woff']
|
||||
[mediaTypes.'font/woff2']
|
||||
suffixes = ['woff2']
|
||||
|
|
|
|||
|
|
@ -25,7 +25,6 @@ The specification consists of the following parts:
|
|||
* [Identity Service API](/identity-service-api)
|
||||
* [Push Gateway API](/push-gateway-api)
|
||||
* [Room Versions](/rooms)
|
||||
* [Olm & Megolm](/olm-megolm)
|
||||
* [Appendices](/appendices)
|
||||
|
||||
Additionally, this introduction page contains the key baseline
|
||||
|
|
@ -152,7 +151,7 @@ request.
|
|||
|
||||
How data flows between clients:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{ Matrix client A } { Matrix client B }
|
||||
^ | ^ |
|
||||
| events | Client-Server API | events |
|
||||
|
|
|
|||
|
|
@ -533,11 +533,6 @@ where `domain` is the [server name](#server-name) of the homeserver
|
|||
which allocated the identifier, and `localpart` is an identifier
|
||||
allocated by that homeserver.
|
||||
|
||||
Because the domain part identifies the server on which the ID resolves,
|
||||
the canonical pronunciation of the separating `:` is "on".
|
||||
For example, `@user:matrix.org` would be pronounced as "at user on matrix dot
|
||||
org".
|
||||
|
||||
The precise grammar defining the allowable format of an identifier
|
||||
depends on the type of identifier. For example, event IDs can sometimes
|
||||
be represented with a `domain` component under some conditions - see the
|
||||
|
|
@ -754,13 +749,13 @@ history (a permalink).
|
|||
|
||||
The Matrix URI scheme is defined as follows (`[]` enclose optional parts, `{}`
|
||||
enclose variables):
|
||||
```nohighlight
|
||||
```
|
||||
matrix:[//{authority}/]{type}/{id without sigil}[/{type}/{id without sigil}...][?{query}][#{fragment}]
|
||||
```
|
||||
|
||||
As a schema, this can be represented as:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
MatrixURI = "matrix:" hier-part [ "?" query ] [ "#" fragment ]
|
||||
hier-part = [ "//" authority "/" ] path
|
||||
path = entity-descriptor ["/" entity-descriptor]
|
||||
|
|
@ -870,7 +865,7 @@ below for more details.
|
|||
A matrix.to URI has the following format, based upon the specification
|
||||
defined in [RFC 3986](https://tools.ietf.org/html/rfc3986):
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
https://matrix.to/#/<identifier>/<extra parameter>?<additional arguments>
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -2,14 +2,16 @@
|
|||
title: "Application Service API"
|
||||
weight: 30
|
||||
type: docs
|
||||
description: |
|
||||
The Matrix client-server API and server-server APIs provide a consistent,
|
||||
self-contained federated messaging fabric but leave little room for custom
|
||||
server-side behaviour such as gateways, filters, or extensible hooks. The
|
||||
Application Service API defines a standard way to add this extensible
|
||||
functionality, independent of the underlying homeserver implementation.
|
||||
---
|
||||
|
||||
The Matrix client-server API and server-server APIs provide the means to
|
||||
implement a consistent self-contained federated messaging fabric.
|
||||
However, they provide limited means of implementing custom server-side
|
||||
behaviour in Matrix (e.g. gateways, filters, extensible hooks etc). The
|
||||
Application Service API (AS API) defines a standard API to allow such
|
||||
extensible functionality to be implemented irrespective of the
|
||||
underlying homeserver implementation.
|
||||
|
||||
## Application Services
|
||||
|
||||
Application services are passive and can only observe events from the
|
||||
|
|
@ -84,7 +86,7 @@ For the `users` namespace, application services can only register interest in
|
|||
homeserver). Events affecting users on other homeservers are not sent to an application
|
||||
service, even if the user happens to match the one of the `users` namespaces (unless,
|
||||
of course, the event affects a room that the application service is interested in
|
||||
for another reason - for example, because there is another user in the room that the
|
||||
for another room - for example, because there is another user in the room that the
|
||||
application service is interested in).
|
||||
|
||||
For the `rooms` and `aliases` namespaces, all events in a matching room will be
|
||||
|
|
@ -100,7 +102,7 @@ this.
|
|||
|
||||
### Homeserver -> Application Service API
|
||||
|
||||
#### Authorisation
|
||||
#### Authorization
|
||||
|
||||
{{% changed-in v="1.4" %}}
|
||||
|
||||
|
|
@ -176,13 +178,13 @@ The application service API provides a transaction API for sending a
|
|||
list of events. Each list of events includes a transaction ID, which
|
||||
works as follows:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
Typical
|
||||
HS ---> AS : Homeserver sends events with transaction ID T.
|
||||
<--- : Application Service sends back 200 OK.
|
||||
```
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
AS ACK Lost
|
||||
HS ---> AS : Homeserver sends events with transaction ID T.
|
||||
<-/- : AS 200 OK is lost.
|
||||
|
|
@ -256,7 +258,7 @@ have been omitted for brevity):
|
|||
|
||||
**Typical**
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
|
||||
HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
|
||||
HS <--- AS : 200 OK {}
|
||||
|
|
@ -265,7 +267,7 @@ AS <--- HS : 200 OK {"duration_ms": 123}
|
|||
|
||||
**Incorrect `hs_token`**
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
|
||||
HS ---> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
|
||||
HS <--- AS : 403 Forbidden {"errcode": "M_FORBIDDEN"}
|
||||
|
|
@ -274,7 +276,7 @@ AS <--- HS : 502 Bad Gateway {"errcode": "M_BAD_STATUS", "status": 403, "body":
|
|||
|
||||
**Can't connect to appservice**
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
AS ---> HS : /_matrix/client/v1/appservice/{appserviceId}/ping {"transaction_id": "meow"}
|
||||
HS -/-> AS : /_matrix/app/v1/ping {"transaction_id": "meow"}
|
||||
AS <--- HS : 502 Bad Gateway {"errcode": "M_CONNECTION_FAILED"}
|
||||
|
|
@ -354,7 +356,6 @@ service would like to masquerade as.
|
|||
Inputs:
|
||||
- Application service token (`as_token`)
|
||||
- User ID in the AS namespace to act as.
|
||||
- Device ID belonging to the User ID to act with.
|
||||
|
||||
Notes:
|
||||
- This applies to all aspects of the Client-Server API, except for
|
||||
|
|
@ -374,19 +375,9 @@ service's `user` namespaces. If the parameter is missing, the homeserver
|
|||
is to assume the application service intends to act as the user implied
|
||||
by the `sender_localpart` property of the registration.
|
||||
|
||||
{{% added-in v="1.17" %}} Application services MAY similarly masquerade
|
||||
as a specific device ID belonging the user ID through use of the `device_id`
|
||||
query string parameter on the request. If the given device ID is not known
|
||||
to belong to the user, the server will return a 400 `M_UNKNOWN_DEVICE` error.
|
||||
If no `user_id` is supplied, the `device_id` MUST belong to the user implied
|
||||
by the `sender_localpart` property of the application service's registration.
|
||||
If no `device_id` is supplied, the homeserver is to assume the request is
|
||||
being made without a device ID and will fail to complete operations which
|
||||
require a device ID (such as uploading one-time keys).
|
||||
|
||||
An example request would be:
|
||||
|
||||
GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org&device_id=ABC123
|
||||
GET /_matrix/client/v3/account/whoami?user_id=@_irc_user:example.org
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
|
||||
#### Timestamp massaging
|
||||
|
|
@ -426,8 +417,6 @@ imports and similar behaviour).
|
|||
|
||||
#### Server admin style permissions
|
||||
|
||||
{{% changed-in v="1.17" %}}
|
||||
|
||||
The homeserver needs to give the application service *full control* over
|
||||
its namespace, both for users and for room aliases. This means that the
|
||||
AS should be able to manage any users and room alias in its namespace. No additional API
|
||||
|
|
@ -444,59 +433,33 @@ achieved by including the `as_token` on a `/register` request, along
|
|||
with a login type of `m.login.application_service` to set the desired
|
||||
user ID without a password.
|
||||
|
||||
```http
|
||||
POST /_matrix/client/v3/register
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
```
|
||||
POST /_matrix/client/v3/register
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "m.login.application_service",
|
||||
"username": "_irc_example"
|
||||
}
|
||||
```
|
||||
Content:
|
||||
{
|
||||
type: "m.login.application_service",
|
||||
username: "_irc_example"
|
||||
}
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
Servers MUST still allow application services to use the `/register` endpoint
|
||||
with a login type of `m.login.application_service` even if they don't support
|
||||
the [Legacy Authentication API](/client-server-api/#legacy-api).
|
||||
|
||||
In that case application services MUST set the `"inhibit_login": true` parameter
|
||||
as they cannot use it to log in as users. If the `inhibit_login` parameter is
|
||||
not set to `true`, the server MUST return a 400 HTTP status code with an
|
||||
`M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Similarly, logging in as users using the [Legacy authentication API](/client-server-api/#legacy-api)
|
||||
needs API changes in order to allow the AS to log in without needing the user's
|
||||
password. This is achieved by including the `as_token` on a `/login` request,
|
||||
along with a login type of `m.login.application_service`:
|
||||
Similarly, logging in as users needs API changes in order to allow the AS to
|
||||
log in without needing the user's password. This is achieved by including the
|
||||
`as_token` on a `/login` request, along with a login type of
|
||||
`m.login.application_service`:
|
||||
|
||||
{{% added-in v="1.2" %}}
|
||||
|
||||
```http
|
||||
POST /_matrix/client/v3/login
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
```
|
||||
POST /_matrix/client/v3/login
|
||||
Authorization: Bearer YourApplicationServiceTokenHere
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "m.login.application_service",
|
||||
Content:
|
||||
{
|
||||
type: "m.login.application_service",
|
||||
"identifier": {
|
||||
"type": "m.id.user",
|
||||
"user": "_irc_example"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.17" %}}
|
||||
Application services MUST NOT use the `/login` endpoint if the server doesn't
|
||||
support the Legacy authentication API. If `/login` is called with the
|
||||
`m.login.application_service` login type the server MUST return a 400 HTTP
|
||||
status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.
|
||||
{{% /boxes/note %}}
|
||||
}
|
||||
|
||||
Application services which attempt to create users or aliases *outside*
|
||||
of their defined namespaces, or log in as users outside of their defined
|
||||
|
|
@ -538,38 +501,6 @@ client-server endpoint.
|
|||
|
||||
{{% http-api spec="client-server" api="appservice_room_directory" %}}
|
||||
|
||||
#### Device management
|
||||
|
||||
{{% added-in v="1.17" %}}
|
||||
|
||||
Application services need to be able to create and delete devices to manage the
|
||||
encryption for their users without having to rely on `/login`, which also
|
||||
generates an access token for the user, and which might not be available for
|
||||
homeservers that only support the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
|
||||
##### Creating devices
|
||||
|
||||
Application services can use the [`PUT /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#put_matrixclientv3devicesdeviceid)
|
||||
endpoint to create new devices.
|
||||
|
||||
##### Deleting devices
|
||||
|
||||
The following endpoints used to delete devices MUST NOT require [User-Interactive
|
||||
Authentication](/client-server-api/#user-interactive-authentication-api) when
|
||||
used by an application service:
|
||||
|
||||
* [`DELETE /_matrix/client/v3/devices/{deviceId}`](/client-server-api/#delete_matrixclientv3devicesdeviceid)
|
||||
* [`POST /_matrix/client/v3/delete_devices`](/client-server-api/#post_matrixclientv3delete_devices)
|
||||
|
||||
#### Cross-signing
|
||||
|
||||
{{% added-in v="1.17" %}}
|
||||
|
||||
Appservices need to be able to verify themselves and replace their cross-signing
|
||||
keys, so the [`POST /_matrix/client/v3/keys/device_signing/upload`](/client-server-api/#post_matrixclientv3keysdevice_signingupload)
|
||||
endpoint MUST NOT require [User-Interactive Authentication](/client-server-api/#user-interactive-authentication-api)
|
||||
when used by an application service, even if cross-signing keys already exist.
|
||||
|
||||
### Referencing messages from a third-party network
|
||||
|
||||
Application services should include an `external_url` in the `content`
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ No significant changes.
|
|||
|
||||
**Spec Clarifications**
|
||||
|
||||
- For room versions 6 and 7, clarify in the authorisation rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- For room versions 6 and 7, clarify in the authorization rules that `m.federate` must be checked and that events with rejected auth events must be rejected, for parity with all the other room versions. ([#2065](https://github.com/matrix-org/matrix-spec/issues/2065))
|
||||
- Fix various typos throughout the specification. ([#2066](https://github.com/matrix-org/matrix-spec/issues/2066))
|
||||
- Refactor PDU definitions to reduce duplication. ([#2070](https://github.com/matrix-org/matrix-spec/issues/2070))
|
||||
- Clarify the maximum `depth` value for room versions 6, 7, 8, 9, 10, and 11. ([#2114](https://github.com/matrix-org/matrix-spec/issues/2114))
|
||||
|
|
|
|||
|
|
@ -1,91 +0,0 @@
|
|||
---
|
||||
title: v1.17 Changelog
|
||||
linkTitle: v1.17
|
||||
type: docs
|
||||
layout: changelog
|
||||
outputs:
|
||||
- html
|
||||
- checklist
|
||||
date: 2025-12-18
|
||||
---
|
||||
|
||||
## Client-Server API
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210). ([#2186](https://github.com/matrix-org/matrix-spec/issues/2186))
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
|
||||
- Add the `m.oauth` authentication type for User-Interactive Authentication, as per [MSC4312](https://github.com/matrix-org/matrix-spec-proposals/pull/4312). ([#2234](https://github.com/matrix-org/matrix-spec/issues/2234))
|
||||
- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Push rule IDs are globally unique within their kind. ([#2214](https://github.com/matrix-org/matrix-spec/issues/2214))
|
||||
- Don't advertise `creator` field in description of room creation. ([#2215](https://github.com/matrix-org/matrix-spec/issues/2215))
|
||||
- `room_id` is required for peeking via `/_matrix/client/v3/events`. ([#2216](https://github.com/matrix-org/matrix-spec/issues/2216))
|
||||
- The `server-name` segment of MXC URIs is sanitised differently from the `media-id` segment. ([#2217](https://github.com/matrix-org/matrix-spec/issues/2217))
|
||||
- Add note to each endpoint that uses capability negotiation. ([#2223](https://github.com/matrix-org/matrix-spec/issues/2223))
|
||||
- Additional OpenGraph properties can be present in URL previews. ([#2225](https://github.com/matrix-org/matrix-spec/issues/2225))
|
||||
- Clarify the special casing of membership events and redactions in power levels. ([#2231](https://github.com/matrix-org/matrix-spec/issues/2231))
|
||||
- `M_RESOURCE_LIMIT_EXCEEDED` is now listed as a common error code. ([#2232](https://github.com/matrix-org/matrix-spec/issues/2232))
|
||||
- Add `m.login.terms` to enumeration of authentication types. ([#2233](https://github.com/matrix-org/matrix-spec/issues/2233))
|
||||
- Clarify how to use `state_after` ahead of declaring full support for its spec version. ([#2240](https://github.com/matrix-org/matrix-spec/issues/2240))
|
||||
- `device_one_time_keys_count` is only optional if no unclaimed one-time keys exist. ([#2245](https://github.com/matrix-org/matrix-spec/issues/2245))
|
||||
- Clarify that servers may choose not to use `M_USER_DEACTIVATED` at login time, for example for privacy reasons when they can't authenticate deactivated users. ([#2246](https://github.com/matrix-org/matrix-spec/issues/2246))
|
||||
- Usage of the `event_id_only` format for push notifications is not mandatory. ([#2255](https://github.com/matrix-org/matrix-spec/issues/2255))
|
||||
- Fix various typos throughout the specification. ([#2224](https://github.com/matrix-org/matrix-spec/issues/2224), [#2227](https://github.com/matrix-org/matrix-spec/issues/2227), [#2250](https://github.com/matrix-org/matrix-spec/issues/2250))
|
||||
|
||||
|
||||
## Server-Server API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Application Service API
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Allow application services to masquerade as specific devices belonging to users, as per [MSC4326](https://github.com/matrix-org/matrix-spec-proposals/pull/4326). ([#2221](https://github.com/matrix-org/matrix-spec/issues/2221))
|
||||
- Allow application services to manage devices and register users without the legacy authentication API, as per [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190). ([#2267](https://github.com/matrix-org/matrix-spec/issues/2267))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Fix JSON formatting in the "Server admin style permissions" examples. ([#2213](https://github.com/matrix-org/matrix-spec/issues/2213))
|
||||
|
||||
|
||||
## Identity Service API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Push Gateway API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Room Versions
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- In room versions 8 through 12, clarify that "sufficient permission to invite users" on restricted joins also includes being a joined member of the room. ([#2220](https://github.com/matrix-org/matrix-spec/issues/2220))
|
||||
- In room versions 3 through 12, clarify that when you have the power to redact, it is possible to redact events that you don't have the power to send. ([#2249](https://github.com/matrix-org/matrix-spec/issues/2249))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Internal Changes/Tooling
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Swapped icon for X (fka. twitter) to updated logo in footer. ([#2219](https://github.com/matrix-org/matrix-spec/issues/2219))
|
||||
- Inline Olm & Megolm specifications. ([#2226](https://github.com/matrix-org/matrix-spec/issues/2226), [#2241](https://github.com/matrix-org/matrix-spec/issues/2241), [#2242](https://github.com/matrix-org/matrix-spec/issues/2242))
|
||||
- Silence failing redocly-cli rule. ([#2238](https://github.com/matrix-org/matrix-spec/issues/2238))
|
||||
- Use NPM Trusted Publishers for publishing `@matrix-org/spec` to npm. ([#2239](https://github.com/matrix-org/matrix-spec/issues/2239))
|
||||
- Add version picker in the navbar. ([#2256](https://github.com/matrix-org/matrix-spec/issues/2256), [#2258](https://github.com/matrix-org/matrix-spec/issues/2258), [#2259](https://github.com/matrix-org/matrix-spec/issues/2259), [#2260](https://github.com/matrix-org/matrix-spec/issues/2260), [#2261](https://github.com/matrix-org/matrix-spec/issues/2261), [#2264](https://github.com/matrix-org/matrix-spec/issues/2264), [#2268](https://github.com/matrix-org/matrix-spec/issues/2268))
|
||||
- Add a list of endpoints to the top of each spec page. ([#2262](https://github.com/matrix-org/matrix-spec/issues/2262))
|
||||
|
|
@ -1,127 +0,0 @@
|
|||
---
|
||||
title: v1.18 Changelog
|
||||
linkTitle: v1.18
|
||||
type: docs
|
||||
layout: changelog
|
||||
outputs:
|
||||
- html
|
||||
- checklist
|
||||
date: 2026-03-25
|
||||
---
|
||||
|
||||
## Client-Server API
|
||||
|
||||
**New Endpoints**
|
||||
|
||||
- Add `GET /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
|
||||
- Add `PUT /_matrix/client/v1/admin/suspend/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
|
||||
- Add `GET /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
|
||||
- Add `PUT /_matrix/client/v1/admin/lock/{userId}`, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- The `score` request parameter on `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` was removed as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277). ([#2311](https://github.com/matrix-org/matrix-spec/issues/2311))
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Add the account management capabilities for the OAuth 2.0 authentication API, as per [MSC4191](https://github.com/matrix-org/matrix-spec-proposals/pull/4191). ([#2270](https://github.com/matrix-org/matrix-spec/issues/2270))
|
||||
- Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824). ([#2272](https://github.com/matrix-org/matrix-spec/issues/2272))
|
||||
- Add administrator endpoints to lock and suspend server-local users and add the `m.account_management` capability, as per [MSC4323](https://github.com/matrix-org/matrix-spec-proposals/pull/4323). ([#2278](https://github.com/matrix-org/matrix-spec/issues/2278))
|
||||
- Add `m.recent_emoji` account data event to track recently used emoji as per [MSC4356](https://github.com/matrix-org/matrix-spec-proposals/pull/4356). ([#2291](https://github.com/matrix-org/matrix-spec/issues/2291))
|
||||
- Add `m.forget_forced_upon_leave` capability for servers to transparently auto-forget rooms that the user leaves as per [MSC4267](https://github.com/matrix-org/matrix-spec-proposals/pull/4267). ([#2292](https://github.com/matrix-org/matrix-spec/issues/2292))
|
||||
- Add support for `m.room.redaction` events at the `PUT /rooms/{roomId}/send/{eventType}/{txnId}` endpoint, as per [MSC4169](https://github.com/matrix-org/matrix-spec-proposals/pull/4169). ([#2298](https://github.com/matrix-org/matrix-spec/issues/2298))
|
||||
- Clients supporting the `ol` HTML element must also support the `start` attribute, as per [MSC4313](https://github.com/matrix-org/matrix-spec-proposals/pull/4313). ([#2299](https://github.com/matrix-org/matrix-spec/issues/2299))
|
||||
- Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153). ([#2301](https://github.com/matrix-org/matrix-spec/issues/2301))
|
||||
- Add invite blocking, as per [MSC4380](https://github.com/matrix-org/matrix-spec-proposals/pull/4380). ([#2305](https://github.com/matrix-org/matrix-spec/issues/2305))
|
||||
- `/_matrix/client/v3/rooms/{roomId}/report` and `/_matrix/client/v3/rooms/{roomId}/report/{eventId}` may respond with HTTP 200 regardless of the reported subject's existence or add a random delay when generating responses as per [MSC4277](https://github.com/matrix-org/matrix-spec-proposals/pull/4277). ([#2311](https://github.com/matrix-org/matrix-spec/issues/2311))
|
||||
- Add `M_USER_LIMIT_EXCEEDED` common error code, as per [MSC4335](https://github.com/matrix-org/matrix-spec-proposals/pull/4335). ([#2315](https://github.com/matrix-org/matrix-spec/issues/2315))
|
||||
- Add the OAuth 2.0 Device Authorization Grant (RFC 8628) as a supported grant type, as per [MSC4341](https://github.com/matrix-org/matrix-spec-proposals/pull/4341). ([#2320](https://github.com/matrix-org/matrix-spec/issues/2320))
|
||||
- Add the `is_animated` flag to the `info` object of the `m.image` msgtype and the `m.sticker` event, as per [MSC4230](https://github.com/matrix-org/matrix-spec-proposals/pull/4230). ([#2328](https://github.com/matrix-org/matrix-spec/issues/2328), [#2338](https://github.com/matrix-org/matrix-spec/issues/2338))
|
||||
- Add a "Policy Servers" module, as per [MSC4284](https://github.com/matrix-org/matrix-spec-proposals/pull/4284). ([#2332](https://github.com/matrix-org/matrix-spec/issues/2332))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- The optional `submit_url` response parameter of the `/requestToken` endpoints uses the same request and response parameters and error codes as the Identity Service API's `POST /_matrix/identity/v2/validate/email/submitToken`, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183). ([#2277](https://github.com/matrix-org/matrix-spec/issues/2277))
|
||||
- Update non-historic mentions of matrix-doc repo to matrix-spec/-proposals. Contributed by @HarHarLinks. ([#2280](https://github.com/matrix-org/matrix-spec/issues/2280))
|
||||
- Remove unintended TeX formatting. Contributed by @HarHarLinks. ([#2283](https://github.com/matrix-org/matrix-spec/issues/2283))
|
||||
- Clarify the requiredness of `event_id` in `predecessor`. ([#2304](https://github.com/matrix-org/matrix-spec/issues/2304))
|
||||
- Clarify terminology for keys in cross-signing module. ([#2306](https://github.com/matrix-org/matrix-spec/issues/2306))
|
||||
- Add 404 responses to the OpenAPI of `GET /login` and `GET /auth_metadata` endpoints. The responses were already defined in text but not written in OpenAPI. ([#2316](https://github.com/matrix-org/matrix-spec/issues/2316))
|
||||
- Fix various typos throughout the specification. Contributed by @HarHarLinks. ([#2318](https://github.com/matrix-org/matrix-spec/issues/2318))
|
||||
- Clarified attachment encryption to require secure generation of keys and hash verification. ([#2324](https://github.com/matrix-org/matrix-spec/issues/2324))
|
||||
- Order the common and other error codes alphabetically and remove duplicate `M_THREEPID_IN_USE` definition. ([#2336](https://github.com/matrix-org/matrix-spec/issues/2336))
|
||||
- Fix various typos throughout the specification. ([#2337](https://github.com/matrix-org/matrix-spec/issues/2337))
|
||||
|
||||
|
||||
## Server-Server API
|
||||
|
||||
**Removed Endpoints**
|
||||
|
||||
- Remove `/v1/send_join` and `/v1/send_leave`, as per [MSC4376](https://github.com/matrix-org/matrix-spec-proposals/pull/4376). ([#2319](https://github.com/matrix-org/matrix-spec/issues/2319))
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Add a concept of "Policy Servers", as per [MSC4284](https://github.com/matrix-org/matrix-spec-proposals/pull/4284). ([#2332](https://github.com/matrix-org/matrix-spec/issues/2332))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify what the `minimum_valid_until_ts` field means when it is set in key queries. ([#2191](https://github.com/matrix-org/matrix-spec/issues/2191))
|
||||
- Specify validation for PDUs passed to and returned from federation membership endpoints. ([#2284](https://github.com/matrix-org/matrix-spec/issues/2284))
|
||||
- Specify that callers of `/_matrix/federation/v1/openid/userinfo` must validate the returned user ID. ([#2288](https://github.com/matrix-org/matrix-spec/issues/2288))
|
||||
- Change `m.signing_update` typo to `m.signing_key_update`. Contributed by @velikopter ([#2300](https://github.com/matrix-org/matrix-spec/issues/2300))
|
||||
- Add link to JSON signing algorithm in server-server auth section for clarity. Contributed by @thetayloredman. ([#2329](https://github.com/matrix-org/matrix-spec/issues/2329))
|
||||
- Fix various typos throughout the specification. ([#2338](https://github.com/matrix-org/matrix-spec/issues/2338))
|
||||
|
||||
|
||||
## Application Service API
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Fix various typos throughout the specification. ([#2330](https://github.com/matrix-org/matrix-spec/issues/2330))
|
||||
|
||||
|
||||
## Identity Service API
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify the error codes that can be returned with a 400 HTTP status code by the `POST /_matrix/identity/v2/validate/email/submitToken` and `POST /_matrix/identity/v2/validate/msisdn/submitToken` endpoints, introducing the `M_TOKEN_INCORRECT` error code, as per [MSC4183](https://github.com/matrix-org/matrix-spec-proposals/pull/4183). ([#2277](https://github.com/matrix-org/matrix-spec/issues/2277))
|
||||
- Order the standard error codes alphabetically. ([#2336](https://github.com/matrix-org/matrix-spec/issues/2336))
|
||||
|
||||
|
||||
## Push Gateway API
|
||||
|
||||
No significant changes.
|
||||
|
||||
|
||||
## Room Versions
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify meaning of floating-point powerlevels. ([#2297](https://github.com/matrix-org/matrix-spec/issues/2297))
|
||||
- Remove the post-1.16 release note for room version 12. ([#2303](https://github.com/matrix-org/matrix-spec/issues/2303))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Add identifier pronunciation guidelines. Contributed by @HarHarLinks. ([#2307](https://github.com/matrix-org/matrix-spec/issues/2307))
|
||||
|
||||
|
||||
## Internal Changes/Tooling
|
||||
|
||||
**Backwards Compatible Changes**
|
||||
|
||||
- Include the spec release version in the filenames in the tarballs generated by CI. ([#2276](https://github.com/matrix-org/matrix-spec/issues/2276))
|
||||
|
||||
**Spec Clarifications**
|
||||
|
||||
- Clarify vendor prefixing requirements. ([#2222](https://github.com/matrix-org/matrix-spec/issues/2222))
|
||||
- Auto-create draft releases when building release tags. ([#2275](https://github.com/matrix-org/matrix-spec/issues/2275))
|
||||
- Replace the Twitter link in the footer with our BlueSky and Mastodon socials. ([#2282](https://github.com/matrix-org/matrix-spec/issues/2282))
|
||||
- Upgrade to docsy v0.13.0. ([#2287](https://github.com/matrix-org/matrix-spec/issues/2287))
|
||||
- Updates to the release documentation. ([#2289](https://github.com/matrix-org/matrix-spec/issues/2289))
|
||||
- Remove unused leftover CSS files. ([#2290](https://github.com/matrix-org/matrix-spec/issues/2290))
|
||||
- Update the footer social links to match matrix.org. Contributed by @HarHarLinks. ([#2317](https://github.com/matrix-org/matrix-spec/issues/2317))
|
||||
- Fix various typos throughout the specification. Contributed by @HarHarLinks. ([#2318](https://github.com/matrix-org/matrix-spec/issues/2318))
|
||||
- Render error code sections as definition lists to improve readability. ([#2323](https://github.com/matrix-org/matrix-spec/issues/2323))
|
||||
|
|
@ -108,12 +108,12 @@ No significant changes.
|
|||
|
||||
|
||||
- Improve readability and understanding of the state resolution algorithms. ([#1037](https://github.com/matrix-org/matrix-spec/issues/1037), [#1042](https://github.com/matrix-org/matrix-spec/issues/1042), [#1043](https://github.com/matrix-org/matrix-spec/issues/1043), [#1120](https://github.com/matrix-org/matrix-spec/issues/1120))
|
||||
- Improve readability of the authorisation rules. ([#1050](https://github.com/matrix-org/matrix-spec/issues/1050))
|
||||
- Improve readability of the authorization rules. ([#1050](https://github.com/matrix-org/matrix-spec/issues/1050))
|
||||
- For room versions 8, 9, and 10: clarify which homeserver is required to sign the join event. ([#1093](https://github.com/matrix-org/matrix-spec/issues/1093))
|
||||
- Clarify that room versions 1 through 9 accept stringy power levels, as noted by [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667). ([#1099](https://github.com/matrix-org/matrix-spec/issues/1099))
|
||||
- For all room versions: Add `m.federate` to the authorisation rules, as originally intended. ([#1103](https://github.com/matrix-org/matrix-spec/issues/1103))
|
||||
- For all room versions: Add `m.federate` to the authorization rules, as originally intended. ([#1103](https://github.com/matrix-org/matrix-spec/issues/1103))
|
||||
- For room versions 2 through 10: More explicitly define the mainline of a power event and the mainline ordering of other events. ([#1107](https://github.com/matrix-org/matrix-spec/issues/1107))
|
||||
- For room versions 7, 8, 9, and 10: fix join membership authorisation rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
|
||||
- For room versions 7, 8, 9, and 10: fix join membership authorization rules when `join_rule` is `knock`. ([#3737](https://github.com/matrix-org/matrix-spec-proposals/issues/3737))
|
||||
|
||||
|
||||
## Appendices
|
||||
|
|
|
|||
|
|
@ -73,7 +73,7 @@ date: 2022-09-29
|
|||
<strong>Breaking Changes</strong>
|
||||
|
||||
|
||||
- Replace homeserver authorisation approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). ([#1200](https://github.com/matrix-org/matrix-spec/issues/1200))
|
||||
- Replace homeserver authorization approach with an `Authorization` header instead of `access_token` when talking to the application service, as per [MSC2832](https://github.com/matrix-org/matrix-spec-proposals/pull/2832). ([#1200](https://github.com/matrix-org/matrix-spec/issues/1200))
|
||||
|
||||
|
||||
<strong>Spec Clarifications</strong>
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -33,7 +33,7 @@ specification.
|
|||
Content locations are represented as Matrix Content (`mxc://`) URIs. They
|
||||
look like:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
mxc://<server-name>/<media-id>
|
||||
|
||||
<server-name> : The name of the homeserver where this content originated, e.g. matrix.org
|
||||
|
|
@ -87,7 +87,7 @@ Matrix 1.12 is expected to be released in the July-September 2024 calendar quart
|
|||
The homeserver SHOULD be able to supply thumbnails for uploaded images
|
||||
and videos. The exact file types which can be thumbnailed are not
|
||||
currently specified - see [Issue
|
||||
\#1938](https://github.com/matrix-org/matrix-spec/issues/453) for more
|
||||
\#1938](https://github.com/matrix-org/matrix-doc/issues/1938) for more
|
||||
information.
|
||||
|
||||
The thumbnail methods are "crop" and "scale". "scale" tries to return an
|
||||
|
|
@ -134,14 +134,9 @@ entity isn't in the room.
|
|||
`mxc://` URIs are vulnerable to directory traversal attacks such as
|
||||
`mxc://127.0.0.1/../../../some_service/etc/passwd`. This would cause the
|
||||
target homeserver to try to access and return this file. As such,
|
||||
homeservers MUST sanitise `mxc://` URIs by:
|
||||
|
||||
- restricting the `server-name` segment to valid
|
||||
[server names](/appendices/#server-name)
|
||||
- allowing only alphanumeric (`A-Za-z0-9`), `_` and `-` characters in
|
||||
the `media-id` segment
|
||||
|
||||
The resulting set of whitelisted characters allows URL-safe
|
||||
homeservers MUST sanitise `mxc://` URIs by allowing only alphanumeric
|
||||
(`A-Za-z0-9`), `_` and `-` characters in the `server-name` and
|
||||
`media-id` values. This set of whitelisted characters allows URL-safe
|
||||
base64 encodings specified in RFC 4648. Applying this character
|
||||
whitelist is preferable to blacklisting `.` and `/` as there are
|
||||
techniques around blacklisted characters (percent-encoded characters,
|
||||
|
|
|
|||
|
|
@ -5,91 +5,6 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be
|
|||
created whose conversation contents are not decryptable or interceptable
|
||||
on any of the participating homeservers.
|
||||
|
||||
#### Recommended client behaviour
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
While clients are able to choose what encryption features they implement based
|
||||
on their threat model, this section recommends behaviours that will improve the
|
||||
overall user experience and security of encrypted conversations.
|
||||
|
||||
While a user may be unable to [verify](#device-verification) every other user
|
||||
that they communicate with, or may be unaware of the need to verify other users,
|
||||
[cross-signing](#cross-signing) gives some measure of protection and so SHOULD
|
||||
be used where possible. In particular, clients SHOULD implement the following
|
||||
recommendations.
|
||||
|
||||
* Clients SHOULD create new [cross-signing keys](#cross-signing) for users who
|
||||
do not yet have cross-signing keys.
|
||||
* Clients SHOULD encourage users to set up their [Secret Storage](#storage) to
|
||||
avoid needing to reset their cryptographic identity in case the user does not
|
||||
have an existing device that can [share the secrets](#sharing) with the new
|
||||
device. The user's Secret Storage SHOULD contain the user's cross-signing
|
||||
private keys and the [key backup](#server-side-key-backups) decryption key
|
||||
(if the user is using key backup). The user's Secret Storage SHOULD have a
|
||||
[default key](#key-storage) (a key referred to by
|
||||
`m.secret_storage.default_key`) that encrypts the private cross-signing keys
|
||||
and key backup decryption key (if available).
|
||||
* Clients SHOULD encourage users to [cross-sign](#cross-signing) their devices.
|
||||
This includes both when logging in a new device, and for existing devices.
|
||||
Clients MAY even go so far as to require cross-signing of devices by
|
||||
preventing the user from using the client until the device is cross-signed.
|
||||
If the user cannot cross-sign their device (for example, if they have
|
||||
forgotten their Secret Storage key), the client can allow users to reset their
|
||||
[Secret Storage](#storage), cross-signing keys, and [key backup](#server-side-key-backups).
|
||||
* When Alice [verifies](#device-verification) Bob, the verification SHOULD
|
||||
verify their [cross-signing keys](#cross-signing). Any flow between different
|
||||
users that does not verify the users' cross-signing keys (it verifies only the
|
||||
device keys) is deprecated.
|
||||
* Clients SHOULD flag when [cross-signing keys](#cross-signing) change. If
|
||||
Alice's cross-signing keys change, Alice's own devices MUST alert her to this
|
||||
fact, and prompt her to re-cross-sign those devices. If Bob is in an
|
||||
encrypted room with Alice, Bob's devices SHOULD inform him of Alice's key
|
||||
change and SHOULD prevent him from sending an encrypted message to Alice
|
||||
without acknowledging the change. Bob's clients may behave differently
|
||||
depending on whether Bob had previously [verified](#device-verification)
|
||||
Alice or not. For example, if Bob had previously verified Alice, and Alice's
|
||||
keys change, Bob's client may require Bob to re-verify, or may display a more
|
||||
aggressive warning.
|
||||
* Clients SHOULD NOT send encrypted [to-device](#send-to-device-messaging)
|
||||
messages, such as [room keys](#sharing-keys-between-devices) or [secrets](#secrets)
|
||||
(via [Secret Sharing](#sharing)), to [non-cross-signed](#cross-signing)
|
||||
devices by default. Non-cross-signed devices don't provide any assurance that
|
||||
the device belongs to the user, and server admins can trivially create new
|
||||
devices for users. When sending room keys, clients can use a
|
||||
[`m.room_key.withheld`](#mroom_keywithheld) message with a code of
|
||||
`m.unverified` to indicate to the non-cross-signed device why it is not
|
||||
receiving the room key.
|
||||
|
||||
Note that clients cannot selectively send room events only to cross-signed
|
||||
devices. The only way to exclude non-cross-signed devices from encrypted
|
||||
conversations is to not send the room keys so those devices won't be able to
|
||||
decrypt the messages.
|
||||
* Similarly, messages sent from [non-cross-signed](#cross-signing) devices
|
||||
cannot be trusted and SHOULD NOT be displayed to the user. Clients have no
|
||||
assurance that encrypted messages sent from non-cross-signed devices were sent
|
||||
by the user, rather than an impersonator.
|
||||
* Matrix clients MUST NOT consider non-cryptographic devices (devices which do
|
||||
not have [device identity keys](#device-keys) uploaded to the homeserver) to
|
||||
be equivalent to [non-cross-signed](#cross-signing) cryptographic devices for
|
||||
purposes of enforcing E2EE policy. For example, clients SHOULD NOT warn nor
|
||||
refuse to send messages due to the presence of non-cryptographic devices. For
|
||||
all intents and purposes, non-cryptographic devices are a completely separate
|
||||
concept and do not exist from the perspective of the cryptography layer since
|
||||
they do not have identity keys, so it is impossible to send them decryption
|
||||
keys.
|
||||
* Clients MAY make provisions for encrypted bridges. Some bridges are structured
|
||||
in a way such that only one user controlled by the bridge (often called the
|
||||
bridge bot) participates in encryption, and encrypted messages from other
|
||||
bridge users are encrypted by the bridge bot. Thus encrypted messages sent by
|
||||
one user could be encrypted by a [Megolm](#mmegolmv1aes-sha2) session sent by
|
||||
a different user. Clients MAY accept such messages, provided the session
|
||||
creator's device is [cross-signed](#cross-signing). However, the client MUST
|
||||
annotate the message with a warning, unless the client has a way to check that
|
||||
the bridge bot is permitted to encrypt messages on behalf of the user. Future
|
||||
MSCs such as [MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
|
||||
may provide a secure way to allow such impersonation.
|
||||
|
||||
#### Key Distribution
|
||||
|
||||
Encryption and Authentication in Matrix is based around public-key
|
||||
|
|
@ -103,7 +18,7 @@ exchange fingerprints between users to build a web of trust.
|
|||
device. This may include long-term identity keys, and/or one-time
|
||||
keys.
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+----------+ +--------------+
|
||||
| Bob's HS | | Bob's Device |
|
||||
+----------+ +--------------+
|
||||
|
|
@ -114,7 +29,7 @@ keys.
|
|||
|
||||
2) Alice requests Bob's public identity keys and supported algorithms.
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+----------------+ +------------+ +----------+
|
||||
| Alice's Device | | Alice's HS | | Bob's HS |
|
||||
+----------------+ +------------+ +----------+
|
||||
|
|
@ -125,7 +40,7 @@ keys.
|
|||
|
||||
3) Alice selects an algorithm and claims any one-time keys needed.
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+----------------+ +------------+ +----------+
|
||||
| Alice's Device | | Alice's HS | | Bob's HS |
|
||||
+----------------+ +------------+ +----------+
|
||||
|
|
@ -178,7 +93,7 @@ Example:
|
|||
```
|
||||
|
||||
`ed25519` and `curve25519` keys are used for [device keys](#device-keys).
|
||||
Additionally, `ed25519` keys are used for [cross-signing](#cross-signing).
|
||||
Additionally, `ed25519` keys are used for [cross-signing keys](#cross-signing).
|
||||
|
||||
`signed_curve25519` keys are used for [one-time and fallback keys](#one-time-and-fallback-keys).
|
||||
|
||||
|
|
@ -350,14 +265,11 @@ field, and as a result should remove her from its list of tracked users.
|
|||
When encryption is enabled in a room, files should be uploaded encrypted
|
||||
on the homeserver.
|
||||
|
||||
In order to achieve this, the client generates a single-use 256-bit AES
|
||||
key, and encrypts the file using AES-CTR. The counter is 64 bits long,
|
||||
starting at 0 and prefixed by a random 64-bit Initialization Vector (IV),
|
||||
which together form a 128-bit unique counter block.
|
||||
|
||||
Clients MUST generate both the AES key and IV using a cryptographically
|
||||
secure random source and MUST NOT use the same key or IV multiple
|
||||
times. The latter 64 bits of the 128-bit counter block MUST start at zero.
|
||||
In order to achieve this, a client should generate a single-use 256-bit
|
||||
AES key, and encrypt the file using AES-CTR. The counter should be
|
||||
64-bit long, starting at 0 and prefixed by a random 64-bit
|
||||
Initialization Vector (IV), which together form a 128-bit unique counter
|
||||
block.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
An IV must never be used multiple times with the same key. This implies
|
||||
|
|
@ -367,14 +279,13 @@ same key and IV.
|
|||
{{% /boxes/warning %}}
|
||||
|
||||
Then, the encrypted file can be uploaded to the homeserver. The key and
|
||||
the IV are included in the room event along with the resulting `mxc://`
|
||||
in order to allow recipients to decrypt the file. As the event
|
||||
the IV must be included in the room event along with the resulting
|
||||
`mxc://` in order to allow recipients to decrypt the file. As the event
|
||||
containing those will be Megolm encrypted, the server will never have
|
||||
access to the decrypted file.
|
||||
|
||||
A hash of the ciphertext MUST also be included, in order to prevent the
|
||||
homeserver from changing the file content. Clients MUST verify the hash
|
||||
before using the file contents.
|
||||
A hash of the ciphertext must also be included, in order to prevent the
|
||||
homeserver from changing the file content.
|
||||
|
||||
A client should send the data as an encrypted `m.room.message` event,
|
||||
using either `m.file` as the msgtype, or the appropriate msgtype for the
|
||||
|
|
@ -396,7 +307,7 @@ properties.
|
|||
| url | string | **Required.** The URL to the file. |
|
||||
| key | JWK | **Required.** A [JSON Web Key](https://tools.ietf.org/html/rfc7517#appendix-A.3) object. |
|
||||
| iv | string | **Required.** The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64. |
|
||||
| hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients MUST support the SHA-256 hash, which uses the key `sha256`. |
|
||||
| hashes | {string: string} | **Required.** A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key `sha256`. |
|
||||
| v | string | **Required.** Version of the encrypted attachment's protocol. Must be `v2`. |
|
||||
|
||||
`JWK`
|
||||
|
|
@ -580,7 +491,7 @@ this example, Bob's device sends the `m.key.verification.start`, Alice's device
|
|||
could also send that message. As well, the order of the
|
||||
`m.key.verification.done` messages could be reversed.
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+---------------+ +---------------+ +-------------+ +-------------+
|
||||
| AliceDevice1 | | AliceDevice2 | | BobDevice1 | | BobDevice2 |
|
||||
+---------------+ +---------------+ +-------------+ +-------------+
|
||||
|
|
@ -637,7 +548,7 @@ request.
|
|||
|
||||
The prompt for Bob to accept/reject Alice's request (or the unsupported method
|
||||
prompt) should be automatically dismissed 10 minutes after the `timestamp` (in
|
||||
the case of to-device messages) or `origin_server_ts` (in the case of in-room
|
||||
the case of to-device messages) or `origin_ts` (in the case of in-room
|
||||
messages) field or 2 minutes after Bob's client receives the message, whichever
|
||||
comes first, if Bob does not interact with the prompt. The prompt should
|
||||
additionally be hidden if an appropriate `m.key.verification.cancel` message is
|
||||
|
|
@ -763,11 +674,8 @@ The process between Alice and Bob verifying each other would be:
|
|||
their devices if they match or not.
|
||||
15. Assuming they match, Alice and Bob's devices each calculate Message
|
||||
Authentication Codes (MACs) for:
|
||||
* {{% changed-in v="1.18" %}} Each of the keys that they wish the other user
|
||||
to verify (usually their device ed25519 key and their master signing key,
|
||||
see below). The master signing key SHOULD be included when two different
|
||||
users are verifying each other. Verifying individual devices of other
|
||||
users is deprecated.
|
||||
* Each of the keys that they wish the other user to verify (usually their
|
||||
device ed25519 key and their master cross-signing key).
|
||||
* The complete list of key IDs that they wish the other user to verify.
|
||||
|
||||
The MAC calculation is defined [below](#mac-calculation).
|
||||
|
|
@ -787,7 +695,7 @@ The process between Alice and Bob verifying each other would be:
|
|||
The wire protocol looks like the following between Alice and Bob's
|
||||
devices:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+-------------+ +-----------+
|
||||
| AliceDevice | | BobDevice |
|
||||
+-------------+ +-----------+
|
||||
|
|
@ -1013,7 +921,7 @@ collaborate to create a common set of translations for all languages.
|
|||
|
||||
{{% boxes/note %}}
|
||||
Known translations for the emoji are available from
|
||||
<https://github.com/matrix-org/matrix-spec/tree/main/data-definitions/>
|
||||
<https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/>
|
||||
and can be translated online:
|
||||
<https://translate.riot.im/projects/matrix-doc/sas-emoji-v1>
|
||||
{{% /boxes/note %}}
|
||||
|
|
@ -1023,47 +931,45 @@ and can be translated online:
|
|||
Rather than requiring Alice to verify each of Bob's devices with each of
|
||||
her own devices and vice versa, the cross-signing feature allows users
|
||||
to sign their device keys such that Alice and Bob only need to verify
|
||||
once. With cross-signing, each user has a set of cross-signing key pairs that
|
||||
once. With cross-signing, each user has a set of cross-signing keys that
|
||||
are used to sign their own device keys and other users' keys, and can be
|
||||
used to trust device keys that were not verified directly.
|
||||
|
||||
Each user has three ed25519 key pairs used for cross-signing (cross-signing keys):
|
||||
Each user has three ed25519 key pairs for cross-signing:
|
||||
|
||||
- a master signing key (MSK, for historical reasons sometimes known as
|
||||
`master_key`) that serves as the user's identity in cross-signing and signs
|
||||
their user-signing and self-signing keys;
|
||||
- a master key (MSK) that serves as the user's identity in
|
||||
cross-signing and signs their other cross-signing keys;
|
||||
- a user-signing key (USK) -- only visible to the user that it belongs
|
||||
to -- that signs other users' master signing keys; and
|
||||
to --that signs other users' master keys; and
|
||||
- a self-signing key (SSK) that signs the user's own device keys.
|
||||
|
||||
The master signing key may also be used to sign other items such as the backup
|
||||
key. The master signing key may also be signed by the user's own device keys to
|
||||
The master key may also be used to sign other items such as the backup
|
||||
key. The master key may also be signed by the user's own device keys to
|
||||
aid in migrating from device verifications: if Alice's device had
|
||||
previously verified Bob's device and Bob's device has signed his master
|
||||
key, then Alice's device can trust Bob's master signing key, and she can sign it
|
||||
key, then Alice's device can trust Bob's master key, and she can sign it
|
||||
with her user-signing key.
|
||||
|
||||
Users upload the public parts of their master signing, user-signing and
|
||||
self-signing keys to the server using [POST
|
||||
Users upload their cross-signing keys to the server using [POST
|
||||
/\_matrix/client/v3/keys/device\_signing/upload](/client-server-api/#post_matrixclientv3keysdevice_signingupload). When Alice uploads
|
||||
new keys, her user ID will appear in the `changed`
|
||||
new cross-signing keys, her user ID will appear in the `changed`
|
||||
property of the `device_lists` field of the `/sync` of response of all
|
||||
users who share an encrypted room with her. When Bob sees Alice's user
|
||||
ID in his `/sync`, he will call [POST /\_matrix/client/v3/keys/query](/client-server-api/#post_matrixclientv3keysquery)
|
||||
to retrieve Alice's device keys, as well as their cross-signing keys.
|
||||
to retrieve Alice's device and cross-signing keys.
|
||||
|
||||
If Alice has a device and wishes to send an encrypted message to Bob,
|
||||
she can trust Bob's device if:
|
||||
|
||||
- Alice's device is using a master signing key that has signed her
|
||||
- Alice's device is using a master key that has signed her
|
||||
user-signing key,
|
||||
- Alice's user-signing key has signed Bob's master signing key,
|
||||
- Bob's master signing key has signed Bob's self-signing key, and
|
||||
- Alice's user-signing key has signed Bob's master key,
|
||||
- Bob's master key has signed Bob's self-signing key, and
|
||||
- Bob's self-signing key has signed Bob's device key.
|
||||
|
||||
The following diagram illustrates how keys are signed:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+------------------+ .................. +----------------+
|
||||
| +--------------+ | .................. : | +------------+ |
|
||||
| | v v v : : v v v | |
|
||||
|
|
@ -1094,7 +1000,7 @@ the user who created them.
|
|||
The following diagram illustrates Alice's view, hiding the keys and
|
||||
signatures that she cannot see:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+------------------+ +----------------+ +----------------+
|
||||
| +--------------+ | | | | +------------+ |
|
||||
| | v v | v v v | |
|
||||
|
|
@ -1118,28 +1024,27 @@ signatures that she cannot see:
|
|||
```
|
||||
|
||||
[Verification methods](#device-verification) can be used to verify a
|
||||
user's master signing key by treating its public key (master signing public
|
||||
key), encoded using unpadded base64, as the device ID, and treating it as a
|
||||
normal device. For example, if Alice and Bob verify each other using SAS,
|
||||
Alice's
|
||||
user's master key by using the master public key, encoded using unpadded
|
||||
base64, as the device ID, and treating it as a normal device. For
|
||||
example, if Alice and Bob verify each other using SAS, Alice's
|
||||
`m.key.verification.mac` message to Bob may include
|
||||
`"ed25519:alices+master+public+key": "alices+master+public+key"` in the
|
||||
`mac` property. Servers therefore must ensure that device IDs will not
|
||||
collide with cross-signing public keys.
|
||||
|
||||
Using the [Secrets](#secrets) module the private parts of the cross-signing keys can
|
||||
be stored on the server or shared with other devices. When doing so, the
|
||||
master signing, user-signing, and self-signing keys are identified using the
|
||||
names `m.cross_signing.master`, `m.cross_signing.user_signing`, and
|
||||
The cross-signing private keys can be stored on the server or shared with other
|
||||
devices using the [Secrets](#secrets) module. When doing so, the master,
|
||||
user-signing, and self-signing keys are identified using the names
|
||||
`m.cross_signing.master`, `m.cross_signing.user_signing`, and
|
||||
`m.cross_signing.self_signing`, respectively, and the keys are base64-encoded
|
||||
before being encrypted.
|
||||
|
||||
###### Key and signature security
|
||||
|
||||
A user's master signing key could allow an attacker to impersonate that user to
|
||||
A user's master key could allow an attacker to impersonate that user to
|
||||
other users, or other users to that user. Thus clients must ensure that
|
||||
the private part of the master signing key is treated securely. If clients do
|
||||
not have a secure means of storing the master signing key (such as a secret
|
||||
the private part of the master key is treated securely. If clients do
|
||||
not have a secure means of storing the master key (such as a secret
|
||||
storage system provided by the operating system), then clients must not
|
||||
store the private part.
|
||||
|
||||
|
|
@ -1152,9 +1057,9 @@ Since device key IDs (`ed25519:DEVICE_ID`) and cross-signing key IDs
|
|||
use the correct keys when verifying.
|
||||
|
||||
While servers MUST not allow devices to have the same IDs as cross-signing
|
||||
keys, a malicious server could construct such a situation, so clients
|
||||
must not rely on the server being well-behaved and should take the following
|
||||
precautions against this:
|
||||
keys, a malicious server could construct such a situation, so clients must not
|
||||
rely on the server being well-behaved and should take the following precautions
|
||||
against this.
|
||||
|
||||
1. Clients MUST refer to keys by their public keys during the verification
|
||||
process, rather than only by the key ID.
|
||||
|
|
@ -1162,32 +1067,31 @@ precautions against this:
|
|||
verification process, and ensure that they do not change in the course of
|
||||
verification.
|
||||
3. Clients SHOULD also display a warning and MUST refuse to verify a user when
|
||||
they detect that the user has a device with the same ID as a cross-signing
|
||||
key.
|
||||
they detect that the user has a device with the same ID as a cross-signing key.
|
||||
|
||||
A user's user-signing and self-signing keys are intended to be easily
|
||||
replaceable if they are compromised by re-issuing a new key signed by
|
||||
the user's master signing key and possibly by re-verifying devices or users.
|
||||
the user's master key and possibly by re-verifying devices or users.
|
||||
However, doing so relies on the user being able to notice when their
|
||||
keys have been compromised, and it involves extra work for the user, and
|
||||
so although clients do not have to treat the private parts as
|
||||
sensitively as the master signing key, clients should still make efforts to
|
||||
sensitively as the master key, clients should still make efforts to
|
||||
store the private part securely, or not store it at all. Clients will
|
||||
need to balance the security of the keys with the usability of signing
|
||||
users and devices when performing key verification.
|
||||
|
||||
To avoid leaking of social graphs, servers will only allow users to see:
|
||||
|
||||
- signatures made by the user's own master signing, self-signing or
|
||||
- signatures made by the user's own master, self-signing or
|
||||
user-signing keys,
|
||||
- signatures made by the user's own devices about their own master
|
||||
key,
|
||||
- signatures made by other users' self-signing keys about their
|
||||
respective devices,
|
||||
- signatures made by other users' master signing keys about their respective
|
||||
- signatures made by other users' master keys about their respective
|
||||
self-signing key, or
|
||||
- signatures made by other users' devices about their respective
|
||||
master signing keys.
|
||||
master keys.
|
||||
|
||||
Users will not be able to see signatures made by other users'
|
||||
user-signing keys.
|
||||
|
|
@ -1289,24 +1193,24 @@ The binary segment MUST be of the following form:
|
|||
- one byte indicating the QR code verification mode. Should be one of the
|
||||
following values:
|
||||
- `0x00` verifying another user with cross-signing
|
||||
- `0x01` self-verifying in which the current device does trust the master signing key
|
||||
- `0x01` self-verifying in which the current device does trust the master key
|
||||
- `0x02` self-verifying in which the current device does not yet trust the
|
||||
master signing key
|
||||
master key
|
||||
- the event ID or `transaction_id` of the associated verification
|
||||
request event, encoded as:
|
||||
- two bytes in network byte order (big-endian) indicating the length in
|
||||
bytes of the ID as a UTF-8 string
|
||||
- the ID encoded as a UTF-8 string
|
||||
- the first key, as 32 bytes. The key to use depends on the mode field:
|
||||
- if `0x00` or `0x01`, then the current user's own master signing public key
|
||||
- if `0x00` or `0x01`, then the current user's own master cross-signing public key
|
||||
- if `0x02`, then the current device's Ed25519 signing key
|
||||
- the second key, as 32 bytes. The key to use depends on the mode field:
|
||||
- if `0x00`, then what the device thinks the other user's master
|
||||
public key is
|
||||
cross-signing public key is
|
||||
- if `0x01`, then what the device thinks the other device's Ed25519 signing
|
||||
public key is
|
||||
- if `0x02`, then what the device thinks the user's master signing public key
|
||||
is
|
||||
- if `0x02`, then what the device thinks the user's master cross-signing public
|
||||
key is
|
||||
- a random shared secret, as a sequence of bytes. It is suggested to use a secret
|
||||
that is about 8 bytes long. Note: as we do not share the length of the
|
||||
secret, and it is not a fixed size, clients will just use the remainder of
|
||||
|
|
@ -1314,17 +1218,17 @@ The binary segment MUST be of the following form:
|
|||
|
||||
For example, if Alice displays a QR code encoding the following binary data:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
"MATRIX" |ver|mode| len | event ID
|
||||
4D 41 54 52 49 58 02 00 00 2D 21 41 42 43 44 ...
|
||||
| the first key | the second key | shared secret
|
||||
| user's cross-signing key | other user's cross-signing key | shared secret
|
||||
00 01 02 03 04 05 06 07 ... 10 11 12 13 14 15 16 17 ... 20 21 22 23 24 25 26 27
|
||||
```
|
||||
|
||||
Mode `0x00` indicates that Alice is verifying another user (say Bob), in
|
||||
response to the request from event "$ABCD...", her master signing key is
|
||||
this indicates that Alice is verifying another user (say Bob), in response to
|
||||
the request from event "$ABCD...", her cross-signing key is
|
||||
`0001020304050607...` (which is "AAECAwQFBg..." in base64), she thinks that
|
||||
Bob's master signing key is `1011121314151617...` (which is "EBESExQVFh..." in
|
||||
Bob's cross-signing key is `1011121314151617...` (which is "EBESExQVFh..." in
|
||||
base64), and the shared secret is `2021222324252627` (which is "ICEiIyQlJic" in
|
||||
base64).
|
||||
|
||||
|
|
@ -1396,8 +1300,8 @@ one of its variants.
|
|||
Clients must only store keys in backups after they have ensured that the
|
||||
`auth_data` is trusted. This can be done either by:
|
||||
|
||||
- checking that it is signed by the user's [master signing key](#cross-signing)
|
||||
or by a verified device belonging to the same user, or
|
||||
- checking that it is signed by the user's [master cross-signing
|
||||
key](#cross-signing) or by a verified device belonging to the same user, or
|
||||
- deriving the public key from a private key that it obtained from a trusted
|
||||
source. Trusted sources for the private key include the user entering the
|
||||
key, retrieving the key stored in [secret storage](#secret-storage), or
|
||||
|
|
@ -1479,43 +1383,6 @@ potential new key backup algorithm version that would fix this issue.
|
|||
|
||||
{{% http-api spec="client-server" api="key_backup" %}}
|
||||
|
||||
###### Key backup enabled preference
|
||||
|
||||
{{% added-in v="1.19" %}}
|
||||
|
||||
This enables clients to track a user's preference about enabling or
|
||||
disabling [server-side backups of room keys](#server-side-key-backups). The data
|
||||
is stored in the [`m.key_backup`](#mkey_backup) global
|
||||
[account data](#client-config).
|
||||
|
||||
{{% event event="m.key_backup" %}}
|
||||
|
||||
When a user signs in to a client which supports encryption and key backup:
|
||||
|
||||
* If this event type exists in account data and contains the specified property
|
||||
in the correct format, clients which support key backup MUST take account of
|
||||
its contents in their behaviour. For example, clients may automatically turn
|
||||
on/off key backup based on the property, or prompt the user, using the
|
||||
property value as a default. (Because this property is server-controlled,
|
||||
clients may wish to confirm the user's intention.)
|
||||
|
||||
* If this event type does not exist in account data, or if it does not contain
|
||||
the `enabled` property, or if the value of `enabled` is not a boolean value,
|
||||
clients MUST ignore the existing value and MAY decide whether or not to
|
||||
perform key backup, possibly based on user input.
|
||||
|
||||
If the user turns on key backups, clients MUST set this event type in account
|
||||
data, to `"enabled": true`.
|
||||
|
||||
If the user turns off key backups, clients MUST set this event type in account
|
||||
data, to `"enabled": false`.
|
||||
|
||||
Clients are not required to monitor the `m.key_backup` account data actively.
|
||||
Clients MAY monitor the setting but should be aware that changing this setting
|
||||
without user interaction based on choices made in a different client (or a
|
||||
compromised homeserver) may cause unforeseen security problems or simply be
|
||||
unexpected by users.
|
||||
|
||||
##### Key exports
|
||||
|
||||
Keys can be manually exported from one device to an encrypted file,
|
||||
|
|
@ -1590,8 +1457,8 @@ readers without adding any useful extra information.
|
|||
##### `m.olm.v1.curve25519-aes-sha2`
|
||||
|
||||
The name `m.olm.v1.curve25519-aes-sha2` corresponds to version 1 of the
|
||||
Olm ratchet, as defined by the [Olm specification](/olm-megolm/olm).
|
||||
This uses:
|
||||
Olm ratchet, as defined by the [Olm
|
||||
specification](http://matrix.org/docs/spec/olm.html). This uses:
|
||||
|
||||
- Curve25519 for the initial key agreement.
|
||||
- HKDF-SHA-256 for ratchet key derivation.
|
||||
|
|
@ -1764,8 +1631,8 @@ This is due to a deprecation of the fields. See
|
|||
{{% changed-in v="1.3" %}}
|
||||
|
||||
The name `m.megolm.v1.aes-sha2` corresponds to version 1 of the Megolm
|
||||
ratchet, as defined by the [Megolm specification](/olm-megolm/megolm).
|
||||
This uses:
|
||||
ratchet, as defined by the [Megolm
|
||||
specification](http://matrix.org/docs/spec/megolm.html). This uses:
|
||||
|
||||
- HMAC-SHA-256 for the hash ratchet.
|
||||
- HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256
|
||||
|
|
@ -1908,16 +1775,17 @@ property is required for inclusion, though previous versions of the
|
|||
specification did not have it. In addition to `/versions`, this can be
|
||||
a way to identify the server's support for fallback keys.
|
||||
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|----------------------------------|-------------------|------------------------------------------------------------------------------------------------------------------------|
|
||||
|----------------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
|
||||
| device_lists | DeviceLists | Optional. Information on e2e device updates. Note: only present on an incremental sync. |
|
||||
| device_one_time_keys_count | {string: integer} | **Required if any unclaimed one-time keys exist.** For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. If the count for an algorithm is zero, servers MAY omit that algorithm. If the count for all algorithms is zero, servers MAY omit this parameter entirely. |
|
||||
| device_one_time_keys_count | {string: integer} | Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device. If an algorithm is unlisted, the count for that algorithm is assumed to be zero. If this entire parameter is missing, the count for all algorithms is assumed to be zero. |
|
||||
| device_unused_fallback_key_types | [string] | **Required.** The unused fallback key algorithms. |
|
||||
|
||||
`DeviceLists`
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| changed | [string] | List of users who have updated their device identity or cross-signing keys, or who now share an encrypted room with the client since the previous sync response. |
|
||||
| left | [string] | List of users with whom we do not share any encrypted rooms anymore since the previous sync response. |
|
||||
|
||||
|
|
|
|||
|
|
@ -84,10 +84,6 @@ Additionally, web clients should ensure that *all* `a` tags get a
|
|||
`rel="noopener"` to prevent the target page from referencing the
|
||||
client's tab/window.
|
||||
|
||||
{{% added-in v="1.18" %}} Clients that support rendering numbered lists via the
|
||||
`ol` tag MUST also support the `start` attribute in order to prevent loss of
|
||||
meaning of a message due to the numbering of list items.
|
||||
|
||||
Tags must not be nested more than 100 levels deep. Clients should only
|
||||
support the subset of tags they can render, falling back to other
|
||||
representations of the tags where possible. For example, a client may
|
||||
|
|
@ -123,7 +119,7 @@ Clients SHOULD verify the structure of incoming events to ensure that
|
|||
the expected keys exist and that they are of the right type. Clients can
|
||||
discard malformed events or display a placeholder message to the user.
|
||||
Redacted `m.room.message` events MUST be removed from the client. This
|
||||
can either be replaced with placeholder text (e.g. "[REDACTED]") or
|
||||
can either be replaced with placeholder text (e.g. "\[REDACTED\]") or
|
||||
the redacted message can be removed entirely from the messages view.
|
||||
|
||||
Events which have attachments (e.g. `m.image`, `m.file`) SHOULD be
|
||||
|
|
|
|||
|
|
@ -1,51 +0,0 @@
|
|||
|
||||
### Invite permission
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
Users may want to control who is allowed to invite them to new rooms. This module defines how
|
||||
clients and servers can implement invite permission.
|
||||
|
||||
#### Account data
|
||||
|
||||
{{% event event="m.invite_permission_config" %}}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
To reject invites from all users automatically, clients MAY add an [`m.invite_permission_config`](#minvite_permission_config)
|
||||
event in the user's [account data](#client-config) with the `default_action` property set to
|
||||
`block`. To stop rejecting all invites, the same event without the `default_action` property MUST be
|
||||
added to the account data.
|
||||
|
||||
When the `default_action` field is unset, other parts of the specification might still have effects
|
||||
on invites seen by clients, like [ignoring users](#ignoring-users).
|
||||
|
||||
Attempting to send an invite to a user that blocks invites will result in an error response with the
|
||||
`M_INVITE_BLOCKED` error code.
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
When invites to a given user are blocked, the user's homeserver MUST respond to the following
|
||||
endpoints with an HTTP 403 status code, with the Matrix error code `M_INVITE_BLOCKED`, if the user
|
||||
is invited:
|
||||
|
||||
* [`PUT /_matrix/federation/v1/invite/{roomId}/{eventId}`](/server-server-api/#put_matrixfederationv1inviteroomideventid)
|
||||
* [`PUT /_matrix/federation/v2/invite/{roomId}/{eventId}`](/server-server-api/#put_matrixfederationv2inviteroomideventid)
|
||||
* [`POST /_matrix/client/v3/rooms/{roomId}/invite`](#post_matrixclientv3roomsroomidinvite)
|
||||
* [`POST /_matrix/client/v3/createRoom`](#post_matrixclientv3createroom), due to a user in the
|
||||
`invite` list. It is possible for one of the invited users to be rejected whilst the room creation
|
||||
as a whole succeeds.
|
||||
* [`PUT /_matrix/client/v3/rooms/{roomId}/state/m.room.member/{stateKey}`](#put_matrixclientv3roomsroomidstateeventtypestatekey),
|
||||
when the `membership` is set to `invite`.
|
||||
|
||||
In addition, invite events for this user already in the database, or received over federation, MUST
|
||||
NOT be served over client synchronisation endpoints such as [`GET /sync`](#get_matrixclientv3sync).
|
||||
|
||||
Servers MAY return any suppressed invite events over `GET /sync` if invite blocking is later
|
||||
disabled.
|
||||
|
||||
Other endpoints, such as [`GET /rooms/{roomId}/state`](#get_matrixclientv3roomsroomidstate), are not
|
||||
affected by invite blocking: invite events are returned as normal.
|
||||
|
||||
The Application Services API is also unaffected by invite blocking: invite events are sent over
|
||||
[`PUT /_matrix/app/v1/transactions/{txnId}`](/application-service-api/#put_matrixappv1transactionstxnid).
|
||||
|
|
@ -3,9 +3,6 @@
|
|||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
{{% changed-in v="1.17" %}}: the legacy push rules that looked for mentions in
|
||||
the `body` of the event were removed.
|
||||
|
||||
This module allows users to "mention" other users and rooms within a room event.
|
||||
This is primarily used as an indicator that the recipient should receive a notification
|
||||
about the event.
|
||||
|
|
@ -41,18 +38,19 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
|
|||
must be decrypted first. See [receiving notifications](#receiving-notifications).
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
|
||||
[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
|
||||
[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of
|
||||
the event contains the user's display name or ID. To avoid unintentional notifications,
|
||||
**it is recommended that clients include a `m.mentions` property on each event**.
|
||||
(If there are no mentions to include it can be an empty object.)
|
||||
|
||||
{{% boxes/rationale %}}
|
||||
In previous versions of the specification, mentioning users was done by
|
||||
including the user's display name or the localpart of their Matrix ID and room
|
||||
mentions were done by including the string "@room" in the plaintext `body` of
|
||||
the event. When the `m.mentions` field was introduced, those push rules were
|
||||
disabled if the `m.mentions` field was present.
|
||||
|
||||
To avoid unintentional notifications with clients and servers that still use
|
||||
those push rules, **it is recommended that clients still include a `m.mentions`
|
||||
property on each event**. (If there are no mentions to include it can be an
|
||||
empty object.)
|
||||
{{% /boxes/note %}}
|
||||
the event. This was prone to confusing and buggy behaviour.
|
||||
{{% /boxes/rationale %}}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
|
|
|
|||
|
|
@ -1,98 +0,0 @@
|
|||
### Policy Servers
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
A Policy Server is a homeserver in the room designated to proactively check events
|
||||
before they are sent to the room/users. Rooms are not required to use a Policy
|
||||
Server (PS). Rooms which do use a Policy Server can prevent unwanted events from
|
||||
reaching users.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Room operators might prefer to use a "moderation bot" instead of a Policy Server.
|
||||
Moderation bots are reactive because they typically [redact](#redactions) events
|
||||
after they've already been sent.
|
||||
|
||||
Room operators might also prefer to layer a moderation bot with a Policy Server
|
||||
for added protection.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
A room's Policy Server is designated by the [`m.room.policy`](#mroompolicy) state
|
||||
event described below. If the state event is not set in the room or is missing
|
||||
required fields, the room does *not* use a Policy Server. Similarly, if the server name in the state
|
||||
event has zero joined users in the room, the room also does *not* use a Policy
|
||||
Server.
|
||||
|
||||
When the room is using a Policy Server, *all* events except for the `m.room.policy`
|
||||
state event itself are checked by that Policy Server. This includes membership
|
||||
events, power level changes, events from before the Policy Server was enabled,
|
||||
and non-state or non-empty `state_key` `m.room.policy` events.
|
||||
|
||||
What a Policy Server checks for on an event is left as an implementation detail.
|
||||
|
||||
{{% boxes/note %}}
|
||||
More information about how a Policy Server operates precisely is available in
|
||||
the [Server-Server API](/server-server-api/#policy-servers). Most notably, not
|
||||
every homeserver is a Policy Server, and not every Policy Server is a full
|
||||
homeserver.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% event event="m.room.policy" %}}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
Clients do not interact with the Policy Server directly, but may need enough
|
||||
information to be able to set the `m.room.policy` state event. For this, a client
|
||||
can attempt to call [`/.well-known/matrix/policy_server`](#getwell-knownmatrixpolicy_server)
|
||||
on a user-provided server name. The returned information can then be used to
|
||||
populate the `m.room.policy` state event.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Clients are *not* required to use `/.well-known/matrix/policy_server` to populate the
|
||||
`m.room.policy` state event. If they have the required information from elsewhere,
|
||||
they can simply send the state event.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Server behaviour
|
||||
|
||||
See the [Policy Servers section of the Server-Server API](/server-server-api/#policy-servers).
|
||||
|
||||
{{% boxes/note %}}
|
||||
If implementing your own Policy Server, see [MSC4284: Policy Servers](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/4284-policy-servers.md)
|
||||
for additional security, implementation, and safety considerations.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
#### Security considerations
|
||||
|
||||
{{% boxes/note %}}
|
||||
Portions of this section rely on context from the [Policy Servers section of the Server-Server API](/server-server-api/#policy-servers).
|
||||
{{% /boxes/note %}}
|
||||
|
||||
By nature of being a proactive tool for a room, Policy Server can expect to be
|
||||
Denial of Service (DoS) targets. Policy Servers MUST be tolerant to DoS attacks.
|
||||
The scale of attack they need to tolerate is left as an implementation/deployment
|
||||
detail. A Policy Server dedicated to a small community might not have the same
|
||||
requirements as a Policy Server available for many communities to use.
|
||||
|
||||
To help ensure that rooms can be used when their chosen Policy Server is inaccessible,
|
||||
the `m.room.policy` state event can be set *without* consulting the Policy Server.
|
||||
This in effect allows users with appropriate power levels to wipe the content of
|
||||
`m.room.policy`, disabling the Policy Server immediately.
|
||||
|
||||
Policy Servers MUST have a joined user in the room to prevent rooms overloading
|
||||
or forcing a given server to act as a Policy Server. The Policy Server can evict
|
||||
itself from the room to also disable usage immediately.
|
||||
|
||||
Events sent "before" the Policy Server was enabled can end up being recommended
|
||||
for exclusion by the Policy Server. This is expected behaviour to ensure new policies
|
||||
apply to events which took a while to send.
|
||||
|
||||
Homeservers might not ask a Policy Server for a signature on an event before sending
|
||||
it to the room. Other compliant homeservers will request that signature instead,
|
||||
and layered tooling (like "moderation bots") can help remove events which bypass
|
||||
the room's Policy Server, if desirable.
|
||||
|
||||
Homeservers might request and receive a valid signature for an event, but delay
|
||||
or never send the event. "Moderation bots" can monitor for clock drift on signed
|
||||
events, if desirable. A Policy Server implementation might also monitor for clock
|
||||
drift, though does need to consider that events can be backdated in ways beyond
|
||||
`origin_server_ts`.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
### Push Notifications
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+--------------------+ +-------------------+
|
||||
Matrix HTTP | | | |
|
||||
Notification Protocol | App Developer | | Device Vendor |
|
||||
|
|
@ -83,7 +83,7 @@ Push Ruleset
|
|||
: A push ruleset *scopes a set of rules according to some criteria*. For
|
||||
example, some rules may only be applied for messages from a particular
|
||||
sender, a particular room, or by default. The push ruleset contains the
|
||||
entire set of rules.
|
||||
entire set of scopes and rules.
|
||||
|
||||
#### Push Rules
|
||||
|
||||
|
|
@ -91,8 +91,10 @@ A push rule is a single rule that states under what *conditions* an
|
|||
event should be passed onto a push gateway and *how* the notification
|
||||
should be presented. There are different "kinds" of push rules and each
|
||||
rule has an associated priority. Every push rule MUST have a `kind` and
|
||||
`rule_id`. The `rule_id` is a unique string within the kind of rule.
|
||||
Rules may have extra keys depending on the value of `kind`.
|
||||
`rule_id`. The `rule_id` is a unique string within the kind of rule and
|
||||
its' scope: `rule_ids` do not need to be unique between rules of the
|
||||
same kind on different devices. Rules may have extra keys depending on
|
||||
the value of `kind`.
|
||||
|
||||
The different `kind`s of rule, in the order that they are checked, are:
|
||||
|
||||
|
|
@ -380,9 +382,6 @@ The following `alt_aliases` values will NOT match:
|
|||
|
||||
**`contains_display_name`**
|
||||
|
||||
{{% changed-in v="1.17" %}}: this condition is deprecated and **should not be
|
||||
used in new push rules**.
|
||||
|
||||
This matches messages where `content.body` contains the owner's display name in
|
||||
that room. This is a separate condition because display names may change and as such
|
||||
it would be hard to maintain a rule that matched the user's display name. This
|
||||
|
|
@ -414,9 +413,6 @@ Parameters:
|
|||
|
||||
#### Predefined Rules
|
||||
|
||||
{{% changed-in v="1.17" %}}: the legacy default push rules that looked for
|
||||
mentions in the `body` of the event were removed.
|
||||
|
||||
Homeservers can specify "server-default rules". They operate at a lower
|
||||
priority than "user-defined rules", except for the `.m.rule.master` rule
|
||||
which has always a higher priority than any other rule. The `rule_id`
|
||||
|
|
@ -561,6 +557,41 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**
|
||||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
|
||||
does not have an [`m.mentions` property](#definition-mmentions)**.
|
||||
|
||||
Matches any message whose content contains the user's current display name
|
||||
in the room in which it was sent.
|
||||
|
||||
Definition:
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.contains_display_name",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "contains_display_name"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
<a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**
|
||||
|
||||
{{% added-in v="1.7" %}}
|
||||
|
|
@ -595,6 +626,44 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**
|
||||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
|
||||
does not have an [`m.mentions` property](#definition-mmentions)**.
|
||||
|
||||
Matches any message from a sender with the proper power level whose content
|
||||
contains the text `@room`, signifying the whole room should be notified of
|
||||
the event.
|
||||
|
||||
Definition:
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.roomnotif",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_match",
|
||||
"key": "content.body",
|
||||
"pattern": "@room"
|
||||
},
|
||||
{
|
||||
"kind": "sender_notification_permission",
|
||||
"key": "room"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**<a id="mruletombstone"></a>`.m.rule.tombstone`**
|
||||
|
||||
Matches any state event whose type is `m.room.tombstone`. This is
|
||||
|
|
@ -707,6 +776,39 @@ Definition:
|
|||
}
|
||||
```
|
||||
|
||||
##### Default Content Rules
|
||||
|
||||
<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**
|
||||
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
As of `v1.7`, this rule is deprecated and **should only be enabled if the event
|
||||
does not have an [`m.mentions` property](#definition-mmentions)**.
|
||||
|
||||
Matches any message whose content contains the local part of the user's
|
||||
Matrix ID, separated by word boundaries.
|
||||
|
||||
Definition (as a `content` rule):
|
||||
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.contains_user_name",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"pattern": "[the local part of the user's Matrix ID]",
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Default Underride Rules
|
||||
|
||||
**`.m.rule.call`**
|
||||
|
|
|
|||
|
|
@ -214,7 +214,7 @@ before delivering them to clients.
|
|||
Some receipts are sent across federation as EDUs with type `m.receipt`. The
|
||||
format of the EDUs are:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
<room_id>: {
|
||||
<receipt_type>: {
|
||||
|
|
|
|||
|
|
@ -1,40 +0,0 @@
|
|||
### Recently used emoji
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
This module enables clients to track a user's cumulated emoji usage across different
|
||||
devices. The data is stored in the [`m.recent_emoji`](#mrecent_emoji)
|
||||
global [account data](#client-config) and can, among other things, be used to
|
||||
generate recommendations in emoji pickers.
|
||||
|
||||
#### Events
|
||||
|
||||
{{% event event="m.recent_emoji" %}}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
What exactly constitutes trackable emoji usage is left as an implementation detail
|
||||
for clients. It is RECOMMENDED to include sending emoji in both messages and
|
||||
annotations.
|
||||
|
||||
When an emoji is used, the sending client moves (or adds) it to the beginning of
|
||||
the `recent_emoji` array and increments (or initializes) its counter. This keeps
|
||||
the array ordered by last usage time which facilitates evaluating the data. How
|
||||
exactly the client evaluates and uses the collected data is deliberately left
|
||||
unspecified.
|
||||
|
||||
To prevent excessive growth of the event as new emoji are being used, clients
|
||||
SHOULD limit the length of the `recent_emoji` array by dropping elements from
|
||||
its end. A RECOMMENDED maximum length is 100 emoji.
|
||||
|
||||
To enable future extension, clients MUST tolerate and preserve array elements
|
||||
within `recent_emoji` regardless of whether they understand or support the
|
||||
contained `emoji` value. This means ignoring entries with unrecognised values
|
||||
of `emoji` when deciding what to display to the user while retaining them when
|
||||
modifying the array (unless the modification is for truncation).
|
||||
|
||||
To prevent undefined behavior, clients SHOULD remove array elements that
|
||||
don't conform to the event schema such as elements with negative counters.
|
||||
|
||||
|
||||
|
||||
|
|
@ -20,9 +20,9 @@ Previously, a rich reply could only reference another `m.room.message` event.
|
|||
{{% boxes/note %}}
|
||||
{{% changed-in v="1.13" %}}
|
||||
In previous versions of the specification, rich replies could include a fallback
|
||||
representation of the original message in the `body` (using a prefix sequence)
|
||||
and `formatted_body` (using a custom HTML element) for clients that do not
|
||||
support rich replies. This is no longer the case, but clients SHOULD still
|
||||
representation of the original message message in the `body` (using a prefix
|
||||
sequence) and `formatted_body` (using a custom HTML element) for clients that do
|
||||
not support rich replies. This is no longer the case, but clients SHOULD still
|
||||
remove this fallback before rendering the event.
|
||||
|
||||
To strip the fallback on the `body`, the client should iterate over each
|
||||
|
|
|
|||
|
|
@ -20,10 +20,6 @@ old room. Another approach may be to virtually merge the rooms such that
|
|||
the old room's timeline seamlessly continues into the new timeline
|
||||
without the user having to jump between the rooms.
|
||||
|
||||
When joining a room using the room ID in an `m.room.tombstone` event or
|
||||
`predecessor` field on `m.room.create`, clients SHOULD parse the event
|
||||
`sender` and use the resulting server name as a `via` parameter.
|
||||
|
||||
{{% http-api spec="client-server" api="room_upgrades" %}}
|
||||
|
||||
#### Server behaviour
|
||||
|
|
@ -47,8 +43,8 @@ They must be explicitly set during the `/upgrade` call.
|
|||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.16" %}} When upgrading to room version 12 or later, the `event_id` property inside
|
||||
`predecessor` MAY be omitted.
|
||||
{{% added-in v="1.16" %}} When upgrading to room version 12 or later, the `predecessor` field MAY NOT contain
|
||||
an `event_id`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
3. Replicates transferable state events to the new room. The exact
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@ clients will try to use the default key to decrypt secrets.
|
|||
|
||||
Clients that want to present a simplified interface to users by not supporting
|
||||
multiple keys should use the default key if one is specified. If no default
|
||||
key is specified, the client may behave as if no key is present at
|
||||
key is specified, the client may behave as if there is no key is present at
|
||||
all. When such a client creates a key, it should mark that key as being the
|
||||
default key.
|
||||
|
||||
|
|
@ -157,7 +157,7 @@ Some secret is encrypted using keys with ID `key_id_1` and `key_id_2`:
|
|||
|
||||
`org.example.some.secret`:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
"encrypted": {
|
||||
"key_id_1": {
|
||||
|
|
@ -177,7 +177,7 @@ and the key descriptions for the keys would be:
|
|||
|
||||
`m.secret_storage.key.key_id_1`:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
"name": "Some key",
|
||||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||||
|
|
@ -187,7 +187,7 @@ and the key descriptions for the keys would be:
|
|||
|
||||
`m.secret_storage.key.key_id_2`:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
"name": "Some other key",
|
||||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||||
|
|
@ -199,7 +199,7 @@ If `key_id_1` is the default key, then we also have:
|
|||
|
||||
`m.secret_storage.default_key`:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
"key": "key_id_1"
|
||||
}
|
||||
|
|
@ -294,7 +294,7 @@ in the `iterations` parameter.
|
|||
|
||||
Example:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
"passphrase": {
|
||||
"algorithm": "m.pbkdf2",
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@ parent to the room. The `state_key` for the event is the child room's ID.
|
|||
|
||||
For example, to achieve the following:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
#space:example.org
|
||||
#general:example.org (!abcdefg:example.org)
|
||||
!private:example.org
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ opening an embedded web view.
|
|||
|
||||
These steps are illustrated as follows:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
Matrix Client Matrix Homeserver Auth Server
|
||||
| | |
|
||||
|-------------(0) GET /login----------->| |
|
||||
|
|
|
|||
|
|
@ -44,7 +44,7 @@ If the lookup yields a result for a Matrix User ID then the normal [invite
|
|||
process](/server-server-api/#inviting-to-a-room) can be initiated. This process
|
||||
ends up looking like this:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+---------+ +-------------+ +-----------------+
|
||||
| Client | | Homeserver | | IdentityServer |
|
||||
+---------+ +-------------+ +-----------------+
|
||||
|
|
@ -74,7 +74,7 @@ the invite on the identity server with a call to
|
|||
and emit a valid [`m.room.third_party_invite`](#mroomthird_party_invite) event
|
||||
to the room. This process ends up looking like this:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+---------+ +-------------+ +-----------------+
|
||||
| Client | | Homeserver | | IdentityServer |
|
||||
+---------+ +-------------+ +-----------------+
|
||||
|
|
@ -133,7 +133,7 @@ and an identity server IS, the full sequence for a third-party invite
|
|||
would look like the following. This diagram assumes H1 and H2 are
|
||||
residents of the room while H3 is attempting to join.
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+
|
||||
| UserA | | ThirdPartyUser | | H1 | | H2 | | H3 | | IS |
|
||||
+-------+ +-----------------+ +-----+ +-----+ +-----+ +-----+
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@ flag to `true`.
|
|||
```
|
||||
|
||||
{{% boxes/note %}}
|
||||
Clients which are aware of threads (they do not render threads, but are otherwise
|
||||
Clients which are acutely aware of threads (they do not render threads, but are otherwise
|
||||
aware of the feature existing in the spec) can treat rich replies to an event with a `rel_type`
|
||||
of `m.thread` as a threaded reply, for conversation continuity on the threaded client's side.
|
||||
|
||||
|
|
|
|||
|
|
@ -129,7 +129,7 @@ or not there have been any changes to the Matrix spec.
|
|||
|
||||
A call is set up with message events exchanged as follows:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
Caller Callee
|
||||
[Place Call]
|
||||
m.call.invite ----------->
|
||||
|
|
@ -144,7 +144,7 @@ A call is set up with message events exchanged as follows:
|
|||
|
||||
Or a rejected call:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
Caller Callee
|
||||
m.call.invite ------------>
|
||||
m.call.candidate --------->
|
||||
|
|
|
|||
|
|
@ -2,15 +2,17 @@
|
|||
title: "Identity Service API"
|
||||
weight: 40
|
||||
type: docs
|
||||
description: |
|
||||
The Matrix client-server and server-server APIs are largely expressed in
|
||||
Matrix user identifiers. Sometimes it is useful to refer to users by other
|
||||
(“third-party”) identifiers such as email addresses or phone numbers. The
|
||||
Identity Service API describes how mappings between 3PIDs and Matrix user
|
||||
IDs can be established, validated, and used; in practice this has been
|
||||
applied to email addresses and phone numbers.
|
||||
---
|
||||
|
||||
The Matrix client-server and server-server APIs are largely expressed in
|
||||
Matrix user identifiers. From time to time, it is useful to refer to
|
||||
users by other ("third-party") identifiers, or "3PID"s, e.g. their email
|
||||
address or phone number. This Identity Service Specification describes
|
||||
how mappings between third-party identifiers and Matrix user identifiers
|
||||
can be established, validated, and used. This description technically
|
||||
may apply to any 3PID, but in practice has only been applied
|
||||
specifically to email addresses and phone numbers.
|
||||
|
||||
## General principles
|
||||
|
||||
The purpose of an identity server is to validate, store, and answer
|
||||
|
|
@ -70,58 +72,54 @@ the keys `error` and `errcode` MUST always be present.
|
|||
|
||||
Some standard error codes are below:
|
||||
|
||||
<!-- Please keep the error codes below in alphabetical order -->
|
||||
`M_NOT_FOUND`
|
||||
The resource requested could not be located.
|
||||
|
||||
`M_MISSING_PARAMS`
|
||||
The request was missing one or more parameters.
|
||||
|
||||
`M_INVALID_PARAM`
|
||||
The request contained one or more invalid parameters.
|
||||
|
||||
`M_SESSION_NOT_VALIDATED`
|
||||
The session has not been validated.
|
||||
|
||||
`M_NO_VALID_SESSION`
|
||||
A session could not be located for the given parameters.
|
||||
|
||||
`M_SESSION_EXPIRED`
|
||||
The session has expired and must be renewed.
|
||||
|
||||
`M_INVALID_EMAIL`
|
||||
The email address provided was not valid.
|
||||
|
||||
`M_EMAIL_SEND_ERROR`
|
||||
: There was an error sending an email. Typically seen when attempting to
|
||||
There was an error sending an email. Typically seen when attempting to
|
||||
verify ownership of a given email address.
|
||||
|
||||
`M_INVALID_ADDRESS`
|
||||
: The provided third-party address was not valid.
|
||||
|
||||
`M_INVALID_EMAIL`
|
||||
: The email address provided was not valid.
|
||||
|
||||
`M_INVALID_PARAM`
|
||||
: The request contained one or more invalid parameters.
|
||||
|
||||
`M_MISSING_PARAMS`
|
||||
: The request was missing one or more parameters.
|
||||
|
||||
`M_NO_VALID_SESSION`
|
||||
: A session could not be located for the given parameters.
|
||||
|
||||
`M_NOT_FOUND`
|
||||
: The resource requested could not be located.
|
||||
The provided third-party address was not valid.
|
||||
|
||||
`M_SEND_ERROR`
|
||||
: There was an error sending a notification. Typically seen when
|
||||
There was an error sending a notification. Typically seen when
|
||||
attempting to verify ownership of a given third-party address.
|
||||
|
||||
`M_SESSION_EXPIRED`
|
||||
: The session has expired and must be renewed.
|
||||
|
||||
`M_SESSION_NOT_VALIDATED`
|
||||
: The session has not been validated.
|
||||
|
||||
`M_THREEPID_IN_USE`
|
||||
: The third-party identifier is already in use by another user. Typically
|
||||
this error will have an additional `mxid` property to indicate who owns
|
||||
the third-party identifier.
|
||||
|
||||
`M_UNKNOWN`
|
||||
: An unknown error has occurred.
|
||||
|
||||
`M_UNRECOGNIZED`
|
||||
: The request contained an unrecognised value, such as an unknown token or
|
||||
The request contained an unrecognised value, such as an unknown token or
|
||||
medium.
|
||||
|
||||
: This is also used as the response if a server did not understand the request.
|
||||
This is also used as the response if a server did not understand the request.
|
||||
This is expected to be returned with a 404 HTTP status code if the endpoint is
|
||||
not implemented or a 405 HTTP status code if the endpoint is implemented, but
|
||||
the incorrect HTTP method is used.
|
||||
|
||||
<!-- Please keep the error codes above in alphabetical order -->
|
||||
`M_THREEPID_IN_USE`
|
||||
The third-party identifier is already in use by another user. Typically
|
||||
this error will have an additional `mxid` property to indicate who owns
|
||||
the third-party identifier.
|
||||
|
||||
`M_UNKNOWN`
|
||||
An unknown error has occurred.
|
||||
|
||||
## Privacy
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +0,0 @@
|
|||
---
|
||||
title: "Olm & Megolm"
|
||||
weight: 61
|
||||
type: docs
|
||||
---
|
||||
|
||||
Matrix uses the Olm and Megolm cryptographic ratchets for [end-to-end encryption](../client-server-api/#end-to-end-encryption).
|
||||
|
||||
- [Olm: A Cryptographic Ratchet](/olm-megolm/olm/)
|
||||
- [Megolm group ratchet](/olm-megolm/megolm/)
|
||||
|
|
@ -1,378 +0,0 @@
|
|||
---
|
||||
title: "Megolm group ratchet"
|
||||
weight: 20
|
||||
type: docs
|
||||
---
|
||||
|
||||
An AES-based cryptographic ratchet intended for group communications.
|
||||
|
||||
## Background
|
||||
|
||||
The Megolm ratchet is intended for encrypted messaging applications where there
|
||||
may be a large number of recipients of each message, thus precluding the use of
|
||||
peer-to-peer encryption systems such as [Olm][].
|
||||
|
||||
It also allows a recipient to decrypt received messages multiple times. For
|
||||
instance, in client/server applications, a copy of the ciphertext can be stored
|
||||
on the (untrusted) server, while the client need only store the session keys.
|
||||
|
||||
## Overview
|
||||
|
||||
Each participant in a conversation uses their own outbound session for
|
||||
encrypting messages. A session consists of a ratchet and an [Ed25519][] keypair.
|
||||
|
||||
Secrecy is provided by the ratchet, which can be wound forwards but not
|
||||
backwards, and is used to derive a distinct message key for each message.
|
||||
|
||||
Authenticity is provided via Ed25519 signatures.
|
||||
|
||||
The value of the ratchet, and the public part of the Ed25519 key, are shared
|
||||
with other participants in the conversation via secure peer-to-peer
|
||||
channels. Provided that peer-to-peer channel provides authenticity of the
|
||||
messages to the participants and deniability of the messages to third parties,
|
||||
the Megolm session will inherit those properties.
|
||||
|
||||
## The Megolm ratchet algorithm
|
||||
|
||||
The Megolm ratchet \(R_i\) consists of four parts, \(R_{i,j}\) for
|
||||
\(j \in {0,1,2,3}\). The length of each part depends on the hash function
|
||||
in use (256 bits for this version of Megolm).
|
||||
|
||||
The ratchet is initialised with cryptographically-secure random data, and
|
||||
advanced as follows:
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
R_{i,0} &=
|
||||
\begin{cases}
|
||||
H_0\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
|
||||
R_{i-1,0} &\text{otherwise}
|
||||
\end{cases}\\
|
||||
R_{i,1} &=
|
||||
\begin{cases}
|
||||
H_1\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
|
||||
H_1\left(R_{2^{16}(m-1),1}\right) &\text{if }\exists m | i = 2^{16}m\\
|
||||
R_{i-1,1} &\text{otherwise}
|
||||
\end{cases}\\
|
||||
R_{i,2} &=
|
||||
\begin{cases}
|
||||
H_2\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
|
||||
H_2\left(R_{2^{16}(m-1),1}\right) &\text{if }\exists m | i = 2^{16}m\\
|
||||
H_2\left(R_{2^8(p-1),2}\right) &\text{if }\exists p | i = 2^8p\\
|
||||
R_{i-1,2} &\text{otherwise}
|
||||
\end{cases}\\
|
||||
R_{i,3} &=
|
||||
\begin{cases}
|
||||
H_3\left(R_{2^{24}(n-1),0}\right) &\text{if }\exists n | i = 2^{24}n\\
|
||||
H_3\left(R_{2^{16}(m-1),1}\right) &\text{if }\exists m | i = 2^{16}m\\
|
||||
H_3\left(R_{2^8(p-1),2}\right) &\text{if }\exists p | i = 2^8p\\
|
||||
H_3\left(R_{i-1,3}\right) &\text{otherwise}
|
||||
\end{cases}
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
where \(H_0\), \(H_1\), \(H_2\), and \(H_3\) are different hash
|
||||
functions. In summary: every \(2^8\) iterations, \(R_{i,3}\) is
|
||||
reseeded from \(R_{i,2}\). Every \(2^{16}\) iterations, \(R_{i,2}\)
|
||||
and \(R_{i,3}\) are reseeded from \(R_{i,1}\). Every \(2^{24}\)
|
||||
iterations, \(R_{i,1}\), \(R_{i,2}\) and \(R_{i,3}\) are reseeded
|
||||
from \(R_{i,0}\).
|
||||
|
||||
The complete ratchet value, \(R_{i}\), is hashed to generate the keys used
|
||||
to encrypt each message. This scheme allows the ratchet to be advanced an
|
||||
arbitrary amount forwards while needing at most 1020 hash computations. A
|
||||
client can decrypt chat history onwards from the earliest value of the ratchet
|
||||
it is aware of, but cannot decrypt history from before that point without
|
||||
reversing the hash function.
|
||||
|
||||
This allows a participant to share its ability to decrypt chat history with
|
||||
another from a point in the conversation onwards by giving a copy of the
|
||||
ratchet at that point in the conversation.
|
||||
|
||||
|
||||
## The Megolm protocol
|
||||
|
||||
### Session setup
|
||||
|
||||
Each participant in a conversation generates their own Megolm session. A
|
||||
session consists of three parts:
|
||||
|
||||
* a 32 bit counter, \(i\).
|
||||
* an [Ed25519][] keypair, \(K\).
|
||||
* a ratchet, \(R_i\), which consists of four 256-bit values,
|
||||
\(R_{i,j}\) for \(j \in {0,1,2,3}\).
|
||||
|
||||
The counter \(i\) is initialised to \(0\). A new Ed25519 keypair is
|
||||
generated for \(K\). The ratchet is simply initialised with 1024 bits of
|
||||
cryptographically-secure random data.
|
||||
|
||||
A single participant may use multiple sessions over the lifetime of a
|
||||
conversation. The public part of \(K\) is used as an identifier to
|
||||
discriminate between sessions.
|
||||
|
||||
### Sharing session data
|
||||
|
||||
To allow other participants in the conversation to decrypt messages, the
|
||||
session data is formatted as described in [Session-sharing format](#session-sharing-format). It is then
|
||||
shared with other participants in the conversation via a secure peer-to-peer
|
||||
channel (such as that provided by [Olm][]).
|
||||
|
||||
When the session data is received from other participants, the recipient first
|
||||
checks that the signature matches the public key. They then store their own
|
||||
copy of the counter, ratchet, and public key.
|
||||
|
||||
### Message encryption
|
||||
|
||||
This version of Megolm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding and
|
||||
[HMAC-SHA-256][] (truncated to 64 bits). The 256 bit AES key, 256 bit HMAC key,
|
||||
and 128 bit AES IV are derived from the megolm ratchet \(R_i\):
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
\mathit{AES\_KEY}_{i}\;\parallel\;\mathit{HMAC\_KEY}_{i}\;\parallel\;\mathit{AES\_IV}_{i}
|
||||
&= \operatorname{HKDF}\left(0,\,R_{i},\text{"MEGOLM\_KEYS"},\,80\right) \\
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
where \(\parallel\) represents string splitting, and
|
||||
\(\operatorname{HKDF}\left(\mathit{salt},\,\mathit{IKM},\,\mathit{info},\,L\right)\)
|
||||
refers to the [HMAC-based key
|
||||
derivation function][] using using [SHA-256][] as the hash function
|
||||
([HKDF-SHA-256][]) with a salt value of \(\mathit{salt}\), input key material of
|
||||
\(\mathit{IKM}\), context string \(\mathit{info}\), and output keying material length of
|
||||
\(L\) bytes.
|
||||
|
||||
The plain-text is encrypted with AES-256, using the key \(\mathit{AES\_KEY}_{i}\)
|
||||
and the IV \(\mathit{AES\_IV}_{i}\) to give the cipher-text, \(X_{i}\).
|
||||
|
||||
The ratchet index \(i\), and the cipher-text \(X_{i}\), are then packed
|
||||
into a message as described in [Message format](#message-format). Then the entire message
|
||||
(including the version bytes and all payload bytes) are passed through
|
||||
HMAC-SHA-256. The first 8 bytes of the MAC are appended to the message.
|
||||
|
||||
Finally, the authenticated message is signed using the Ed25519 keypair; the 64
|
||||
byte signature is appended to the message.
|
||||
|
||||
The complete signed message, together with the public part of \(K\) (acting
|
||||
as a session identifier), can then be sent over an insecure channel. The
|
||||
message can then be authenticated and decrypted only by recipients who have
|
||||
received the session data.
|
||||
|
||||
### Advancing the ratchet
|
||||
|
||||
After each message is encrypted, the ratchet is advanced. This is done as
|
||||
described in [The Megolm ratchet algorithm](#the-megolm-ratchet-algorithm), using the following definitions:
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
H_0(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x00"}) \\
|
||||
H_1(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x01"}) \\
|
||||
H_2(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x02"}) \\
|
||||
H_3(A) &\equiv \operatorname{HMAC}(A,\text{``\char`\\x03"}) \\
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
where \(\operatorname{HMAC}(A, T)\) is the HMAC-SHA-256 of ``T``, using ``A`` as the
|
||||
key.
|
||||
|
||||
For outbound sessions, the updated ratchet and counter are stored in the
|
||||
session.
|
||||
|
||||
In order to maintain the ability to decrypt conversation history, inbound
|
||||
sessions should store a copy of their earliest known ratchet value (unless they
|
||||
explicitly want to drop the ability to decrypt that history - see [Partial
|
||||
Forward Secrecy](#partial-forward-secrecy)). They may also choose to cache calculated ratchet values,
|
||||
but the decision of which ratchet states to cache is left to the application.
|
||||
|
||||
## Data exchange formats
|
||||
|
||||
### Session sharing format
|
||||
|
||||
This format is used for the initial sharing of a Megolm session with other
|
||||
group participants who need to be able to read messages encrypted by this
|
||||
session.
|
||||
|
||||
The session sharing format is as follows:
|
||||
|
||||
```nohighlight
|
||||
+---+----+--------+--------+--------+--------+------+-----------+
|
||||
| V | i | R(i,0) | R(i,1) | R(i,2) | R(i,3) | Kpub | Signature |
|
||||
+---+----+--------+--------+--------+--------+------+-----------+
|
||||
0 1 5 37 69 101 133 165 229 bytes
|
||||
```
|
||||
|
||||
The version byte, ``V``, is ``"\x02"``.
|
||||
|
||||
This is followed by the ratchet index, \(i\), which is encoded as a
|
||||
big-endian 32-bit integer; the ratchet values \(R_{i,j}\); and the public
|
||||
part of the Ed25519 keypair \(K\).
|
||||
|
||||
The data is then signed using the Ed25519 keypair, and the 64-byte signature is
|
||||
appended.
|
||||
|
||||
### Session export format
|
||||
|
||||
Once the session is initially shared with the group participants, each
|
||||
participant needs to retain a copy of the session if they want to maintain
|
||||
their ability to decrypt messages encrypted with that session.
|
||||
|
||||
For forward-secrecy purposes, a participant may choose to store a ratcheted
|
||||
version of the session. But since the ratchet index is covered by the
|
||||
signature, this would invalidate the signature. So we define a similar format,
|
||||
called the *session export format*, which is identical to the [session sharing
|
||||
format](#session-sharing-format) except for dropping the signature.
|
||||
|
||||
The Megolm session export format is thus as follows:
|
||||
|
||||
```nohighlight
|
||||
+---+----+--------+--------+--------+--------+------+
|
||||
| V | i | R(i,0) | R(i,1) | R(i,2) | R(i,3) | Kpub |
|
||||
+---+----+--------+--------+--------+--------+------+
|
||||
0 1 5 37 69 101 133 165 bytes
|
||||
```
|
||||
|
||||
The version byte, ``V``, is ``"\x01"``.
|
||||
|
||||
This is followed by the ratchet index, \(i\), which is encoded as a
|
||||
big-endian 32-bit integer; the ratchet values \(R_{i,j}\); and the public
|
||||
part of the Ed25519 keypair \(K\).
|
||||
|
||||
### Message format
|
||||
|
||||
Megolm messages consist of a one byte version, followed by a variable length
|
||||
payload, a fixed length message authentication code, and a fixed length
|
||||
signature.
|
||||
|
||||
```nohighlight
|
||||
+---+------------------------------------+-----------+------------------+
|
||||
| V | Payload Bytes | MAC Bytes | Signature Bytes |
|
||||
+---+------------------------------------+-----------+------------------+
|
||||
0 1 N N+8 N+72 bytes
|
||||
```
|
||||
|
||||
The version byte, ``V``, is ``"\x03"``.
|
||||
|
||||
The payload uses a format based on the [Protocol Buffers encoding][]. It
|
||||
consists of the following key-value pairs:
|
||||
|
||||
**Name**|**Tag**|**Type**|**Meaning**
|
||||
:-----:|:-----:|:-----:|:-----:
|
||||
Message-Index|0x08|Integer|The index of the ratchet, i
|
||||
Cipher-Text|0x12|String|The cipher-text, Xi, of the message
|
||||
|
||||
Within the payload, integers are encoded using a variable length encoding. Each
|
||||
integer is encoded as a sequence of bytes with the high bit set followed by a
|
||||
byte with the high bit clear. The seven low bits of each byte store the bits of
|
||||
the integer. The least significant bits are stored in the first byte.
|
||||
|
||||
Strings are encoded as a variable-length integer followed by the string itself.
|
||||
|
||||
Each key-value pair is encoded as a variable-length integer giving the tag,
|
||||
followed by a string or variable-length integer giving the value.
|
||||
|
||||
The payload is followed by the MAC. The length of the MAC is determined by the
|
||||
authenticated encryption algorithm being used (8 bytes in this version of the
|
||||
protocol). The MAC protects all of the bytes preceding the MAC.
|
||||
|
||||
The length of the signature is determined by the signing algorithm being used
|
||||
(64 bytes in this version of the protocol). The signature covers all of the
|
||||
bytes preceding the signature.
|
||||
|
||||
## Limitations
|
||||
|
||||
### Message Replays
|
||||
|
||||
A message can be decrypted successfully multiple times. This means that an
|
||||
attacker can re-send a copy of an old message, and the recipient will treat it
|
||||
as a new message.
|
||||
|
||||
To mitigate this it is recommended that applications track the ratchet indices
|
||||
they have received and that they reject messages with a ratchet index that
|
||||
they have already decrypted.
|
||||
|
||||
### Lack of Transcript Consistency
|
||||
|
||||
In a group conversation, there is no guarantee that all recipients have
|
||||
received the same messages. For example, if Alice is in a conversation with Bob
|
||||
and Charlie, she could send different messages to Bob and Charlie, or could
|
||||
send some messages to Bob but not Charlie, or vice versa.
|
||||
|
||||
Solving this is, in general, a hard problem, particularly in a protocol which
|
||||
does not guarantee in-order message delivery. For now it remains the subject of
|
||||
future research.
|
||||
|
||||
### Lack of Backward Secrecy
|
||||
|
||||
[Backward secrecy](https://intensecrypto.org/public/lec_08_hash_functions_part2.html#sec-forward-and-backward-secrecy)
|
||||
(also called 'future secrecy' or 'post-compromise security') is the property
|
||||
that if current private keys are compromised, an attacker cannot decrypt
|
||||
future messages in a given session. In other words, when looking
|
||||
**backwards** in time at a compromise which has already happened, **current**
|
||||
messages are still secret.
|
||||
|
||||
By itself, Megolm does not possess this property: once the key to a Megolm
|
||||
session is compromised, the attacker can decrypt any message that was
|
||||
encrypted using a key derived from the compromised or subsequent ratchet
|
||||
values.
|
||||
|
||||
In order to mitigate this, the application should ensure that Megolm sessions
|
||||
are not used indefinitely. Instead it should periodically start a new session,
|
||||
with new keys shared over a secure channel.
|
||||
|
||||
<!-- TODO: Can we recommend sensible lifetimes for Megolm sessions? Probably
|
||||
depends how paranoid we're feeling, but some guidelines might be useful. -->
|
||||
|
||||
### Partial Forward Secrecy
|
||||
|
||||
[Forward secrecy](https://intensecrypto.org/public/lec_08_hash_functions_part2.html#sec-forward-and-backward-secrecy)
|
||||
(also called 'perfect forward secrecy') is the property that if the current
|
||||
private keys are compromised, an attacker cannot decrypt *past* messages in
|
||||
a given session. In other words, when looking **forwards** in time towards a
|
||||
potential future compromise, **current** messages will be secret.
|
||||
|
||||
In Megolm, each recipient maintains a record of the ratchet value which allows
|
||||
them to decrypt any messages sent in the session after the corresponding point
|
||||
in the conversation. If this value is compromised, an attacker can similarly
|
||||
decrypt past messages which were encrypted by a key derived from the
|
||||
compromised or subsequent ratchet values. This gives 'partial' forward
|
||||
secrecy.
|
||||
|
||||
To mitigate this issue, the application should offer the user the option to
|
||||
discard historical conversations, by winding forward any stored ratchet values,
|
||||
or discarding sessions altogether.
|
||||
|
||||
### Dependency on secure channel for key exchange
|
||||
|
||||
The design of the Megolm ratchet relies on the availability of a secure
|
||||
peer-to-peer channel for the exchange of session keys. Any vulnerabilities in
|
||||
the underlying channel are likely to be amplified when applied to Megolm
|
||||
session setup.
|
||||
|
||||
For example, if the peer-to-peer channel is vulnerable to an unknown key-share
|
||||
attack, the entire Megolm session become similarly vulnerable. For example:
|
||||
Alice starts a group chat with Eve, and shares the session keys with Eve. Eve
|
||||
uses the unknown key-share attack to forward the session keys to Bob, who
|
||||
believes Alice is starting the session with him. Eve then forwards messages
|
||||
from the Megolm session to Bob, who again believes they are coming from
|
||||
Alice. Provided the peer-to-peer channel is not vulnerable to this attack, Bob
|
||||
will realise that the key-sharing message was forwarded by Eve, and can treat
|
||||
the Megolm session as a forgery.
|
||||
|
||||
A second example: if the peer-to-peer channel is vulnerable to a replay
|
||||
attack, this can be extended to entire Megolm sessions.
|
||||
|
||||
## License
|
||||
|
||||
The Megolm specification (this document) is licensed under the Apache License,
|
||||
Version 2.0 http://www.apache.org/licenses/LICENSE-2.0.
|
||||
|
||||
[Ed25519]: http://ed25519.cr.yp.to/
|
||||
[HMAC-based key derivation function]: https://tools.ietf.org/html/rfc5869
|
||||
[HKDF-SHA-256]: https://tools.ietf.org/html/rfc5869
|
||||
[HMAC-SHA-256]: https://tools.ietf.org/html/rfc2104
|
||||
[SHA-256]: https://tools.ietf.org/html/rfc6234
|
||||
[AES-256]: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
|
||||
[CBC]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
|
||||
[PKCS#7]: https://tools.ietf.org/html/rfc2315
|
||||
[Olm]: /olm-megolm/olm/
|
||||
[Protocol Buffers encoding]: https://developers.google.com/protocol-buffers/docs/encoding
|
||||
|
|
@ -1,334 +0,0 @@
|
|||
---
|
||||
title: "Olm: A Cryptographic Ratchet"
|
||||
weight: 10
|
||||
type: docs
|
||||
---
|
||||
|
||||
An implementation of the double cryptographic ratchet described by
|
||||
https://whispersystems.org/docs/specifications/doubleratchet/.
|
||||
|
||||
## Notation
|
||||
|
||||
This document uses \(\parallel\) to represent string concatenation. When
|
||||
\(\parallel\) appears on the right hand side of an \(=\) it means that
|
||||
the inputs are concatenated. When \(\parallel\) appears on the left hand
|
||||
side of an \(=\) it means that the output is split.
|
||||
|
||||
When this document uses \(\operatorname{ECDH}\left(K_A,K_B\right)\) it means
|
||||
that each party computes a Diffie-Hellman agreement using their private key
|
||||
and the remote party's public key.
|
||||
So party \(A\) computes \(\operatorname{ECDH}\left(K_B^{public},K_A^{private}\right)\)
|
||||
and party \(B\) computes \(\operatorname{ECDH}\left(K_A^{public},K_B^{private}\right)\).
|
||||
|
||||
Where this document uses \(\operatorname{HKDF}\left(salt,IKM,info,L\right)\) it
|
||||
refers to the [HMAC-based key derivation function][] with a salt value of
|
||||
\(salt\), input key material of \(IKM\), context string \(info\),
|
||||
and output keying material length of \(L\) bytes.
|
||||
|
||||
## The Olm Algorithm
|
||||
|
||||
### Initial setup
|
||||
|
||||
The setup takes four [Curve25519][] inputs: Identity keys for Alice and Bob,
|
||||
\(I_A\) and \(I_B\), and one-time keys for Alice and Bob,
|
||||
\(E_A\) and \(E_B\). A shared secret, \(S\), is generated using
|
||||
[Triple Diffie-Hellman][]. The initial 256 bit root key, \(R_0\), and 256
|
||||
bit chain key, \(C_{0,0}\), are derived from the shared secret using an
|
||||
HMAC-based Key Derivation Function using [SHA-256][] as the hash function
|
||||
([HKDF-SHA-256][]) with default salt and ``"OLM_ROOT"`` as the info.
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
S&=\operatorname{ECDH}\left(I_A,E_B\right)\;\parallel\;
|
||||
\operatorname{ECDH}\left(E_A,I_B\right)\;\parallel\;
|
||||
\operatorname{ECDH}\left(E_A,E_B\right)\\
|
||||
R_0\;\parallel\;C_{0,0}&=
|
||||
\operatorname{HKDF}\left(0,S,\text{``OLM\_ROOT"},64\right)
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
### Advancing the root key
|
||||
|
||||
Advancing a root key takes the previous root key, \(R_{i-1}\), and two
|
||||
Curve25519 inputs: the previous ratchet key, \(T_{i-1}\), and the current
|
||||
ratchet key \(T_i\). The even ratchet keys are generated by Alice.
|
||||
The odd ratchet keys are generated by Bob. A shared secret is generated
|
||||
using Diffie-Hellman on the ratchet keys. The next root key, \(R_i\), and
|
||||
chain key, \(C_{i,0}\), are derived from the shared secret using
|
||||
[HKDF-SHA-256][] using \(R_{i-1}\) as the salt and ``"OLM_RATCHET"`` as the
|
||||
info.
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
R_i\;\parallel\;C_{i,0}&=
|
||||
\operatorname{HKDF}\left(
|
||||
R_{i-1},
|
||||
\operatorname{ECDH}\left(T_{i-1},T_i\right),
|
||||
\text{``OLM\_RATCHET"},
|
||||
64
|
||||
\right)
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
### Advancing the chain key
|
||||
|
||||
Advancing a chain key takes the previous chain key, \(C_{i,j-1}\). The next
|
||||
chain key, \(C_{i,j}\), is the [HMAC-SHA-256][] of ``"\x02"`` using the
|
||||
previous chain key as the key.
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
C_{i,j}&=\operatorname{HMAC}\left(C_{i,j-1},\text{``\char`\\x02"}\right)
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
### Creating a message key
|
||||
|
||||
Creating a message key takes the current chain key, \(C_{i,j}\). The
|
||||
message key, \(M_{i,j}\), is the [HMAC-SHA-256][] of ``"\x01"`` using the
|
||||
current chain key as the key. The message keys where \(i\) is even are used
|
||||
by Alice to encrypt messages. The message keys where \(i\) is odd are used
|
||||
by Bob to encrypt messages.
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
M_{i,j}&=\operatorname{HMAC}\left(C_{i,j},\text{``\char`\\x01"}\right)
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
## The Olm Protocol
|
||||
|
||||
### Creating an outbound session
|
||||
|
||||
Bob publishes the public parts of his identity key, \(I_B\), and some
|
||||
single-use one-time keys \(E_B\).
|
||||
|
||||
Alice downloads Bob's identity key, \(I_B\), and a one-time key,
|
||||
\(E_B\). She generates a new single-use key, \(E_A\), and computes a
|
||||
root key, \(R_0\), and a chain key \(C_{0,0}\). She also generates a
|
||||
new ratchet key \(T_0\).
|
||||
|
||||
### Sending the first pre-key messages
|
||||
|
||||
Alice computes a message key, \(M_{0,j}\), and a new chain key,
|
||||
\(C_{0,j+1}\), using the current chain key. She replaces the current chain
|
||||
key with the new one.
|
||||
|
||||
Alice encrypts her plain-text with the message key, \(M_{0,j}\), using an
|
||||
authenticated encryption scheme (see below) to get a cipher-text,
|
||||
\(X_{0,j}\).
|
||||
|
||||
She then sends the following to Bob:
|
||||
* The public part of her identity key, \(I_A\)
|
||||
* The public part of her single-use key, \(E_A\)
|
||||
* The public part of Bob's single-use key, \(E_B\)
|
||||
* The current chain index, \(j\)
|
||||
* The public part of her ratchet key, \(T_0\)
|
||||
* The cipher-text, \(X_{0,j}\)
|
||||
|
||||
Alice will continue to send pre-key messages until she receives a message from
|
||||
Bob.
|
||||
|
||||
### Creating an inbound session from a pre-key message
|
||||
|
||||
Bob receives a pre-key message as above.
|
||||
|
||||
Bob looks up the private part of his single-use key, \(E_B\). He can now
|
||||
compute the root key, \(R_0\), and the chain key, \(C_{0,0}\), from
|
||||
\(I_A\), \(E_A\), \(I_B\), and \(E_B\).
|
||||
|
||||
Bob then advances the chain key \(j\) times, to compute the chain key used
|
||||
by the message, \(C_{0,j}\). He now creates the
|
||||
message key, \(M_{0,j}\), and attempts to decrypt the cipher-text,
|
||||
\(X_{0,j}\). If the cipher-text's authentication is correct then Bob can
|
||||
discard the private part of his single-use one-time key, \(E_B\).
|
||||
|
||||
Bob stores Alice's initial ratchet key, \(T_0\), until he wants to
|
||||
send a message.
|
||||
|
||||
### Sending normal messages
|
||||
|
||||
Once a message has been received from the other side, a session is considered
|
||||
established, and a more compact form is used.
|
||||
|
||||
To send a message, the user checks if they have a sender chain key,
|
||||
\(C_{i,j}\). Alice uses chain keys where \(i\) is even. Bob uses chain
|
||||
keys where \(i\) is odd. If the chain key doesn't exist then a new ratchet
|
||||
key \(T_i\) is generated and a new root key \(R_i\) and chain key
|
||||
\(C_{i,0}\) are computed using \(R_{i-1}\), \(T_{i-1}\) and
|
||||
\(T_i\).
|
||||
|
||||
A message key,
|
||||
\(M_{i,j}\) is computed from the current chain key, \(C_{i,j}\), and
|
||||
the chain key is replaced with the next chain key, \(C_{i,j+1}\). The
|
||||
plain-text is encrypted with \(M_{i,j}\), using an authenticated encryption
|
||||
scheme (see below) to get a cipher-text, \(X_{i,j}\).
|
||||
|
||||
The user then sends the following to the recipient:
|
||||
* The current chain index, \(j\)
|
||||
* The public part of the current ratchet key, \(T_i\)
|
||||
* The cipher-text, \(X_{i,j}\)
|
||||
|
||||
### Receiving messages
|
||||
|
||||
The user receives a message as above with the sender's current chain index, \(j\),
|
||||
the sender's ratchet key, \(T_i\), and the cipher-text, \(X_{i,j}\).
|
||||
|
||||
The user checks if they have a receiver chain with the correct
|
||||
\(i\) by comparing the ratchet key, \(T_i\). If the chain doesn't exist
|
||||
then they compute a new root key, \(R_i\), and a new receiver chain, with
|
||||
chain key \(C_{i,0}\), using \(R_{i-1}\), \(T_{i-1}\) and
|
||||
\(T_i\).
|
||||
|
||||
If the \(j\) of the message is less than
|
||||
the current chain index on the receiver then the message may only be decrypted
|
||||
if the receiver has stored a copy of the message key \(M_{i,j}\). Otherwise
|
||||
the receiver computes the chain key, \(C_{i,j}\). The receiver computes the
|
||||
message key, \(M_{i,j}\), from the chain key and attempts to decrypt the
|
||||
cipher-text, \(X_{i,j}\).
|
||||
|
||||
If the decryption succeeds the receiver updates the chain key for \(T_i\)
|
||||
with \(C_{i,j+1}\) and stores the message keys that were skipped in the
|
||||
process so that they can decode out of order messages. If the receiver created
|
||||
a new receiver chain then they discard their current sender chain so that
|
||||
they will create a new chain when they next send a message.
|
||||
|
||||
## The Olm Message Format
|
||||
|
||||
Olm uses two types of messages. The underlying transport protocol must provide
|
||||
a means for recipients to distinguish between them.
|
||||
|
||||
### Normal Messages
|
||||
|
||||
Olm messages start with a one byte version followed by a variable length
|
||||
payload followed by a fixed length message authentication code.
|
||||
|
||||
```nohighlight
|
||||
+--------------+------------------------------------+-----------+
|
||||
| Version Byte | Payload Bytes | MAC Bytes |
|
||||
+--------------+------------------------------------+-----------+
|
||||
```
|
||||
|
||||
The version byte is ``"\x03"``.
|
||||
|
||||
The payload consists of key-value pairs where the keys are integers and the
|
||||
values are integers and strings. The keys are encoded as a variable length
|
||||
integer tag where the 3 lowest bits indicates the type of the value:
|
||||
0 for integers, 2 for strings. If the value is an integer then the tag is
|
||||
followed by the value encoded as a variable length integer. If the value is
|
||||
a string then the tag is followed by the length of the string encoded as
|
||||
a variable length integer followed by the string itself.
|
||||
|
||||
Olm uses a variable length encoding for integers. Each integer is encoded as a
|
||||
sequence of bytes with the high bit set followed by a byte with the high bit
|
||||
clear. The seven low bits of each byte store the bits of the integer. The least
|
||||
significant bits are stored in the first byte.
|
||||
|
||||
**Name**|**Tag**|**Type**|**Meaning**
|
||||
:-----:|:-----:|:-----:|:-----:
|
||||
Ratchet-Key|0x0A|String|The public part of the ratchet key, Ti, of the message
|
||||
Chain-Index|0x10|Integer|The chain index, j, of the message
|
||||
Cipher-Text|0x22|String|The cipher-text, Xi, j, of the message
|
||||
|
||||
The length of the MAC is determined by the authenticated encryption algorithm
|
||||
being used. (Olm version 1 uses [HMAC-SHA-256][], truncated to 8 bytes). The
|
||||
MAC protects all of the bytes preceding the MAC.
|
||||
|
||||
### Pre-Key Messages
|
||||
|
||||
Olm pre-key messages start with a one byte version followed by a variable
|
||||
length payload.
|
||||
|
||||
```nohighlight
|
||||
+--------------+------------------------------------+
|
||||
| Version Byte | Payload Bytes |
|
||||
+--------------+------------------------------------+
|
||||
```
|
||||
|
||||
The version byte is ``"\x03"``.
|
||||
|
||||
The payload uses the same key-value format as for normal messages.
|
||||
|
||||
**Name**|**Tag**|**Type**|**Meaning**
|
||||
:-----:|:-----:|:-----:|:-----:
|
||||
One-Time-Key|0x0A|String|The public part of Bob's single-use key, Eb.
|
||||
Base-Key|0x12|String|The public part of Alice's single-use key, Ea.
|
||||
Identity-Key|0x1A|String|The public part of Alice's identity key, Ia.
|
||||
Message|0x22|String|An embedded Olm message with its own version and MAC.
|
||||
|
||||
## Olm Authenticated Encryption
|
||||
|
||||
### Version 1
|
||||
|
||||
Version 1 of Olm uses [AES-256][] in [CBC][] mode with [PKCS#7][] padding for
|
||||
encryption and [HMAC-SHA-256][] (truncated to 64 bits) for authentication. The
|
||||
256 bit AES key, 256 bit HMAC key, and 128 bit AES IV are derived from the
|
||||
message key using [HKDF-SHA-256][] using the default salt and an info of
|
||||
``"OLM_KEYS"``.
|
||||
|
||||
\[
|
||||
\begin{aligned}
|
||||
AES\_KEY_{i,j}\;\parallel\;HMAC\_KEY_{i,j}\;\parallel\;AES\_IV_{i,j}
|
||||
&= \operatorname{HKDF}\left(0,M_{i,j},\text{``OLM\_KEYS"},80\right)
|
||||
\end{aligned}
|
||||
\]
|
||||
|
||||
The plain-text is encrypted with AES-256, using the key \(AES\_KEY_{i,j}\)
|
||||
and the IV \(AES\_IV_{i,j}\) to give the cipher-text, \(X_{i,j}\).
|
||||
|
||||
Then the entire message (including the Version Byte and all Payload Bytes) are
|
||||
passed through [HMAC-SHA-256][]. The first 8 bytes of the MAC are appended to the message.
|
||||
|
||||
## Message authentication concerns
|
||||
|
||||
To avoid unknown key-share attacks, the application must include identifying
|
||||
data for the sending and receiving user in the plain-text of (at least) the
|
||||
pre-key messages. Such data could be a user ID, a telephone number;
|
||||
alternatively it could be the public part of a keypair which the relevant user
|
||||
has proven ownership of.
|
||||
|
||||
### Example attacks
|
||||
|
||||
1. Alice publishes her public [Curve25519][] identity key, \(I_A\). Eve
|
||||
publishes the same identity key, claiming it as her own. Bob downloads
|
||||
Eve's keys, and associates \(I_A\) with Eve. Alice sends a message to
|
||||
Bob; Eve intercepts it before forwarding it to Bob. Bob believes the
|
||||
message came from Eve rather than Alice.
|
||||
|
||||
This is prevented if Alice includes her user ID in the plain-text of the
|
||||
pre-key message, so that Bob can see that the message was sent by Alice
|
||||
originally.
|
||||
|
||||
2. Bob publishes his public [Curve25519][] identity key, \(I_B\). Eve
|
||||
publishes the same identity key, claiming it as her own. Alice downloads
|
||||
Eve's keys, and associates \(I_B\) with Eve. Alice sends a message to
|
||||
Eve; Eve cannot decrypt it, but forwards it to Bob. Bob believes the
|
||||
Alice sent the message to him, whereas Alice intended it to go to Eve.
|
||||
|
||||
This is prevented by Alice including the user ID of the intended recpient
|
||||
(Eve) in the plain-text of the pre-key message. Bob can now tell that the
|
||||
message was meant for Eve rather than him.
|
||||
|
||||
## IPR
|
||||
|
||||
The Olm specification (this document) is hereby placed in the public domain.
|
||||
|
||||
## Feedback
|
||||
|
||||
Can be sent to olm at matrix.org.
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
The ratchet that Olm implements was designed by Trevor Perrin and Moxie
|
||||
Marlinspike - details at https://whispersystems.org/docs/specifications/doubleratchet/. Olm is
|
||||
an entirely new implementation written by the Matrix.org team.
|
||||
|
||||
[Curve25519]: http://cr.yp.to/ecdh.html
|
||||
[Triple Diffie-Hellman]: https://whispersystems.org/blog/simplifying-otr-deniability/
|
||||
[HMAC-based key derivation function]: https://tools.ietf.org/html/rfc5869
|
||||
[HKDF-SHA-256]: https://tools.ietf.org/html/rfc5869
|
||||
[HMAC-SHA-256]: https://tools.ietf.org/html/rfc2104
|
||||
[SHA-256]: https://tools.ietf.org/html/rfc6234
|
||||
[AES-256]: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
|
||||
[CBC]: http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf
|
||||
[PKCS#7]: https://tools.ietf.org/html/rfc2315
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
title: "Spec Change Proposals"
|
||||
weight: 62
|
||||
weight: 60
|
||||
type: docs
|
||||
---
|
||||
|
||||
|
|
@ -281,7 +281,7 @@ corresponding labels for each stage on the
|
|||
[matrix-spec-proposals](https://github.com/matrix-org/matrix-spec-proposals)
|
||||
pull request trackers.
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+ +
|
||||
Proposals | Spec PRs | Additional States
|
||||
+-------+ | +------+ | +---------------+
|
||||
|
|
@ -408,9 +408,41 @@ development or testing data.
|
|||
that a particular MSC works) do not have to follow this process.
|
||||
|
||||
1. Have an idea for a feature.
|
||||
1. Implement the feature using [unstable endpoints, vendor prefixes, and
|
||||
unstable feature flags](#unstable-endpoints-features-and-vendor-prefixes)
|
||||
as appropriate.
|
||||
1. Implement the feature using unstable endpoints, vendor prefixes, and
|
||||
unstable feature flags as appropriate.
|
||||
- When using unstable endpoints, they MUST include a vendor
|
||||
prefix. For example:
|
||||
`/_matrix/client/unstable/com.example/login`. Vendor prefixes
|
||||
throughout Matrix always use the Java package naming convention.
|
||||
The MSC for the feature should identify which preferred vendor
|
||||
prefix is to be used by early adopters.
|
||||
- Note that unstable namespaces do not automatically inherit
|
||||
endpoints from stable namespaces: for example, the fact that
|
||||
`/_matrix/client/r0/sync` exists does not imply that
|
||||
`/_matrix/client/unstable/com.example/sync` exists.
|
||||
- If the client needs to be sure the server supports the feature,
|
||||
an unstable feature flag that MUST be vendor prefixed is to be
|
||||
used. This kind of flag shows up in the `unstable_features`
|
||||
section of `/versions` as, for example, `com.example.new_login`.
|
||||
The MSC for the feature should identify which preferred feature
|
||||
flag is to be used by early adopters.
|
||||
- When using this approach correctly, the implementation can
|
||||
ship/release the feature at any time, so long as the
|
||||
implementation is able to accept the technical debt that results
|
||||
from needing to provide adequate backwards and forwards
|
||||
compatibility. The implementation MUST support the flag (and
|
||||
server-side implementation) disappearing and be generally safe
|
||||
for users. Note that implementations early in the MSC review
|
||||
process may also be required to provide backwards compatibility
|
||||
with earlier editions of the proposal.
|
||||
- If the implementation cannot support the technical debt (or if
|
||||
it's impossible to provide forwards/backwards compatibility -
|
||||
e.g. a user authentication change which can't be safely rolled
|
||||
back), the implementation should not attempt to implement the
|
||||
feature and should instead wait for a spec release.
|
||||
- If at any point after early release, the idea changes in a
|
||||
backwards-incompatible way, the feature flag should also change
|
||||
so that implementations can adapt as needed.
|
||||
1. In parallel, or ahead of implementation, open an MSC and solicit
|
||||
review per above.
|
||||
1. Before FCP can be called, the Spec Core Team will require evidence
|
||||
|
|
@ -420,7 +452,10 @@ that a particular MSC works) do not have to follow this process.
|
|||
forwards/backwards compatibility concerns mentioned here.
|
||||
1. The FCP process is completed, and assuming nothing is flagged the
|
||||
MSC lands.
|
||||
1. Implementations can now switch to using stable prefixes, assuming that the change
|
||||
1. Implementations can now switch to using stable prefixes
|
||||
(for example, for an endpoint, moving from
|
||||
`/unstable/org.matrix.mscxxxx/frobnicate`
|
||||
to `/v1/frobnicate`), assuming that the change
|
||||
is backwards compatible with older implementations. In the rare occasion
|
||||
where backwards compatibility is not possible without a new spec release,
|
||||
implementations should continue to use unstable prefixes.
|
||||
|
|
@ -436,6 +471,13 @@ that a particular MSC works) do not have to follow this process.
|
|||
started supporting the new spec release, some noise should be raised
|
||||
in the general direction of the implementation.
|
||||
|
||||
{{% boxes/note %}}
|
||||
MSCs MUST still describe what the stable endpoints/feature looks like
|
||||
with a note towards the bottom for what the unstable feature
|
||||
flag/prefixes are. For example, an MSC would propose `/_matrix/client/r0/new/endpoint`, not `/_matrix/client/unstable/
|
||||
com.example/new/endpoint`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
In summary:
|
||||
|
||||
- Implementations MUST NOT use stable endpoints before the MSC has
|
||||
|
|
@ -447,90 +489,14 @@ In summary:
|
|||
- Implementations SHOULD be wary of the technical debt they are
|
||||
incurring by moving faster than the spec.
|
||||
- The vendor prefix is chosen by the developer of the feature, using
|
||||
the Java package naming convention.
|
||||
the Java package naming convention. The foundation's preferred
|
||||
vendor prefix is `org.matrix`.
|
||||
- The vendor prefixes, unstable feature flags, and unstable endpoints
|
||||
should be included in the MSC, though the MSC MUST be written in a
|
||||
way that proposes new stable endpoints. Typically this is solved by
|
||||
a small table at the bottom mapping the various values from stable
|
||||
to unstable.
|
||||
|
||||
#### Unstable endpoints, features and vendor prefixes
|
||||
|
||||
Unstable endpoints MUST use `/unstable` as the endpoint version and a
|
||||
vendor prefix in Java package naming format. For example:
|
||||
`/_matrix/client/unstable/com.example.mscxxxx/login`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Proposal authors operating with a Matrix.org Foundation mandate SHOULD use
|
||||
a vendor prefix within the `org.matrix` namespace. This namespace is otherwise
|
||||
restricted. Authors who don't own a domain MAY use the `io.github` namespace
|
||||
instead.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
Note that unstable namespaces do not automatically inherit endpoints from
|
||||
stable namespaces: for example, the fact that `/_matrix/client/v3/sync`
|
||||
exists does not imply that `/_matrix/client/unstable/com.example.mscxxxx/sync`
|
||||
exists.
|
||||
|
||||
Vendor prefixes MUST also be used for:
|
||||
|
||||
- New parameters on existing endpoints. For example:
|
||||
`/_matrix/client/v3/publicRooms?com.example.mscxxxx.ordered_by=member_count`.
|
||||
- New properties in existing JSON objects. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
|
||||
"displayname": "Alice Margatroid",
|
||||
"com.example.mscxxxx.phone": [{
|
||||
"type": "landline",
|
||||
"number": "+1-206-555-7000"
|
||||
}],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
- New values for existing parameters or properties. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"errcode": "COM.EXAMPLE.MSCXXXX.M_INVALID_EMAIL",
|
||||
"error": "The email address you provided is invalid."
|
||||
}
|
||||
```
|
||||
|
||||
If the client needs to be sure the server supports the feature, an
|
||||
unstable feature flag that MUST also be vendor prefixed is to be used.
|
||||
This flag shows up in the `unstable_features` section of
|
||||
[`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions)
|
||||
as, for example, `com.example.mscxxxx.new_login`.
|
||||
|
||||
{{% boxes/note %}}
|
||||
MSCs MUST still describe what the stable endpoints/feature looks like
|
||||
with a note towards the bottom for what the unstable feature
|
||||
flag/prefixes are. For example, an MSC would propose `/_matrix/client/v1/new/endpoint`,
|
||||
not `/_matrix/client/unstable/com.example.mscxxxx/new/endpoint`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When using this approach correctly, the implementation can release
|
||||
the feature at any time, so long as the implementation is able to
|
||||
accept the technical debt that results from needing to provide
|
||||
adequate backwards and forwards compatibility. The implementation
|
||||
MUST support the flag (and server-side implementation) disappearing
|
||||
and be generally safe for users. Note that implementations early in
|
||||
the MSC review process may also be required to provide backwards
|
||||
compatibility with earlier editions of the proposal.
|
||||
|
||||
If the implementation cannot support the technical debt (or if it's
|
||||
impossible to provide forwards/backwards compatibility - e.g. a user
|
||||
authentication change which can't be safely rolled back), the
|
||||
implementation should not attempt to implement the feature and should
|
||||
instead wait for a spec release.
|
||||
|
||||
If at any point after early release, the idea changes in a
|
||||
backwards-incompatible way, the feature flag should also change so
|
||||
that implementations can adapt as needed.
|
||||
|
||||
### Placeholder MSCs
|
||||
|
||||
Some proposals may contain security-sensitive or private context which can't be
|
||||
|
|
|
|||
|
|
@ -2,18 +2,19 @@
|
|||
title: "Push Gateway API"
|
||||
weight: 50
|
||||
type: docs
|
||||
description: |
|
||||
Clients may want to receive push notifications when events are received at the
|
||||
homeserver. This is managed by a distinct entity called the Push Gateway.
|
||||
---
|
||||
|
||||
Clients may want to receive push notifications when events are received
|
||||
at the homeserver. This is managed by a distinct entity called the Push
|
||||
Gateway.
|
||||
|
||||
## Overview
|
||||
|
||||
A client's homeserver forwards information about received events to the
|
||||
push gateway. The gateway then submits a push notification to the push
|
||||
notification provider (e.g. APNS, GCM).
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+--------------------+ +-------------------+
|
||||
Matrix HTTP | | | |
|
||||
Notification Protocol | App Developer | | Device Vendor |
|
||||
|
|
|
|||
|
|
@ -56,6 +56,19 @@ Clients should not ask room administrators to upgrade their rooms if the
|
|||
room is running a stable version. Servers SHOULD use **room version 12** as
|
||||
the default room version when creating new rooms.
|
||||
|
||||
{{% boxes/note %}}
|
||||
|
||||
{{% added-in v="1.16" %}}
|
||||
|
||||
Room version 12 is introduced and made default in this specification release.
|
||||
Servers are encouraged to continue using room version 11 as the default room
|
||||
version for the early days and weeks following this specification release,
|
||||
and then gradually switch the default over when they deem appropriate.
|
||||
|
||||
<!-- TODO(SCT): Remove this note box in Matrix 1.17 -->
|
||||
|
||||
{{% /boxes/note %}}
|
||||
|
||||
The available room versions are:
|
||||
|
||||
- [Version 1](/rooms/v1) - **Stable**. The initial room version.
|
||||
|
|
@ -68,7 +81,7 @@ The available room versions are:
|
|||
- [Version 5](/rooms/v5) - **Stable**. Introduces enforcement of
|
||||
signing key validity periods.
|
||||
- [Version 6](/rooms/v6) - **Stable**. Alters several
|
||||
authorisation rules for events.
|
||||
authorization rules for events.
|
||||
- [Version 7](/rooms/v7) - **Stable**. Introduces knocking.
|
||||
- [Version 8](/rooms/v8) - **Stable**. Adds a join rule to allow members
|
||||
of another room to join without invite.
|
||||
|
|
@ -85,7 +98,7 @@ The available room versions are:
|
|||
|
||||
Room versions are used to change properties of rooms that may not be
|
||||
compatible with other servers. For example, changing the rules for event
|
||||
authorisation would cause older servers to potentially end up in a
|
||||
authorization would cause older servers to potentially end up in a
|
||||
split-brain situation due to not understanding the new rules.
|
||||
|
||||
A room version is defined as a string of characters which MUST NOT
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -1,41 +0,0 @@
|
|||
|
||||
##### `m.room.power_levels` events accept values as floats
|
||||
|
||||
When the value is a float
|
||||
* First, exponential notation is applied: `5.114698E4` becomes `51146.98`
|
||||
* Second, the value is truncated at the decimal point: `51146.98` becomes `51146`.
|
||||
|
||||
Values outside the range represented by IEE754 binary64 (a "double") cause the
|
||||
powerlevel event to be rejected, as do `Infinity`, `-Infinity` and `NaN`.
|
||||
|
||||
For example, this is a valid `m.room.power_levels` event in this room version:
|
||||
|
||||
```json
|
||||
{
|
||||
"content": {
|
||||
"ban": 50,
|
||||
"events": {
|
||||
"m.room.power_levels": 100
|
||||
},
|
||||
"events_default": 0,
|
||||
"state_default": 50,
|
||||
"users": {
|
||||
"@example:example.org": 100,
|
||||
"@alice:localhost": 50,
|
||||
"@bob:localhost": 50.57
|
||||
},
|
||||
"users_default": 0
|
||||
},
|
||||
"origin_server_ts": 1432735824653,
|
||||
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
||||
"sender": "@example:example.org",
|
||||
"state_key": "",
|
||||
"type": "m.room.power_levels"
|
||||
}
|
||||
```
|
||||
|
||||
In this example, both `@bob:localhost` and `@alice:localhost` have the same effective
|
||||
power level of `50`, even though the values are technically different.
|
||||
|
||||
Note that, since this room version does not enforce that events comply with the requirements
|
||||
of [Canonical JSON](/appendices#canonical-json), power levels can be formatted as floats.
|
||||
|
|
@ -123,11 +123,11 @@ events: for events *x* and *y*, *x* < *y* if
|
|||
The *iterative auth checks algorithm* takes as input an initial room
|
||||
state and a sorted list of state events, and constructs a new room state
|
||||
by iterating through the event list and applying the state event to the
|
||||
room state if the state event is allowed by the [authorisation
|
||||
rules](/server-server-api#authorisation-rules).
|
||||
If the state event is not allowed by the authorisation rules, then the
|
||||
room state if the state event is allowed by the [authorization
|
||||
rules](/server-server-api#authorization-rules).
|
||||
If the state event is not allowed by the authorization rules, then the
|
||||
event is ignored. If a `(event_type, state_key)` key that is required
|
||||
for checking the authorisation rules is not present in the state, then
|
||||
for checking the authorization rules is not present in the state, then
|
||||
the appropriate state event from the event's `auth_events` is used if
|
||||
the auth event is not rejected.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ in the same respect, so does not need a signature from that server.
|
|||
The event must still be signed by the server denoted by the `sender` property,
|
||||
however.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
---
|
||||
{{% added-in v=3 %}} In room versions 1 and 2, redactions were
|
||||
explicitly part of the [authorisation rules](/rooms/v1/#authorisation-rules)
|
||||
explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
|
||||
under Rule 11. As of room version 3, these conditions no longer exist as
|
||||
represented by [this version's authorisation rules](#authorisation-rules).
|
||||
represented by [this version's authorization rules](#authorization-rules).
|
||||
|
||||
While redactions are always accepted by the authorisation rules for
|
||||
While redactions are always accepted by the authorization rules for
|
||||
events, they should not be sent to clients until both the redaction
|
||||
event and the event the redaction affects have been received, and can
|
||||
be validated. If both events are valid and have been seen by the server,
|
||||
|
|
@ -17,9 +17,6 @@ is met:
|
|||
2. The domain of the redaction event's `sender` matches that of the
|
||||
original event's `sender`.
|
||||
|
||||
Note that the first condition holds true even when the `sender` doesn't have a
|
||||
high enough power level to send the type of event that they're redacting.
|
||||
|
||||
If the server would apply a redaction, the redaction event is also sent
|
||||
to clients. Otherwise, the server simply waits for a valid partner event
|
||||
to arrive where it can then re-check the above.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
@ -74,7 +74,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users or is not a joined member of the room, reject.
|
||||
users, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -59,9 +59,7 @@ Events in version 1 rooms have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
||||
|
|
@ -106,7 +104,7 @@ results of the resolution so far.
|
|||
`sha1(event_id)`.
|
||||
- Add the first event in the list to *R*.
|
||||
- For each subsequent event in the list, check that the event
|
||||
would be allowed by the authorisation rules for a room in state
|
||||
would be allowed by the authorization rules for a room in state
|
||||
*R*. If the event would be allowed, then update *R* with the
|
||||
event and continue with the next event in the list. If it would
|
||||
not be allowed, stop and continue below with `m.room.join_rules`
|
||||
|
|
@ -115,7 +113,7 @@ results of the resolution so far.
|
|||
events.
|
||||
- Repeat the above process for conflicts between `m.room.member`
|
||||
events.
|
||||
- No other events affect the authorisation rules, so for all other
|
||||
- No other events affect the authorization rules, so for all other
|
||||
conflicts, just pick the event with the highest depth and lowest
|
||||
`sha1(event_id)` that passes authentication in *R* and add it to
|
||||
*R*.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ refined in [room version 9](/rooms/v9)).
|
|||
|
||||
Clients should render the new join rule accordingly for such rooms. For example:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
This room is:
|
||||
[ ] Public
|
||||
[x] Private
|
||||
|
|
@ -71,13 +71,13 @@ power levels could be represented as strings for backwards compatibility.
|
|||
|
||||
This backwards compatibility is removed in this room version - power levels MUST NOT
|
||||
be represented as strings within this room version. Power levels which are not
|
||||
correctly structured are rejected under the authorisation rules below.
|
||||
correctly structured are rejected under the authorization rules below.
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
@ -150,7 +150,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users or is not a joined member of the room, reject.
|
||||
users, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -80,11 +80,11 @@ For improved compatibility with newer clients, servers should add a `redacts` pr
|
|||
to the `content` of `m.room.redaction` events in *older* room versions when serving
|
||||
such events over the Client-Server API.
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
@ -157,7 +157,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users or is not a joined member of the room, reject.
|
||||
users, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
|
|||
|
|
@ -43,11 +43,11 @@ Room version 12 is based upon room version 11 with the following considerations.
|
|||
|
||||
{{% rver-fragment name="v12-event-format" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
@ -141,7 +141,7 @@ The rules are as follows:
|
|||
1. If membership state is `join` or `invite`, allow.
|
||||
2. If the `join_authorised_via_users_server` key in `content`
|
||||
is not a user with sufficient permission to invite other
|
||||
users or is not a joined member of the room, reject.
|
||||
users, reject.
|
||||
3. Otherwise, allow.
|
||||
6. If the `join_rule` is `public`, allow.
|
||||
7. Otherwise, reject.
|
||||
|
|
@ -267,7 +267,7 @@ algorithm found in [room version 2](/rooms/v2) with the following modifications:
|
|||
now starts with an *empty* state map instead of the unconflicted state map.
|
||||
|
||||
2. A new [definition](#definitions) for *conflicted state subgraph* has been added
|
||||
which describes events that are required to authorise events during iterative
|
||||
which describes events that are required to authorize events during iterative
|
||||
auth checks.
|
||||
|
||||
3. To ensure the new conflicted state subgraph is actually referenced, the definition
|
||||
|
|
@ -405,11 +405,11 @@ events: for events *x* and *y*, *x* < *y* if
|
|||
The *iterative auth checks algorithm* takes as input an initial room
|
||||
state and a sorted list of state events, and constructs a new room state
|
||||
by iterating through the event list and applying the state event to the
|
||||
room state if the state event is allowed by the [authorisation
|
||||
rules](/server-server-api#authorisation-rules).
|
||||
If the state event is not allowed by the authorisation rules, then the
|
||||
room state if the state event is allowed by the [authorization
|
||||
rules](/server-server-api#authorization-rules).
|
||||
If the state event is not allowed by the authorization rules, then the
|
||||
event is ignored. If a `(event_type, state_key)` key that is required
|
||||
for checking the authorisation rules is not present in the state, then
|
||||
for checking the authorization rules is not present in the state, then
|
||||
the appropriate state event from the event's `auth_events` is used if
|
||||
the auth event is not rejected.
|
||||
|
||||
|
|
|
|||
|
|
@ -57,9 +57,7 @@ Events in rooms of this version have the following structure:
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v1-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -87,9 +87,7 @@ The complete structure of a event in a v3 room is shown below.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v=3 %}} `m.room.redaction` events are subject to auth rules in
|
||||
|
|
|
|||
|
|
@ -76,9 +76,7 @@ the changes in this room version.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -58,9 +58,7 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
{{% rver-fragment name="v1-floaty-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v3-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ version: 6
|
|||
---
|
||||
|
||||
This room version builds on [version 5](/rooms/v5) while changing various
|
||||
authorisation rules performed on events.
|
||||
authorization rules performed on events.
|
||||
|
||||
## Client considerations
|
||||
|
||||
|
|
@ -42,25 +42,24 @@ in [room version 5](/rooms/v5).
|
|||
### Event format
|
||||
|
||||
{{% added-in v=6 %}} Through enforcement of [Canonical JSON](#canonical-json),
|
||||
the `depth` limit has been reduced in this room version, and numeric values may
|
||||
no longer be formatted as floats.
|
||||
the `depth` limit has been reduced in this room version.
|
||||
|
||||
{{% rver-fragment name="v6-event-format" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=6 %}} Rule 4, which related specifically to events
|
||||
of type `m.room.aliases`, is removed. `m.room.aliases` events must still pass
|
||||
authorisation checks relating to state events.
|
||||
authorization checks relating to state events.
|
||||
|
||||
{{% added-in v=6 %}} Additionally, the authorisation rules for events of
|
||||
{{% added-in v=6 %}} Additionally, the authorization rules for events of
|
||||
type `m.room.power_levels` now include a `notifications` property under
|
||||
`content`. This updates rules 10.4 and 10.5 (now 9.4 and 9.5), which checked
|
||||
the `events` property.
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -27,18 +27,18 @@ regarding client considerations is the resource that Client-Server API
|
|||
use cases should reference.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
Room version 7 adds new authorisation rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorisation rule changes,
|
||||
Room version 7 adds new authorization rules for events to support knocking.
|
||||
[Room version 6](/rooms/v6) has details of other authorization rule changes,
|
||||
as do the versions v6 is based upon.
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=7 %}} For checks performed upon `m.room.member` events, a
|
||||
new point for `membership=knock` is added.
|
||||
|
||||
Events must be signed by the server denoted by the `sender` property.
|
||||
|
||||
The types of state events that affect authorisation are:
|
||||
The types of state events that affect authorization are:
|
||||
|
||||
- [`m.room.create`](/client-server-api#mroomcreate)
|
||||
- [`m.room.member`](/client-server-api#mroommember)
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ Room version 8 adds a new join rule to allow members of a room to join another
|
|||
room without invite. Otherwise, the room version inherits all properties of
|
||||
[Room version 7](/rooms/v7).
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% added-in v=8 %}} For checks performed upon `m.room.member` events, new
|
||||
points for handling `content.join_authorised_via_users_server` are added (Rule 4.2
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ completeness.
|
|||
|
||||
{{% rver-fragment name="v1-stringy-power-levels" %}}
|
||||
|
||||
### Authorisation rules
|
||||
### Authorization rules
|
||||
|
||||
{{% rver-fragment name="v8-auth-rules" %}}
|
||||
|
||||
|
|
|
|||
|
|
@ -2,46 +2,49 @@
|
|||
title: "Server-Server API"
|
||||
weight: 20
|
||||
type: docs
|
||||
description: |
|
||||
Matrix homeservers use the Federation APIs (also known as server-server APIs)
|
||||
to communicate with each other. Homeservers use these APIs to push messages in
|
||||
real-time, retrieve historic messages, and query profile or presence
|
||||
information about users on other servers. The APIs are implemented over HTTPS,
|
||||
with authentication provided by public key signatures both at the TLS
|
||||
transport layer and in HTTP `Authorization` headers.
|
||||
|
||||
There are three main kinds of communication that occur between
|
||||
homeservers:
|
||||
|
||||
Persistent Data Units (PDUs):
|
||||
These events are broadcast from one homeserver to any others that have
|
||||
joined the same room (identified by Room ID). They are persisted in
|
||||
long-term storage and record the history of messages and state for a
|
||||
room.
|
||||
|
||||
Like email, it is the responsibility of the originating server of a PDU
|
||||
to deliver that event to its recipient servers. However PDUs are signed
|
||||
using the originating server's private key so that it is possible to
|
||||
deliver them through third-party servers.
|
||||
|
||||
Ephemeral Data Units (EDUs):
|
||||
These events are pushed between pairs of homeservers. They are not
|
||||
persisted and are not part of the history of a room, nor does the
|
||||
receiving homeserver have to reply to them.
|
||||
|
||||
Queries:
|
||||
These are single request/response interactions between a given pair of
|
||||
servers, initiated by one side sending an HTTPS GET request to obtain
|
||||
some information, and responded by the other. They are not persisted and
|
||||
contain no long-term significant history. They simply request a snapshot
|
||||
state at the instant the query is made.
|
||||
|
||||
EDUs and PDUs are further wrapped in an envelope called a Transaction,
|
||||
which is transferred from the origin to the destination homeserver using
|
||||
an HTTPS PUT request.
|
||||
|
||||
---
|
||||
|
||||
Matrix homeservers use the Federation APIs (also known as server-server
|
||||
APIs) to communicate with each other. Homeservers use these APIs to push
|
||||
messages to each other in real-time, to retrieve historic messages from
|
||||
each other, and to query profile and presence information about users on
|
||||
each other's servers.
|
||||
|
||||
The APIs are implemented using HTTPS requests between each of the
|
||||
servers. These HTTPS requests are strongly authenticated using public
|
||||
key signatures at the TLS transport layer and using public key
|
||||
signatures in HTTP Authorization headers at the HTTP layer.
|
||||
|
||||
There are three main kinds of communication that occur between
|
||||
homeservers:
|
||||
|
||||
Persistent Data Units (PDUs):
|
||||
These events are broadcast from one homeserver to any others that have
|
||||
joined the same room (identified by Room ID). They are persisted in
|
||||
long-term storage and record the history of messages and state for a
|
||||
room.
|
||||
|
||||
Like email, it is the responsibility of the originating server of a PDU
|
||||
to deliver that event to its recipient servers. However PDUs are signed
|
||||
using the originating server's private key so that it is possible to
|
||||
deliver them through third-party servers.
|
||||
|
||||
Ephemeral Data Units (EDUs):
|
||||
These events are pushed between pairs of homeservers. They are not
|
||||
persisted and are not part of the history of a room, nor does the
|
||||
receiving homeserver have to reply to them.
|
||||
|
||||
Queries:
|
||||
These are single request/response interactions between a given pair of
|
||||
servers, initiated by one side sending an HTTPS GET request to obtain
|
||||
some information, and responded by the other. They are not persisted and
|
||||
contain no long-term significant history. They simply request a snapshot
|
||||
state at the instant the query is made.
|
||||
|
||||
EDUs and PDUs are further wrapped in an envelope called a Transaction,
|
||||
which is transferred from the origin to the destination homeserver using
|
||||
an HTTPS PUT request.
|
||||
|
||||
## API standards
|
||||
|
||||
The mandatory baseline for server-server communication in Matrix is
|
||||
|
|
@ -277,16 +280,16 @@ queried from multiple servers to mitigate against DNS spoofing.
|
|||
|
||||
Every HTTP request made by a homeserver is authenticated using public
|
||||
key digital signatures. The request method, target and body are signed
|
||||
by wrapping them in a JSON object and signing it using the [JSON signing
|
||||
algorithm](/appendices#signing-json). The resulting signatures are added
|
||||
as an `Authorization` header with an auth scheme of `X-Matrix`. Note that
|
||||
the target field should include the full path starting with `/_matrix/...`,
|
||||
including the `?` and any query parameters if present, but should not
|
||||
include the leading `https:`, nor the destination server's hostname.
|
||||
by wrapping them in a JSON object and signing it using the JSON signing
|
||||
algorithm. The resulting signatures are added as an Authorization header
|
||||
with an auth scheme of `X-Matrix`. Note that the target field should
|
||||
include the full path starting with `/_matrix/...`, including the `?`
|
||||
and any query parameters if present, but should not include the leading
|
||||
`https:`, nor the destination server's hostname.
|
||||
|
||||
Step 1 sign JSON:
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
{
|
||||
"method": "POST",
|
||||
"uri": "/target",
|
||||
|
|
@ -307,7 +310,7 @@ section](#resolving-server-names) above do not affect these - the server
|
|||
names from before delegation would take place are used. This same
|
||||
condition applies throughout the request signing process.
|
||||
|
||||
Step 2 add `Authorization` header:
|
||||
Step 2 add Authorization header:
|
||||
|
||||
POST /target HTTP/1.1
|
||||
Authorization: X-Matrix origin="origin.hs.example.com",destination="destination.hs.example.com",key="ed25519:key1",sig="ABCDEF..."
|
||||
|
|
@ -346,9 +349,9 @@ def authorization_headers(origin_name, origin_signing_key,
|
|||
return ("Authorization", authorization_headers[0])
|
||||
```
|
||||
|
||||
The format of the `Authorization` header is given in
|
||||
The format of the Authorization header is given in
|
||||
[Section 11.4 of RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#section-11.4). In
|
||||
summary, the header begins with authorisation scheme `X-Matrix`, followed by one
|
||||
summary, the header begins with authorization scheme `X-Matrix`, followed by one
|
||||
or more spaces, followed by a comma-separated list of parameters written as
|
||||
name=value pairs. Zero or more spaces and tabs around each comma are allowed.
|
||||
The names are case insensitive and order does not matter. The
|
||||
|
|
@ -369,7 +372,7 @@ For compatibility with older servers, the sender should
|
|||
For compatibility with older servers, the recipient should allow colons to be
|
||||
included in values without requiring the value to be enclosed in quotes.
|
||||
|
||||
The authorisation parameters to include are:
|
||||
The authorization parameters to include are:
|
||||
|
||||
- `origin`: the server name of the sending server. This is the same as the
|
||||
`origin` field from JSON described in step 1.
|
||||
|
|
@ -378,8 +381,8 @@ The authorisation parameters to include are:
|
|||
in step 1. For compatibility with older servers, recipients should accept
|
||||
requests without this parameter, but MUST always send it. If this property
|
||||
is included, but the value does not match the receiving server's name, the
|
||||
receiving server must deny the request with an HTTP status code `401
|
||||
Unauthorized`.
|
||||
receiving server must deny the request with an HTTP status code 401
|
||||
Unauthorized.
|
||||
- `key`: the ID, including the algorithm name, of the sending server's key used
|
||||
to sign the request.
|
||||
- `signature`: the signature of the JSON as calculated in step 1.
|
||||
|
|
@ -467,14 +470,11 @@ server must ensure that the event:
|
|||
2. Passes signature checks, otherwise it is dropped.
|
||||
3. Passes hash checks, otherwise it is redacted before being processed
|
||||
further.
|
||||
4. Passes authorisation rules based on the event's auth events,
|
||||
4. Passes authorization rules based on the event's auth events,
|
||||
otherwise it is rejected.
|
||||
5. Passes authorisation rules based on the state before the event,
|
||||
5. Passes authorization rules based on the state before the event,
|
||||
otherwise it is rejected.
|
||||
6. Passes authorisation rules based on the current state of the room,
|
||||
otherwise it is "soft failed".
|
||||
7. {{% added-in v="1.18" %}} Is [validated](#validating-policy-server-signatures)
|
||||
by the Policy Server, if the room is [using a Policy Server](#determining-if-a-policy-server-is-enabled-in-a-room),
|
||||
6. Passes authorization rules based on the current state of the room,
|
||||
otherwise it is "soft failed".
|
||||
|
||||
Further details of these checks, and how to handle failures, are
|
||||
|
|
@ -516,9 +516,9 @@ and must never populate the default power levels in a room as string values.
|
|||
See the [room version specification](/rooms) for more information.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
#### Authorisation rules
|
||||
#### Authorization rules
|
||||
|
||||
The rules governing whether an event is authorised depends on a set of
|
||||
The rules governing whether an event is authorized depends on a set of
|
||||
state. A given event is checked multiple times against different sets of
|
||||
state, as specified above. Each room version can have a different
|
||||
algorithm for how the rules work, and which rules are applied. For more
|
||||
|
|
@ -692,14 +692,9 @@ then any new event `D'` will not reference `C`:
|
|||
|
|
||||
D'
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.18" %}}
|
||||
Events can also be soft failed if they fail [Policy Server checks](#validating-policy-server-signatures).
|
||||
{{% /boxes/note %}}
|
||||
#### Retrieving event authorization information
|
||||
|
||||
#### Retrieving event authorisation information
|
||||
|
||||
The homeserver may be missing event authorisation information, or wish
|
||||
The homeserver may be missing event authorization information, or wish
|
||||
to check with other servers to ensure it is receiving the correct auth
|
||||
chain. These APIs give the homeserver an avenue for getting the
|
||||
information it needs.
|
||||
|
|
@ -827,7 +822,7 @@ ResidentServer->JoiningServer: send_join response
|
|||
JoiningServer->Client: join response
|
||||
-->
|
||||
|
||||
```nohighlight
|
||||
```
|
||||
+---------+ +---------------+ +-----------------+ +-----------------+
|
||||
| Client | | JoiningServer | | DirectoryServer | | ResidentServer |
|
||||
+---------+ +---------------+ +-----------------+ +-----------------+
|
||||
|
|
@ -876,10 +871,8 @@ selecting a resident from the candidate list, and using the
|
|||
enough information for the joining server to fill in the event.
|
||||
|
||||
The joining server is expected to add or replace the `origin`,
|
||||
`origin_server_ts`, and `event_id` on the templated event received by the
|
||||
resident server. The joining server MUST also verify that the `type`, `room_id`,
|
||||
`sender`, `state_key` and `content.membership` fields have the expected values.
|
||||
This event is then signed by the joining server.
|
||||
`origin_server_ts`, and `event_id` on the templated event received by
|
||||
the resident server. This event is then signed by the joining server.
|
||||
|
||||
To complete the join handshake, the joining server submits this new event
|
||||
to the resident server it used for `GET /make_join`, using the `PUT /send_join`
|
||||
|
|
@ -1285,171 +1278,6 @@ endpoint MUST be protected as follows:
|
|||
room ID MUST be ignored if the sending server is denied access to
|
||||
the room identified by that ID.
|
||||
|
||||
The following endpoints MAY be protected:
|
||||
|
||||
- [`/_matrix/policy/v1/sign`](#post_matrixpolicyv1sign) - {{< added-in v="1.18" >}}
|
||||
Protected if the server is tracking the DAG and chooses to enforce the ACL.
|
||||
|
||||
|
||||
## Policy Servers
|
||||
|
||||
{{% added-in v="1.18" %}}
|
||||
|
||||
Policy Servers are an available tool for rooms to add proactive protections. Rooms
|
||||
which use a Policy Server (PS) can prevent unwanted events from reaching users. Rooms
|
||||
are not required to use a Policy Server, and can disable it any time after enabling
|
||||
it.
|
||||
|
||||
For a homeserver to be a Policy Server, it MUST implement the following functionality
|
||||
of the Server-Server API:
|
||||
|
||||
* [Normal server name resolution](#resolving-server-names).
|
||||
* [Publishing a signing key](#publishing-keys).
|
||||
* [Request authentication](#authentication).
|
||||
* Being able to [make and send join requests](#joining-rooms).
|
||||
* Receiving and processing [`POST /_matrix/policy/v1/sign`](#post_matrixpolicyv1sign)
|
||||
requests.
|
||||
|
||||
All other functionality and endpoints are optional for a Policy Server.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Though a Policy Server is not required to implement the full Server-Server API
|
||||
surface, some functionality may be desirable to implement anyway:
|
||||
|
||||
* Receiving [invites](#inviting-to-a-room) can make it easier to add the Policy
|
||||
Server to a room.
|
||||
* Receiving [transactions](#transactions) is recommended to avoid remote servers
|
||||
flagging the Policy Server as "offline", even if the contents are discarded.
|
||||
* Receiving [device lookups](#get_matrixfederationv1userdevicesuserid) can also
|
||||
help reduce remote servers flagging the Policy Server as "offline".
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
Policy Servers are *not* required to track the DAG for a room. Policy Servers
|
||||
might be optimized for content moderation and therefore do not need knowledge of
|
||||
the DAG.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
### Determining if a Policy Server is enabled in a room
|
||||
|
||||
For a room to be considered as "using" a Policy Server, *all* of the following
|
||||
conditions MUST be true:
|
||||
|
||||
* The *current state* for the room has a valid [`m.room.policy`](/client-server-api/#mroompolicy)
|
||||
state event with empty state key. Valid means `content` contains at least:
|
||||
* A string value for `via`.
|
||||
* An object value for `public_keys` containing at least a string value for
|
||||
`ed25519`.
|
||||
* The server name denoted by the `m.room.policy` state event's `via` has at least
|
||||
one joined user in the room in *current state*. The user does not need any
|
||||
special permissions or power levels in the room.
|
||||
|
||||
If a room has enabled a Policy Server, *all* servers in that room MUST [ask that
|
||||
Policy Server](#asking-for-a-policy-server-signature-on-an-event) for a signature
|
||||
before sending an event. If the Policy Server refuses to sign the event being
|
||||
sent, servers SHOULD fail to send that event as per the [validation rules](#validating-policy-server-signatures).
|
||||
|
||||
{{% boxes/note %}}
|
||||
"Current state" shares the same definition as [soft failure](#soft-failure).
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
Policy Servers MUST have at least one joined user in the room to give the Policy
|
||||
Server agency in whether it serves that role for the room. Otherwise, a room
|
||||
would be able to force a Policy Server to participate and then overwhelm it.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
### Validating Policy Server signatures
|
||||
|
||||
Policy Servers use signatures to indicate whether an event was checked and is
|
||||
recommended for inclusion in a room. The Policy Server's recommendation does *not*
|
||||
affect the authorization rules for an event, but does affect whether homeservers
|
||||
[soft fail](#soft-failure) or refuse to actually go forward with sending an event.
|
||||
|
||||
If a room has disabled (or never enabled) a Policy Server, events are recommended
|
||||
for inclusion and subject to normal authorization rules.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Because the Policy Server is not asked to sign [`m.room.policy`](/client-server-api/#mroompolicy)
|
||||
state events with empty string `state_key`s, those events will not have a Policy
|
||||
Server signature. Those events are by default recommended for inclusion and still
|
||||
subject to normal authorization rules.
|
||||
|
||||
All other events SHOULD have a valid Policy Server signature when a Policy Server
|
||||
is enabled in the room, including non-state `m.room.policy` events and `m.room.policy`
|
||||
state events with non-empty `state_key`s. This also includes state events like
|
||||
membership and power level changes.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
If a room has enabled a Policy Server, the Policy Server's signature appears
|
||||
alongside the normal [event signatures](#signing-events), though uses a public
|
||||
key from the room's `m.room.policy` state event.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Currently, only Ed25519 keys are supported by homeservers. The Key ID for the
|
||||
`ed25519` key in `m.room.policy` is *always* `ed25519:policy_server`.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
By embedding the Policy Server's public key into room state, the Policy Server
|
||||
does not need to be online or have its keys cached by a notary in order to validate
|
||||
an event.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/warning %}}
|
||||
The Policy Server's [published signing key](#publishing-keys) SHOULD NOT be the
|
||||
same key contained in the `m.room.policy` state event. This is to keep "can send
|
||||
federation traffic" and "can recommend events for inclusion" separate, and to
|
||||
allow rooms to revoke the Policy Server's key without cooperation of the Policy
|
||||
Server.
|
||||
|
||||
If the Policy Server is acting as a normal homeserver and attempting to send an
|
||||
event, that event will require a signature from the server's published signing
|
||||
key alongside the Policy Server signature described in this section.
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
If the Policy Server's signature is valid, the event is recommended for inclusion
|
||||
in the room, and is still subject to normal authorization rules.
|
||||
|
||||
If the Policy Server's signature is invalid or missing, the homeserver SHOULD
|
||||
[ask for a new signature](#asking-for-a-policy-server-signature-on-an-event). If
|
||||
the event still does not have a valid Policy Server signature, the event is *not*
|
||||
recommended for inclusion and the homeserver SHOULD:
|
||||
|
||||
* If applicable, reject the Client-Server API request which was generating the
|
||||
event. If the Policy Server returned an error, that error SHOULD be provided
|
||||
to the client verbatim. The event the client was attempting to send SHOULD be
|
||||
discarded and not processed/sent any further.
|
||||
* If the event was received over federation or the homeserver sends a local client's
|
||||
event anyway, [soft fail](#soft-failure) the event.
|
||||
|
||||
{{% boxes/note %}}
|
||||
For clarity, an event which lacks a valid Policy Server signature is still subject
|
||||
to normal authorization rules.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
{{% boxes/note %}}
|
||||
When a Policy Server's signature is invalid, a new one is requested because the
|
||||
Policy Server's key may have rotated between the event being signed and the event
|
||||
being checked.
|
||||
|
||||
Because the key is contained in the `m.room.policy` state event, if the Policy
|
||||
Server rotates its key without the room also updating the state event, events
|
||||
will be flagged as not recommended for inclusion. This is expected behaviour.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
### Asking for a Policy Server signature on an event
|
||||
|
||||
Per [above](#determining-if-a-policy-server-is-enabled-in-a-room), if a room has
|
||||
a Policy Server enabled, *all* servers in the room MUST ask the Policy Server to
|
||||
sign their events before sending them to clients and servers.
|
||||
|
||||
After asking for a signature, homeservers SHOULD [validate](#validating-policy-server-signatures)
|
||||
the returned signature before continuing to send events. If the Policy Server
|
||||
returns an error, the event SHOULD NOT be sent to clients and servers.
|
||||
|
||||
{{% http-api spec="server-server" api="room_policy" %}}
|
||||
|
||||
## Signing Events
|
||||
|
||||
Signing events is complicated by the fact that servers can choose to
|
||||
|
|
@ -1473,52 +1301,34 @@ The signature is then copied back to the original event object.
|
|||
For an example of a signed event, see the [room version
|
||||
specification](/rooms).
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.18" %}}
|
||||
Events sent in rooms with [Policy Servers](#policy-servers) MUST [ask](#asking-for-a-policy-server-signature-on-an-event)
|
||||
the Policy Server for a signature too.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
### Validating hashes and signatures on received events
|
||||
|
||||
When a server receives an event over federation from another server, the
|
||||
receiving server should check the hashes and signatures on that event.
|
||||
|
||||
First the signatures are checked. The event is redacted following the
|
||||
[redaction algorithm](/client-server-api#redactions), and
|
||||
the resultant object is checked for signatures from the originating
|
||||
First the signature is checked. The event is redacted following the
|
||||
[redaction
|
||||
algorithm](/client-server-api#redactions), and
|
||||
the resultant object is checked for a signature from the originating
|
||||
server, following the algorithm described in [Checking for a
|
||||
signature](/appendices#checking-for-a-signature). Note that this
|
||||
step should succeed whether we have been sent the full event or a
|
||||
redacted copy.
|
||||
|
||||
For room versions 3 and later, unless the event is a 3rd party invite, only the
|
||||
signature(s) from the originating server (the server the `sender` belongs to)
|
||||
are required for verification. Room versions 1 and 2 also require that a
|
||||
signature is present from the domain in the `event_id`, if it differs from the
|
||||
originating server. If a signature is from an unknown or expired key, it is
|
||||
skipped.
|
||||
The signatures expected on an event are:
|
||||
|
||||
If the event is a 3rd party invite, the sender must already match the 3rd party
|
||||
invite, and the server which actually sends the event may be a different
|
||||
server.
|
||||
- The `sender`'s server, unless the invite was created as a result of
|
||||
3rd party invite. The sender must already match the 3rd party
|
||||
invite, and the server which actually sends the event may be a
|
||||
different server.
|
||||
- For room versions 1 and 2, the server which created the `event_id`.
|
||||
Other room versions do not track the `event_id` over federation and
|
||||
therefore do not need a signature from those servers.
|
||||
|
||||
Only signatures from known server keys are validated here. Any unknown keys are ignored.
|
||||
In particular, the [policy server key](#validating-policy-server-signatures) is not
|
||||
expected to be published and therefore should be skipped at this stage.
|
||||
Additionally, any keys that are known to have expired prior to the event's
|
||||
`origin_server_ts` are ignored.
|
||||
|
||||
{{% boxes/note %}}
|
||||
{{% added-in v="1.18" %}}
|
||||
Events sent in rooms with [Policy Servers](#policy-servers) have [additional](#validating-policy-server-signatures)
|
||||
signature validation requirements.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
If all signatures from known unexpired keys from the originating server(s) are
|
||||
found to be valid, the expected content hash is calculated as described below.
|
||||
The content hash in the `hashes` property of the received event is base64-decoded,
|
||||
and the two are compared for equality.
|
||||
If the signature is found to be valid, the expected content hash is
|
||||
calculated as described below. The content hash in the `hashes` property
|
||||
of the received event is base64-decoded, and the two are compared for
|
||||
equality.
|
||||
|
||||
If the hash check fails, then it is assumed that this is because we have
|
||||
only been given a redacted version of the event. To enforce this, the
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -83,7 +83,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to modify this user's account
|
||||
The access token provided is not authorized to modify this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -126,7 +126,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -151,7 +151,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to retrieve this user's account
|
||||
The access token provided is not authorized to retrieve this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -196,7 +196,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to set account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -253,7 +253,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to modify this user's account
|
||||
The access token provided is not authorized to modify this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
@ -296,7 +296,7 @@ paths:
|
|||
required: true
|
||||
description: |-
|
||||
The ID of the user to get account data for. The access token must be
|
||||
authorised to make requests for this user ID.
|
||||
authorized to make requests for this user ID.
|
||||
example: "@alice:example.com"
|
||||
schema:
|
||||
type: string
|
||||
|
|
@ -341,7 +341,7 @@ paths:
|
|||
}
|
||||
"403":
|
||||
description: |-
|
||||
The access token provided is not authorised to retrieve this user's account
|
||||
The access token provided is not authorized to retrieve this user's account
|
||||
data. Errcode: `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
|
|
|
|||
|
|
@ -35,14 +35,6 @@ paths:
|
|||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
{{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients)
|
||||
MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management),
|
||||
if available, and MAY use the `action=org.matrix.account_deactivate`
|
||||
parameter.
|
||||
{{% /boxes/warning %}}
|
||||
security:
|
||||
- {}
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ info:
|
|||
title: Matrix Client-Server Administration API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
"/v3/admin/whois/{userId}":
|
||||
"/admin/whois/{userId}":
|
||||
get:
|
||||
summary: Gets information about a particular user.
|
||||
description: |-
|
||||
|
|
@ -107,391 +107,6 @@ paths:
|
|||
}
|
||||
tags:
|
||||
- Server administration
|
||||
"/v1/admin/suspend/{userId}":
|
||||
get:
|
||||
summary: Gets information about the suspended status of a particular user.
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
description: |-
|
||||
Gets information about the suspended status of a particular server-local user.
|
||||
|
||||
The user calling this endpoint MUST be a server admin.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: getAdminSuspendUser
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user to look up.
|
||||
required: true
|
||||
example: "@peter:rabbit.rocks"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
|
||||
responses:
|
||||
"200":
|
||||
description: The lookup was successful.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
suspended:
|
||||
type: boolean
|
||||
description: Whether the target account is suspended.
|
||||
example: true
|
||||
required:
|
||||
- suspended
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"suspended": true,
|
||||
}
|
||||
"400":
|
||||
description: |-
|
||||
The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "User does not belong to the local server."
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The requesting user is not a server administrator, or the target user is another
|
||||
administrator. The errcode is `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Requesting user is not a server administrator."
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "User not found."
|
||||
}
|
||||
tags:
|
||||
- Server administration
|
||||
put:
|
||||
summary: Set the suspended status of a particular user.
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
description: |-
|
||||
Sets the suspended status of a particular server-local user.
|
||||
|
||||
The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
|
||||
is allowed to suspend other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
|
||||
endpoint prior to using this endpoint.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: setAdminSuspendUser
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user to change the suspended status of.
|
||||
required: true
|
||||
example: "@peter:rabbit.rocks"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
suspended:
|
||||
type: boolean
|
||||
description: Whether to suspend the target account.
|
||||
example: true
|
||||
required:
|
||||
- suspended
|
||||
examples:
|
||||
request:
|
||||
value: {
|
||||
"suspended": true,
|
||||
}
|
||||
required: true
|
||||
|
||||
responses:
|
||||
"200":
|
||||
description: The action was successful.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
suspended:
|
||||
type: boolean
|
||||
description: Whether the target account is suspended.
|
||||
example: true
|
||||
required:
|
||||
- suspended
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"suspended": true,
|
||||
}
|
||||
"400":
|
||||
description: |-
|
||||
The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "User does not belong to the local server."
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The requesting user is not a server administrator, is trying to suspend their own
|
||||
account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Requesting user is not a server administrator."
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "User not found."
|
||||
}
|
||||
tags:
|
||||
- Server administration
|
||||
"/v1/admin/lock/{userId}":
|
||||
get:
|
||||
summary: Gets information about the locked status of a particular user.
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
description: |-
|
||||
Gets information about the locked status of a particular server-local user.
|
||||
|
||||
The user calling this endpoint MUST be a server admin.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: getAdminLockUser
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user to look up.
|
||||
required: true
|
||||
example: "@peter:rabbit.rocks"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
|
||||
responses:
|
||||
"200":
|
||||
description: The lookup was successful.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
locked:
|
||||
type: boolean
|
||||
description: Whether the target account is locked.
|
||||
required:
|
||||
- locked
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"locked": true,
|
||||
}
|
||||
"400":
|
||||
description: |-
|
||||
The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "User does not belong to the local server."
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The requesting user is not a server administrator, or the target user is another
|
||||
administrator. The errcode is `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Requesting user is not a server administrator."
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "User not found."
|
||||
}
|
||||
tags:
|
||||
- Server administration
|
||||
put:
|
||||
summary: Set the locked status of a particular user.
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
description: |-
|
||||
Sets the locked status of a particular server-local user.
|
||||
|
||||
The user calling this endpoint MUST be a server admin. The client SHOULD check that the user
|
||||
is allowed to lock other users at the [`GET /capabilities`](/client-server-api/#get_matrixclientv3capabilities)
|
||||
endpoint prior to using this endpoint.
|
||||
|
||||
In order to prevent user enumeration, servers MUST ensure that authorisation is checked
|
||||
prior to trying to do account lookups.
|
||||
operationId: setAdminLockUser
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
- accessTokenBearer: []
|
||||
parameters:
|
||||
- in: path
|
||||
name: userId
|
||||
description: The user to change the locked status of.
|
||||
required: true
|
||||
example: "@peter:rabbit.rocks"
|
||||
schema:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
locked:
|
||||
type: boolean
|
||||
description: Whether to lock the target account.
|
||||
example: true
|
||||
required:
|
||||
- locked
|
||||
examples:
|
||||
request:
|
||||
value: {
|
||||
"locked": true,
|
||||
}
|
||||
required: true
|
||||
|
||||
responses:
|
||||
"200":
|
||||
description: The action was successful.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
locked:
|
||||
type: boolean
|
||||
description: Whether the target account is locked.
|
||||
example: true
|
||||
required:
|
||||
- locked
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"locked": true,
|
||||
}
|
||||
"400":
|
||||
description: |-
|
||||
The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_INVALID_PARAM",
|
||||
"error": "User does not belong to the local server."
|
||||
}
|
||||
"403":
|
||||
description: |-
|
||||
The requesting user is not a server administrator, is trying to lock their own
|
||||
account, or the target user is another administrator. The errcode is `M_FORBIDDEN`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Requesting user is not a server administrator."
|
||||
}
|
||||
"404":
|
||||
description: |-
|
||||
The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "User not found."
|
||||
}
|
||||
tags:
|
||||
- Server administration
|
||||
servers:
|
||||
- url: "{protocol}://{hostname}{basePath}"
|
||||
variables:
|
||||
|
|
@ -503,7 +118,7 @@ servers:
|
|||
hostname:
|
||||
default: localhost:8008
|
||||
basePath:
|
||||
default: /_matrix/client
|
||||
default: /_matrix/client/v3
|
||||
components:
|
||||
securitySchemes:
|
||||
accessTokenQuery:
|
||||
|
|
|
|||
|
|
@ -99,10 +99,6 @@ paths:
|
|||
has been removed, making this endpoint behave as though it was `false`.
|
||||
This results in this endpoint being an equivalent to `/3pid/bind` rather
|
||||
than dual-purpose.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
|
||||
to determine if this endpoint is available.
|
||||
operationId: post3PIDs
|
||||
deprecated: true
|
||||
security:
|
||||
|
|
@ -206,10 +202,6 @@ paths:
|
|||
Homeservers should prevent the caller from adding a 3PID to their account if it has
|
||||
already been added to another user's account on the homeserver.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
|
||||
to determine if this endpoint is available.
|
||||
|
||||
{{% boxes/warning %}}
|
||||
Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
|
|
@ -339,10 +331,6 @@ paths:
|
|||
Unlike other endpoints, this endpoint does not take an `id_access_token`
|
||||
parameter because the homeserver is expected to sign the request to the
|
||||
identity server instead.
|
||||
|
||||
This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
|
||||
Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
|
||||
to determine if this endpoint is available.
|
||||
operationId: delete3pidFromAccount
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
|
|||
|
|
@ -379,8 +379,7 @@ paths:
|
|||
description: |-
|
||||
The OpenGraph data for the URL, which may be empty. Some values are
|
||||
replaced with matrix equivalents if they are provided in the response.
|
||||
The differences from the [OpenGraph protocol](https://ogp.me/) are
|
||||
described here.
|
||||
The differences from the OpenGraph protocol are described here.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -395,9 +394,6 @@ paths:
|
|||
format: uri
|
||||
description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
|
||||
the image. Omitted if there is no image.
|
||||
additionalProperties:
|
||||
description: |-
|
||||
Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
|
|
|
|||
|
|
@ -50,12 +50,6 @@ paths:
|
|||
m.change_password:
|
||||
$ref: '#/components/schemas/booleanCapability'
|
||||
description: Capability to indicate if the user can change their password.
|
||||
m.forget_forced_upon_leave:
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
$ref: '#/components/schemas/booleanCapability'
|
||||
description: |-
|
||||
Capability to indicate if the server automatically forgets rooms once the user
|
||||
leaves.
|
||||
m.room_versions:
|
||||
type: object
|
||||
description: The room versions the server supports.
|
||||
|
|
@ -147,34 +141,6 @@ paths:
|
|||
example: true
|
||||
required:
|
||||
- enabled
|
||||
m.account_moderation:
|
||||
x-addedInMatrixVersion: "1.18"
|
||||
type: object
|
||||
title: AccountModerationCapability
|
||||
description: |-
|
||||
Capability to indicate if the user can perform account moderation actions
|
||||
via [server administration](/client-server-api/#server-administration)
|
||||
endpoints.
|
||||
|
||||
This property should be omitted altogether if `suspend` and `lock` would
|
||||
be `false`.
|
||||
properties:
|
||||
suspend:
|
||||
type: boolean
|
||||
description: |-
|
||||
`true` if the user can suspend a user via [`PUT /admin/suspend/{userId}`](/client-server-api/#put_matrixclientv1adminsuspenduserid),
|
||||
`false` otherwise.
|
||||
|
||||
Defaults to `false`.
|
||||
example: true
|
||||
lock:
|
||||
type: boolean
|
||||
description: |-
|
||||
`true` if the user can lock a user via [`PUT /admin/lock/{userId}`](/client-server-api/#put_matrixclientv1adminlockuserid),
|
||||
`false` otherwise.
|
||||
|
||||
Defaults to `false`.
|
||||
example: true
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
|
|
|
|||
|
|
@ -605,8 +605,7 @@ paths:
|
|||
description: |-
|
||||
The OpenGraph data for the URL, which may be empty. Some values are
|
||||
replaced with matrix equivalents if they are provided in the response.
|
||||
The differences from the [OpenGraph](https://ogp.me/) protocol are
|
||||
described here.
|
||||
The differences from the OpenGraph protocol are described here.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -621,9 +620,6 @@ paths:
|
|||
format: uri
|
||||
description: An [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) to
|
||||
the image. Omitted if there is no image.
|
||||
additionalProperties:
|
||||
description: |-
|
||||
Additional properties as per the [OpenGraph](https://ogp.me/) protocol.
|
||||
examples:
|
||||
response:
|
||||
value: {
|
||||
|
|
|
|||
|
|
@ -250,6 +250,7 @@ paths:
|
|||
}
|
||||
"400":
|
||||
description: |-
|
||||
|
||||
The request is invalid. A meaningful `errcode` and description
|
||||
error text will be returned. Example reasons for rejection include:
|
||||
|
||||
|
|
@ -273,17 +274,6 @@ paths:
|
|||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
"403":
|
||||
description: |-
|
||||
Creating the room is not allowed.
|
||||
|
||||
{{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
|
||||
indicate that one of the homeservers of the invited users rejected
|
||||
the invite due to [invite blocking](/client-server-api/#invite-permission).
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: definitions/errors/error.yaml
|
||||
tags:
|
||||
- Room creation
|
||||
servers:
|
||||
|
|
|
|||
|
|
@ -21,20 +21,16 @@ paths:
|
|||
x-addedInMatrixVersion: "1.1"
|
||||
x-changedInMatrixVersion:
|
||||
"1.11": UIA is not always required for this endpoint.
|
||||
"1.17": |-
|
||||
This endpoint no longer requires User-Interactive Authentication when used by an
|
||||
application service.
|
||||
summary: Upload cross-signing keys.
|
||||
description: |-
|
||||
Publishes cross-signing keys for the user.
|
||||
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api),
|
||||
except when used by an application service.
|
||||
This API endpoint uses the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
|
||||
|
||||
User-Interactive Authentication MUST be performed for regular clients, except in these cases:
|
||||
- there is no existing master signing key uploaded to the homeserver, OR
|
||||
- there is an existing master signing key and it exactly matches the
|
||||
master signing key provided in the request body. If there are any additional
|
||||
User-Interactive Authentication MUST be performed, except in these cases:
|
||||
- there is no existing cross-signing master key uploaded to the homeserver, OR
|
||||
- there is an existing cross-signing master key and it exactly matches the
|
||||
cross-signing master key provided in the request body. If there are any additional
|
||||
keys provided in the request (self-signing key, user-signing key) they MUST also
|
||||
match the existing keys stored on the server. In other words, the request contains
|
||||
no new keys.
|
||||
|
|
@ -44,12 +40,10 @@ paths:
|
|||
makes this endpoint idempotent in the case where the response is lost over the network,
|
||||
which would otherwise cause a UIA challenge upon retry.
|
||||
|
||||
{{% boxes/note %}}
|
||||
When this endpoint requires User-Interactive Authentication,
|
||||
it uses the [`m.oauth`](/client-server-api/#oauth-authentication)
|
||||
authentication type if the access token was obtained
|
||||
{{% boxes/warning %}}
|
||||
When this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained
|
||||
via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
|
||||
{{% /boxes/note %}}
|
||||
{{% /boxes/warning %}}
|
||||
operationId: uploadCrossSigningKeys
|
||||
security:
|
||||
- accessTokenQuery: []
|
||||
|
|
@ -61,22 +55,22 @@ paths:
|
|||
type: object
|
||||
properties:
|
||||
master_key:
|
||||
description: Optional. The user\'s master signing key.
|
||||
description: Optional. The user\'s master key.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
self_signing_key:
|
||||
description: |-
|
||||
Optional. The user\'s self-signing key. Must be signed by
|
||||
the accompanying master signing key, or by the user\'s most recently
|
||||
uploaded master signing key if no master signing key is included in the
|
||||
the accompanying master key, or by the user\'s most recently
|
||||
uploaded master key if no master key is included in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
user_signing_key:
|
||||
description: |-
|
||||
Optional. The user\'s user-signing key. Must be signed by
|
||||
the accompanying master signing key, or by the user\'s most recently
|
||||
uploaded master signing key if no master signing key is included in the
|
||||
the accompanying master key, or by the user\'s most recently
|
||||
uploaded master key if no master key is included in the
|
||||
request.
|
||||
allOf:
|
||||
- $ref: definitions/cross_signing_key.yaml
|
||||
|
|
@ -147,7 +141,7 @@ paths:
|
|||
|
||||
* `M_INVALID_SIGNATURE`: For example, the self-signing or
|
||||
user-signing key had an incorrect signature.
|
||||
* `M_MISSING_PARAM`: No master signing key is available.
|
||||
* `M_MISSING_PARAM`: No master key is available.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -159,7 +153,7 @@ paths:
|
|||
"403":
|
||||
description: |-
|
||||
The public key of one of the keys is the same as one of the user\'s
|
||||
device IDs, or the request is not authorised for any other reason.
|
||||
device IDs, or the request is not authorized for any other reason.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
|
|
@ -24,9 +24,8 @@ allOf:
|
|||
room_id:
|
||||
description: The ID of the room associated with this event.
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
example: '!jEsUZKDJdhlrceRyVU:example.org'
|
||||
|
||||
unsigned:
|
||||
properties:
|
||||
redacted_because:
|
||||
|
|
|
|||
|
|
@ -28,8 +28,6 @@ properties:
|
|||
event_id:
|
||||
description: The globally unique identifier for this event.
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
example: '$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45'
|
||||
type:
|
||||
description: The type of the event.
|
||||
|
|
@ -49,8 +47,6 @@ properties:
|
|||
sender:
|
||||
description: Contains the fully-qualified ID of the user who sent this event.
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
example: "@example:example.org"
|
||||
origin_server_ts:
|
||||
description: |-
|
||||
|
|
@ -105,10 +101,9 @@ properties:
|
|||
type: string
|
||||
prev_content:
|
||||
description: |
|
||||
The `content` of the previous state event that was replaced by this event.
|
||||
This field is generated by the local homeserver, and is only returned if
|
||||
the event is a state event, and the client has permission to see the
|
||||
previous event.
|
||||
The previous `content` for this event. This field is generated
|
||||
by the local homeserver, and is only returned if the event is a state event,
|
||||
and the client has permission to see the previous content.
|
||||
x-changedInMatrixVersion:
|
||||
"1.2": |
|
||||
Previously, this field was specified at the top level of returned
|
||||
|
|
@ -118,13 +113,6 @@ properties:
|
|||
this.
|
||||
title: EventContent
|
||||
type: object
|
||||
replaces_state:
|
||||
description: |
|
||||
The event ID of the state event replaced by this event. This field is generated
|
||||
by the local homeserver, and is only returned if the event is a state event.
|
||||
Unlike `prev_content`, this field is included regardless of history visibility.
|
||||
type: string
|
||||
x-addedInMatrixVersion: "1.19"
|
||||
membership:
|
||||
description: |
|
||||
The room membership of the user making the request, at the time of the event.
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
# limitations under the License.
|
||||
type: object
|
||||
title: CrossSigningKey
|
||||
description: Key used for cross signing
|
||||
description: Cross signing key
|
||||
properties:
|
||||
user_id:
|
||||
type: string
|
||||
|
|
@ -44,8 +44,8 @@ properties:
|
|||
title: Signatures
|
||||
description: |-
|
||||
Signatures of the key, calculated using the process described at [Signing JSON](/appendices/#signing-json).
|
||||
Optional for the master signing key. Other keys must be signed by the
|
||||
user\'s master signing key.
|
||||
Optional for the master key. Other keys must be signed by the
|
||||
user\'s master key.
|
||||
example: {
|
||||
"@alice:example.com": {
|
||||
"ed25519:alice+base64+master+key": "signature+of+key"
|
||||
|
|
|
|||
|
|
@ -23,16 +23,14 @@ properties:
|
|||
not_senders:
|
||||
description: A list of sender IDs to exclude. If this list is absent then no senders
|
||||
are excluded. A matching sender will be excluded even if it is listed in the
|
||||
`senders` filter.
|
||||
`'senders'` filter.
|
||||
items:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
type: array
|
||||
not_types:
|
||||
description: A list of event types to exclude. If this list is absent then no
|
||||
event types are excluded. A matching type will be excluded even if it is listed
|
||||
in the `types` filter. A `*` can be used as a wildcard to match any sequence
|
||||
in the `'types'` filter. A '*' can be used as a wildcard to match any sequence
|
||||
of characters.
|
||||
items:
|
||||
type: string
|
||||
|
|
@ -42,12 +40,10 @@ properties:
|
|||
senders are included.
|
||||
items:
|
||||
type: string
|
||||
format: mx-user-id
|
||||
pattern: "^@"
|
||||
type: array
|
||||
types:
|
||||
description: A list of event types to include. If this list is absent then all
|
||||
event types are included. A `*` can be used as a wildcard to match any sequence
|
||||
event types are included. A `'*'` can be used as a wildcard to match any sequence
|
||||
of characters.
|
||||
items:
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -1,30 +0,0 @@
|
|||
# Copyright 2025 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
title: m.oauth params
|
||||
description: Schema for `m.oauth` entry in the `params` object in a User-Interactive Authentication response.
|
||||
required: ['url']
|
||||
properties:
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
A URL pointing to the homeserver's OAuth account management web UI
|
||||
where the user can approve the action. MUST be a valid URI with scheme
|
||||
`http://` or `https://`, the latter being RECOMMENDED.
|
||||
pattern: "^https?://"
|
||||
example: {
|
||||
"url": "https://example.org/account/reset-cross-signing"
|
||||
}
|
||||
|
|
@ -39,7 +39,5 @@ properties:
|
|||
such.
|
||||
event_id:
|
||||
type: string
|
||||
format: mx-event-id
|
||||
pattern: "^\\$"
|
||||
description: The event ID of the event that this event relates to.
|
||||
required: ['rel_type', 'event_id']
|
||||
|
|
|
|||
|
|
@ -34,6 +34,24 @@ properties:
|
|||
type: array
|
||||
type: object
|
||||
example: {
|
||||
"content": [
|
||||
{
|
||||
"actions": [
|
||||
"notify",
|
||||
{
|
||||
"set_tweak": "sound",
|
||||
"value": "default"
|
||||
},
|
||||
{
|
||||
"set_tweak": "highlight"
|
||||
}
|
||||
],
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"pattern": "alice",
|
||||
"rule_id": ".m.rule.contains_user_name"
|
||||
}
|
||||
],
|
||||
"override": [
|
||||
{
|
||||
"actions": [],
|
||||
|
|
@ -95,14 +113,12 @@ example: {
|
|||
],
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_property_contains",
|
||||
"key": "content.m\\.mentions.user_ids",
|
||||
"value": "@alice:example.com"
|
||||
"kind": "contains_display_name"
|
||||
}
|
||||
],
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"rule_id": ".m.rule.is_user_mention"
|
||||
"rule_id": ".m.rule.contains_display_name"
|
||||
},
|
||||
{
|
||||
"actions": [
|
||||
|
|
|
|||
|
|
@ -1,29 +0,0 @@
|
|||
# Copyright 2026 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
title: Recent Emoji
|
||||
type: object
|
||||
properties:
|
||||
emoji:
|
||||
type: string
|
||||
description: The Unicode emoji as string.
|
||||
example: 🚀
|
||||
total:
|
||||
type: number
|
||||
description: |-
|
||||
The number of times the emoji has been used.
|
||||
MUST be non-negative and smaller than 2^53.
|
||||
required:
|
||||
- emoji
|
||||
- total
|
||||
|
|
@ -24,23 +24,16 @@ properties:
|
|||
submit_url:
|
||||
type: string
|
||||
format: uri
|
||||
x-changedInMatrixVersion:
|
||||
"1.18": |-
|
||||
The URL has the same request and response parameters and error codes as
|
||||
the Identity Service API's endpoint.
|
||||
description: |-
|
||||
An optional field containing a URL where the client must submit the
|
||||
validation token, with identical request and response parameters and error
|
||||
codes to the Identity Service API's
|
||||
[`POST /validate/email/submitToken`](/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)
|
||||
and [`POST /validate/msisdn/submitToken`](/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)
|
||||
endpoints (without the requirement for an access token). The homeserver
|
||||
must send this token to the user (if applicable), who should then be
|
||||
prompted to provide it to the client.
|
||||
validation token to, with identical parameters to the Identity Service
|
||||
API's `POST /validate/email/submitToken` endpoint (without the requirement
|
||||
for an access token). The homeserver must send this token to the user (if
|
||||
applicable), who should then be prompted to provide it to the client.
|
||||
|
||||
If this field is not present, the client can assume that verification
|
||||
will happen without the client's involvement provided the homeserver
|
||||
advertises a sufficiently recent version in the [`GET /versions`](/client-server-api/#get_matrixclientversions)
|
||||
response (ie: r0.5.0).
|
||||
advertises this specification version in the `/versions` response
|
||||
(ie: r0.5.0).
|
||||
example: "https://example.org/path/to/submitToken"
|
||||
required: ['sid']
|
||||
|
|
|
|||
|
|
@ -39,20 +39,16 @@ allOf:
|
|||
for more information. Defaults to `false`.
|
||||
not_rooms:
|
||||
description: A list of room IDs to exclude. If this list is absent then no rooms
|
||||
are excluded. A matching room will be excluded even if it is listed in the `rooms`
|
||||
are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
|
||||
filter.
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
type: array
|
||||
rooms:
|
||||
description: A list of room IDs to include. If this list is absent then all rooms
|
||||
are included.
|
||||
items:
|
||||
type: string
|
||||
format: mx-room-id
|
||||
pattern: "^!"
|
||||
type: array
|
||||
contains_url:
|
||||
type: boolean
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue