diff --git a/docs/example-advanced.nginx.conf b/docs/example-advanced.nginx.conf new file mode 100644 index 000000000..3b38a4606 --- /dev/null +++ b/docs/example-advanced.nginx.conf @@ -0,0 +1,260 @@ +# This file is included strictly as an example of how Nginx can be configured +# to work with CryptPad. This example WILL NOT WORK AS IS. For best results, +# compare the sections of this configuration file against a working CryptPad +# installation (http server by the Nodejs process). If you are using CryptPad +# in production and require professional support please contact sales@cryptpad.fr + +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + + # Let's Encrypt webroot + include letsencrypt-webroot; + + # CryptPad serves static assets over these two domains. + # `main_domain` is what users will enter in their address bar. + # Privileged computation such as key management is handled in this scope + # UI content is loaded via the `sandbox_domain`. + # "Content Security Policy" headers prevent content loaded via the sandbox + # from accessing privileged information. + # These variables must be different to take advantage of CryptPad's sandboxing techniques. + # In the event of an XSS vulnerability in CryptPad's front-end code + # this will limit the amount of information accessible to attackers. + set $main_domain "your-main-domain.com"; + set $sandbox_domain "your-sandbox-domain.com"; + + # By default CryptPad forbids remote domains from embedding CryptPad documents in iframes. + # The sandbox domain must always be permitted in order for the platform to function. + # If you wish to enable remote embedding you may change the value below to "*" + # as per the commented value. + set $allowed_origins "https://${sandbox_domain}"; + #set $allowed_origins "*"; + + # CryptPad's dynamic content (websocket traffic and encrypted blobs) + # can be served over separate domains. Using dedicated domains (or subdomains) + # for these purposes allows you to move them to a separate machine at a later date + # if you find that a single machine cannot handle all of your users. + # If you don't use dedicated domains, this can be the same as $main_domain + # If you do, they can be added as exceptions to any rules which block connections to remote domains. + # You can find these variables referenced below in the relevant places + set $api_domain "api.your-main-domain.com"; + set $files_domain "files.your-main-domain.com"; + + # nginx doesn't let you set server_name via variables, so you need to hardcode your domains here + server_name your-main-domain.com your-sandbox-domain.com; + + # You'll need to Set the path to your certificates and keys here + # IMPORTANT: this config is intended to serve assets for at least two domains + # (your main domain and your sandbox domain). As such, you'll need to generate a single SSL certificate + # that includes both domains in order for things to work as expected. + ssl_certificate /etc/ssl/lets-encrypt/your-main-domain.com/cert; + ssl_certificate_key /etc/ssl/lets-encrypt/your-main-domain.com/key; + + # diffie-hellman parameters are used to negotiate keys for your session + # generate strong parameters using the following command + ssl_dhparam /etc/nginx/dhparam.pem; # openssl dhparam -out /etc/nginx/dhparam.pem 4096 + + # Speeds things up a little bit when resuming a session + ssl_session_timeout 1d; + ssl_session_cache shared:MozSSL:10m; + ssl_session_tickets off; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384; + ssl_prefer_server_ciphers off; + + # HSTS (ngx_http_headers_module is required) (63072000 seconds) + add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always; + + # OCSP stapling + ssl_stapling on; + ssl_stapling_verify on; + + # verify chain of trust of OCSP response using Root CA and Intermediate certs + ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; + + # replace with the IP address of your resolver + resolver 8.8.8.8 8.8.4.4 1.1.1.1 1.0.0.1 9.9.9.9 149.112.112.112 208.67.222.222 208.67.220.220; + + add_header X-XSS-Protection "1; mode=block"; + add_header X-Content-Type-Options nosniff; + add_header Access-Control-Allow-Origin "${allowed_origins}"; + add_header Access-Control-Allow-Credentials true; + # add_header X-Frame-Options "SAMEORIGIN"; + + # Opt out of Google's FLoC Network + add_header Permissions-Policy interest-cohort=(); + + # Enable SharedArrayBuffer in Firefox (for .xlsx export) + add_header Cross-Origin-Resource-Policy cross-origin; + add_header Cross-Origin-Embedder-Policy require-corp; + + # Insert the path to your CryptPad repository root here + root /home/cryptpad/cryptpad; + index index.html; + error_page 404 /customize.dist/404.html; + + # any static assets loaded with "ver=" in their URL will be cached for a year + if ($args ~ ver=) { + set $cacheControl max-age=31536000; + } + # This rule overrides the above caching directive and makes things somewhat less efficient. + # We had inverted them as an optimization, but Safari 16 introduced a bug that interpreted + # some important headers incorrectly when loading these files from cache. + # This is why we can't have nice things :( + if ($uri ~ ^(\/|.*\/|.*\.html)$) { + set $cacheControl no-cache; + } + + # Will not set any header if it is emptystring + add_header Cache-Control $cacheControl; + + # CSS can be dynamically set inline, loaded from the same domain, or from $main_domain + set $styleSrc "'unsafe-inline' 'self' https://${main_domain}"; + + # connect-src restricts URLs which can be loaded using script interfaces + # if you have configured your instance to use a dedicated $files_domain or $api_domain + # you will need to add them below as: https://${files_domain} and https://${api_domain} + set $connectSrc "'self' https://${main_domain} blob: wss://${api_domain} https://${sandbox_domain}"; + + # fonts can be loaded from data-URLs or the main domain + set $fontSrc "'self' data: https://${main_domain}"; + + # images can be loaded from anywhere, though we'd like to deprecate this as it allows the use of images for tracking + set $imgSrc "'self' data: blob: https://${main_domain}"; + + # frame-src specifies valid sources for nested browsing contexts. + # this prevents loading any iframes from anywhere other than the sandbox domain + set $frameSrc "'self' https://${sandbox_domain} blob:"; + + # specifies valid sources for loading media using video or audio + set $mediaSrc "blob:"; + + # defines valid sources for webworkers and nested browser contexts + # deprecated in favour of worker-src and frame-src + set $childSrc "https://${main_domain}"; + + # specifies valid sources for Worker, SharedWorker, or ServiceWorker scripts. + # supercedes child-src but is unfortunately not yet universally supported. + set $workerSrc "'self'"; + + # script-src specifies valid sources for javascript, including inline handlers + set $scriptSrc "'self' resource: https://${main_domain}"; + + # frame-ancestors specifies which origins can embed your CryptPad instance + # this must include 'self' and your main domain (over HTTPS) in order for CryptPad to work + # if you have enabled remote embedding via the admin panel then this must be more permissive. + # note: cryptpad.fr permits web pages served via https: and vector: (element desktop app) + set $frameAncestors "'self' https://${main_domain}"; + # set $frameAncestors "'self' https: vector:"; + + set $unsafe 0; + # the following assets are loaded via the sandbox domain + # they unfortunately still require exceptions to the sandboxing to work correctly. + if ($uri ~ ^\/(sheet|doc|presentation)\/inner.html.*$) { set $unsafe 1; } + if ($uri ~ ^\/common\/onlyoffice\/.*\/.*\.html.*$) { set $unsafe 1; } + + # everything except the sandbox domain is a privileged scope, as they might be used to handle keys + if ($host != $sandbox_domain) { set $unsafe 0; } + # this iframe is an exception. Office file formats are converted outside of the sandboxed scope + # because of bugs in Chromium-based browsers that incorrectly ignore headers that are supposed to enable + # the use of some modern APIs that we require when javascript is run in a cross-origin context. + # We've applied other sandboxing techniques to mitigate the risk of running WebAssembly in this privileged scope + if ($uri ~ ^\/unsafeiframe\/inner\.html.*$) { set $unsafe 1; } + + # draw.io uses inline script tags in it's index.html. The hashes are added here. + if ($uri ~ ^\/components\/drawio\/src\/main\/webapp\/index.html.*$) { + set $scriptSrc "'self' 'sha256-6zAB96lsBZREqf0sT44BhH1T69sm7HrN34rpMOcWbNo=' 'sha256-6g514VrT/cZFZltSaKxIVNFF46+MFaTSDTPB8WfYK+c=' resource: https://${main_domain}"; + } + + # privileged contexts allow a few more rights than unprivileged contexts, though limits are still applied + if ($unsafe) { + set $scriptSrc "'self' 'unsafe-eval' 'unsafe-inline' resource: https://${main_domain}"; + } + + # Finally, set all the rules you composed above. + add_header Content-Security-Policy "default-src 'none'; child-src $childSrc; worker-src $workerSrc; media-src $mediaSrc; style-src $styleSrc; script-src $scriptSrc; connect-src $connectSrc; font-src $fontSrc; img-src $imgSrc; frame-src $frameSrc; frame-ancestors $frameAncestors"; + + # The nodejs process can handle all traffic whether accessed over websocket or as static assets + # We prefer to serve static content from nginx directly and to leave the API server to handle + # the dynamic content that only it can manage. This is primarily an optimization + location ^~ /cryptpad_websocket { + # XXX + # static assets like blobs and blocks are served by clustered workers in the API server + # Websocket traffic still needs to be handled by the main process, which means it needs + # to be hosted on a different port. By default 3003 will be used, though this is configurable + # via config.websocketPort + proxy_pass http://localhost:3003; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # WebSocket support (nginx 1.4) + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection upgrade; + } + + location ^~ /customize.dist/ { + # This is needed in order to prevent infinite recursion between /customize/ and the root + } + # try to load customizeable content via /customize/ and fall back to the default content + # located at /customize.dist/ + # This is what allows you to override behaviour. + location ^~ /customize/ { + rewrite ^/customize/(.*)$ $1 break; + try_files /customize/$uri /customize.dist/$uri; + } + + # /api/config is loaded once per page load and is used to retrieve + # the caching variable which is applied to every other resource + # which is loaded during that session. + location ~ ^/api/.*$ { + proxy_pass http://localhost:3000; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # These settings prevent both NGINX and the API server + # from setting the same headers and creating duplicates + proxy_hide_header Cross-Origin-Resource-Policy; + add_header Cross-Origin-Resource-Policy cross-origin; + proxy_hide_header Cross-Origin-Embedder-Policy; + add_header Cross-Origin-Embedder-Policy require-corp; + } + + # Requests for blobs and blocks are now proxied to the API server + # This simplifies NGINX path configuration in the event they are being hosted in a non-standard location + # or with odd unexpected permissions. Serving blobs in this manner also means that it will be possible to + # enforce access control for them, though this is not yet implemented. + # Access control (via TOTP 2FA) has been added to blocks, so they can be handled with the same directives. + location ~ ^/(blob|block)/.*$ { + if ($request_method = 'OPTIONS') { + add_header 'Access-Control-Allow-Origin' "${allowed_origins}"; + add_header 'Access-Control-Allow-Credentials' true; + add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; + add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range'; + add_header 'Access-Control-Max-Age' 1728000; + add_header 'Content-Type' 'application/octet-stream; charset=utf-8'; + add_header 'Content-Length' 0; + return 204; + } + # Since we are proxying to the API server these headers can get duplicated + # so we hide them + proxy_hide_header 'X-Content-Type-Options'; + proxy_hide_header 'Access-Control-Allow-Origin'; + proxy_hide_header 'Permissions-Policy'; + proxy_hide_header 'X-XSS-Protection'; + proxy_pass http://localhost:3000; + } + + # The nodejs server has some built-in forwarding rules to prevent + # URLs like /pad from resulting in a 404. This simply adds a trailing slash + # to a variety of applications. + location ~ ^/(register|login|recovery|settings|user|pad|drive|poll|slide|code|whiteboard|file|media|profile|contacts|todo|filepicker|debug|kanban|sheet|support|admin|notifications|teams|calendar|presentation|doc|form|report|convert|checkup|diagram)$ { + rewrite ^(.*)$ $1/ redirect; + } + + # Finally, serve anything the above exceptions don't govern. + try_files /customize/www/$uri /customize/www/$uri/index.html /www/$uri /www/$uri/index.html /customize/$uri; +} diff --git a/docs/example.nginx.conf b/docs/example.nginx.conf index 3b38a4606..5a7a3b876 100644 --- a/docs/example.nginx.conf +++ b/docs/example.nginx.conf @@ -12,35 +12,14 @@ server { include letsencrypt-webroot; # CryptPad serves static assets over these two domains. - # `main_domain` is what users will enter in their address bar. + # `your-main-domain` is what users will enter in their address bar. # Privileged computation such as key management is handled in this scope - # UI content is loaded via the `sandbox_domain`. + # UI content is loaded via the `your-sandbox-domain`. # "Content Security Policy" headers prevent content loaded via the sandbox # from accessing privileged information. - # These variables must be different to take advantage of CryptPad's sandboxing techniques. + # This setup allows to take advantage of CryptPad's sandboxing techniques. # In the event of an XSS vulnerability in CryptPad's front-end code # this will limit the amount of information accessible to attackers. - set $main_domain "your-main-domain.com"; - set $sandbox_domain "your-sandbox-domain.com"; - - # By default CryptPad forbids remote domains from embedding CryptPad documents in iframes. - # The sandbox domain must always be permitted in order for the platform to function. - # If you wish to enable remote embedding you may change the value below to "*" - # as per the commented value. - set $allowed_origins "https://${sandbox_domain}"; - #set $allowed_origins "*"; - - # CryptPad's dynamic content (websocket traffic and encrypted blobs) - # can be served over separate domains. Using dedicated domains (or subdomains) - # for these purposes allows you to move them to a separate machine at a later date - # if you find that a single machine cannot handle all of your users. - # If you don't use dedicated domains, this can be the same as $main_domain - # If you do, they can be added as exceptions to any rules which block connections to remote domains. - # You can find these variables referenced below in the relevant places - set $api_domain "api.your-main-domain.com"; - set $files_domain "files.your-main-domain.com"; - - # nginx doesn't let you set server_name via variables, so you need to hardcode your domains here server_name your-main-domain.com your-sandbox-domain.com; # You'll need to Set the path to your certificates and keys here @@ -89,172 +68,15 @@ server { add_header Cross-Origin-Resource-Policy cross-origin; add_header Cross-Origin-Embedder-Policy require-corp; - # Insert the path to your CryptPad repository root here - root /home/cryptpad/cryptpad; - index index.html; - error_page 404 /customize.dist/404.html; + location / { + proxy_pass http://localhost:3000; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + client_max_body_size 150m; - # any static assets loaded with "ver=" in their URL will be cached for a year - if ($args ~ ver=) { - set $cacheControl max-age=31536000; - } - # This rule overrides the above caching directive and makes things somewhat less efficient. - # We had inverted them as an optimization, but Safari 16 introduced a bug that interpreted - # some important headers incorrectly when loading these files from cache. - # This is why we can't have nice things :( - if ($uri ~ ^(\/|.*\/|.*\.html)$) { - set $cacheControl no-cache; - } - - # Will not set any header if it is emptystring - add_header Cache-Control $cacheControl; - - # CSS can be dynamically set inline, loaded from the same domain, or from $main_domain - set $styleSrc "'unsafe-inline' 'self' https://${main_domain}"; - - # connect-src restricts URLs which can be loaded using script interfaces - # if you have configured your instance to use a dedicated $files_domain or $api_domain - # you will need to add them below as: https://${files_domain} and https://${api_domain} - set $connectSrc "'self' https://${main_domain} blob: wss://${api_domain} https://${sandbox_domain}"; - - # fonts can be loaded from data-URLs or the main domain - set $fontSrc "'self' data: https://${main_domain}"; - - # images can be loaded from anywhere, though we'd like to deprecate this as it allows the use of images for tracking - set $imgSrc "'self' data: blob: https://${main_domain}"; - - # frame-src specifies valid sources for nested browsing contexts. - # this prevents loading any iframes from anywhere other than the sandbox domain - set $frameSrc "'self' https://${sandbox_domain} blob:"; - - # specifies valid sources for loading media using video or audio - set $mediaSrc "blob:"; - - # defines valid sources for webworkers and nested browser contexts - # deprecated in favour of worker-src and frame-src - set $childSrc "https://${main_domain}"; - - # specifies valid sources for Worker, SharedWorker, or ServiceWorker scripts. - # supercedes child-src but is unfortunately not yet universally supported. - set $workerSrc "'self'"; - - # script-src specifies valid sources for javascript, including inline handlers - set $scriptSrc "'self' resource: https://${main_domain}"; - - # frame-ancestors specifies which origins can embed your CryptPad instance - # this must include 'self' and your main domain (over HTTPS) in order for CryptPad to work - # if you have enabled remote embedding via the admin panel then this must be more permissive. - # note: cryptpad.fr permits web pages served via https: and vector: (element desktop app) - set $frameAncestors "'self' https://${main_domain}"; - # set $frameAncestors "'self' https: vector:"; - - set $unsafe 0; - # the following assets are loaded via the sandbox domain - # they unfortunately still require exceptions to the sandboxing to work correctly. - if ($uri ~ ^\/(sheet|doc|presentation)\/inner.html.*$) { set $unsafe 1; } - if ($uri ~ ^\/common\/onlyoffice\/.*\/.*\.html.*$) { set $unsafe 1; } - - # everything except the sandbox domain is a privileged scope, as they might be used to handle keys - if ($host != $sandbox_domain) { set $unsafe 0; } - # this iframe is an exception. Office file formats are converted outside of the sandboxed scope - # because of bugs in Chromium-based browsers that incorrectly ignore headers that are supposed to enable - # the use of some modern APIs that we require when javascript is run in a cross-origin context. - # We've applied other sandboxing techniques to mitigate the risk of running WebAssembly in this privileged scope - if ($uri ~ ^\/unsafeiframe\/inner\.html.*$) { set $unsafe 1; } - - # draw.io uses inline script tags in it's index.html. The hashes are added here. - if ($uri ~ ^\/components\/drawio\/src\/main\/webapp\/index.html.*$) { - set $scriptSrc "'self' 'sha256-6zAB96lsBZREqf0sT44BhH1T69sm7HrN34rpMOcWbNo=' 'sha256-6g514VrT/cZFZltSaKxIVNFF46+MFaTSDTPB8WfYK+c=' resource: https://${main_domain}"; - } - - # privileged contexts allow a few more rights than unprivileged contexts, though limits are still applied - if ($unsafe) { - set $scriptSrc "'self' 'unsafe-eval' 'unsafe-inline' resource: https://${main_domain}"; - } - - # Finally, set all the rules you composed above. - add_header Content-Security-Policy "default-src 'none'; child-src $childSrc; worker-src $workerSrc; media-src $mediaSrc; style-src $styleSrc; script-src $scriptSrc; connect-src $connectSrc; font-src $fontSrc; img-src $imgSrc; frame-src $frameSrc; frame-ancestors $frameAncestors"; - - # The nodejs process can handle all traffic whether accessed over websocket or as static assets - # We prefer to serve static content from nginx directly and to leave the API server to handle - # the dynamic content that only it can manage. This is primarily an optimization - location ^~ /cryptpad_websocket { - # XXX - # static assets like blobs and blocks are served by clustered workers in the API server - # Websocket traffic still needs to be handled by the main process, which means it needs - # to be hosted on a different port. By default 3003 will be used, though this is configurable - # via config.websocketPort - proxy_pass http://localhost:3003; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header Host $host; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - - # WebSocket support (nginx 1.4) - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection upgrade; - } - - location ^~ /customize.dist/ { - # This is needed in order to prevent infinite recursion between /customize/ and the root - } - # try to load customizeable content via /customize/ and fall back to the default content - # located at /customize.dist/ - # This is what allows you to override behaviour. - location ^~ /customize/ { - rewrite ^/customize/(.*)$ $1 break; - try_files /customize/$uri /customize.dist/$uri; - } - - # /api/config is loaded once per page load and is used to retrieve - # the caching variable which is applied to every other resource - # which is loaded during that session. - location ~ ^/api/.*$ { - proxy_pass http://localhost:3000; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header Host $host; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - - # These settings prevent both NGINX and the API server - # from setting the same headers and creating duplicates - proxy_hide_header Cross-Origin-Resource-Policy; - add_header Cross-Origin-Resource-Policy cross-origin; - proxy_hide_header Cross-Origin-Embedder-Policy; - add_header Cross-Origin-Embedder-Policy require-corp; - } - - # Requests for blobs and blocks are now proxied to the API server - # This simplifies NGINX path configuration in the event they are being hosted in a non-standard location - # or with odd unexpected permissions. Serving blobs in this manner also means that it will be possible to - # enforce access control for them, though this is not yet implemented. - # Access control (via TOTP 2FA) has been added to blocks, so they can be handled with the same directives. - location ~ ^/(blob|block)/.*$ { - if ($request_method = 'OPTIONS') { - add_header 'Access-Control-Allow-Origin' "${allowed_origins}"; - add_header 'Access-Control-Allow-Credentials' true; - add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; - add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range'; - add_header 'Access-Control-Max-Age' 1728000; - add_header 'Content-Type' 'application/octet-stream; charset=utf-8'; - add_header 'Content-Length' 0; - return 204; - } - # Since we are proxying to the API server these headers can get duplicated - # so we hide them - proxy_hide_header 'X-Content-Type-Options'; - proxy_hide_header 'Access-Control-Allow-Origin'; - proxy_hide_header 'Permissions-Policy'; - proxy_hide_header 'X-XSS-Protection'; - proxy_pass http://localhost:3000; - } - - # The nodejs server has some built-in forwarding rules to prevent - # URLs like /pad from resulting in a 404. This simply adds a trailing slash - # to a variety of applications. - location ~ ^/(register|login|recovery|settings|user|pad|drive|poll|slide|code|whiteboard|file|media|profile|contacts|todo|filepicker|debug|kanban|sheet|support|admin|notifications|teams|calendar|presentation|doc|form|report|convert|checkup|diagram)$ { - rewrite ^(.*)$ $1/ redirect; - } - - # Finally, serve anything the above exceptions don't govern. - try_files /customize/www/$uri /customize/www/$uri/index.html /www/$uri /www/$uri/index.html /customize/$uri; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection upgrade; + } }