Update FAQ with how to use a CA-issued certificate

[lewellyn]

There should be a mention of how to use a standard CA-issued PEM-format certificate (such as a wildcard certificate used for Apache HTTPD, Nginx, etc.) in the FAQ (as this does seem to be a generally unanswered question, from my trawling of the web earlier). All the documentation for serving SSL directly with Gitblit is regarding self-signed certificates (e.g. issued via the authority tool). Even if it starts off fairly rudimentary and has big old warning flags that it's for experts only, that hopefully will get clueful people to provide feedback on how to make it more beginner-friendly.

In an effort to make this a reality, here's some helpful information. :)

• To convert a key from the standard PEM + key format used by most traditional webservers into something Java can use:
  1. openssl pkcs12 -export -in /path/to/certs/yourdomain.pem -inkey /path/to/keys/yourdomain.key > yourdomain.p12
  2. Enter a passphrase that will be required upon importing the certificate file.
• To import the key into your Java keystore:
  1. keytool -importkeystore -srckeystore yourdomain.p12 -destkeystore data/serverKeyStore.jks -srcstoretype pkcs12 -name yourdomain
  2. Note that the name you use here will be the alias in Gitblit's keystore.
  3. Enter the password to the Gitblit keystore (default gitblit).
  4. Enter the password to the certificate file, as entered above.
• To use the key in the keystore:
  1. Edit data/gitblit.properties and add the following line:
     server.certificateAlias = yourdomain
  2. Make sure that this is the same as the name you gave upon importing the key.
  3. Save data/gitblit.properties.
  4. Restart Gitblit.

Caveats:

• The Java runtime can apparently only reliably handle RSA keys up to 2048 bits. It doesn't matter if you're using Oracle, IBM, or OpenJDK's Java. It doesn't matter if you're using Java 7 or 8. It also doesn't matter if you have the Unlimited JCE Policies.
• I probably forgot something important in between at least one pair of steps. :)
• Any or all of the above information may be inaccurate, but it should be a starting point for someone more familiar with keytool to be able to massage into something as friendly as keytool can get.
• None of the above applies to .pfx files exported from Windows, but theoretically they can be used with keytool without the initial openssl step.

[lewellyn]

It might be worth noting that this should alleviate any and all problems with git clients when it comes to certificate verification.

Also, I suppose a feature request might be to have an import button in the GitBlit Authority tool that can validate and import PEM and/or PFX certificates. However, I have no idea how much work that might be and whether that might require pulling in dependencies which are not currently needed, so I'm hesitant to ask for it (nor can I currently implement it myself).

[gitblit]

Matt, this is good stuff. It would be even better as a PR for a Markdown file we can add to the site documentation. :)

The site documentation structure is defined in build.xml and the source files are in src/site. You can build the site with ant buildSite.