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 generalError
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")
-
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
-
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
-
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
-
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]?
-
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