html/rootcert.html

   1 @section=site guide
   2 @heading=Root Certificate
   3 @header
   4
   5 <!-- This file is preprocessed by cgi/html.cgi -->
   6
   7 <h2>Overview</h2>
   8
   9 <div class="indent">
  10 <p>This site provides https support in order to support the Git smart HTTP
  11 push protocol.</p>
  12
  13 <p>This obviously requires this site to have an SSL server certificate.  In order
  14 to avoid the hassle (and the continual renewal burden) of getting an SSL server
  15 certificate that has been signed by a root certificate already included (and trusted)
  16 by your browser, this site uses its own root certificate.</p>
  17
  18 <p>Git version 1.8.5 and later can quickly and easily be configured (see the
  19 &#x201c;Quick Setup&#x201d; section below) to use this root certificate ONLY
  20 for connections to @@base(httpspushurl)@@.  This configuration is the equivalent
  21 of answering &#x201c;yes&#x201d; to the ssh &#x201c;Are you sure you want to
  22 continue connecting?&#x201d; prompt when you first connect to a new ssh server.</p>
  23
  24 <p>The root certificate for this site (@@base(httpspushurl)@@) is available from:</p>
  25 <div class="indent">
  26 <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">@@server(webadmurl)@@/@@nickname@@_root_cert.pem</a>
  27 <br />
  28 md5: <tt>@@md5(@@nickname@@_root_cert.pem)@@</tt>
  29 <br />
  30 sha1: <tt>@@sha1(@@nickname@@_root_cert.pem)@@</tt>
  31 <br />
  32 blob: <tt>@@blob(@@nickname@@_root_cert.pem)@@</tt>
  33 </div>
  34
  35 <p>See also the <a href="@@path(htmlurl)@@/httpspush.html">full instructions on configuring your Git client for https push</a>.</p>
  36 @@ifmob@@
  37 <p>For information on how to push to the mob branch using https see <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>.</p>
  38 @@end@@
  39 </div>
  40
  41 <h2 id="quick">Quick Setup</h2>
  42 <div class="indent">
  43 <p>These instructions require Git version 1.8.5 or later.</p>
  44 <p>The following shell commands (which can be copied and pasted into a terminal window)
  45 will download the root certificate to <tt>~/certs/@@nickname@@_root_cert.pem</tt>
  46 using <tt>curl</tt> and then configure Git to use it ONLY for connections to @@base(httpspushurl)@@.</p>
  47 <pre class="indent">
  48 mkdir -p ~/certs
  49 cd ~/certs
  50 curl -kO @@base(httpspushurl)@@/@@nickname@@_root_cert.pem
  51 git config --global http.@@base(httpspushurl)@@.sslCAInfo \
  52   ~/certs/@@nickname@@_root_cert.pem
  53 git hash-object --no-filters ~/certs/@@nickname@@_root_cert.pem
  54 </pre>
  55 <p>Verify that the hash value output by <tt>git hash-object</tt> matches
  56 the &#x201c;blob:&#x201d; hash value shown at the top of this page.</p>
  57 </div>
  58
  59 <h2 id="details">Details</h2>
  60 <div class="indent">
  61 <p>A side effect of using an unrecognized root certificate is that Git may
  62 complain with an error such as:</p>
  63 <blockquote>
  64 <tt>error: server certificate verification failed</tt>
  65 </blockquote>
  66
  67 <p>To see this error in action, simply execute this git command:</p>
  68 <blockquote><pre>
  69 git ls-remote @@httpspushurl@@/girocco.git
  70 </pre></blockquote>
  71
  72 <p>Instead of downloading the server&#x2019;s root certificate, server certificate verification may be disabled with one of these techniques:</p>
  73
  74 <ol>
  75 <li>Set the <tt>GIT_SSL_NO_VERIFY</tt> environment variable like so:
  76 <pre>
  77 GIT_SSL_NO_VERIFY=1 git ls-remote @@httpspushurl@@/girocco.git
  78 </pre></li>
  79
  80 <li>Temporarily set the git configuration variable <tt>http.sslVerify</tt> like so:
  81 <pre>
  82 git -c http.sslVerify=false \
  83 ls-remote @@httpspushurl@@/girocco.git
  84 </pre>
  85 <p>Note that the <tt>-c</tt> option requires Git version 1.7.2 or later.</p></li>
  86 </ol>
  87
  88 <p>Or, after downloading the root certificate for this site, the error may be
  89 avoided through various methods by specifying the root certificate.<br />
  90 For each of these methods, the root certificate will be assumed to be downloaded
  91 and saved to the file <tt>$HOME/certs/@@nickname@@_root_cert.pem</tt>.</p>
  92
  93 <p id="git185">Using Git version 1.8.5 or later (recommended):</p>
  94
  95 <ol>
  96 <li>Configure the global <tt>http.sslCAInfo</tt> variable but only for this site like so:
  97 <pre>
  98 git config --global http.@@base(httpspushurl)@@.sslCAInfo \
  99                     $HOME/certs/@@nickname@@_root_cert.pem
 100 </pre>
 101 <p>Note that this technique requires Git version 1.8.5 or later on the client but has the advantage of only needing to be done once.</p></li>
 102 </ol>
 103
 104 <p>Using any version of Git:</p>
 105
 106 <ol start="2">
 107 <li>Set the <tt>GIT_SSL_CAINFO</tt> environment variable before running git like so:
 108 <pre>
 109 GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
 110 git ls-remote @@httpspushurl@@/girocco.git
 111 </pre></li>
 112
 113 <li>Temporarily set the git configuration variable <tt>http.sslCAInfo</tt> like so:
 114 <pre>
 115 git -c http.sslCAInfo=$HOME/certs/@@nickname@@_root_cert.pem \
 116 ls-remote @@httpspushurl@@/girocco.git
 117 </pre></li>
 118
 119 <li>Configure the git <tt>http.sslCAInfo</tt> variable like so:
 120 <pre>
 121 git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
 122 </pre>
 123 <p>Note that this technique works best after the repository has already been cloned
 124 or initialized.</p></li>
 125 </ol>
 126
 127 <p>For further details see the <tt>git help config</tt> output.</p>
 128 </div>