Merge "API doc improvement to FileIntegrityManager" into main
diff --git a/core/java/android/security/FileIntegrityManager.java b/core/java/android/security/FileIntegrityManager.java
index 2dbb5da..dae3202 100644
--- a/core/java/android/security/FileIntegrityManager.java
+++ b/core/java/android/security/FileIntegrityManager.java
@@ -76,28 +76,38 @@
* Enables fs-verity to the owned file under the calling app's private directory. It always uses
* the common configuration, i.e. SHA-256 digest algorithm, 4K block size, and without salt.
*
- * The operation can only succeed when the file is not opened as writable by any process.
+ * <p>For enabling fs-verity to succeed, the device must support fs-verity, the file must be
+ * writable by the app and not already have fs-verity enabled, and the file must not currently
+ * be open for writing by any process. To check whether the device supports fs-verity, use
+ * {@link #isApkVeritySupported()}.
*
- * It takes O(file size) time to build the underlying data structure for continuous
+ * <p>It takes O(file size) time to build the underlying data structure for continuous
* verification. The operation is atomic, i.e. it's either enabled or not, even in case of
* power failure during or after the call.
*
- * Note for the API users: When the file's authenticity is crucial, the app typical needs to
+ * <p>Note for the API users: When the file's authenticity is crucial, the app typical needs to
* perform a signature check by itself before using the file. The signature is often delivered
* as a separate file and stored next to the targeting file in the filesystem. The public key of
* the signer (normally the same app developer) can be put in the APK, and the app can use the
* public key to verify the signature to the file's actual fs-verity digest (from {@link
- * #getFsVerityDigest}) before using the file. The exact format is not prescribed by the
+ * #getFsVerityDigest(File)}) before using the file. The exact format is not prescribed by the
* framework. App developers may choose to use common practices like JCA for the signing and
* verification, or their own preferred approach.
*
- * @param file The file to enable fs-verity. It should be an absolute path.
+ * @param file The file to enable fs-verity. It must represent an absolute path.
+ * @throws IllegalArgumentException If the provided file is not an absolute path.
+ * @throws IOException If the operation failed.
*
* @see <a href="https://www.kernel.org/doc/html/next/filesystems/fsverity.html">Kernel doc</a>
*/
@FlaggedApi(Flags.FLAG_FSVERITY_API)
public void setupFsVerity(@NonNull File file) throws IOException {
if (!file.isAbsolute()) {
+ // fs-verity is to be enabled by installd, which enforces the validation to the
+ // (untrusted) file path passed from here. To make this less error prone, installd
+ // accepts only absolute path. When a relative path is provided, we fail with an
+ // explicit exception to help developers understand the requirement to use an absolute
+ // path.
throw new IllegalArgumentException("Expect an absolute path");
}
IFsveritySetupAuthToken authToken;
@@ -121,11 +131,12 @@
}
/**
- * Returns the fs-verity digest for the owned file under the calling app's
- * private directory, or null when the file does not have fs-verity enabled.
+ * Returns the fs-verity digest for the owned file under the calling app's private directory, or
+ * null when the file does not have fs-verity enabled (including when fs-verity is not supported
+ * on older devices).
*
* @param file The file to measure the fs-verity digest.
- * @return The fs-verity digeset in byte[], null if none.
+ * @return The fs-verity digest in byte[], null if none.
* @see <a href="https://www.kernel.org/doc/html/next/filesystems/fsverity.html">Kernel doc</a>
*/
@FlaggedApi(Flags.FLAG_FSVERITY_API)