Diff for "SecureConnections"

Overview

Mercurial performs various checks to verify that connections to servers are secure. These checks vary depending on the Mercurial and Python version being used.

Behavior of Various Configurations

Mercurial 3.9 contained a major refactor of the connection security code and user configuration. One of the changes is that Mercurial 3.9+ is more strict about connection security and will abort if a connection cannot be verified (prior versions would issue warnings and continue connecting).

Common Errors and Warnings

1. abort: unable to verify security of localhost (no loaded CA certificates); refusing to connect

This error occurs when Mercurial is unable to load CA certificates to verify the server's certificate.

The way server security works is the server has a certificate saying they are server X. This certificate is signed by an entity called a Certificate Authority or CA. Before that happens, the CA is supposed to verify that they should really sign that certificate. e.g. if someone requests the signing for a certificate for google.com the CA is supposed to verify that the possessor of that certificate is Google (the company).

Clients contain lists of CAs that are trusted. When connecting to a server, they will enforce that the CA that signed that server's certificate was signed by a trusted CA.

This error message basically means Mercurial is unable to load a list of trusted CAs and therefore can't establish the trust for the server certificate's CA. Since it can't trust the certificate, it is refusing to connect.

This error message indicates your Mercurial installation/configuration is incomplete. Typically, Mercurial will load your system's CA certificates. However, it can't always do this. Reasons why it can't do this include:

• Running Python <2.7.9 (older versions of Python don't know how to locate the system CA store)

• Python is unable to find the system CA store (this may indicate the Python installation is mis-configured)

The mitigation for this error is to tell Mercurial where trusted CA certificates are located. This can be done by setting the web.cacerts configuration option to the path to a file containing PEM certificates. Common file locations include:

• /etc/pki/tls/certs/ca-bundle.trust.crt (RedHat, CentOS, Fedora)

• /etc/ssl/certs/ca-certificates.crt (Debian, Ubuntu, Gentoo)

Expectations of Mercurial Packages

Proper Mercurial packages should guarantee one of the following:

1. The underlying Python install is able to load CA certificates from configured locations

2. The web.cacerts config option is defined to an appropriate location

3. The certifi Python package is installed

If one of these isn't true, Mercurial will fail to establish secure connections to servers and/or will print a warning saying that Mercurial is improperly configured.

To test whether the underlying Python install is able to load CA certificates from default locations, run the following Python code:

import socket, ssl
context = ssl.create_default_context()
context.verify_mode = ssl.CERT_REQUIRED
context.load_default_certs()
conn = context.wrap_socket(socket.socket(socket.AF_INET), server_hostname='www.mozilla.org')
conn.connect(('www.mozilla.org', 443))

This should work on Python 2.7.9+ or Python versions with a backported ssl module (such as RHEL7's Python 2.7.5 package). If this doesn't work on Python 2.7.9+, that Python package is arguably broken as it doesn't provide a mechanism to verify CA certificates in the standard library.

If the above code works, the Python install is able to load CA certificates (using the location configured by the OpenSSL that Python is using). Mercurial should work out of the box. You don't need to change anything unless you want to explicitly point Mercurial at a different set of trusted CA certificates. (Wanting to point Mercurial at a different set of trusted CA certificates from the Python it runs on is weird: you should consider changing the Python configuration instead.)

If the above code fails, the Mercurial install should set the web.cacerts config option in the global/system hgrc to a file containing PEM encoded certificates of trusted CAs (preferred) or ensure the certifi Python package is installed. Configuring web.cacerts is preferred over installing certifi because your system likely already has a file containing trusted CA certificates on it and installing certifi will create N+1 CA files, which results in a more complicated system configuration and potential for things to get out of sync. You probably want a single CA certificate list.