Rewrite the getVmInstanceSecret comment
It seemed to be causing some confusion, so I've attempted to fix that.
Bug: 262415211
Test: n/a
Change-Id: Ia7dd7d3b8cc52e825963ea5b4323dcbefc3d90a9
diff --git a/vm_payload/include/vm_payload.h b/vm_payload/include/vm_payload.h
index e0c2613..5cc2d1e 100644
--- a/vm_payload/include/vm_payload.h
+++ b/vm_payload/include/vm_payload.h
@@ -62,9 +62,23 @@
void* _Nullable param);
/**
- * Get a secret that is uniquely bound to this VM instance. The secrets are
- * 32-byte values and the value associated with an identifier will not change
- * over the lifetime of the VM instance.
+ * Returns all or part of a 32-byte secret that is bound to this unique VM
+ * instance and the supplied identifier. The secret can be used e.g. as an
+ * encryption key.
+ *
+ * Every VM has a secret that is derived from a device-specific value known to
+ * the hypervisor, the code that runs in the VM and its non-modifiable
+ * configuration; it is not made available to the host OS.
+ *
+ * This function performs a further derivation from the VM secret and the
+ * supplied identifier. As long as the VM identity doesn't change the same value
+ * will be returned for the same identifier, even if the VM is stopped &
+ * restarted or the device rebooted.
+ *
+ * If multiple secrets are required for different purposes, a different
+ * identifier should be used for each. The identifiers otherwise are arbitrary
+ * byte sequences and do not need to be kept secret; typically they are
+ * hardcoded in the calling code.
*
* \param identifier identifier of the secret to return.
* \param identifier_size size of the secret identifier.