Overview

The https push facility relies on user client authentication certificates to enable pushing. These certificates are automatically created whenever an RSA SSH public key is included in the “Public SSH Key(s)” section of the Register user page and may be downloaded from the download link(s) shown on the user registration confirmation page or the Update user email/SSH Keys page.

A user client certificate is NOT required to fetch using https.

An https push user authentication certificate may be downloaded from the Register user confirmation page or the Update user email/SSH Keys page.

Instructions

Note: These instructions are for modern Gits. If you have an ancient Git (i.e. prior to version 1.8.5) see the alternate instructions below.

0. Quick Overview

  1. Download your user certificate from the Register user confirmation page or the Update user email/SSH Keys page.
  2. Identify the file containing your private key and make sure it’s in a compatible format.
  3. Perform one-time Git global configuration of the user certificate (http.sslCert) and private key (http.sslKey) but only for URLs starting with “https://repo.or.cz”.

1. Download your user certificate

You must register an RSA public key using either the Register user page or the Update user email/SSH Keys page.

Your user push certificate for that RSA public key can then be downloaded from the register user confirmation page or the edit user page.

Please note that if you use ssh, you may already have a suitable RSA public key stored in the “$HOME/.ssh/id_rsa.pub” file.

If you do not already have a suitable RSA public key (or you want to use a different one for this site) you will need to generate a new RSA key and then register the public key portion using either the Register user page or the Update user email/SSH Keys page.

A new RSA key (both public and private parts) can be generated using the “ssh-keygen -t rsa” command (from OpenSSH) or using a combination of the “openssl genrsa” command (from OpenSSL) and the “ConvertPubKey” command (from EZCert).

Download your https push user certificate and store it in the “$HOME/certs” directory. The downloaded user certificate file will have a name like “rorcz_name_user_1.pem” where “name” is the user name you registered the public key for (the downloaded user certificate file may also have a suffix other than “_1” if you’ve registered more than one public key).

2. Locate your private key and check its format

If you registered “$HOME/.ssh/id_rsa.pub” as your public key then your corresponding private key can most likely be found in “$HOME/.ssh/id_rsa”.

If you’re using a different RSA public key, you will need the full path to the corresponding private key portion for the next step.

Check the format of your private key. If it’s not in the file “$HOME/.ssh/id_rsa”, adjust the following commands accordingly. Run this command:

head -n 1 "$HOME/.ssh/id_rsa"

If the output is either of these lines:

-----BEGIN RSA PRIVATE KEY-----
-----BEGIN ENCRYPTED PRIVATE KEY-----

Then you’re good to go.

If the output is “-----BEGIN OPENSSH PRIVATE KEY-----” then you must convert it to one of the other two formats before it can be used for https pushing.

If the output of “ssh -V” shows a version of at least 8.1p1 then the recommended format to use is “PKCS8” (although you may alternatively use the older “PEM” format if desired) and you can convert your private key file like so:

ssh-keygen -p -m PKCS8 -f "$HOME/.ssh/id_rsa"

If the output of “ssh -V” shows a version prior to 8.1p1 then you must use the “PEM” format and you can convert your private key file like so:

ssh-keygen -p -m PEM -f "$HOME/.ssh/id_rsa"

3. Perform Git global configuration

Please note that these configuration steps will only be effective for modern Gits (version 1.8.5 or later). If you’re dealing with an ancient Git see the alternate instructions.

Assuming the user certificate has been downloaded and stored in “$HOME/certs” and the private key is located in “$HOME/.ssh/id_rsa”, the following will configure Git’s “http.sslCert” and “http.sslKey” settings but only for URLs starting with “https://repo.or.cz”:

git config --global http.https://repo.or.cz.sslCert \
                    "$HOME/certs/rorcz_name_user_1.pem"

git config --global http.https://repo.or.cz.sslKey \
                    "$HOME/.ssh/id_rsa"

Your git is now configured and ready to push to this site using an https push URL (presuming your user has push permission to the project you’re pushing to). See the examples below.

If your RSA private key is password protected, you may want to also set the following to avoid overly repetitious entering of the private key’s password:

git config --global http.https://repo.or.cz.sslCertPasswordProtected true

OS X Note: Users of OS X 10.9 and later (including 10.10 etc.) please be advised that the system’s curl library (“/usr/lib/libcurl.4.dylib”) has problems handling client certificates. If you’re using a version of Git that uses that version of the curl library (Git uses libcurl to talk https), you will be unable to use any downloaded https user push certificate. If you think you might be affected, you can test your Git and if you have a problem, install a Git without the problem instead. (Reportedly this issue MAY have been addressed starting with Mac OS X 10.13, but it doesn't hurt to test your Git just to be sure.)

Examples

It’s possible to both fetch and push over https. It’s also possible to fetch over http and push over https. There’s an example of each. Both examples assume Git has already been configured as described in the instructions.

# clone using http
git clone https://repo.or.cz/mobexample.git mob1

# clone using https
git clone https://repo.or.cz/mobexample.git mob2

# configure mob1 to push over https
cd /tmp/mob1
git remote set-url --push origin https://repo.or.cz/mobexample.git
echo mob1 >> mob1
git add mob1
git commit -m mob1
# push will fail unless your user has push permission
git push --all origin

# configure mob2 to fetch and push over https
cd /tmp/mob2
# nothing needs to be done, the clone & global config took care of it
echo mob2 >> mob2
git add mob2
git commit -m mob2
# push will fail unless your user has push permission
git push --all origin

Alternative Git Configuration Techniques

These techniques work with Git version 1.6.6 and later (versions of Git prior to 1.6.6 lack the required smart HTTP protocol support).

# work in /tmp
cd /tmp

# clone using http
git clone https://repo.or.cz/mobexample.git mob1

# clone using https
git clone https://repo.or.cz/mobexample.git mob2

# configure mob1 to push over https
cd /tmp/mob1
# omitting --global makes these settings repository specific
git config http.sslCert $HOME/certs/rorcz_name_user_1.pem
git config http.sslKey $HOME/.ssh/id_rsa
git remote set-url --push origin https://repo.or.cz/mobexample.git
echo mob1 >> mob1
git add mob1
git commit -m mob1
# push will fail unless your user has push permission
git push --all origin

# configure mob2 to fetch and push over https
cd /tmp/mob2
git config http.sslCert $HOME/certs/rorcz_name_user_1.pem
git config http.sslKey $HOME/.ssh/id_rsa
echo mob2 >> mob2
git add mob2
git commit -m mob2
# push will fail unless your user has push permission
git push --all origin

The example git push commands above will fail with a push permission error since your user most likely does not have permission to push to the mobexample.git project, but the mob user can push to the mob branch of mobexample.git over https as detailed here.

Password Caching

In the above examples, if the “$HOME/.ssh/id_rsa” private key is password protected, then it’s desirable to set http.sslCertPasswordProtected to true like so:

# with the current directory /tmp/mob1 or /tmp/mob2
git config --bool http.sslCertPasswordProtected true
(view source)