1<!-- 2 Copyright (C) 2021 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License 15--> 16 17# BlobStore Manager 18 19## Introduction 20* BlobStoreManager is a system service added in Android R release that facilitates sharing of 21 data blobs among apps. 22* Apps that would like to share data blobs with other apps can do so by contributing those 23 data blobs with the System and can choose how they would like the System to share the data blobs 24 with other apps. 25* Apps can access data blobs shared by other apps from the System using checksum of the data blobs 26 (plus some other data attributes. More details [below](#blob-handle)). 27* The APIs provided by the BlobStoreManager are meant to reduce storage and network usage by 28 reusing the data available on the device instead of downloading the same data again and having 29 multiple copies of the same data on disk. 30* It is not meant to provide access to the data which apps otherwise would not be able to access. 31 In other words, if an app’s only means of obtaining access to certain data is through 32 BlobStoreManager, then that use case is not really intended or supported. 33* For example, if earlier an app was downloading certain shared data from a server, then by using 34 BlobStoreManager, it can first check whether or not the data is already available on the device 35 before downloading. 36 37## Concepts 38### Blob handle 39Blob handle is the identifier of the data and it is what apps need to use for referring to the 40data blobs. Currently, this is made of following bits of information: 41* SHA256 checksum of data 42* Data label: A user readable string that indicates what the data blob is. 43 This is meant to be used when surfacing a list of blobs to the user. 44* Data expiry time: A timestamp after which the data blob should be considered invalid and not 45 allowed to be accessed by any app. 46* Data tag: An opaque string associated with the blob. System does not interpret this in any way or 47 use it for any purposes other than when checking whether two Blob handle identifiers are referring 48 to the same data blob. This is meant to be used by the apps, either for categorization for 49 data blobs or for adding additional identifiers. For example, an app can add tags like 50 *machine_learning* or *media* depending on the data blob if necessary. 51 52When comparing two Blob handles, the System will compare all the pieces of information above and 53only when two Blob handles are equal, the data blobs corresponding to those identifiers are 54considered equal. 55 56### Blob sharing session 57Session is a way to allow apps to contribute data over multiple time intervals. Each session is 58associated with a unique Identifier that is created and obtained by the apps by calling 59[BlobStoreManager#createSession](https://developer.android.com/reference/android/app/blob/BlobStoreManager#createSession(android.app.blob.BlobHandle)). 60Apps can save the Identifier associated with a session and use it to open and close it 61multiple times for contributing the data. For example, if an app is downloading 62some content over the network, it can start a Session and start contributing this data to the 63System immediately and if the network connection is lost for any reason, the app can close this 64session. When the download resumes, the app can reopen the session and start contributing again. 65Note that once the entire data is contributed, the app has no reason to hold on to the Session Id. 66 67### Blob commit 68Since a data blob can be contributed in a session over multiple time intervals, an app closing a 69session does not imply that the contribution is completed. So, *commit* is added as an explicit 70event / signal for the app to indicate that the contribution of the data blob is completed. 71At this point, the System can verify the data blob does indeed correspond to the Blob handle used 72by the app and prevent the app from making any further modifications to the data blob. Once the 73data blob is committed and verified by the System, it is available for other applications to access. 74 75### Access modes 76When an application contributes a data blob to the System, it can choose to specify how it would 77like the System to share this data blob with other applications. Access modes refer to the type of 78access that apps specified when contributing a data blob. As of Android S release, there are 79four access modes: 80* Allow specific packages: Apps can specify a specific set of applications that are allowed to 81 access their data blob. 82* Allow packages with the same signature: Apps can specify that only the applications that are 83 signed with the same certificate as them can access their data blob. 84* Allow public access: Apps can specify that any other app on the device can access their data blob. 85* Allow private access: Apps can specify that no other app can access their data blob unless they 86 happen to contribute the same data blob. 87 * Note that in this case, two apps might download the same data blob and contribute to the System 88 in which case we are not saving anything in terms of bandwidth usage, but we would still be 89 saving disk usage since we would be keeping only one copy of data on disk. 90 91### Lease 92Leasing a blob is a way to specify that an application is interested in using a data blob 93and would like the System to not delete this data blob. Applications can also access a blob 94without holding a lease on it, in which case the System can choose to delete the data blob at any 95time. So, if an application wants to make sure a data blob is available for access for a certain 96period, it is recommended that the application acquire a lease on the data blob. Applications can 97either specify upfront how long they would like to hold the lease for (which is called the lease 98expiry time), or they can acquire a lease without specifying a time period and release the lease 99when they are done with the data blob. 100 101## Sharing data blobs across users 102By default, data blobs are only accessible to applications in the user in which the data blob was 103contributed, but if an application holds the permission 104[ACCESS_BLOBS_ACROSS_USERS](https://developer.android.com/reference/android/Manifest.permission#ACCESS_BLOBS_ACROSS_USERS), 105then they are allowed to access blobs that are contributed by the applications in the other users. 106As of Android S, this permission is only available to following set of applications: 107* Apps signed with the platform certificate 108* Privileged applications 109* Applications holding the 110 [ASSISTANT](https://developer.android.com/reference/android/app/role/RoleManager#ROLE_ASSISTANT) 111 role 112* Development applications 113 114Note that the access modes that applications choose while committing the data blobs still apply 115when these data blobs are accessed across users. So for example, if *appA* contributed a 116data blob in *user0* and specified to share this data blob with only a specific set of 117applications [*appB*, *appC*], then *appD* on *user10* will not be able to access this data blob 118even if the app is granted the `ACCESS_BLOBS_ACROSS_USERS` permission. 119 120When apps that are allowed to access blobs across users 121(i.e. those holding the permission `ACCESS_BLOBS_ACROSS_USERS`) try to access a data blob, 122they can do so as if it is any other data blob. In other words, the applications don’t need to 123know where the data blob is contributed, because the System will automatically check and will 124allow access if this data blob is available either on the user in which the calling application 125is running in or other users.