I'm working on an application that uses the BlackBerry Enterprise Server 5.0 API and I wanted to install a valid SSL certificate to make development easier since it's a bit of a pain to trust self-signed certificates with ColdFusion. I figured that a $12.99 SSL certificate from Go Daddy was cheap compared to the trouble I was having with ColdFusion. Big mistake.
99% of these instructions apply to JBoss as well as the BlackBerry Administration Service (BAS) which is running on top of JBoss. I read a few guides on installing a SSL Certificate in JBoss, but ran into issues with each of them.
For anyone who only needs vanillla JBoss instructions I'll flag BAS-specific items that can be ignored. Some guides will have you extract the private key from your certificate and generate a PKCS12 keystore using openssl. I'm intentionally not taking that approach to avoid modifying the BAS server.xml.
The process goes like this:
- Generate a new key, optionally create a new keystore
- Generate a CSR
- Purchase the SSL certificate
- Prepare chained certificates – gather root certificate, intermediate certificates, reply
- Import certificates
- Install new certificate
Everything will be easier if you keep all the related files in a single location initially.
- Create a directory called "req" and open a new command prompt inside of it.
- Choose a keystore name and certificate alias. In the examples I'm using web.keystore and bas respectively.
(BAS only) the keystore name must be web.keystore
- Locate keytool.exe in the JRE bin directory. On my server it was in C:\Program Files\Java\jre1.6.0_07\bin\keytool.exe
- (BAS only)Back up the current keystore file located in <drive:\program files>\Research In Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore
Note: Most likely this is in <drive>:\Program Files\ unless you're on 64-bit Windows, in which case it will be <drive>:\Program Files (X86)
- (BAS only)You'll need to know your current keystore password, use that whenever prompted for a password. If you want to set a new password you will need to change the cacerts keystore password in the BlackBerry Server Configuration.
Step 1 – Generate the Key
keytool -genkey -alias bas -keyalg RSA -keystore web.keystore
This will generate a new key with the alias bas and create a new keystore in web.keystore (if it doesn't exist). (BAS only) When prompted for a password us your current BAS cacert password.
Press RETURN when prompted for a key password to use the keystore password. Replace bas.example.com with the hostname you are purchasing a SSL certificate for. Replace bas and web.keystore with the keystore name and certificate alias you chose in the Prerequisites section.
C:\req>keytool -genkey -alias bas -keyalg RSA -keystore web.keystore Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: bas.example.com What is the name of your organizational unit? [Unknown]: bas.example.com What is the name of your organization? [Unknown]: bas.example.com What is the name of your City or Locality? [Unknown]: Denver What is the name of your State or Province? [Unknown]: CO What is the two-letter country code for this unit? [Unknown]: US Is CN=bas.example.com, OU=bas.example.com, O=bas.example.com, L=Denver, ST=CO, C=US correct? [no]: yes Enter key password for (RETURN if same as keystore password):
Step 2 – Generate the CSR
Next you must generate a Certificate Signing Request (CSR) to submit to Go Daddy (or whoever you've chosen).
keytool -certreq -keyalg RSA -alias bas -file bas.example.com.csr -keystore web.keystore
Provide your keystore password when prompted. This will generate a CSR from web.keystore for the bas entry.
The CSR should look something like:
-----BEGIN NEW CERTIFICATE REQUEST----- MIIBuTCCASICAQAweTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNPMQ8wDQYDVQQHEwZEZW52ZXIx GDAWBgNVBAoTD2Jhcy5leGFtcGxlLmNvbTEYMBYGA1UECxMPYmFzLmV4YW1wbGUuY29tMRgwFgYD VQQDEw9iYXMuZXhhbXBsZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMNSDrG1vAxX zaEelgKxl2Sr7zxTdUh+muoBN/uBiLrIZjMzz278tmqbKbZ3+ok4ZB99Pzto5SLKnpi1i8tuHL51 unGXqAZRCSQgN7agT4HqURsURjKEPJsvjR7pjRKcPOzmCYaus2KeOAP8BHCPCGZbZRlAS7aND3Qi r4ArNFjrAgMBAAGgADANBgkqhkiG9w0BAQUFAAOBgQAs4avQ2JiUfAA2N2hOHwbPE7Wax5kIIldS RNIpSW2jButL4YdbNoj1BgVGtY1D+/9vOUnMYWl63rHRGv1StTHzaqsZE3Wmb8b5epZbzfKe9p0b pewqnuGnwcqTz9HRkR+rXizF0vPGnyKWQKRYuqFxtnCqVYXDbWYxv32qgggtQQ== -----END NEW CERTIFICATE REQUEST-----
Step 3 – Purchase the SSL Certificate
Open the generated CSR up in a text editor( eg, notepad bas.example.com.csr) and paste the contents into the CSR Data field on Go Daddy.You're given the choice of which issuing organization to use (Starfield Root or Godaddy Root), and the Web Server Type. I chose Starfield Root. The Web Server Type must be Tomcat.
Once you've verified the ownership of the domain you will receive a zip file containing the SSL certificate and the intermediate certificates.
Step 4 – Prepare chained certificates
Extract the contents of the the zip file (mine was named certbundle.zip) into your req working directory. If you chose Starfield Root for the issuing organization you should have the following files in req:
- web.keystore – Your keystore file
- bas.example.com.csr – Your generated CSR
- bas.example.com.crt – Your certificate response
- sf_bundle.crt (or gd_bundle.crt) – Bundled intermediate certificates
- sf_intermediate.crt (or gd_intermediate.crt) – Intermediate certificate
- sf_cross_intermediate.crt (or gd_cross_intermediate.crt) – Cross intermediate certificate
I'm not sure if this step is 100% necessary, but I did it and my certificate worked. Download the appropriate root certificate for your issuing organization and save it into your req working directory – Starfield Root (sfsroot.crt) or Go Daddy Root (gd-class2-root.crt).
Step 5 – Import Certificates
Once you've gathered the various certificates they must be imported into your keystore. The root and intermediate certificate are used to establish a chain of trust which eventually ends with your self-signed keystore.
- Import the root certificate (sfsroot.crt or gd-class2-root.crt)
keytool -import -alias root -keystore web.keystore -trustcacerts -file sfsroot.crt
- Import the cross intermediate certificate (sf_cross_intermediate.crt or gd_cross_intermediate.crt)
keytool -import -alias cross -keystore web.keystore -trustcacerts -file sf_cross_intermediate.crt
- Import the intermediate certificate (sf_intermediate.crt or gd_intermediate.crt)
keytool -import -alias intermed -keystore web.keystore -trustcacerts -file sf_intermediate.crt
- Import your reply. The alias you use here MUST match the alias you used when you generated the certificate in Step 1.
keytool -import -alias bas -keystore web.keystore -trustcacerts -file bas.example.com.crt
The output should be similar to:
C:\req>keytool -import -alias bas -keystore web.keystore -trustcacerts -file bas.example.com.crt Enter keystore password: Certificate reply was installed in keystore
Your request is now complete, and your keystore contains a trusted, signed request. You can verify this:
C:\req>keytool -list -keystore web.keystore -storetype jks Enter keystore password: Keystore type: JKS Keystore provider: SUN Your keystore contains 1 entry bas, Jun 2, 2009, PrivateKeyEntry, Certificate fingerprint (MD5): F4:63:44:DA:33:BA:C2:2A:C3:0E:6C:92:AB:E9:45:12
Step 6 – Install the Certificate
Install and activate your new keystore using the instructions on the JBoss SSL Setup wiki page. If you've followed all the steps properly you will have a JKS-type keystore, not PKCS12.
- Back up your web.keystore file if you haven't already.
- If the new keystore has a different password than the current keystore change the password in the BlackBerry Server Configuration tool, under the Administration Service – Cacerts keystore tab.
- Stop the BAS services – BlackBerry Administration Service – Native Code Container and BlackBerry Administration Service – Application Server.
- Rename <drive:\program files>\Research In Motion\BlackBerry Enterprise Server\BAS\bin\web.keystore to web.keystore.original
- Copy web.keystore from your req working directory into the BAS\bin directory.
- Restart the BAS services – starting the Application Server service will automatically start the Native Code Container service.
Browse to your BAS using HTTPS and verify the server is working correctly. To undo the changes stop the BAS services, delete web.keystore and rename web.keystore.original to web.keystore. Restart the BAS services, which are now using the original, working keystore.
- When importing your reply you must use the same alias as you did to generate the original key which was used to generate the CSR.
- The key password must match the keystore password.
- (BAS only) The keystore filename must be web.keystore
- (BAS only) The keystore password must match what is entered in BlackBerry Server Configuration > Administration Service – Cacerts keystore
- (BAS only) Open the highest-numbered <servername>_BBAS-AS_01_YYYYMMDD_00##.txt log file and search for error, ssl and keystore for information about why the server didn't start. Most commonly this will be a password mismatch between the keystore and the BAS or a missing certificate.
- Verify the keystore using keytool -list.
- If the keystore is valid but the certificate is shown to be issued by bas.example.com instead of Go Daddy or Starfield you most likely did not import your reply (Step 5, keytool -import … bas.example.com.crt) using the same alias as the generated key (Step 1, keytool -genkey).
The following sites were helpful:
- Go Daddy Tomcat SSL Installation instructions
- keytool documentation
- JBoss SSL Setup
- How to install a Go Daddy Wildcard Certificate on JBoss
- Import a new SSL certificate for the BlackBerry Administration Service and BlackBerry Web Desktop Manager
- Go Daddy Certificate Repository
- Portecle – A wonderful Java GUI application for managing keystores and certificates.