How to import a .pfx SAN certificate to the BAS keystore

One of my many roles is that I’m responsible for and manage a number of BlackBerry Enterprise Servers (BES) for both our company and our customers.  From 40 user BES Express up to 10,000 user licensed resilient enterprise systems.  Some of them I’ve implemented, some I’ve inherited.  I know some messaging system administrators don’t really get along with the BlackBerry Administration Service (BAS) that’s been available since version 5, but I quite like it – especially for publishing apps which is *so* much easier!

The thing about BAS is that it’s a web application, and is published (as it should be) via HTTPS, and therefore requires a certificate.  Now if you don’t mind the prompts, or can trust the self signed default certificates, then it’s fine, and you can carry on regardless.

Because I need to delegate administration to various people / departments etc, I find it important that security prompts do not appear, and that you don’t need to mess about publishing certificates to trusted stores of clients etc, especially on multiple domains.  It’s easy enough to get a public signed certificate for your BAS, and this is documented widely and quite thoroughly – RIM themselves even have a sensible walk through.  It’s worth noting though that none of the documentation refers to getting a certificate then using it, it’s all about generating the CSR on the BES, then getting that signed and imported.

I also manage a number of Microsoft Exchange environments, and I therefore use Subject Alternative Name (SAN) certificates a great deal, and for cost savings, I like to get as many SANs in a certificate as I can, and use them as widely as possible.  I also like to generate all my CSRs on a specific machine, export the signed certificates with their private keys and certificate chains as .pfx files, and save them in a secure area for later use / DR etc.

So here comes the issue that still gives me nightmares – using one of my certificates with BAS.  It’s not just a simple case of importing the certificate, key and chain into the computer’s private store (although I still do that anyway), as BAS uses the Java Keystore.  It’s also (once you’ve figured out how to do that) not just as simple as importing the .pfx to the keystore!  Hopefully though, this little guide will help to provide uninterrupted sleep (no, I’m not hoping to bore you that much), and a simple method of using any certificate you wish for your BAS.

The first thing to remember, above all else, is to back up your existing keystore.  Take a copy.  Take two copies.  Stick at least one on a USB stick.  Not to labour a point, but DON’T LOSE THIS BACKUP.  This “How To” guide has worked for me, but your mileage may vary and if it breaks your system, it’s your fault, and I can’t fix it, but you can feel free to call me names!!   🙂

The file that we back up is actually password protected.  By default the password is “password”, but you may have changed it, or it may be different on your system.  Note that this password cannot contain special characters (such as !, £, & etc).  This password is stored in the registry at “HKEY_CURRENT_USER\Software\Research In Motion\BlackBerry Enterprise Server\Administration Service\Key Store” as an encrypted value in “CacertsKeyStorePass”.  As you can see, this is a user hive key, so it’s important to be logged in as the correct user (normally BESADMIN – see later in this guide).  It’s worth backing up the “Key Store” branch to a .reg file if you want belt and braces, or if you need to change the password of the file (just right click “Key Store” in the left hand pane of regedit and select Export, ensuring “Selected Branch” is selected before choosing a location and file name).

To perform these actions, you need to be logged into your BES server using the default service account that your BES services run as (normally some derivative of BESADMIN).  For the rest of this guide, we’ll assume that BES is installed at the default (x86) location of C:\Program Files.  The file to back up is “C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore”.  Once you have your backups, we can move along to finding the program that lets us amend the data in that file.

You normally find this program (keytool.exe) in your Java (JRE) program folder, under \bin (for example “C:\Program Files\Java\jre1.6.0_18\bin”, which we’ll assume for this guide).  Open a command prompt (with administrative rights if in a recent Windows version) at this \bin location.  Again, ensure you are logged in as your “BESADMIN” account.

If you don’t have the password for your web.keystore file, and “password” doesn’t work in the following commands, you can change it as described here, by opening your “BlackBerry Server Configuration” tool, and setting it on the “Administration Service – Cacerts keystore” tab.  If you do this, make sure you have the Key Store registry key backed up first, as described earlier!

As long as you do not restart your server or BAS services, nothing you do here will have any effect.  Once you make your changes, you need to restart the BAS services, and make sure the BAS restarts and is accessible.  If after 5 minutes you can’t log in, you might have to just switch to your backups and restart them again!

In your command window, the first thing to do is look in the existing web.keystore file and see what certificates are in there.  To do that, we use the -list function of the keytool.exe command :

keytool -list -v -keystore "C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore" -storepass "password"

You’ll probably see your existing certificate, with the alias of “httpssl”.  Before we can continue with the import of our new certificate, we need to delete this old one.  Again, we use the keytool command :

keytool -delete -alias httpssl -keystore "C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore" -storepass "password"

The trick of this “How To” guide, and the reason I felt I had to write it, is that it’s the alias that’s important.  You can easily import a .pfx file to your web.keystore file, but unless the alias is “httpssl”, you’ll not be able to get back into your BAS.  So, as the alias is important, we need to find the current alias of the certificate in your .pfx file, and record it.  It’s worth noting at this point that the certificate doesn’t need to be a SAN certificate, I’m just pointing out that SAN certificates are fine, and don’t rely on the CN being the BAS hostname.  The BAS hostname just needs to be in the certificate somewhere, either as the CN or a SAN.

I’m not going to go into the details of exporting a certificate to a .pfx file, but just be aware that the file should include the full certificate chain and the private key, and that you need to know the password for the .pfx file so that you can import it.  For this “How To”, we’ll assume that you’ve saved your .pfx file to C:\ on your BES server, and that it’s called cert.pfx.  We’ll also assume that the password for the file is “P@ssw0rd”.

To find the current alias of the certificate in your .pfx file, we use keytool again.  Note the alias as we’ll be using it in a later command  :

keytool -list -keystore c:\cert.pfx -storetype PKCS12 -storepass "P@ssw0rd"

The alias in a public certificate is normally a long hexadecimal string, to ease things for this “How To”, we’ll assume that the alias is 123-456-7.

The next task is to import this certificate into our web.keystore so that we can use it.  I know there are a lot of assumptions in the command, but it should be easy for you to tailor it to your own environment.  Again, we’re using keytool.exe :

keytool -importkeystore -deststorepass "password" -destkeypass "password" -destkeystore "C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore" -srckeystore c:\cert.pfx -srcstoretype PKCS12 -srcstorepass "P@ssw0rd" -alias 123-456-7

As you can see, the commands are fairly self explanatory, and at this point, we’re most of the way there.  We have a certificate with its private key and chain in the web.keystore file, which you can verify using the list command we used first of all.  We now just need to do that magic trick of changing the alias of the certificate to “httpssl”, so that we can get into BAS!  Again, we use keytool.exe, and it’s a fairly straightforward command :

keytool -changealias -alias 123-456-7 -destalias httpssl -keystore "C:\Program Files\Research In Motion\BlackBerry Enterprise Server\bas\bin\web.keystore" -storepass "password" 

That’s your lot!  All we have to do now is to restart the BAS services so that we can make use of the new certificate.  The relevant services are “BlackBerry Administration Service – Application Server” (BAS-AS) and “BlackBerry Administration Service – Native Code Container” (BAS-NCC).  If you restart the BAS-NCC service, it will automatically restart the BAS-AS service too.  Wait a couple of minutes for the services to settle down (you can watch task manager until BAS-AS is using over 300MB of memory if you wish), then try to log on to your BAS.

Hopefully, you’ll be able to see that your session is secured using your new certificate, and everything is working normally, but if you have a problem, or you can’t log in, just roll back to your backups and restart BAS-NCC, then either work through this “How To” again, or just call me names!

The Zoo Keeper

By TheZooKeeper

An Azure Cloud Architect with a background in messaging and infrastructure (Wintel). Bearded dog parent who likes chocolate, doughnuts and Frank's RedHot sauce, but has not yet attempted to try all three in combination!


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.