seedvault/README.md

# Seedvault
[![Build](https://github.com/seedvault-app/seedvault/actions/workflows/build.yml/badge.svg)](https://github.com/seedvault-app/seedvault/actions/workflows/build.yml)

A backup application for the [Android Open Source Project](https://source.android.com/).

If you are having an issue/question, please look at our [FAQ](../../wiki/FAQ).

## Components

* [Local Contacts Backup](contactsbackup) - an app that backs up local on-device contacts
* [Storage library](storage) - a library handling efficient backup of files
* [Seedvault app](app) - the main app where all functionality comes together

## Features
- Backup application data to a flash drive.
- Restore application data from a flash drive.
- User-friendly encryption using a mnemonic phrase (BIP39).
- Automatic daily backups that run in the background.

## Requirements

SeedVault is developed alongwith AOSP releases

We update it every time Google releases a new Android version, make any changes required for basic functionality, and any improvements possible through API changes in the OS.

This means that for ROMs using SeedVault it's recommended to use the same branch as your android version

- This current branch `android14` is meant for usage with Android 14
- This is indicated by the version name starting with `14`, and the version code starting with `34` - the Android 14 API version

For older versions of Android, check out [the branches](https://github.com/seedvault-app/seedvault/branches).

Trying to use an older branch on a newer version may lead to issues and is not something we can support.

## Getting Started
- Check out [the wiki](https://github.com/seedvault-app/seedvault/wiki) for information on building the application with 
AOSP.

## What makes this different?
This application is compiled with the operating system and does not require a rooted device for use.
It uses the same internal APIs as `adb backup` which is deprecated and thus needs a replacement.

## Permissions
* `android.permission.BACKUP` to back up application data.
* `android.permission.ACCESS_NETWORK_STATE` to check if there is internet access when network storage is used.
* `android.permission.MANAGE_USB` to access the serial number of USB mass storage devices.
* `android.permission.WRITE_SECURE_SETTINGS` to change system backup settings and enable call log backup.
* `android.permission.QUERY_ALL_PACKAGES` to get information about all installed apps for backup.
* `android.permission.INSTALL_PACKAGES` to re-install apps when restoring from backup.
* `android.permission.MANAGE_EXTERNAL_STORAGE` to backup and restore files from device storage.
* `android.permission.ACCESS_MEDIA_LOCATION` to backup original media files e.g. without stripped EXIF metadata.
* `android.permission.FOREGROUND_SERVICE` to do periodic storage backups without interruption.
* `android.permission.FOREGROUND_SERVICE_DATA_SYNC` to do periodic storage backups without interruption.
* `android.permission.MANAGE_DOCUMENTS` to retrieve the available storage roots (optional) for better UX.
* `android.permission.USE_BIOMETRIC` to authenticate saving a new recovery code
* `android.permission.INTERACT_ACROSS_USERS_FULL` to use storage roots in other users (optional).
* `android.permission.POST_NOTIFICATIONS` to inform users about backup status and errors.

## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/seedvault-app/seedvault.

See [DEVELOPMENT.md](app/development/DEVELOPMENT.md) for information on developing Seedvault locally.

This project aims to adhere to the [official Kotlin coding style](https://developer.android.com/kotlin/style-guide).

## Third-party tools

> **⚠ WARNING**: the Seedvault developers make no guarantees about external software projects.
> Please be aware that disclosing your secret recovery key to other software has security risks.

The [Seedvault backup parser](https://github.com/tlambertz/seedvault_backup_parser)
allows you to decrypt and inspect your backups (version 0 backup).
It can also re-encrypt them.

The [Seedvault extractor](https://github.com/jackwilsdon/seedvault-extractor)
allows you to decrypt and inspect your backups from newer versions of Seedvault (version 1 backup).
It is currently work-in-progress.

## License
This application is available as open source under the terms of the [Apache-2.0 License](https://opensource.org/licenses/Apache-2.0).

## Funding

### Calyx Institute

This project is primarily developed and maintained by the [Calyx Institute](https://calyxinstitute.org/)
for usage in [CalyxOS](https://calyxos.org/).

### NGI0 PET Fund

This project was funded through the [NGI0 PET Fund](https://nlnet.nl/project/Seedvault/),
a fund established by [NLnet](https://nlnet.nl)
with financial support from the European Commission's Next Generation Internet programme,
under the aegis of DG Communications Networks, Content and Technology
under grant agreement No 825310.
Rebrand application as 'Seedvault' 2019-10-29 02:57:47 +01:00			`# Seedvault`
Update build badge in README 2024-04-11 22:11:41 +02:00			`[![Build](https://github.com/seedvault-app/seedvault/actions/workflows/build.yml/badge.svg)](https://github.com/seedvault-app/seedvault/actions/workflows/build.yml)`
Add Travis badge 2018-11-14 00:12:05 +01:00
Initial commit 2017-09-21 04:42:15 +02:00			`A backup application for the [Android Open Source Project](https://source.android.com/).`

Link FAQ in Readme to make it more discoverable E.g. for https://github.com/seedvault-app/seedvault/issues/264 I found the FAQ way to late. And for users this is a very valuable resource. As such, IMHO you should make it more discoverable, e.g. like this. 2021-08-28 14:40:07 +02:00			`If you are having an issue/question, please look at our [FAQ](../../wiki/FAQ).`

add READMEs and tie them together in main README 2021-03-05 18:05:04 +01:00			`## Components`

			`* [Local Contacts Backup](contactsbackup) - an app that backs up local on-device contacts`
			`* [Storage library](storage) - a library handling efficient backup of files`
			`* [Seedvault app](app) - the main app where all functionality comes together`

Update README.md with features list and link to wiki 2017-10-13 04:56:47 +02:00			`## Features`
Update README.md to reflect latest features and permissions 2019-11-30 20:32:39 +01:00			`- Backup application data to a flash drive.`
			`- Restore application data from a flash drive.`
			`- User-friendly encryption using a mnemonic phrase (BIP39).`
			`- Automatic daily backups that run in the background.`
Update README.md with features list and link to wiki 2017-10-13 04:56:47 +02:00
add requirements topic let users know that A10 or higher is needed 2020-07-27 10:48:15 +02:00			`## Requirements`
Change AOSP version requirement in README and add note about older releases in branches. 2020-09-17 14:06:48 +02:00
README: Add more details about branching (#445) 2022-09-13 19:53:10 +02:00			`SeedVault is developed alongwith AOSP releases`

			`We update it every time Google releases a new Android version, make any changes required for basic functionality, and any improvements possible through API changes in the OS.`

			`This means that for ROMs using SeedVault it's recommended to use the same branch as your android version`

README: 13 -> 14 Change-Id: Ia5ebd0f3f1ccb5f9261a956f2485d60f22a5f269 2023-10-07 21:00:19 +02:00			- This current branch `android14` is meant for usage with Android 14
			- This is indicated by the version name starting with `14`, and the version code starting with `34` - the Android 14 API version
Change AOSP version requirement in README and add note about older releases in branches. 2020-09-17 14:06:48 +02:00
Switch all text references to github.com/seedvault-app 2021-04-19 23:28:37 +02:00			`For older versions of Android, check out [the branches](https://github.com/seedvault-app/seedvault/branches).`
add requirements topic let users know that A10 or higher is needed 2020-07-27 10:48:15 +02:00
README: Add more details about branching (#445) 2022-09-13 19:53:10 +02:00			`Trying to use an older branch on a newer version may lead to issues and is not something we can support.`

Update README.md with features list and link to wiki 2017-10-13 04:56:47 +02:00			`## Getting Started`
Switch all text references to github.com/seedvault-app 2021-04-19 23:28:37 +02:00			`- Check out [the wiki](https://github.com/seedvault-app/seedvault/wiki) for information on building the application with`
Update README.md with features list and link to wiki 2017-10-13 04:56:47 +02:00			`AOSP.`

Add advantages section to README.md 2017-11-09 06:08:29 +01:00			`## What makes this different?`
Re-install backed-up APKs before restoring from backup 2019-12-20 17:55:38 +01:00			`This application is compiled with the operating system and does not require a rooted device for use.`
			It uses the same internal APIs as `adb backup` which is deprecated and thus needs a replacement.
Add contributing section to README.md 2017-10-13 05:54:55 +02:00
Resolve review comments about backup compontent refactoring 2019-06-12 14:19:38 +02:00			`## Permissions`
Update README.md to reflect latest features and permissions 2019-11-30 20:32:39 +01:00			* `android.permission.BACKUP` to back up application data.
Request backoff when asked to backup to network storage while no internet available K/V backups are normally only attempted when charging and having an (un-metered) internet connection. However, if the system could not do a backup for more than a day, it ignores these requirements and still attempts a backup run. If a backup storage is used that is only accessible on the internet, but there is no internet connection, the backup attempt will fail. Therefore, we check if our storage requires the internet and if so, we treat it similar to a removable storage, by rejecting backup attempts and suppressing error notifications. 2020-10-19 20:44:36 +02:00			* `android.permission.ACCESS_NETWORK_STATE` to check if there is internet access when network storage is used.
Update README.md to reflect latest features and permissions 2019-11-30 20:32:39 +01:00			* `android.permission.MANAGE_USB` to access the serial number of USB mass storage devices.
Enable backup of call logs It turned out that call log backup is already in AOSP, but it is disabled by an undocumented flag. This commit sets this flag (for new and existing installs) to enable call log backup. 2020-09-02 19:37:02 +02:00			* `android.permission.WRITE_SECURE_SETTINGS` to change system backup settings and enable call log backup.
Add QUERY_ALL_PACKAGES permission which is now needed on Android 11 2020-09-10 14:26:55 +02:00			* `android.permission.QUERY_ALL_PACKAGES` to get information about all installed apps for backup.
Re-install backed-up APKs before restoring from backup 2019-12-20 17:55:38 +01:00			* `android.permission.INSTALL_PACKAGES` to re-install apps when restoring from backup.
Add storage library (and demo app) and use for periodic files backup 2021-01-19 13:14:52 +01:00			* `android.permission.MANAGE_EXTERNAL_STORAGE` to backup and restore files from device storage.
			* `android.permission.ACCESS_MEDIA_LOCATION` to backup original media files e.g. without stripped EXIF metadata.
			* `android.permission.FOREGROUND_SERVICE` to do periodic storage backups without interruption.
14: Add new permission FOREGROUND_SERVICE_DATA_SYNC * Android.bp build means we get set to targetSdk 34 already Fixes: Starting FGS with type dataSync targetSDK=34 requires permissions See: https://developer.android.com/about/versions/14/changes/fgs-types-required#data-sync Change-Id: I69932d778e870535522e08dff131f1bb1d128955 2023-10-07 20:50:26 +02:00			* `android.permission.FOREGROUND_SERVICE_DATA_SYNC` to do periodic storage backups without interruption.
Make MANAGE_DOCUMENTS permission optional for those who can not or do not want to use it Fixes #58 2020-10-21 22:19:30 +02:00			* `android.permission.MANAGE_DOCUMENTS` to retrieve the available storage roots (optional) for better UX.
Ask for system authentication before storing a new recovery code This will help to prevent data extraction via seedvault when somebody gets hold of an unlocked phone. However, it will not help against someone able to force you to provide fingerprints or other device secrets. 2021-08-11 11:54:28 +02:00			* `android.permission.USE_BIOMETRIC` to authenticate saving a new recovery code
Allow secondary user backup to USB By default, Android exposes USB devices only to the main user. In order to query, read and write to it, the signature permission INTERACT_ACROSS_USERS_FULL (optional) is granted to create Seedvault's context as the system user. Issue: calyxos#437 Issue: https://github.com/seedvault-app/seedvault/issues/77 Change-Id: I0b1b4c8c5aeeb226419ff94e15f631ebe1db66df 2021-06-30 03:33:25 +02:00			* `android.permission.INTERACT_ACROSS_USERS_FULL` to use storage roots in other users (optional).
Add POST_NOTIFICATIONS permission and pre-grant it 2022-08-23 15:59:37 +02:00			* `android.permission.POST_NOTIFICATIONS` to inform users about backup status and errors.
Resolve review comments about backup compontent refactoring 2019-06-12 14:19:38 +02:00
Update README.md to reflect latest features and permissions 2019-11-30 20:32:39 +01:00			`## Contributing`
Remove redirect from README 2021-01-11 20:38:46 +01:00			`Bug reports and pull requests are welcome on GitHub at https://github.com/seedvault-app/seedvault.`
Auto-format code style of all files to match official style This also adds a note to the README and the Android Studio coding style files. 2020-09-24 20:45:59 +02:00
Add support for local development with an emulator 2023-09-10 04:25:36 +02:00			`See [DEVELOPMENT.md](app/development/DEVELOPMENT.md) for information on developing Seedvault locally.`

Auto-format code style of all files to match official style This also adds a note to the README and the Android Studio coding style files. 2020-09-24 20:45:59 +02:00			`This project aims to adhere to the [official Kotlin coding style](https://developer.android.com/kotlin/style-guide).`
Resolve review comments about backup compontent refactoring 2019-06-12 14:19:38 +02:00
Add Seedvault backup parser to README Closes #104 2020-10-05 15:41:07 +02:00			`## Third-party tools`

Add warning for third-party tools to README 2021-09-02 14:29:05 +02:00			`> ⚠ WARNING: the Seedvault developers make no guarantees about external software projects.`
			`> Please be aware that disclosing your secret recovery key to other software has security risks.`

Add Seedvault backup parser to README Closes #104 2020-10-05 15:41:07 +02:00			`The [Seedvault backup parser](https://github.com/tlambertz/seedvault_backup_parser)`
Include extractor project in README.md 2023-05-19 15:07:16 +02:00			`allows you to decrypt and inspect your backups (version 0 backup).`
Add Seedvault backup parser to README Closes #104 2020-10-05 15:41:07 +02:00			`It can also re-encrypt them.`

Include extractor project in README.md 2023-05-19 15:07:16 +02:00			`The [Seedvault extractor](https://github.com/jackwilsdon/seedvault-extractor)`
			`allows you to decrypt and inspect your backups from newer versions of Seedvault (version 1 backup).`
			`It is currently work-in-progress.`

Initial commit 2017-09-21 04:42:15 +02:00			`## License`
Update changelog and readme for 1.0.0-alpha1 2019-12-23 02:20:12 +01:00			`This application is available as open source under the terms of the [Apache-2.0 License](https://opensource.org/licenses/Apache-2.0).`
Add funding section to README 2023-03-06 18:42:21 +01:00
			`## Funding`

			`### Calyx Institute`

			`This project is primarily developed and maintained by the [Calyx Institute](https://calyxinstitute.org/)`
			`for usage in [CalyxOS](https://calyxos.org/).`

			`### NGI0 PET Fund`

			`This project was funded through the [NGI0 PET Fund](https://nlnet.nl/project/Seedvault/),`
			`a fund established by [NLnet](https://nlnet.nl)`
			`with financial support from the European Commission's Next Generation Internet programme,`
			`under the aegis of DG Communications Networks, Content and Technology`
			`under grant agreement No 825310.`