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">User Registration</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">User SSH Key Update</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="@@gitwebfiles@@/@@nickname@@_root_cert.pem">root certificate</a>
  18 has been downloaded to <tt>/tmp/@@nickname@@_root_cert.pem</tt> (see
  19 <a href="@@htmlurl@@/rootcert.html">here</a> for more information about the
  20 <a href="@@gitwebfiles@@/@@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 <h2>Example</h2>
  29
  30 <p>It&#x2019;s possible to both fetch and push over https.  It&#x2019;s also
  31 possible to fetch over http and push over https.  There&#x2019;s an example
  32 of each.</p>
  33
  34 <pre style="margin:3ex">
  35 # the @@nickname@@ root certificate is in /tmp/@@nickname@@_root_cert.pem
  36 # the test user certificate is in /tmp/@@nickname@@_test_user_1.pem
  37 # the ~/.ssh/id_rsa.pub SSH public key was uploaded
  38 # the ~/.ssh/id_rsa file is the ~/.ssh/id_rsa.pub private key
  39
  40 # work in /tmp
  41 cd /tmp
  42
  43 # clone using http
  44 git clone @@httppullurl@@/mobexample.git mob1
  45
  46 # clone using https
  47 GIT_SSL_CAINFO=/tmp/@@nickname@@_root_cert.pem \
  48 git clone @@httpspushurl@@/mobexample.git mob2
  49
  50 # configure mob1 to push over https
  51 cd /tmp/mob1
  52 git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem
  53 git config http.sslCert /tmp/@@nickname@@_test_user_1.pem
  54 git config http.sslKey ~/.ssh/id_rsa
  55 git remote set-url --push origin @@httpspushurl@@/mobexample.git
  56 echo mob1 >> mob1
  57 git add mob1
  58 git commit -m mob1
  59 # push will fail because test does not have push permission
  60 git push --all origin
  61
  62 # configure mob2 to fetch and push over https
  63 cd /tmp/mob2
  64 git config http.sslCAInfo /tmp/@@nickname@@_root_cert.pem
  65 git config http.sslCert /tmp/@@nickname@@_test_user_1.pem
  66 git config http.sslKey ~/.ssh/id_rsa
  67 echo mob2 >> mob2
  68 git add mob2
  69 git commit -m mob2
  70 # push will fail because test does not have push permission
  71 git push --all origin
  72 </pre>
  73
  74 <p>The example <tt>git push</tt> commands above will fail with a push permission
  75 error since the test user does not have permission to push to the
  76 <tt>mobexample.git</tt> project@@ifmob@@, but the mob user can push to the mob branch of
  77 <tt>mobexample.git</tt> over https as detailed
  78 <a href="@@htmlurl@@/mob.html#httpsmobpush">here</a>@@end@@.
  79
  80 <h2>Password Caching</h2>
  81
  82 <p>In the above examples, if the <tt>~/.ssh/id_rsa</tt> private key is password
  83 protected, then it&#x2019;s desirable to set <tt>http.sslCertPasswordProtected</tt>
  84 to true like so:</p>
  85
  86 <pre style="margin:3ex">
  87 # with the current directory /tmp/mob1 or /tmp/mob2
  88 git config --bool http.sslCertPasswordProtected true
  89 </pre>