NSData (ACSharedSecureFile) and ACFileHandle (ACSharedSecureFile) categories
Use these categories if you want to encrypt the data that your app stores and you want the app to share the data with another AppConnect app. An encryption group ID determines which apps can share encrypted data. Each method in these categories corresponds to a method in NSData or NSFileHandle, and includes an encryption group ID parameter. The methods use the encryption group ID when encrypting and decrypting data. Therefore, any app using the same encryption group ID can share the encrypted data.
Note the following:
•If you do not want to share the data with another AppConnect app, use NSData (ACSharedSecureFile) and ACFileHandle (ACSharedSecureFile) categories and NSData (ACSharedSecureFile) and ACFileHandle (ACSharedSecureFile) categories.
•If you want to share data from a Document View Controller extension to a host app, see Sharing secure files from an extension.
Your app receives the encryption group ID in its app-specific configuration key-value pairs. Therefore, to use these categories, do the following:
| 1. | Define the encryption group ID key name that your app expects to receive in its app-specific configuration. |
For example: com.sample.groupID
The number of characters in the key name is not limited.
| 2. | Include information about the key in your documentation for Ivanti server administrators. The information includes: |
-
The name of the key
-
The other AppConnect apps that are sharing the encrypted data
Each of these other AppConnect apps also do these steps.
| 3. | Handle receiving app-specific configuration as described in App-specific configuration API details . |
| 4. | Use the value of the encryption group ID key received in the app-specific configuration in the methods of these categories. |
Note the following:
•The url parameter in these categories’ methods must be a file URL, and point to a regular file.
•The categories’ methods that return an NSError object set the properties on the object as described in NSError objects that secure Objective-C methods return.
•Ivanti recommends that you only use the methods that return an NSError object. However, to be consistent with the NSData and NSFileHandle classes, these categories include secure versions of NSData and ACFileHandle methods that do not return an NSError object.
The following table shows each added method for NSData(ACSharedSecureFile) and its corresponding method in NSData.
|
Method in category |
Corresponding method in NSData |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example using NSData(ACSharedSecureFile) category methods:
The following example shows how to use NSData(ACSharedSecureFile) category methods to:
| 1. | Create a shared secure file and write data to it. |
| 2. | Read the contents of the secure file. |
For brevity, the example does not include error handling.
- (void)NSDataSharedCategoryExample
{
NSError *error;
// This example assumes the app has already:
// 1. Retrieved the encryption group Id value from the config property on
// the AppConnect object.
// 2. Stored the value in an NSString * property named groupId of the current object.
// Read the contents of /etc/group.
NSData *etcGroupData = [NSData dataWithContentsOfFile:@"/etc/group"];
// Write the contents of /etc/group to a secure file to be shared with
// another AppConnect app.
NSString *secureFileName = @"/tmp/group.sec";
[etcGroupData writeToSecureFile:secureFileName
encryptionGroupId:self.groupId
options:0 error:&error];
// Read the contents of the secure file.
NSData *secureFileData =
[NSData dataWithContentsOfSecureFile:secureFileName
encryptionGroupId:self.groupId
options:0 error:&error];
// Note: The contents of NSData objects 'secureFileData' and 'etcGroupData'
// are identical.
}
Example using ACFileHandle(ACSharedSecureFile) category methods:
The following example shows how to use ACFileHandle(ACSharedSecureFile) category methods to:
| 1. | Create a shared secure file and write data to it. |
| 2. | Read the encrypted contents of the secure file, decrypt the contents, and write it to a unsecured file. |
For brevity, the example does not include error handling.
- (void)ACFileHandleSharedCategoryExample
{
NSError *error;
// This example assumes the app has already:
// - Retrieved the encryption group Id value from the config property on
// the AppConnect object.
// - Stored the value in an NSString * property named groupId of the current object.
// - Stored URLs in NSString * properties destinationPathURL and decryptedURL
// of the current object.
// Read the contents of /etc/group.
NSError *err;
NSFileHandle *sourceFileHandle =
[NSFileHandle fileHandleForReadingAtPath:@"/etc/group" error:&err];
// Get a file handle to a file to share with another AppConnect app.
ACFileHandle *destFileHandle =
[ACFileHandle fileHandleForWritingToURL:self.destinationPathURL
withEncryptionGroupId:self.groupID
error:&err];
//Read chunks and write them using the secure file handle.
NSData *data = nil;
while ((data = [sourceFileHandle readDataOfLength:1024]) && (data.length > 0)) {
[destFileHandle writeData:data error:&Serr];
NSLog(@"Wrote bytes (%@)", err.description);
}
[destFileHandle synchronizeFile];
// Read the contents of the secure file.
ACFileHandle *sharedEncryptedFileHandle =
[ACFileHandle fileHandleForReadingFromURL:self.destinationPathURL
withEncryptionGroupId:self.groupID
error:&err];
// Create an empty file.
[[NSFileManager defaultManager] createFileAtPath:self.decryptedURL.path
contents:nil
attributes:nil];
// Read the encrypted file, decrypt the data, and write it to an unencrypted file.
NSFileHandle *writeToFileHandle =
[NSFileHandle fileHandleForWritingAtPath:@"/etc/group-copy"];
NSData *decryptedData = nil;
while ((decryptedData = [sharedEncryptedFileHandle readDataOfLength:1024]) &&
(decryptedData.length > 0)) {
[writeToFileHandle writeData:decryptedData];
}
[writeToFileHandle synchronizeFile];
// Note: The contents of @"/etc/group" and @"/etc/group-copy" are identical.
}