Encrypted store README: Document security section
Additionally, also introduce the intersection of Encrypted Store &
Updatable VM.
Bug: 329202578
Test: N/A
Change-Id: If08e4282a25d709492cca22667772c08c2dfd315
diff --git a/README.md b/README.md
index 827e55c..4905b56 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@
* [Microdroid kernel](microdroid/kernel/README.md)
* [Microdroid payload](microdroid/payload/README.md)
* [vmbase](vmbase/README.md)
+* [Encrypted Storage](encryptedstore/README.md)
AVF APIs:
* [Java API](java/framework/README.md)
diff --git a/encryptedstore/README.md b/encryptedstore/README.md
new file mode 100644
index 0000000..544d6eb
--- /dev/null
+++ b/encryptedstore/README.md
@@ -0,0 +1,31 @@
+# Encrypted Storage
+
+Since Android U, AVF (with Microdroid) supports Encrypted Storage which is the storage solution
+in a VM. Within a VM, this is mounted at a path that can be retrieved via the [`AVmPayload_getEncryptedStoragePath()`][vm_payload_api].
+Any data written in encrypted storage is persisted and is available next time the VM is run.
+
+Encrypted Storage is backed by a para-virtualized block device on the guest which is further
+backed by a qcow2 disk image in the host. The block device is formatted with an ext4 filesystem.
+
+## Security
+
+Encrypted Storage uses block level encryption layer (Device-Mapper's "crypt" target) using a key
+derived from the VM secret and AES256 cipher with HCTR2 mode. The Block level encryption ensures
+the filesystem is also encrypted.
+
+### Integrity
+Encrypted Storage does not offer the level of integrity offered by primitives such as
+authenticated encryption/dm-integrity/RPMB. That level of integrity comes with substantial
+disk/performance overhead. Instead, it uses HCTR2 which is a super-pseudorandom
+permutation encryption mode, this offers better resilience against malleability attacks (than other
+modes such as XTS).
+
+## Encrypted Storage and Updatable VMs
+
+With [Updatable VM feature][updatable_vm] shipping in Android V, Encrypted Storage can be accessed
+even after OTA/updates of boot images and apks. This requires chipsets to support [Secretkeeper HAL][sk_hal].
+
+
+[vm_payload_api]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/vm_payload/include/vm_payload.h;l=2?q=vm_payload%2Finclude%2Fvm_payload.h&ss=android%2Fplatform%2Fsuperproject%2Fmain
+[updatable_vm]: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/docs/updatable_vm.md
+[sk_hal]: https://cs.android.com/android/platform/superproject/main/+/main:system/secretkeeper/README.md
diff --git a/java/framework/README.md b/java/framework/README.md
index cf7a6cb..bbcd0ef 100644
--- a/java/framework/README.md
+++ b/java/framework/README.md
@@ -339,6 +339,8 @@
powerful attacker could delete it, wholly or partially roll it back to an
earlier version, or modify it, corrupting the data.
+For more info see [README](https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Virtualization/java/framework/README.md)
+
# Transferring a VM
It is possible to make a copy of a VM instance. This can be used to transfer a
diff --git a/libs/devicemapper/src/crypt.rs b/libs/devicemapper/src/crypt.rs
index 36c45c7..3afd374 100644
--- a/libs/devicemapper/src/crypt.rs
+++ b/libs/devicemapper/src/crypt.rs
@@ -15,8 +15,8 @@
*/
/// `crypt` module implements the "crypt" target in the device mapper framework. Specifically,
-/// it provides `DmCryptTargetBuilder` struct which is used to construct a `DmCryptTarget` struct
-/// which is then given to `DeviceMapper` to create a mapper device.
+/// it provides `DmCryptTargetBuilder` struct which is used to construct a `DmCryptTarget`
+/// struct which is then given to `DeviceMapper` to create a mapper device.
use crate::DmTargetSpec;
use anyhow::{ensure, Context, Result};
@@ -33,9 +33,14 @@
/// Supported ciphers
#[derive(Clone, Copy, Debug)]
pub enum CipherType {
- // AES-256-HCTR2 takes a 32-byte key
+ /// AES256 with HCTR2 mode. HCTR2 is a tweakable super-pseudorandom permutation
+ /// length-preserving encryption mode. It is the preferred mode in absence of other
+ /// dedicated integrity primitives (such as for encryptedstore in pVM) since it is less
+ /// malleable than other modes.
AES256HCTR2,
- // XTS requires key of twice the length of the underlying block cipher i.e., 64B for AES256
+ /// AES with XTS mode. This has slight performance benefits over HCTR2. In particular, XTS is
+ /// supported by inline encryption hardware. Note that (status quo) `encryptedstore` in VMs
+ /// is the only user of this module & inline encryption is not supported by guest kernel.
AES256XTS,
}
impl CipherType {
@@ -50,7 +55,10 @@
fn get_required_key_size(&self) -> usize {
match *self {
+ // AES-256-HCTR2 takes a 32-byte key
CipherType::AES256HCTR2 => 32,
+ // XTS requires key of twice the length of the underlying block cipher
+ // i.e., 64B for AES256
CipherType::AES256XTS => 64,
}
}