Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Content protection

Content protection is a security framework that you can use to protect the data in your app. Content protection addresses the problem of someone stealing a BlackBerry smartphone and copying its data, which may be possible even when data is encrypted and the smartphone is locked. Content protection encrypts data in such a way that the encryption key is inaccessible when the smartphone is locked.

There are three requirements to implement content protection in a Java app:

  • There is content protection functionality on every BlackBerry smartphone. To use it, the smartphone must have a smartphone password, and content protection must be enabled by the smartphone user or by an IT policy rule.
  • To protect data in an app, the app must subscribe to the content protection framework by registering a listener.
  • Content protection functionality is triggered by the user locking and unlocking the smartphone.

Content protection can be used to encrypt data in String objects or byte arrays. Content protection can apply to data that is not persisted, but the Content Protection API contains specific functionality for the persistent store.

Whenever an app attempts to encrypt an object, the unencrypted version of the object is marked with a special bit called a plaintext bit. Any object marked with a plaintext bit is presumed to contain unencrypted, sensitive data. An app specifies which data it considers to be sensitive by encrypting and decrypting objects, and marking these objects with plaintext bits. Until an attempt has been made to encrypt data, the smartphone assumes that that data is not sensitive. When the smartphone is locked, the content protection framework uses these plaintext bits to ensure that as many plaintext objects as possible are erased from smartphone memory.

Here are the basic steps for implementing content protection for your app:

  • Subscribe to content protection.
    • Implement the PersistentContentListener interface.
    • Register the listener using PersistentContent.addListener() or PersistentContent.addWeakListener().
  • Encode and decode your objects, as required, using PersistentContent.encode() and PersistentContent.decode().

In the context of content protection, encoding means to encrypt and/or compress objects.

Compressing data with content protection

In addition to encrypting data, content protection can be used to compress data. Compression and encryption are enabled separately.

As with encryption, apps can compress data by passing data objects to the content protection framework and then storing the altered versions that the framework returns. Apps can only compress data if a BlackBerry smartphone user has enabled compression on their smartphone.

The content protection framework does not compress all data that is passed to it. For example, anything smaller than 32 bytes is not compressed because the overhead associated with the compression process would result in compressed data that is larger than the original, uncompressed data.

Enabling content protection

For content protection to be in effect, the following conditions must be met:

  • The BlackBerry smartphone must have a password set.

  • Content protection must be enabled on the smartphone, either through an IT policy rule or by the BlackBerry smartphone user. (Content protection is not enabled by default.)

  • The app must subscribe to the content protection framework.

When content protection is first enabled on a smartphone, the smartphone must be locked and remain locked long enough (a few minutes) for the smartphone to fully enable content protection and remove all unencrypted, sensitive data. Each time a smartphone transitions from having content protection turned off to having it turned on, the following occurs:

  1. The content protection framework notifies all registered apps to re-encode their data. During this process, data may be encrypted.
  2. The smartphone waits two minutes before it attempts to fully enable content protection. This waiting period is designed to guard against the possibility that the user only wanted to lock the smartphone temporarily.
  3. The smartphone displays a dialog box reading, "Content Protection is being enabled. This operation may take a few minutes to complete." Content protection is only considered to be fully enabled after all registered apps have finished encoding their data, the content protection framework has cleaned all the plaintext objects it can from memory, the encryption keys are no longer available, and the smartphone is securely locked. This process may take some time to complete, depending on the amount of data that needs to be encoded.
  4. The content protection framework enforces additional safeguards, such as having garbage collection zero out deleted data that was previously encrypted.

Enabling content protection through IT policy rules

In a BlackBerry Enterprise Server environment, administrators can use IT policy rules to turn content protection on and off on the BlackBerry smartphones they administrate. There are several IT policy settings that pertain to content protection:

  • Content Protection Usage IT policy rule: Determines whether smartphone users can enable content protection on their devices. When this rule is set to disallowed, users cannot turn on content protection. When this rule is set to allowed, users can choose whether or not to use content protection. The Content Protection Usage IT policy rule cannot be used to force users to use content protection; that is handled by the Content Protection Strength IT policy rule.

  • Content Protection Strength IT policy rule: Specifies the strength of the key used to encrypt data when the smartphone is locked. If the Content Protection Strength IT policy is set, content protection cannot be turned off.

  • Content Protection of Contact List IT policy rule: Includes or excludes contacts from content protection.

  • Two Factor Content Protection Usage IT policy rule: Specifies whether the smartphone uses an installed smart card reader and certificate for certain content protection operations. This option is only present if a supported smart card driver is installed.

  • Force Content Protection Of Master Keys IT policy rule: Enables or disables content protection for smartphone transport keys.

IT policy rules for content protection only specify a minimum level of security. Provided that content protection has not been forbidden by an IT policy, users can increase the strength of encryption used on their smartphones.

For more information about the IT policy rules that affect content protection, see the BlackBerry Enterprise Solution Security Technical Overview, available at http://docs.blackberry.com/en/admin.

Enabling content protection by a smartphone user

The following content protection options allow BlackBerry smartphone users to specify the strength and extent of content protection on their smartphones:

  • Encrypt: Enables or disables content protection and media encryption.

  • Strength: Dictates the strength of the key used to encrypt data when the smartphone is locked.

  • Include Contacts: Includes or excludes certain contact fields from content protection. When content protection for contacts is turned on, the caller's name does not appear on the screen if the user receives a call from a contact when the smartphone is locked. If contacts are excluded from content protection, the user is presented with the caller's name and user picture, as usual.

  • Include Media Files: Specifies whether media files stored on the internal media card (eMMC) should be encrypted. Although it is grouped with the content protection options, this option actually has nothing to do with content protection. Content protection is not used to encrypt media files and generally only applies to data that is ultimately written to the smartphone's application storage.

  • Two-factor Protection: Specifies whether the smartphone uses an installed smart card reader and certificate for certain content protection operations. This option is only present if a supported smart card driver is installed.

Understanding locked and unlocked smartphone states

The content protection framework encrypts data differently when the BlackBerry smartphone is locked and when it is unlocked.

When the smartphone is unlocked, it is generally considered appropriate for security requirements to be relatively lax. Therefore, all the cryptographic keys necessary to decrypt data are readily available. Apps that subscribe to the content protection framework can encrypt, decrypt, compress, or decompress data at any time. The content protection framework does not dictate which data should be considered sensitive or when that data should be encrypted or compressed; it is up to each individual app to implement the available content protection APIs in a way that makes the most sense for that app.

When the smartphone is locked, it is generally considered appropriate for security requirements to be much stricter. Therefore, the content protection framework only allows apps to encrypt data, not decrypt it, and it ensures that garbage collection removes any unencrypted, potentially sensitive data as promptly as possible. When an app receives potentially sensitive data while the smartphone is locked, the app should encrypt the data immediately.

Cryptographic keys

The content protection framework uses one cryptographic key to encrypt data when the BlackBerry smartphone is unlocked and a different set of keys to encrypt data when the smartphone is locked.

When the smartphone is unlocked, the content protection framework encrypts all data passed to it using a symmetric cryptographic key known as the content protection key or bulk key.

The bulk key is a 256-bit AES key. It can encrypt and decrypt data quickly, making it ideal for transcoding data when the smartphone is unlocked and the user is unlikely to tolerate long delays or reduced performance that might result from using a slower and more cumbersome system of keys.

The bulk key can't be used when the smartphone is locked because it can decrypt data that it previously encrypted. When the smartphone is locked, the bulk key must be hidden from potential attackers by encrypting it using the device password.

When the smartphone is locked, the content protection framework uses a more complicated system of paired private and public ECC keys to encrypt data. The content protection framework can encrypt in any one of three different encryption strengths when a smartphone is locked, each of which corresponds to a different key size:

  • Strong keys: 160-bit ECC keys (equivalent to an 80-bit symmetric key)

  • Stronger keys: 238-bit ECC keys (equivalent to a 128-bit symmetric key)

  • Strongest keys: 571-bit ECC keys (equivalent to a 256-bit symmetric key)

The content protection framework decides which set of keys to use based on the smartphone's Encryption Strength setting, as configured through either the Options application or an IT policy. If the setting is Stronger or Strongest, then when content protection is turned on for the first time, the user is asked to generate random data by pressing random keys or scrolling around the screen. This random data is incorporated into the Stronger and Strongest keys, making them more random and thus more secure.

Each pair of ECC keys consists of a public key and a private key. When the smartphone is locked, only the public ECC key is available; the private ECC key, like the bulk key, is hidden and encrypted with the device password. This makes it possible to encrypt data so that it can only be decrypted when the smartphone is unlocked and the private ECC key once again becomes available.

The paired ECC keys are also known as the long-term public key and the long-term private key. They are used in combination with a pair of cryptographic keys that are only used once, the one-time public key and the one-time private key.

The long-term public key is involved in encrypting every piece of new data that arrives on the smartphone when it is locked, while the long-term private key remains encrypted (and so hidden and inaccessible) for as long as the smartphone is locked. The long-term private key is only used after the smartphone is unlocked, to aid in decrypting those data objects that were previously encrypted using the long-term public key.

Every time new data arrives on the smartphone and an application makes it into a data object and passes that object to the content protection framework, a new pair of one-time keys is created, which are only used to encrypt that one data object.

Encrypting data when the smartphone is locked

To encrypt a new data object when a smartphone is locked, the content protection framework starts by combining the long-term public key with the one-time private key to produce a symmetric key. This symmetric key is similar to the symmetric AES bulk key that is used to encrypt data when the smartphone is unlocked. This symmetric key is used to encrypt the new data.

Once the data has been successfully encrypted, the one-time private key and the symmetric key it helped create are deleted and wiped from the smartphone. The one-time public key is embedded within the encoding that represents the encrypted data. This leaves just the long-term public key and the one-time public key available. With only those two keys, there is no way to decrypt the encrypted object.

Decrypting data when the smartphone is unlocked

When a smartphone is unlocked, the AES bulk key and long-term private ECC key are decrypted and once again made available for the content protection framework to use. At this point, any data encrypted by the content protection framework can be decrypted. The content protection framework automatically determines when the bulk key can be used to decrypt data or if the corresponding one-time symmetric key needs to be recomputed.

When the smartphone is unlocked and the long-term private key is available, the long-term public key and the one-time private key can be combined so that that they create a single symmetric key. This key is identical to the key that is produced when the long-term private key and the one-time public key are combined.

To decrypt an object that was encrypted when the smartphone was locked, the content protection framework combines the long-term private key with the one-time public key. This is relatively easy because when an object is encrypted using a combination of public and private keys, the relevant one-time public key is stored with it.

Data that was originally encrypted when the smartphone was unlocked can be decrypted using the AES bulk key, since that is the same key that the content protection framework used to encrypt the data.

The content protection framework tracks the number of times it has been asked to decode data that was encrypted when the smartphone was locked. Once it reaches the threshold number of 2053 data objects, the content protection framework sends out a notification requesting that all apps verify the integrity of their data and re-encode any data that does not conform to the current content protection settings or that was not encoded using the bulk key. By re-encoding data when it receives such a notification, an app can improve its performance, since an object encrypted using the bulk key is much quicker to decrypt than one encrypted using the two-key ECC scheme.

Encrypting data when the smartphone is unlocked

When a smartphone is unlocked, the content protection framework encrypts data using the AES bulk key. Apps that subscribe to the content protection framework can encrypt and decrypt data at any time, as long as the smartphone is unlocked.

Locking the smartphone

When a smartphone locks, the content protection framework sends out a "state changed" notification to all registered listeners. Apps that subscribe to the content protection framework can use this notification as a trigger to encrypt any of their data that has not already been encrypted.

As soon as all the registered listeners indicate that they no longer need the bulk key, the framework hides the bulk key and private ECC keys. Once these keys are hidden, only the long-term public ECC keys are available.

The framework initiates garbage collection of any plaintext object that is not in use. (A plaintext object is an object marked with a plaintext bit. It is presumed to contain unencrypted, sensitive data. It is by encrypting and decrypting objects, and thereby marking them with plaintext bits, that an app specifies which data it considers to be sensitive.) It may not be possible to remove some plaintext objects because, for example, they are referenced by apps that do not use content protection or that do not use it well.

In an effort to eliminate the possibility of confidential information being held by an app when the smartphone is locked, the content protection framework attempts to close all open screens. For each screen that is open, it does the equivalent of pressing the Escape key. This is a best effort approach, and when a key press is not able to close a screen the smartphone stops trying to close that screen.