Secure Storage

BlackBerry Secure File System

Overview

This class is a subclass of the native FileManager class, for access to the BlackBerry secure file system.

For applications, the BlackBerry secure file system behaves like the default file system, with the following differences.

• All data within the secure file system is stored on the device in an encrypted form.
• Directory and file names are also encrypted.
• The secure file system cannot be accessed until runtime is in an active or tokenExpired InitializationState.

Every operating system has a maximum supported length for the names of files and directories. For example, iOS 11 supports a maximum length of 255 bytes, given by the NAME_MAX constant. The encrypted form of the name of a directory or file will typically be longer than the plaintext, and it is the encrypted form that must be within the limits supported by the operating system. This means that names in the secure file system have a shorter effective maximum supported length. It isn’t possible to give a simple maximum but the following should be expected.

• Names that are 16 bytes or longer will be increased by a factor of 4:3 approximately.
• Shorter names will be increased to a length of 20 bytes approximately.

Encryption and decryption is transparent to the application code:

• The application passes its data to a file writing interface. The runtime encrypts the data and stores it on the device.
• When a file-reading interface is utilized, the runtime decrypts and returns the data.
• Path access interfaces accept plaintext parameters for directory and file names. The runtime encrypts the parameter values in order to create paths in the secure store.
• Directory and file names provided as return values are plaintext. The runtime decrypts paths in the secure store in order to generate the return values.

Usage

This class is a subclass of the native FileManager class. It should be easy to replace references to FileManager with references to BBSFileManager, in order to convert application code that utilizes the native file system into code that utilizes the secure file system.

The differences between this class and FileManager are:

• Write access is limited to the secure store.
• There is no access to “Ubiquitous” files and directories, i.e. no access to items in “cloud” storage.
• There is no access to native application group containers, which aren’t secured by BlackBerry Security. The containerURL(forSecurityApplicationGroupIdentifier:) returns the same value as the base class would for an invalid group identifier.
• The secure file system doesn’t have a designated temporary directory. The temporaryDirectory property mustn’t be used to create paths.
• File Provider extensions aren’t supported. The getFileProviderServicesForItem(at:completionHandler:) interface always fails.
• Returned URL values for locations within the secure file system can only be utilized by BlackBerry Security programming interfaces, see below.
• Returned String values for paths within the secure file system can only be utilized by BlackBerry Security programming interfaces, see below.
• Error codes could be in the specific BBSFileManager error domain or could be general Error codes.

The URL values returned by functions in this class can only be used to access files and directories by SecureEdge programming interfaces. They cannot be used by native interfaces, such as InputStream nor string(withContentsOf:) for example.

The String values for paths returned by functions in this class can only be used to access files and directories by BlackBerry Security programming interfaces. They cannot be used by native interfaces, such as stringByResolvingSymlinksInPath for example.

To read and write files in the secure store, use functions in this class or in one of the other BlackBerry Security programming interfaces. For example:

Use createFile(atPath:contents:attributes:) to write a file

Use contents(atPath:) to read a file

Don’t use file-reading and -writing functions in the native Foundation classes to access files in the secure store

Best practice for building paths for use with this class is as follows. First use an SearchPathDirectory value to generate a path prefix, for example by calling the NSSearchPathForDirectoriesInDomains(_:_:_:). Then append to the prefix, for example:

    let paths = NSSearchPathForDirectoriesInDomains(FileManager.SearchPathDirectory.applicationDirectory, FileManager.SearchPathDomainMask.userDomainMask, true)
    let filePath = paths[0].appending("testFile")

See more

public class BBSFileManager : NSObject, FileManagerDelegate, InitializationStateProvider

Enumeration for error codes of the BBSFileManager

See more

public enum BBSFileManagerErrorCode : Int, CaseIterable

Overview

InputStream subclass for reading files that are in the secure store. This class is a subclass of the native InputStream class, for access to the BlackBerrySecurity secure file system.

Usage

This class supports the read and hasBytesAvailable member functions of InputStream. This class doesn’t support getBuffer, which will always return false. This class also doesn’t support scheduleInRunLoop nor removeFromRunLoop. Support for run loops isn’t required because the file data can be read immediately.

Notes on use of the read function

The read function in this class will work best when the supplied buffer is a multiple of 16 bytes in length. The maxLength parameter should reflect the size of the buffer, and not the amount of data remaining to be read from the file. To read a particular number of bytes, B, supply a buffer whose size is B rounded up to the next multiple of 16.

The return value of the read function must always be checked by the application. It mustn’t be assumed that a file has been completely read into a buffer, even if the buffer is large enough to accomodate the whole file.

See more

public class BBSReadStream : InputStream, InitializationStateProvider

Overview

OutputStream subclass for writing files in the secure store.

This class is a subclass of the native OutputStream class, for access to the BlackBerrySecurity secure file system.

Usage

The class supports the write and hasSpaceAvailable member functions of OutputStream. The subclass doesn’t support scheduleInRunLoop nor removeFromRunLoop. Support for run loops isn’t required because the file data can be written immediately.

See more

public class BBSWriteStream : OutputStream, InitializationStateProvider