[Summary view] [Print] [Text view]

   1  @title Troubleshooting HTTPS
   2  @group config
   3  
   4  Detailed instructions for troubleshooting HTTPS connection problems.
   5  
   6  = Overview =
   7  
   8  If you're having trouble connecting to an HTTPS install of Phabricator, and
   9  particularly if you're receiving a "There was an error negotiating the SSL
  10  connection." error, this document may be able to help you diagnose and resolve
  11  the problem.
  12  
  13  Connection negotiation can fail for several reasons. The major ones are:
  14  
  15    - You have not added the the Certificate Authority as a trusted authority
  16      (this is the most common problem, and usually the issue for self-signed
  17      certificates).
  18    - The SSL certificate is signed for the wrong domain. For example, a
  19      certificate signed for `www.example.com` will not work for
  20      `phabricator.example.com`.
  21    - The server rejects TLSv1 SNI connections for the domain (this is
  22      complicated, see below).
  23  
  24  = Certificate Authority Problems =
  25  
  26  SSL certificates need to be signed by a trusted authority (called a Certificate
  27  Authority or "CA") to be accepted. If the CA for a certificate is untrusted, the
  28  connection will fail (this defends the connection from an eavesdropping attack
  29  called "man in the middle"). Normally, you purchase a certificate from a known
  30  authority and clients have a list of trusted authorities.
  31  
  32  You can self-sign a certificate by creating your own CA, but clients will not
  33  trust it by default. They need to add the CA as a trusted authority.
  34  
  35  For instructions on adding CAs, see `libphutil/resources/ssl/README`.
  36  
  37  If you'd prefer that `arc` not verify the identity of the server whatsoever, you
  38  can use the `https.blindly-trust-domains` setting. This will make it
  39  dramatically easier for adversaries to perform certain types of attacks, and is
  40  **strongly discouraged**:
  41  
  42    $ arc set-config https.blindly-trust-domains '["example.com"]'
  43  
  44  
  45  = Domain Problems =
  46  
  47  Verify the domain the certificate was issued for. You can generally do this
  48  with:
  49  
  50    $ openssl x509 -text -in <certificate>
  51  
  52  If the certificate was accidentally generated for, e.g. `www.example.com` but
  53  you installed Phabricator on `phabricator.example.com`, you need to generate a
  54  new certificate for the right domain.
  55  
  56  = SNI Problems =
  57  
  58  Server Name Identification ("SNI") is a feature of TLSv1 which works a bit like
  59  Apache VirtualHosts, and allows a server to present different certificates to
  60  clients who are connecting to it using different names.
  61  
  62  Servers that are not configured properly may reject TSLv1 SNI requests because
  63  they do not recognize the name the client is connecting with. This
  64  topic is complicated, but you can test for it by running:
  65  
  66    $ openssl s_client -connect example.com:443 -servername example.com
  67  
  68  Replace **both** instances of "example.com" with your domain. If you receive
  69  an error in `SSL23_GET_SERVER_HELLO` with `reason(1112)`, like this:
  70  
  71    CONNECTED(00000003)
  72    87871:error:14077458:SSL routines:SSL23_GET_SERVER_HELLO:reason(1112):
  73      /SourceCache/OpenSSL098/OpenSSL098-44/src/ssl/s23_clnt.c:602:
  74  
  75  ...it indicates server is misconfigured. The most common cause of this problem
  76  is an Apache server that does not explicitly name the Phabricator domain as a
  77  valid VirtualHost.
  78  
  79  This error occurs only for some versions of the OpenSSL client library
  80  (from v0.9.8r or earlier until 1.0.0), so only some users may experience it.