Package net.rim.device.api.crypto

Overview

This document contains overview, reference and tutorial information relating to the RIM Crypto API. It is intended for developers with experience using Java and at least a brief or conceptial knowledge of cryptography. For additional information about Cryptography, see below.

The RIM Crypto API is a collection of classes that allows you to provide effective security for your BlackBerry custom application regardless of its scope or complexity. The API is very robust and flexible so that you can accomplish each task in a number of different ways, depending on the needs of your application.

Using the Crypto, API you can accomplish the following tasks:

It is this flexibility that makes the Crypto API effective on a number of different levels. The RIM Cryptography API consists of several components:

Secure Messaging API Secure Connection API
CMS API
TLS API SSL API WTLS API

Key Management API
KeyStore API
KeyStore DesktopKeyStore
SyncableRIMKeyStore RIMKeyStore
PersistableRIMKeyStore TrustedKeyStore
Encoding API
Private Key Encoders Public Key Encoders
Signature Encoders Symmetric Key Encoders
Certificate API
Certificate X509
Status WTLS
ASN.1 API
ASN1InputStream
ASN1OutputStream
ASN1InputByteArray
OID API
OID OIDs

Cryptographic Primitives API
Symmetric Key Algorithms Public Key Algorithms
Miscellaneous
Digests PRNGs

The above diagram displays the Crypto API as a system of smaller APIs.

The Secure Messaging API contains the CMS (Cryptographic Message Syntax) API and provides the functionality needed to create a secure messaging application. The Secure Connection API contains the TLS (Transport Layer Security), WTLS (Wireless Transport Layer Security), and SSL (Secure Sockets Layer) APIs and provides the functionality required to create and manage secure connections between client and server. Together, these two APIs define the protocol functionality since they contain the code necessary for implementing secure communication.

The Key Management API contains the basic cryptographic framework needed to create secure applications. Key management and distribution are handled by the KeyStore API, while keys are encoded using the Encoding API. The Certificate API contains the functionality necessary for managing cryptographic certificates. The OID (Object Identifier) API contains the functionality necessary for handling and using some popular Object IDs. The ASN.1 (Abstract Syntax Notation) API provides a mechanism to format and parse data that is commonly needed with cryptographic schemes and protocols.

At the lowest level, the Cryptographic Primitives API contains the most basic tools needed to implement the cryptographic utilities. This API contains the keys, MACS (Message Authentication Codes), ciphers and other functionality associated with both symmetric and public cryptography. In addition, this API contains the "unkeyed" algorithms such as digests and PRNGs (Pseudo Random Number Generators) needed by other members in the API.

Symmetric Key Algorithms
Keys Encryptors Decryptors MACs

AES
ARC4
Cast128
DES
TripleDES
RC2
RC5
Skipjack
HMAC
Algorithms
AES ARC4
DES TripleDES
RC2 RC5
Skipjack CAST128
Algorithms
AES ARC4
DES TripleDES
RC2 RC5
Skipjack CAST128
CBCMAC
HMAC
Modes
CBC CFB
OFB X
Modes
CBC CFB
OFB X
Padding
PKCS5
Padding
PKCS5
Public Key Algorithms
Keys Key Agreement Encryptors Decryptors Signers Verifiers
DH
DSA
EC
KEA
RSA
DH
ECDH
ECMQV
KEA
RSA PKCS1
RSA OAEP
ElGamal
RSA PKCS1
RSA OAEP
ElGamal
DSA
ECDSA
ECNR
RSA PKCS1
RSA PSS
X9.31
DSA
ECDSA
ECNR
RSA PKCS1
RSA PSS
X9.31
KDFs
P1363 KDF1
X9.42 KDF
Miscellaneous
Digests PRNGs
SHA1 SHA256 SHA384
SHA512 MD2 MD4
MD5 RIPEMD128 RIPEMD160
P1363 KDF1 PKCS1 MGF1
X9.42 KDF PKCS5 KDF1
PKCS5 KDF2 FIPS186 PRNG
RFC 2631 KDF


The API was intended for use by all developers who are trying to incorporate security into their applications, regardless of their knowledge of security concepts or low level programming. The API can be used to provide security for any project no matter the size or complexity. This is accomplished by implementing flexible cryptography algorithms that can be implemented in a number of different ways. For example, the Crypto API contains a variety of encryption algorithms that can be implemented individually as a low level algorithm or as part of a larger, more customized process. This process is encapsulated within an object called a factory. By incorporating the various levels of granularity into the API, the system becomes extremely customizable and extremely flexible.

The RIM Crypto API was developed internally by RIM.The CLDC (Connected Limited Device Configuration) and MIDP (Mobile Information Device Profile) of J2ME (Java 2 Platform Micro Edition) do not define a cryptographic API. In creating the API, RIM chose not to follow the java.security model for the following reasons:

API Reference

The Crypto API Class Reference provides a table containing a brief description of all members in the API. This is the original entry page of the API documentation and can be used to navigate to classes within the API.

Extending the Crypto API

The crypto API was developed to provide developers with the means necessary to design and create secure software for the BlackBerry Handheld. It was intended for use by all developers who are trying to incorporate security into their applications, regardless of their knowledge of security concepts or low level programming. The API can be used to provide security for any project no matter the size or complexity.

To compliment this inherent flexibility, developers can extend the API by implementing their own cryptographic algorithms, encoding schemes, certificates and software tokens. This way, custom cryptographic solutions can be even more flexible.

To learn more about extending the crypto API, and to access the documentation for the relevant classes, see the Extending the Crypto API Javadocs.

Note:For ease of use, this documentation set is divided into two separate file sets. This set contains all help related to the Main RIM API, including the Crypto API. The second set (Extending the Crypto API - mentioned above) contains all help related to extending the Crypto API and implementing smart cards and crypto tokens.

Tutorials

This series of tutorials tells you how to use the common features and components provided in the Crypto API.

TitleDescription
  1. Overview of cryptography
This tutorial provides a brief overview and introduction to Cryptography.
  1. Getting started with the crypto API
This is a quick start lesson. It talks about the structure of the Crypto API and some of the most commonly asked questions.
  1. Keys, cryptoSystems, certificates and keyStores
This tutorial provides a lesson on how keys work and describes why they are an integral part of the Crypto API. The lesson then covers cryptosystems and how they work in the Crypto API. Finally, the lesson finishes with introductions on certificates and keystores which are provided outside of the Crypto API but are intended to work with the API.
  1. Encrypting and decrypting data
This tutorial describes the most common uses of the RIM Crypto API. The tutorial demonstrates encrypting and decrypting data using the Crypto API by providing a walk through of a sample application:CryptoSample.java.
  1. Block ciphers
This is a comprehensive lesson on how to use the block ciphers. This includes using the "engines" concept provided in the Crypto API and the "encryptor/decryptor" concept for streaming block ciphers together. The block ciphers lesson explains how to use common algorithms such as DES, AES and other block ciphers.
  1. Stream ciphers
This tutorial is a comprehensive lesson on how to use the stream ciphers provided with the Crypto API. This includes an introduction to such topics as RandomSource, PseudoRandomSource and modes for block ciphers that act as streams, such as OFB (Output Feedback Mode).
  1. Encryptor and decryptor factories
This tutorial demonstrates how to use factories to encrypt and decrypt data.
  1. Key agreement
This tutorial provides an introduction to the concept of key agreement within the Crypto API and several of the common algorithms available.
  1. Key encoders
This tutorial demonstrates how key encoding is accomplished in the Crypto API. This includes private keys, public keys, and the PKCS8 and X.509 encoding schemes.
  1. Digests and MACs
This is a lesson on how to use the digests and Message Authentication Codes (MACs) that are provided by the Crypto API. The lesson describes the common uses of digests and the MACs provided.
  1. Signatures
This is a lesson on how to use the Signature functionality that is provided by the Crypto API. This lesson covers the concepts of SignatureSigners and SignatureVerifiers, including the idea of signing engines. The encoding of signatures is also covered here.
  1. Encoders
This tutorial is a description of the encoding shemes that this API supports. The Signature, Public Key, and Private Key encoders are all detailed in it.
  1. Securing the RuntimeStore
This tutorial demonstrates the steps involved in securely adding items to the RuntimeStore, and retrieving items from the RuntimeStore.

For more information on cryptography

Two good books on the subject are:

Feedback

Your input is important to us. Please send your feedback to Crypto SDK Feedback.