v0.11.0

Changelog:

• Completely replace all the old iphone-dataprotection code. Add a new class utils.BackupKeyBag to represent keybags, with improved documentation and more consistent method and attribute names. Add utils.aes_unwrap(...) using pycryptodome's AES Key Wrapping functionality rather than a custom implementation, and add utils.aes_decrypt_cbc(...) for decryption, to replace the old versions in google_iphone_dataprotection. The module google_iphone_dataprotection still exists for backwards compatibility, but it is now deprecated will be removed in a future release.
• Raise custom exceptions for common error cases, for example backup directories that do not contain the right files, or incorrect passphrases. These are in the exceptions module e.g. iphone_backup_decrypt.exceptions.BackupNotEncryptedError, but the most likely are exposed at the top-level e.g. iphone_backup_decrypt.IncorrectPassphraseError.
• Allow per-file renaming of output files from backup.extract_files(...) using the filter_callback function. If the callback returns a string, that value will be used as-is as the output filename instead of the generated value. The generated output filepath is also now provided to the callback function. Returning True and False retains the existing behaviour. If existing callback functions use **kwargs as recommended, this is not a breaking change.
• Add full file PList data to the filter_callback signature in backup.extract_files(...). The callback now receives all of the data contained in the Manifest.db row for the file and can make sophisticated inclusion/exclusion decisions based on this. If existing callback functions use **kwargs as recommended, this is not a breaking change.
• Allow the use of the raw passphrase key instead of the passphrase when creating an EncryptedBackup. If this value is known, it saves computing it from the passphrase and so speeds up load time. The value required can be obtained from backup.keybag.passphrase_key after a successful decryption using the passphrase. Call backup.test_decryption() before accessing the keybag.
• Allow listing of folders and symlinks included in the backup Manifest.db file. The extract_files(...) method with preserve_folders=True does not actually use the folder structure recorded in Manifest.db directly; it creates the folders from the paths in extracted file names. There are some use-cases for accessing the folder metadata, such as obtaining folder creation and modification times not set by extract_files(...); the new backup.get_folders(...) generator can be used to loop through these. Similarly backup.get_symlinks(...) will provide data about the only other type of object recorded in the Files table of Manifest.db, though this is mostly for completeness and is not expected to be of much use.
• Check the contents of Manifest.plist before attempting any keybag or decryption operations, to verify the backup is marked as encrypted and error earlier if it is not.
• Avoid a filesystem call per extracted file if incremental=False in extract_files(...).
• Avoid creating the temporary folder required for the decrypted Manifest.db file until that decryption is required.
• Fix a bug where backup.decrypted was never correctly set, even after successful decryption!
• Upgrade pycryptodome dependency to latest, for AES Key Wrapping support.

Breaking changes

• Make keybag a public (rather than private) attribute of EncryptedBackup, using the new utils.BackupKeyBag class.
• Remove data from the public interface of FilePlist; if that object is truly still required, use _data. Add target (for symlink PLists), mode (for the read-write state as a string using hex notation) and created timestamp attributes.
• backup._unlocked has now been removed. Use either backup.decrypted or backup.keybag.unlocked if necessary.
• Some raised exceptions have changed type, though most extend the generic type they previously were.

v0.10.0...v0.11.0