The {@link #run} method actually starts up the VM and allows the payload code to execute. It * will continue until it exits or {@link #stop} is called. Updates on the state of the VM can be * received using {@link #setCallback}. The app can communicate with the VM using {@link * #connectToVsockServer} or {@link #connectVsock}. * *
The payload code running inside the VM has access to a set of native APIs; see the README * file for details. * *
Each VM has a unique secret, computed from the APK that contains the code running in it, the
* VM configuration, and a random per-instance salt. The secret can be accessed by the payload code
* running inside the VM (using {@code AVmPayload_getVmInstanceSecret}) but is not made available
* outside it.
*
* @hide
*/
@SystemApi
public class VirtualMachine implements AutoCloseable {
/** The permission needed to create or run a virtual machine. */
public static final String MANAGE_VIRTUAL_MACHINE_PERMISSION =
"android.permission.MANAGE_VIRTUAL_MACHINE";
/**
* The permission needed to create a virtual machine with more advanced configuration options.
*/
public static final String USE_CUSTOM_VIRTUAL_MACHINE_PERMISSION =
"android.permission.USE_CUSTOM_VIRTUAL_MACHINE";
/**
* The lowest port number that can be used to communicate with the virtual machine payload.
*
* @see #connectToVsockServer
* @see #connectVsock
*/
@SuppressLint("MinMaxConstant") // Won't change: see man 7 vsock.
public static final long MIN_VSOCK_PORT = 1024;
/**
* The highest port number that can be used to communicate with the virtual machine payload.
*
* @see #connectToVsockServer
* @see #connectVsock
*/
@SuppressLint("MinMaxConstant") // Won't change: see man 7 vsock.
public static final long MAX_VSOCK_PORT = (1L << 32) - 1;
private ParcelFileDescriptor mTouchSock;
private ParcelFileDescriptor mKeySock;
private ParcelFileDescriptor mMouseSock;
private ParcelFileDescriptor mSwitchesSock;
private ParcelFileDescriptor mTrackpadSock;
private enum InputEventType {
TOUCH,
MOUSE,
TRACKPAD
}
private BlockingQueue Is only set iff encrypted store is enabled in the {@link
* VirtualMachineConfig#ENCRYPTED_STORE_MODE_KEK_ON_CE} mode.
*/
@Nullable private final EncryptedStoreKEK mEncryptedStoreKEK;
/** File that contains the Id. This is NULL iff FEATURE_LLPVM is disabled */
@Nullable private final File mInstanceIdPath;
/**
* Unmodifiable list of extra apks. Apks are specified by the vm config, and corresponding
* idsigs are to be generated.
*/
@NonNull private final List The new virtual machine will be in the same state as the descriptor indicates.
*
* Once a virtual machine is imported it is persisted until it is deleted by calling {@link
* #delete}. The imported virtual machine is in {@link #STATUS_STOPPED} state. To run the VM,
* call {@link #run}.
*/
@GuardedBy("VirtualMachineManager.sCreateLock")
@NonNull
static VirtualMachine fromDescriptor(
@NonNull Context context,
@NonNull String name,
@NonNull VirtualMachineDescriptor vmDescriptor)
throws VirtualMachineException {
File vmDir = createVmDir(context, name);
try {
VirtualMachine vm;
try (vmDescriptor) {
VirtualMachineConfig config = VirtualMachineConfig.from(vmDescriptor.getConfigFd());
VirtualizationService service = VirtualizationService.getInstance();
vm = new VirtualMachine(context, name, config, service);
config.serialize(vm.mConfigFilePath);
try {
vm.mInstanceFilePath.createNewFile();
} catch (IOException e) {
throw new VirtualMachineException("failed to create instance image", e);
}
vm.importInstanceFrom(vmDescriptor.getInstanceImgFd());
// TODO(b/406258175): handle the encrypted store KEK for VM transfer.
if (vmDescriptor.getEncryptedStoreFd() != null) {
try {
vm.mEncryptedStoreFilePath.createNewFile();
} catch (IOException e) {
throw new VirtualMachineException(
"failed to create encrypted storage image", e);
}
vm.importEncryptedStoreFrom(vmDescriptor.getEncryptedStoreFd());
}
if (vm.mInstanceIdPath != null) {
vm.importInstanceIdFrom(vmDescriptor.getInstanceIdFd());
vm.claimInstance(service);
}
}
return vm;
} catch (VirtualMachineException | RuntimeException e) {
// If anything goes wrong, delete any files created so far and the VM's directory
try {
deleteRecursively(vmDir);
} catch (Exception innerException) {
e.addSuppressed(innerException);
}
throw e;
}
}
/**
* Creates a virtual machine with the given name and config. Once a virtual machine is created
* it is persisted until it is deleted by calling {@link #delete}. The created virtual machine
* is in {@link #STATUS_STOPPED} state. To run the VM, call {@link #run}.
*/
@GuardedBy("VirtualMachineManager.sCreateLock")
@NonNull
static VirtualMachine create(
@NonNull Context context, @NonNull String name, @NonNull VirtualMachineConfig config)
throws VirtualMachineException {
File vmDir = createVmDir(context, name);
try {
VirtualizationService virtualizationService = VirtualizationService.getInstance();
VirtualMachine vm = new VirtualMachine(context, name, config, virtualizationService);
try {
vm.mInstanceFilePath.createNewFile();
} catch (IOException e) {
throw new VirtualMachineException("failed to create instance image", e);
}
if (config.isEncryptedStorageEnabled()) {
try {
vm.mEncryptedStoreFilePath.createNewFile();
} catch (IOException e) {
throw new VirtualMachineException(
"failed to create encrypted storage image", e);
}
}
IVirtualizationService service = virtualizationService.getBinder();
if (vm.mInstanceIdPath != null) {
try (FileOutputStream stream = new FileOutputStream(vm.mInstanceIdPath)) {
byte[] id = service.allocateInstanceId();
stream.write(id);
} catch (FileNotFoundException e) {
throw new VirtualMachineException("instance_id file missing", e);
} catch (IOException e) {
throw new VirtualMachineException("failed to persist instance_id", e);
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException | IllegalArgumentException e) {
throw new VirtualMachineException("failed to create instance_id", e);
}
}
try (ParcelFileDescriptor fd =
ParcelFileDescriptor.open(vm.mInstanceFilePath, MODE_READ_WRITE)) {
service.initializeWritablePartition(
fd, INSTANCE_FILE_SIZE, PartitionType.ANDROID_VM_INSTANCE);
} catch (FileNotFoundException e) {
throw new VirtualMachineException("instance image missing", e);
} catch (IOException e) {
throw new VirtualMachineException("failed to initialize instance partition", e);
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException | IllegalArgumentException e) {
throw new VirtualMachineException("failed to create instance partition", e);
}
if (config.isEncryptedStorageEnabled()) {
try (ParcelFileDescriptor fd =
ParcelFileDescriptor.open(vm.mEncryptedStoreFilePath, MODE_READ_WRITE)) {
service.initializeWritablePartition(
fd, config.getEncryptedStorageBytes(), PartitionType.ENCRYPTEDSTORE);
} catch (FileNotFoundException e) {
throw new VirtualMachineException("encrypted storage image missing", e);
} catch (IOException e) {
throw new VirtualMachineException(
"failed to initialize encrypted store partition", e);
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException | IllegalArgumentException e) {
throw new VirtualMachineException(
"failed to create encrypted storage partition", e);
}
}
// persist the config only after we pass all the checks above.
config.serialize(vm.mConfigFilePath);
return vm;
} catch (VirtualMachineException | RuntimeException e) {
// If anything goes wrong, delete any files created so far and the VM's directory
try {
vmInstanceCleanup(context, name);
} catch (Exception innerException) {
e.addSuppressed(innerException);
}
throw e;
}
}
/** Loads a virtual machine that is already created before. */
@GuardedBy("VirtualMachineManager.sCreateLock")
@Nullable
static VirtualMachine load(@NonNull Context context, @NonNull String name)
throws VirtualMachineException {
File thisVmDir = getVmDir(context, name);
if (!thisVmDir.exists()) {
// The VM doesn't exist.
return null;
}
File configFilePath = new File(thisVmDir, CONFIG_FILE);
VirtualMachineConfig config = VirtualMachineConfig.from(configFilePath);
VirtualMachine vm =
new VirtualMachine(context, name, config, VirtualizationService.getInstance());
if (vm.mInstanceIdPath != null && !vm.mInstanceIdPath.exists()) {
throw new VirtualMachineException("instance_id file missing");
}
if (!vm.mInstanceFilePath.exists()) {
throw new VirtualMachineException("instance image missing");
}
if (config.isEncryptedStorageEnabled() && !vm.mEncryptedStoreFilePath.exists()) {
throw new VirtualMachineException("Storage image missing");
}
// TODO(b/406258175): here we need to detect if migration is required.
return vm;
}
@GuardedBy("VirtualMachineManager.sCreateLock")
void delete(Context context, String name) throws VirtualMachineException {
synchronized (mLock) {
checkStopped();
// Once we explicitly delete a VM it must remain permanently in the deleted state;
// if a new VM is created with the same name (and files) that's unrelated.
mWasDeleted = true;
}
vmInstanceCleanup(context, name);
}
// Delete the full VM directory and notify VirtualizationService to remove this
// VM instance for housekeeping.
@GuardedBy("VirtualMachineManager.sCreateLock")
static void vmInstanceCleanup(Context context, String name) throws VirtualMachineException {
File vmDir = getVmDir(context, name);
File ceVmDir = getVmDir(context.createCredentialProtectedStorageContext(), name);
notifyInstanceRemoval(vmDir, VirtualizationService.getInstance());
try {
deleteRecursively(vmDir);
if (ceVmDir.exists() && !vmDir.getCanonicalPath().equals(ceVmDir.getCanonicalPath())) {
deleteRecursively(ceVmDir);
}
} catch (IOException e) {
throw new VirtualMachineException(e);
}
}
private static void notifyInstanceRemoval(
File vmDirectory, @NonNull VirtualizationService service) {
File instanceIdFile = new File(vmDirectory, INSTANCE_ID_FILE);
try {
byte[] instanceId = Files.readAllBytes(instanceIdFile.toPath());
service.getBinder().removeVmInstance(instanceId);
} catch (Exception e) {
// Deliberately ignoring error in removing VM instance. This potentially leads to
// unaccounted instances in the VS' database. But, nothing much can be done by caller.
Log.w(TAG, "Failed to notify VS to remove the VM instance", e);
}
}
// Claim the instance. This notifies the global VS about the ownership of this
// instance_id for housekeeping purpose.
void claimInstance(@NonNull VirtualizationService service) throws VirtualMachineException {
if (mInstanceIdPath != null) {
try {
byte[] instanceId = Files.readAllBytes(mInstanceIdPath.toPath());
service.getBinder().claimVmInstance(instanceId);
} catch (IOException e) {
throw new VirtualMachineException("failed to read instance_id", e);
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
}
}
}
@GuardedBy("VirtualMachineManager.sCreateLock")
@NonNull
private static File createVmDir(@NonNull Context context, @NonNull String name)
throws VirtualMachineException {
File vmDir = getVmDir(context, name);
try {
// We don't need to undo this even if VM creation fails.
Files.createDirectories(vmDir.getParentFile().toPath());
// The checking of the existence of this directory and the creation of it is done
// atomically. If the directory already exists (i.e. the VM with the same name was
// already created), FileAlreadyExistsException is thrown.
Files.createDirectory(vmDir.toPath());
} catch (FileAlreadyExistsException e) {
throw new VirtualMachineException(
"virtual machine already exists",
e,
VirtualMachineException.CODE_NAME_ALREADY_EXISTS);
} catch (IOException e) {
throw new VirtualMachineException("failed to create directory for VM", e);
}
return vmDir;
}
@NonNull
private static File getVmDir(@NonNull Context context, @NonNull String name) {
if (name.contains(File.separator) || name.equals(".") || name.equals("..")) {
throw new IllegalArgumentException("Invalid VM name: " + name);
}
File vmRoot = new File(context.getDataDir(), VM_DIR);
return new File(vmRoot, name);
}
/**
* Returns the name of this virtual machine. The name is unique in the package and can't be
* changed.
*
* @hide
*/
@SystemApi
@NonNull
public String getName() {
return mName;
}
/**
* Returns the currently selected config of this virtual machine. There can be multiple virtual
* machines sharing the same config. Even in that case, the virtual machines are completely
* isolated from each other; they have different secrets. It is also possible that a virtual
* machine can change its config, which can be done by calling {@link #setConfig}.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public VirtualMachineConfig getConfig() {
synchronized (mLock) {
return mConfig;
}
}
/**
* Returns the current status of this virtual machine.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @hide
*/
@SystemApi
@WorkerThread
@Status
public int getStatus() {
IVirtualMachine virtualMachine;
synchronized (mLock) {
if (mWasDeleted) {
return STATUS_DELETED;
}
virtualMachine = mVirtualMachine;
}
int status;
if (virtualMachine == null) {
status = STATUS_STOPPED;
} else {
try {
status = stateToStatus(virtualMachine.getState());
} catch (RemoteException e) {
status = STATUS_STOPPED;
}
}
if (status == STATUS_STOPPED && !mVmRootPath.exists()) {
// A VM can quite happily keep running if its backing files have been deleted.
// But once it stops, it's gone forever.
synchronized (mLock) {
mWasDeleted = true;
}
return STATUS_DELETED;
}
return status;
}
private int stateToStatus(@VirtualMachineState int state) {
switch (state) {
case VirtualMachineState.STARTING:
case VirtualMachineState.STARTED:
case VirtualMachineState.READY:
case VirtualMachineState.FINISHED:
return STATUS_RUNNING;
case VirtualMachineState.NOT_STARTED:
case VirtualMachineState.DEAD:
default:
return STATUS_STOPPED;
}
}
// Throw an appropriate exception if we have a running VM, or the VM has been deleted.
@GuardedBy("mLock")
private void checkStopped() throws VirtualMachineException {
switch (getStatus()) {
case STATUS_STOPPED:
// no-op
return;
case STATUS_RUNNING:
throw new VirtualMachineException(
"VM is not in stopped state",
VirtualMachineException.CODE_VIRTUAL_MACHINE_RUNNING);
case STATUS_DELETED:
throw new VirtualMachineException(
"VM has been deleted",
VirtualMachineException.CODE_VIRTUAL_MACHINE_DELETED);
}
}
private void handleStopped(int cid, @VirtualMachineCallback.StopReason int reason) {
synchronized (mLock) {
// Since we just took the lock, we can't assume the stopped
// notification is for the current VM.
if (mCid == cid) {
if (mStopHandled) {
return;
}
mStopHandled = true;
dropVm();
}
}
executeCallback((cb) -> cb.onStopped(VirtualMachine.this, reason));
}
/**
* This should only be called when we know our VM has stopped; we no longer need to hold a
* reference to it (this allows resources to be GC'd) and we no longer need to be informed of
* memory pressure.
*/
@GuardedBy("mLock")
private void dropVm() {
if (mInputEventExecutor != null) {
mInputEventExecutor.shutdownNow();
mInputEventExecutor = null;
}
if (mMemoryManagementCallbacks != null) {
mContext.unregisterComponentCallbacks(mMemoryManagementCallbacks);
}
if (mVirtualMachine != null) {
try {
mVirtualMachine.asBinder().unlinkToDeath(mVMDeathRecipient, /* flags= */ 0);
} catch (RuntimeException e) {
Log.w(TAG, "Ignore exception unlinkToDeath() for IVirtualMachine, exception=" + e);
}
mVirtualMachine = null;
mCid = -1;
}
if (mVirtualizationService != null) {
try {
mVirtualizationService
.getBinder()
.asBinder()
.unlinkToDeath(mVSDeathRecipient, /* flags= */ 0);
} catch (RuntimeException e) {
Log.w(
TAG,
"Ignore exception unlinkToDeath() for IVirtualizationService, exception="
+ e);
}
mVirtualizationService = null;
}
}
/** If we have an IVirtualMachine in the running state return it, otherwise throw. */
@GuardedBy("mLock")
private IVirtualMachine getRunningVm() throws VirtualMachineException {
switch (getStatus()) {
case STATUS_STOPPED:
throw new VirtualMachineException(
"VM is not in running state",
VirtualMachineException.CODE_VIRTUAL_MACHINE_STOPPED);
case STATUS_RUNNING:
return mVirtualMachine;
case STATUS_DELETED:
throw new VirtualMachineException(
"VM has been deleted",
VirtualMachineException.CODE_VIRTUAL_MACHINE_DELETED);
default:
// unreachable code. Just make compiler happy.
return null;
}
}
/**
* Registers the callback object to get events from the virtual machine. If a callback was
* already registered, it is replaced with the new one.
*
* @hide
*/
@SystemApi
public void setCallback(
@NonNull @CallbackExecutor Executor executor,
@NonNull VirtualMachineCallback callback) {
synchronized (mCallbackLock) {
mCallback = callback;
mCallbackExecutor = executor;
}
}
/**
* Clears the currently registered callback.
*
* @hide
*/
@SystemApi
public void clearCallback() {
synchronized (mCallbackLock) {
mCallback = null;
mCallbackExecutor = null;
}
}
/** Executes a callback on the callback executor. */
private void executeCallback(Consumer NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if the virtual machine is not stopped or could not be
* started.
* @hide
*/
@SystemApi
@WorkerThread
@RequiresPermission(MANAGE_VIRTUAL_MACHINE_PERMISSION)
public void run() throws VirtualMachineException {
synchronized (mLock) {
checkStopped();
mVirtualizationService = VirtualizationService.getInstance();
mStopHandled = false;
try {
mIdsigFilePath.createNewFile();
for (ApkSpec extraApk : mExtraApks) {
extraApk.idsig.createNewFile();
}
for (ApkSpec tenantApk : mTenantApks) {
tenantApk.idsig.createNewFile();
}
} catch (IOException e) {
// If the file already exists, exception is not thrown.
throw new VirtualMachineException("Failed to create APK signature file", e);
}
IVirtualizationService service = mVirtualizationService.getBinder();
try {
if (mConnectVmConsole) {
createPtyConsole();
}
if (mVmOutputCaptured) {
createVmOutputPipes();
}
if (mVmConsoleInputSupported) {
createVmInputPipes();
}
ParcelFileDescriptor consoleOutFd = null;
if (mConnectVmConsole && mVmOutputCaptured) {
// If we are enabling output pipes AND the host console, then we tee the console
// output to both.
ParcelFileDescriptor[] pipe = ParcelFileDescriptor.createPipe();
mTeeConsoleOutReader = pipe[0];
mTeeConsoleOutWriter = pipe[1];
consoleOutFd = mTeeConsoleOutWriter;
TeeWorker tee =
new TeeWorker(
mName + " console",
new FileInputStream(mTeeConsoleOutReader.getFileDescriptor()),
List.of(
new FileOutputStream(mPtyFd.getFileDescriptor()),
new FileOutputStream(
mConsoleOutWriter.getFileDescriptor())));
// If the VM is stopped then the tee worker thread would get an EOF or read()
// error which would tear down itself.
mConsoleExecutor.execute(tee);
} else if (mConnectVmConsole) {
consoleOutFd = mPtyFd;
} else if (mVmOutputCaptured) {
consoleOutFd = mConsoleOutWriter;
}
mInputEventExecutor = Executors.newSingleThreadExecutor();
mInputEventExecutor.execute(
() -> {
while (true) {
try {
Pair If you turn on output capture, you must consume data from {@code getConsoleOutput} -
* because otherwise the code in the VM may get blocked when the pipe buffer fills up.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if the stream could not be created, or capturing is turned
* off.
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public InputStream getConsoleOutput() throws VirtualMachineException {
if (!mVmOutputCaptured) {
throw new VirtualMachineException(
"Capturing vm outputs is turned off",
VirtualMachineException.CODE_FEATURE_DISABLED);
}
synchronized (mLock) {
createVmOutputPipes();
return new FileInputStream(mConsoleOutReader.getFileDescriptor());
}
}
/**
* Returns the stream object representing the console input to the virtual machine. The console
* input is only available if the {@link VirtualMachineConfig} specifies that it should be
* {@linkplain VirtualMachineConfig#isVmConsoleInputSupported supported}.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if the stream could not be created, or console input is not
* supported.
* @hide
*/
@TestApi
@WorkerThread
@NonNull
public OutputStream getConsoleInput() throws VirtualMachineException {
if (!mVmConsoleInputSupported) {
throw new VirtualMachineException(
"VM console input is not supported",
VirtualMachineException.CODE_FEATURE_DISABLED);
}
synchronized (mLock) {
createVmInputPipes();
return new FileOutputStream(mConsoleInWriter.getFileDescriptor());
}
}
/**
* Returns the stream object representing the log output from the virtual machine. The log
* output is only available if the VirtualMachineConfig specifies that it should be {@linkplain
* VirtualMachineConfig#isVmOutputCaptured captured}.
*
* If you turn on output capture, you must consume data from {@code getLogOutput} - because
* otherwise the code in the VM may get blocked when the pipe buffer fills up.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if the stream could not be created, or capturing is turned
* off.
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public InputStream getLogOutput() throws VirtualMachineException {
if (!mVmOutputCaptured) {
throw new VirtualMachineException(
"Capturing vm outputs is turned off",
VirtualMachineException.CODE_FEATURE_DISABLED);
}
synchronized (mLock) {
createVmOutputPipes();
return new FileInputStream(mLogReader.getFileDescriptor());
}
}
/**
* Stops this virtual machine. Stopping a virtual machine is like pulling the plug on a real
* computer; the machine halts immediately. Software running on the virtual machine is not
* notified of the event. Writes to {@linkplain
* VirtualMachineConfig.Builder#setEncryptedStorageBytes encrypted storage} might not be
* persisted, and the instance might be left in an inconsistent state.
*
* For a graceful shutdown, you could request the payload to call {@code exit()}, e.g. via a
* {@linkplain #connectToVsockServer binder request}, and wait for {@link
* VirtualMachineCallback#onPayloadFinished} to be called.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if the virtual machine is not running or could not be
* stopped.
* @hide
*/
@SystemApi
@WorkerThread
public void stop() throws VirtualMachineException {
synchronized (mLock) {
if (getStatus() == STATUS_RUNNING) {
try {
mVirtualMachine.stop();
dropVm();
return;
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException e) {
throw new VirtualMachineException(e);
}
}
}
throw new VirtualMachineException(
"VM is not running", VirtualMachineException.CODE_VIRTUAL_MACHINE_STOPPED);
}
/** @hide */
public void suspend() throws VirtualMachineException {
synchronized (mLock) {
if (mVirtualMachine == null) {
throw new VirtualMachineException(
"VM is not running", VirtualMachineException.CODE_VIRTUAL_MACHINE_STOPPED);
}
try {
mVirtualMachine.suspend();
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException e) {
throw new VirtualMachineException(e);
}
}
}
/** @hide */
public void resume() throws VirtualMachineException {
synchronized (mLock) {
if (mVirtualMachine == null) {
throw new VirtualMachineException(
"VM is not running", VirtualMachineException.CODE_VIRTUAL_MACHINE_STOPPED);
}
try {
mVirtualMachine.resume();
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException e) {
throw new VirtualMachineException(e);
}
}
}
/**
* Stops this virtual machine, if it is running.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @see #stop()
* @hide
*/
@SystemApi
@WorkerThread
@Override
public void close() {
try {
stop();
mVirtualizationService
.getBinder()
.asBinder()
.unlinkToDeath(mVSDeathRecipient, /* flags= */ 0);
} catch (Exception e) {
// Deliberately ignored; this almost certainly means the VM exited just as
// we tried to stop it.
Log.i(TAG, "Ignoring error on close()", e);
}
}
private static void deleteRecursively(File dir) throws IOException {
// Note: This doesn't follow symlinks, which is important. Instead they are just deleted
// (and Files.delete deletes the link not the target).
Files.walkFileTree(
dir.toPath(),
new SimpleFileVisitor<>() {
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
throws IOException {
Files.delete(file);
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult postVisitDirectory(Path dir, IOException e)
throws IOException {
// Directory is deleted after we've visited (deleted) all its contents, so
// it
// should be empty by now.
Files.delete(dir);
return FileVisitResult.CONTINUE;
}
});
}
/**
* Changes the config of this virtual machine to a new one. This can be used to adjust things
* like the number of CPU and size of the RAM, depending on the situation (e.g. the size of the
* application to run on the virtual machine, etc.)
*
* The new config must be {@linkplain VirtualMachineConfig#isCompatibleWith compatible with}
* the existing config.
*
* NOTE: Modification of the encrypted storage size is restricted to expansion only and is an
* irreversible operation.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @return the old config
* @throws VirtualMachineException if the virtual machine is not stopped, or the new config is
* incompatible.
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public VirtualMachineConfig setConfig(@NonNull VirtualMachineConfig newConfig)
throws VirtualMachineException {
synchronized (mLock) {
VirtualMachineConfig oldConfig = mConfig;
if (!oldConfig.isCompatibleWith(newConfig)
|| oldConfig.getEncryptedStorageBytes()
> newConfig.getEncryptedStorageBytes()) {
throw new VirtualMachineException(
"incompatible config", VirtualMachineException.CODE_CONFIG_INCOMPATIBLE);
}
checkStopped();
if (oldConfig != newConfig) {
// Note that VirtualMachineConfig.serialize replaces the old config atomically.
// This ensures that errors while writing the new config won't leave the config on
// disk in a broken state and also that any VirtualMachineDescriptor that refers to
// the old file does not see the new config.
newConfig.serialize(mConfigFilePath);
mConfig = newConfig;
}
return oldConfig;
}
}
/**
* Abstracts away the task of creating a vsock connection. Normally, in the same process, you'll
* make the connection and then promote it to a binder as part of the same API call, but if you
* want to pass a connection to another process first, before establishing the RPC binder
* connection, you may implement this method by getting a vsock connection from another process.
*
* It is recommended to convert other types of exceptions (e.g. remote exceptions) to
* VirtualMachineException, so that all connection failures will be visible under the same type
* of exception.
*
* @hide
*/
@SystemApi
@SuppressLint("UnflaggedApi") // already existing functionality exposed, users should flag
public interface VsockConnectionProvider {
/**
* Returns a connection, either from {@link #connectVsock} or from
* the VM owner which would call {@link #connectVsock} on your behalf.
*
* Each call should return a new connection.
*/
@NonNull
@SuppressLint("UnflaggedApi") // already existing functionality exposed, users should flag
public ParcelFileDescriptor addConnection() throws VirtualMachineException;
}
/**
* Class to make it easy to use JNI, without needing PFD and other classes.
*
* @hide
*/
private static class NativeProviderWrapper {
private VsockConnectionProvider mProvider = null;
// ensures last FD is owned until get is called again
private ParcelFileDescriptor mMoreLifetime = null;
public NativeProviderWrapper(VsockConnectionProvider provider) {
mProvider = provider;
}
int connect() throws VirtualMachineException {
mMoreLifetime = mProvider.addConnection();
return mMoreLifetime.getFileDescriptor().getInt$();
}
}
/**
* Connect to a VM's binder service via vsock and return the root IBinder object. Guest VMs are
* expected to set up vsock servers in their payload. After the host app receives the {@link
* VirtualMachineCallback#onPayloadReady}, it can use this method to establish a connection to
* the guest VM.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if the virtual machine is not running or the connection
* failed.
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public IBinder connectToVsockServer(
@IntRange(from = MIN_VSOCK_PORT, to = MAX_VSOCK_PORT) long port)
throws VirtualMachineException {
VsockConnectionProvider provider =
new VsockConnectionProvider() {
@Override
public ParcelFileDescriptor addConnection() throws VirtualMachineException {
return connectVsock(port);
}
};
return binderFromPreconnectedClient(provider);
}
@Nullable
private static native IBinder nativeBinderFromPreconnectedClient(
NativeProviderWrapper provider);
/**
* Convert existing vsock connection to a binder connection.
*
* See {@linkplain #connectToVsockServer} for details. This method allows
* you to create the connects independently from upgrading them to the
* binder connection. Specifically:
*
* connectToVsockServer = connectToVsock + binderFromPreconnectedClient
*
* This method is useful if you want to pass the vsock connection to
* another process before establishing the RPC binder connection, so that
* you can create a direct connection.
*
* @args
* provider: a provider that provides the vsock connection. This
* provider should return connections from
* {@link #connectVsock}, from the VM owner.
*
* @hide
*/
@SystemApi
@SuppressLint("UnflaggedApi") // already existing functionality exposed, users should flag
@WorkerThread
@NonNull
public static IBinder binderFromPreconnectedClient(@NonNull VsockConnectionProvider provider)
throws VirtualMachineException {
IBinder binder = nativeBinderFromPreconnectedClient(new NativeProviderWrapper(provider));
if (binder == null) {
throw new VirtualMachineException("Failed to connect to vsock server");
}
// b/420703082
// We don't allow 3P apps to host RPC Binder services. Additionally,
// our clients are updatable, so they can't allow blocking calls.
// Allow it here, to avoid all the spam/logs from these services.
// If we ever allow 3P apps to host these services, we should have
// a higher-level API that does not set this.
Binder.allowBlocking(binder);
return binder;
}
/**
* Opens a vsock connection to the VM on the given port.
*
* The caller is responsible for closing the returned {@code ParcelFileDescriptor}.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @throws VirtualMachineException if connecting fails.
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public ParcelFileDescriptor connectVsock(
@IntRange(from = MIN_VSOCK_PORT, to = MAX_VSOCK_PORT) long port)
throws VirtualMachineException {
synchronized (mLock) {
try {
return getRunningVm().connectVsock(validatePort(port));
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
} catch (ServiceSpecificException e) {
throw new VirtualMachineException(e);
}
}
}
private int validatePort(long port) {
// Ports below 1024 are "privileged" (payload code can't bind to these), and port numbers
// are 32-bit unsigned numbers at the OS level, even though we pass them as 32-bit signed
// numbers internally.
if (port < MIN_VSOCK_PORT || port > MAX_VSOCK_PORT) {
throw new IllegalArgumentException("Bad port " + port);
}
return (int) port;
}
/**
* Returns the root directory where all files related to this {@link VirtualMachine} (e.g.
* {@code instance.img}, {@code apk.idsig}, etc) are stored.
*
* @hide
*/
@TestApi
@NonNull
public File getRootDir() {
return mVmRootPath;
}
/**
* Enables the VM to request attestation in testing mode.
*
* This function provisions a key pair for the VM attestation testing, a fake certificate
* will be associated to the fake key pair when the VM requests attestation in testing mode.
*
* The provisioned key pair can only be used in subsequent calls to {@link
* AVmPayload_requestAttestationForTesting} within a running VM.
*
* @hide
*/
// TODO: Make this static API.
@TestApi
@RequiresPermission(USE_CUSTOM_VIRTUAL_MACHINE_PERMISSION)
public void enableTestAttestation() throws VirtualMachineException {
try {
VirtualizationService.getInstance().getBinder().enableTestAttestation();
} catch (RemoteException e) {
throw e.rethrowAsRuntimeException();
}
}
/**
* Captures the current state of the VM in a {@link VirtualMachineDescriptor} instance. The VM
* needs to be stopped to avoid inconsistency in its state representation.
*
* The state of the VM is not actually copied until {@link
* VirtualMachineManager#importFromDescriptor} is called. It is recommended that the VM not be
* started until that operation is complete.
*
* NOTE: This method may block and should not be called on the main thread.
*
* @return a {@link VirtualMachineDescriptor} instance that represents the VM's state.
* @throws VirtualMachineException if the virtual machine is not stopped, or the state could not
* be captured.
* @hide
*/
@SystemApi
@WorkerThread
@NonNull
public VirtualMachineDescriptor toDescriptor() throws VirtualMachineException {
synchronized (mLock) {
checkStopped();
try {
return new VirtualMachineDescriptor(
ParcelFileDescriptor.open(mConfigFilePath, MODE_READ_ONLY),
mInstanceIdPath != null
? ParcelFileDescriptor.open(mInstanceIdPath, MODE_READ_ONLY)
: null,
ParcelFileDescriptor.open(mInstanceFilePath, MODE_READ_ONLY),
mEncryptedStoreFilePath != null
? ParcelFileDescriptor.open(mEncryptedStoreFilePath, MODE_READ_ONLY)
: null);
} catch (IOException e) {
throw new VirtualMachineException(e);
}
}
}
@Override
public String toString() {
VirtualMachineConfig config = getConfig();
String payloadConfigPath = config.getPayloadConfigPath();
String payloadBinaryName = config.getPayloadBinaryName();
StringBuilder result = new StringBuilder();
result.append("VirtualMachine(").append("name:").append(getName()).append(", ");
if (payloadBinaryName != null) {
result.append("payload:").append(payloadBinaryName).append(", ");
}
if (payloadConfigPath != null) {
result.append("config:").append(payloadConfigPath).append(", ");
}
result.append("package: ").append(mPackageName).append(")");
return result.toString();
}
/**
* Reads the payload config inside the application, parses extra APK information, and then
* creates corresponding idsig file paths.
*/
private static List { "extra_apks": [ { "path": "/system/app/foo.apk", }, ... ], ... }
*/
try {
List Supports non-blocking writes to the output streams by ignoring EAGAIN error.
*/
private static class TeeWorker implements Runnable {
private final String mName;
private final InputStream mIn;
private final List