From eefc95ca2402f271e3665c256e5894ea1139528c Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Tue, 28 Jan 2025 18:43:38 +0100 Subject: [PATCH 1/2] add section about Cryptomator desktop network settings --- source/desktop/network.rst | 56 +++++++++++++++++++++++++++++++++++++ source/hub/introduction.rst | 2 ++ source/index.rst | 1 + 3 files changed, 59 insertions(+) create mode 100644 source/desktop/network.rst diff --git a/source/desktop/network.rst b/source/desktop/network.rst new file mode 100644 index 0000000..93de5e2 --- /dev/null +++ b/source/desktop/network.rst @@ -0,0 +1,56 @@ +Network Settings +================ + +In general, Cryptomator does not require a network connection to function. + +If the network connection is present, it is used for optional features, i.e. update checks and searching the error database for solutions. +The only exception is when unlocking :ref:`Cryptomator Hub ` vaults, then a network connection to the hub server is required. +All network connections to the internet are using HTTPS with at least TLS 1.2. + +Trust Certificate Management +----------------------------- +Depending on the OS, the required trusted root certificates are loaded from different locations. + ++---------+--------------------------------------------------------------------------------------------------------------------------------+ +| OS | Trust store | ++=========+================================================================================================================================+ +| Linux | | PKCS#12 file ``/etc/cryptomator/certs.p12``; If the file does not exist, an internal list | +| | | of common CAs is used. | ++---------+--------------------------------------------------------------------------------------------------------------------------------+ +| macOS | System keychain | ++---------+--------------------------------------------------------------------------------------------------------------------------------+ +| Windows | | Certificate store "Trusted Root Certification Authorities", with registry path | +| | | ``HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates\ROOT\`` | ++---------+--------------------------------------------------------------------------------------------------------------------------------+ + +Proxy Server +------------ +The default proxy server differs depending on the operating system: + ++---------+-----------------------+ +| OS | Default proxy setting | ++=========+=======================+ +| Linux | No proxy | ++---------+-----------------------+ +| macOS | Use system proxy | ++---------+-----------------------+ +| Windows | Use system proxy | ++---------+-----------------------+ + + +To change the proxy server, you need to edit the file ``Cryptomator.cfg``, which can be found inside the installation directory of Cryptomator. +Search for the line:: + + java-options=-Djava.net.useSystemProxies=true + +and *if it exists*, only replace the word ``true`` with ``false``. + +Add the following lines to the end of the file:: + + java-options=-Dhttp.proxyHost=[1] + java-options=-Dhttp.proxyPort=[2] + java-options=-Dhttps.proxyHost=[1] + java-options=-Dhttps.proxyPort=[2] + java-options=-Dhttp.nonProxyHosts=localhost|127.0.0.1|cryptomator-vault|[3] + +and replace ``[1]`` with the host address of the proxy server, ``[2]`` with the port used on the proxy server and ``[3]`` with all host addresses, not redirected via the proxy server, separated by '|'. \ No newline at end of file diff --git a/source/hub/introduction.rst b/source/hub/introduction.rst index 88d7b72..799e54d 100644 --- a/source/hub/introduction.rst +++ b/source/hub/introduction.rst @@ -5,6 +5,8 @@ | +.. _hub/introduction: + *************** Cryptomator Hub *************** diff --git a/source/index.rst b/source/index.rst index bb0f895..2624411 100644 --- a/source/index.rst +++ b/source/index.rst @@ -29,6 +29,7 @@ If you are interested in the security of Cryptomator, have a look at our :ref:`s desktop/error-handling.rst desktop/sync-conflicts.rst desktop/advanced-settings.rst + desktop/network.rst .. toctree:: :hidden: From 0e8e335e660605b108dcb3d9f154fee571c021e6 Mon Sep 17 00:00:00 2001 From: Armin Schrenk Date: Wed, 29 Jan 2025 14:00:01 +0100 Subject: [PATCH 2/2] Apply suggestions from code review --- source/desktop/network.rst | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/source/desktop/network.rst b/source/desktop/network.rst index 93de5e2..76b216d 100644 --- a/source/desktop/network.rst +++ b/source/desktop/network.rst @@ -1,3 +1,5 @@ +.. _desktop/network: + Network Settings ================ @@ -7,6 +9,9 @@ If the network connection is present, it is used for optional features, i.e. upd The only exception is when unlocking :ref:`Cryptomator Hub ` vaults, then a network connection to the hub server is required. All network connections to the internet are using HTTPS with at least TLS 1.2. + +.. _desktop/network/trust-certificate-management: + Trust Certificate Management ----------------------------- Depending on the OS, the required trusted root certificates are loaded from different locations. @@ -14,8 +19,8 @@ Depending on the OS, the required trusted root certificates are loaded from diff +---------+--------------------------------------------------------------------------------------------------------------------------------+ | OS | Trust store | +=========+================================================================================================================================+ -| Linux | | PKCS#12 file ``/etc/cryptomator/certs.p12``; If the file does not exist, an internal list | -| | | of common CAs is used. | +| Linux | | PKCS#12 file ``/etc/cryptomator/certs.p12``; If the file does not exist, the JDK default | +| | | trust store is used. [1]_ | +---------+--------------------------------------------------------------------------------------------------------------------------------+ | macOS | System keychain | +---------+--------------------------------------------------------------------------------------------------------------------------------+ @@ -23,6 +28,13 @@ Depending on the OS, the required trusted root certificates are loaded from diff | | | ``HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SystemCertificates\ROOT\`` | +---------+--------------------------------------------------------------------------------------------------------------------------------+ +Remarks: + +.. [1] For more information about the location and contained certificates, see `JEP 319 `_. + + +.. _desktop/network/proxy-server: + Proxy Server ------------ The default proxy server differs depending on the operating system: @@ -38,14 +50,14 @@ The default proxy server differs depending on the operating system: +---------+-----------------------+ -To change the proxy server, you need to edit the file ``Cryptomator.cfg``, which can be found inside the installation directory of Cryptomator. -Search for the line:: +To change the proxy server, you need to edit :ref:`Cryptomator.cfg `. +Open the file in a text editor, search for the line:: java-options=-Djava.net.useSystemProxies=true and *if it exists*, only replace the word ``true`` with ``false``. -Add the following lines to the end of the file:: +In the second step, add the following lines to the end of the file:: java-options=-Dhttp.proxyHost=[1] java-options=-Dhttp.proxyPort=[2] @@ -53,4 +65,4 @@ Add the following lines to the end of the file:: java-options=-Dhttps.proxyPort=[2] java-options=-Dhttp.nonProxyHosts=localhost|127.0.0.1|cryptomator-vault|[3] -and replace ``[1]`` with the host address of the proxy server, ``[2]`` with the port used on the proxy server and ``[3]`` with all host addresses, not redirected via the proxy server, separated by '|'. \ No newline at end of file +and replace ``[1]`` with the host address of the proxy server, ``[2]`` with the port used on the proxy server and ``[3]`` with the list of host addresses, which should not use the proxy server, separated by '|'. \ No newline at end of file