CloudFile2CleartextInputStream

@interface CloudFile2CleartextInputStream : ZDCInputStream <NSCopying>

Converts from cloudFile (encrypted) format to cleartext (non-encrypted) format.

In other words, the stream takes as input a cloudFile source (via file/stream/data). And as output (what you receive when you invoke -read:maxLength:), it gives you the decrypted/cleartext version.

Use this for reading encrypted files in ZDCCryptoFileFormat_CloudFile.

How it works:

  • Create an instance of this class configured to read the raw cloudFile data, along with the encryption key for decrypting the cloudFile data.
  • Then continually invoke the -read:maxLength: method, passing in a buffer for the output (the decrypted/cleartext data).
  • This class will read and decrypt the next chuck of data, and write the decrypted version to your buffer.

  • Warning

    A CloudFile contains multiple sections.

    Recall that a CloudFile is composed of multiple different sections:

    • header (always present)
    • metadata (optional, may be present)
    • thumbnail (optiona, may be present)
    • data (always present)

    This class allows you to read every section. Which is a bit different from your average stream. So, to simplify its use, this class will perform a soft break between each section via the -read:maxLength: method. That is, the ‘read:maxLength’ method will return a 0 (zero) when you reach the end of a section. This ensures you will only ever receive data from a single section at a time.

    Thus, you can simply invoke ‘read:maxLength:’ until the -cloudFileSection reflects the section you’re interested in. If you want to jump to a particular section, you can use NSInputStream’s setProperty:forKey: method, and use the ZDCStreamCloudFileSection key.

    • Creates an instance that will read from the given cryptoFile, decrypt the data, and produce the decrypted data to you via ‘read:maxLength:’.

      Declaration

      Objective-C

      - (nonnull instancetype)initWithCryptoFile:(nonnull ZDCCryptoFile *)cryptoFile;

      Swift

      init(cryptoFile: ZDCCryptoFile)

      Parameters

      cryptoFile

      An instance which contains the fileURL & encryptionKey. Also stream.retainToken is set to cryptoFile.retainToken.

    • Creates an instance that will read from the given cloudFileURL, decrypt the data, and produce the decrypted data to you via ‘read:maxLength:’.

      Declaration

      Objective-C

      - (nonnull instancetype)initWithCloudFileURL:(nonnull NSURL *)cloudFileURL
                                     encryptionKey:(nonnull NSData *)encryptionKey;

      Swift

      init(cloudFileURL: URL, encryptionKey: Data)

      Parameters

      cloudFileURL

      The location of the encrypted file in cloud file format. The instance will open an inputStream with this URL in order to read the file.

      encryptionKey

      The key used to decrypt the file. (i.e. node.encryptionKey)

    • Creates an instance that will read from the given cloudFileStream, decrypt the data, and produce the decrypted data to you via ‘read:maxLength:’.

      Declaration

      Objective-C

      - (nonnull instancetype)initWithCloudFileStream:
                                  (nonnull NSInputStream *)cloudFileStream
                                        encryptionKey:(nonnull NSData *)encryptionKey;

      Swift

      init(cloudFileStream: InputStream, encryptionKey: Data)

      Parameters

      cloudFileStream

      A stream that can be used to read the encrypted file in cloud file format.

      encryptionKey

      The key used to decrypt the file. (i.e. node.encryptionKey)

    • Creates an instance that will read from the given cloudFileData, decrypt the data, and produce the decrypted data to you via ‘read:maxLength:’.

      Note

      If your cloudFile data is in a file, don’t use this method. Instead you should be using initWithCloudFileURL::.

      Declaration

      Objective-C

      - (nonnull instancetype)initWithCloudFileData:(nonnull NSData *)cloudFileData
                                      encryptionKey:(nonnull NSData *)encryptionKey;

      Swift

      init(cloudFileData: Data, encryptionKey: Data)

      Parameters

      cloudFileData

      A smallish chunk of data. If your data is in a file, use initWithCloudFileURL:: instead.

      encryptionKey

      The key used to decrypt the file. (i.e. node.encryptionKey)

    • This property is available anytime after the stream has been opened.

      Declaration

      Objective-C

      @property (readonly, nonatomic) NSNumber *_Nonnull cleartextFileSize;

      Swift

      var cleartextFileSize: NSNumber { get }
    • This property is available anytime after the cloudFileSection has been set to ZDCCloudFileSection_Metadata (or higher).

      Declaration

      Objective-C

      @property (readonly, nonatomic) ZDCCloudFileHeader cloudFileHeader;

      Swift

      var cloudFileHeader: ZDCCloudFileHeader { get }
    • Every invocation of ‘read:maxLength:’ will only ever give you data from a single section at a time. This property tells you what the next invocation of ‘read:maxLength:’ will return to you.

      Note

      You can jump to a particular section by using the setProperty:forKey: method. For the key you pass ZDCStreamCloudFileSection. And for the value you pass ZDCCloudFileSection (wrapped as NSNumber).

      Declaration

      Objective-C

      @property (readonly, nonatomic) ZDCCloudFileSection cloudFileSection;

      Swift

      var cloudFileSection: ZDCCloudFileSection { get }
    • This method is used to read just the header, metadata & thumbnail sections of a cloud file.

      Pass nil/NULL for anything you don’t need, and this method will skip attempting to read that section.

      Since this method only attempts to read part of the cloud file, the stream can represent a partial file. (e.g. only the first X bytes)

      Declaration

      Objective-C

      + (BOOL)decryptCloudFileStream:
                  (nonnull CloudFile2CleartextInputStream *)inputStream
                              header:(ZDCCloudFileHeader *_Nullable)headerPtr
                         rawMetadata:(NSData *_Nullable *_Nullable)metadataPtr
                        rawThumbnail:(NSData *_Nullable *_Nullable)thumbnailPtr
                               error:(NSError *_Nullable *_Nullable)errorPtr;

      Swift

      class func decryptCloudFileStream(_ inputStream: CloudFile2CleartextInputStream, header headerPtr: UnsafeMutablePointer<ZDCCloudFileHeader>?, rawMetadata metadataPtr: AutoreleasingUnsafeMutablePointer<NSData?>?, rawThumbnail thumbnailPtr: AutoreleasingUnsafeMutablePointer<NSData?>?) throws
    • This method is used to read the header, metadata & thumbnail sections of a cloud file. As such, the data you pass can be a partially downloaded cloud file.

      Pass nil/NULL for anything you don’t expect to be in the (partial) data, and this method will skip attempting to read that section.

      For example, if you only downloaded the header & metadata, simply pass null for the thumbnail, and the code won’t bother reading/decrypting that section.

      Declaration

      Objective-C

      + (BOOL)decryptCloudFileData:(nonnull NSData *)cloudFileData
                 withEncryptionKey:(nonnull NSData *)encryptionKey
                            header:(ZDCCloudFileHeader *_Nullable)headerPtr
                       rawMetadata:(NSData *_Nullable *_Nullable)metadataPtr
                      rawThumbnail:(NSData *_Nullable *_Nullable)thumbnailPtr
                             error:(NSError *_Nullable *_Nullable)errorPtr;

      Swift

      class func decryptCloudFileData(_ cloudFileData: Data, withEncryptionKey encryptionKey: Data, header headerPtr: UnsafeMutablePointer<ZDCCloudFileHeader>?, rawMetadata metadataPtr: AutoreleasingUnsafeMutablePointer<NSData?>?, rawThumbnail thumbnailPtr: AutoreleasingUnsafeMutablePointer<NSData?>?) throws
    • This method is used to read the header, metadata & thumbnail sections of a cloud file. As such, the URL you pass can be a partially downloaded cloud file.

      Pass nil/NULL for anything you don’t expect to be in the (partial) data, and this method will skip attempting to read that section.

      For example, if you only downloaded the header & metadata, simply pass null for the thumbnail, and the code won’t bother reading/decrypting that section.

      Declaration

      Objective-C

      + (BOOL)decryptCloudFileURL:(nonnull NSURL *)cloudFileURL
                withEncryptionKey:(nonnull NSData *)encryptionKey
                           header:(ZDCCloudFileHeader *_Nullable)headerPtr
                      rawMetadata:(NSData *_Nullable *_Nullable)metadataPtr
                     rawThumbnail:(NSData *_Nullable *_Nullable)thumbnailPtr
                            error:(NSError *_Nullable *_Nullable)errorPtr;

      Swift

      class func decryptCloudFileURL(_ cloudFileURL: URL, withEncryptionKey encryptionKey: Data, header headerPtr: UnsafeMutablePointer<ZDCCloudFileHeader>?, rawMetadata metadataPtr: AutoreleasingUnsafeMutablePointer<NSData?>?, rawThumbnail thumbnailPtr: AutoreleasingUnsafeMutablePointer<NSData?>?) throws
    • This method can be used to decrypt bytes from the middle of a cloud file.

      Declaration

      Objective-C

      + (nullable NSData *)decryptCloudFileBlocks:(nonnull NSData *)cloudFileBlocks
                                   withByteOffset:(uint64_t)byteOffset
                                    encryptionKey:(nonnull NSData *)encryptionKey
                                            error:(NSError *_Nullable *_Nullable)
                                                      errorPtr;

      Swift

      class func decryptCloudFileBlocks(_ cloudFileBlocks: Data, withByteOffset byteOffset: UInt64, encryptionKey: Data) throws -> Data

      Parameters

      cloudFileBlocks

      Data from the cloud file. The length of this data must be a perfect multiple of encryptionKey.length.

      byteOffset

      The offset (in bytes) of cloudFileBlocks, from the very beginning of the cloud file. This value must be a perfect multiple of kZDCNode_TweakBlockSizeInBytes.

      encryptionKey

      The symmetric key used to encrypt/decrypt the file.

      errorPtr

      If an error occurs, this will tell you what went wrong.

      Return Value

      The decrypted cleartext data if the decryption process was successful. Nil otherwise.