Written by: John Murray (@jcmrim)
Introduction
This is the second in a three-part series of Blog Posts so if you haven’t already read the first in the series this is a good opportunity to do so – you can find it here. This series arose out of my experience of needing to use the BlackBerry 10 Cryptography Library APIs and the fact that I found them extremely intimidating even though I had a fairly good understanding of cryptography and knew what it was that I wanted to achieve: generate a random number, calculate an SH256 hash, or even create RSA key pairs; yet, I found the description of the APIs themselves opaque and getting that first snippet of working code took quite a lot of effort.
Over time I managed to accumulate a number of code fragments for the more common use-cases I came across that I could easily reuse – I’m sure you do the same sort of thing! So, noticing that there were still many questions in the Developer Support Forums I decided to wrap the most common of these code fragments into a sample application to share with the wider community.
I wrote an application called CryptoSample that you can find on GitHub here:
https://github.com/blackberry/Cascades-Community-Samples/tree/master/cryptosample.
It demonstrates three common cryptography use-cases using the BlackBerry 10 Cryptography Library APIs:
- Generating a simple random number —- http://devblog.blackberry.com/2015/04/cryptography-apis-a-gentle-introduction-random-numbers;
- Calculating Hashes (SHA1, SHA256) and HMAC using a predefined key;
- Using RSA:
- Creating an RSA public/private key pair;
- Creating a self-signed certificate using this pair of keys showing how to select SHA256 as the hash for the RSA certificate signing rather than the default MD5;
- Encrypting plaintext and decrypting the resulting cipher text using this pair of keys.
This isn’t intended to be a tutorial on cryptography; if this is what you’re looking for take a look on the web to any of the excellent resources that you’ll find there. These are simply simple implementations of these use cases using the BlackBerry 10 Cryptography Library APIs that can be used to help you in overcoming that barrier of understanding how to use them. I haven’t touched on AES simply because there is already an excellent example in GitHub covering this specific use-case:
https://github.com/blackberry/Cascades-Community-Samples/tree/master/AESCryptoDemo
This is the second in the series and it’s all about generating hashes using the BlackBerry 10 Cryptography Library APIs. So, let’s get started!
Hashes
A hash is a one-way function that is practicably impossible to invert. You’ll find them everywhere in cryptography since they are fundamental to applications such as signing and authentication.
The input to a hash is called the “message” and the output is called the “digest”. So, for example, if the message was, say, a large Word document the digest after applying a specific hash algorithm might be a byte array a 100 or so bytes long. There are some characteristics that any good hash function ought to have: It should be easy to calculate; it should be infeasible to recover the original message from the digest; It should be infeasible to change any of the message’s content without changing the digest; and, it should be infeasible to find two different messages that possess the same digest.
The use of the word “infeasible” is important. It doesn’t mean “impossible”, rather it means that using the technology of the day the resources required to compromise a specific has function should be so large of take such a long time as to be completely impracticable and not worth the effort.
Of course as technology has improved it has become feasible to compromise some of the earlier hash functions and these have had to be replaced with newer, stronger ones. For example, MD5 is one of the earlier hash functions that is known to have weaknesses and it is generally accepted that it’s not a good idea to use it when security is a consideration – it’s still perfectly good for using as a key in simple hash tables though. SHA-1 is the hash function that is probably in widest use today although it too has shown that it is vulnerable and some organisations has deprecated its use with a phase-out of their use by 2017. The SHA-2 family of hash functions is replacing SHA-1 and has proved to be resilient to attacks so far.
The sample application demonstrates how to calculate SHA-1 and SHA-2 hashes of a simple message.
Using the BlackBerry 10 Cryptography Library for Hashing
So, let’s take a look at how to generate SHA-1 and SHA-2 hashes using this library. Let’s look at the user interface first. The UI is fairly functional with a few buttons at the top and a logging area at the bottom (these screen shots were taken on a Passport device). We’re interested only in the second line of buttons in this post that deal with hash generation – We covered the first row related to random numbers in the previous post and we’ll talk about the bottom row in the last post.
When you launch the application you’ll see the screenshot on the left above. The first task is to initialise the hash environment by pressing the “Init Hash” button. In the screenshot you’ll see that there’s been some activity after we’ve done this – 3 Cryptographic API functions, all starting “hu_…” have been called. We also select the SHA-1 hash from the radio button group.
To generate a hash from a predefined message of “1234567890” press the “Make Hash” button. In the screenshot above on the left you’ll see that a 20 byte hash is generated each time we press this button. The screenshot above on the right just shows the activity after we press: “End Hash” to de-initialise the hash environment.
Let’s look at the code itself.
The Code
We’ll start with the initialisation step. You can find the code fragment in the image below in GitHub here if you want to look at the source itself or want to copy the fragment for your own use. The macro _CHECKRC() is simply a convenience to process the return code from the cryptographic calls and log them to the application’s screen. A successful return code will have the value: SB_SUCCESS.
There is one key object that the initialisation step must create. Namely:
- _sbCtx – an instance of sb_GlobalCtx (Global Context), and;
The global context structure is passed to every Security Builder Crypto function and is used to store call-back functions and other global workspace data.
I’ve used hu_GlobalCtxCreateDefault()to create a Global Context. It’s the very first thing you have to do whenever you use the Cryptographic Libraries.
The next two calls to the API are concerned with setting up the details of the algorithms we want to use:
- hu_registerSbg56() – this enables support for all algorithms from the GSE56 software provider; that is the BlackBerry Cryptographic Kernel version 5.6 (SB-GSE-56).
- hu_InitSbg56() – this initialises the GSE56 provider and performs a series of self-tests to ensure its integrity. It should only be called once so I check to see if it’s been called already earlier in the lifetime of the application.
Only now with a suitable _sbCtx are we ready to start generating digests. Notice that we haven’t specified the type of hash function to use yet.
Here’s what you have to do to generate an SHA-1 hash. You first need to create an instance (_sha1Context) of a Security Builder context (sb_Context) using hu_SHA1Begin().
Then you need to provide the parameters to the _sha1Context that describe the input message to the hash using the hu_SHA1Hash() function.
Finally to generate the digest itself use the hu_SHA1End() function to specify the location where the message digest will be placed. This function also de-allocates the resources associated with the _sha1Context.
You can find the code fragment in the image above in GitHub here if you want to look at the source itself or want to copy the fragment for your own use.
Once you’re finished you need to de-allocate any memory and resources that are associated with the
Global Context _sbCtx like this:
You can find the code fragment in the image above in GitHub here if you want to look at the source itself or want to copy the fragment for your own use.
That’s all there is to it.
Making an SHA-2 hash of type SHA256
Calculating an SHA256 digest, which is longer than an SHA-1 digest, is almost identical so I won’t spend much time on this other than to note that the functions hu_SHA256Begin(), hu_SHA256Hash() and hu_SHA256End()are substituted for the corresponding SHA-1 ones like this:
You can find the code fragment in the image above in GitHub here if you want to look at the source itself or want to copy the fragment for your own use.
Easy!
Creating an HMAC
There’s one more variant that is worth knowing about and that’s how to calculate an HMAC. An HMAC is a variant of a MAC (Message Authentication Code), which is a combination of a hash function (such as SHA-1 or SHA-2) and a secret cryptographic key. So, as well as producing a digest from a message, which provides you with an assurance of message integrity, it provides an element of authentication regarding who created the digest in the first place. If SHA-1 is used to calculate the HMAC it’s called HMAC-SHA1; similarly for, say, SHA256 where it’s HMAC-SHA256.
Calculating the HMAC-SHA256 digest follows the very same pattern where the functions hu_HMACSHA256Begin(), hu_HMACSHA256Hash() and hu_HMACSHA256End()are substituted for the corresponding SHA-1 or SHA256 ones like this:
The additional parameter provided to the hu_HMACSHA256Begin() function is a key, which I’ve provided as a fixed value in this sample application.
You can find the code fragment in the images above in GitHub here if you want to look at the source itself or want to copy the fragment for your own use.
Here’s a screenshot from the application showing the input message, input key and output digest from this process.
Summary
I’ve released v1.0.0 of the CryptoSample sample application containing the features described in this article and so you can download, review and reuse the full source code – you can find the URL in the “Resources” section below. I hope this has been interesting and will help set you on your way developing real-world applications for Blackberry 10.
Please feel free to contact me, @jcmrim, via Twitter if you need any help on anything related to this article.
I’ll follow this article with a final one covering the topic of RSA.
Resources
http://devblog.blackberry.com/2015/04/cryptography-apis-a-gentle-introduction-random-numbers/ – first in series
BlackBerry 10 Cryptography Library APIs
https://github.com/blackberry/Cascades-Community-Samples/tree/master/cryptosample
https://github.com/blackberry/Cascades-Community-Samples/tree/master/AESCryptoDemo
Contacts
John Murray – @jcmrim
