comparison mercurial/help/config.txt @ 29559:7dec5e441bf7

sslutil: config option to specify TLS protocol version

Currently, Mercurial will use TLS 1.0 or newer when connecting to
remote servers, selecting the highest TLS version supported by both
peers. On older Pythons, only TLS 1.0 is available. On newer Pythons,
TLS 1.1 and 1.2 should be available.

Security-minded people may want to not take any risks running
TLS 1.0 (or even TLS 1.1). This patch gives those people a config
option to explicitly control which TLS versions Mercurial should use.
By providing this option, one can require newer TLS versions
before they are formally deprecated by Mercurial/Python/OpenSSL/etc
and lower their security exposure. This option also provides an
easy mechanism to change protocol policies in Mercurial. If there
is a 0-day and TLS 1.0 is completely broken, we can act quickly
without changing much code.

Because setting the minimum TLS protocol is something you'll likely
want to do globally, this patch introduces a global config option under
[hostsecurity] for that purpose.

wrapserversocket() has been taught a hidden config option to define
the explicit protocol to use. This is queried in this function and
not passed as an argument because I don't want to expose this dangerous
option as part of the Python API. There is a risk someone could footgun
themselves. But the config option is a devel option, has a warning
comment, and I doubt most people are using `hg serve` to run a
production HTTPS server (I would have something not Mercurial/Python
handle TLS). If this is problematic, we can go back to using a
custom extension in tests to coerce the server into bad behavior.

29558:a935cd7d51a6

    hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33

``hostsecurity``
----------------

Used to specify per-host security settings.

Options in this section have the form ``hostname``:``setting``. This allows
multiple settings to be defined on a per-host basis.

The following per-host settings can be defined.

``fingerprints``
    A list of hashes of the DER encoded peer/remote certificate. Values have

    This can provide stronger security than traditional CA-based validation
    at the expense of convenience.

    This option takes precedence over ``verifycertsfile``.

``verifycertsfile``
    Path to file a containing a list of PEM encoded certificates used to
    verify the server certificate. Environment variables and ``~user``
    constructs are expanded in the filename.

    [hostsecurity]
    hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
    hg2.example.com:fingerprints = sha1:914f1aff87249c09b6859b88b1906d30756491ca, sha1:fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
    foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem

``http_proxy``
--------------

Used to access web-based Mercurial repositories through a HTTP

29559:7dec5e441bf7

    hg.intevation.org = fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33

``hostsecurity``
----------------

Used to specify global and per-host security settings for connecting to
other machines.

The following options control default behavior for all hosts.

``minimumprotocol``
    Defines the minimum channel encryption protocol to use.

    By default, the highest version of TLS - 1.0 or greater - supported by
    both client and server is used.

    Allowed values are: ``tls1.0`` (the default), ``tls1.1``, ``tls1.2``.

Options in the ``[hostsecurity]`` section can have the form
``hostname``:``setting``. This allows multiple settings to be defined on a
per-host basis.

The following per-host settings can be defined.

``fingerprints``
    A list of hashes of the DER encoded peer/remote certificate. Values have

    This can provide stronger security than traditional CA-based validation
    at the expense of convenience.

    This option takes precedence over ``verifycertsfile``.

``minimumprotocol``
    This behaves like ``minimumprotocol`` as described above except it
    only applies to the host on which it is defined.

``verifycertsfile``
    Path to file a containing a list of PEM encoded certificates used to
    verify the server certificate. Environment variables and ``~user``
    constructs are expanded in the filename.

    [hostsecurity]
    hg.example.com:fingerprints = sha256:c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2
    hg2.example.com:fingerprints = sha1:914f1aff87249c09b6859b88b1906d30756491ca, sha1:fc:e2:8d:d9:51:cd:cb:c1:4d:18:6b:b7:44:8d:49:72:57:e6:cd:33
    foo.example.com:verifycertsfile = /etc/ssl/trusted-ca-certs.pem

To change the default minimum protocol version to TLS 1.2 but to allow TLS 1.1
when connecting to ``hg.example.com``::

    [hostsecurity]
    minimumprotocol = tls1.2
    hg.example.com:minimumprotocol = tls1.1

``http_proxy``
--------------

Used to access web-based Mercurial repositories through a HTTP