ZDCFileConversion

@interface ZDCFileConversion : NSObject

The ZDCFileConverstion class contains many utility methods to encrypt & decrypt files.

  • Converts from unencrypted/cleartext file format to cache file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes. If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        encryptCleartextFile:(nonnull NSURL *)cleartextFileURL
          toCacheFileWithKey:(nonnull NSData *)encryptionKey
             completionQueue:(nullable dispatch_queue_t)completionQueue
             completionBlock:(nonnull void (^)(ZDCCryptoFile *_Nullable,
                                               NSError *_Nullable))completionBlock;

    Swift

    class func encryptCleartextFile(_ cleartextFileURL: URL, toCacheFileWithKey encryptionKey: Data, completionQueue: DispatchQueue?, completionBlock: @escaping (ZDCCryptoFile?, Error?) -> Void) -> Progress

    Parameters

    cleartextFileURL

    The input file (stored unencrypted).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    completionQueue

    (optional) If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    (optional) The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the encryption progress.

  • Converts from unencrypted/cleartext file format to cache file format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextFile:(nonnull NSURL *)cleartextFileURL
              toCacheFileWithKey:(nonnull NSData *)encryptionKey
                    outputStream:(nonnull NSOutputStream *)outStream
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextFile(_ cleartextFileURL: URL, toCacheFileWithKey encryptionKey: Data, outputStream outStream: OutputStream) throws

    Parameters

    cleartextFileURL

    The input file (stored unencrypted).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    outStream

    An output stream that is already open, and ready to be written to.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext file format to cache file format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextFile:(nonnull NSURL *)cleartextFileURL
              toCacheFileWithKey:(nonnull NSData *)encryptionKey
                       outputURL:(nonnull NSURL *)outputFileURL
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextFile(_ cleartextFileURL: URL, toCacheFileWithKey encryptionKey: Data, outputURL outputFileURL: URL) throws

    Parameters

    cleartextFileURL

    The input file (stored unencrypted).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext format to cachefile format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes. If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        encryptCleartextData:(nonnull NSData *)cleartextData
          toCacheFileWithKey:(nonnull NSData *)encryptionKey
             completionQueue:(nullable dispatch_queue_t)completionQueue
             completionBlock:(nonnull void (^)(ZDCCryptoFile *_Nullable,
                                               NSError *_Nullable))completionBlock;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCacheFileWithKey encryptionKey: Data, completionQueue: DispatchQueue?, completionBlock: @escaping (ZDCCryptoFile?, Error?) -> Void) -> Progress

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the encryption progress.

  • Converts from unencrypted/cleartext format to cachefile format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextData:(nonnull NSData *)cleartextData
              toCacheFileWithKey:(nonnull NSData *)encryptionKey
                    outputStream:(nonnull NSOutputStream *)outStream
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCacheFileWithKey encryptionKey: Data, outputStream outStream: OutputStream) throws

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext format to cachefile format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextData:(nonnull NSData *)cleartextData
              toCacheFileWithKey:(nonnull NSData *)encryptionKey
                       outputURL:(nonnull NSURL *)outputFileURL
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCacheFileWithKey encryptionKey: Data, outputURL outputFileURL: URL) throws

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    outputFileURL

    The location to write the encrypted file.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext format to cachefile format.

    The operation is synchronous, and thus should be called from a background thread. If successful, the encrypted data is returned. Otherwise returns nil, and sets outError to the error that occurred.

    Declaration

    Objective-C

    + (nullable NSData *)encryptCleartextData:(nonnull NSData *)cleartextData
                           toCacheFileWithKey:(nonnull NSData *)encryptionKey
                                        error:
                                            (NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCacheFileWithKey encryptionKey: Data) throws -> Data

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    outError

    If something goes wrong, this parameter will tell you why.

    Return Value

    On success, returns the encrypted data. Returns nil if an error occurs.

  • Creates and returns a pump.

    This is typically used in conjunction with an API that gives you chunks of data at a time. And your goal is to take the cleartext chunks, and stream them to a cachefile on disk.

    Here’s how it works:

    • You call this method and get back 2 blocks: dataBlock & completionBlock
    • When your data provider gives you data, you invoke the databBlock
    • And when your data provider reports EOF (end-of-file) or error, you invoke the completionBlock
    • Barring any errors, you now have an encrypted version of the data on disk

    Declaration

    Objective-C

    + (nullable NSError *)
        encryptCleartextWithDataBlock:
            (NSError *_Nullable (^_Nonnull *_Nonnull)(NSData *_Nonnull))dataBlockOut
                      completionBlock:(NSError *_Nullable (^_Nonnull *_Nonnull)(
                                          void))completionBlockOut
                          toCacheFile:(nonnull NSURL *)outputFileURL
                              withKey:(nonnull NSData *)encryptionKey;

    Swift

    class func encryptCleartext(dataBlock dataBlockOut: AutoreleasingUnsafeMutablePointer<(Data) -> Error?>, completionBlock completionBlockOut: AutoreleasingUnsafeMutablePointer<() -> Error?>, toCacheFile outputFileURL: URL, withKey encryptionKey: Data) -> Error?

    Parameters

    dataBlockOut

    Returns the dataBlock that you’ll invoke. The data you pass to this block is the cleartext data that will get encrypted & written to the outputFileURL.

    completionBlockOut

    Returns the completionBlock that you’ll invoke. When you invoke this block you’re telling the encryption stream there’s no more data to encrypt, and it should finish the encryption process, and flush any remaining data to the disk. (You cannot invoke the dataBlock again after invoking the completionBlock.)

    outputFileURL

    The location to write the encrypted file.

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    Return Value

    Returns nil on success. Otherwise returns an error that describes what went wrong.

  • Converts from unencrypted/cleartext file format to cloud file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes. If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        encryptCleartextFile:(nonnull NSURL *)cleartextFileURL
          toCloudFileWithKey:(nonnull NSData *)encryptionKey
                    metadata:(nullable NSData *)metadata
                   thumbnail:(nullable NSData *)thumbnail
             completionQueue:(nullable dispatch_queue_t)completionQueue
             completionBlock:(nonnull void (^)(ZDCCryptoFile *_Nullable,
                                               NSError *_Nullable))completionBlock;

    Swift

    class func encryptCleartextFile(_ cleartextFileURL: URL, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?, completionQueue: DispatchQueue?, completionBlock: @escaping (ZDCCryptoFile?, Error?) -> Void) -> Progress

    Parameters

    cleartextFileURL

    The input file (stored unencrypted).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    completionQueue

    (optional) If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    (optional) The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the encryption progress.

  • Converts from unencrypted/cleartext file format to cloud file format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextFile:(nonnull NSURL *)cleartextFileURL
              toCloudFileWithKey:(nonnull NSData *)encryptionKey
                        metadata:(nullable NSData *)metadata
                       thumbnail:(nullable NSData *)thumbnail
                    outputStream:(nonnull NSOutputStream *)outStream
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextFile(_ cleartextFileURL: URL, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?, outputStream outStream: OutputStream) throws

    Parameters

    cleartextFileURL

    The input file (stored unencrypted).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    outStream

    An output stream to write to. This method will open the stream if it’s not already open.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext file format to cloud file format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextFile:(nonnull NSURL *)cleartextFileURL
              toCloudFileWithKey:(nonnull NSData *)encryptionKey
                        metadata:(nullable NSData *)metadata
                       thumbnail:(nullable NSData *)thumbnail
                       outputURL:(nonnull NSURL *)outputFileURL
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextFile(_ cleartextFileURL: URL, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?, outputURL outputFileURL: URL) throws

    Parameters

    cleartextFileURL

    The input file (stored unencrypted).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    outputFileURL

    The location to write the encrypted file.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext format to cloudfile format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes. If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        encryptCleartextData:(nonnull NSData *)cleartextData
          toCloudFileWithKey:(nonnull NSData *)encryptionKey
                    metadata:(nullable NSData *)metadata
                   thumbnail:(nullable NSData *)thumbnail
             completionQueue:(nullable dispatch_queue_t)completionQueue
             completionBlock:(nonnull void (^)(ZDCCryptoFile *_Nullable,
                                               NSError *_Nullable))completionBlock;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?, completionQueue: DispatchQueue?, completionBlock: @escaping (ZDCCryptoFile?, Error?) -> Void) -> Progress

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the encryption progress.

  • Converts from unencrypted/cleartext format to cloud file format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextData:(nonnull NSData *)cleartextData
              toCloudFileWithKey:(nonnull NSData *)encryptionKey
                        metadata:(nullable NSData *)metadata
                       thumbnail:(nullable NSData *)thumbnail
                    outputStream:(nonnull NSOutputStream *)outStream
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?, outputStream outStream: OutputStream) throws

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    outStream

    An output stream to write to. This method will open the stream if it’s not already open.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext format to cloudfile format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)encryptCleartextData:(nonnull NSData *)cleartextData
              toCloudFileWithKey:(nonnull NSData *)encryptionKey
                        metadata:(nullable NSData *)metadata
                       thumbnail:(nullable NSData *)thumbnail
                       outputURL:(nonnull NSURL *)outputFileURL
                           error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?, outputURL outputFileURL: URL) throws

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    outputFileURL

    The location to write the encrypted file.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from unencrypted/cleartext format to cloudfile format.

    The operation is synchronous, and thus should be called from a background thread. If successful, the encrypted data will be returned. Otherwise returns nil, and sets outError to the error that occurred.

    Declaration

    Objective-C

    + (nullable NSData *)encryptCleartextData:(nonnull NSData *)cleartextData
                           toCloudFileWithKey:(nonnull NSData *)encryptionKey
                                     metadata:(nullable NSData *)metadata
                                    thumbnail:(nullable NSData *)thumbnail
                                        error:
                                            (NSError *_Nullable *_Nullable)outError;

    Swift

    class func encryptCleartextData(_ cleartextData: Data, toCloudFileWithKey encryptionKey: Data, metadata: Data?, thumbnail: Data?) throws -> Data

    Parameters

    cleartextData

    The input data (unencrypted file in memory).

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    outError

    If something goes wrong, this parameter will tell you why.

    Return Value

    On success, returns the encrypted data. Returns nil if an error occurs.

  • Creates and returns a pump.

    This is typically used in conjunction with an API that gives you chunks of data at a time. And your goal is to take the cleartext chunks, and stream them to a cloudfile on disk.

    Here’s how it works:

    • You call this method and get back 2 blocks: dataBlock & completionBlock
    • When your data provider gives you data, you invoke the databBlock
    • And when your data provider reports EOF (end-of-file) or error, you invoke the completionBlock
    • Barring any errors, you now have an encrypted version of the data on disk

    Declaration

    Objective-C

    + (nullable NSError *)
        encryptCleartextWithDataBlock:
            (NSError *_Nullable (^_Nonnull *_Nonnull)(NSData *_Nonnull))dataBlockOut
                      completionBlock:(NSError *_Nullable (^_Nonnull *_Nonnull)(
                                          void))completionBlockOut
                          toCloudFile:(nonnull NSURL *)outputFileURL
                              withKey:(nonnull NSData *)encryptionKey
                             metadata:(nullable NSData *)metadata
                            thumbnail:(nullable NSData *)thumbnail;

    Swift

    class func encryptCleartext(dataBlock dataBlockOut: AutoreleasingUnsafeMutablePointer<(Data) -> Error?>, completionBlock completionBlockOut: AutoreleasingUnsafeMutablePointer<() -> Error?>, toCloudFile outputFileURL: URL, withKey encryptionKey: Data, metadata: Data?, thumbnail: Data?) -> Error?

    Parameters

    dataBlockOut

    Returns the dataBlock that you’ll invoke. The data you pass to this block is the cleartext data that will get encrypted & written to the outputFileURL.

    completionBlockOut

    Returns the completionBlock that you’ll invoke. When you invoke this block you’re telling the encryption stream there’s no more data to encrypt, and it should finish the encryption process, and flush any remaining data to the disk. (You cannot invoke the dataBlock again after invoking the completionBlock.)

    outputFileURL

    The location to write the encrypted file.

    encryptionKey

    A proper key for the encryption. If encrypting data that corresponds to a ZDCNode, then use -[ZDCNode encryptionKey]. Otherwise you can generate a key using +[ZDCNode randomEncryptionKey].

    metadata

    Optional metadata section to be included in the cloudfile.

    thumbnail

    Optional thumbnail section to be included in the cloudfile.

    Return Value

    Returns nil on success. Otherwise returns an error that describes what went wrong.

  • Converts a file from an encrypted format to an unencrypted/cleartext format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        decryptCryptoFile:(nonnull ZDCCryptoFile *)cryptoFile
          completionQueue:(nullable dispatch_queue_t)completionQueue
          completionBlock:(nonnull void (^)(NSURL *_Nullable,
                                            NSError *_Nullable))completionBlock;

    Swift

    class func decryptCryptoFile(_ cryptoFile: ZDCCryptoFile, completionQueue: DispatchQueue?, completionBlock: @escaping (URL?, Error?) -> Void) -> Progress

    Parameters

    cryptoFile

    Encapsulated information about the encrypted file.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the decryption progress.

  • Converts a file from an encrypted format to an unencrypted/cleartext format.

    The operation is synchronous, and thus should be called from a background thread. If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)decryptCryptoFile:(nonnull ZDCCryptoFile *)cryptoFile
               toOutputStream:(nonnull NSOutputStream *)outStream
                        error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func decryptCryptoFile(_ cryptoFile: ZDCCryptoFile, to outStream: OutputStream) throws

    Parameters

    cryptoFile

    Encapsulated information about the encrypted file.

    outStream

    An output stream to write to. This method will open the stream if it’s not already open.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts a file from an encrypted format to an unencrypted/cleartext format.

    The operation is synchronous, and thus should be called from a background thread. If successful, the cleartext/decrypted data will be returned. Otherwise a relavent error will be returned via the outError parameter that describes the error that occurred.

    Declaration

    Objective-C

    + (nullable NSData *)
        decryptCryptoFileIntoMemory:(nonnull ZDCCryptoFile *)cryptoFile
                              error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func decryptCryptoFile(intoMemory cryptoFile: ZDCCryptoFile) throws -> Data

    Parameters

    cryptoFile

    Encapsulated information about the encrypted file.

    outError

    If something goes wrong, this parameter will tell you why.

    Return Value

    On success, returns the decrypted data. Returns nil if an error occurs.

  • Converts a file from an encrypted format to an unencrypted/cleartext format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        decryptCryptoFileIntoMemory:(nonnull ZDCCryptoFile *)cryptoFile
                    completionQueue:(nullable dispatch_queue_t)completionQueue
                    completionBlock:
                        (nonnull void (^)(NSData *_Nullable,
                                          NSError *_Nullable))completionBlock;

    Swift

    class func decryptCryptoFile(intoMemory cryptoFile: ZDCCryptoFile, completionQueue: DispatchQueue?, completionBlock: @escaping (Data?, Error?) -> Void) -> Progress

    Parameters

    cryptoFile

    Encapsulated information about the encrypted file.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the decryption progress.

  • Converts from cache file format to unencrypted/cleartext file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        decryptCacheFile:(nonnull NSURL *)cacheFileURL
           encryptionKey:(nonnull NSData *)encryptionKey
             retainToken:(nullable id)retainToken
         completionQueue:(nullable dispatch_queue_t)completionQueue
         completionBlock:(nonnull void (^)(NSURL *_Nullable,
                                           NSError *_Nullable))completionBlock;

    Swift

    class func decryptCacheFile(_ cacheFileURL: URL, encryptionKey: Data, retainToken: Any?, completionQueue: DispatchQueue?, completionBlock: @escaping (URL?, Error?) -> Void) -> Progress

    Parameters

    cacheFileURL

    The input file (stored in cache file format).

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    encryptionKey

    The key that was used to encrypt the file.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the decryption progress.

  • Converts from cache file format to unencrypted/cleartext file format.

    The operation is synchronous, and thus should be called from a background thread.

    Declaration

    Objective-C

    + (BOOL)decryptCacheFile:(nonnull NSURL *)cacheFileURL
               encryptionKey:(nonnull NSData *)encryptionKey
                 retainToken:(nullable id)retainToken
              toOutputStream:(nonnull NSOutputStream *)outStream
                       error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func decryptCacheFile(_ cacheFileURL: URL, encryptionKey: Data, retainToken: Any?, to outStream: OutputStream) throws

    Parameters

    cacheFileURL

    The input file (stored in cache file format).

    encryptionKey

    The key that was used to encrypt the file.

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    outStream

    An output stream to write to. This method will open the stream if it’s not already open.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from cache file format to unencrypted/cleartext file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    Declaration

    Objective-C

    + (nullable NSData *)decryptCacheFileIntoMemory:(nonnull NSURL *)cacheFileURL
                                      encryptionKey:(nonnull NSData *)encryptionKey
                                        retainToken:(nullable id)retainToken
                                              error:(NSError *_Nullable *_Nullable)
                                                        outError;

    Swift

    class func decryptCacheFile(intoMemory cacheFileURL: URL, encryptionKey: Data, retainToken: Any?) throws -> Data

    Parameters

    cacheFileURL

    The input file (stored in cache file format).

    encryptionKey

    The key that was used to encrypt the file.

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    outError

    If something goes wrong, this parameter will tell you why.

    Return Value

    On success, returns the decrypted data. Returns nil if an error occurs.

  • Converts from cache file format to unencrypted/cleartext file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        decryptCacheFileIntoMemory:(nonnull NSURL *)cacheFileURL
                     encryptionKey:(nonnull NSData *)encryptionKey
                       retainToken:(nullable id)retainToken
                   completionQueue:(nullable dispatch_queue_t)completionQueue
                   completionBlock:
                       (nonnull void (^)(NSData *_Nullable,
                                         NSError *_Nullable))completionBlock;

    Swift

    class func decryptCacheFile(intoMemory cacheFileURL: URL, encryptionKey: Data, retainToken: Any?, completionQueue: DispatchQueue?, completionBlock: @escaping (Data?, Error?) -> Void) -> Progress

    Parameters

    cacheFileURL

    The input file (stored in cache file format).

    encryptionKey

    The key that was used to encrypt the file.

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the decryption progress.

  • Converts from cloud file format to unencrypted/cleartext file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        decryptCloudFile:(nonnull NSURL *)cloudFileURL
           encryptionKey:(nonnull NSData *)encryptionKey
             retainToken:(nullable id)retainToken
         completionQueue:(nullable dispatch_queue_t)completionQueue
         completionBlock:(nonnull void (^)(ZDCCloudFileHeader, NSData *_Nullable,
                                           NSData *_Nullable, NSURL *_Nullable,
                                           NSError *_Nullable))completionBlock;

    Swift

    class func decryptCloudFile(_ cloudFileURL: URL, encryptionKey: Data, retainToken: Any?, completionQueue: DispatchQueue?, completionBlock: @escaping (ZDCCloudFileHeader, Data?, Data?, URL?, Error?) -> Void) -> Progress

    Parameters

    cloudFileURL

    The input file (stored in cloud file format).

    encryptionKey

    The key that was used to encrypt the file.

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the decryption progress.

  • Converts from cloud file format to unencrypted/cleartext file format.

    The operation is synchronous, and thus should be called from a background thread.

    Note

    A cloudFile is composed of several sections: [header, metadata, thumbnail, data]. The only section written to the outStream by this method is the data section.

    @return If successful, a nil value will be returned. Otherwise a relavent error will be returned that should describe the error that occurred.

    Declaration

    Objective-C

    + (BOOL)decryptCloudFile:(nonnull NSURL *)cloudFileURL
               encryptionKey:(nonnull NSData *)encryptionKey
                 retainToken:(nullable id)retainToken
              toOutputStream:(nonnull NSOutputStream *)outStream
                       error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func decryptCloudFile(_ cloudFileURL: URL, encryptionKey: Data, retainToken: Any?, to outStream: OutputStream) throws

    Parameters

    cloudFileURL

    The input file (stored in cloud file format).

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    encryptionKey

    The key that was used to encrypt the file.

    outStream

    An output stream that is already open, and ready to be written to.

    outError

    If an error occurs, describes what went wrong.

    Return Value

    Returns YES on success, NO otherwise.

  • Converts from cloud file format to unencrypted/cleartext file format.

    The operation is synchronous, and thus should be called from a background thread.

    Declaration

    Objective-C

    + (nullable NSData *)decryptCloudFileIntoMemory:(nonnull NSURL *)cloudFileURL
                                      encryptionKey:(nonnull NSData *)encryptionKey
                                        retainToken:(nullable id)retainToken
                                              error:(NSError *_Nullable *_Nullable)
                                                        outError;

    Swift

    class func decryptCloudFile(intoMemory cloudFileURL: URL, encryptionKey: Data, retainToken: Any?) throws -> Data

    Parameters

    cloudFileURL

    The input file (stored in cloud file format).

    encryptionKey

    The key that was used to encrypt the file.

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    outError

    If something goes wrong, this parameter will tell you why.

    Return Value

    On success, returns the decrypted data. Returns nil if an error occurs.

  • Converts from cloud file format to unencrypted/cleartext file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
        decryptCloudFileIntoMemory:(nonnull NSURL *)cloudFileURL
                     encryptionKey:(nonnull NSData *)encryptionKey
                       retainToken:(nullable id)retainToken
                   completionQueue:(nullable dispatch_queue_t)completionQueue
                   completionBlock:
                       (nonnull void (^)(ZDCCloudFileHeader, NSData *_Nullable,
                                         NSData *_Nullable, NSData *_Nullable,
                                         NSError *_Nullable))completionBlock;

    Swift

    class func decryptCloudFile(intoMemory cloudFileURL: URL, encryptionKey: Data, retainToken: Any?, completionQueue: DispatchQueue?, completionBlock: @escaping (ZDCCloudFileHeader, Data?, Data?, Data?, Error?) -> Void) -> Progress

    Parameters

    cloudFileURL

    The input file (stored in cloud file format).

    encryptionKey

    The key that was used to encrypt the file.

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    completionQueue

    If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the decryption progress.

  • Converts from cache file format to cloud file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes. If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
          convertCacheFile:(nonnull NSURL *)cacheFileURL
               retainToken:(nullable id)retainToken
             encryptionKey:(nonnull NSData *)cacheFileEncryptionKey
        toCloudFileWithKey:(nonnull NSData *)cloudFileEncryptionKey
                  metadata:(nullable NSData *)metadata
                 thumbnail:(nullable NSData *)thumbnail
           completionQueue:(nullable dispatch_queue_t)completionQueue
           completionBlock:(nonnull void (^)(NSURL *_Nullable,
                                             NSError *_Nullable))completionBlock;

    Swift

    class func convertCacheFile(_ cacheFileURL: URL, retainToken: Any?, encryptionKey cacheFileEncryptionKey: Data, toCloudFileWithKey cloudFileEncryptionKey: Data, metadata: Data?, thumbnail: Data?, completionQueue: DispatchQueue?, completionBlock: @escaping (URL?, Error?) -> Void) -> Progress

    Parameters

    cacheFileURL

    The input file (stored in cache file format).

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    cacheFileEncryptionKey

    If given, the new cacheFile will be encrypted using the given encryptionKey. It not given, the new cacheFile will be encrypted using file.encryptionKey.

    completionQueue

    (optional) If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    (optional) The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the conversion progress.

  • Converts from cloud file format to cache file format.

    The operation is asynchronous, and the completionBlock should be used to detect when it completes. If successful, the output file will be written to the tempDirectoryURL, using a random fileName. The caller is responsible for moving the temp file into its permanent location, or deleting it.

    Declaration

    Objective-C

    + (nonnull NSProgress *)
          convertCloudFile:(nonnull NSURL *)cloudFileURL
               retainToken:(nullable id)retainToken
             encryptionKey:(nonnull NSData *)cloudFileEncryptionKey
        toCacheFileWithKey:(nonnull NSData *)cacheFileEncryptionKey
           completionQueue:(nonnull dispatch_queue_t)completionQueue
           completionBlock:(nonnull void (^)(ZDCCloudFileHeader, NSData *_Nullable,
                                             NSData *_Nullable, NSURL *_Nullable,
                                             NSError *_Nullable))completionBlock;

    Swift

    class func convertCloudFile(_ cloudFileURL: URL, retainToken: Any?, encryptionKey cloudFileEncryptionKey: Data, toCacheFileWithKey cacheFileEncryptionKey: Data, completionQueue: DispatchQueue, completionBlock: @escaping (ZDCCloudFileHeader, Data?, Data?, URL?, Error?) -> Void) -> Progress

    Parameters

    cloudFileURL

    The input file (stored in cloud file format).

    retainToken

    A retainToken from the CacheManager, than can be used to ensure the file isn’t deleted before it can be opened.

    cloudFileEncryptionKey

    The encryption key used when encrypting the input/cloudFileURL.

    cacheFileEncryptionKey

    The encryption key to use when creating/encrypting the output/cacheFile

    completionQueue

    (optional) If not specified, dispatch_get_main_queue() will be used.

    completionBlock

    (optional) The completionBlock to be executed when the operation is complete.

    Return Value

    A progress instance you can use to monitor the conversion progress.

  • Re-Encrypts an encrypted file (either in CacheFile or CloudFile format), by decrypting each block on the fly, and then re-encrypting them with a different key.

    Declaration

    Objective-C

    + (nonnull NSProgress *)reEncryptFile:(nonnull NSURL *)srcFileURL
                                  fromKey:(nonnull NSData *)srcEncryptionKey
                                    toKey:(nonnull NSData *)dstEncryptionKey
                          completionQueue:(nullable dispatch_queue_t)completionQueue
                          completionBlock:
                              (nonnull void (^)(NSURL *_Nullable,
                                                NSError *_Nullable))completionBlock;

    Swift

    class func reEncryptFile(_ srcFileURL: URL, fromKey srcEncryptionKey: Data, toKey dstEncryptionKey: Data, completionQueue: DispatchQueue?, completionBlock: @escaping (URL?, Error?) -> Void) -> Progress

    Return Value

    A progress instance you can use to monitor the conversion progress.

  • Re-Encrypts an encrypted file (either in CacheFile or CloudFile format), by decrypting each block on the fly, and then re-encrypting them with a different key.

    Declaration

    Objective-C

    + (BOOL)reEncryptFile:(nonnull NSURL *)srcFileURL
                  fromKey:(nonnull NSData *)srcEncryptionKey
                   toFile:(nonnull NSURL *)dstFileURL
                    toKey:(nonnull NSData *)dstEncryptionKey
                    error:(NSError *_Nullable *_Nullable)outError;

    Swift

    class func reEncryptFile(_ srcFileURL: URL, fromKey srcEncryptionKey: Data, toFile dstFileURL: URL, toKey dstEncryptionKey: Data) throws

    Return Value

    Returns YES on success, NO otherwise.