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).
Behavior |
Mercurial <3.8 |
Mercurial >=3.9 |
Requires trusted CA certificate when connecting to new servers |
No |
Yes |
web.cacerts=! disables certificate validation |
Yes |
No (feature removed) |
[hostsecurity] config section |
No |
Yes |
Preferred certificate fingerprint hash algorithm |
SHA-1 |
SHA-256 |
Per-host CA certificates |
No |
Yes |
Supporting pinning multiple cert fingerprints per host |
3.8+ |
Yes |
smtp.verifycert config option |
Yes |
No (option removed) |
Behavior |
Python <2.7.9 |
Python >=2.7.9 (or with modern ssl module) |
Supports TLS 1.1 and 1.2 |
No |
Yes |
Server Name Indication (SNI) support |
No |
Yes |
System trusted certificate authority access |
No |
Yes |
Good ciphersuites available |
No |
Yes |
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)
Mercurial packagers are highly encouraged to set the web.cacerts config option in the global/system hgrc file to the system's trusted CA store.