POSIX-style secure file APIs

To secure the contents of your app’s files, your Objective-C or Swift app can use C-language, POSIX-style, AppConnect secure file APIs declared in ACSecureFile.h. These APIs:

•

Work only on regular files.

They do not work on directories, pipes, named pipes, character specials, block specials, or symbolic links.

•

Encrypt all file contents when writing, and decrypt the contents when reading.

•

Have the same parameters, return types, and functionality as their corresponding POSIX APIs, but with the added encryption and decryption capabilities.

For information on the corresponding POSIX APIs, see, for example, the sections “Standard I/O Streams” and “System Interfaces” at:

http://pubs.opengroup.org/onlinepubs/009696699/functions/contents.html

•

Fail if secure services are not available.

•

Provide additional error information besides setting errno.

The following table shows each secure file I/O API and its corresponding POSIX API:

 

Table 1. Secure file I/O API and corresponding POSIX API

Secure File I/O API	Corresponding POSIX API
ACSecureFileClose()	close()
ACSecureFileLseek()	lseek()
ACSecureFileOpen()	open()
ACSecureFilePread()	pread()
ACSecureFilePwrite()	pwrite()
ACSecureFileRead()	read()
ACSecureFileReadv()	readv()
ACSecureFileRename()	rename()
ACSecureFileWrite()	write()
ACSecureFileWritev()	writev()
ACSecureFstat()	fstat()
ACSecureFtruncate()	ftruncate()
ACSecureLstat()	lstat()
ACSecureTruncate()	truncate()

Additional error returns using ACSecureFileLastError()

The secure file I/O APIs add a layer on top of the POSIX APIs to provide encryption. This layer allows the secure file I/O APIs to provide more detailed error information than available in errno. This additional error information is available through the method ACSecureFileLastError(), defined in ACSecureFile.h:

 

int ACSecureFileLastError(int fd);

You can call this method when:

•

a POSIX-style secure file I/O API has failed.

•

the failed method operated on a valid and open file descriptor.

The ACSecureFileLastError() method returns one of the following enumeration values, defined in ACError.h:

 

Table 2. ACSecureFileLastError() return values

Return value	Description
ACE_NO_ERROR	No error occurred.
ACE_NO_KEYS_ERROR	AppConnect encryption keys are not available. This error occurs when secure services are not available. See The secureServicesAvailability and secureFileIOPolicy properties .
ACE_FILE_TOO_BIG_ERROR	The operation would result in exceeding the maximum file size, which is 6,961,618,944 bytes.
ACE_NEGATIVE_FILE_LEN_ERROR	The operation would result in a negative file size.
ACE_LOW_MEMORY_ERROR	A memory alloc failed while trying to perform the operation.
ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR	An encryption operation failed, due to either a corrupt encryption key or other corrupt data. Some situations that can cause this error are: • The device user has uninstalled and reinstalled the MobileIron client app, and re-registered it with the MobileIron server. • Mixing secure and regular file routines on a file.
ACE_INVALID_ARG	One of the arguments had an invalid value.
ACE_REGULAR_FILE_ONLY_ERROR	An NSURL parameter is not a file URL. The operation is allowed only on regular files.
ACE_INTERNAL_ERROR	An error occurred in the encryption layer of the function. The file is possibly no longer accessible.

The following table shows which secure file I/O APIs set these additional error values:

 

Table 3. Additional return values set by secure file I/O APIs

Secure File I/O API	Sets these additional return values
ACSecureFileClose()	None
ACSecureFileLseek()	• ACE_NO_KEYS_ERROR • ACE_FILE_TOO_BIG_ERROR • ACE_NEGATIVE_FILE_LEN_ERROR • ACE_INVALID_ARG
ACSecureFileOpen()	None
ACSecureFilePread()	• ACE_NO_KEYS_ERROR • ACE_READ_ON_WRITEONLY_ERROR • ACE_INTERNAL_ERROR • ACE_LOW_MEMORY_ERROR • ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR
ACSecureFilePwrite()	• ACE_NO_KEYS_ERROR • ACE_WRITE_ON_READONLY_ERROR • ACE_FILE_TOO_BIG_ERROR • ACE_LOW_MEMORY_ERROR • ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR • ACE_INTERNAL_ERROR
ACSecureFileRead()	• ACE_NO_KEYS_ERROR • ACE_READ_ON_WRITEONLY_ERROR • ACE_INTERNAL_ERROR • ACE_LOW_MEMORY_ERROR • ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR
ACSecureFileReadv()	• ACE_NO_KEYS_ERROR • ACE_READ_ON_WRITEONLY_ERROR • ACE_LOW_MEMORY_ERROR • ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR • ACE_INTERNAL_ERROR
ACSecureFileRename()	None
ACSecureFileWrite()	• ACE_NO_KEYS_ERROR • ACE_WRITE_ON_READONLY_ERROR • ACE_FILE_TOO_BIG_ERROR • ACE_LOW_MEMORY_ERROR • ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR • ACE_INTERNAL_ERROR
ACSecureFileWritev()	• ACE_NO_KEYS_ERROR • ACE_WRITE_ON_READONLY_ERROR • ACE_FILE_TOO_BIG_ERROR • ACE_LOW_MEMORY_ERROR • ACE_BAD_KEY_OR_CORRUPT_DATA_ERROR • ACE_INTERNAL_ERROR
ACSecureFstat()	• ACE_NO_KEYS_ERROR • ACE_INTERNAL_ERROR
ACSecureFtruncate()	• ACE_NO_KEYS_ERROR • ACE_TRUNC_ON_READONLY_ERROR • ACE_FILE_TOO_BIG_ERROR • ACE_NEGATIVE_FILE_LEN_ERROR • ACE_LOW_MEMORY_ERROR • ACE_INTERNAL_ERROR
ACSecureLstat()	None
ACSecureTruncate()	None