tequilaOS/platform_hardware_interfaces
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge "Create Secure Storage AIDL interface" into main am: 7f20fbe400

Browse source 
Original change: https://android-review.googlesource.com/c/platform/hardware/interfaces/+/2585668

Change-Id: I02e4e6750ac89471d49bdd7c2c1320f20d4641c9
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
This commit is contained in:
Weston Carvalho 2024-02-21 21:55:47 +00:00 committed by Automerger Merge Worker
commit dbe3ce37e9
15 changed files with 674 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
staging/security/see/storage/aidl/Android.bp Normal file
View file

@ -0,0 +1,26 @@
package {
default_applicable_licenses: ["hardware_interfaces_license"],
}
aidl_interface {
name: "android.hardware.security.see.storage",
unstable: true,
host_supported: true,
srcs: [
"android/hardware/security/see/storage/*.aidl",
],
backend: {
java: {
enabled: false,
},
cpp: {
enabled: true,
},
ndk: {
enabled: true,
},
rust: {
enabled: true,
},
},
}

27
staging/security/see/storage/aidl/android/hardware/security/see/storage/CreationMode.aidl Normal file
View file

@ -0,0 +1,27 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
enum CreationMode {
/** Returns an error if the file does not already exist. */
NO_CREATE,
/** Creates the file or returns an error if it already exists. */
CREATE_EXCLUSIVE,
/** Creates the file if it does not already exist. */
CREATE,
}

37
staging/security/see/storage/aidl/android/hardware/security/see/storage/DeleteOptions.aidl Normal file
View file

@ -0,0 +1,37 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.ReadIntegrity;
parcelable DeleteOptions {
/**
* Set to acknowledge possible files tampering.
*
* If unacknowledged tampering is detected, the operation will fail with an ERR_FS_*
* service-specific code.
*/
ReadIntegrity readIntegrity = ReadIntegrity.NO_TAMPER;
/**
* Allow writes to succeed while the filesystem is in the middle of an A/B update.
*
* If the A/B update fails, the operation will be rolled back. This rollback will not
* cause subsequent operations fail with any ERR_FS_* code nor will need to be
* acknowledged by setting the `readIntegrity`.
*/
boolean allowWritesDuringAbUpdate = false;
}

25
staging/security/see/storage/aidl/android/hardware/security/see/storage/FileAvailability.aidl Normal file
View file

@ -0,0 +1,25 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
/** Determines how early during the boot process file is able to be accessed. */
enum FileAvailability {
/** Available before userdata is mounted, but after android has booted. */
BEFORE_USERDATA,
/** Available after userdata is mounted. */
AFTER_USERDATA,
}

33
staging/security/see/storage/aidl/android/hardware/security/see/storage/FileIntegrity.aidl Normal file
View file

@ -0,0 +1,33 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
enum FileIntegrity {
/** REE may prevent operations, but cannot alter data once written. */
TAMPER_PROOF_AT_REST,
/**
* REE may alter written data, but changes will be detected and reported as
* an error on read.
*/
TAMPER_DETECT,
/**
* REE may alter written data. Changes other than full filesystem resets will be detected and
* reported.
*/
TAMPER_DETECT_IGNORE_RESET,
}

27
staging/security/see/storage/aidl/android/hardware/security/see/storage/FileMode.aidl Normal file
View file

@ -0,0 +1,27 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
enum FileMode {
/** The file may only be read from. */
READ_ONLY,
/** The file may only be written to. */
WRITE_ONLY,
/** The file may be both read from and written to. */
READ_WRITE,
}

27
staging/security/see/storage/aidl/android/hardware/security/see/storage/FileProperties.aidl Normal file
View file

@ -0,0 +1,27 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.FileAvailability;
import android.hardware.security.see.storage.FileIntegrity;
parcelable FileProperties {
FileIntegrity integrity = FileIntegrity.TAMPER_PROOF_AT_REST;
FileAvailability availability = FileAvailability.BEFORE_USERDATA;
/** Whether the file is reset when user data is wiped. */
boolean persistent;
}

40
staging/security/see/storage/aidl/android/hardware/security/see/storage/IDir.aidl Normal file
View file

@ -0,0 +1,40 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
/** The interface for an open directory */
interface IDir {
/**
* Gets the next batch of filenames in this directory.
*
* Calling multiple times will return different results as the IDir iterates through all the
* files it contains. When all filenames have been returned, all successive calls will return an
* empty list.
*
* @maxCount:
* the maximum number of filenames to return. A @maxCount of 0 signifies no limit on the
* number of filenames returned.
*
* Returns:
* An ordered list of filenames. If @maxCount > 0, the length of the returned list will be
* less than or equal to @maxCount.
*
* May return service-specific errors:
* - ERR_FS_* if the filesystem has been tampered with in a way that the `readIntegrity` the
* dir was opened with does not acknowledge
*/
@utf8InCpp String[] readNextFilenames(int maxCount);
}

95
staging/security/see/storage/aidl/android/hardware/security/see/storage/IFile.aidl Normal file
View file

@ -0,0 +1,95 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.CreationMode;
/** The interface for an open file */
interface IFile {
/**
* Read bytes from this file.
*
* @size:
* the size (in bytes) of the segment to read. If @size is larger than the service's maximum
* read size, the call will return an error (EX_ILLEGAL_ARGUMENT).
* @offset:
* the offset (in bytes) at which to start reading
*
* Return:
* the sequence of bytes at [offset, offset + size) in the file
*
* May return service-specific errors:
* - ERR_FS_* if the filesystem has been tampered with in a way that the `readIntegrity` the
* file was opened with does not acknowledge
*/
byte[] read(long size, long offset);
/**
* Write the bytes in `buffer` to this file.
*
* @offset:
* the offset (in bytes) at which to start writing
*
* Return:
* the number of bytes written successfully
*
* May return service-specific errors:
* - ERR_FS_* if the filesystem has been tampered with in a way that the `readIntegrity` the
* file was opened with does not acknowledge
*/
long write(long offset, in byte[] buffer);
/**
* Reads this file's size.
*
* May return service-specific errors:
* - ERR_FS_* if the filesystem has been tampered with in a way that the `readIntegrity` the
* file was opened with does not acknowledge
*/
long getSize();
/**
* Sets this file's size.
*
* Truncates the file if `new_size` is less than the current size. If `new_size` is greater than
* the current size, the file will be extended with zeroed data.
*
* @newSize:
* the file's new size
*
* May return service-specific errors:
* - ERR_FS_* if the filesystem has been tampered with in a way that the `readIntegrity` the
* file was opened with does not acknowledge
*/
void setSize(long newSize);
/**
* Renames this file.
*
* @destPath:
* the file's new path, relative to filesystem root
* @destCreateMode:
* controls creation behavior of the dest file
*
* May return service-specific errors:
* - ERR_NOT_FOUND if no file exists at @destPath and @destCreateMode is `NO_CREATE`
* - ERR_ALREADY_EXISTS if a file already exists at @destPath and @destCreateMode is
* `CREATE_EXCLUSIVE`
* - ERR_FS_* if the filesystem has been tampered with in a way that the `readIntegrity` the
* file was opened with does not acknowledge
*/
void rename(in @utf8InCpp String destPath, in CreationMode destCreateMode);
}

47
staging/security/see/storage/aidl/android/hardware/security/see/storage/ISecureStorage.aidl Normal file
View file

@ -0,0 +1,47 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.FileProperties;
import android.hardware.security.see.storage.IStorageSession;
/**
* Interface for the Secure Storage HAL
*
* Creates sessions which can be used to access storage.
*/
interface ISecureStorage {
const int ERR_UNSUPPORTED_PROPERTIES = 1;
const int ERR_NOT_FOUND = 2;
const int ERR_ALREADY_EXISTS = 3;
const int ERR_BAD_TRANSACTION = 4;
const int ERR_FS_RESET = 5;
const int ERR_FS_ROLLED_BACK = 6;
const int ERR_FS_TAMPERED = 7;
/**
* Starts a storage session for a filesystem.
*
* @properties:
* the minimum filesystem properties requested for the session.
*
* May return service-specific errors:
* - ERR_UNSUPPORTED_PROPERTIES if no filesystems exist which meet the minimum requested
* requirements
*/
IStorageSession startSession(in FileProperties properties);
}

129
staging/security/see/storage/aidl/android/hardware/security/see/storage/IStorageSession.aidl Normal file
View file

@ -0,0 +1,129 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.DeleteOptions;
import android.hardware.security.see.storage.IDir;
import android.hardware.security.see.storage.IFile;
import android.hardware.security.see.storage.OpenOptions;
import android.hardware.security.see.storage.ReadIntegrity;
import android.hardware.security.see.storage.RenameOptions;
/**
* Interface for a Secure Storage session
*
* When the connection is opened, it will start a transaction and any changes made through this
* session or the interfaces this session returns will be added to this transaction's pending
* changes. Calling `CommitChanges`/`AbandonChanges` will commit/abandon these pending changes, and
* start a new, empty transaction. The interfaces this session returns _remain_ valid across
* transactions; it is not necessary, for example, to reopen a file after a commit.
*
* Any changes still pending when the session is dropped will be abandoned.
*/
interface IStorageSession {
/**
* Commits any pending changes made through this session to storage.
*
* The session will no longer have pending changes after this call returns. Files may then still
* be modified through this session to create another commit.
*
* May return service-specific errors:
* - ERR_BAD_TRANSACTION
*/
void commitChanges();
/**
* Abandons any pending changes made through this session.
*
* The session can then be reused to make new changes.
*/
void abandonChanges();
/**
* Opens a secure file for writing and/or reading.
*
* Changes made to the file are part of the current transaction. Dropping this session
* invalidates the returned `IFile` interface
*
* @filePath:
* path to the file, relative to filesystem root
* @options:
* options controlling opening behavior
*
* May return service-specific errors:
* - ERR_NOT_FOUND
* - ERR_ALREADY_EXISTS
* - ERR_FS_* if the filesystem has been tampered with in a way that @options.readIntegrity
* does not acknowledge
*/
IFile openFile(in @utf8InCpp String filePath, in OpenOptions options);
/**
* Delete a file.
*
* @filePath:
* path to the file, relative to filesystem root
* @options:
* options controlling deletion behavior
*
* May return service-specific errors:
* - ERR_NOT_FOUND
* - ERR_FS_* if the filesystem has been tampered with in a way that @options.readIntegrity
* does not acknowledge
*/
void deleteFile(in @utf8InCpp String filePath, in DeleteOptions options);
/**
* Renames an existing file.
*
* The file must not already be opened. (If it is, use `IFile::rename`.)
*
* @currentPath:
* path to the file, relative to filesystem root
* @destPath:
* the file's new path, relative to filesystem root
* @options:
* options controlling rename behavior
*
* May return service-specific errors:
* - ERR_NOT_FOUND if no file exists at @currentPath, or if @options.destCreateMode is
* `NO_CREATE` and no file exists at @destPath
* - ERR_ALREADY_EXISTS if @options.destCreateMode is `CREATE_EXCLUSIVE` and a file exists at
* @destPath
* - ERR_FS_* if the filesystem has been tampered with in a way that @options.readIntegrity
* does not acknowledge
*/
void renameFile(in @utf8InCpp String currentPath, in @utf8InCpp String destPath,
in RenameOptions options);
/**
* Opens a directory from a filesystem with the given properties.
*
* Dropping this session invalidates the returned `IDir` interface.
*
* @path:
* path to the directory, relative to filesystem root
* @readIntegrity:
* allow opening (and subsequent read/write operations) despite possible tampering for the
* directory
*
* May return service-specific errors:
* - ERR_NOT_FOUND
* - ERR_FS_* if the filesystem has been tampered with in a way that @readIntegrity does not
* acknowledge
*/
IDir openDir(in @utf8InCpp String path, in ReadIntegrity readIntegrity);
}

51
staging/security/see/storage/aidl/android/hardware/security/see/storage/OpenOptions.aidl Normal file
View file

@ -0,0 +1,51 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.CreationMode;
import android.hardware.security.see.storage.FileMode;
import android.hardware.security.see.storage.ReadIntegrity;
parcelable OpenOptions {
/** Controls creation behavior of the to-be-opened file. See `CreationMode` docs for details. */
CreationMode createMode = CreationMode.NO_CREATE;
/** Controls access behavior of the to-be-opened file. See `FileMode` docs for details. */
FileMode accessMode = FileMode.READ_WRITE;
/**
* Set to acknowledge possible files tampering.
*
* If unacknowledged tampering is detected, the operation will fail with an ERR_FS_*
* service-specific code.
*/
ReadIntegrity readIntegrity = ReadIntegrity.NO_TAMPER;
/**
* If this file already exists, discard existing content and open
* it as a new file. No semantic change if the file does not exist.
*/
boolean truncateOnOpen;
/**
* Allow writes to succeed while the filesystem is in the middle of an A/B update.
*
* If the A/B update fails, the operation will be rolled back. This rollback will not
* cause subsequent operations fail with any ERR_FS_* code nor will need to be
* acknowledged by setting the `readIntegrity`.
*/
boolean allowWritesDuringAbUpdate = false;
}

41
staging/security/see/storage/aidl/android/hardware/security/see/storage/ReadIntegrity.aidl Normal file
View file

@ -0,0 +1,41 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
enum ReadIntegrity {
/**
* Return an error on reads if any REE alteration of the written data
* has been detected.
*/
NO_TAMPER,
/**
* Return an error on reads if any REE alteration other than a reset
* has been detected.
*/
IGNORE_RESET,
/**
* Return an error if any REE alteration other than a rollback to a
* valid checkpoint has been detected. (What makes a checkpoint valid is
* implementation defined; an implementation might take a checkpoint on its
* first post-factory boot. A reset is a rollback to the initial state.)
*/
IGNORE_ROLLBACK,
// There's no `IGNORE_ALL` because if REE has done any alteration other
// than a rollback, the file contents will be known-bad data.
}

41
staging/security/see/storage/aidl/android/hardware/security/see/storage/RenameOptions.aidl Normal file
View file

@ -0,0 +1,41 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
import android.hardware.security.see.storage.CreationMode;
import android.hardware.security.see.storage.ReadIntegrity;
parcelable RenameOptions {
/** Controls creation behavior of the dest file. See `CreationMode` docs for details. */
CreationMode destCreateMode = CreationMode.CREATE_EXCLUSIVE;
/**
* Set to acknowledge possible files tampering.
*
* If unacknowledged tampering is detected, the operation will fail with an ERR_FS_*
* service-specific code.
*/
ReadIntegrity readIntegrity = ReadIntegrity.NO_TAMPER;
/**
* Allow writes to succeed while the filesystem is in the middle of an A/B update.
*
* If the A/B update fails, the operation will be rolled back. This rollback will not
* cause subsequent operations fail with any ERR_FS_* code nor will need to be
* acknowledged by setting the `readIntegrity`.
*/
boolean allowWritesDuringAbUpdate = false;
}

28
staging/security/see/storage/aidl/android/hardware/security/see/storage/Tamper.aidl Normal file
View file

@ -0,0 +1,28 @@
/*
* Copyright 2024 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.security.see.storage;
/** Specifies types of REE tampering the filesystem may detect */
enum Tamper {
/** REE has reset this file or the containing file system. */
RESET,
/** REE has rolled back this file or the containing file system to a previous state. */
ROLLBACK,
/** REE has made some other modification to the file. */
OTHER,
}