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:
|
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:
|
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 Ivanti client app, and re-registered it with the Ivanti 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:
|
Secure File I/O API |
Sets these additional return values |
|
ACSecureFileClose() |
None |
|
ACSecureFileLseek() |
|
|
ACSecureFileOpen() |
None |
|
ACSecureFilePread() |
|
|
ACSecureFilePwrite() |
|
|
ACSecureFileRead() |
|
|
ACSecureFileReadv() |
|
|
ACSecureFileRename() |
None |
|
ACSecureFileWrite() |
|
|
ACSecureFileWritev() |
|
|
ACSecureFstat() |
|
|
ACSecureFtruncate() |
|
|
ACSecureLstat() |
None |
|
ACSecureTruncate() |
None |