BBSFileManager

public class BBSFileManager : NSObject, FileManagerDelegate, InitializationStateProvider

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")

Creating and Deleting Items

  • Creates a directory with the given attributes at the specified URL.

    Declaration

    Swift

    public func createDirectory(at url: URL, withIntermediateDirectories: Bool, attributes: [String : Any]?) throws
  • Creates a directory with given attributes at the specified path.

    Declaration

    Swift

    public func createDirectory(atPath path: String, withIntermediateDirectories: Bool, attributes: [String : Any]? = nil) throws
  • Creates a file with the specified content and attributes at the given location.

    Declaration

    Swift

    public func createFile(atPath path: String, contents: Data?, attributes: [String : Any]? = nil) throws -> Bool
  • Removes the file or directory at the specified URL.

    Declaration

    Swift

    public func removeItem(at url: URL) throws
  • Removes the file or directory at the specified path.

    Declaration

    Swift

    public func removeItem(atPath path: String) throws

Moving and Copying Items

  • Replaces the contents of the item at the specified URL in a manner that ensures no data loss occurs.

    Declaration

    Swift

    public func replaceItem(at originalItemURL: URL, withItemAt newItemURL: URL, backupItemName: String? = nil, options: FileManager.ItemReplacementOptions = [], resultingItemURL: AutoreleasingUnsafeMutablePointer<NSURL?>) throws
  • Copies the file at the specified URL to a new location synchronously.

    Declaration

    Swift

    public func copyItem(at srcURL: URL, to dstURL: URL) throws
  • Copies the item at the specified path to a new location synchronously.

    Declaration

    Swift

    public func copyItem(atPath srcPath: String, toPath dstPath: String) throws
  • Moves the file or directory at the specified URL to a new location synchronously.

    Declaration

    Swift

    public func moveItem(at srcURL: URL, to dstURL: URL) throws
  • Moves the file or directory at the specified path to a new location synchronously.

    Declaration

    Swift

    public func moveItem(atPath srcPath: String, toPath dstPath: String) throws

Getting and Comparing File Contents

  • Returns the contents of the file at the specified path.

    Declaration

    Swift

    public func contents(atPath path: String) throws -> Data?
  • Returns a Boolean value that indicates whether the files or directories in specified paths have the same contents.

    Declaration

    Swift

    public func contentsEqual(atPath path1: String, andPath path2: String) throws -> Bool

Discovering Directory Contents

  • Performs a shallow search of the specified directory and returns URLs for the contained items.

    Declaration

    Swift

    public func contentsOfDirectory(at url: URL, includingPropertiesForKeys: [URLResourceKey]?, options: FileManager.DirectoryEnumerationOptions = []) throws -> [URL]?
  • Performs a shallow search of the specified directory and returns the paths of any contained items.

    Declaration

    Swift

    public func contentsOfDirectory(atPath path: String) throws -> [String]?

Determining Access to Files

  • Returns a Boolean value that indicates whether a file or directory exists at a specified path.

    The following methods are of limited utility. Attempting to predict behavior based on the current state of the filesystem or a particular file on the filesystem is encouraging odd behavior in the face of filesystem race conditions. It’s far better to attempt an operation (like loading a file or creating a directory) and handle the error gracefully than it is to try to figure out ahead of time whether the operation will succeed.

    Declaration

    Swift

    public func fileExists(atPath path: String) throws -> Bool
  • Returns a Boolean value that indicates whether a file or directory exists at a specified path.

    Declaration

    Swift

    public func fileExists(atPath path: String, isDirectory: UnsafeMutablePointer<ObjCBool>?) throws -> Bool