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 <p>The https push facility relies on user client authentication certificates to
   8 enable pushing.  These certificates are automatically created whenever an
   9 RSA SSH public key is included in the &#x201c;Public SSH Key(s)&#x201d; section
  10 of the <a href="/reguser.cgi">Register user</a> page and may be downloaded
  11 from the download link(s) shown on the user registration confirmation page
  12 or the <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  13
  14 <h2>Prerequisites</h2>
  15
  16 <p>Assuming the user login name is <tt>test</tt> and the
  17 <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>
  18 has been downloaded to <tt>/tmp/@@nickname@@_root_cert.pem</tt> (see
  19 <a href="@@path(htmlurl)@@/rootcert.html">here</a> for more information about the
  20 <a href="@@path(webadmurl)@@/@@nickname@@_root_cert.pem">root certificate</a>),
  21 the single RSA SSH public key from <tt>~/.ssh/id_rsa.pub</tt> has been uploaded
  22 as the sole public key for the <tt>test</tt> user and the resulting
  23 <tt>test</tt> user authentication certifcate has been downloaded to
  24 <tt>/tmp/@@nickname@@_test_user_1.pem</tt>, the following
  25 shows how to clone and then push to a <tt>mobexample.git</tt> project using
  26 only the smart HTTP protocol.</p>
  27
  28 <p>A user authentication certificate may be downloaded from the
  29 <a href="/reguser.cgi">Register user</a> confirmation page or the
  30 <a href="/edituser.cgi">Update user email/SSH Keys</a> page.</p>
  31
  32 <h2>Example</h2>
  33
  34 <p>It&#x2019;s possible to both fetch and push over https.  It&#x2019;s also
  35 possible to fetch over http and push over https.  There&#x2019;s an example
  36 of each.</p>
  37
  38 <pre style="margin:3ex">
  39 # the @@nickname@@ root certificate is in /tmp/@@nickname@@_root_cert.pem
  40 # the test user certificate is in /tmp/@@nickname@@_test_user_1.pem
  41 # the ~/.ssh/id_rsa.pub SSH public key was uploaded
  42 # the ~/.ssh/id_rsa file is the ~/.ssh/id_rsa.pub private key
  43
  44 # work in /tmp
  45 cd /tmp
  46
  47 # clone using http
  48 git clone @@httppullurl@@/mobexample.git mob1
  49
  50 # clone using https
  51 GIT_SSL_CAINFO=/tmp/@@nickname@@_root_cert.pem \
  52 git clone @@httpspushurl@@/mobexample.git mob2
  53
  54 # configure mob1 to push over https
  55 cd /tmp/mob1
  56 git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem
  57 git config http.sslCert /tmp/@@nickname@@_test_user_1.pem
  58 git config http.sslKey ~/.ssh/id_rsa
  59 git remote set-url --push origin @@httpspushurl@@/mobexample.git
  60 echo mob1 >> mob1
  61 git add mob1
  62 git commit -m mob1
  63 # push will fail because test does not have push permission
  64 git push --all origin
  65
  66 # configure mob2 to fetch and push over https
  67 cd /tmp/mob2
  68 git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem
  69 git config http.sslCert /tmp/@@nickname@@_test_user_1.pem
  70 git config http.sslKey ~/.ssh/id_rsa
  71 echo mob2 >> mob2
  72 git add mob2
  73 git commit -m mob2
  74 # push will fail because test does not have push permission
  75 git push --all origin
  76 </pre>
  77
  78 <p>The example <tt>git push</tt> commands above will fail with a push permission
  79 error since the test user does not have permission to push to the
  80 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
  81 <tt>mobexample.git</tt> over https as detailed
  82 <a href="@@path(htmlurl)@@/mob.html#httpsmobpush">here</a>@@end@@.
  83
  84 <h2>Password Caching</h2>
  85
  86 <p>In the above examples, if the <tt>~/.ssh/id_rsa</tt> private key is password
  87 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
  88 to true like so:</p>
  89
  90 <pre style="margin:3ex">
  91 # with the current directory /tmp/mob1 or /tmp/mob2
  92 git config --bool http.sslCertPasswordProtected true
  93 </pre>