As I mentioned in a recent post, I use Atlassian Stash to manage my git repositories. It has some great features especially when it comes to setting up user permissions. It also integrates with JIRA and SourceTree since they’re also Atlassian products.
I wanted to be able to use my repositories while I was on the go so, naturally, I wanted the transmission to be encrypted over HTTPS/SSL. Stash uses an Apache Tomcat server to serve up both the admin pages and the repositories themselves. It’s not totally clear on how to set up a self-signed SSL certificate on Windows (their documentation focuses on Mac’s, mostly) and there are a couple issues that they don’t even discuss.
This post covers how I generated the certificate, got Windows to trust it and set up git so that it could connect to both my Stash server and externally hosted servers such as github.
Let’s get to it.
What We’re Going To Do
1. Generate the certificate
2. Add it to Windows’ certificate store so we don’t get errors
3. Set up a custom certificate authority so git will trust your cert + other legitimate certificates
Note: If you just want to fix issues with git not trusting your cert, skip to part 2.
1. Generating a Self-Signed SSL Certificate
The first step is to generate the self-signed certificate. This part of the process is discussed in their documentation, so I’m not going to go into too much detail. However, there are a couple extra things that they don’t cover that will be helpful to know.
» How to run a command without logging in as another user
If you installed Stash under a separate, restricted user account (as their install guide recommends) you’ll have to generate your key under that user. In my case, the user I created is super restrictive and can’t even log on locally. This means it’s a bit of a pain to switch to them and log in with their desktop profile (which doesn’t exist) and run a command.
Most *nix systems have a command called switch user or
su that allows you to run commands as another user. Windows has a similar feature with the
To use it, you’ll have to start by running a command prompt as administrator:
- Open the Start Menu
- Type in the word “command”
- The search should find “Command Prompt”. Right click this item and select “Run as Administrator”
OK, so you have the command prompt running as an administrator, now we need to switch to the other user so we can generate the SSL certificate.
Type in the following command:
runas /user:computername\stashusername cmd
This is broken up into three parts:
- runas – This is the command that lets us run something as another user.
- /user:computername\stashusername – You have to change computername to the name of your computer and stashusername to the name of the account that stash runs under. You can find this info by running the net user command.
- cmd – This part tells it what program to run. In our case, we want to run a new command prompt window as this user.
You will then be prompted to enter the user’s password. Just type it in and hit enter. You may be alarmed that it doesn’t actually show anything as you type, that’s normal, though. It doesn’t look like anything is being typed in, but it’s remembering it.
Once you enter the password successfully, you’ll see another command prompt open with a title indicating it is being run as the other user. You can now run the keytool command in that window and it will be created under the other user. But wait! Check out the next section for how to extend the expiry of the certificate.
» How to change the expiry date of the SSL certificate
By default, the Java keytool generated a certificate that was only two months in duration for me. I didn’t want to have to go through this process and update my CA store (we’ll get to that in a minute) every two months. Fortunately, the keytool supports a command line argument called “-validity” that allows you to specify the number of days the cert will be valid for.
Your command should look like this:
"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA -validity 730
You’ll want to run that in the window you created above and then follow the second step of the instructions.
I’m not going to go into any more detail on setting up the cert since the rest should be covered in the instructions linked above.
2. Add the Cert to the Trusted Root CA Store
Ok, so you’ve got the cert installed and Stash responds to https requests. Great! But wait, if you check out the certificate details, you’ll notice that it’s not trusted. This is because you self-signed it and you’re not a legitimate SSL Certificate Authority or CA. That said, you can trick Windows into thinking you are by adding the certificate to the Trusted Root Certificate Authorities.
Ok, with that out of the way, let’s get started.
- Go to the https version of your Stash site in Firefox.
- If it tells you “This Connection is Untrusted”, click on “I Understand the Risks” and then “Add Exception…”.
- If not, click the padlock icon in the address bar and click on “More Information…”.
- Click the “View…” or “View Certificate” button and select the “Details” tab.
- Click “Export…” and save the file somewhere as, say, stash.crt.
- Open Windows’ “Manage Computer Certificates” tool. You can do this by going to Start->Run and typing “certmgr.msc”. Hit enter or click Ok.
- Navigate to the “Trusted Root Certification Authorities/Certificates” folder.
- Right-click on an empty area (it can’t be on an existing certificate) and choose All-Tasks>Import…
- Follow the instructions (defaults should be fine). Choose the file you saved from Firefox when it asks for it.
- Navigate to the https version of your Stash site in your browser. It should appear as a green secured icon (you may need to restart the browser).
3. Trust the SSL Cert in Git
Ok, so we have Windows accepting it, but git doesn’t use the Windows store when it looks up certificates. Fortunately, the .gitcofig file allows us to override the default behaviour by specifying a new certificate store to check.
You can technically add this to any level of gitconfig—whether in your project, or in the user or global gitconfig files. I opted for adding it to my user’s gitconfig file. This can be found in the same directory as your “My Documents” or “Downloads” folders with the name .gitconfig. This would typically be at C:\Users\YourWindowsUsername\.gitconfig.
Open this file in a text editor and add the following lines:
There, now you will be able to access your Stash repo with the self-signed SSL certificate, without git throwing SSL errors.
However, if you try to add, say, a GitHub repository or remote, it won’t work. This is because the sslCAInfo directive doesn’t seem to add to the list of CAs, it replaces them.
In order to get it working, we have to get a list of CA public SSL certificates and add ours into the mix. You can download the latest CA public certificates from here. This is just a text file that contains all of the latest Certificate Authority public certificates.
Once you have that file, open up the stash.crt file that you saved from Firefox and add a few newlines to the end of the file. Then, paste the entire contents of the Public CA certificates file at the end of it. This will essentially make a huge list of CA certificates in addition to your file.
Now, when git wants to check the validity of a site’s certificate, it will look it up in this file and will be able to find all the main public CA certs as well as your own self-signed Stash SSL cert.
That’s it! Now you should be able to run git and connect to your local Stash instance and to external sites such as GitHub over HTTPS.