Fix multiple issues with the keystore grant mechanism
1. Ungrant did not check the callers uid which allowed any caller
to remove grants to any key.
2. Grants were not removed when a key was deleted.
3. clean_uid did not clear the grant cache of the target uid.
This would leave state grants that could have been used
by a new app that happend to get the same uid as the one
that was previously uninstalled.
4. Various paths did not respect grants: del, exist, getmtime
The del path was particularly awkward because it is required
by upgradeKeyBlob. This means it must work when a key that needs
upgrading is accessed through a grant alias.
Bug: 65851049
Change-Id: I6709b7562d47ad6156bee88a9e2d961f8a4a797d
diff --git a/keystore/permissions.h b/keystore/permissions.h
index 80d0e04..1f7b7a6 100644
--- a/keystore/permissions.h
+++ b/keystore/permissions.h
@@ -61,4 +61,52 @@
int configure_selinux();
+/*
+ * Keystore grants.
+ *
+ * What are keystore grants?
+ *
+ * Keystore grants are a mechanism that allows an app to grant the permission to use one of its
+ * keys to an other app.
+ *
+ * Liftime of a grant:
+ *
+ * A keystore grant is ephemeral in that is never persistently stored. When the keystore process
+ * exits, all grants are lost. Also, grants can be explicitly revoked by the granter by invoking
+ * the ungrant operation.
+ *
+ * What happens when a grant is created?
+ *
+ * The grant operation expects a valid key alias and the uid of the grantee, i.e., the app that
+ * shall be allowed to use the key denoted by the alias. It then makes an entry in the grant store
+ * which generates a new alias of the form <alias>_KEYSTOREGRANT_<random_grant_no_>. This grant
+ * alias is returned to the caller which can pass the new alias to the grantee. For every grantee,
+ * the grant store keeps a set of grants, an entry of which holds the following information:
+ * - the owner of the key by uid, aka granter uid,
+ * - the original alias of the granted key, and
+ * - the random grant number.
+ * (See "grant_store.h:class Grant")
+ *
+ * What happens when a grant is used?
+ *
+ * Upon any keystore operation that expects an alias, the alias and the caller's uid are used
+ * to retrieve a key file. If that fails some operations try to retrieve a key file indirectly
+ * through a grant. These operations include:
+ * - attestKey
+ * - begin
+ * - exportKey
+ * - get
+ * - getKeyCharacteristics
+ * - del
+ * - exist
+ * - getmtime
+ * Operations that DO NOT follow the grant indirection are:
+ * - import
+ * - generate
+ * - grant
+ * - ungrant
+ * Especially, the latter two mean that neither can a grantee transitively grant a granted key
+ * to a third, nor can they relinquish access to the key or revoke access to the key by a third.
+ */
+
#endif // KEYSTORE_PERMISSIONS_H_