Inherits from NSObject
Declared in FZACryptor.h

Overview

FZACryptor is the public interface to the TICoreDataSync encryption module.

Tasks

Configuration

Encryption and Decryption

Instance Methods

clearPasswordAndSalt

Clears any previously-existing keychain password and salt.

- (void)clearPasswordAndSalt

Declared In

FZACryptor.h

decryptFileAtLocation:writingToLocation:error:

Decrypt the content of a file, storing the clear-text data in another file.

- (BOOL)decryptFileAtLocation:(NSURL *)cipherTextURL writingToLocation:(NSURL *)plainTextURL error:(NSError **)error

Parameters

cipherTextURL

The file to be decrypted.

plainTextURL

The location to write the decrypted file. Any existing content will be blindly truncated.

error

Possible errors include no password being configured or the keychain item being corrupted, not being able to read from the source or write to the destination, or the cipher text file not being in the expected format. Errors come either from CommonCrypto/CommonCryptor.h or from the enumeration at the end of TICDSTypesAndEnums.h.

Return Value

YES if the decryption succeeds, otherwise NO and the error is set.

Discussion

%warning%
Warning: Any exceptions encountered in dealing with the filesystem will be propagated to the calling code. It is therefore up to the calling code to make sure it’s working with a reliable filesystem, or to handle exceptions occurring in here.

Declared In

FZACryptor.h

encryptFileAtLocation:writingToLocation:error:

Encrypt the content of a file, storing the encrypted data in another file.

- (BOOL)encryptFileAtLocation:(NSURL *)plainTextURL writingToLocation:(NSURL *)cipherTextURL error:(NSError **)error

Parameters

plainTextURL

The URL of the file to be encrypted.

cipherTextURL

The URL of the file to write the encrypted file. Any existing content will be blindly truncated.

error

Possible errors include no password being configured or the keychain item being corrupted, or not being able to read from the source or write to the destination. The error codes come from CommonCrypto/CommonCryptor.h.

Return Value

YES if the encryption succeeds, otherwise NO and the error is set.

Discussion

The file format is like this, where the numbers are byte indices:
0-15 An IV used to protect the first block of file key and IV.
16-63 The file key and IV, which have been encrypted by the sync key.
64-(end-32) The file content, encrypted by the file key.
(end-32)-end A SHA-256 HMAC derived using the sync key.

%warning%
Warning: Any exceptions encountered in dealing with the filesystem will be propagated to the calling code. It is therefore up to the calling code to make sure it’s working with a reliable filesystem, or to handle exceptions occurring in here.

Declared In

FZACryptor.h

isConfigured

Reports whether this object has already got a key and can be used for crypto operations.

- (BOOL)isConfigured

Return Value

YES if the object is ready to be used for crypto, otherwise NO.

Discussion

If this method returns NO, the app should get a password from the user and call setPassword:salt:.

Declared In

FZACryptor.h

setPassword:salt:error:

Set a new password to be used for protecting the encrypted content.

- (NSData *)setPassword:(NSString *)password salt:(NSData *)salt error:(NSError **)outError

Parameters

password

The password to use.

salt

Some random data to salt the password. If this is nil, the method will
generate its own salt from a random oracle.

outError

A pointer to an NSError that will be set if the data cannot be generated.

Return Value

The data used for salting the password. If this object needed to create salt material and couldn’t, it will return nil. In this case, the key used for encryption has not been set, and the object is not configured.

Discussion

This can either be used to initially configure the cryptography, or unilaterally change the password (without doing any re-encryption of existing data) at a later time.

%warning%
Warning: This class uses the keychain for secure storage, so it’s possible for a newly-created instance not to need a password if the key material has already been created. Check isConfigured to see whether this is the case.

Declared In

FZACryptor.h