html/httpspush.html

   1 @section=site guide
   2 @heading=How to Setup HTTPS Push
   3 @header
   4
   5 <!-- This file is preprocessed by cgi/html.cgi -->
   6
   7 <h2>Overview</h2>
   8
   9 <div class="indent">
  10 <p>The https push facility relies on user client authentication certificates to
  11 enable pushing.  These certificates are automatically created whenever an
  12 RSA SSH public key is included in the &#x201c;Public SSH Key(s)&#x201d; section
  13 of the <a href="/reguser.cgi">Register user</a> page and may be downloaded
  14 from the download link(s) shown on the user registration confirmation page
  15 or the <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  16
  17 <p>A user client certificate is <em>NOT</em> required to fetch using https@@ifcustom@@, but you will
  18 likely need to configure the root certificate (if you haven&#x2019;t already done so).  See
  19 <a href="rootcert.html#quick">the instructions to quickly and easily configure the root certificate</a>
  20 if you only want to fetch over https and don&#x2019;t currently need to push@@end@@.</p>
  21
  22 <p style="border:thin dotted black;background-color:#eef;padding:0.5ex 1ex;max-width:90ex">An
  23 https push user authentication certificate may be downloaded from the
  24 <a href="/reguser.cgi">Register user</a> confirmation page or the
  25 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  26 </div>
  27
  28 <h2 id="instructions">Instructions</h2>
  29
  30 <div class="indent">
  31 <p><b>Note</b>: These instructions are for modern Gits.  If you have
  32 an ancient Git (i.e. prior to version 1.8.5) see the
  33 <a href="#alternate">alternate instructions</a> below.</p>
  34 </div>
  35
  36 <h3>0. Quick Overview</h3>
  37 <div>
  38 <ol>
  39 @@ifcustom@@
  40 <li>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>.</li>
  41 @@end@@
  42 <li>Download your user certificate from the <a href="/reguser.cgi">Register user</a>
  43 confirmation page or the <a href="/edituser.cgi">Update user email/SSH Keys</a>
  44 page.</li>
  45 <li>Identify the file containing your private key.</li>
  46 <li>Perform one-time Git global configuration of the @@ifcustom@@root certificate (<tt>http.sslCAInfo</tt>),@@end@@
  47 user certificate (<tt>http.sslCert</tt>) and private key (<tt>http.sslKey</tt>) but <em>only</em>
  48 for URLs starting with "<tt>@@base(httpspushurl)@@</tt>".</li>
  49 </ol>
  50 </div>
  51
  52 @@ifcustom@@
  53 <h3>@@ctr()@@. Download the root certificate</h3>
  54
  55 <div class="indent">
  56 <p>Download the <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>
  57 (more information about it can be found <a href="@@path(htmlurl)@@/rootcert.html">here</a>).</p>
  58
  59 <p>Assuming the root certificate will be stored in "<tt>$HOME/certs</tt>" it may be
  60 downloaded like so:</p>
  61
  62 <pre class="indent">
  63 mkdir -p "$HOME/certs"
  64 cd "$HOME/certs"
  65 curl -LO "@@server(webadmurl)@@/@@nickname@@_root_cert.pem"
  66 </pre>
  67 </div>
  68 @@end@@
  69
  70 <h3>@@ctr()@@. Download your user certificate</h3>
  71
  72 <div class="indent">
  73 <p>You must register an RSA public key using either the
  74 <a href="/reguser.cgi">Register user</a> page or the
  75 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  76
  77 <p>Your user push certificate for that RSA public key can then be
  78 downloaded from the register user confirmation page or the edit
  79 user page.</p>
  80
  81 <p>Please note that if you use ssh, you may already have a suitable RSA
  82 public key stored in the "<tt>$HOME/.ssh/id_rsa.pub</tt>" file.</p>
  83
  84 <p>If you do not already have a suitable RSA public key (or you want to use
  85 a different one for this site) you will need to
  86 generate a new RSA key and then register the public key portion using either
  87 the <a href="/reguser.cgi">Register user</a> page or the
  88 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  89
  90 <p>A new RSA key (both public and private parts) can be generated using the
  91 "<tt>ssh-keygen -t rsa</tt>" command (from OpenSSH) or using a combination of
  92 the "<tt>openssl genrsa</tt>" command (from OpenSSL) and the
  93 "<tt><a href="https://repo.or.cz/ezcert.git/blob/HEAD:/ConvertPubKey#l173">ConvertPubKey</a></tt>"
  94 command (from <a href="https://repo.or.cz/ezcert.git">EZCert</a>).</p>
  95
  96 <p>Download your https push user certificate and store it in the
  97 "<tt>$HOME/certs</tt>" directory.  The downloaded user certificate file will
  98 have a name like "<tt>@@nickname@@_</tt><i>name</i><tt>_user_1.pem</tt>" where
  99 "<i>name</i>" is the user name you registered the public key for (the downloaded
 100 user certificate file may also have a suffix other than "<tt>_1</tt>" if
 101 you&#x2019;ve registered more than one public key).</p>
 102 </div>
 103
 104 <h3>@@ctr()@@. Locate your private key</h3>
 105
 106 <div class="indent">
 107 <p>If you registered "<tt>$HOME/.ssh/id_rsa.pub</tt>" as your public key then
 108 your corresponding private key can most likely be found in
 109 "<tt>$HOME/.ssh/id_rsa</tt>".</p>
 110
 111 <p>If you&#x2019;re using a different RSA public key, you will need the full
 112 path to the corresponding private key portion for the next step.</p>
 113 </div>
 114
 115 <h3>@@ctr()@@. Perform Git global configuration</h3>
 116
 117 <div class="indent">
 118 <p>Please note that these configuration steps will only be effective for modern Gits
 119 (version 1.8.5 or later).  If you&#x2019;re dealing with an ancient Git see the
 120 <a href="#alternate">alternate instructions</a>.</p>
 121
 122 <p>Assuming @@ifcustom@@the root certificate has been downloaded and stored in "<tt>$HOME/certs</tt>",@@end@@
 123 the user certificate has been downloaded and stored in "<tt>$HOME/certs</tt>" and
 124 the private key is located in "<tt>$HOME/.ssh/id_rsa</tt>", the following will
 125 configure Git&#x2019;s @@ifcustom@@"<tt>http.sslCAInfo</tt>", @@end@@"<tt>http.sslCert</tt>" and "<tt>http.sslKey</tt>"
 126 settings but <em>only</em> for URLs starting with "<tt>@@base(httpspushurl)@@</tt>":</p>
 127
 128 <pre class="indent">
 129 @@ifcustom@@git config --global http.@@base(httpspushurl)@@.sslCAInfo \
 130                     "$HOME/certs/@@nickname@@_root_cert.pem"
 131
 132 @@end@@git config --global http.@@base(httpspushurl)@@.sslCert \
 133                     "$HOME/certs/@@nickname@@_<i>name</i>_user_1.pem"
 134
 135 git config --global http.@@base(httpspushurl)@@.sslKey \
 136                     "$HOME/.ssh/id_rsa"
 137 </pre>
 138
 139 <p>Your git is now configured and ready to push to this site using
 140 an https push URL (presuming your user has push permission to the project
 141 you&#x2019;re pushing to).  See the <a href="#examples">examples</a> below.</p>
 142
 143 <p>If your RSA private key is password protected, you may want to also set
 144 the following to avoid overly repetitious entering of the private key&#x2019;s
 145 password:</p>
 146
 147 <pre class="indent">
 148 git config --global http.@@base(httpspushurl)@@.sslCertPasswordProtected true
 149 </pre>
 150
 151 <p><b>OS X Note</b>: Users of OS X 10.9 and later (including 10.10 etc.) please
 152 be advised that the system&#x2019;s curl library ("<tt>/usr/lib/libcurl.4.dylib</tt>")
 153 has <a href="https://mackyle.github.io/git-osx-installer/iscurlsick.html#problem"
 154 >problems handling client certificates</a>.  If you&#x2019;re using a version of
 155 Git that uses that version of the curl library (Git uses libcurl to talk https),
 156 you will be unable to use any downloaded https user push certificate.  If you
 157 think you might be affected, you can
 158 <a href="https://mackyle.github.io/git-osx-installer/iscurlsick.html#gittest"
 159 >test your Git</a> and if you have a problem, install a
 160 <a href="https://mackyle.github.io/git-osx-installer/">Git without the problem</a>
 161 instead.  (Reportedly this issue MAY have been addressed starting with Mac OS X 10.13,
 162 but it doesn't hurt to <a href="https://mackyle.github.io/git-osx-installer/iscurlsick.html#gittest"
 163 >test your Git</a> just to be sure.)</p>
 164 </div>
 165
 166 <h2 id="examples">Examples</h2>
 167
 168 <div class="indent">
 169 <p>It&#x2019;s possible to both fetch and push over https.  It&#x2019;s also
 170 possible to fetch over http and push over https.  There&#x2019;s an example
 171 of each.  Both examples assume Git has already been configured as described
 172 in the <a href="#instructions">instructions</a>.</p>
 173
 174 <pre class="indent">
 175 # clone using http
 176 git clone @@httppullurl@@/mobexample.git mob1
 177
 178 # clone using https
 179 git clone @@httpspushurl@@/mobexample.git mob2
 180
 181 # configure mob1 to push over https
 182 cd /tmp/mob1
 183 git remote set-url --push origin @@httpspushurl@@/mobexample.git
 184 echo mob1 >> mob1
 185 git add mob1
 186 git commit -m mob1
 187 # push will fail unless your user has push permission
 188 git push --all origin
 189
 190 # configure mob2 to fetch and push over https
 191 cd /tmp/mob2
 192 # nothing needs to be done, the clone &amp; global config took care of it
 193 echo mob2 >> mob2
 194 git add mob2
 195 git commit -m mob2
 196 # push will fail unless your user has push permission
 197 git push --all origin
 198 </pre>
 199 </div>
 200
 201 <h2 id="alternate">Alternative Git Configuration Techniques</h2>
 202
 203 <div class="indent">
 204 <p>These techniques work with Git version 1.6.6 and later (versions of Git
 205 prior to 1.6.6 lack the required smart HTTP protocol support).</p>
 206
 207 <pre class="indent">
 208 # work in /tmp
 209 cd /tmp
 210
 211 # clone using http
 212 git clone @@httppullurl@@/mobexample.git mob1
 213
 214 # clone using https
 215 @@ifcustom@@GIT_SSL_CAINFO=$HOME/certs/@@nickname@@_root_cert.pem \
 216 @@end@@git clone @@httpspushurl@@/mobexample.git mob2
 217
 218 # configure mob1 to push over https
 219 cd /tmp/mob1
 220 # omitting --global makes these settings repository specific
 221 @@ifcustom@@git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
 222 @@end@@git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
 223 git config http.sslKey $HOME/.ssh/id_rsa
 224 git remote set-url --push origin @@httpspushurl@@/mobexample.git
 225 echo mob1 >> mob1
 226 git add mob1
 227 git commit -m mob1
 228 # push will fail unless your user has push permission
 229 git push --all origin
 230
 231 # configure mob2 to fetch and push over https
 232 cd /tmp/mob2
 233 @@ifcustom@@git config http.sslCAInfo $HOME/certs/@@nickname@@_root_cert.pem
 234 @@end@@git config http.sslCert $HOME/certs/@@nickname@@_<i>name</i>_user_1.pem
 235 git config http.sslKey $HOME/.ssh/id_rsa
 236 echo mob2 >> mob2
 237 git add mob2
 238 git commit -m mob2
 239 # push will fail unless your user has push permission
 240 git push --all origin
 241 </pre>
 242
 243 <p>The example <tt>git push</tt> commands above will fail with a push permission
 244 error since your user most likely does not have permission to push to the
 245 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
 246 <tt>mobexample.git</tt> over https as detailed
 247 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.</p>
 248 </div>
 249
 250 <h2>Password Caching</h2>
 251
 252 <div class="indent">
 253 <p>In the above examples, if the <tt>$HOME/.ssh/id_rsa</tt> private key is password
 254 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
 255 to true like so:</p>
 256
 257 <pre class="indent">
 258 # with the current directory /tmp/mob1 or /tmp/mob2
 259 git config --bool http.sslCertPasswordProtected true
 260 </pre>
 261 </div>