mirror of
https://github.com/element-hq/synapse.git
synced 2025-12-05 01:10:13 +00:00
Move security note from README into the docs (#19259)
This is a) to simplify the README and b) so that we can easily link to the security page from e.g. the installation guide. Follows on from https://github.com/element-hq/synapse/pull/19228
This commit is contained in:
Erik Johnston
50
README.rst
50
README.rst
@@ -42,61 +42,13 @@ There are three editions of ESS:
|
||||
|
||||
The Synapse documentation describes `options for installing Synapse standalone
|
||||
<https://element-hq.github.io/synapse/latest/setup/installation.html>`_. See
|
||||
below for more useful documenation links.
|
||||
below for more useful documentation links.
|
||||
|
||||
- `Synapse configuration options <https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html>`_
|
||||
- `Synapse configuration for federation <https://element-hq.github.io/synapse/latest/federate.html>`_
|
||||
- `Using a reverse proxy with Synapse <https://element-hq.github.io/synapse/latest/reverse_proxy.html>`_
|
||||
- `Upgrading Synapse <https://element-hq.github.io/synapse/develop/upgrade.html>`_
|
||||
|
||||
Platform dependencies
|
||||
---------------------
|
||||
|
||||
Synapse uses a number of platform dependencies such as Python and PostgreSQL,
|
||||
and aims to follow supported upstream versions. See the `deprecation policy
|
||||
<https://element-hq.github.io/synapse/latest/deprecation_policy.html>`_ for more
|
||||
details.
|
||||
|
||||
|
||||
Security note
|
||||
-------------
|
||||
|
||||
Matrix serves raw, user-supplied data in some APIs — specifically the `content
|
||||
repository endpoints`_.
|
||||
|
||||
.. _content repository endpoints: https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid
|
||||
|
||||
Whilst we make a reasonable effort to mitigate against XSS attacks (for
|
||||
instance, by using `CSP`_), a Matrix homeserver should not be hosted on a
|
||||
domain hosting other web applications. This especially applies to sharing
|
||||
the domain with Matrix web clients and other sensitive applications like
|
||||
webmail. See
|
||||
https://developer.github.com/changes/2014-04-25-user-content-security for more
|
||||
information.
|
||||
|
||||
.. _CSP: https://github.com/matrix-org/synapse/pull/1021
|
||||
|
||||
Ideally, the homeserver should not simply be on a different subdomain, but on
|
||||
a completely different `registered domain`_ (also known as top-level site or
|
||||
eTLD+1). This is because `some attacks`_ are still possible as long as the two
|
||||
applications share the same registered domain.
|
||||
|
||||
.. _registered domain: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-2.3
|
||||
|
||||
.. _some attacks: https://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cookie
|
||||
|
||||
To illustrate this with an example, if your Element Web or other sensitive web
|
||||
application is hosted on ``A.example1.com``, you should ideally host Synapse on
|
||||
``example2.com``. Some amount of protection is offered by hosting on
|
||||
``B.example1.com`` instead, so this is also acceptable in some scenarios.
|
||||
However, you should *not* host your Synapse on ``A.example1.com``.
|
||||
|
||||
Note that all of the above refers exclusively to the domain used in Synapse's
|
||||
``public_baseurl`` setting. In particular, it has no bearing on the domain
|
||||
mentioned in MXIDs hosted on that server.
|
||||
|
||||
Following this advice ensures that even if an XSS is found in Synapse, the
|
||||
impact to other applications will be minimal.
|
||||
|
||||
🎯 Troubleshooting and support
|
||||
==============================
|
||||
|
||||
1
changelog.d/19259.misc
Normal file
1
changelog.d/19259.misc
Normal file
@@ -0,0 +1 @@
|
||||
Simplify README and add ESS Getting started section.
|
||||
@@ -5,6 +5,7 @@
|
||||
|
||||
# Setup
|
||||
- [Installation](setup/installation.md)
|
||||
- [Security](setup/security.md)
|
||||
- [Using Postgres](postgres.md)
|
||||
- [Configuring a Reverse Proxy](reverse_proxy.md)
|
||||
- [Configuring a Forward/Outbound Proxy](setup/forward_proxy.md)
|
||||
|
||||
@@ -16,8 +16,15 @@ that your email address is probably `user@example.com` rather than
|
||||
`user@email.example.com`) - but doing so may require more advanced setup: see
|
||||
[Setting up Federation](../federate.md).
|
||||
|
||||
⚠️ Before setting up Synapse please consult the [security page](security.md) for
|
||||
best practices. ⚠️
|
||||
|
||||
## Installing Synapse
|
||||
|
||||
Note: Synapse uses a number of platform dependencies such as Python and PostgreSQL,
|
||||
and aims to follow supported upstream versions. See the [deprecation
|
||||
policy](../deprecation_policy.md) for more details.
|
||||
|
||||
### Prebuilt packages
|
||||
|
||||
Prebuilt packages are available for a number of platforms. These are recommended
|
||||
|
||||
41
docs/setup/security.md
Normal file
41
docs/setup/security.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Security
|
||||
|
||||
This page lays out security best-practices when running Synapse.
|
||||
|
||||
If you believe you have encountered a security issue, see our [Security
|
||||
Disclosure Policy](https://element.io/en/security/security-disclosure-policy).
|
||||
|
||||
## Content repository
|
||||
|
||||
Matrix serves raw, user-supplied data in some APIs — specifically the [content
|
||||
repository endpoints](https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid).
|
||||
|
||||
Whilst we make a reasonable effort to mitigate against XSS attacks (for
|
||||
instance, by using [CSP](https://github.com/matrix-org/synapse/pull/1021)), a
|
||||
Matrix homeserver should not be hosted on a domain hosting other web
|
||||
applications. This especially applies to sharing the domain with Matrix web
|
||||
clients and other sensitive applications like webmail. See
|
||||
https://developer.github.com/changes/2014-04-25-user-content-security for more
|
||||
information.
|
||||
|
||||
Ideally, the homeserver should not simply be on a different subdomain, but on a
|
||||
completely different [registered
|
||||
domain](https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-2.3)
|
||||
(also known as top-level site or eTLD+1). This is because [some
|
||||
attacks](https://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cookie)
|
||||
are still possible as long as the two applications share the same registered
|
||||
domain.
|
||||
|
||||
|
||||
To illustrate this with an example, if your Element Web or other sensitive web
|
||||
application is hosted on `A.example1.com`, you should ideally host Synapse on
|
||||
`example2.com`. Some amount of protection is offered by hosting on
|
||||
`B.example1.com` instead, so this is also acceptable in some scenarios.
|
||||
However, you should *not* host your Synapse on `A.example1.com`.
|
||||
|
||||
Note that all of the above refers exclusively to the domain used in Synapse's
|
||||
`public_baseurl` setting. In particular, it has no bearing on the domain
|
||||
mentioned in MXIDs hosted on that server.
|
||||
|
||||
Following this advice ensures that even if an XSS is found in Synapse, the
|
||||
impact to other applications will be minimal.
|
||||
Reference in New Issue
Block a user