The basic Code Collaborator installation configures the server to handle requests over standard HTTP. In many environments this is sufficient as the network is trusted. However some organizations require that all network applications are secured with Transport Layer Security (TLS) or Secure Sockets Layer (SSL). Code Collaborator supports HTTP over TLS (or HTTPS), but this requires additional manual server configuration:
In order to authenticate to clients, the Code Collaborator server must have a "Certificate" that serves as proof of identity. Certificates come in two forms: Certificate Authority (CA) signed certificates and "self-signed" certificates. CA signed certificates provide an additional level of security because they can be automatically verified and do not rely on human verification. By providing you a certificate, the Certificate Authority is vouching for your identity. Software systems such as web browsers and the Java Runtime Environment (JRE) include the public keys of the trusted Certificate Authorities that are used to verify server certificates were vouched for by a trusted CA. To acquire a CA signed certificate, contact the appropriate person in your IT department.
Self-signed certificates have the advantages of being free and easy to generate. The disadvantage of self-signed certificates is that they cannot be automatically verified. Instead, their security relies on users verifying the certificate signature against a signature obtained through another, ideally secure, channel.
A keystore is Java's mechanism for storing cryptographic keys and certificates. The persistent form of a keystore is a password protected file on disk. A keystore may contain "key entries" that allow applications with access to the keystore to authenticate themselves to users or other services. A keystore is also used to store "trusted certificate entries" that contain the public keys of services that are trusted and certificate authorities that are trusted to vouch for services.
To enable HTTPS in Code Collaborator, you will need to create a keystore with the server's certificate (either CA- or self-signed) and if CA-signed, the certificate authority's "chain certificate". Follow the instructions below to create a keystore with the type of certificate you will be using to secure Code Collaborator.
If you are using a CA-signed certificate, you will need the server certificate and the CA's chain certificate (or root certificate). The CA chain certificates are publicly available, but the instructions for acquiring them vary by certificate authority. To get the CA chain certificate, inquire of the IT person in your organization responsible for procuring SSL certificates for services. Once you have the certificates, import them into a new keystore using the Java "keytool" program (located in $JAVA_HOME/bin).
To import the CA chain certificate:
keytool -import -alias root -keystore <collab install dir>/tomcat/conf/collab.ks -trustcacerts \
-file <path to chain certificate file>
To import the server certificate:
keytool -import -alias tomcat -keystore <collab install dir>/tomcat/conf/collab.ks -trustcacerts \
-file <path to server certificate file>
Remember the keystore password you select, as you will need this in the next step.
If you are using a self-signed certificate, you can create the certificate and populate a keystore with a single invocation of Java's keytool (located in $JAVA_HOME/bin). Simply run the following command:
keytool -genkey -alias tomcat -keyalg RSA -keystore <collab install dir>/tomcat/conf/collab.ks
Keytool will ask you a variety of questions about the certificate you are generating. Be sure to remember the keystore password, as you will need it when configuring the server.
After you have generated the keys for the server, you will need to distribute its signature to users so they can validate the certificate when asked. To do this, first export the certificate to a file:
keytool -export -keystore <collab install dir>/tomcat/conf/collab.ks -alias tomcat > collab.cert
Then print the certificate information that you will need to distribute. Of particular interest are the fingerprints. To do this:
keytool -printcert -file collab.cert
This will print something like the following:
Owner: CN=Code Collaborator, OU=Smart Bear, O=Smart Bear, L=Austin, ST=TX, C=US
Issuer: CN=Code Collaborator, OU=Smart Bear, O=Smart Bear, L=Austin, ST=TX, C=US
Serial number: 463251eb
Valid from: Fri Apr 27 14:41:31 CDT 2007 until: Thu Jul 26 14:41:31 CDT 2007
Certificate fingerprints:
MD5: 67:D7:74:5E:72:9D:B2:82:88:3F:33:AA:A0:41:01:F0
SHA1: E2:4A:1F:9B:9A:38:0F:6B:7B:33:12:73:1B:50:76:30:AC:A6:B2:EA
Existing Keys and Certificates
In some cases, you may already have a signed certificate (generated by openssl, for instance) and so don't want to use keytool to generate a key and certificate for you. In those cases, you still must put the key and certificates into a keystore so that the Code Collaborator server can use them.
You import it into the keystore by first putting it into a pkcs12-format keystore:
openssl pkcs12 -export -in certified_collab_certificate.pem \
-inkey private_collab_key.pem \
-out mystore.p12 -name tomcat \
-CAfile CA_chain_certificate.cer \
-caname root -chain
and then import the pkcs12 keystore into the java keystore by doing:
keytool -importkeystore \
-destkeystore tomcat/conf/collab.ks \
-srckeystore mystore.p12 -srcstoretype PKCS12
Note that of course the .pem, .cer, and .p12 files may all be referred to using full path name.
The final step in configuring the Code Collaborator server is to instruct the server to use SSL and tell it what certificates to use. This is done by editing the server.xml file located in <install directory>/tomcat/conf. In server.xml, locate the "Connector" element and replace it with the following:
<Connector protocol="org.apache.coyote.http11.Http11Protocol"
port="8443" minSpareThreads="5" maxSpareThreads="75"
enableLookups="true" disableUploadTimeout="true"
acceptCount="100" maxThreads="100"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="conf/collab.ks" keystorePass="<the keystore password>"
clientAuth="false" sslProtocol="TLS"/>
Note, you will need to replace the keystore password in the above XML snippet. That is all the required configuration. Restart the server and it will be operating over SSL on port 8443.
Be sure to update the External URL in the server settings to reflect the correct https URL.
If the certificate used to secure Code Collaborator is a CA signed certificate from a trusted CA, there will be very little impact on users. The only thing that they must do is configure their clients with the correct HTTPS url.
If you are using a self-signed certificate or the certificate cannot be automatically verified, users will be asked to verify the certificate by comparing its signature to the published signatures for the service. The exact nature of this confirmation varies by client, but the process is the same: look at the certificate the server presents and confirm that its signature matches the published signature.
In the web browser, the certificate confirmation dialog looks something like this:
The above screenshot is from Firefox, but other browser users will see a similar dialog. The users will need verify that the fingerprint (or signature) of the certificate by comparing it to the signature of that you distributed for the server.
When the command line client fails to validate the server's certificate, it also offers the user a chance to manually validate the certificate. This conversation looks like the following:
~bdurette/work> ccollab login http://myserver.com bdurette password
The SSL certificates sent by the server could not be validated:
No trusted certificate found
It is possible, though unlikely, that someone may be trying to
intercept your communication with this service. If you have
questions about the validity of the certificate, please check with
your administrator.
What would you like to do?
P: Print the certificate chain.
A: Accept the certificate permanently (automatically accept this certificate in the future).
T: Temporarily accept this certificate (confirm again upon next connection).
R: Reject the certificate.
P
Subject: CN=Code Collaborator, OU=Smart Bear, O=Smart Bear, L=Austin, ST=TX, C=US
Issuer: CN=Code Collaborator, OU=Smart Bear, O=Smart Bear, L=Austin, ST=TX, C=US
Serial Number: 463251eb
SHA1 Fingerprint: e2:4a:1f:9b:9a:38:0f:6b:7b:33:12:73:1b:50:76:30:ac:a6:b2:ea
MD5 Fingerprint: 67:d7:74:5e:72:9d:b2:82:88:3f:33:aa:a0:41:01:f0
What would you like to do?
P: Print the certificate chain.
A: Accept the certificate permanently (automatically accept this certificate in the future).
T: Temporarily accept this certificate (confirm again upon next connection).
R: Reject the certificate.
A
Collaborator connection information set. Connection is good.
Additional Resources