How to: Bouncy Castle on BlackBerry

September 10th at 12:00am

While RIM does provide a Cryptographic API for their BlackBerry smartphones there are times when what is provided out of the box just isn't enough. In my case I was creating a mobile application that needed to retrieve infomation about TLS certificates presented on a socket / port by a server. While the RIM API has a 'Certificate' object, it does not allow you to get the encoded public key information.

To get around this problem I turned my attention to the Bouncy Castle Lightweight API which is suitable for use with the J2ME platform (BlackBerry included). As seems to be the case with Bouncy Castle it took me a few days to find out how to accomplish my task.

This article describes how to 'install' Bouncy Castle into your BlackBerry application.

Update: For information how to use the TLS Client from the BC Lightweight API, see this article.

References

 

Steps to get Bouncy Castle compiling in a BlackBerry project

    1. Download the Bouncy Castle J2ME edition from the BC download page
      1. Even though there is a package which contains 'everything' BC related, I found more luck using the J2ME specific package: lcrypto-j2me-147.zip

        Other tutorials out there speak of a cldc_classes.zip file that should be used. I found working with the source code to be easier for me. That file doesn't exist any more, anyway: It's cldc_bccore_classes.zip
         
    2. Extract the lcrypto-j2me-147\lcrypto-j2me-147\zips\cldc_bccore_sources.zip file

    3. Import the source files into eclipse. Since this was new to me, here are some steps on how to do that:
      1. Right click on the src folder and select Import...
        0.1-Import_sources_from_Eclipse.png
      2. Select File System when the 'Import' dialog appears
        0.2-SelectFileSystem.png
      3. Navigate to the folder where you decompressed the lcrypto-j2me package and check the boxes next to org and java. You may need to copy/paste the path into the From Directory box to avoid importing unnecessary folders
        0.3-SelectBothJavaAndOrgPackages.png
    4. Right-click and rename the Java.xxx packages to something like org.bouncycastle.java.xxx. This is important if you want to avoid code obfuscation (See question 3 of the bouncy castle FAQ for info on why they add code to the java.* namespace)
      1. If you don't use obfuscation and don't rename the java.* namespaces provided by bouncy castle, your app will seem to compile fine- then you'll see an error like this when you try to run it on a BB device:
        ErrorDueToAddingCodeToJavaNamespace.png
        Error Text: Error starting AppName, AppName may not contain classes in com.rim, net.rim, net.blackberry, java or javax packages

        The error makes it sound like the app should have classes in those namespaces when in reality it is trying to tell you to NOT put classes there.

      2. When I tried to refactor / rename the java.* files provided by BC, I ran into this eclipse error:
        ErrorWhenRenamingJavaNamespaces.png
        Error Text:
        An exception has been caught while processing the refactoring Rename Package

        Reason:
        Some characters cannot be mapped using Cp1252 character encoding. Either change the encoding or remove the characters which are not supported by the CP1252 character encoding

      3. To get past the problem I ended up changing the character encoding in Eclipse to UTF-8. This can be done by:
        1. Clicking on the Window menu
        2. Selecting the Preferences menu item
        3. Clicking on General -> Workspace
        4. In here you can change the Text File Encoding option
    5. At this point you should be able to compile and run your BlackBerry application without any weird error messages

In another article I'll demonstrate how to use the TLSClient functionality found in Bouncy Castle to gather information on Server Certificates.

I want to call out the assistance that rihan007 gave me in this BlackBerry forum thread. I was marching down the obfuscation path when he suggested renaming the classes. Makes sense to me!