From cebb55ea9d98dc7ba93eed520b874ac24ff96800 Mon Sep 17 00:00:00 2001
From: Robert Berry <robertberry@google.com>
Date: Tue, 27 Mar 2018 15:26:37 +0100
Subject: [PATCH] Update docs to match encryption requirements

Bug: 70900575
Test: none, it's documentation
Change-Id: I9b85063bca636dca3085b187b736664f8d3f3c53
---
 core/java/android/app/backup/BackupAgent.java     | 15 +++++++++++----
 .../java/android/app/backup/BackupDataOutput.java |  6 +++++-
 .../android/app/backup/FullBackupDataOutput.java  |  6 +++++-
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/core/java/android/app/backup/BackupAgent.java b/core/java/android/app/backup/BackupAgent.java
index d1c957b8fedc6..39b9181b9b6ed 100644
--- a/core/java/android/app/backup/BackupAgent.java
+++ b/core/java/android/app/backup/BackupAgent.java
@@ -148,10 +148,17 @@ public abstract class BackupAgent extends ContextWrapper {
      * Flag for {@link BackupDataOutput#getTransportFlags()} and
      * {@link FullBackupDataOutput#getTransportFlags()} only.
      *
-     * <p>The transport has client-side encryption enabled. i.e., the user's backup has been
-     * encrypted with a key known only to the device, and not to the remote storage solution. Even
-     * if an attacker had root access to the remote storage provider they should not be able to
-     * decrypt the user's backup data.
+     * <p>The transport has client-side encryption enabled. i.e., the user's backup is encrypted
+     * with a key known only to the device, and not to the remote storage solution where the backup
+     * data is stored. The key may be synced to a remote trusted hardware module if it has
+     * protections equivalent to those described in the
+     * <a href="https://developer.android.com/preview/features/security/ckv-whitepaper.html">Google
+     * Cloud Key Vault Service whitepaper</a>. Having direct access to the trusted hardware module
+     * must be insufficient to decrypt the user's backup data.
+     *
+     * <p>The backup data itself must be encrypted using an AES/GCM/NoPadding cipher. The key
+     * material must be randomly generated using {@link java.security.SecureRandom}, and must have
+     * at least 256 bits of entropy.
      */
     public static final int FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED = 1;
 
diff --git a/core/java/android/app/backup/BackupDataOutput.java b/core/java/android/app/backup/BackupDataOutput.java
index 5a66f34074176..4f90cf7781e00 100644
--- a/core/java/android/app/backup/BackupDataOutput.java
+++ b/core/java/android/app/backup/BackupDataOutput.java
@@ -107,8 +107,12 @@ public class BackupDataOutput {
 
     /**
      * Returns flags with additional information about the backup transport. For supported flags see
-     * {@link android.app.backup.BackupAgent}
+     * {@link android.app.backup.BackupAgent}.
      *
+     * <p>Returns the same flags that {@link BackupTransport#getTransportFlags()} returns.
+     *
+     * @see BackupAgent#FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED
+     * @see BackupAgent#FLAG_DEVICE_TO_DEVICE_TRANSFER
      * @see FullBackupDataOutput#getTransportFlags()
      */
     public int getTransportFlags() {
diff --git a/core/java/android/app/backup/FullBackupDataOutput.java b/core/java/android/app/backup/FullBackupDataOutput.java
index 18f4283399415..f1d9dc6fa93cd 100644
--- a/core/java/android/app/backup/FullBackupDataOutput.java
+++ b/core/java/android/app/backup/FullBackupDataOutput.java
@@ -26,8 +26,12 @@ public class FullBackupDataOutput {
 
     /**
      * Returns flags with additional information about the backup transport. For supported flags see
-     * {@link android.app.backup.BackupAgent}
+     * {@link android.app.backup.BackupAgent}.
      *
+     * <p>Returns the same flags that {@link BackupTransport#getTransportFlags()} returns.
+     *
+     * @see BackupAgent#FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED
+     * @see BackupAgent#FLAG_DEVICE_TO_DEVICE_TRANSFER
      * @see BackupDataOutput#getTransportFlags()
      */
     public int getTransportFlags() {