|
Size: 2979
Comment: Clean up per WikiStyleGuide, copy-edit
|
Size: 8221
Comment: I jumped to this from Google Go pages, and have no clue on Mercurial, and had difficulty knowing where the configuration is...
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| Line 4: | Line 3: |
About Mercurial's handling of SSL certificates for https urls. |
About Mercurial's handling of SSL certificates for `https` urls. |
| Line 10: | Line 8: |
| Mercurial has improved its https support in the 1.7.x series. When connecting to an https server, it will now verify the server's certificate. Connections to a server with the wrong identity will be rejected. As of 1.7.3, Mercurial will warn if it doesn't know how to verify it because no Certification Authorities (CAs) have been configured. | Mercurial has improved its HTTPS support in the 1.7.x series. When connecting to an HTTPS server, it will now verify the server's certificate correctly and reject the connection if the server identity can't be confirmed - but only if Certification Authorities (CAs) have been configured. As of 1.7.3, Mercurial will warn if CAs haven't been configured. |
| Line 12: | Line 10: |
| {i} The "certificate not verified" warning does not mean that you are less secure than before. It just informs you how insecure you always has been. | {i} The new "certificate not verified" warning does not mean that you are less secure than before. It just informs you of how insecure you have always been. |
| Line 14: | Line 12: |
| You should fix your setup so you get the security you might expect from SSL and don't get any warnings; otherwise you might just as well stop using https. | You should fix your setup so you get the security you might expect from SSL and don't get any warnings; otherwise you might just as well stop using HTTPS. |
| Line 16: | Line 14: |
| == Configuration of Certificate Authorities == Most operating systems maintain a set of root certificates that you might decide to trust. Note that any of these authorities can approve a server identity, and any of them will thus be able to spoof any server identity. |
== Configuration of HTTPS certificate authorities == Most operating systems maintain a set of root certificates that you might decide to trust. Note that any of these authorities can approve any server identity, and any of them will thus be able to spoof any server identity. |
| Line 19: | Line 17: |
| Add the lines below to your configuration file, for example /etc/mercurial/hgrc === Debian/Ubuntu === |
|
| Line 25: | Line 26: |
| === Fedora/RHEL === | |
| Line 31: | Line 33: |
| === openSUSE/SLE === Suse should already ship hg with included link to the ssl bundle, else use this global configuration: |
|
| Line 32: | Line 36: |
| On other platforms you can download a cacert file from http://curl.haxx.se/docs/caextract.html . The Mercurial-1.7.3 installers for Windows already contains a `misc\cacert.pem`. | {{{ [web] cacerts = /etc/ssl/ca-bundle.pem }}} === Mac OS X before 10.6 === You can generate the file you need by opening Keychain Access (from /Applications/Utilities), going to the System Roots keychain, selecting everything and then choosing `Export Items...` from the `File` menu. Make sure the `File Format` is set to `Privacy Enhanced Mail (.pem)`, then save it to your Desktop as `Certificates`. Next, in Terminal enter |
| Line 34: | Line 43: |
| You might want to modify the cacert file, for examply by removing CAs you don't trust or by adding your own internal or self-signed CAs. | {{{ sudo cp ~/Desktop/Certificates.pem /etc/hg-ca-roots.pem }}} then configure Mercurial as follows: {{{ [web] cacerts = /etc/hg-ca-roots.pem }}} Note that because the vendor supplied set of CA root certificates on Mac OS X is in the system keychain, you may wish to repeat these steps after installing software updates if they include changes to the root certificate list. === Mac OS X 10.6 and higher === On Mac OS X 10.6 and higher, OpenSSL (which is what Python and therefore Mercurial use to implement their SSL support) will look in the system keychain. Unfortunately, the SSL code in the Python core doesn't allow for this situation---it always expects you to specify a certificate bundle, and if one is specified if must contain at least one certificate. A simple way to deal with this problem is to enter (in Terminal) {{{ openssl req -new -x509 -extensions v3_ca -keyout /dev/null -out dummycert.pem -days 3650 }}} to generate a dummy certificate (the contents don't matter, so you can just hit return at all of the prompts), then {{{ sudo cp dummycert.pem /etc/hg-dummy-cert.pem }}} and set your configuration as follows: {{{ [web] cacerts = /etc/hg-dummy-cert.pem }}} Don't download a dummy certificate someone on the Internet has created to solve this problem unless you're certain that they're trustworthy; if they kept the private key, they would be able to sign certificates that Mercurial would trust. Better just to enter the commands above. If you have trouble getting a dummy certificate to work, see below on how to work around the issue with host certificate fingerprints. === Windows === The Windows installer for Mercurial 1.7.3 (and corresponding !TortoiseHg installers) are now safe by default. They now check the validity of the identity of the server you connect to with the root certificates. The Windows installers for Mercurial 1.7.3 (and corresponding !TortoiseHg installers) contain a `cacert.pem` and by default configure `web.cacerts` in `hgrc.d\paths.rc` . Note that per the default settings installed, connect to repositories with self-signed certificates fail with 1.7.3. You need to adjust the default configuration for that case. === Other platforms === If your platform doesn't provide a usable CA list, you can download a cacert file from http://curl.haxx.se/docs/caextract.html or some other trusted source. === Other Certificate Authorities === If want to trust other CAs you must make sure their '''root''' certificates are in your web.cacerts. For example, in order to use certificates from by [[http://cacert.org|cacert.org]] you need to download their [[http://www.cacert.org/index.php?id=3|root certificate in PEM format]] and configure Mercurial to use that certificate. === Self-signed certificates === You might want to tweak your cacert file, for example by removing CAs you don't trust or by adding your own internal or self-signed CAs. Only one cacerts file can be specified at any time, so you might want to override `web.cacerts` in your user or repository configuration. The root CA certificate for a server can for example be retrieved with Firefox. Browse to `https://server/repo` and verify that this is the repository you trust, click the lock symbol in the lower right corner, View Certificate, Details, select the certificate at the top of the Certificate Hierarchy, Export, "X.509 Certificate (PEM)" and save somewhere for example as `server.pem`. With other browsers on Windows you have to view the certificate at the top of the Certification Path and "Copy to File" as "Base-64 encoded X.509 (.CER)". Several such files can be concatenated into one cacerts file. Note: Self-signed certificates generated by IIS7 might not work with OpenSSL/Python as used by Mercurial. They do apparently have different opinions on what a valid CA certificate should contain. Instead, use openssl to create your server certificate and your CA certificate. {i} The content of a single PEM encoded certificate can be seen with . {{{ openssl x509 -in server.pem -text }}} |
| Line 37: | Line 99: |
| If you want to control explicitly which servers you will authenticate to and pull from you can explicitly configure the trusted servers identity for each local clone. | If you want to control more explicitly who can impersonate which servers you will authenticate to and pull from you can explicitly configure the trusted CAs for each local clone. |
| Line 39: | Line 101: |
| The server's public identity can for example be retrieved with Firefox. Browse to `https://server/repo`, click the lock symbol in the lower right corner, View Certificate, Details, Export, "X.509 Certificate (PEM)" and save somewhere as server.pem. In your local repo edit .hg/hgrc and add |
In your local repository add the following to your `.hg/hgrc`: |
| Line 47: | Line 107: |
| Line 50: | Line 109: |
| == Packaging == Packagers are encouraged to integrate as good as possible with the platforms existing PKI, for example by distributing a `hgrc.d/cacert.rc` with configuration of `web.cacerts`. If the platform don't have a suitable CA list you might want to distribute your own - for example the one from cURL/Mozilla. |
== Host certificate fingerprints == With Mercurial 1.7.4 a new method for verification of server identify was introduced. The warnings given for insecure https connections will show the fingerprint of the server certificate, and when such a fingerprint is configured for a hostname in the [[http://www.selenic.com/mercurial/hgrc.5.html#hostfingerprints|hostfingerprints]] section Mercurial will verify for all connections to that server that its certificate matches the fingerprint. |
| Line 53: | Line 112: |
| Note however that that will cause a regression for those who connect to servers with self-signed certificates. It should thus not be introduced in a bugfix release but wait for a major update, depending on how your update strategy is. | For example, for https://hg.intevation.org/mercurial/crew+main/ : {{{ [hostfingerprints] hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc }}} == Manually bypassing security checks on self-signed certificates == /!\ This is obviously insecure. Sometimes it may be expedient to disable security checks, for instance when dealing with hosts with self-signed certificates. This can be done by disabling the CA certificate configuration on the command line: {{{ hg push --config web.cacerts= https://self-signed-host/repo }}} A `--insecure` option was introduced with Mercurial 1.7.5 so you can do: {{{ hg push --insecure https://self-signed-host/repo }}} == HTTP proxy support == Mercurial 1.8 will also verify certificates for HTTPS connections made with CONNECT through HTTP proxies. == SMTP TLS certificates == Mercurial does not currently verify TLS certificates for SMTP. |
| Line 56: | Line 138: |
| * http://docs.python.org/library/ssl.html#ssl-certificates | |
| Line 59: | Line 142: |
---- [[JapaneseCACertificates|日本語]] |
CA Certificates
About Mercurial's handling of SSL certificates for https urls.
Contents
1. Changes in Mercurial 1.7.x
Mercurial has improved its HTTPS support in the 1.7.x series. When connecting to an HTTPS server, it will now verify the server's certificate correctly and reject the connection if the server identity can't be confirmed - but only if Certification Authorities (CAs) have been configured. As of 1.7.3, Mercurial will warn if CAs haven't been configured.
The new "certificate not verified" warning does not mean that you are less secure than before. It just informs you of how insecure you have always been.
You should fix your setup so you get the security you might expect from SSL and don't get any warnings; otherwise you might just as well stop using HTTPS.
2. Configuration of HTTPS certificate authorities
Most operating systems maintain a set of root certificates that you might decide to trust. Note that any of these authorities can approve any server identity, and any of them will thus be able to spoof any server identity.
Add the lines below to your configuration file, for example /etc/mercurial/hgrc
2.1. Debian/Ubuntu
On Debian and Ubuntu you can use this global configuration:
[web] cacerts = /etc/ssl/certs/ca-certificates.crt
2.2. Fedora/RHEL
On Fedora and RHEL you can use this global configuration:
[web] cacerts = /etc/pki/tls/certs/ca-bundle.crt
2.3. openSUSE/SLE
Suse should already ship hg with included link to the ssl bundle, else use this global configuration:
[web] cacerts = /etc/ssl/ca-bundle.pem
2.4. Mac OS X before 10.6
You can generate the file you need by opening Keychain Access (from /Applications/Utilities), going to the System Roots keychain, selecting everything and then choosing Export Items... from the File menu. Make sure the File Format is set to Privacy Enhanced Mail (.pem), then save it to your Desktop as Certificates. Next, in Terminal enter
sudo cp ~/Desktop/Certificates.pem /etc/hg-ca-roots.pem
then configure Mercurial as follows:
[web] cacerts = /etc/hg-ca-roots.pem
Note that because the vendor supplied set of CA root certificates on Mac OS X is in the system keychain, you may wish to repeat these steps after installing software updates if they include changes to the root certificate list.
2.5. Mac OS X 10.6 and higher
On Mac OS X 10.6 and higher, OpenSSL (which is what Python and therefore Mercurial use to implement their SSL support) will look in the system keychain. Unfortunately, the SSL code in the Python core doesn't allow for this situation---it always expects you to specify a certificate bundle, and if one is specified if must contain at least one certificate. A simple way to deal with this problem is to enter (in Terminal)
openssl req -new -x509 -extensions v3_ca -keyout /dev/null -out dummycert.pem -days 3650
to generate a dummy certificate (the contents don't matter, so you can just hit return at all of the prompts), then
sudo cp dummycert.pem /etc/hg-dummy-cert.pem
and set your configuration as follows:
[web] cacerts = /etc/hg-dummy-cert.pem
Don't download a dummy certificate someone on the Internet has created to solve this problem unless you're certain that they're trustworthy; if they kept the private key, they would be able to sign certificates that Mercurial would trust. Better just to enter the commands above.
If you have trouble getting a dummy certificate to work, see below on how to work around the issue with host certificate fingerprints.
2.6. Windows
The Windows installer for Mercurial 1.7.3 (and corresponding TortoiseHg installers) are now safe by default. They now check the validity of the identity of the server you connect to with the root certificates.
The Windows installers for Mercurial 1.7.3 (and corresponding TortoiseHg installers) contain a cacert.pem and by default configure web.cacerts in hgrc.d\paths.rc . Note that per the default settings installed, connect to repositories with self-signed certificates fail with 1.7.3. You need to adjust the default configuration for that case.
2.7. Other platforms
If your platform doesn't provide a usable CA list, you can download a cacert file from http://curl.haxx.se/docs/caextract.html or some other trusted source.
2.8. Other Certificate Authorities
If want to trust other CAs you must make sure their root certificates are in your web.cacerts. For example, in order to use certificates from by cacert.org you need to download their root certificate in PEM format and configure Mercurial to use that certificate.
2.9. Self-signed certificates
You might want to tweak your cacert file, for example by removing CAs you don't trust or by adding your own internal or self-signed CAs. Only one cacerts file can be specified at any time, so you might want to override web.cacerts in your user or repository configuration.
The root CA certificate for a server can for example be retrieved with Firefox. Browse to https://server/repo and verify that this is the repository you trust, click the lock symbol in the lower right corner, View Certificate, Details, select the certificate at the top of the Certificate Hierarchy, Export, "X.509 Certificate (PEM)" and save somewhere for example as server.pem. With other browsers on Windows you have to view the certificate at the top of the Certification Path and "Copy to File" as "Base-64 encoded X.509 (.CER)". Several such files can be concatenated into one cacerts file.
Note: Self-signed certificates generated by IIS7 might not work with OpenSSL/Python as used by Mercurial. They do apparently have different opinions on what a valid CA certificate should contain. Instead, use openssl to create your server certificate and your CA certificate.
The content of a single PEM encoded certificate can be seen with
openssl x509 -in server.pem -text
3. Per-repository configuration
If you want to control more explicitly who can impersonate which servers you will authenticate to and pull from you can explicitly configure the trusted CAs for each local clone.
In your local repository add the following to your .hg/hgrc:
[web] cacerts = /path/to/server.pem
Note: This requires Mercurial 1.7.3 or later.
4. Host certificate fingerprints
With Mercurial 1.7.4 a new method for verification of server identify was introduced. The warnings given for insecure https connections will show the fingerprint of the server certificate, and when such a fingerprint is configured for a hostname in the hostfingerprints section Mercurial will verify for all connections to that server that its certificate matches the fingerprint.
For example, for https://hg.intevation.org/mercurial/crew+main/ :
[hostfingerprints] hg.intevation.org = 38:76:52:7c:87:26:9a:8f:4a:f8:d3:de:08:45:3b:ea:d6:4b:ee:cc
5. Manually bypassing security checks on self-signed certificates
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
This is obviously insecure.
Sometimes it may be expedient to disable security checks, for instance when dealing with hosts with self-signed certificates. This can be done by disabling the CA certificate configuration on the command line:
hg push --config web.cacerts= https://self-signed-host/repo
A --insecure option was introduced with Mercurial 1.7.5 so you can do:
hg push --insecure https://self-signed-host/repo
6. HTTP proxy support
Mercurial 1.8 will also verify certificates for HTTPS connections made with CONNECT through HTTP proxies.
7. SMTP TLS certificates
Mercurial does not currently verify TLS certificates for SMTP.