blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Public Member Functions | Static Public Member Functions | Properties

GDFileManager Class Reference

Secure File System. More...

#import <GDFileManager.h>

List of all members.

Public Member Functions

Static Public Member Functions

Properties


Detailed Description

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

Secure File System

The secure file system is part of the BlackBerry Dynamics Secure Storage feature.

For applications, the BlackBerry Dynamics 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 BlackBerry Dynamics authorization processing is complete, see under authorize (GDiOS).

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 BlackBerry Dynamics 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.

The encryption method used by the BlackBerry Dynamics runtime generally requires that the user has entered a security password, from which an encryption key is derived.

Usage

This class is a subclass of the native NSFileManager class. It should be easy to replace references to NSFileManager with references to GDFileManager, 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 NSFileManager 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 Dynamics. The containerURLForSecurityApplicationGroupIdentifier: function 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 getFileProviderServicesForItemAtURL:completionHandler: interface always fails.
  • Returned NSURL values for locations within the secure file system can only be utilized by BlackBerry Dynamics programming interfaces, see below.
  • Returned NSString values for paths within the secure file system can only be utilized by BlackBerry Dynamics programming interfaces, see below.
  • Error codes could be in the specific GDFileManager error domain, or could be general NS error codes.

The NSURL values returned by functions in this class can only be used to access files and directories by BlackBerry Dynamics programming interfaces. They cannot be used by native interfaces, such as NSInputStream nor stringWithContentsOfURL: for example.

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

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

Don't use file-reading and -writing functions in the native NS classes to access files in the secure store.

Best practice for building paths for use with this class is as follows. First use an NSSearchPathDirectory value to generate a path prefix, for example by calling the NSSearchPathForDirectoriesInDomains: function. Then append to the prefix, for example by calling the NSString stringByAppendingPath: function or the NSURL URLByAppendingPathComponent function.

The functions in this API utilize NSError in a conventional way. Function calls accept as a parameter the location of a pointer to NSError, i.e. a pointer to a pointer, with type NSError**. The location may be nil. If the location isn't nil, and an error occurs, the BlackBerry Dynamics runtime overwrites the pointer at the specified location with the address of an object that describes the error that occurred.

The documentation of this class includes descriptions for functions and other elements of the programming interface that:

  • Have different semantics to the corresponding elements in the base class.
  • Are not present in the base class.

Elements of the base class that are overriden, but have the same semantics, are listed in the documentation of this class, but not described further. Elements of the base class that aren't overriden are not listed. See the documentation of the base class, NSFileManager, for full descriptions.

See also:
NSFileManager class reference on the apple.com developer website.
Error Handling Programming Guide on the apple.com developer website.
NSSearchPathForDirectoriesInDomains reference documentation on the apple.com developer website.
GDFileManager Error Domain
Secure SQL Database API
GDPersistentStoreCoordinator
GDFileHandle
C Language Programming Interface List

Code Snippets

The following code snippets illustrate some common tasks.

Simple conversion to secure file system

The following code snippets illustrate simple conversion of a function that uses the native file system to use the secure files system instead.

The second function in the snippet is the original; the third is the converted version. The changed line is flagged with a comment. The first function in the snippet is a utility that is used by both the original and the converted function, with no changes.

 - (NSString *)documentsFolderPathForFileNamed:(NSString *)fileName
 {
     NSArray *paths =
     NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                         NSUserDomainMask,
                                         YES);
     NSString *documentsDirectory = [paths objectAtIndex:0];
     return [documentsDirectory stringByAppendingPathComponent:fileName];
 }
 
 - (BOOL)writeMyFile
 {
     NSString *text = @"Text that is not protected.";
     NSData *fileData = [text dataUsingEncoding:NSUTF8StringEncoding];
     
     BOOL fileCreated =
     [[NSFileManager defaultManager]
      createFileAtPath:[self
                        documentsFolderPathForFileNamed:@"MyFile.txt"]
      contents:fileData
      attributes:nil];
     return fileCreated;
 }
 
 - (BOOL)writeMyFileGD
 {
     NSString *text = @"Text to be protected by BlackBerry Dynamics.";
     NSData *fileData = [text dataUsingEncoding:NSUTF8StringEncoding];

     // Following assignment uses GDFileManager instead of NSFileManager.
     BOOL fileCreated =
     [[GDFileManager defaultManager]
      createFileAtPath:[self
                        documentsFolderPathForFileNamed:@"MyFile.txt"]
      contents:fileData
      attributes:nil];
     return fileCreated;
 }

Member Function Documentation

+ (GDFileManager *) defaultManager
+ (GDCReadStream*) getReadStream: (NSString *)  filePath
error: (NSError **)  error 

Call this function to open a file in the secure store for reading. Files in the secure store are encrypted on the device; this function provides access to decrypted data.

Parameters:
filePathNSString of the path, within the secure store, that represents the file to be opened.
errorFor returning an NSError object if an error occurs. If nil, no object will be returned.
Returns:
GDCReadStream object from which the file's data can be read, or a null pointer if the file could not be opened.
+ (GDCWriteStream*) getWriteStream: (NSString *)  filePath
appendmode: (BOOL)  flag
error: (NSError **)  error 

Call this function to create a new file in the secure store, or to open an existing file for writing. Files in the secure store are encrypted on the device; data written to the stream returned by this function will be encrypted, transparently to the application.

If a file already exists at the specified path, the file can either be appended to, or overwritten.

Parameters:
filePathNSString of the path, within the secure store, that represents the file to be opened.
flagSelects the action to take if a file already exists at the path. YES to append to the file, or NO to overwrite.
errorFor returning an NSError object if an error occurs. If nil, no object will be returned.
Returns:
GDCWriteStream object to which data can be written, or a null pointer if the file could not be opened.
+ (NSString*) getAbsoluteEncryptedPath: (NSString *)  filePath

This function returns the encrypted path for a file or directory within the secure store. The principal usage for this function is to provide a path that is compatible with the SQL ATTACH command.

Parameters:
filePathNSString of the path, within the secure store, that represents the item for which the encrypted path is required.
Returns:
NSString containing the encrypted path.
+ (NSString*) pathForCFromManagerPath: (NSString *)  filePath

Call this function to convert a path so that it can be used with the BlackBerry Dynamics POSIX-level C language programming interface.

Paths used with this class, GDFileManager, have a different root to the file access functions in the POSIX-level C programming interface. This is because this class is an NSFileManager subclass. This function maps a path with the GDFileManager root to a path with the POSIX-level root.

The pathForManagerFromCPath: and pathForCFromManagerPath:, functions facilitate inter-operation of the programming interfaces. For example, a file could be created with POSIX-level C functions, then read back with functions in this class.

Parameters:
filePathNSString containing a path for use with this class.
Returns:
NSString containing the converted path.
See also:
C Language Programming Interface.
+ (NSString*) pathForManagerFromCPath: (NSString *)  filePath

Call this function to convert a path from the BlackBerry Dynamics POSIX-level C programming interface.

Paths used with this class, GDFileManager, have a different root to the file access functions in the POSIX-level C programming interface. This is because this class is an NSFileManager subclass. This function maps a path with the POSIX-level root to a path with the GDFileManager root.

The pathForManagerFromCPath: and pathForCFromManagerPath:, functions facilitate inter-operation of the programming interfaces. For example, a file could be created with POSIX-level C functions, then read back with functions in this class.

Parameters:
filePathNSString containing a path for use with the POSIX-level C programming interface.
Returns:
NSString containing the converted path.
See also:
C Language Programming Interface.
+ (BOOL) exportLogFileToDocumentsFolder: (NSError **)  error
Deprecated:
This function is deprecated and will be removed in a future release. Use the programming interface in the GDLogManager class to upload log files instead.

Call this function to create a dump of BlackBerry Dynamics activity logs. The logs will be dumped to a file that is outside the secure store, in the Documents folder. The file will not be encrypted.

Parameters:
errorFor returning an NSError object if an error occurs. If nil, no object will be returned.

The log file can be copied from the device in the normal way, and sent to BlackBerry to assist in support analysis.

+ (BOOL) uploadLogs: (NSError **)  error
Deprecated:
This function is deprecated and will be removed in a future release. Use GDLogManager::startUpload instead.

Call this function to upload BlackBerry Dynamics activity logs for support purposes. The logs will be uploaded to a server in the BlackBerry Network Operation Center (NOC).

Upload takes place in background and is retried as necessary. This function returns immediately.

Parameters:
errorFor returning an NSError object if an error occurs. If nil, no object will be returned.

BlackBerry support staff have access to the server to which log files are uploaded, and can use the data for support analysis. This function can be used to upload logs even if authorization has failed. The end user's enterprise email address will be needed by support staff, to identify uploaded files. If authorization has failed or been cancelled without an email address being successfully entered no logs will be uploaded.

- (NSURL *) URLForDirectory: (NSSearchPathDirectory)  directory
inDomain: (NSSearchPathDomainMask)  domain
appropriateForURL: (NSURL *)  url
create: (BOOL)  shouldCreate
error: (NSError **)  error 
- (NSArray *) URLsForDirectory: (NSSearchPathDirectory)  directory
inDomains: (NSSearchPathDomainMask)  domainMask 
- (NSURL *) containerURLForSecurityApplicationGroupIdentifier: (NSString *)  groupIdentifier

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
nil always.
- (NSArray*) contentsOfDirectoryAtURL: (NSURL *)  url
includingPropertiesForKeys: (NSArray *)  keys
options: (NSDirectoryEnumerationOptions)  mask
error: (NSError **)  error 
- (NSArray*) contentsOfDirectoryAtPath: (NSString *)  path
error: (NSError **)  error 
- (NSDirectoryEnumerator *) enumeratorAtURL: (NSURL *)  url
includingPropertiesForKeys: (NSArray *)  keys
options: (NSDirectoryEnumerationOptions)  mask
errorHandler: (NSURL *)  url
(NSError *error)  handler 
- (NSDirectoryEnumerator *) enumeratorAtPath: (NSString *)  path
- (NSArray *) subpathsOfDirectoryAtPath: (NSString *)  pathRaw
error: (NSError **)  error 
- (NSArray *) subpathsAtPath: (NSString *)  path
- (BOOL) createDirectoryAtURL: (NSURL *)  url
withIntermediateDirectories: (BOOL)  createIntermediates
attributes: (NSDictionary *)  attributes
error: (NSError **)  error 
- (BOOL) createDirectoryAtPath: (NSString *)  path
withIntermediateDirectories: (BOOL)  createIntermediates
attributes: (NSDictionary *)  attributes
error: (NSError **)  error 
- (BOOL) createFileAtPath: (NSString *)  path
contents: (NSData *)  contents
attributes: (NSDictionary *)  attributes 
- (BOOL) removeItemAtURL: (NSURL *)  URL
error: (NSError **)  error 
- (BOOL) removeItemAtPath: (NSString *)  filePath
error: (NSError **)  error 
- (BOOL) replaceItemAtURL: (NSURL *)  originalItemURL
withItemAtURL: (NSURL *)  newItemURL
backupItemName: (NSString *)  backupItemName
options: (NSFileManagerItemReplacementOptions)  options
resultingItemURL: (NSURL **)  resultingURL
error: (NSError **)  error 
- (BOOL) copyItemAtURL: (NSURL *)  srcURL
toURL: (NSURL *)  dstURL
error: (NSError **)  error 
- (BOOL) copyItemAtPath: (NSString *)  srcPath
toPath: (NSString *)  dstPath
error: (NSError **)  error 
- (BOOL) moveItemAtURL: (NSURL *)  srcURL
toURL: (NSURL *)  dstURL
error: (NSError **)  error 
- (BOOL) moveItemAtPath: (NSString *)  srcPath
toPath: (NSString *)  dstPath
error: (NSError **)  error 
- (NSURL *) URLForUbiquityContainerIdentifier: (NSString *)  containerIdentifier

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
nil always.
- (BOOL) isUbiquitousItemAtURL: (NSURL *)  url

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
NO always.
- (BOOL) setUbiquitous: (BOOL)  flag
itemAtURL: (NSURL *)  url
destinationURL: (NSURL *)  destinationURL
error: (NSError **)  error 

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
NO always. Sets GDFileManagerErrorICloudNotSupported if an error location is specified.
- (BOOL) startDownloadingUbiquitousItemAtURL: (NSURL *)  url
error: (NSError **)  error 

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
NO always. Sets GDFileManagerErrorICloudNotSupported if an error location is specified.
- (BOOL) evictUbiquitousItemAtURL: (NSURL *)  url
error: (NSError **)  error 

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
NO always. Sets GDFileManagerErrorICloudNotSupported if an error location is specified.
- (NSURL *) URLForPublishingUbiquitousItemAtURL: (NSURL *)  url
expirationDate: (NSDate **)  outDate
error: (NSError **)  error 

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
nil always. Sets GDFileManagerErrorICloudNotSupported if an error location is specified.
- (void) getFileProviderServicesForItemAtURL: (NSURL *)  url
completionHandler: (NSDictionary *)  services
(NSError *error)  completionHandler 

This element of the base class interface isn't available in this subclass. See under Usage, above.

Calling this function in the subclass causes the specified completion handler to be invoked as follows. The services parameter will receive nil. The error parameter will receive an NSError object with the GDFileManagerErrorNotSupported code. The invocation will be on a background thread.

- (BOOL) createSymbolicLinkAtURL: (NSURL *)  url
withDestinationURL: (NSURL *)  destURL
error: (NSError **)  error 
- (BOOL) createSymbolicLinkAtPath: (NSString *)  path
withDestinationPath: (NSString *)  destPath
error: (NSError **)  error 
- (BOOL) linkItemAtURL: (NSURL *)  srcURL
toURL: (NSURL *)  dstURL
error: (NSError **)  error 
- (BOOL) linkItemAtPath: (NSString *)  srcPath
toPath: (NSString *)  dstPath
error: (NSError **)  error 
- (NSString *) destinationOfSymbolicLinkAtPath: (NSString *)  path
error: (NSError **)  error 
- (BOOL) fileExistsAtPath: (NSString *)  path
- (BOOL) fileExistsAtPath: (NSString *)  path
isDirectory: (BOOL *)  isDirectory 
- (BOOL) isReadableFileAtPath: (NSString *)  path
- (BOOL) isWritableFileAtPath: (NSString *)  path
- (BOOL) isExecutableFileAtPath: (NSString *)  path
- (BOOL) isDeletableFileAtPath: (NSString *)  path
- (NSDictionary *) attributesOfItemAtPath: (NSString *)  path
error: (NSError **)  error 
- (NSDictionary *) attributesOfFileSystemForPath: (NSString *)  path
error: (NSError **)  error 
- (BOOL) setAttributes: (NSDictionary *)  attributes
ofItemAtPath: (NSString *)  path
error: (NSError **)  error 
- (NSData *) contentsAtPath: (NSString *)  path
- (BOOL) contentsEqualAtPath: (NSString *)  path1
andPath: (NSString *)  path2 
- (const char *) fileSystemRepresentationWithPath: (NSString *)  NS_RETURNS_INNER_POINTER
- (NSString *) stringWithFileSystemRepresentation: (const char *)  string
length: (NSUInteger)  len 
- (BOOL) changeCurrentDirectoryPath: (NSString *)  path
- (NSString *) currentDirectoryPath
- (BOOL) changeFileAttributes: (NSDictionary *)  attributes
atPath: (NSString *)  path 
Deprecated:
This function is deprecated in the base class. Use setAttributes:ofItemAtPath:error: instead.
- (NSDictionary *) fileAttributesAtPath: (NSString *)  path
traverseLink: (BOOL)  flag 
Deprecated:
This function is deprecated in the base class. Use attributesOfItemAtPath:error: instead.
- (NSDictionary *) fileSystemAttributesAtPath: (NSString *)  path
Deprecated:
This function is deprecated in the base class. Use attributesOfFileSystemForPath:error: instead.
- (NSArray *) directoryContentsAtPath: (NSString *)  path
Deprecated:
This function is deprecated in the base class. Use contentsOfDirectoryAtPath:error: instead.
- (BOOL) createDirectoryAtPath: (NSString *)  path
attributes: (NSDictionary *)  attributes 
Deprecated:
This function is deprecated in the base class. Use createDirectoryAtPath:withIntermediateDirectories:attributes:error: instead.
- (BOOL) createSymbolicLinkAtPath: (NSString *)  path
pathContent: (NSString *)  otherPath 
Deprecated:
This function is deprecated in the base class. Use createSymbolicLinkAtPath:withDestinationPath:error: instead.
- (NSString *) pathContentOfSymbolicLinkAtPath: (NSString *)  path
Deprecated:
This function is deprecated in the base class. Use destinationOfSymbolicLinkAtPath:error: instead.

Property Documentation

- (id<NSObject, NSCopying, NSCoding>) ubiquityIdentityToken [read, copy]

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
nil always.
- (NSURL*) temporaryDirectory [read, copy]

This element of the base class interface isn't available in this subclass. See under Usage, above.

Returns:
Instance of NSURL class with no path always.

The documentation for this class was generated from the following file: