summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorandroid-build-team Robot2018-05-24 02:22:13 -0500
committerandroid-build-team Robot2018-05-24 02:22:13 -0500
commit19131e0f82af2ed99c3eb34d6cb3c52e3dac9393 (patch)
tree69d85c62937985b05bf990533c172249b19d5081
parente4db4f546c3453e741d688311ce60ee3f55f7fe3 (diff)
parent1f74538cdb297a0a2ecd4ac1cc40214e83edb11f (diff)
downloadplatform-hardware-interfaces-19131e0f82af2ed99c3eb34d6cb3c52e3dac9393.tar.gz
platform-hardware-interfaces-19131e0f82af2ed99c3eb34d6cb3c52e3dac9393.tar.xz
platform-hardware-interfaces-19131e0f82af2ed99c3eb34d6cb3c52e3dac9393.zip
Snap for 4801384 from 1f74538cdb297a0a2ecd4ac1cc40214e83edb11f to pi-release
Change-Id: I3f3ccc80230a48a51f2e1045779df3eee06b3679
-rw-r--r--CleanSpec.mk2
-rw-r--r--broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp41
-rw-r--r--broadcastradio/common/tests/IdentifierIterator_test.cpp35
-rw-r--r--broadcastradio/common/utils2x/Utils.cpp20
-rw-r--r--broadcastradio/common/utils2x/include/broadcastradio-utils-2x/Utils.h10
-rw-r--r--camera/common/1.0/default/CameraModule.cpp2
-rw-r--r--camera/device/3.2/default/CameraDeviceSession.cpp81
-rw-r--r--camera/device/3.2/default/CameraDeviceSession.h13
-rw-r--r--camera/device/3.4/default/CameraDeviceSession.cpp47
-rw-r--r--compatibility_matrices/Android.mk2
-rw-r--r--compatibility_matrices/compatibility_matrix.3.xml2
-rw-r--r--configstore/1.0/default/android.hardware.configstore@1.0-service.rc4
-rw-r--r--configstore/1.1/Android.bp23
-rw-r--r--configstore/1.1/ISurfaceFlingerConfigs.hal28
-rw-r--r--configstore/1.1/default/Android.mk (renamed from configstore/1.0/default/Android.mk)13
-rw-r--r--configstore/1.1/default/SurfaceFlingerConfigs.cpp (renamed from configstore/1.0/default/SurfaceFlingerConfigs.cpp)58
-rw-r--r--configstore/1.1/default/SurfaceFlingerConfigs.h (renamed from configstore/1.0/default/SurfaceFlingerConfigs.h)18
-rw-r--r--configstore/1.1/default/android.hardware.configstore@1.1-service.rc4
-rw-r--r--configstore/1.1/default/seccomp_policy/configstore@1.1-arm64.policy (renamed from configstore/1.0/default/seccomp_policy/configstore@1.0-arm64.policy)0
-rw-r--r--configstore/1.1/default/service.cpp (renamed from configstore/1.0/default/service.cpp)12
-rw-r--r--configstore/1.1/default/surfaceflinger.mk (renamed from configstore/1.0/default/surfaceflinger.mk)4
-rw-r--r--configstore/1.1/types.hal31
-rw-r--r--configstore/utils/Android.bp2
-rw-r--r--configstore/utils/include/configstore/Utils.h16
-rw-r--r--current.txt6
-rw-r--r--keymaster/4.0/IKeymasterDevice.hal1040
-rw-r--r--keymaster/4.0/support/Keymaster.cpp24
-rw-r--r--keymaster/4.0/types.hal969
28 files changed, 2065 insertions, 442 deletions
diff --git a/CleanSpec.mk b/CleanSpec.mk
index 00d0aa50..531e44ec 100644
--- a/CleanSpec.mk
+++ b/CleanSpec.mk
@@ -64,3 +64,5 @@ $(call add-clean-step, rm -rf $(PRODUCT_OUT)/system/lib/android.hardware.tests*)
64$(call add-clean-step, rm -rf $(PRODUCT_OUT)/system/lib/vndk/android.hardware.tests*) 64$(call add-clean-step, rm -rf $(PRODUCT_OUT)/system/lib/vndk/android.hardware.tests*)
65$(call add-clean-step, rm -rf $(PRODUCT_OUT)/system/lib/vndk-sp/android.hardware.graphics.allocator*) 65$(call add-clean-step, rm -rf $(PRODUCT_OUT)/system/lib/vndk-sp/android.hardware.graphics.allocator*)
66$(call add-clean-step, find $(PRODUCT_OUT)/system $(PRODUCT_OUT)/vendor -type f -name "android\.hardware\.configstore\@1\.1*" -print0 | xargs -0 rm -f) 66$(call add-clean-step, find $(PRODUCT_OUT)/system $(PRODUCT_OUT)/vendor -type f -name "android\.hardware\.configstore\@1\.1*" -print0 | xargs -0 rm -f)
67$(call add-clean-step, find $(PRODUCT_OUT)/system $(PRODUCT_OUT)/vendor -type f -name "android\.hardware\.configstore*" -print0 | xargs -0 rm -f)
68$(call add-clean-step, rm -rf $(PRODUCT_OUT)/vendor/etc/seccomp_policy/configstore@1.0.policy)
diff --git a/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp b/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp
index 571b80c7..62b00379 100644
--- a/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp
+++ b/broadcastradio/2.0/vts/functional/VtsHalBroadcastradioV2_0TargetTest.cpp
@@ -137,29 +137,30 @@ TunerCallbackMock::TunerCallbackMock() {
137} 137}
138 138
139Return<void> TunerCallbackMock::onCurrentProgramInfoChanged(const ProgramInfo& info) { 139Return<void> TunerCallbackMock::onCurrentProgramInfoChanged(const ProgramInfo& info) {
140 auto logically = utils::getType(info.logicallyTunedTo); 140 for (auto&& id : info.selector) {
141 if (logically != IdentifierType::INVALID) { 141 EXPECT_NE(IdentifierType::INVALID, utils::getType(id));
142 EXPECT_TRUE(logically == IdentifierType::AMFM_FREQUENCY ||
143 logically == IdentifierType::RDS_PI ||
144 logically == IdentifierType::HD_STATION_ID_EXT ||
145 logically == IdentifierType::DAB_SID_EXT ||
146 logically == IdentifierType::DRMO_SERVICE_ID ||
147 logically == IdentifierType::SXM_SERVICE_ID ||
148 (logically >= IdentifierType::VENDOR_START &&
149 logically <= IdentifierType::VENDOR_END) ||
150 logically > IdentifierType::SXM_CHANNEL);
151 } 142 }
152 143
144 auto logically = utils::getType(info.logicallyTunedTo);
145 /* This field is required for currently tuned program and should be INVALID
146 * for entries from the program list.
147 */
148 EXPECT_TRUE(
149 logically == IdentifierType::AMFM_FREQUENCY || logically == IdentifierType::RDS_PI ||
150 logically == IdentifierType::HD_STATION_ID_EXT ||
151 logically == IdentifierType::DAB_SID_EXT || logically == IdentifierType::DRMO_SERVICE_ID ||
152 logically == IdentifierType::SXM_SERVICE_ID ||
153 (logically >= IdentifierType::VENDOR_START && logically <= IdentifierType::VENDOR_END) ||
154 logically > IdentifierType::SXM_CHANNEL);
155
153 auto physically = utils::getType(info.physicallyTunedTo); 156 auto physically = utils::getType(info.physicallyTunedTo);
154 if (physically != IdentifierType::INVALID) { 157 // ditto (see "logically" above)
155 EXPECT_TRUE(physically == IdentifierType::AMFM_FREQUENCY || 158 EXPECT_TRUE(
156 physically == IdentifierType::DAB_ENSEMBLE || 159 physically == IdentifierType::AMFM_FREQUENCY ||
157 physically == IdentifierType::DRMO_FREQUENCY || 160 physically == IdentifierType::DAB_ENSEMBLE ||
158 physically == IdentifierType::SXM_CHANNEL || 161 physically == IdentifierType::DRMO_FREQUENCY || physically == IdentifierType::SXM_CHANNEL ||
159 (physically >= IdentifierType::VENDOR_START && 162 (physically >= IdentifierType::VENDOR_START && physically <= IdentifierType::VENDOR_END) ||
160 physically <= IdentifierType::VENDOR_END) || 163 physically > IdentifierType::SXM_CHANNEL);
161 physically > IdentifierType::SXM_CHANNEL);
162 }
163 164
164 if (logically == IdentifierType::AMFM_FREQUENCY) { 165 if (logically == IdentifierType::AMFM_FREQUENCY) {
165 auto ps = utils::getMetadataString(info, MetadataKey::RDS_PS); 166 auto ps = utils::getMetadataString(info, MetadataKey::RDS_PS);
diff --git a/broadcastradio/common/tests/IdentifierIterator_test.cpp b/broadcastradio/common/tests/IdentifierIterator_test.cpp
index 5bf222bf..75e0d49d 100644
--- a/broadcastradio/common/tests/IdentifierIterator_test.cpp
+++ b/broadcastradio/common/tests/IdentifierIterator_test.cpp
@@ -33,8 +33,8 @@ TEST(IdentifierIteratorTest, singleSecondary) {
33 }; 33 };
34 // clang-format on 34 // clang-format on
35 35
36 auto it = utils::begin(sel); 36 auto it = V2_0::begin(sel);
37 auto end = utils::end(sel); 37 auto end = V2_0::end(sel);
38 38
39 ASSERT_NE(end, it); 39 ASSERT_NE(end, it);
40 EXPECT_EQ(sel.primaryId, *it); 40 EXPECT_EQ(sel.primaryId, *it);
@@ -46,8 +46,8 @@ TEST(IdentifierIteratorTest, singleSecondary) {
46TEST(IdentifierIteratorTest, empty) { 46TEST(IdentifierIteratorTest, empty) {
47 V2_0::ProgramSelector sel{}; 47 V2_0::ProgramSelector sel{};
48 48
49 auto it = utils::begin(sel); 49 auto it = V2_0::begin(sel);
50 auto end = utils::end(sel); 50 auto end = V2_0::end(sel);
51 51
52 ASSERT_NE(end, it++); // primary id is always present 52 ASSERT_NE(end, it++); // primary id is always present
53 ASSERT_EQ(end, it); 53 ASSERT_EQ(end, it);
@@ -57,8 +57,8 @@ TEST(IdentifierIteratorTest, twoSelectors) {
57 V2_0::ProgramSelector sel1{}; 57 V2_0::ProgramSelector sel1{};
58 V2_0::ProgramSelector sel2{}; 58 V2_0::ProgramSelector sel2{};
59 59
60 auto it1 = utils::begin(sel1); 60 auto it1 = V2_0::begin(sel1);
61 auto it2 = utils::begin(sel2); 61 auto it2 = V2_0::begin(sel2);
62 62
63 EXPECT_NE(it1, it2); 63 EXPECT_NE(it1, it2);
64} 64}
@@ -66,8 +66,8 @@ TEST(IdentifierIteratorTest, twoSelectors) {
66TEST(IdentifierIteratorTest, increments) { 66TEST(IdentifierIteratorTest, increments) {
67 V2_0::ProgramSelector sel{{}, {{}, {}}}; 67 V2_0::ProgramSelector sel{{}, {{}, {}}};
68 68
69 auto it = utils::begin(sel); 69 auto it = V2_0::begin(sel);
70 auto end = utils::end(sel); 70 auto end = V2_0::end(sel);
71 auto pre = it; 71 auto pre = it;
72 auto post = it; 72 auto post = it;
73 73
@@ -102,8 +102,8 @@ TEST(IdentifierIteratorTest, findType) {
102 auto isRdsPi = std::bind(typeEquals, _1, IdentifierType::RDS_PI); 102 auto isRdsPi = std::bind(typeEquals, _1, IdentifierType::RDS_PI);
103 auto isFreq = std::bind(typeEquals, _1, IdentifierType::AMFM_FREQUENCY); 103 auto isFreq = std::bind(typeEquals, _1, IdentifierType::AMFM_FREQUENCY);
104 104
105 auto end = utils::end(sel); 105 auto end = V2_0::end(sel);
106 auto it = std::find_if(utils::begin(sel), end, isRdsPi); 106 auto it = std::find_if(V2_0::begin(sel), end, isRdsPi);
107 ASSERT_NE(end, it); 107 ASSERT_NE(end, it);
108 EXPECT_EQ(rds_pi1, it->value); 108 EXPECT_EQ(rds_pi1, it->value);
109 109
@@ -111,7 +111,7 @@ TEST(IdentifierIteratorTest, findType) {
111 ASSERT_NE(end, it); 111 ASSERT_NE(end, it);
112 EXPECT_EQ(rds_pi2, it->value); 112 EXPECT_EQ(rds_pi2, it->value);
113 113
114 it = std::find_if(utils::begin(sel), end, isFreq); 114 it = std::find_if(V2_0::begin(sel), end, isFreq);
115 ASSERT_NE(end, it); 115 ASSERT_NE(end, it);
116 EXPECT_EQ(freq1, it->value); 116 EXPECT_EQ(freq1, it->value);
117 117
@@ -120,4 +120,17 @@ TEST(IdentifierIteratorTest, findType) {
120 EXPECT_EQ(freq2, it->value); 120 EXPECT_EQ(freq2, it->value);
121} 121}
122 122
123TEST(IdentifierIteratorTest, rangeLoop) {
124 V2_0::ProgramSelector sel{{}, {{}, {}, {}}};
125
126 unsigned count = 0;
127 for (auto&& id : sel) {
128 ASSERT_EQ(0u, id.type);
129 count++;
130 }
131
132 const auto expectedCount = 1 + sel.secondaryIds.size();
133 ASSERT_EQ(expectedCount, count);
134}
135
123} // anonymous namespace 136} // anonymous namespace
diff --git a/broadcastradio/common/utils2x/Utils.cpp b/broadcastradio/common/utils2x/Utils.cpp
index 6fe95549..3e20b357 100644
--- a/broadcastradio/common/utils2x/Utils.cpp
+++ b/broadcastradio/common/utils2x/Utils.cpp
@@ -81,14 +81,6 @@ bool IdentifierIterator::operator==(const IdentifierIterator& rhs) const {
81 return mPos == rhs.mPos; 81 return mPos == rhs.mPos;
82} 82}
83 83
84IdentifierIterator begin(const V2_0::ProgramSelector& sel) {
85 return IdentifierIterator(sel);
86}
87
88IdentifierIterator end(const V2_0::ProgramSelector& sel) {
89 return IdentifierIterator(sel) + 1 /* primary id */ + sel.secondaryIds.size();
90}
91
92FrequencyBand getBand(uint64_t freq) { 84FrequencyBand getBand(uint64_t freq) {
93 // keep in sync with 85 // keep in sync with
94 // frameworks/base/services/core/java/com/android/server/broadcastradio/hal2/Utils.java 86 // frameworks/base/services/core/java/com/android/server/broadcastradio/hal2/Utils.java
@@ -411,6 +403,18 @@ V2_0::ProgramIdentifier make_hdradio_station_name(const std::string& name) {
411} 403}
412 404
413} // namespace utils 405} // namespace utils
406
407namespace V2_0 {
408
409utils::IdentifierIterator begin(const ProgramSelector& sel) {
410 return utils::IdentifierIterator(sel);
411}
412
413utils::IdentifierIterator end(const ProgramSelector& sel) {
414 return utils::IdentifierIterator(sel) + 1 /* primary id */ + sel.secondaryIds.size();
415}
416
417} // namespace V2_0
414} // namespace broadcastradio 418} // namespace broadcastradio
415} // namespace hardware 419} // namespace hardware
416} // namespace android 420} // namespace android
diff --git a/broadcastradio/common/utils2x/include/broadcastradio-utils-2x/Utils.h b/broadcastradio/common/utils2x/include/broadcastradio-utils-2x/Utils.h
index 5e519416..c4aecb21 100644
--- a/broadcastradio/common/utils2x/include/broadcastradio-utils-2x/Utils.h
+++ b/broadcastradio/common/utils2x/include/broadcastradio-utils-2x/Utils.h
@@ -69,9 +69,6 @@ class IdentifierIterator
69 size_t mPos = 0; 69 size_t mPos = 0;
70}; 70};
71 71
72IdentifierIterator begin(const V2_0::ProgramSelector& sel);
73IdentifierIterator end(const V2_0::ProgramSelector& sel);
74
75/** 72/**
76 * Guesses band from the frequency value. 73 * Guesses band from the frequency value.
77 * 74 *
@@ -153,6 +150,13 @@ std::optional<std::string> getMetadataString(const V2_0::ProgramInfo& info,
153V2_0::ProgramIdentifier make_hdradio_station_name(const std::string& name); 150V2_0::ProgramIdentifier make_hdradio_station_name(const std::string& name);
154 151
155} // namespace utils 152} // namespace utils
153
154namespace V2_0 {
155
156utils::IdentifierIterator begin(const ProgramSelector& sel);
157utils::IdentifierIterator end(const ProgramSelector& sel);
158
159} // namespace V2_0
156} // namespace broadcastradio 160} // namespace broadcastradio
157} // namespace hardware 161} // namespace hardware
158} // namespace android 162} // namespace android
diff --git a/camera/common/1.0/default/CameraModule.cpp b/camera/common/1.0/default/CameraModule.cpp
index 9217a823..dc4e0f01 100644
--- a/camera/common/1.0/default/CameraModule.cpp
+++ b/camera/common/1.0/default/CameraModule.cpp
@@ -306,7 +306,7 @@ int CameraModule::getCameraInfo(int cameraId, struct camera_info *info) {
306 return ret; 306 return ret;
307 } 307 }
308 CameraMetadata m; 308 CameraMetadata m;
309 m = rawInfo.static_camera_characteristics; 309 m.append(rawInfo.static_camera_characteristics);
310 deriveCameraCharacteristicsKeys(rawInfo.device_version, m); 310 deriveCameraCharacteristicsKeys(rawInfo.device_version, m);
311 cameraInfo = rawInfo; 311 cameraInfo = rawInfo;
312 cameraInfo.static_camera_characteristics = m.release(); 312 cameraInfo.static_camera_characteristics = m.release();
diff --git a/camera/device/3.2/default/CameraDeviceSession.cpp b/camera/device/3.2/default/CameraDeviceSession.cpp
index 1cef882f..f33da134 100644
--- a/camera/device/3.2/default/CameraDeviceSession.cpp
+++ b/camera/device/3.2/default/CameraDeviceSession.cpp
@@ -35,6 +35,13 @@ static constexpr size_t CAMERA_REQUEST_METADATA_QUEUE_SIZE = 1 << 20 /* 1MB */;
35// Size of result metadata fast message queue. Change to 0 to always use hwbinder buffer. 35// Size of result metadata fast message queue. Change to 0 to always use hwbinder buffer.
36static constexpr size_t CAMERA_RESULT_METADATA_QUEUE_SIZE = 1 << 20 /* 1MB */; 36static constexpr size_t CAMERA_RESULT_METADATA_QUEUE_SIZE = 1 << 20 /* 1MB */;
37 37
38// Metadata sent by HAL will be replaced by a compact copy
39// if their (total size >= compact size + METADATA_SHRINK_ABS_THRESHOLD &&
40// total_size >= compact size * METADATA_SHRINK_REL_THRESHOLD)
41// Heuristically picked by size of one page
42static constexpr int METADATA_SHRINK_ABS_THRESHOLD = 4096;
43static constexpr int METADATA_SHRINK_REL_THRESHOLD = 2;
44
38HandleImporter CameraDeviceSession::sHandleImporter; 45HandleImporter CameraDeviceSession::sHandleImporter;
39const int CameraDeviceSession::ResultBatcher::NOT_BATCHED; 46const int CameraDeviceSession::ResultBatcher::NOT_BATCHED;
40 47
@@ -780,13 +787,11 @@ Status CameraDeviceSession::constructDefaultRequestSettingsRaw(int type, CameraM
780 mOverridenRequest.update( 787 mOverridenRequest.update(
781 ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST, 788 ANDROID_CONTROL_POST_RAW_SENSITIVITY_BOOST,
782 defaultBoost, 1); 789 defaultBoost, 1);
783 const camera_metadata_t *metaBuffer =
784 mOverridenRequest.getAndLock();
785 convertToHidl(metaBuffer, outMetadata);
786 mOverridenRequest.unlock(metaBuffer);
787 } else {
788 convertToHidl(rawRequest, outMetadata);
789 } 790 }
791 const camera_metadata_t *metaBuffer =
792 mOverridenRequest.getAndLock();
793 convertToHidl(metaBuffer, outMetadata);
794 mOverridenRequest.unlock(metaBuffer);
790 } 795 }
791 } 796 }
792 return status; 797 return status;
@@ -1362,6 +1367,62 @@ status_t CameraDeviceSession::constructCaptureResult(CaptureResult& result,
1362 return OK; 1367 return OK;
1363} 1368}
1364 1369
1370// Static helper method to copy/shrink capture result metadata sent by HAL
1371void CameraDeviceSession::sShrinkCaptureResult(
1372 camera3_capture_result* dst, const camera3_capture_result* src,
1373 std::vector<::android::hardware::camera::common::V1_0::helper::CameraMetadata>* mds,
1374 std::vector<const camera_metadata_t*>* physCamMdArray,
1375 bool handlePhysCam) {
1376 *dst = *src;
1377 if (sShouldShrink(src->result)) {
1378 mds->emplace_back(sCreateCompactCopy(src->result));
1379 dst->result = mds->back().getAndLock();
1380 }
1381
1382 if (handlePhysCam) {
1383 // First determine if we need to create new camera_metadata_t* array
1384 bool needShrink = false;
1385 for (uint32_t i = 0; i < src->num_physcam_metadata; i++) {
1386 if (sShouldShrink(src->physcam_metadata[i])) {
1387 needShrink = true;
1388 }
1389 }
1390
1391 if (!needShrink) return;
1392
1393 physCamMdArray->reserve(src->num_physcam_metadata);
1394 dst->physcam_metadata = physCamMdArray->data();
1395 for (uint32_t i = 0; i < src->num_physcam_metadata; i++) {
1396 if (sShouldShrink(src->physcam_metadata[i])) {
1397 mds->emplace_back(sCreateCompactCopy(src->physcam_metadata[i]));
1398 dst->physcam_metadata[i] = mds->back().getAndLock();
1399 } else {
1400 dst->physcam_metadata[i] = src->physcam_metadata[i];
1401 }
1402 }
1403 }
1404}
1405
1406bool CameraDeviceSession::sShouldShrink(const camera_metadata_t* md) {
1407 size_t compactSize = get_camera_metadata_compact_size(md);
1408 size_t totalSize = get_camera_metadata_size(md);
1409 if (totalSize >= compactSize + METADATA_SHRINK_ABS_THRESHOLD &&
1410 totalSize >= compactSize * METADATA_SHRINK_REL_THRESHOLD) {
1411 ALOGV("Camera metadata should be shrunk from %zu to %zu", totalSize, compactSize);
1412 return true;
1413 }
1414 return false;
1415}
1416
1417camera_metadata_t* CameraDeviceSession::sCreateCompactCopy(const camera_metadata_t* src) {
1418 size_t compactSize = get_camera_metadata_compact_size(src);
1419 void* buffer = calloc(1, compactSize);
1420 if (buffer == nullptr) {
1421 ALOGE("%s: Allocating %zu bytes failed", __FUNCTION__, compactSize);
1422 }
1423 return copy_camera_metadata(buffer, compactSize, src);
1424}
1425
1365/** 1426/**
1366 * Static callback forwarding methods from HAL to instance 1427 * Static callback forwarding methods from HAL to instance
1367 */ 1428 */
@@ -1372,7 +1433,13 @@ void CameraDeviceSession::sProcessCaptureResult(
1372 const_cast<CameraDeviceSession*>(static_cast<const CameraDeviceSession*>(cb)); 1433 const_cast<CameraDeviceSession*>(static_cast<const CameraDeviceSession*>(cb));
1373 1434
1374 CaptureResult result = {}; 1435 CaptureResult result = {};
1375 status_t ret = d->constructCaptureResult(result, hal_result); 1436 camera3_capture_result shadowResult;
1437 bool handlePhysCam = (d->mDeviceVersion >= CAMERA_DEVICE_API_VERSION_3_5);
1438 std::vector<::android::hardware::camera::common::V1_0::helper::CameraMetadata> compactMds;
1439 std::vector<const camera_metadata_t*> physCamMdArray;
1440 sShrinkCaptureResult(&shadowResult, hal_result, &compactMds, &physCamMdArray, handlePhysCam);
1441
1442 status_t ret = d->constructCaptureResult(result, &shadowResult);
1376 if (ret == OK) { 1443 if (ret == OK) {
1377 d->mResultBatcher.processCaptureResult(result); 1444 d->mResultBatcher.processCaptureResult(result);
1378 } 1445 }
diff --git a/camera/device/3.2/default/CameraDeviceSession.h b/camera/device/3.2/default/CameraDeviceSession.h
index 269cc06f..af90e5a0 100644
--- a/camera/device/3.2/default/CameraDeviceSession.h
+++ b/camera/device/3.2/default/CameraDeviceSession.h
@@ -141,7 +141,7 @@ protected:
141 }; 141 };
142 142
143 camera3_device_t* mDevice; 143 camera3_device_t* mDevice;
144 uint32_t mDeviceVersion; 144 const uint32_t mDeviceVersion;
145 bool mIsAELockAvailable; 145 bool mIsAELockAvailable;
146 bool mDerivePostRawSensKey; 146 bool mDerivePostRawSensKey;
147 uint32_t mNumPartialResults; 147 uint32_t mNumPartialResults;
@@ -329,6 +329,17 @@ protected:
329 329
330 status_t constructCaptureResult(CaptureResult& result, 330 status_t constructCaptureResult(CaptureResult& result,
331 const camera3_capture_result *hal_result); 331 const camera3_capture_result *hal_result);
332
333 // Static helper method to copy/shrink capture result metadata sent by HAL
334 // Temporarily allocated metadata copy will be hold in mds
335 static void sShrinkCaptureResult(
336 camera3_capture_result* dst, const camera3_capture_result* src,
337 std::vector<::android::hardware::camera::common::V1_0::helper::CameraMetadata>* mds,
338 std::vector<const camera_metadata_t*>* physCamMdArray,
339 bool handlePhysCam);
340 static bool sShouldShrink(const camera_metadata_t* md);
341 static camera_metadata_t* sCreateCompactCopy(const camera_metadata_t* src);
342
332private: 343private:
333 344
334 struct TrampolineSessionInterface_3_2 : public ICameraDeviceSession { 345 struct TrampolineSessionInterface_3_2 : public ICameraDeviceSession {
diff --git a/camera/device/3.4/default/CameraDeviceSession.cpp b/camera/device/3.4/default/CameraDeviceSession.cpp
index 9722c75d..6a18161f 100644
--- a/camera/device/3.4/default/CameraDeviceSession.cpp
+++ b/camera/device/3.4/default/CameraDeviceSession.cpp
@@ -479,31 +479,40 @@ void CameraDeviceSession::sProcessCaptureResult_3_4(
479 const_cast<CameraDeviceSession*>(static_cast<const CameraDeviceSession*>(cb)); 479 const_cast<CameraDeviceSession*>(static_cast<const CameraDeviceSession*>(cb));
480 480
481 CaptureResult result = {}; 481 CaptureResult result = {};
482 status_t ret = d->constructCaptureResult(result.v3_2, hal_result); 482 camera3_capture_result shadowResult;
483 bool handlePhysCam = (d->mDeviceVersion >= CAMERA_DEVICE_API_VERSION_3_5);
484 std::vector<::android::hardware::camera::common::V1_0::helper::CameraMetadata> compactMds;
485 std::vector<const camera_metadata_t*> physCamMdArray;
486 sShrinkCaptureResult(&shadowResult, hal_result, &compactMds, &physCamMdArray, handlePhysCam);
487
488 status_t ret = d->constructCaptureResult(result.v3_2, &shadowResult);
483 if (ret != OK) { 489 if (ret != OK) {
484 return; 490 return;
485 } 491 }
486 492
487 if (hal_result->num_physcam_metadata > d->mPhysicalCameraIds.size()) { 493 if (handlePhysCam) {
488 ALOGE("%s: Fatal: Invalid num_physcam_metadata %u", __FUNCTION__, 494 if (shadowResult.num_physcam_metadata > d->mPhysicalCameraIds.size()) {
489 hal_result->num_physcam_metadata); 495 ALOGE("%s: Fatal: Invalid num_physcam_metadata %u", __FUNCTION__,
490 return; 496 shadowResult.num_physcam_metadata);
491 }
492 result.physicalCameraMetadata.resize(hal_result->num_physcam_metadata);
493 for (uint32_t i = 0; i < hal_result->num_physcam_metadata; i++) {
494 std::string physicalId = hal_result->physcam_ids[i];
495 if (d->mPhysicalCameraIds.find(physicalId) == d->mPhysicalCameraIds.end()) {
496 ALOGE("%s: Fatal: Invalid physcam_ids[%u]: %s", __FUNCTION__,
497 i, hal_result->physcam_ids[i]);
498 return; 497 return;
499 } 498 }
500 V3_2::CameraMetadata physicalMetadata; 499 result.physicalCameraMetadata.resize(shadowResult.num_physcam_metadata);
501 V3_2::implementation::convertToHidl(hal_result->physcam_metadata[i], &physicalMetadata); 500 for (uint32_t i = 0; i < shadowResult.num_physcam_metadata; i++) {
502 PhysicalCameraMetadata physicalCameraMetadata = { 501 std::string physicalId = shadowResult.physcam_ids[i];
503 .fmqMetadataSize = 0, 502 if (d->mPhysicalCameraIds.find(physicalId) == d->mPhysicalCameraIds.end()) {
504 .physicalCameraId = physicalId, 503 ALOGE("%s: Fatal: Invalid physcam_ids[%u]: %s", __FUNCTION__,
505 .metadata = physicalMetadata }; 504 i, shadowResult.physcam_ids[i]);
506 result.physicalCameraMetadata[i] = physicalCameraMetadata; 505 return;
506 }
507 V3_2::CameraMetadata physicalMetadata;
508 V3_2::implementation::convertToHidl(
509 shadowResult.physcam_metadata[i], &physicalMetadata);
510 PhysicalCameraMetadata physicalCameraMetadata = {
511 .fmqMetadataSize = 0,
512 .physicalCameraId = physicalId,
513 .metadata = physicalMetadata };
514 result.physicalCameraMetadata[i] = physicalCameraMetadata;
515 }
507 } 516 }
508 d->mResultBatcher_3_4.processCaptureResult_3_4(result); 517 d->mResultBatcher_3_4.processCaptureResult_3_4(result);
509} 518}
diff --git a/compatibility_matrices/Android.mk b/compatibility_matrices/Android.mk
index 86fe00dd..3702cf0a 100644
--- a/compatibility_matrices/Android.mk
+++ b/compatibility_matrices/Android.mk
@@ -66,7 +66,7 @@ LOCAL_SRC_FILES := $(LOCAL_MODULE_STEM)
66LOCAL_KERNEL_CONFIG_DATA_PATHS := \ 66LOCAL_KERNEL_CONFIG_DATA_PATHS := \
67 4.4.107:$(my_kernel_config_data)/p/android-4.4 \ 67 4.4.107:$(my_kernel_config_data)/p/android-4.4 \
68 4.9.84:$(my_kernel_config_data)/p/android-4.9 \ 68 4.9.84:$(my_kernel_config_data)/p/android-4.9 \
69 4.14.40:$(my_kernel_config_data)/p/android-4.14 \ 69 4.14.42:$(my_kernel_config_data)/p/android-4.14 \
70 70
71include $(BUILD_FRAMEWORK_COMPATIBILITY_MATRIX) 71include $(BUILD_FRAMEWORK_COMPATIBILITY_MATRIX)
72 72
diff --git a/compatibility_matrices/compatibility_matrix.3.xml b/compatibility_matrices/compatibility_matrix.3.xml
index 2c5d4310..f271642f 100644
--- a/compatibility_matrices/compatibility_matrix.3.xml
+++ b/compatibility_matrices/compatibility_matrix.3.xml
@@ -113,7 +113,7 @@
113 </hal> 113 </hal>
114 <hal format="hidl" optional="false"> 114 <hal format="hidl" optional="false">
115 <name>android.hardware.configstore</name> 115 <name>android.hardware.configstore</name>
116 <version>1.0</version> 116 <version>1.0-1</version>
117 <interface> 117 <interface>
118 <name>ISurfaceFlingerConfigs</name> 118 <name>ISurfaceFlingerConfigs</name>
119 <instance>default</instance> 119 <instance>default</instance>
diff --git a/configstore/1.0/default/android.hardware.configstore@1.0-service.rc b/configstore/1.0/default/android.hardware.configstore@1.0-service.rc
deleted file mode 100644
index 40fb4983..00000000
--- a/configstore/1.0/default/android.hardware.configstore@1.0-service.rc
+++ /dev/null
@@ -1,4 +0,0 @@
1service vendor.configstore-hal-1-0 /vendor/bin/hw/android.hardware.configstore@1.0-service
2 class hal animation
3 user system
4 group system
diff --git a/configstore/1.1/Android.bp b/configstore/1.1/Android.bp
new file mode 100644
index 00000000..2b6e6fa3
--- /dev/null
+++ b/configstore/1.1/Android.bp
@@ -0,0 +1,23 @@
1// This file is autogenerated by hidl-gen -Landroidbp.
2
3hidl_interface {
4 name: "android.hardware.configstore@1.1",
5 root: "android.hardware",
6 vndk: {
7 enabled: true,
8 },
9 srcs: [
10 "types.hal",
11 "ISurfaceFlingerConfigs.hal",
12 ],
13 interfaces: [
14 "android.hardware.configstore@1.0",
15 "android.hidl.base@1.0",
16 ],
17 types: [
18 "DisplayOrientation",
19 "OptionalDisplayOrientation",
20 ],
21 gen_java: true,
22}
23
diff --git a/configstore/1.1/ISurfaceFlingerConfigs.hal b/configstore/1.1/ISurfaceFlingerConfigs.hal
new file mode 100644
index 00000000..3a695941
--- /dev/null
+++ b/configstore/1.1/ISurfaceFlingerConfigs.hal
@@ -0,0 +1,28 @@
1/*
2 * Copyright (C) 2018 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.1 (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.1
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 */
16package android.hardware.configstore@1.1;
17
18import @1.0::ISurfaceFlingerConfigs;
19
20/**
21 * New revision of ISurfaceFlingerConfigs
22 */
23interface ISurfaceFlingerConfigs extends @1.0::ISurfaceFlingerConfigs {
24 /**
25 * Returns the orientation of the primary display device.
26 */
27 primaryDisplayOrientation() generates (OptionalDisplayOrientation value);
28};
diff --git a/configstore/1.0/default/Android.mk b/configstore/1.1/default/Android.mk
index 22d7c920..40f621b3 100644
--- a/configstore/1.0/default/Android.mk
+++ b/configstore/1.1/default/Android.mk
@@ -2,15 +2,15 @@ LOCAL_PATH := $(call my-dir)
2 2
3################################################################################ 3################################################################################
4include $(CLEAR_VARS) 4include $(CLEAR_VARS)
5LOCAL_MODULE := android.hardware.configstore@1.0-service 5LOCAL_MODULE := android.hardware.configstore@1.1-service
6# seccomp is not required for coverage build. 6# seccomp is not required for coverage build.
7ifneq ($(NATIVE_COVERAGE),true) 7ifneq ($(NATIVE_COVERAGE),true)
8LOCAL_REQUIRED_MODULES_arm64 := configstore@1.0.policy 8LOCAL_REQUIRED_MODULES_arm64 := configstore@1.1.policy
9endif 9endif
10LOCAL_PROPRIETARY_MODULE := true 10LOCAL_PROPRIETARY_MODULE := true
11LOCAL_MODULE_CLASS := EXECUTABLES 11LOCAL_MODULE_CLASS := EXECUTABLES
12LOCAL_MODULE_RELATIVE_PATH := hw 12LOCAL_MODULE_RELATIVE_PATH := hw
13LOCAL_INIT_RC := android.hardware.configstore@1.0-service.rc 13LOCAL_INIT_RC := android.hardware.configstore@1.1-service.rc
14LOCAL_SRC_FILES:= service.cpp 14LOCAL_SRC_FILES:= service.cpp
15 15
16include $(LOCAL_PATH)/surfaceflinger.mk 16include $(LOCAL_PATH)/surfaceflinger.mk
@@ -22,16 +22,17 @@ LOCAL_SHARED_LIBRARIES := \
22 libhwminijail \ 22 libhwminijail \
23 liblog \ 23 liblog \
24 libutils \ 24 libutils \
25 android.hardware.configstore@1.0 25 android.hardware.configstore@1.0 \
26 android.hardware.configstore@1.1
26 27
27include $(BUILD_EXECUTABLE) 28include $(BUILD_EXECUTABLE)
28 29
29# seccomp filter for configstore 30# seccomp filter for configstore
30ifeq ($(TARGET_ARCH), $(filter $(TARGET_ARCH), arm64)) 31ifeq ($(TARGET_ARCH), $(filter $(TARGET_ARCH), arm64))
31include $(CLEAR_VARS) 32include $(CLEAR_VARS)
32LOCAL_MODULE := configstore@1.0.policy 33LOCAL_MODULE := configstore@1.1.policy
33LOCAL_MODULE_CLASS := ETC 34LOCAL_MODULE_CLASS := ETC
34LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/etc/seccomp_policy 35LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/etc/seccomp_policy
35LOCAL_SRC_FILES := seccomp_policy/configstore@1.0-$(TARGET_ARCH).policy 36LOCAL_SRC_FILES := seccomp_policy/configstore@1.1-$(TARGET_ARCH).policy
36include $(BUILD_PREBUILT) 37include $(BUILD_PREBUILT)
37endif 38endif
diff --git a/configstore/1.0/default/SurfaceFlingerConfigs.cpp b/configstore/1.1/default/SurfaceFlingerConfigs.cpp
index 3239274f..da3081c1 100644
--- a/configstore/1.0/default/SurfaceFlingerConfigs.cpp
+++ b/configstore/1.1/default/SurfaceFlingerConfigs.cpp
@@ -1,5 +1,5 @@
1/* 1/*
2 * Copyright (C) 2017 The Android Open Source Project 2 * Copyright (C) 2018 The Android Open Source Project
3 * 3 *
4 * Licensed under the Apache License, Version 2.1 (the "License"); 4 * Licensed under the Apache License, Version 2.1 (the "License");
5 * you may not use this file except in compliance with the License. 5 * you may not use this file except in compliance with the License.
@@ -16,10 +16,13 @@
16 16
17#include "SurfaceFlingerConfigs.h" 17#include "SurfaceFlingerConfigs.h"
18 18
19#include <android/hardware/configstore/1.1/types.h>
20#include <log/log.h>
21
19namespace android { 22namespace android {
20namespace hardware { 23namespace hardware {
21namespace configstore { 24namespace configstore {
22namespace V1_0 { 25namespace V1_1 {
23namespace implementation { 26namespace implementation {
24 27
25// Methods from ::android::hardware::configstore::V1_0::ISurfaceFlingerConfigs 28// Methods from ::android::hardware::configstore::V1_0::ISurfaceFlingerConfigs
@@ -139,10 +142,59 @@ Return<void> SurfaceFlingerConfigs::startGraphicsAllocatorService(
139 return Void(); 142 return Void();
140} 143}
141 144
145// Methods from ::android::hardware::configstore::V1_1::ISurfaceFlingerConfigs
146// follow.
147
148#ifdef PRIMARY_DISPLAY_ORIENTATION
149static_assert(PRIMARY_DISPLAY_ORIENTATION == 0 || PRIMARY_DISPLAY_ORIENTATION == 90 ||
150 PRIMARY_DISPLAY_ORIENTATION == 180 || PRIMARY_DISPLAY_ORIENTATION == 270,
151 "Primary display orientation must be 0/90/180/270");
152#endif
153
154Return<void> SurfaceFlingerConfigs::primaryDisplayOrientation(
155 primaryDisplayOrientation_cb _hidl_cb) {
156 using ::android::hardware::configstore::V1_1::DisplayOrientation;
157
158 bool specified = false;
159 DisplayOrientation value = DisplayOrientation::ORIENTATION_0;
160
161 int orientation = 0;
162#ifdef PRIMARY_DISPLAY_ORIENTATION
163 specified = true;
164 orientation = PRIMARY_DISPLAY_ORIENTATION;
165#endif
166
167 switch (orientation) {
168 case 0: {
169 value = DisplayOrientation::ORIENTATION_0;
170 break;
171 }
172 case 90: {
173 value = DisplayOrientation::ORIENTATION_90;
174 break;
175 }
176 case 180: {
177 value = DisplayOrientation::ORIENTATION_180;
178 break;
179 }
180 case 270: {
181 value = DisplayOrientation::ORIENTATION_270;
182 break;
183 }
184 default: {
185 // statically checked above -> memory corruption
186 LOG_ALWAYS_FATAL("Invalid orientation %d", orientation);
187 }
188 }
189
190 _hidl_cb({specified, value});
191 return Void();
192}
193
142// Methods from ::android::hidl::base::V1_0::IBase follow. 194// Methods from ::android::hidl::base::V1_0::IBase follow.
143 195
144} // namespace implementation 196} // namespace implementation
145} // namespace V1_0 197} // namespace V1_1
146} // namespace configstore 198} // namespace configstore
147} // namespace hardware 199} // namespace hardware
148} // namespace android 200} // namespace android
diff --git a/configstore/1.0/default/SurfaceFlingerConfigs.h b/configstore/1.1/default/SurfaceFlingerConfigs.h
index 32e5fc39..3714e816 100644
--- a/configstore/1.0/default/SurfaceFlingerConfigs.h
+++ b/configstore/1.1/default/SurfaceFlingerConfigs.h
@@ -1,17 +1,17 @@
1#ifndef ANDROID_HARDWARE_CONFIGSTORE_V1_0_SURFACEFLINGERCONFIGS_H 1#ifndef ANDROID_HARDWARE_CONFIGSTORE_V1_1_SURFACEFLINGERCONFIGS_H
2#define ANDROID_HARDWARE_CONFIGSTORE_V1_0_SURFACEFLINGERCONFIGS_H 2#define ANDROID_HARDWARE_CONFIGSTORE_V1_1_SURFACEFLINGERCONFIGS_H
3 3
4#include <android/hardware/configstore/1.0/ISurfaceFlingerConfigs.h> 4#include <android/hardware/configstore/1.1/ISurfaceFlingerConfigs.h>
5#include <hidl/MQDescriptor.h> 5#include <hidl/MQDescriptor.h>
6#include <hidl/Status.h> 6#include <hidl/Status.h>
7 7
8namespace android { 8namespace android {
9namespace hardware { 9namespace hardware {
10namespace configstore { 10namespace configstore {
11namespace V1_0 { 11namespace V1_1 {
12namespace implementation { 12namespace implementation {
13 13
14using ::android::hardware::configstore::V1_0::ISurfaceFlingerConfigs; 14using ::android::hardware::configstore::V1_1::ISurfaceFlingerConfigs;
15using ::android::hardware::Return; 15using ::android::hardware::Return;
16using ::android::hardware::Void; 16using ::android::hardware::Void;
17using ::android::sp; 17using ::android::sp;
@@ -32,13 +32,17 @@ struct SurfaceFlingerConfigs : public ISurfaceFlingerConfigs {
32 Return<void> maxFrameBufferAcquiredBuffers(maxFrameBufferAcquiredBuffers_cb _hidl_cb) override; 32 Return<void> maxFrameBufferAcquiredBuffers(maxFrameBufferAcquiredBuffers_cb _hidl_cb) override;
33 Return<void> startGraphicsAllocatorService(startGraphicsAllocatorService_cb _hidl_cb) override; 33 Return<void> startGraphicsAllocatorService(startGraphicsAllocatorService_cb _hidl_cb) override;
34 34
35 // Methods from
36 // ::android::hardware::configstore::V1_1::ISurfaceFlingerConfigs follow.
37 Return<void> primaryDisplayOrientation(primaryDisplayOrientation_cb _hidl_cb) override;
38
35 // Methods from ::android::hidl::base::V1_0::IBase follow. 39 // Methods from ::android::hidl::base::V1_0::IBase follow.
36}; 40};
37 41
38} // namespace implementation 42} // namespace implementation
39} // namespace V1_0 43} // namespace V1_1
40} // namespace configstore 44} // namespace configstore
41} // namespace hardware 45} // namespace hardware
42} // namespace android 46} // namespace android
43 47
44#endif // ANDROID_HARDWARE_CONFIGSTORE_V1_0_SURFACEFLINGERCONFIGS_H 48#endif // ANDROID_HARDWARE_CONFIGSTORE_V1_1_SURFACEFLINGERCONFIGS_H
diff --git a/configstore/1.1/default/android.hardware.configstore@1.1-service.rc b/configstore/1.1/default/android.hardware.configstore@1.1-service.rc
new file mode 100644
index 00000000..105678ac
--- /dev/null
+++ b/configstore/1.1/default/android.hardware.configstore@1.1-service.rc
@@ -0,0 +1,4 @@
1service vendor.configstore-hal /vendor/bin/hw/android.hardware.configstore@1.1-service
2 class hal animation
3 user system
4 group system
diff --git a/configstore/1.0/default/seccomp_policy/configstore@1.0-arm64.policy b/configstore/1.1/default/seccomp_policy/configstore@1.1-arm64.policy
index d523a1a7..d523a1a7 100644
--- a/configstore/1.0/default/seccomp_policy/configstore@1.0-arm64.policy
+++ b/configstore/1.1/default/seccomp_policy/configstore@1.1-arm64.policy
diff --git a/configstore/1.0/default/service.cpp b/configstore/1.1/default/service.cpp
index c9c81a07..3b4e7745 100644
--- a/configstore/1.0/default/service.cpp
+++ b/configstore/1.1/default/service.cpp
@@ -1,5 +1,5 @@
1/* 1/*
2 * Copyright (C) 2017 The Android Open Source Project 2 * Copyright (C) 2018 The Android Open Source Project
3 * 3 *
4 * Licensed under the Apache License, Version 2.1 (the "License"); 4 * Licensed under the Apache License, Version 2.1 (the "License");
5 * you may not use this file except in compliance with the License. 5 * you may not use this file except in compliance with the License.
@@ -14,9 +14,9 @@
14 * limitations under the License. 14 * limitations under the License.
15 */ 15 */
16 16
17#define LOG_TAG "android.hardware.configstore@1.0-service" 17#define LOG_TAG "android.hardware.configstore@1.1-service"
18 18
19#include <android/hardware/configstore/1.0/ISurfaceFlingerConfigs.h> 19#include <android/hardware/configstore/1.1/ISurfaceFlingerConfigs.h>
20#include <hidl/HidlTransportSupport.h> 20#include <hidl/HidlTransportSupport.h>
21#include <hwminijail/HardwareMinijail.h> 21#include <hwminijail/HardwareMinijail.h>
22 22
@@ -24,8 +24,8 @@
24 24
25using android::hardware::configureRpcThreadpool; 25using android::hardware::configureRpcThreadpool;
26using android::hardware::joinRpcThreadpool; 26using android::hardware::joinRpcThreadpool;
27using android::hardware::configstore::V1_0::ISurfaceFlingerConfigs; 27using android::hardware::configstore::V1_1::ISurfaceFlingerConfigs;
28using android::hardware::configstore::V1_0::implementation::SurfaceFlingerConfigs; 28using android::hardware::configstore::V1_1::implementation::SurfaceFlingerConfigs;
29using android::hardware::SetupMinijail; 29using android::hardware::SetupMinijail;
30using android::sp; 30using android::sp;
31using android::status_t; 31using android::status_t;
@@ -34,7 +34,7 @@ using android::OK;
34int main() { 34int main() {
35 configureRpcThreadpool(10, true); 35 configureRpcThreadpool(10, true);
36 36
37 SetupMinijail("/vendor/etc/seccomp_policy/configstore@1.0.policy"); 37 SetupMinijail("/vendor/etc/seccomp_policy/configstore@1.1.policy");
38 38
39 sp<ISurfaceFlingerConfigs> surfaceFlingerConfigs = new SurfaceFlingerConfigs; 39 sp<ISurfaceFlingerConfigs> surfaceFlingerConfigs = new SurfaceFlingerConfigs;
40 status_t status = surfaceFlingerConfigs->registerAsService(); 40 status_t status = surfaceFlingerConfigs->registerAsService();
diff --git a/configstore/1.0/default/surfaceflinger.mk b/configstore/1.1/default/surfaceflinger.mk
index f7487d58..51f06e1f 100644
--- a/configstore/1.0/default/surfaceflinger.mk
+++ b/configstore/1.1/default/surfaceflinger.mk
@@ -58,3 +58,7 @@ endif
58ifneq ($(SF_START_GRAPHICS_ALLOCATOR_SERVICE),) 58ifneq ($(SF_START_GRAPHICS_ALLOCATOR_SERVICE),)
59 LOCAL_CFLAGS += -DSTART_GRAPHICS_ALLOCATOR_SERVICE 59 LOCAL_CFLAGS += -DSTART_GRAPHICS_ALLOCATOR_SERVICE
60endif 60endif
61
62ifneq ($(SF_PRIMARY_DISPLAY_ORIENTATION),)
63 LOCAL_CFLAGS += -DPRIMARY_DISPLAY_ORIENTATION=$(SF_PRIMARY_DISPLAY_ORIENTATION)
64endif
diff --git a/configstore/1.1/types.hal b/configstore/1.1/types.hal
new file mode 100644
index 00000000..adc57476
--- /dev/null
+++ b/configstore/1.1/types.hal
@@ -0,0 +1,31 @@
1/*
2 * Copyright (C) 2018 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 */
16package android.hardware.configstore@1.1;
17
18/**
19 * Orientation in degrees.
20 */
21enum DisplayOrientation : uint8_t {
22 ORIENTATION_0,
23 ORIENTATION_90,
24 ORIENTATION_180,
25 ORIENTATION_270,
26};
27
28struct OptionalDisplayOrientation {
29 bool specified;
30 DisplayOrientation value;
31};
diff --git a/configstore/utils/Android.bp b/configstore/utils/Android.bp
index 93e52f1d..cb4e6ebb 100644
--- a/configstore/utils/Android.bp
+++ b/configstore/utils/Android.bp
@@ -28,11 +28,13 @@ cc_library_shared {
28 28
29 shared_libs: [ 29 shared_libs: [
30 "android.hardware.configstore@1.0", 30 "android.hardware.configstore@1.0",
31 "android.hardware.configstore@1.1",
31 "libbase", 32 "libbase",
32 "libhidlbase" 33 "libhidlbase"
33 ], 34 ],
34 export_shared_lib_headers: [ 35 export_shared_lib_headers: [
35 "android.hardware.configstore@1.0", 36 "android.hardware.configstore@1.0",
37 "android.hardware.configstore@1.1",
36 "libbase", 38 "libbase",
37 "libhidlbase" 39 "libhidlbase"
38 ], 40 ],
diff --git a/configstore/utils/include/configstore/Utils.h b/configstore/utils/include/configstore/Utils.h
index b107a207..e04f57df 100644
--- a/configstore/utils/include/configstore/Utils.h
+++ b/configstore/utils/include/configstore/Utils.h
@@ -18,6 +18,7 @@
18#define ANDROID_HARDWARE_CONFIGSTORE_UTILS_H 18#define ANDROID_HARDWARE_CONFIGSTORE_UTILS_H
19 19
20#include <android/hardware/configstore/1.0/types.h> 20#include <android/hardware/configstore/1.0/types.h>
21#include <android/hardware/configstore/1.1/types.h>
21#include <hidl/Status.h> 22#include <hidl/Status.h>
22 23
23#include <sstream> 24#include <sstream>
@@ -34,13 +35,20 @@ void logAlwaysError(const std::string& message);
34} // namespace details 35} // namespace details
35 36
36namespace configstore { 37namespace configstore {
37// import types from V1_0 38// import types from configstore
39using ::android::hardware::configstore::V1_1::DisplayOrientation;
38using ::android::hardware::configstore::V1_0::OptionalBool; 40using ::android::hardware::configstore::V1_0::OptionalBool;
39using ::android::hardware::configstore::V1_0::OptionalInt32; 41using ::android::hardware::configstore::V1_0::OptionalInt32;
40using ::android::hardware::configstore::V1_0::OptionalUInt32; 42using ::android::hardware::configstore::V1_0::OptionalUInt32;
41using ::android::hardware::configstore::V1_0::OptionalInt64; 43using ::android::hardware::configstore::V1_0::OptionalInt64;
42using ::android::hardware::configstore::V1_0::OptionalUInt64; 44using ::android::hardware::configstore::V1_0::OptionalUInt64;
43using ::android::hardware::configstore::V1_0::OptionalString; 45using ::android::hardware::configstore::V1_0::OptionalString;
46using ::android::hardware::configstore::V1_1::OptionalDisplayOrientation;
47
48static inline std::ostream& operator<<(std::ostream& os, DisplayOrientation orientation) {
49 os << ::android::hardware::configstore::V1_1::toString(orientation);
50 return os;
51}
44 52
45// a function to retrieve and cache the service handle 53// a function to retrieve and cache the service handle
46// for a particular interface 54// for a particular interface
@@ -141,6 +149,12 @@ std::string getString(const std::string &defValue) {
141 return get<OptionalString, I, func>(defValue); 149 return get<OptionalString, I, func>(defValue);
142} 150}
143 151
152template <typename I, android::hardware::Return<void> (I::*func)(
153 std::function<void(const OptionalDisplayOrientation&)>)>
154DisplayOrientation getDisplayOrientation(DisplayOrientation defValue) {
155 return get<OptionalDisplayOrientation, I, func>(defValue);
156}
157
144} // namespace configstore 158} // namespace configstore
145} // namespace hardware 159} // namespace hardware
146} // namespace android 160} // namespace android
diff --git a/current.txt b/current.txt
index 75ea5db6..15b096b3 100644
--- a/current.txt
+++ b/current.txt
@@ -325,6 +325,8 @@ eacf4e7491fc52c4db90898faddf25ec7bc72501b07ae8737434c47cb845128c android.hardwar
325812fa66aa10ba0cba27cfddc2fd7f0ee27a8ab65a1f15aa79fdad97d403e6a14 android.hardware.camera.device@3.4::ICameraDeviceSession 325812fa66aa10ba0cba27cfddc2fd7f0ee27a8ab65a1f15aa79fdad97d403e6a14 android.hardware.camera.device@3.4::ICameraDeviceSession
326cc288f1f78d1e643eb3d3dbc16e1401d44033d8e6856761f5156814a29986ec7 android.hardware.camera.device@3.4::types 326cc288f1f78d1e643eb3d3dbc16e1401d44033d8e6856761f5156814a29986ec7 android.hardware.camera.device@3.4::types
327f9278c8beb9d42d96e26d73ecabe1dff1d7e2fb301ab7f737d93e5ffae8d3312 android.hardware.camera.metadata@3.3::types 327f9278c8beb9d42d96e26d73ecabe1dff1d7e2fb301ab7f737d93e5ffae8d3312 android.hardware.camera.metadata@3.3::types
328f858091b10f7d5927be60573c06df4805275d37226bbb41a732190bfb81457ec android.hardware.configstore@1.1::ISurfaceFlingerConfigs
3295b0fb9842f8b0eb3730b93c30a7925290ab44763ab86bb493bfa58d0f2eeb369 android.hardware.configstore@1.1::types
3281a46aeae45b7a0e47f79b7207300532986f9d9cd7060779afc7a529f54d712ab android.hardware.confirmationui@1.0::IConfirmationResultCallback 3301a46aeae45b7a0e47f79b7207300532986f9d9cd7060779afc7a529f54d712ab android.hardware.confirmationui@1.0::IConfirmationResultCallback
3296d8347ff3cd7de471065ac3e8e68385073630cdeebe9f8fa58cb91cf44436c95 android.hardware.confirmationui@1.0::IConfirmationUI 3316d8347ff3cd7de471065ac3e8e68385073630cdeebe9f8fa58cb91cf44436c95 android.hardware.confirmationui@1.0::IConfirmationUI
330a3ff916784dce87a56c757ab5c86433f0cdf562280999a5f978a6e8a0f3f19e7 android.hardware.confirmationui@1.0::types 332a3ff916784dce87a56c757ab5c86433f0cdf562280999a5f978a6e8a0f3f19e7 android.hardware.confirmationui@1.0::types
@@ -345,8 +347,8 @@ dd83be076b6b3f10ed62ab34d8c8b95f2415961fb785200eb842e7bfb2b0ee92 android.hardwar
345675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth 347675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth
346434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback 348434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback
347c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types 349c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types
348a6cf986593c6ad15fe2ae3a1995d2cae233500bc32c055912a42723bdc076868 android.hardware.keymaster@4.0::IKeymasterDevice 3505c8e06f9945276d1a9e8f7e37cf0ea8894bdb906fa80809cb06c36abb39afc4f android.hardware.keymaster@4.0::IKeymasterDevice
349e15ebdf1e0a326ff5b8a59668d4d8cd3852bd88388eae91de13f5f7e1af50ed1 android.hardware.keymaster@4.0::types 3516695eb5744108035506004dd136068b1aaebe809cf9d4a69c2fe33b73058bb85 android.hardware.keymaster@4.0::types
3506d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor 3526d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor
351b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager 353b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager
3524a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection 3544a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection
diff --git a/keymaster/4.0/IKeymasterDevice.hal b/keymaster/4.0/IKeymasterDevice.hal
index aef81c72..6c09ef33 100644
--- a/keymaster/4.0/IKeymasterDevice.hal
+++ b/keymaster/4.0/IKeymasterDevice.hal
@@ -20,46 +20,234 @@ import android.hardware.keymaster@3.0::ErrorCode;
20import android.hardware.keymaster@3.0::KeyFormat; 20import android.hardware.keymaster@3.0::KeyFormat;
21 21
22/** 22/**
23 * Keymaster device definition. For thorough documentation see the implementer's reference, at 23 * Keymaster device definition.
24 * https://source.android.com/security/keystore/implementer-ref.html 24 *
25 * == Features ==
26 *
27 * An IKeymasterDevice provides cryptographic services, including the following categories of
28 * operations:
29 *
30 * o Key generation
31 * o Import and export (public only) of asymmetric keys
32 * o Import of raw symmetric keys
33 * o Asymmetric encryption and decryption with appropriate padding modes
34 * o Asymmetric signing and verification with digesting and appropriate padding modes
35 * o Symmetric encryption and decryption in appropriate modes, including an AEAD mode
36 * o Generation and verification of symmetric message authentication codes
37 * o Attestation to the presence and configuration of asymmetric keys.
38 *
39 * Protocol elements, such as purpose, mode and padding, as well as access control constraints, must
40 * be specified by the caller when keys are generated or imported and must be permanently bound to
41 * the key, ensuring that the key cannot be used in any other way.
42 *
43 * In addition to the list above, IKeymasterDevice implementations must provide one more service
44 * which is not exposed as an API but used internally: Random number generation. The random number
45 * generator must be high-quality and must be used for generation of keys, initialization vectors,
46 * random padding and other elements of secure protocols that require randomness.
47 *
48 * == Types of IKeymasterDevices ==
49 *
50 * All of the operations and storage of key material must occur in a secure environment. Secure
51 * environments may be either:
52 *
53 * 1. Isolated execution environments, such as a separate virtual machine, hypervisor or
54 * purpose-built trusted execution environment like ARM TrustZone. The isolated environment
55 * must provide complete separation from the Android kernel and user space (collectively called
56 * the "non-secure world", or NSW) so that nothing running in the NSW can observe or manipulate
57 * the results of any computation in the isolated environment. Isolated execution environments
58 * are identified by the SecurityLevel TRUSTED_ENVIRONMENT.
59 *
60 * 2. Completely separate, purpose-built and certified secure CPUs, called "StrongBox" devices.
61 * Examples of StrongBox devices are embedded Secure Elements (eSE) or on-SoC secure processing
62 * units (SPU). StrongBox environments are identified by the SecurityLevel STRONGBOX. To
63 * qualify as a StrongBox, a device must meet the requirements specified in CDD 9.11.2.
64 *
65 * == Necessary Primitives ==
66 *
67 * All IKeymasterDevice implementations must provide support for the following:
68 *
69 * o RSA
70 *
71 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support 2048, 3072 and 4096-bit keys.
72 * STRONGBOX IKeymasterDevices must support 2048-bit keys.
73 * - Public exponent F4 (2^16+1)
74 * - Unpadded, RSASSA-PSS and RSASSA-PKCS1-v1_5 padding modes for RSA signing
75 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD5, SHA1, SHA-2 224, SHA-2 256, SHA-2
76 * 384 and SHA-2 512 digest modes for RSA signing. STRONGBOX IKeymasterDevices must support
77 * SHA-2 256.
78 * - Unpadded, RSAES-OAEP and RSAES-PKCS1-v1_5 padding modes for RSA encryption.
79 *
80 * o ECDSA
81 *
82 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support NIST curves P-224, P-256, P-384 and
83 * P-521. STRONGBOX IKeymasterDevices must support NIST curve P-256.
84 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support SHA1, SHA-2 224, SHA-2 256, SHA-2
85 * 384 and SHA-2 512 digest modes. STRONGBOX IKeymasterDevices must support SHA-2 256.
86 *
87 * o AES
88 *
89 * - 128 and 256-bit keys
90 * - CBC, CTR, ECB and GCM modes. The GCM mode must not allow the use of tags smaller than 96
91 * bits or nonce lengths other than 96 bits.
92 * - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and
93 * ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
94 * multiple of the AES block size. With PKCS7 padding, GCM and CTR operations must fail with
95 * ErrorCode::INCOMPATIBLE_PADDING_MODE.
96 *
97 * o 3DES
98 *
99 * - 168-bit keys.
100 * - CBC and ECB mode.
101
102 * - CBC and ECB modes must support unpadded and PKCS7 padding modes. With no padding CBC and
103 * ECB-mode operations must fail with ErrorCode::INVALID_INPUT_LENGTH if the input isn't a
104 * multiple of the DES block size.
105 *
106 * o HMAC
107 *
108 * - Any key size that is between 64 and 512 bits (inclusive) and a multiple of 8 must be
109 * supported. STRONGBOX IKeymasterDevices must not support keys larger than 512 bits.
110 * - TRUSTED_ENVIRONMENT IKeymasterDevices must support MD-5, SHA1, SHA-2-224, SHA-2-256,
111 * SHA-2-384 and SHA-2-512. STRONGBOX IKeymasterDevices must support SHA-2-256.
112 *
113 * == Key Access Control ==
114 *
115 * Hardware-based keys that can never be extracted from the device don't provide much security if an
116 * attacker can use them at will (though they're more secure than keys which can be
117 * exfiltrated). Therefore, IKeymasterDevice must enforce access controls.
118 *
119 * Access controls are defined as an "authorization list" of tag/value pairs. Authorization tags
120 * are 32-bit integers from the Tag enum, and the values are a variety of types, defined in the
121 * TagType enum. Some tags may be repeated to specify multiple values. Whether a tag may be
122 * repeated is specified in the documentation for the tag and in the TagType. When a key is created
123 * or imported, the caller specifies an authorization list. The IKeymasterDevice must divide the
124 * caller-provided authorizations into two lists, those it enforces in hardware and those it does
125 * not. These two lists are returned as the "hardwareEnforced" and "softwareEnforced" elements of
126 * the KeyCharacteristics struct. The IKeymasterDevice must also add the following authorizations
127 * to the appropriate list:
128 *
129 * o Tag::OS_VERSION, must be hardware-enforced.
130 * o Tag::OS_PATCHLEVEL, must be hardware-enforced.
131 * o Tag::VENDOR_PATCHLEVEL, must be hardware-enforced.
132 * o Tag::BOOT_PATCHLEVEL, must be hardware-enforced.
133 * o Tag::CREATION_DATETIME, must be software-enforced, unless the IKeymasterDevice has access to
134 * a secure time service.
135 * o Tag::ORIGIN, must be hardware-enforced.
136 *
137 * The IKeymasterDevice must accept arbitrary, unknown tags and return them in the softwareEnforced
138 * list.
139 *
140 * All authorization tags and their values, both hardwareEnforced and softwareEnforced, including
141 * unknown tags, must be cryptographically bound to the private/secret key material such that any
142 * modification of the portion of the key blob that contains the authorization list makes it
143 * impossible for the secure environment to obtain the private/secret key material. The recommended
144 * approach to meet this requirement is to use the full set of authorization tags associated with a
145 * key as input to a secure key derivation function used to derive a key that is used to encrypt the
146 * private/secret key material.
147 *
148 * IKeymasterDevice implementations must place any tags they cannot fully and completely enforce in
149 * the softwareEnforced list. For example, Tag::ORIGINATION_EXPIRE_DATETIME provides the date and
150 * time after which a key may not be used to encrypt or sign new messages. Unless the
151 * IKeymasterDevice has access to a secure source of current date/time information, it is not
152 * possible for the IKeymasterDevice to enforce this tag. An IKeymasterDevice implementation may
153 * not rely on the non-secure world's notion of time, because it could be controlled by an attacker.
154 * Similarly, it cannot rely on GPSr time, even if it has exclusive control of the GPSr, because
155 * that might be spoofed by attacker RF signals.
156 *
157 * It is recommended that IKeymasterDevices not enforce any tags they place in the softwareEnforced
158 * list. The IKeymasterDevice caller must enforce them, and it is unnecessary to enforce them
159 * twice.
160 *
161 * Some tags must be enforced by the IKeymasterDevice. See the detailed documentation on each Tag
162 * in types.hal.
163 *
164 * == Root of Trust Binding ==
165 *
166 * IKeymasterDevice keys must be bound to a root of trust, which is a bitstring that must be
167 * provided to the secure environment (by an unspecified, implementation-defined mechanism) during
168 * startup, preferably by the bootloader. This bitstring must be cryptographically bound to every
169 * key managed by the IKeymasterDevice. As above, the recommended mechanism for this cryptographic
170 * binding is to include the Root of Trust data in the input to the key derivation function used to
171 * derive a key that is used to encryp the private/secret key material.
172 *
173 * The root of trust consists of a bitstring that must be derived from the public key used by
174 * Verified Boot to verify the signature on the boot image and from the the lock state of the
175 * device. If the public key is changed to allow a different system image to be used or if the lock
176 * state is changed, then all of the IKeymasterDevice-protected keys created by the previous system
177 * state must be unusable, unless the previous state is restored. The goal is to increase the value
178 * of the software-enforced key access controls by making it impossible for an attacker-installed
179 * operating system to use IKeymasterDevice keys.
180 *
181 * == Version Binding ==
182 *
183 * All keys must also be bound to the operating system and patch level of the system image and the
184 * patch levels of the vendor image and boot image. This ensures that an attacker who discovers a
185 * weakness in an old version of the software cannot roll a device back to the vulnerable version
186 * and use keys created with the newer version. In addition, when a key with a given version and
187 * patch level is used on a device that has been upgraded to a newer version or patch level, the key
188 * must be upgraded (See IKeymasterDevice::upgradeKey()) before it can be used, and the previous
189 * version of the key must be invalidated. In this way, as the device is upgraded, the keys will
190 * "ratchet" forward along with the device, but any reversion of the device to a previous release
191 * will cause the keys to be unusable.
192 *
193 * This version information must be associated with every key as a set of tag/value pairs in the
194 * hardwareEnforced authorization list. Tag::OS_VERSION, Tag::OS_PATCHLEVEL,
195 * Tag::VENDOR_PATCHLEVEL, and Tag::BOOT_PATCHLEVEL must be cryptographically bound to every
196 * IKeymasterDevice key, as described in the Key Access Control section above.
25 */ 197 */
198
26interface IKeymasterDevice { 199interface IKeymasterDevice {
27 200
28 /** 201 /**
29 * Returns information about the underlying Keymaster hardware. 202 * Returns information about the underlying IKeymasterDevice hardware.
30 * 203 *
31 * @return security level of the Keymaster implementation accessed through this HAL. 204 * @return security level of the IKeymasterDevice implementation accessed through this HAL.
32 * 205 *
33 * @return keymasterName is the name of the Keymaster implementation. 206 * @return keymasterName is the name of the IKeymasterDevice implementation.
34 * 207 *
35 * @return keymasterAuthorName is the name of the author of the Keymaster implementation 208 * @return keymasterAuthorName is the name of the author of the IKeymasterDevice implementation
36 * (organization name, not individual). 209 * (organization name, not individual).
37 */ 210 */
38 getHardwareInfo() 211 getHardwareInfo()
39 generates (SecurityLevel securityLevel, string keymasterName, string keymasterAuthorName); 212 generates (SecurityLevel securityLevel, string keymasterName, string keymasterAuthorName);
40 213
41 /** 214 /**
42 * Start the creation of an HMAC key, shared with another Keymaster implementation. Any device 215 * Start the creation of an HMAC key, shared with another IKeymasterDevice implementation. Any
43 * with a StrongBox Keymaster has two Keymaster instances, because there must be a TEE Keymaster 216 * device with a StrongBox IKeymasterDevice has two IKeymasterDevice instances, because there
44 * as well. The HMAC key used to MAC and verify authentication tokens must be shared between 217 * must be a TEE Keymaster as well. The HMAC key used to MAC and verify authentication tokens
45 * TEE and StrongBox so they can each validate tokens produced by the other. This method is the 218 * (HardwareAuthToken, VerificationToken and ConfirmationToken all use this HMAC key) must be
46 * first step in the process for for agreeing on a shared key. It is called by Keystore during 219 * shared between TEE and StrongBox so they can each validate tokens produced by the other.
47 * startup if and only if Keystore loads multiple Keymaster HALs. Keystore calls it on each of 220 * This method is the first step in the process for for agreeing on a shared key. It is called
48 * the HAL instances and collects the results in preparation for the second step. 221 * by Android during startup. The system calls it on each of the HAL instances and collects the
222 * results in preparation for the second step.
223 *
224 * @return error ErrorCode::OK on success, ErrorCode::UNIMPLEMENTED if HMAC agreement is not
225 * implemented (note that all 4.0::IKeymasterDevice HALS must implement HMAC agreement,
226 * regardless of whether or not the HAL will be used on a device with StrongBox), or
227 * ErrorCode::UNKNOWN_ERROR if the parameters cannot be returned.
228 *
229 * @return params The HmacSharingParameters to use. As specified in the HmacSharingParameters
230 * documentation in types.hal, the seed must contain the same value in every invocation
231 * of the method on a given device, and the nonce must return the same value for every
232 * invocation during a boot session.
49 */ 233 */
50 getHmacSharingParameters() generates (ErrorCode error, HmacSharingParameters params); 234 getHmacSharingParameters() generates (ErrorCode error, HmacSharingParameters params);
51 235
52 /** 236 /**
53 * Complete the creation of an HMAC key, shared with another Keymaster implementation. Any 237 * Complete the creation of an HMAC key, shared with another IKeymasterDevice implementation.
54 * device with a StrongBox Keymaster has two Keymasters instances, because there must be a TEE 238 * Any device with a StrongBox IKeymasterDevice has two IKeymasterDevice instances, because
55 * Keymaster as well. The HMAC key used to MAC and verify authentication tokens must be shared 239 * there must be a TEE IKeymasterDevice as well. The HMAC key used to MAC and verify
56 * between TEE and StrongBox so they can each validate tokens produced by the other. This 240 * authentication tokens must be shared between TEE and StrongBox so they can each validate
57 * method is the second and final step in the process for agreeing on a shared key. It is 241 * tokens produced by the other. This method is the second and final step in the process for
58 * called by Keystore during startup if and only if Keystore loads multiple Keymaster HALs. 242 * agreeing on a shared key. It is called by Android during startup. The system calls it on
59 * Keystore calls it on each of the HAL instances, and sends to it all of the 243 * each of the HAL instances, and sends to it all of the HmacSharingParameters returned by all
60 * HmacSharingParameters returned by all HALs. 244 * HALs.
61 * 245 *
62 * This method computes the shared 32-byte HMAC ``H'' as follows (all Keymaster instances 246 * To ensure consistent ordering of the HmacSharingParameters, the caller must sort the
247 * parameters lexicographically. See the support/keymaster_utils.cpp for an operator< that
248 * defines the appropriate ordering.
249 *
250 * This method computes the shared 32-byte HMAC ``H'' as follows (all IKeymasterDevice instances
63 * perform the same computation to arrive at the same result): 251 * perform the same computation to arrive at the same result):
64 * 252 *
65 * H = CKDF(key = K, 253 * H = CKDF(key = K,
@@ -70,25 +258,27 @@ interface IKeymasterDevice {
70 * 258 *
71 * ``CKDF'' is the standard AES-CMAC KDF from NIST SP 800-108 in counter mode (see Section 259 * ``CKDF'' is the standard AES-CMAC KDF from NIST SP 800-108 in counter mode (see Section
72 * 5.1 of the referenced publication). ``key'', ``context'', and ``label'' are 260 * 5.1 of the referenced publication). ``key'', ``context'', and ``label'' are
73 * defined in the standard. The counter is prefixed, as shown in the construction on 261 * defined in the standard. The counter is prefixed and length L appended, as shown
74 * page 12 of the standard. The label string is UTF-8 encoded. 262 * in the construction on page 12 of the standard. The label string is UTF-8 encoded.
75 * 263 *
76 * ``K'' is a pre-established shared secret, set up during factory reset. The mechanism for 264 * ``K'' is a pre-established shared secret, set up during factory reset. The mechanism for
77 * establishing this shared secret is implementation-defined, but see below for a 265 * establishing this shared secret is implementation-defined, but see below for a
78 * recommended approach, which assumes that the TEE Keymaster does not have storage 266 * recommended approach, which assumes that the TEE IKeymasterDevice does not have
79 * available to it, but the StrongBox Keymaster does. 267 * storage available to it, but the StrongBox IKeymasterDevice does.
80 * 268 *
81 * <b>CRITICAL SECURITY REQUIREMENT</b>: All keys created by a Keymaster instance must 269 * CRITICAL SECURITY REQUIREMENT: All keys created by a IKeymasterDevice instance must
82 * be cryptographically bound to the value of K, such that establishing a new K 270 * be cryptographically bound to the value of K, such that establishing a new K
83 * permanently destroys them. 271 * permanently destroys them.
84 * 272 *
85 * ``||'' represents concatenation. 273 * ``||'' represents concatenation.
86 * 274 *
87 * ``Pi'' is the i'th HmacSharingParameters value in the params vector. Note that at 275 * ``Pi'' is the i'th HmacSharingParameters value in the params vector. Note that at
88 * present only two Keymaster implementations are supported, but this mechanism 276 * present only two IKeymasterDevice implementations are supported, but this mechanism
89 * extends without modification to any number of implementations. Encoding of an 277 * extends without modification to any number of implementations. Encoding of an
90 * HmacSharingParameters is the concatenation of its two fields, i.e. seed || nonce. 278 * HmacSharingParameters is the concatenation of its two fields, i.e. seed || nonce.
91 * 279 *
280 * Note that the label "KeymasterSharedMac" is the 18-byte UTF-8 encoding of the string.
281 *
92 * Process for establishing K: 282 * Process for establishing K:
93 * 283 *
94 * Any method of securely establishing K that ensures that an attacker cannot obtain or 284 * Any method of securely establishing K that ensures that an attacker cannot obtain or
@@ -98,19 +288,19 @@ interface IKeymasterDevice {
98 * have secure persistent storage. This model was chosen because StrongBox has secure 288 * have secure persistent storage. This model was chosen because StrongBox has secure
99 * persistent storage (by definition), but the TEE may not. The instance without storage is 289 * persistent storage (by definition), but the TEE may not. The instance without storage is
100 * assumed to be able to derive a unique hardware-bound key (HBK) which is used only for 290 * assumed to be able to derive a unique hardware-bound key (HBK) which is used only for
101 * this purpose, and is not derivable outside of the secure environment.. 291 * this purpose, and is not derivable outside the secure environment.
102 * 292 *
103 * In what follows, T is the Keymaster instance without storage, S is the Keymaster instance 293 * In what follows, T is the IKeymasterDevice instance without storage, S is the
104 * with storage: 294 * IKeymasterDevice instance with storage:
105 * 295 *
106 * 1. T generates an ephemeral EC P-256 key pair K1 296 * 1. T generates an ephemeral EC P-256 key pair K1.
107 * 2. T sends K1_pub to S, signed with T's attestation key. 297 * 2. T sends K1_pub to S, signed with T's attestation key.
108 * 3. S validates the signature on K1_pub. 298 * 3. S validates the signature on K1_pub.
109 * 4. S generates an ephemeral EC P-256 key pair K2. 299 * 4. S generates an ephemeral EC P-256 key pair K2.
110 * 5. S sends {K1_pub, K2_pub}, to T, signed with S's attestation key. 300 * 5. S sends {K1_pub, K2_pub}, to T, signed with S's attestation key.
111 * 6. T validates the signature on {K1_pub, K2_pub} 301 * 6. T validates the signature on {K1_pub, K2_pub}.
112 * 7. T uses {K1_priv, K2_pub} with ECDH to compute session secret Q. 302 * 7. T uses {K1_priv, K2_pub} with ECDH to compute session secret Q.
113 * 8. T generates a random seed S 303 * 8. T generates a random seed S.
114 * 9. T computes K = KDF(HBK, S), where KDF is some secure key derivation function. 304 * 9. T computes K = KDF(HBK, S), where KDF is some secure key derivation function.
115 * 10. T sends M = AES-GCM-ENCRYPT(Q, {S || K}) to S. 305 * 10. T sends M = AES-GCM-ENCRYPT(Q, {S || K}) to S.
116 * 10. S uses {K2_priv, K1_pub} with ECDH to compute session secret Q. 306 * 10. S uses {K2_priv, K1_pub} with ECDH to compute session secret Q.
@@ -121,40 +311,54 @@ interface IKeymasterDevice {
121 * T receives the computeSharedHmac call, it uses the seed provided by S to compute K. S, 311 * T receives the computeSharedHmac call, it uses the seed provided by S to compute K. S,
122 * of course, has K stored. 312 * of course, has K stored.
123 * 313 *
124 * @param params The HmacSharingParameters data returned by all Keymaster instances when 314 * @param params The HmacSharingParameters data returned by all IKeymasterDevice instances when
125 * getHmacSharingParameters was called. 315 * getHmacSharingParameters was called.
126 * 316 *
127 * @return sharingCheck A 32-byte value used to verify that all Keymaster instances have 317 * @return error ErrorCode::OK in the event that there is no error. ErrorCode::INVALID_ARGUMENT
318 * if one of the provided parameters is not the value returned by the prior call to
319 * getHmacParameters().
320 *
321 * @return sharingCheck A 32-byte value used to verify that all IKeymasterDevice instances have
128 * computed the same shared HMAC key. The sharingCheck value is computed as follows: 322 * computed the same shared HMAC key. The sharingCheck value is computed as follows:
129 * 323 *
130 * sharingCheck = HMAC(H, "Keymaster HMAC Verification") 324 * sharingCheck = HMAC(H, "Keymaster HMAC Verification")
131 * 325 *
132 * The string is UTF-8 encoded. If the returned values of all Keymaster instances don't 326 * The string is UTF-8 encoded, 27 bytes in length. If the returned values of all
133 * match, Keystore will assume that HMAC agreement failed. 327 * IKeymasterDevice instances don't match, Keystore will assume that HMAC agreement
328 * failed.
134 */ 329 */
135 computeSharedHmac(vec<HmacSharingParameters> params) 330 computeSharedHmac(vec<HmacSharingParameters> params)
136 generates (ErrorCode error, vec<uint8_t> sharingCheck); 331 generates (ErrorCode error, vec<uint8_t> sharingCheck);
137 332
138 /** 333 /**
139 * Verify authorizations for another Keymaster instance. 334 * Verify authorizations for another IKeymasterDevice instance.
140 * 335 *
141 * On systems with both a StrongBox and a TEE Keymaster instance it is sometimes useful to ask 336 * On systems with both a StrongBox and a TEE IKeymasterDevice instance it is sometimes useful
142 * the TEE Keymaster to verify authorizations for a key hosted in StrongBox. 337 * to ask the TEE IKeymasterDevice to verify authorizations for a key hosted in StrongBox.
143 * 338 *
144 * For every StrongBox operation, Keystore is required to call this method on the TEE Keymaster, 339 * For every StrongBox operation, Keystore is required to call this method on the TEE Keymaster,
145 * passing in the StrongBox key's hardwareEnforced authorization list and the operation handle 340 * passing in the StrongBox key's hardwareEnforced authorization list and the operation handle
146 * returned by StrongBox begin(). The TEE Keymaster must validate all of the authorizations it 341 * returned by StrongBox begin(). The TEE IKeymasterDevice must validate all of the
147 * can and return those it validated in the VerificationToken. If it cannot verify any, the 342 * authorizations it can and return those it validated in the VerificationToken. If it cannot
148 * parametersVerified field of the VerificationToken must be empty. Keystore must then pass the 343 * verify any, the parametersVerified field of the VerificationToken must be empty. Keystore
149 * VerificationToken to the subsequent invocations of StrongBox update() and finish(). 344 * must then pass the VerificationToken to the subsequent invocations of StrongBox update() and
345 * finish().
150 * 346 *
151 * StrongBox implementations must return ErrorCode::UNIMPLEMENTED. 347 * StrongBox implementations must return ErrorCode::UNIMPLEMENTED.
152 * 348 *
153 * @param operationHandle the operation handle returned by StrongBox Keymaster's begin(). 349 * @param operationHandle the operation handle returned by StrongBox Keymaster's begin().
154 * 350 *
155 * @param parametersToVerify Set of authorizations to verify. 351 * @param parametersToVerify Set of authorizations to verify. The caller may provide an empty
352 * vector if the only required information is the TEE timestamp.
156 * 353 *
157 * @param authToken A HardwareAuthToken if needed to authorize key usage. 354 * @param authToken A HardwareAuthToken if needed to authorize key usage.
355 *
356 * @return error ErrorCode::OK on success or ErrorCode::UNIMPLEMENTED if the IKeymasterDevice is
357 * a StrongBox. If the IKeymasterDevice cannot verify one or more elements of
358 * parametersToVerify it must not return an error code, but just omit the unverified
359 * parameter from the VerificationToken.
360 *
361 * @return token the verification token. See VerificationToken in types.hal for details.
158 */ 362 */
159 verifyAuthorization(uint64_t operationHandle, vec<KeyParameter> parametersToVerify, 363 verifyAuthorization(uint64_t operationHandle, vec<KeyParameter> parametersToVerify,
160 HardwareAuthToken authToken) 364 HardwareAuthToken authToken)
@@ -162,53 +366,143 @@ interface IKeymasterDevice {
162 366
163 367
164 /** 368 /**
165 * Adds entropy to the RNG used by Keymaster. Entropy added through this method is guaranteed 369 * Adds entropy to the RNG used by Keymaster. Entropy added through this method must not be the
166 * not to be the only source of entropy used, and the mixing function is required to be secure, 370 * only source of entropy used, and a secure mixing function must be used to mix the entropy
167 * in the sense that if the RNG is seeded (from any source) with any data the attacker cannot 371 * provided by this method with internally-generated entropy. The mixing function must be
168 * predict (or control), then the RNG output is indistinguishable from random. Thus, if the 372 * secure in the sense that if any one of the mixing function inputs is provided with any data
169 * entropy from any source is good, the output must be good. 373 * the attacker cannot predict (or control), then the output of the seeded CRNG is
170 * 374 * indistinguishable from random. Thus, if the entropy from any source is good, the output must
171 * @param data Bytes to be mixed into the RNG. 375 * be good.
172 * 376 *
173 * @return error See the ErrorCode enum in types.hal. 377 * @param data Bytes to be mixed into the CRNG seed. The caller must not provide more than 2
378 * KiB of data per invocation.
379 *
380 * @return error ErrorCode::OK on success; ErrorCode::INVALID_INPUT_LENGTH if the caller
381 * provides more than 2 KiB of data.
174 */ 382 */
175 addRngEntropy(vec<uint8_t> data) generates (ErrorCode error); 383 addRngEntropy(vec<uint8_t> data) generates (ErrorCode error);
176 384
177 /** 385 /**
178 * Generates a key, or key pair, returning a key blob and a description of the key. 386 * Generates a new cryptographic key, specifying associated parameters, which must be
387 * cryptographically bound to the key. IKeymasterDevice implementations must disallow any use
388 * of a key in any way inconsistent with the authorizations specified at generation time. With
389 * respect to parameters that the secure environment cannot enforce, the secure envionment's
390 * obligation is limited to ensuring that the unenforceable parameters associated with the key
391 * cannot be modified, so that every call to getKeyCharacteristics returns the original
392 * values. In addition, the characteristics returned by generateKey places parameters correctly
393 * in the hardware-enforced and software-enforced lists. See getKeyCharacteristics for more
394 * details.
179 * 395 *
180 * @param keyParams Key generation parameters are defined as Keymaster tag/value pairs, provided 396 * In addition to the parameters provided, generateKey must add the following to the returned
181 * in params. See Tag in types.hal for the full list. 397 * characteristics.
182 * 398 *
183 * @return error See the ErrorCode enum in types.hal. 399 * o Tag::ORIGIN with the value KeyOrigin::GENERATED.
184 * 400 *
185 * @return keyBlob Opaque, encrypted descriptor of the generated key. A recommended 401 * o Tag::BLOB_USAGE_REQUIREMENTS with the appropriate value (see KeyBlobUsageRequirements in
186 * implementation strategy is to include an encrypted copy of the key material, wrapped 402 * types.hal).
187 * in a key unavailable outside secure hardware.
188 * 403 *
189 * @return keyCharacteristics Description of the generated key. See KeyCharacteristis in 404 * o Tag::CREATION_DATETIME with the appropriate value. Note that it is expected that this will
190 * types.hal. 405 * generally be added by the HAL, not by the secure environment, and that it will be in the
406 * software-enforced list. It must be cryptographically bound to the key, like all tags.
407 *
408 * o Tag::OS_VERSION, Tag::OS_PATCHLEVEL, Tag::VENDOR_PATCHLEVEL and Tag::BOOT_PATCHLEVEL with
409 * appropriate values.
410 *
411 * The parameters provided to generateKey depend on the type of key being generated. This
412 * section summarizes the necessary and optional tags for each type of key. Tag::ALGORITHM is
413 * always necessary, to specify the type.
414 *
415 * == RSA Keys ==
416 *
417 * The following parameters are required to generate an RSA key:
418 *
419 * o Tag::Key_SIZE specifies the size of the public modulus, in bits. If omitted, generateKey
420 * must return ErrorCode::UNSUPPORTED_KEY_SIZE. Required values for TEE IKeymasterDevice
421 * implementations are 1024, 2048, 3072 and 4096. StrongBox IKeymasterDevice implementations
422 * must support 2048.
423 *
424 * o Tag::RSA_PUBLIC_EXPONENT specifies the RSA public exponent value. If omitted, generateKey
425 * must return ErrorCode::INVALID_ARGUMENT. The values 3 and 65537 must be supported. It is
426 * recommended to support all prime values up to 2^64. If provided with a non-prime value,
427 * generateKey must return ErrorCode::INVALID_ARGUMENT.
428 *
429 * The following parameters are not necessary to generate a usable RSA key, but generateKey must
430 * not return an error if they are omitted:
431 *
432 * o Tag::PURPOSE specifies allowed purposes. All KeyPurpose values (see types.hal) must be
433 * supported for RSA keys.
434 *
435 * o Tag::DIGEST specifies digest algorithms that may be used with the new key. TEE
436 * IKeymasterDevice implementatiosn must support all Digest values (see types.hal) for RSA
437 * keys. StrongBox IKeymasterDevice implementations must support SHA_2_256.
438 *
439 * o Tag::PADDING specifies the padding modes that may be used with the new
440 * key. IKeymasterDevice implementations must support PaddingMode::NONE,
441 * PaddingMode::RSA_OAEP, PaddingMode::RSA_PSS, PaddingMode::RSA_PKCS1_1_5_ENCRYPT and
442 * PaddingMode::RSA_PKCS1_1_5_SIGN for RSA keys.
443 *
444 * == ECDSA Keys ==
445 *
446 * Either Tag::KEY_SIZE or Tag::EC_CURVE must be provided to generate an ECDSA key. If neither
447 * is provided, generateKey must return ErrorCode::UNSUPPORTED_KEY_SIZE. If Tag::KEY_SIZE is
448 * provided, the possible values are 224, 256, 384 and 521, and must be mapped to Tag::EC_CURVE
449 * values P_224, P_256, P_384 and P_521, respectively. TEE IKeymasterDevice implementations
450 * must support all curves. StrongBox implementations must support P_256.
451 *
452 * == AES Keys ==
453 *
454 * Only Tag::KEY_SIZE is required to generate an AES key. If omitted, generateKey must return
455 * ErrorCode::UNSUPPORTED_KEY_SIZE. 128 and 256-bit key sizes must be supported.
456 *
457 * If Tag::BLOCK_MODE is specified with value BlockMode::GCM, then the caller must also provide
458 * Tag::MIN_MAC_LENGTH. If omitted, generateKey must return ErrorCode::MISSING_MIN_MAC_LENGTH.
459 *
460 *
461 * @param keyParams Key generation parameters are defined as IKeymasterDevice tag/value pairs,
462 * provided in params. See above for detailed specifications of which tags are required
463 * for which types of keys.
464 *
465 * @return keyBlob Opaque descriptor of the generated key. The recommended implementation
466 * strategy is to include an encrypted copy of the key material, wrapped in a key
467 * unavailable outside secure hardware.
468 *
469 * @return keyCharacteristics Description of the generated key. See the getKeyCharacteristics
470 * method below.
191 */ 471 */
192 generateKey(vec<KeyParameter> keyParams) 472 generateKey(vec<KeyParameter> keyParams)
193 generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 473 generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics);
194 474
195 /** 475 /**
196 * Imports a key, or key pair, returning a key blob and/or a description of the key. 476 * Imports key material into an IKeymasterDevice. Key definition parameters and return values
477 * are the same as for generateKey, with the following exceptions:
197 * 478 *
198 * @param keyParams Key generation parameters are defined as Keymaster tag/value pairs, provided 479 * o Tag::KEY_SIZE is not necessary in the input parameters. If not provided, the
199 * in params. See Tag for the full list. 480 * IKeymasterDevice must deduce the value from the provided key material and add the tag and
481 * value to the key characteristics. If Tag::KEY_SIZE is provided, the IKeymasterDevice must
482 * validate it against the key material. In the event of a mismatch, importKey must return
483 * ErrorCode::IMPORT_PARAMETER_MISMATCH.
200 * 484 *
201 * @param keyFormat The format of the key material to import. 485 * o Tag::RSA_PUBLIC_EXPONENT (for RSA keys only) is not necessary in the input parameters. If
486 * not provided, the IKeymasterDevice must deduce the value from the provided key material and
487 * add the tag and value to the key characteristics. If Tag::RSA_PUBLIC_EXPONENT is provided,
488 * the IKeymasterDevice must validate it against the key material. In the event of a
489 * mismatch, importKey must return ErrorCode::IMPORT_PARAMETER_MISMATCH.
202 * 490 *
203 * @pram keyData The key material to import, in the format specifed in keyFormat. 491 * o Tag::ORIGIN (returned in keyCharacteristics) must have the value KeyOrigin::IMPORTED.
204 * 492 *
205 * @return error See the ErrorCode enum. 493 * @param keyParams Key generation parameters are defined as IKeymasterDevice tag/value pairs,
494 * provided in params.
206 * 495 *
207 * @return keyBlob Opaque, encrypted descriptor of the generated key, which will generally 496 * @param keyFormat The format of the key material to import. See KeyFormat in types.hal.
208 * contain a copy of the key material, wrapped in a key unavailable outside secure
209 * hardware.
210 * 497 *
211 * @return keyCharacteristics Decription of the generated key. 498 * @pram keyData The key material to import, in the format specifed in keyFormat.
499 *
500 * @return keyBlob Opaque descriptor of the imported key. The recommended implementation
501 * strategy is to include an encrypted copy of the key material, wrapped in a key
502 * unavailable outside secure hardware.
503 *
504 * @return keyCharacteristics Decription of the generated key. See the getKeyCharacteristics
505 * method below.
212 */ 506 */
213 importKey(vec<KeyParameter> keyParams, KeyFormat keyFormat, vec<uint8_t> keyData) 507 importKey(vec<KeyParameter> keyParams, KeyFormat keyFormat, vec<uint8_t> keyData)
214 generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 508 generates (ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics);
@@ -241,10 +535,10 @@ interface IKeymasterDevice {
241 * o keyParams is the characteristics of the key to be imported (as with generateKey or 535 * o keyParams is the characteristics of the key to be imported (as with generateKey or
242 * importKey). If the secure import is successful, these characteristics must be 536 * importKey). If the secure import is successful, these characteristics must be
243 * associated with the key exactly as if the key material had been insecurely imported 537 * associated with the key exactly as if the key material had been insecurely imported
244 * with the @3.0::IKeymasterDevice::importKey. 538 * with the @3.0::IKeymasterDevice::importKey. See attestKey() for documentation of the
539 * AuthorizationList schema.
245 * o encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted 540 * o encryptedTransportKey is a 256-bit AES key, XORed with a masking key and then encrypted
246 * in RSA-OAEP mode (SHA-256 digest, SHA-1 MGF1 digest) with the wrapping key specified by 541 * with the wrapping key specified by wrappingKeyBlob.
247 * wrappingKeyBlob.
248 * o keyDescription is a KeyDescription, above. 542 * o keyDescription is a KeyDescription, above.
249 * o encryptedKey is the key material of the key to be imported, in format keyFormat, and 543 * o encryptedKey is the key material of the key to be imported, in format keyFormat, and
250 * encrypted with encryptedEphemeralKey in AES-GCM mode, with the DER-encoded 544 * encrypted with encryptedEphemeralKey in AES-GCM mode, with the DER-encoded
@@ -266,10 +560,7 @@ interface IKeymasterDevice {
266 * that the origin tag should be set to SECURELY_IMPORTED. 560 * that the origin tag should be set to SECURELY_IMPORTED.
267 * 561 *
268 * @param wrappingKeyBlob The opaque key descriptor returned by generateKey() or importKey(). 562 * @param wrappingKeyBlob The opaque key descriptor returned by generateKey() or importKey().
269 * This key must have been created with Purpose::WRAP_KEY, and must be a key algorithm 563 * This key must have been created with Purpose::WRAP_KEY.
270 * that supports encryption and must be at least as strong (in key size) as the key to be
271 * imported (per NIST key length recommendations: 112 bits symmetric is equivalent to
272 * 2048-bit RSA or 224-bit EC, 128 bits symmetric ~ 3072-bit RSA or 256-bit EC, etc.).
273 * 564 *
274 * @param maskingKey The 32-byte value XOR'd with the transport key in the SecureWrappedKey 565 * @param maskingKey The 32-byte value XOR'd with the transport key in the SecureWrappedKey
275 * structure. 566 * structure.
@@ -291,8 +582,6 @@ interface IKeymasterDevice {
291 * If the wrappedKeyData does not contain such a tag and value, this argument must be 582 * If the wrappedKeyData does not contain such a tag and value, this argument must be
292 * ignored. 583 * ignored.
293 * 584 *
294 * @return error See the ErrorCode enum.
295 *
296 * @return keyBlob Opaque descriptor of the imported key. It is recommended that the keyBlob 585 * @return keyBlob Opaque descriptor of the imported key. It is recommended that the keyBlob
297 * contain a copy of the key material, wrapped in a key unavailable outside secure 586 * contain a copy of the key material, wrapped in a key unavailable outside secure
298 * hardware. 587 * hardware.
@@ -303,10 +592,18 @@ interface IKeymasterDevice {
303 generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics); 592 generates(ErrorCode error, vec<uint8_t> keyBlob, KeyCharacteristics keyCharacteristics);
304 593
305 /** 594 /**
306 * Returns the characteristics of the specified key, if the keyBlob is valid (implementations 595 * Returns parameters associated with the provided key, divided into two sets: hardware-enforced
307 * must fully validate the integrity of the key). 596 * and software-enforced. The description here applies equally to the key characteristics lists
597 * returned by generateKey, importKey and importWrappedKey. The characteristics returned by
598 * this method completely describe the type and usage of the specified key.
308 * 599 *
309 * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); 600 * The rule that IKeymasterDevice implementations must use for deciding whether a given tag
601 * belongs in the hardware-enforced or software-enforced list is that if the meaning of the tag
602 * is fully assured by secure hardware, it is hardware enforced. Otherwise, it's software
603 * enforced.
604 *
605 *
606 * @param keyBlob The opaque descriptor returned by generateKey, importKey or importWrappedKey.
310 * 607 *
311 * @param clientId An opaque byte string identifying the client. This value must match the 608 * @param clientId An opaque byte string identifying the client. This value must match the
312 * Tag::APPLICATION_ID data provided during key generation/import. Without the correct 609 * Tag::APPLICATION_ID data provided during key generation/import. Without the correct
@@ -318,9 +615,7 @@ interface IKeymasterDevice {
318 * value, it must be computationally infeasible for the secure hardware to obtain the key 615 * value, it must be computationally infeasible for the secure hardware to obtain the key
319 * material. 616 * material.
320 * 617 *
321 * @return error See the ErrorCode enum in types.hal. 618 * @return keyCharacteristics Decription of the generated key. See KeyCharacteristics in
322 *
323 * @return keyCharacteristics Decription of the generated key. See KeyCharacteristis in
324 * types.hal. 619 * types.hal.
325 */ 620 */
326 getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData) 621 getKeyCharacteristics(vec<uint8_t> keyBlob, vec<uint8_t> clientId, vec<uint8_t> appData)
@@ -344,8 +639,6 @@ interface IKeymasterDevice {
344 * value, it must be computationally infeasible for the secure hardware to obtain the key 639 * value, it must be computationally infeasible for the secure hardware to obtain the key
345 * material. 640 * material.
346 * 641 *
347 * @return error See the ErrorCode enum in types.hal.
348 *
349 * @return keyMaterial The public key material in PKCS#8 format. 642 * @return keyMaterial The public key material in PKCS#8 format.
350 */ 643 */
351 exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId, 644 exportKey(KeyFormat keyFormat, vec<uint8_t> keyBlob, vec<uint8_t> clientId,
@@ -353,56 +646,191 @@ interface IKeymasterDevice {
353 646
354 /** 647 /**
355 * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in 648 * Generates a signed X.509 certificate chain attesting to the presence of keyToAttest in
356 * Keymaster. The certificate must contain an extension with OID 1.3.6.1.4.1.11129.2.1.17 and 649 * Keymaster.
357 * value defined in: 650 *
358 * 651 * The certificates in the chain must be ordered such that each certificate is signed by the
359 * https://developer.android.com/training/articles/security-key-attestation.html. 652 * subsequent one, up to the root which must be self-signed. The first certificate in the chain
653 * signs the public key info of the attested key and must contain the following entries (see RFC
654 * 5280 for details on each):
655 *
656 * o version -- with value 2
657 *
658 * o serialNumber -- with value 1 (same value for all keys)
659 *
660 * o signature -- contains an the AlgorithmIdentifier of the algorithm used to sign, must be
661 * ECDSA for EC keys, RSA for RSA keys.
662 *
663 * o issuer -- must contain the same value as the Subject field of the next certificate.
664 *
665 * o validity -- SEQUENCE of two dates, containing the values of Tag::ACTIVE_DATETIME and
666 * Tag::USAGE_EXPIRE_DATETIME. The tag values are in milliseconds since Jan 1, 1970; see RFD
667 * 5280 for the correct representation in certificates. If Tag::ACTIVE_DATETIME is not
668 * present in the key, the IKeymasterDevice must use the value of Tag::CREATION_DATETIME. If
669 * Tag::USAGE_EXPIRE_DATETIME is not present, the IKeymasterDevice must use the expiration
670 * date of the batch attestation certificate (see below).
671 *
672 * o subject -- CN="Android Keystore Key" (same value for all keys)
673 *
674 * o subjectPublicKeyInfo -- X.509 SubjectPublicKeyInfo containing the attested public key.
675 *
676 * o Key Usage extension -- digitalSignature bit must be set iff the attested key has
677 * KeyPurpose::SIGN. dataEncipherment bit must be set iff the attested key has
678 * KeyPurpose::DECRYPT. keyEncipherment bit must be set iff the attested key has
679 * KeyPurpose::KEY_WRAP. All other bits must be clear.
680 *
681 * In addition to the above, the attestation certificate must contain an extension with OID
682 * 1.3.6.1.4.1.11129.2.1.17 and value according to the KeyDescription schema defined as:
683 *
684 * KeyDescription ::= SEQUENCE {
685 * attestationVersion INTEGER, # Value 3
686 * attestationSecurityLevel SecurityLevel, # See below
687 * keymasterVersion INTEGER, # Value 4
688 * keymasterSecurityLevel SecurityLevel, # See below
689 * attestationChallenge OCTET_STRING, # Tag::ATTESTATION_CHALLENGE from attestParams
690 * uniqueId OCTET_STRING, # Empty unless key has Tag::INCLUDE_UNIQUE_ID
691 * softwareEnforced AuthorizationList, # See below
692 * hardwareEnforced AuthorizationList, # See below
693 * }
694 *
695 * SecurityLevel ::= ENUMERATED {
696 * Software (0),
697 * TrustedEnvironment (1),
698 * StrongBox (2),
699 * }
700 *
701 * RootOfTrust ::= SEQUENCE {
702 * verifiedBootKey OCTET_STRING,
703 * deviceLocked BOOLEAN,
704 * verifiedBootState VerifiedBootState,
705 * # verifiedBootHash must contain 32-byte value that represents the state of all binaries
706 * # or other components validated by verified boot. Updating any verified binary or
707 * # component must cause this value to change.
708 * verifiedBootHash OCTET_STRING,
709 * }
710 *
711 * VerifiedBootState ::= ENUMERATED {
712 * Verified (0),
713 * SelfSigned (1),
714 * Unverified (2),
715 * Failed (3),
716 * }
717 *
718 * AuthorizationList ::= SEQUENCE {
719 * purpose [1] EXPLICIT SET OF INTEGER OPTIONAL,
720 * algorithm [2] EXPLICIT INTEGER OPTIONAL,
721 * keySize [3] EXPLICIT INTEGER OPTIONAL.
722 * blockMode [4] EXPLICIT SET OF INTEGER OPTIONAL,
723 * digest [5] EXPLICIT SET OF INTEGER OPTIONAL,
724 * padding [6] EXPLICIT SET OF INTEGER OPTIONAL,
725 * ecCurve [10] EXPLICIT INTEGER OPTIONAL,
726 * rsaPublicExponent [200] EXPLICIT INTEGER OPTIONAL,
727 * rollbackResistance [303] EXPLICIT NULL OPTIONAL,
728 * activeDateTime [400] EXPLICIT INTEGER OPTIONAL
729 * originationExpireDateTime [401] EXPLICIT INTEGER OPTIONAL
730 * usageExpireDateTime [402] EXPLICIT INTEGER OPTIONAL
731 * noAuthRequired [503] EXPLICIT NULL OPTIONAL,
732 * userAuthType [504] EXPLICIT INTEGER OPTIONAL,
733 * authTimeout [505] EXPLICIT INTEGER OPTIONAL,
734 * allowWhileOnBody [506] EXPLICIT NULL OPTIONAL,
735 * trustedUserPresenceReq [507] EXPLICIT NULL OPTIONAL,
736 * trustedConfirmationReq [508] EXPLICIT NULL OPTIONAL,
737 * unlockedDeviceReq [509] EXPLICIT NULL OPTIONAL,
738 * allApplications [600] EXPLICIT NULL OPTIONAL,
739 * applicationId [601] EXPLICIT OCTET_STRING OPTIONAL,
740 * creationDateTime [701] EXPLICIT INTEGER OPTIONAL,
741 * origin [702] EXPLICIT INTEGER OPTIONAL,
742 * rollbackResistant [703] EXPLICIT NULL OPTIONAL,
743 * rootOfTrust [704] EXPLICIT RootOfTrust OPTIONAL,
744 * osVersion [705] EXPLICIT INTEGER OPTIONAL,
745 * osPatchLevel [706] EXPLICIT INTEGER OPTIONAL,
746 * attestationChallenge [708] EXPLICIT OCTET_STRING OPTIONAL,
747 * attestationApplicationId [709] EXPLICIT OCTET_STRING OPTIONAL,
748 * attestationIdBrand [710] EXPLICIT OCTET_STRING OPTIONAL,
749 * attestationIdDevice [711] EXPLICIT OCTET_STRING OPTIONAL,
750 * attestationIdProduct [712] EXPLICIT OCTET_STRING OPTIONAL,
751 * attestationIdSerial [713] EXPLICIT OCTET_STRING OPTIONAL,
752 * attestationIdImei [714] EXPLICIT OCTET_STRING OPTIONAL,
753 * attestationIdMeid [715] EXPLICIT OCTET_STRING OPTIONAL,
754 * attestationIdManufacturer [716] EXPLICIT OCTET_STRING OPTIONAL,
755 * attestationIdModel [717] EXPLICIT OCTET_STRING OPTIONAL,
756 * vendorPatchLevel [718] EXPLICIT INTEGER OPTIONAL,
757 * bootPatchLevel [718] EXPLICIT INTEGER OPTIONAL,
758 * }
759 *
760 * The above schema is mostly a straightforward translation of the IKeymasterDevice tag/value
761 * parameter lists to ASN.1:
762 *
763 * o TagType::ENUM, TagType::UINT, TagType::ULONG and TagType::DATE tags are represented as
764 * ASN.1 INTEGER.
765 *
766 * o TagType::ENUM_REP, TagType::UINT_REP and TagType::ULONG_REP tags are represented as ASN.1
767 * SET of INTEGER.
768 *
769 * o TagType::BOOL tags are represented as ASN.1 NULL. All entries in AuthorizationList are
770 * OPTIONAL, so the presence of the tag means "true", absence means "false".
771 *
772 * o TagType::BYTES tags are represented as ASN.1 OCTET_STRING.
773 *
774 * The numeric ASN.1 tag numbers are the same values as the IKeymasterDevice Tag enum values,
775 * except with the TagType modifier stripped.
776 *
777 * The attestation certificate must be signed by a "batch" key, which must be securely
778 * pre-installed into the device, generally in the factory, and securely stored to prevent
779 * access or extraction. The batch key must be used only for signing attestation certificates.
780 * The batch attestation certificate must be signed by a chain or zero or more intermediates
781 * leading to a self-signed roots. The intermediate and root certificate signing keys must not
782 * exist anywhere on the device.
783 *
784 * == ID Attestation ==
785 *
786 * ID attestation is a special case of key attestation in which unique device ID values are
787 * included in the signed attestation certificate.
360 * 788 *
361 * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The 789 * @param keyToAttest The opaque descriptor returned by generateKey() or importKey(). The
362 * referenced key must be asymmetric. 790 * referenced key must be asymmetric.
363 * 791 *
364 * @param attestParams Parameters for the attestation, notably Tag::ATTESTATION_CHALLENGE. 792 * @param attestParams Parameters for the attestation. Must contain Tag::ATTESTATION_CHALLENGE,
365 * 793 * the value of which must be put in the attestationChallenge field of the KeyDescription
366 * @return error See the ErrorCode enum in types.hal. 794 * ASN.1 structure defined above.
367 * 795 *
368 * @return certChain The attestation certificate, and additional certificates back to the root 796 * @return certChain The attestation certificate, and additional certificates back to the root
369 * attestation certificate, which clients will need to check against a known-good value. 797 * attestation certificate, which clients will need to check against a known-good value.
798 * The certificates must be DER-encoded.
370 */ 799 */
371 attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams) 800 attestKey(vec<uint8_t> keyToAttest, vec<KeyParameter> attestParams)
372 generates (ErrorCode error, vec<vec<uint8_t>> certChain); 801 generates (ErrorCode error, vec<vec<uint8_t>> certChain);
373 802
374 /** 803 /**
375 * Upgrades an old key blob. Keys can become "old" in two ways: Keymaster can be upgraded to a 804 * Upgrades an old key blob. Keys can become "old" in two ways: IKeymasterDevice can be
376 * new version with an incompatible key blob format, or the system can be updated to invalidate 805 * upgraded to a new version with an incompatible key blob format, or the system can be updated
377 * the OS version (OS_VERSION tag), system patch level (OS_PATCHLEVEL tag), vendor patch level 806 * to invalidate the OS version (OS_VERSION tag), system patch level (OS_PATCHLEVEL tag), vendor
378 * (VENDOR_PATCH_LEVEL tag), boot patch level (BOOT_PATCH_LEVEL tag) or other, 807 * patch level (VENDOR_PATCH_LEVEL tag), boot patch level (BOOT_PATCH_LEVEL tag) or other,
379 * implementation-defined patch level (keymaster implementers are encouraged to extend this HAL 808 * implementation-defined patch level (keymaster implementers are encouraged to extend this HAL
380 * with a minor version extension to define validatable patch levels for other images; tags 809 * with a minor version extension to define validatable patch levels for other images; tags must
381 * must be defined in the implemeter's namespace, starting at 10000). In either case, 810 * be defined in the implementer's namespace, starting at 10000). In either case, attempts to
382 * attempts to use an old key blob with getKeyCharacteristics(), exportKey(), attestKey() or 811 * use an old key blob with getKeyCharacteristics(), exportKey(), attestKey() or begin() must
383 * begin() must result in Keymaster returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must 812 * result in IKeymasterDevice returning ErrorCode::KEY_REQUIRES_UPGRADE. The caller must use
384 * use this method to upgrade the key blob. 813 * this method to upgrade the key blob.
385 * 814 *
386 * If upgradeKey is asked to update a key with any version or patch level that is higher than 815 * The upgradeKey method must examine each version or patch level associated with the key. If
387 * the current system version or patch level, it must return ErrorCode::INVALID_ARGUMENT. There 816 * any one of them is higher than the corresponding current device value upgradeKey() must
388 * is one exception: it is always permissible to "upgrade" from any OS_VERSION number to 817 * return ErrorCode::INVALID_ARGUMENT. There is one exception: it is always permissible to
389 * OS_VERSION 0. For example, if the key has OS_VERSION 080001, it is permisible to upgrade the 818 * "downgrade" from any OS_VERSION number to OS_VERSION 0. For example, if the key has
390 * key if the current system version is 080100, because the new version is larger, or if the 819 * OS_VERSION 080001, it is permisible to upgrade the key if the current system version is
391 * current system version is 0, because upgrades to 0 are always allowed. If the system version 820 * 080100, because the new version is larger, or if the current system version is 0, because
392 * were 080000, however, keymaster must return ErrorCode::INVALID_ARGUMENT because that value is 821 * upgrades to 0 are always allowed. If the system version were 080000, however, keymaster must
393 * smaller than 080001. 822 * return ErrorCode::INVALID_ARGUMENT because that value is smaller than 080001. Values other
823 * than OS_VERSION must never be downgraded.
394 * 824 *
395 * Note that Keymaster versions 2 and 3 required that the system and boot images have the same 825 * Note that Keymaster versions 2 and 3 required that the system and boot images have the same
396 * patch level and OS version. This requirement is relaxed for Keymaster 4, and the OS version 826 * patch level and OS version. This requirement is relaxed for 4.0::IKeymasterDevice, and the
397 * in the boot image footer is no longer used. 827 * OS version in the boot image footer is no longer used.
398 * 828 *
399 * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey(); 829 * @param keyBlobToUpgrade The opaque descriptor returned by generateKey() or importKey();
400 * 830 *
401 * @param upgradeParams A parameter list containing any parameters needed to complete the 831 * @param upgradeParams A parameter list containing any parameters needed to complete the
402 * upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA. 832 * upgrade, including Tag::APPLICATION_ID and Tag::APPLICATION_DATA.
403 * 833 *
404 * @return error See the ErrorCode enum.
405 *
406 * @return upgradedKeyBlob A new key blob that references the same key as keyBlobToUpgrade, but 834 * @return upgradedKeyBlob A new key blob that references the same key as keyBlobToUpgrade, but
407 * is in the new format, or has the new version data. 835 * is in the new format, or has the new version data.
408 */ 836 */
@@ -416,8 +844,6 @@ interface IKeymasterDevice {
416 * unusable. 844 * unusable.
417 * 845 *
418 * @param keyBlob The opaque descriptor returned by generateKey() or importKey(); 846 * @param keyBlob The opaque descriptor returned by generateKey() or importKey();
419 *
420 * @return error See the ErrorCode enum.
421 */ 847 */
422 deleteKey(vec<uint8_t> keyBlob) generates (ErrorCode error); 848 deleteKey(vec<uint8_t> keyBlob) generates (ErrorCode error);
423 849
@@ -441,8 +867,6 @@ interface IKeymasterDevice {
441 * must never attest any device ids. 867 * must never attest any device ids.
442 * 868 *
443 * This is a NOP if device id attestation is not supported. 869 * This is a NOP if device id attestation is not supported.
444 *
445 * @return error See the ErrorCode enum.
446 */ 870 */
447 destroyAttestationIds() generates (ErrorCode error); 871 destroyAttestationIds() generates (ErrorCode error);
448 872
@@ -452,12 +876,180 @@ interface IKeymasterDevice {
452 * to update(), finish() or abort(). 876 * to update(), finish() or abort().
453 * 877 *
454 * It is critical that each call to begin() be paired with a subsequent call to finish() or 878 * It is critical that each call to begin() be paired with a subsequent call to finish() or
455 * abort(), to allow the Keymaster implementation to clean up any internal operation state. The 879 * abort(), to allow the IKeymasterDevice implementation to clean up any internal operation
456 * caller's failure to do this may leak internal state space or other internal resources and may 880 * state. The caller's failure to do this may leak internal state space or other internal
457 * eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it runs out of space 881 * resources and may eventually cause begin() to return ErrorCode::TOO_MANY_OPERATIONS when it
458 * for operations. Any result other than ErrorCode::OK from begin(), update() or finish() 882 * runs out of space for operations. Any result other than ErrorCode::OK from begin(), update()
459 * implicitly aborts the operation, in which case abort() need not be called (and must return 883 * or finish() implicitly aborts the operation, in which case abort() need not be called (and
460 * ErrorCode::INVALID_OPERATION_HANDLE if called). 884 * must return ErrorCode::INVALID_OPERATION_HANDLE if called). IKeymasterDevice implementations
885 * must support 16 concurrent operations.
886 *
887 * If Tag::APPLICATION_ID or Tag::APPLICATION_DATA were specified during key generation or
888 * import, calls to begin must include those tags with the originally-specified values in the
889 * inParams argument to this method. If not, begin() must return ErrorCode::INVALID_KEY_BLOB.
890 *
891 * == Authorization Enforcement ==
892 *
893 * The following key authorization parameters must be enforced by the IKeymasterDevice secure
894 * environment if the tags were returned in the "hardwareEnforced" list in the
895 * KeyCharacteristics. Public key operations, meaning KeyPurpose::ENCRYPT and
896 * KeyPurpose::VERIFY must be allowed to succeed even if authorization requirements are not met.
897 *
898 * -- All Key Types --
899 *
900 * The tags in this section apply to all key types. See below for additional key type-specific
901 * tags.
902 *
903 * o Tag::PURPOSE: The purpose specified in the begin() call must match one of the purposes in
904 * the key authorizations. If the specified purpose does not match, begin() must return
905 * ErrorCode::UNSUPPORTED_PURPOSE.
906 *
907 * o Tag::ACTIVE_DATETIME can only be enforced if a trusted UTC time source is available. If
908 * the current date and time is prior to the tag value, begin() must return
909 * ErrorCode::KEY_NOT_YET_VALID.
910 *
911 * o Tag::ORIGINATION_EXPIRE_DATETIME can only be enforced if a trusted UTC time source is
912 * available. If the current date and time is later than the tag value and the purpose is
913 * KeyPurpose::ENCRYPT or KeyPurpose::SIGN, begin() must return ErrorCode::KEY_EXPIRED.
914 *
915 * o Tag::USAGE_EXPIRE_DATETIME can only be enforced if a trusted UTC time source is
916 * available. If the current date and time is later than the tag value and the purpose is
917 * KeyPurpose::DECRYPT or KeyPurpose::VERIFY, begin() must return ErrorCode::KEY_EXPIRED.
918
919 * o Tag::MIN_SECONDS_BETWEEN_OPS must be compared with a trusted relative timer indicating the
920 * last use of the key. If the last use time plus the tag value is less than the current
921 * time, begin() must return ErrorCode::KEY_RATE_LIMIT_EXCEEDED. See the tag description for
922 * important implementation details.
923
924 * o Tag::MAX_USES_PER_BOOT must be compared against a secure counter that tracks the uses of
925 * the key since boot time. If the count of previous uses exceeds the tag value, begin() must
926 * return ErrorCode::KEY_MAX_OPS_EXCEEDED.
927 *
928 * o Tag::USER_SECURE_ID must be enforced by this method if and only if the key also has
929 * Tag::AUTH_TIMEOUT (if it does not have Tag::AUTH_TIMEOUT, the Tag::USER_SECURE_ID
930 * requirement must be enforced by update() and finish()). If the key has both, then this
931 * method must receive a non-empty HardwareAuthToken in the authToken argument. For the auth
932 * token to be valid, all of the following have to be true:
933 *
934 * o The HMAC field must validate correctly.
935 *
936 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
937 * the secure ID values in the token.
938 *
939 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
940 *
941 * o The timestamp in the auth token plus the value of the Tag::AUTH_TIMEOUT must be less than
942 * the current secure timestamp (which is a monotonic timer counting milliseconds since
943 * boot.)
944 *
945 * If any of these conditions are not met, begin() must return
946 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
947 *
948 * o Tag::CALLER_NONCE allows the caller to specify a nonce or initialization vector (IV). If
949 * the key doesn't have this tag, but the caller provided Tag::NONCE to this method,
950 * ErrorCode::CALLER_NONCE_PROHIBITED must be returned.
951 *
952 * o Tag::BOOTLOADER_ONLY specifies that only the bootloader may use the key. If this method is
953 * called with a bootloader-only key after the bootloader has finished executing, it must
954 * return ErrorCode::INVALID_KEY_BLOB. The mechanism for notifying the IKeymasterDevice that
955 * the bootloader has finished executing is implementation-defined.
956 *
957 * -- RSA Keys --
958 *
959 * All RSA key operations must specify exactly one padding mode in inParams. If unspecified or
960 * specified more than once, the begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE.
961 *
962 * RSA signing and verification operations need a digest, as do RSA encryption and decryption
963 * operations with OAEP padding mode. For those cases, the caller must specify exactly one
964 * digest in inParams. If unspecified or specified more than once, begin() must return
965 * ErrorCode::UNSUPPORTED_DIGEST.
966 *
967 * Private key operations (KeyPurpose::DECRYPT and KeyPurpose::SIGN) need authorization of
968 * digest and padding, which means that the key authorizations need to contain the specified
969 * values. If not, begin() must return ErrorCode::INCOMPATIBLE_DIGEST or
970 * ErrorCode::INCOMPATIBLE_PADDING, as appropriate. Public key operations (KeyPurpose::ENCRYPT
971 * and KeyPurpose::VERIFY) are permitted with unauthorized digest or padding modes.
972 *
973 * With the exception of PaddingMode::NONE, all RSA padding modes are applicable only to certain
974 * purposes. Specifically, PaddingMode::RSA_PKCS1_1_5_SIGN and PaddingMode::RSA_PSS only
975 * support signing and verification, while PaddingMode::RSA_PKCS1_1_5_ENCRYPT and
976 * PaddingMode::RSA_OAEP only support encryption and decryption. begin() must return
977 * ErrorCode::UNSUPPORTED_PADDING_MODE if the specified mode does not support the specified
978 * purpose.
979 *
980 * There are some important interactions between padding modes and digests:
981 *
982 * o PaddingMode::NONE indicates that a "raw" RSA operation is performed. If signing or
983 * verifying, Digest::NONE is specified for the digest. No digest is necessary for unpadded
984 * encryption or decryption.
985 *
986 * o PaddingMode::RSA_PKCS1_1_5_SIGN padding requires a digest. The digest may be Digest::NONE,
987 * in which case the Keymaster implementation cannot build a proper PKCS#1 v1.5 signature
988 * structure, because it cannot add the DigestInfo structure. Instead, the IKeymasterDevice
989 * must construct 0x00 || 0x01 || PS || 0x00 || M, where M is the provided message and PS is a
990 * random padding string at least eight bytes in length. The size of the RSA key has to be at
991 * least 11 bytes larger than the message, otherwise begin() must return
992 * ErrorCode::INVALID_INPUT_LENGTH.
993 *
994 * o PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding does not require a digest.
995 *
996 * o PaddingMode::RSA_PSS padding requires a digest, which may not be Digest::NONE. If
997 * Digest::NONE is specified, the begin() must return ErrorCode::INCOMPATIBLE_DIGEST. In
998 * addition, the size of the RSA key must be at least 2 + D bytes larger than the output size
999 * of the digest, where D is the size of the digest, in bytes. Otherwise begin() must
1000 * return ErrorCode::INCOMPATIBLE_DIGEST. The salt size must be D.
1001 *
1002 * o PaddingMode::RSA_OAEP padding requires a digest, which may not be Digest::NONE. If
1003 * Digest::NONE is specified, begin() must return ErrorCode::INCOMPATIBLE_DIGEST. The OAEP
1004 * mask generation function must be MGF1 and the MGF1 digest must be SHA1, regardless of the
1005 * OAEP digest specified.
1006 *
1007 * -- EC Keys --
1008 *
1009 * EC key operations must specify exactly one padding mode in inParams. If unspecified or
1010 * specified more than once, begin() must return ErrorCode::UNSUPPORTED_PADDING_MODE.
1011 *
1012 * Private key operations (KeyPurpose::SIGN) need authorization of digest and padding, which
1013 * means that the key authorizations must contain the specified values. If not, begin() must
1014 * return ErrorCode::INCOMPATIBLE_DIGEST. Public key operations (KeyPurpose::VERIFY) are
1015 * permitted with unauthorized digest or padding.
1016 *
1017 * -- AES Keys --
1018 *
1019 * AES key operations must specify exactly one block mode (Tag::BLOCK_MODE) and one padding mode
1020 * (Tag::PADDING) in inParams. If either value is unspecified or specified more than once,
1021 * begin() must return ErrorCode::UNSUPPORTED_BLOCK_MODE or
1022 * ErrorCode::UNSUPPORTED_PADDING_MODE. The specified modes must be authorized by the key,
1023 * otherwise begin() must return ErrorCode::INCOMPATIBLE_BLOCK_MODE or
1024 * ErrorCode::INCOMPATIBLE_PADDING_MODE.
1025 *
1026 * If the block mode is BlockMode::GCM, inParams must specify Tag::MAC_LENGTH, and the specified
1027 * value must be a multiple of 8 that is not greater than 128 or less than the value of
1028 * Tag::MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than 128 or
1029 * non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For values less
1030 * than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
1031 *
1032 * If the block mode is BlockMode::GCM or BlockMode::CTR, the specified padding mode must be
1033 * PaddingMode::NONE. For BlockMode::ECB or BlockMode::CBC, the mode may be PaddingMode::NONE
1034 * or PaddingMode::PKCS7. If the padding mode doesn't meet these conditions, begin() must
1035 * return ErrorCode::INCOMPATIBLE_PADDING_MODE.
1036 *
1037 * If the block mode is BlockMode::CBC, BlockMode::CTR, or BlockMode::GCM, an initialization
1038 * vector or nonce is required. In most cases, callers shouldn't provide an IV or nonce and the
1039 * IKeymasterDevice implementation must generate a random IV or nonce and return it via
1040 * Tag::NONCE in outParams. CBC and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
1041 * authorizations contain Tag::CALLER_NONCE, then the caller may provide an IV/nonce with
1042 * Tag::NONCE in inParams. If a nonce is provided when Tag::CALLER_NONCE is not authorized,
1043 * begin() must return ErrorCode::CALLER_NONCE_PROHIBITED. If a nonce is not provided when
1044 * Tag::CALLER_NONCE is authorized, IKeymasterDevice msut generate a random IV/nonce.
1045 *
1046 * -- HMAC keys --
1047 *
1048 * HMAC key operations must specify Tag::MAC_LENGTH in inParams. The specified value must be a
1049 * multiple of 8 that is not greater than the digest length or less than the value of
1050 * Tag::MIN_MAC_LENGTH in the key authorizations. For MAC lengths greater than the digest
1051 * length or non-multiples of 8, begin() must return ErrorCode::UNSUPPORTED_MAC_LENGTH. For
1052 * values less than the key's minimum length, begin() must return ErrorCode::INVALID_MAC_LENGTH.
461 * 1053 *
462 * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT, 1054 * @param purpose The purpose of the operation, one of KeyPurpose::ENCRYPT, KeyPurpose::DECRYPT,
463 * KeyPurpose::SIGN or KeyPurpose::VERIFY. Note that for AEAD modes, encryption and 1055 * KeyPurpose::SIGN or KeyPurpose::VERIFY. Note that for AEAD modes, encryption and
@@ -466,7 +1058,7 @@ interface IKeymasterDevice {
466 * 1058 *
467 * @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key 1059 * @param keyBlob The opaque key descriptor returned by generateKey() or importKey(). The key
468 * must have a purpose compatible with purpose and all of its usage requirements must be 1060 * must have a purpose compatible with purpose and all of its usage requirements must be
469 * satisfied, or begin() must return an appropriate error code. 1061 * satisfied, or begin() must return an appropriate error code (see above).
470 * 1062 *
471 * @param inParams Additional parameters for the operation. If Tag::APPLICATION_ID or 1063 * @param inParams Additional parameters for the operation. If Tag::APPLICATION_ID or
472 * Tag::APPLICATION_DATA were provided during generation, they must be provided here, or 1064 * Tag::APPLICATION_DATA were provided during generation, they must be provided here, or
@@ -478,8 +1070,6 @@ interface IKeymasterDevice {
478 * @param authToken Authentication token. Callers that provide no token must set all numeric 1070 * @param authToken Authentication token. Callers that provide no token must set all numeric
479 * fields to zero and the MAC must be an empty vector. 1071 * fields to zero and the MAC must be an empty vector.
480 * 1072 *
481 * @return error See the ErrorCode enum in types.hal.
482 *
483 * @return outParams Output parameters. Used to return additional data from the operation 1073 * @return outParams Output parameters. Used to return additional data from the operation
484 * initialization, notably to return the IV or nonce from operations that generate an IV 1074 * initialization, notably to return the IV or nonce from operations that generate an IV
485 * or nonce. 1075 * or nonce.
@@ -493,13 +1083,87 @@ interface IKeymasterDevice {
493 1083
494 /** 1084 /**
495 * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun 1085 * Provides data to, and possibly receives output from, an ongoing cryptographic operation begun
496 * with begin(). 1086 * with begin(). The operation is specified by the operationHandle paramater.
497 * 1087 *
498 * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE. 1088 * If operationHandle is invalid, update() must return ErrorCode::INVALID_OPERATION_HANDLE.
499 * 1089 *
500 * update() may not consume all of the data provided in the data buffer. update() must return 1090 * To provide more flexibility for buffer handling, implementations of this method have the
501 * the amount consumed in inputConsumed. The caller may provide the unconsumed data in a 1091 * option of consuming less data than was provided. The caller is responsible for looping to
502 * subsequent call. 1092 * feed the rest of the data in subsequent calls. The amount of input consumed must be returned
1093 * in the inputConsumed parameter. Implementations must always consume at least one byte, unless
1094 * the operation cannot accept any more; if more than zero bytes are provided and zero bytes are
1095 * consumed, callers must consider this an error and abort the operation.
1096 *
1097 * Implementations may also choose how much data to return, as a result of the update. This is
1098 * only relevant for encryption and decryption operations, because signing and verification
1099 * return no data until finish. It is recommended to return data as early as possible, rather
1100 * than buffer it.
1101 *
1102 * If this method returns an error code other than ErrorCode::OK, the operation is aborted and
1103 * the operation handle must be invalidated. Any future use of the handle, with this method,
1104 * finish, or abort, must return ErrorCode::INVALID_OPERATION_HANDLE.
1105 *
1106 * == Authorization Enforcement ==
1107 *
1108 * Key authorization enforcement is performed primarily in begin(). The one exception is the
1109 * case where the key has:
1110
1111 * o One or more Tag::USER_SECURE_IDs, and
1112 *
1113 * o Does not have a Tag::AUTH_TIMEOUT
1114 *
1115 * In this case, the key requires an authorization per operation, and the update method must
1116 * receive a non-empty and valid HardwareAuthToken. For the auth token to be valid, all of the
1117 * following has to be true:
1118 *
1119 * o The HMAC field must validate correctly.
1120 *
1121 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
1122 * the secure ID values in the token.
1123 *
1124 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
1125 *
1126 * o The challenge field in the auth token must contain the operationHandle
1127 *
1128 * If any of these conditions are not met, update() must return
1129 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
1130 *
1131 * The caller must provide the auth token on every call to update() and finish().
1132 *
1133 * -- RSA keys --
1134 *
1135 * For signing and verification operations with Digest::NONE, this method must accept the entire
1136 * block to be signed or verified in a single update. It may not consume only a portion of the
1137 * block in these cases. However, the caller may choose to provide the data in multiple updates,
1138 * and update() must accept the data this way as well. If the caller provides more data to sign
1139 * than can be used (length of data exceeds RSA key size), update() must return
1140 * ErrorCode::INVALID_INPUT_LENGTH.
1141 *
1142 * -- ECDSA keys --
1143 *
1144 * For signing and verification operations with Digest::NONE, this method must accept the entire
1145 * block to be signed or verified in a single update. This method may not consume only a
1146 * portion of the block. However, the caller may choose to provide the data in multiple updates
1147 * and update() must accept the data this way as well. If the caller provides more data to sign
1148 * than can be used, the data is silently truncated. (This differs from the handling of excess
1149 * data provided in similar RSA operations. The reason for this is compatibility with legacy
1150 * clients.)
1151 *
1152 * -- AES keys --
1153 *
1154 * AES GCM mode supports "associated authentication data," provided via the Tag::ASSOCIATED_DATA
1155 * tag in the inParams argument. The associated data may be provided in repeated calls
1156 * (important if the data is too large to send in a single block) but must always precede data
1157 * to be encrypted or decrypted. An update call may receive both associated data and data to
1158 * encrypt/decrypt, but subsequent updates must not include associated data. If the caller
1159 * provides associated data to an update call after a call that includes data to
1160 * encrypt/decrypt, update() must return ErrorCode::INVALID_TAG.
1161 *
1162 * For GCM encryption, the AEAD tag must be appended to the ciphertext by finish(). During
1163 * decryption, the last Tag::MAC_LENGTH bytes of the data provided to the last update call must
1164 * be the AEAD tag. Since a given invocation of update cannot know if it's the last invocation,
1165 * it must process all but the tag length and buffer the possible tag data for processing during
1166 * finish().
503 * 1167 *
504 * @param operationHandle The operation handle returned by begin(). 1168 * @param operationHandle The operation handle returned by begin().
505 * 1169 *
@@ -513,16 +1177,18 @@ interface IKeymasterDevice {
513 * @param authToken Authentication token. Callers that provide no token must set all numeric 1177 * @param authToken Authentication token. Callers that provide no token must set all numeric
514 * fields to zero and the MAC must be an empty vector. 1178 * fields to zero and the MAC must be an empty vector.
515 * 1179 *
516 * @param verificationToken Verification token, used to prove that another Keymaster HAL has 1180 * @param verificationToken Verification token, used to prove that another IKeymasterDevice HAL
517 * verified some parameters, and to deliver the other HAL's current timestamp, if needed. 1181 * has verified some parameters, and to deliver the other HAL's current timestamp, if
518 * If not provided, all fields must be initialized to zero and vectors empty. 1182 * needed. If not provided, all fields must be initialized to zero and vectors must be
1183 * empty.
519 * 1184 *
520 * @return error See the ErrorCode enum in types.hal. 1185 * @return error See the ErrorCode enum in types.hal.
521 * 1186 *
522 * @return inputConsumed Amount of data that was consumed by update(). If this is less than the 1187 * @return inputConsumed Amount of data that was consumed by update(). If this is less than the
523 * amount provided, the caller may provide the remainder in a subsequent call to 1188 * amount provided, the caller may provide the remainder in a subsequent call to
524 * update() or finish(). Every call to update must consume at least one byte, and 1189 * update() or finish(). Every call to update must consume at least one byte, unless
525 * implementations should consume as much data as reasonably possible for each call. 1190 * the input is empty, and implementations should consume as much data as reasonably
1191 * possible for each call.
526 * 1192 *
527 * @return outParams Output parameters, used to return additional data from the operation. 1193 * @return outParams Output parameters, used to return additional data from the operation.
528 * 1194 *
@@ -536,6 +1202,86 @@ interface IKeymasterDevice {
536 /** 1202 /**
537 * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle. 1203 * Finalizes a cryptographic operation begun with begin() and invalidates operationHandle.
538 * 1204 *
1205 * This method is the last one called in an operation, so all processed data must be returned.
1206 *
1207 * Whether it completes successfully or returns an error, this method finalizes the operation
1208 * and therefore must invalidate the provided operation handle. Any future use of the handle,
1209 * with finish(), update(), or abort(), must return ErrorCode::INVALID_OPERATION_HANDLE.
1210 *
1211 * Signing operations return the signature as the output. Verification operations accept the
1212 * signature in the signature parameter, and return no output.
1213 *
1214 * == Authorization enforcement ==
1215 *
1216 * Key authorization enforcement is performed primarily in begin(). The exceptions are
1217 * authorization per operation keys and confirmation-required keys.
1218 *
1219 * Authorization per operation keys are the case where the key has one or more
1220 * Tag::USER_SECURE_IDs, and does not have a Tag::AUTH_TIMEOUT. In this case, the key requires
1221 * an authorization per operation, and the finish method must receive a non-empty and valid
1222 * authToken. For the auth token to be valid, all of the following has to be true:
1223 *
1224 * o The HMAC field must validate correctly.
1225 *
1226 * o At least one of the Tag::USER_SECURE_ID values from the key must match at least one of
1227 * the secure ID values in the token.
1228 *
1229 * o The key must have a Tag::USER_AUTH_TYPE that matches the auth type in the token.
1230 *
1231 * o The challenge field in the auth token must contain the operationHandle
1232 *
1233 * If any of these conditions are not met, update() must return
1234 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
1235 *
1236 * The caller must provide the auth token on every call to update() and finish().
1237 *
1238 * Confirmation-required keys are keys that were generated with
1239 * Tag::TRUSTED_CONFIRMATION_REQUIRED. For these keys, when doing a signing operation the
1240 * caller must pass a KeyParameter Tag::CONFIRMATION_TOKEN to finish(). Implementations must
1241 * check the confirmation token by computing the 32-byte HMAC-SHA256 over all of the
1242 * to-be-signed data, prefixed with the 18-byte UTF-8 encoded string "confirmation token". If
1243 * the computed value does not match the Tag::CONFIRMATION_TOKEN parameter, finish() must not
1244 * produce a signature and must return ErrorCode::NO_USER_CONFIRMATION.
1245 *
1246 * -- RSA keys --
1247 *
1248 * Some additional requirements, depending on the padding mode:
1249 *
1250 * o PaddingMode::NONE. For unpadded signing and encryption operations, if the provided data is
1251 * shorter than the key, the data must be zero-padded on the left before
1252 * signing/encryption. If the data is the same length as the key, but numerically larger,
1253 * finish() must return ErrorCode::INVALID_ARGUMENT. For verification and decryption
1254 * operations, the data must be exactly as long as the key. Otherwise, return
1255 * ErrorCode::INVALID_INPUT_LENGTH.
1256 *
1257 * o PaddingMode::RSA_PSS. For PSS-padded signature operations, the PSS salt length must match
1258 * the size of the PSS digest selected. The digest specified with Tag::DIGEST in inputParams
1259 * on begin() must be used as the PSS digest algorithm, MGF1 must be used as the mask
1260 * generation function and SHA1 must be used as the MGF1 digest algorithm.
1261 *
1262 * o PaddingMode::RSA_OAEP. The digest specified with Tag::DIGEST in inputParams on begin is
1263 * used as the OAEP digest algorithm, MGF1 must be used as the mask generation function and
1264 * and SHA1 must be used as the MGF1 digest algorithm.
1265 *
1266 * -- ECDSA keys --
1267 *
1268 * If the data provided for unpadded signing or verification is too long, truncate it.
1269 *
1270 * -- AES keys --
1271 *
1272 * Some additional conditions, depending on block mode:
1273 *
1274 * o BlockMode::ECB or BlockMode::CBC. If padding is PaddingMode::NONE and the data length is
1275 * not a multiple of the AES block size, finish() must return
1276 * ErrorCode::INVALID_INPUT_LENGTH. If padding is PaddingMode::PKCS7, pad the data per the
1277 * PKCS#7 specification, including adding an additional padding block if the data is a multiple
1278 * of the block length.
1279 *
1280 * o BlockMode::GCM. During encryption, after processing all plaintext, compute the tag
1281 * (Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption,
1282 * process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, finish()
1283 * must return ErrorCode::VERIFICATION_FAILED.
1284 *
539 * @param operationHandle The operation handle returned by begin(). This handle must be invalid 1285 * @param operationHandle The operation handle returned by begin(). This handle must be invalid
540 * when finish() returns. 1286 * when finish() returns.
541 * 1287 *
@@ -551,11 +1297,9 @@ interface IKeymasterDevice {
551 * @param authToken Authentication token. Callers that provide no token must set all numeric 1297 * @param authToken Authentication token. Callers that provide no token must set all numeric
552 * fields to zero and the MAC must be an empty vector. 1298 * fields to zero and the MAC must be an empty vector.
553 * 1299 *
554 * @param verificationToken Verification token, used to prove that another Keymaster HAL has 1300 * @param verificationToken Verification token, used to prove that another IKeymasterDevice HAL
555 * verified some parameters, and to deliver the other HAL's current timestamp, if needed. 1301 * has verified some parameters, and to deliver the other HAL's current timestamp, if
556 * If not provided, all fields must be initialized to zero and vectors empty. 1302 * needed. If not provided, all fields must be initialized to zero and vectors empty.
557 *
558 * @return error See the ErrorCode enum in types.hal.
559 * 1303 *
560 * @return outParams Any output parameters generated by finish(). 1304 * @return outParams Any output parameters generated by finish().
561 * 1305 *
diff --git a/keymaster/4.0/support/Keymaster.cpp b/keymaster/4.0/support/Keymaster.cpp
index 066bca41..444298b5 100644
--- a/keymaster/4.0/support/Keymaster.cpp
+++ b/keymaster/4.0/support/Keymaster.cpp
@@ -156,17 +156,19 @@ static void computeHmac(const Keymaster::KeymasterSet& keymasters,
156 for (auto& keymaster : keymasters) { 156 for (auto& keymaster : keymasters) {
157 if (keymaster->halVersion().majorVersion < 4) continue; 157 if (keymaster->halVersion().majorVersion < 4) continue;
158 LOG(DEBUG) << "Computing HMAC for " << *keymaster; 158 LOG(DEBUG) << "Computing HMAC for " << *keymaster;
159 auto rc = keymaster->computeSharedHmac(params, [&](auto error, auto& curSharingCheck) { 159 auto rc = keymaster->computeSharedHmac(
160 CHECK(error == ErrorCode::OK) 160 params, [&](ErrorCode error, const hidl_vec<uint8_t>& curSharingCheck) {
161 << "Failed to get HMAC parameters from " << *keymaster << " error " << error; 161 CHECK(error == ErrorCode::OK)
162 if (firstKeymaster) { 162 << "Failed to get HMAC parameters from " << *keymaster << " error " << error;
163 sharingCheck = curSharingCheck; 163 if (firstKeymaster) {
164 firstKeymaster = false; 164 sharingCheck = curSharingCheck;
165 } 165 firstKeymaster = false;
166 // TODO: Validate that curSharingCheck == sharingCheck. b/77588764 166 }
167 // CHECK(curSharingCheck == sharingCheck) << "HMAC computation failed for " << 167 CHECK(curSharingCheck == sharingCheck)
168 // *keymaster; 168 << "HMAC computation failed for " << *keymaster //
169 }); 169 << " Expected: " << sharingCheck //
170 << " got: " << curSharingCheck;
171 });
170 CHECK(rc.isOk()) << "Failed to communicate with " << *keymaster 172 CHECK(rc.isOk()) << "Failed to communicate with " << *keymaster
171 << " error: " << rc.description(); 173 << " error: " << rc.description();
172 } 174 }
diff --git a/keymaster/4.0/types.hal b/keymaster/4.0/types.hal
index 47fd1ed0..85f181ac 100644
--- a/keymaster/4.0/types.hal
+++ b/keymaster/4.0/types.hal
@@ -59,83 +59,364 @@ enum TagType : uint32_t {
59enum Tag : uint32_t { 59enum Tag : uint32_t {
60 INVALID = TagType:INVALID | 0, 60 INVALID = TagType:INVALID | 0,
61 61
62 /* 62 /**
63 * Tags that must be semantically enforced by hardware and software implementations. 63 * Tag::PURPOSE specifies the set of purposes for which the key may be used. Possible values
64 * are defined in the KeyPurpose enumeration.
65 *
66 * This tag is repeatable; keys may be generated with multiple values, although an operation has
67 * a single purpose. When begin() is called to start an operation, the purpose of the operation
68 * is specified. If the purpose specified for the operation is not authorized by the key (the
69 * key didn't have a corresponding Tag::PURPOSE provided during generation/import), the
70 * operation must fail with ErrorCode::INCOMPATIBLE_PURPOSE.
71 *
72 * Must be hardware-enforced.
73 */
74 PURPOSE = TagType:ENUM_REP | 1,
75
76 /**
77 * Tag::ALGORITHM specifies the cryptographic algorithm with which the key is used. This tag
78 * must be provided to generateKey and importKey, and must be specified in the wrapped key
79 * provided to importWrappedKey.
80 *
81 * Must be hardware-enforced.
82 */
83 ALGORITHM = TagType:ENUM | 2,
84
85 /**
86 * Tag::KEY_SIZE pecifies the size, in bits, of the key, measuring in the normal way for the
87 * key's algorithm. For example, for RSA keys, Tag::KEY_SIZE specifies the size of the public
88 * modulus. For AES keys it specifies the length of the secret key material. For 3DES keys it
89 * specifies the length of the key material, not counting parity bits (though parity bits must
90 * be provided for import, etc.). Since only three-key 3DES keys are supported, 3DES
91 * Tag::KEY_SIZE must be 168.
92 *
93 * Must be hardware-enforced.
64 */ 94 */
95 KEY_SIZE = TagType:UINT | 3,
65 96
66 /* Crypto parameters */ 97 /**
67 PURPOSE = TagType:ENUM_REP | 1, /* KeyPurpose. */ 98 * Tag::BLOCK_MODE specifies the block cipher mode(s) with which the key may be used. This tag
68 ALGORITHM = TagType:ENUM | 2, /* Algorithm. */ 99 * is only relevant to AES and 3DES keys. Possible values are defined by the BlockMode enum.
69 KEY_SIZE = TagType:UINT | 3, /* Key size in bits. */ 100 *
101 * This tag is repeatable for key generation/import. For AES and 3DES operations the caller
102 * must specify a Tag::BLOCK_MODE in the additionalParams argument of begin(). If the mode is
103 * missing or the specified mode is not in the modes specified for the key during
104 * generation/import, the operation must fail with ErrorCode::INCOMPATIBLE_BLOCK_MODE.
105 *
106 * Must be hardware-enforced.
107 */
70 BLOCK_MODE = TagType:ENUM_REP | 4, /* BlockMode. */ 108 BLOCK_MODE = TagType:ENUM_REP | 4, /* BlockMode. */
71 DIGEST = TagType:ENUM_REP | 5, /* Digest. */ 109
72 PADDING = TagType:ENUM_REP | 6, /* PaddingMode. */ 110 /**
73 CALLER_NONCE = TagType:BOOL | 7, /* Allow caller to specify nonce or IV. */ 111 * Tag::DIGEST specifies the digest algorithms that may be used with the key to perform signing
74 MIN_MAC_LENGTH = TagType:UINT | 8, /* Minimum length of MAC or AEAD authentication tag in 112 * and verification operations. This tag is relevant to RSA, ECDSA and HMAC keys. Possible
75 * bits. */ 113 * values are defined by the Digest enum.
76 // 9 reserved 114 *
77 EC_CURVE = TagType:ENUM | 10, /* EcCurve. */ 115 * This tag is repeatable for key generation/import. For signing and verification operations,
78 116 * the caller must specify a digest in the additionalParams argument of begin(). If the digest
79 /* Algorithm-specific. */ 117 * is missing or the specified digest is not in the digests associated with the key, the
118 * operation must fail with ErrorCode::INCOMPATIBLE_DIGEST.
119 *
120 * Must be hardware-enforced.
121 */
122 DIGEST = TagType:ENUM_REP | 5,
123
124 /**
125 * Tag::PADDING specifies the padding modes that may be used with the key. This tag is relevant
126 * to RSA, AES and 3DES keys. Possible values are defined by the PaddingMode enum.
127 *
128 * PaddingMode::RSA_OAEP and PaddingMode::RSA_PKCS1_1_5_ENCRYPT are used only for RSA
129 * encryption/decryption keys and specify RSA OAEP padding and RSA PKCS#1 v1.5 randomized
130 * padding, respectively. PaddingMode::RSA_PSS and PaddingMode::RSA_PKCS1_1_5_SIGN are used
131 * only for RSA signing/verification keys and specify RSA PSS padding and RSA PKCS#1 v1.5
132 * deterministic padding, respectively.
133 *
134 * PaddingMode::NONE may be used with either RSA, AES or 3DES keys. For AES or 3DES keys, if
135 * PaddingMode::NONE is used with block mode ECB or CBC and the data to be encrypted or
136 * decrypted is not a multiple of the AES block size in length, the call to finish() must fail
137 * with ErrorCode::INVALID_INPUT_LENGTH.
138 *
139 * PaddingMode::PKCS7 may only be used with AES and 3DES keys, and only with ECB and CBC modes.
140 *
141 * In any case, if the caller specifies a padding mode that is not usable with the key's
142 * algorithm, the generation or import method must return ErrorCode::INCOMPATIBLE_PADDING_MODE.
143 *
144 * This tag is repeatable. A padding mode must be specified in the call to begin(). If the
145 * specified mode is not authorized for the key, the operation must fail with
146 * ErrorCode::INCOMPATIBLE_BLOCK_MODE.
147 *
148 * Must be hardware-enforced.
149 */
150 PADDING = TagType:ENUM_REP | 6,
151
152 /**
153 * Tag::CALLER_NONCE specifies that the caller can provide a nonce for nonce-requiring
154 * operations. This tag is boolean, so the possible values are true (if the tag is present) and
155 * false (if the tag is not present).
156 *
157 * This tag is used only for AES and 3DES keys, and is only relevant for CBC, CTR and GCM block
158 * modes. If the tag is not present in a key's authorization list, implementations must reject
159 * any operation that provides Tag::NONCE to begin() with ErrorCode::CALLER_NONCE_PROHIBITED.
160 *
161 * Must be hardware-enforced.
162 */
163 CALLER_NONCE = TagType:BOOL | 7,
164
165 /**
166 * Tag::MIN_MAC_LENGTH specifies the minimum length of MAC that can be requested or verified
167 * with this key for HMAC keys and AES keys that support GCM mode.
168 *
169 * This value is the minimum MAC length, in bits. It must be a multiple of 8 bits. For HMAC
170 * keys, the value must be least 64 and no more than 512. For GCM keys, the value must be at
171 * least 96 and no more than 128. If the provided value violates these requirements,
172 * generateKey() or importKey() must return ErrorCode::UNSUPPORTED_KEY_SIZE.
173 *
174 * Must be hardware-enforced.
175 */
176 MIN_MAC_LENGTH = TagType:UINT | 8,
177
178 // Tag 9 reserved
179
180 /**
181 * Tag::EC_CURVE specifies the elliptic curve. EC key generation requests may have
182 * Tag:EC_CURVE, Tag::KEY_SIZE, or both. If both are provided and the size and curve do not
183 * match, IKeymasterDevice must return ErrorCode::INVALID_ARGUMENT.
184 *
185 * Must be hardware-enforced.
186 */
187 EC_CURVE = TagType:ENUM | 10,
188
189 /**
190 * Tag::RSA_PUBLIC_EXPONENT specifies the value of the public exponent for an RSA key pair.
191 * This tag is relevant only to RSA keys, and is required for all RSA keys.
192 *
193 * The value is a 64-bit unsigned integer that satisfies the requirements of an RSA public
194 * exponent. This value must be a prime number. IKeymasterDevice implementations must support
195 * the value 2^16+1 and may support other reasonable values. If no exponent is specified or if
196 * the specified exponent is not supported, key generation must fail with
197 * ErrorCode::INVALID_ARGUMENT.
198 *
199 * Must be hardware-enforced.
200 */
80 RSA_PUBLIC_EXPONENT = TagType:ULONG | 200, 201 RSA_PUBLIC_EXPONENT = TagType:ULONG | 200,
81 // 201 reserved for ECIES 202
82 INCLUDE_UNIQUE_ID = TagType:BOOL | 202, /* If true, attestation certificates for this key must 203 // Tag 201 reserved
83 * contain an application-scoped and time-bounded 204
84 * device-unique ID.*/ 205 /**
85 206 * Tag::INCLUDE_UNIQUE_ID is specified during key generation to indicate that an attestation
86 /* Other hardware-enforced. */ 207 * certificate for the generated key should contain an application-scoped and time-bounded
87 BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301, /* KeyBlobUsageRequirements. */ 208 * device-unique ID. See Tag::UNIQUE_ID.
88 BOOTLOADER_ONLY = TagType:BOOL | 302, /* Usable only by bootloader. */ 209 *
89 ROLLBACK_RESISTANCE = TagType:BOOL | 303, /* Whether key is rollback-resistant. Specified 210 * Must be hardware-enforced.
90 * in the key description provided to generateKey 211 */
91 * or importKey if rollback resistance is desired. 212 INCLUDE_UNIQUE_ID = TagType:BOOL | 202,
92 * If the implementation cannot provide rollback 213
93 * resistance, it must return 214 /**
94 * ROLLBACK_RESISTANCE_UNAVAILABLE. */ 215 * Tag::BLOB_USAGE_REQUIREMENTS specifies the necessary system environment conditions for the
95 216 * generated key to be used. Possible values are defined by the KeyBlobUsageRequirements enum.
96 /* HARDWARE_TYPE specifies the type of the secure hardware that is requested for the key 217 *
97 * generation / import. See the SecurityLevel enum. In the absence of this tag, keystore must 218 * This tag is specified by the caller during key generation or import to require that the key
98 * use TRUSTED_ENVIRONMENT. If this tag is present and the requested hardware type is not 219 * is usable in the specified condition. If the caller specifies Tag::BLOB_USAGE_REQUIREMENTS
99 * available, Keymaster returns HARDWARE_TYPE_UNAVAILABLE. This tag is not included in 220 * with value KeyBlobUsageRequirements::STANDALONE the IKeymasterDevice must return a key blob
100 * attestations, but hardware type must be reflected in the Keymaster SecurityLevel of the 221 * that can be used without file system support. This is critical for devices with encrypted
101 * attestation header. */ 222 * disks, where the file system may not be available until after a Keymaster key is used to
223 * decrypt the disk.
224 *
225 * Must be hardware-enforced.
226 */
227 BLOB_USAGE_REQUIREMENTS = TagType:ENUM | 301,
228
229 /**
230 * Tag::BOOTLOADER_ONLY specifies only the bootloader can use the key.
231 *
232 * Any attempt to use a key with Tag::BOOTLOADER_ONLY from the Android system must fail with
233 * ErrorCode::INVALID_KEY_BLOB.
234 *
235 * Must be hardware-enforced.
236 */
237 BOOTLOADER_ONLY = TagType:BOOL | 302,
238
239 /**
240 * Tag::ROLLBACK_RESISTANCE specifies that the key has rollback resistance, meaning that when
241 * deleted with deleteKey() or deleteAllKeys(), the key is guaranteed to be permanently deleted
242 * and unusable. It's possible that keys without this tag could be deleted and then restored
243 * from backup.
244 *
245 * This tag is specified by the caller during key generation or import to require. If the
246 * IKeymasterDevice cannot guarantee rollback resistance for the specified key, it must return
247 * ErrorCode::ROLLBACK_RESISTANCE_UNAVAILABLE. IKeymasterDevice implementations are not
248 * required to support rollback resistance.
249 *
250 * Must be hardwared-enforced.
251 */
252 ROLLBACK_RESISTANCE = TagType:BOOL | 303,
253
254 // Reserved for future use.
102 HARDWARE_TYPE = TagType:ENUM | 304, 255 HARDWARE_TYPE = TagType:ENUM | 304,
103 256
104 /* 257 /**
105 * Tags that should be semantically enforced by hardware if possible and will otherwise be 258 * Tag::ACTIVE_DATETIME specifies the date and time at which the key becomes active, in
106 * enforced by software (keystore). 259 * milliseconds since Jan 1, 1970. If a key with this tag is used prior to the specified date
107 */ 260 * and time, IKeymasterDevice::begin() must return ErrorCode::KEY_NOT_YET_VALID;
108 261 *
109 /* Key validity period */ 262 * Need not be hardware-enforced.
110 ACTIVE_DATETIME = TagType:DATE | 400, /* Start of validity. */ 263 */
111 ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401, /* Date when new "messages" should no longer 264 ACTIVE_DATETIME = TagType:DATE | 400, /* Start of validity. */
112 * be created. */ 265
113 USAGE_EXPIRE_DATETIME = TagType:DATE | 402, /* Date when existing "messages" should no 266 /**
114 * longer be trusted. */ 267 * Tag::ORIGINATION_EXPIRE_DATETIME specifies the date and time at which the key expires for
115 MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403, /* Minimum elapsed time between 268 * signing and encryption purposes. After this time, any attempt to use a key with
116 * cryptographic operations with the key. */ 269 * KeyPurpose::SIGN or KeyPurpose::ENCRYPT provided to begin() must fail with
117 MAX_USES_PER_BOOT = TagType:UINT | 404, /* Number of times the key can be used per 270 * ErrorCode::KEY_EXPIRED.
118 * boot. */ 271 *
119 272 * The value is a 64-bit integer representing milliseconds since January 1, 1970.
120 /* User authentication */ 273 *
121 // 500 reserved 274 * Need not be hardware-enforced.
122 USER_ID = TagType:UINT | 501, /* Android ID of authorized user or authenticator(s), */ 275 */
276 ORIGINATION_EXPIRE_DATETIME = TagType:DATE | 401,
277
278 /**
279 * Tag::USAGE_EXPIRE_DATETIME specifies the date and time at which the key expires for
280 * verification and decryption purposes. After this time, any attempt to use a key with
281 * KeyPurpose::VERIFY or KeyPurpose::DECRYPT provided to begin() must fail with
282 * ErrorCode::KEY_EXPIRED.
283 *
284 * The value is a 64-bit integer representing milliseconds since January 1, 1970.
285 *
286 * Need not be hardware-enforced.
287 */
288 USAGE_EXPIRE_DATETIME = TagType:DATE | 402,
289
290 /**
291 * Tag::MIN_SECONDS_BETWEEN_OPS specifies the minimum amount of time that elapses between
292 * allowed operations using a key. This can be used to rate-limit uses of keys in contexts
293 * where unlimited use may enable brute force attacks.
294 *
295 * The value is a 32-bit integer representing seconds between allowed operations.
296 *
297 * When a key with this tag is used in an operation, the IKeymasterDevice must start a timer
298 * during the finish() or abort() call. Any call to begin() that is received before the timer
299 * indicates that the interval specified by Tag::MIN_SECONDS_BETWEEN_OPS has elapsed must fail
300 * with ErrorCode::KEY_RATE_LIMIT_EXCEEDED. This implies that the IKeymasterDevice must keep a
301 * table of use counters for keys with this tag. Because memory is often limited, this table
302 * may have a fixed maximum size and Keymaster may fail operations that attempt to use keys with
303 * this tag when the table is full. The table must acommodate at least 8 in-use keys and
304 * aggressively reuse table slots when key minimum-usage intervals expire. If an operation
305 * fails because the table is full, Keymaster returns ErrorCode::TOO_MANY_OPERATIONS.
306 *
307 * Must be hardware-enforced.
308 */
309 MIN_SECONDS_BETWEEN_OPS = TagType:UINT | 403,
310
311 /**
312 * Tag::MAX_USES_PER_BOOT specifies the maximum number of times that a key may be used between
313 * system reboots. This is another mechanism to rate-limit key use.
314 *
315 * The value is a 32-bit integer representing uses per boot.
316 *
317 * When a key with this tag is used in an operation, a key-associated counter must be
318 * incremented during the begin() call. After the key counter has exceeded this value, all
319 * subsequent attempts to use the key must fail with ErrorCode::MAX_OPS_EXCEEDED, until the
320 * device is restarted. This implies that the IKeymasterDevice must keep a table of use
321 * counters for keys with this tag. Because Keymaster memory is often limited, this table can
322 * have a fixed maximum size and Keymaster can fail operations that attempt to use keys with
323 * this tag when the table is full. The table needs to acommodate at least 8 keys. If an
324 * operation fails because the table is full, IKeymasterDevice must
325 * ErrorCode::TOO_MANY_OPERATIONS.
326 *
327 * Must be hardware-enforced.
328 */
329 MAX_USES_PER_BOOT = TagType:UINT | 404,
330
331 /**
332 * Tag::USER_ID specifies the ID of the Android user that is permitted to use the key.
333 *
334 * Must not be hardware-enforced.
335 */
336 USER_ID = TagType:UINT | 501,
337
338 /**
339 * Tag::USER_SECURE_ID specifies that a key may only be used under a particular secure user
340 * authentication state. This tag is mutually exclusive with Tag::NO_AUTH_REQUIRED.
341 *
342 * The value is a 64-bit integer specifying the authentication policy state value which must be
343 * present in the userId or authenticatorId field of a HardwareAuthToken provided to begin(),
344 * update(), or finish(). If a key with Tag::USER_SECURE_ID is used without a HardwareAuthToken
345 * with the matching userId or authenticatorId, the IKeymasterDevice must return
346 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
347 *
348 * Tag::USER_SECURE_ID interacts with Tag::AUTH_TIMEOUT in a very important way. If
349 * Tag::AUTH_TIMEOUT is present in the key's characteristics then the key is a "timeout-based"
350 * key, and may only be used if the difference between the current time when begin() is called
351 * and the timestamp in the HardwareAuthToken is less than the value in Tag::AUTH_TIMEOUT * 1000
352 * (the multiplier is because Tag::AUTH_TIMEOUT is in seconds, but the HardwareAuthToken
353 * timestamp is in milliseconds). Otherwise the IKeymasterDevice must returrn
354 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
355 *
356 * If Tag::AUTH_TIMEOUT is not present, then the key is an "auth-per-operation" key. In this
357 * case, begin() must not require a HardwareAuthToken with appropriate contents. Instead,
358 * update() and finish() must receive a HardwareAuthToken with Tag::USER_SECURE_ID value in
359 * userId or authenticatorId fields, and the current operation's operation handle in the
360 * challenge field. Otherwise the IKeymasterDevice must returrn
361 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
362 *
363 * This tag is repeatable. If repeated, and any one of the values matches the HardwareAuthToken
364 * as described above, the key is authorized for use. Otherwise the operation must fail with
365 * ErrorCode::KEY_USER_NOT_AUTHENTICATED.
366 *
367 * Must be hardware-enforced.
368 */
123 USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s). 369 USER_SECURE_ID = TagType:ULONG_REP | 502, /* Secure ID of authorized user or authenticator(s).
124 * Disallowed if NO_AUTH_REQUIRED is present. */ 370 * Disallowed if NO_AUTH_REQUIRED is present. */
125 NO_AUTH_REQUIRED = TagType:BOOL | 503, /* If key is usable without authentication. */ 371
126 USER_AUTH_TYPE = TagType:ENUM | 504, /* Bitmask of authenticator types allowed when 372 /**
127 * USER_SECURE_ID contains a secure user ID, rather 373 * Tag::NO_AUTH_REQUIRED specifies that no authentication is required to use this key. This tag
128 * than a secure authenticator ID. Defined in 374 * is mutually exclusive with Tag::USER_SECURE_ID.
129 * HardwareAuthenticatorType. */ 375 *
130 AUTH_TIMEOUT = TagType:UINT | 505, /* Required freshness of user authentication for 376 * Must be hardware-enforced.
131 * private/secret key operations, in seconds. Public 377 */
132 * key operations require no authentication. If 378 NO_AUTH_REQUIRED = TagType:BOOL | 503, /* If key is usable without authentication. */
133 * absent, authentication is required for every use. 379
134 * Authentication state is lost when the device is 380 /**
135 * powered off. */ 381 * Tag::USER_AUTH_TYPE specifies the types of user authenticators that may be used to authorize
136 ALLOW_WHILE_ON_BODY = TagType:BOOL | 506, /* Allow key to be used after authentication timeout 382 * this key.
137 * if device is still on-body (requires secure 383 *
138 * on-body sensor. */ 384 * The value is one or more values from HardwareAuthenticatorType, ORed together.
385 *
386 * When IKeymasterDevice is requested to perform an operation with a key with this tag, it must
387 * receive a HardwareAuthToken and one or more bits must be set in both the HardwareAuthToken's
388 * authenticatorType field and the Tag::USER_AUTH_TYPE value. That is, it must be true that
389 *
390 * (token.authenticatorType & tag_user_auth_type) != 0
391 *
392 * where token.authenticatorType is the authenticatorType field of the HardwareAuthToken and
393 * tag_user_auth_type is the value of Tag:USER_AUTH_TYPE.
394 *
395 * Must be hardware-enforced.
396 */
397 USER_AUTH_TYPE = TagType:ENUM | 504,
398
399 /**
400 * Tag::AUTH_TIMEOUT specifies the time in seconds for which the key is authorized for use,
401 * after user authentication. If
402 * Tag::USER_SECURE_ID is present and this tag is not, then the key requies authentication for
403 * every usage (see begin() for the details of the authentication-per-operation flow).
404 *
405 * The value is a 32-bit integer specifying the time in seconds after a successful
406 * authentication of the user specified by Tag::USER_SECURE_ID with the authentication method
407 * specified by Tag::USER_AUTH_TYPE that the key can be used.
408 *
409 * Must be hardware-enforced.
410 */
411 AUTH_TIMEOUT = TagType:UINT | 505,
412
413 /**
414 * Tag::ALLOW_WHILE_ON_BODY specifies that the key may be used after authentication timeout if
415 * device is still on-body (requires on-body sensor).
416 *
417 * Cannot be hardware-enforced.
418 */
419 ALLOW_WHILE_ON_BODY = TagType:BOOL | 506,
139 420
140 /** 421 /**
141 * TRUSTED_USER_PRESENCE_REQUIRED is an optional feature that specifies that this key must be 422 * TRUSTED_USER_PRESENCE_REQUIRED is an optional feature that specifies that this key must be
@@ -166,7 +447,7 @@ enum Tag : uint32_t {
166 * the non-secure world, which means an attacker who has compromised Android can spoof 447 * the non-secure world, which means an attacker who has compromised Android can spoof
167 * password authentication. 448 * password authentication.
168 * 449 *
169 * Note that no mechanism is defined for delivering proof of presence to Keymaster, 450 * Note that no mechanism is defined for delivering proof of presence to an IKeymasterDevice,
170 * except perhaps as implied by an auth token. This means that Keymaster must be able to check 451 * except perhaps as implied by an auth token. This means that Keymaster must be able to check
171 * proof of presence some other way. Further, the proof of presence must be performed between 452 * proof of presence some other way. Further, the proof of presence must be performed between
172 * begin() and the first call to update() or finish(). If the first update() or the finish() 453 * begin() and the first call to update() or finish(). If the first update() or the finish()
@@ -182,108 +463,408 @@ enum Tag : uint32_t {
182 */ 463 */
183 TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507, 464 TRUSTED_USER_PRESENCE_REQUIRED = TagType:BOOL | 507,
184 465
185 /** TRUSTED_CONFIRMATION_REQUIRED is only applicable to keys with KeyPurpose SIGN, and specifies 466 /** Tag::TRUSTED_CONFIRMATION_REQUIRED is only applicable to keys with KeyPurpose SIGN, and
186 * that this key must not be usable unless the user provides confirmation of the data to be 467 * specifies that this key must not be usable unless the user provides confirmation of the data
187 * signed. Confirmation is proven to keymaster via an approval token. See CONFIRMATION_TOKEN, 468 * to be signed. Confirmation is proven to keymaster via an approval token. See
188 * as well as the ConfirmatinUI HAL. 469 * CONFIRMATION_TOKEN, as well as the ConfirmatinUI HAL.
189 * 470 *
190 * If an attempt to use a key with this tag does not have a cryptographically valid 471 * If an attempt to use a key with this tag does not have a cryptographically valid
191 * CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not 472 * CONFIRMATION_TOKEN provided to finish() or if the data provided to update()/finish() does not
192 * match the data described in the token, keymaster must return NO_USER_CONFIRMATION. */ 473 * match the data described in the token, keymaster must return NO_USER_CONFIRMATION. */
193 TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508, 474 TRUSTED_CONFIRMATION_REQUIRED = TagType:BOOL | 508,
194 475
195 UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509, /* Require the device screen to be unlocked if 476 /**
196 * the key is used. */ 477 *
478 */
479 UNLOCKED_DEVICE_REQUIRED = TagType:BOOL | 509,
197 480
198 /* Application access control */ 481 /**
199 APPLICATION_ID = TagType:BYTES | 601, /* Byte string identifying the authorized application. */ 482 * Tag::APPLICATION_ID. When provided to generateKey or importKey, this tag specifies data
483 * that is necessary during all uses of the key. In particular, calls to exportKey() and
484 * getKeyCharacteristics() must provide the same value to the clientId parameter, and calls to
485 * begin must provide this tag and the same associated data as part of the inParams set. If
486 * the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB.
487 *
488 * The content of this tag must be bound to the key cryptographically, meaning it must not be
489 * possible for an adversary who has access to all of the secure world secrets but does not have
490 * access to the tag content to decrypt the key without brute-forcing the tag content, which
491 * applications can prevent by specifying sufficiently high-entropy content.
492 *
493 * Must be hardware-enforced.
494 */
495 APPLICATION_ID = TagType:BYTES | 601,
200 496
201 /* 497 /*
202 * Semantically unenforceable tags, either because they have no specific meaning or because 498 * Semantically unenforceable tags, either because they have no specific meaning or because
203 * they're informational only. 499 * they're informational only.
204 */ 500 */
205 APPLICATION_DATA = TagType:BYTES | 700, /* Data provided by authorized application. */ 501
206 CREATION_DATETIME = TagType:DATE | 701, /* Key creation time */ 502 /**
207 ORIGIN = TagType:ENUM | 702, /* keymaster_key_origin_t. */ 503 * Tag::APPLICATION_DATA. When provided to generateKey or importKey, this tag specifies data
504 * that is necessary during all uses of the key. In particular, calls to exportKey() and
505 * getKeyCharacteristics() must provide the same value to the appData parameter, and calls to
506 * begin must provide this tag and the same associated data as part of the inParams set. If
507 * the correct data is not provided, the method must return ErrorCode::INVALID_KEY_BLOB.
508 *
509 * The content of this tag msut be bound to the key cryptographically, meaning it must not be
510 * possible for an adversary who has access to all of the secure world secrets but does not have
511 * access to the tag content to decrypt the key without brute-forcing the tag content, which
512 * applications can prevent by specifying sufficiently high-entropy content.
513 *
514 * Must be hardware-enforced.
515 */
516 APPLICATION_DATA = TagType:BYTES | 700,
517
518 /**
519 * Tag::CREATION_DATETIME specifies the date and time the key was created, in milliseconds since
520 * January 1, 1970. This tag is optional and informational only.
521 *
522 * Tag::CREATED is informational only, and not enforced by anything. Must be in the
523 * software-enforced list, if provided.
524 */
525 CREATION_DATETIME = TagType:DATE | 701,
526
527 /**
528 * Tag::ORIGIN specifies where the key was created, if known. This tag must not be specified
529 * during key generation or import, and must be added to the key characteristics by the
530 * IKeymasterDevice. The possible values are defined in the KeyOrigin enum.
531 *
532 * Must be hardware-enforced.
533 */
534 ORIGIN = TagType:ENUM | 702,
535
208 // 703 is unused. 536 // 703 is unused.
209 ROOT_OF_TRUST = TagType:BYTES | 704, /* Root of trust ID. */ 537
210 OS_VERSION = TagType:UINT | 705, /* Version of system (keymaster2) */ 538 /**
211 OS_PATCHLEVEL = TagType:UINT | 706, /* Patch level of system (keymaster2) */ 539 * Tag::ROOT_OF_TRUST specifies the root of trust, the key used by verified boot to validate the
212 UNIQUE_ID = TagType:BYTES | 707, /* Used to provide unique ID in attestation */ 540 * operating system booted (if any). This tag is never provided to or returned from Keymaster
541 * in the key characteristics. It exists only to define the tag for use in the attestation
542 * record.
543 *
544 * Must never appear in KeyCharacteristics.
545 */
546 ROOT_OF_TRUST = TagType:BYTES | 704,
547
548 /**
549 * Tag::OS_VERSION specifies the system OS version with which the key may be used. This tag is
550 * never sent to the IKeymasterDevice, but is added to the hardware-enforced authorization list
551 * by the TA. Any attempt to use a key with a Tag::OS_VERSION value different from the
552 * currently-running OS version must cause begin(), getKeyCharacteristics() or exportKey() to
553 * return ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
554 *
555 * The value of the tag is an integer of the form MMmmss, where MM is the major version number,
556 * mm is the minor version number, and ss is the sub-minor version number. For example, for a
557 * key generated on Android version 4.0.3, the value would be 040003.
558 *
559 * The IKeymasterDevice HAL must read the current OS version from the system property
560 * ro.build.id and deliver it to the secure environment when the HAL is first loaded (mechanism
561 * is implementation-defined). The secure environment must not accept another version until
562 * after the next boot. If the content of ro.build.id has additional version information after
563 * the sub-minor version number, it must not be included in Tag::OS_VERSION. If the content is
564 * non-numeric, the secure environment must use 0 as the system version.
565 *
566 * Must be hardware-enforced.
567 */
568 OS_VERSION = TagType:UINT | 705,
569
570 /**
571 * Tag::OS_PATCHLEVEL specifies the system security patch level with which the key may be used.
572 * This tag is never sent to the keymaster TA, but is added to the hardware-enforced
573 * authorization list by the TA. Any attempt to use a key with a Tag::OS_PATCHLEVEL value
574 * different from the currently-running system patchlevel must cause begin(),
575 * getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See
576 * upgradeKey() for details.
577 *
578 * The value of the tag is an integer of the form YYYYMM, where YYYY is the four-digit year of
579 * the last update and MM is the two-digit month of the last update. For example, for a key
580 * generated on an Android device last updated in December 2015, the value would be 201512.
581 *
582 * The IKeymasterDevice HAL must read the current system patchlevel from the system property
583 * ro.build.version.security_patch and deliver it to the secure environment when the HAL is
584 * first loaded (mechanism is implementation-defined). The secure environment must not accept
585 * another patchlevel until after the next boot.
586 *
587 * Must be hardware-enforced.
588 */
589 OS_PATCHLEVEL = TagType:UINT | 706,
590
591 /**
592 * Tag::UNIQUE_ID specifies a unique, time-based identifier. This tag is never provided to or
593 * returned from Keymaster in the key characteristics. It exists only to define the tag for use
594 * in the attestation record.
595 *
596 * When a key with Tag::INCLUDE_UNIQUE_ID is attested, the unique ID is added to the attestation
597 * record. The value is a 128-bit hash that is unique per device and per calling application,
598 * and changes monthly and on most password resets. It is computed with:
599 *
600 * HMAC_SHA256(T || C || R, HBK)
601 *
602 * Where:
603 *
604 * T is the "temporal counter value", computed by dividing the value of
605 * Tag::CREATION_DATETIME by 2592000000, dropping any remainder. T changes every 30 days
606 * (2592000000 = 30 * 24 * 60 * 60 * 1000).
607 *
608 * C is the value of Tag::ATTESTATION_APPLICATION_ID that is provided to attestKey().
609 *
610 * R is 1 if Tag::RESET_SINCE_ID_ROTATION was provided to attestKey or 0 if the tag was not
611 * provided.
612 *
613 * HBK is a unique hardware-bound secret known to the secure environment and never revealed
614 * by it. The secret must contain at least 128 bits of entropy and be unique to the
615 * individual device (probabilistic uniqueness is acceptable).
616 *
617 * HMAC_SHA256 is the HMAC function, with SHA-2-256 as the hash.
618 *
619 * The output of the HMAC function must be truncated to 128 bits.
620 *
621 * Must be hardware-enforced.
622 */
623 UNIQUE_ID = TagType:BYTES | 707,
624
625 /**
626 * Tag::ATTESTATION_CHALLENGE is used to deliver a "challenge" value to the attestKey() method,
627 * which must place the value in the KeyDescription SEQUENCE of the attestation extension. See
628 * attestKey().
629 *
630 * Must never appear in KeyCharacteristics.
631 */
213 ATTESTATION_CHALLENGE = TagType:BYTES | 708, /* Used to provide challenge in attestation */ 632 ATTESTATION_CHALLENGE = TagType:BYTES | 708, /* Used to provide challenge in attestation */
214 ATTESTATION_APPLICATION_ID = TagType:BYTES | 709, /* Used to identify the set of possible 633
215 * applications of which one has initiated a 634 /**
216 * key attestation */ 635 * Tag::ATTESTATION_APPLICATION_ID identifies the set of applications which may use a key, used
217 ATTESTATION_ID_BRAND = TagType:BYTES | 710, /* Used to provide the device's brand name to be 636 * only with attestKey().
218 * included in attestation */ 637 *
219 ATTESTATION_ID_DEVICE = TagType:BYTES | 711, /* Used to provide the device's device name to 638 * The content of Tag::ATTESTATION_APPLICATION_ID is a DER-encoded ASN.1 structure, with the
220 * be included in attestation */ 639 * following schema:
221 ATTESTATION_ID_PRODUCT = TagType:BYTES | 712, /* Used to provide the device's product name to 640 *
222 * be included in attestation */ 641 * AttestationApplicationId ::= SEQUENCE {
223 ATTESTATION_ID_SERIAL = 642 * packageInfoRecords SET OF PackageInfoRecord,
224 TagType:BYTES | 713, /* Used to provide the device's serial number to be 643 * signatureDigests SET OF OCTET_STRING,
225 * included in attestation */ 644 * }
645 *
646 * PackageInfoRecord ::= SEQUENCE {
647 * packageName OCTET_STRING,
648 * version INTEGER,
649 * }
650 *
651 * See system/security/keystore/keystore_attestation_id.cpp for details of construction.
652 * IKeymasterDevice implementers do not need to create or parse the ASN.1 structure, but only
653 * copy the tag value into the attestation record. The DER-encoded string must not exceed 1 KiB
654 * in length.
655 *
656 * Cannot be hardware-enforced.
657 */
658 ATTESTATION_APPLICATION_ID = TagType:BYTES | 709,
659
660 /**
661 * Tag::ATTESTATION_ID_BRAND provides the device's brand name, as returned by Build.BRAND in
662 * Android, to attestKey(). This field is set only when requesting attestation of the device's
663 * identifiers.
664 *
665 * If the device does not support ID attestation (or destroyAttestationIds() was previously
666 * called and the device can no longer attest its IDs), any key attestation request that
667 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
668 *
669 * Must never appear in KeyCharacteristics.
670 */
671 ATTESTATION_ID_BRAND = TagType:BYTES | 710,
672
673 /**
674 * Tag::ATTESTATION_ID_DEVICE provides the device's device name, as returned by Build.DEVICE in
675 * Android, to attestKey(). This field is set only when requesting attestation of the device's
676 * identifiers.
677 *
678 * If the device does not support ID attestation (or destroyAttestationIds() was previously
679 * called and the device can no longer attest its IDs), any key attestation request that
680 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
681 *
682 * Must never appear in KeyCharacteristics.
683 */
684 ATTESTATION_ID_DEVICE = TagType:BYTES | 711,
685
686 /**
687 * Tag::ATTESTATION_ID_PRODUCT provides the device's product name, as returned by Build.PRODUCT
688 * in Android, to attestKey(). This field is set only when requesting attestation of the
689 * device's identifiers.
690 *
691 * If the device does not support ID attestation (or destroyAttestationIds() was previously
692 * called and the device can no longer attest its IDs), any key attestation request that
693 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
694 *
695 * Must never appear in KeyCharacteristics.
696 */
697 ATTESTATION_ID_PRODUCT = TagType:BYTES | 712,
698
699 /**
700 * Tag::ATTESTATION_ID_SERIAL the device's serial number. This field is set only when
701 * requesting attestation of the device's identifiers.
702 *
703 * If the device does not support ID attestation (or destroyAttestationIds() was previously
704 * called and the device can no longer attest its IDs), any key attestation request that
705 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
706 *
707 * Must never appear in KeyCharacteristics.
708 */
709 ATTESTATION_ID_SERIAL = TagType:BYTES | 713,
710
711 /**
712 * Tag::ATTESTATION_ID_IMEI provides the IMEIs for all radios on the device to attestKey().
713 * This field is set only when requesting attestation of the device's identifiers.
714 *
715 * If the device does not support ID attestation (or destroyAttestationIds() was previously
716 * called and the device can no longer attest its IDs), any key attestation request that
717 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
718 *
719 * Must never appear in KeyCharacteristics.
720 */
226 ATTESTATION_ID_IMEI = TagType:BYTES | 714, /* Used to provide the device's IMEI to be included 721 ATTESTATION_ID_IMEI = TagType:BYTES | 714, /* Used to provide the device's IMEI to be included
227 * in attestation */ 722 * in attestation */
723
724 /**
725 * Tag::ATTESTATION_ID_MEID provides the MEIDs for all radios on the device to attestKey().
726 * This field will only be set when requesting attestation of the device's identifiers.
727 *
728 * If the device does not support ID attestation (or destroyAttestationIds() was previously
729 * called and the device can no longer attest its IDs), any key attestation request that
730 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
731 *
732 * Must never appear in KeyCharacteristics.
733 */
228 ATTESTATION_ID_MEID = TagType:BYTES | 715, /* Used to provide the device's MEID to be included 734 ATTESTATION_ID_MEID = TagType:BYTES | 715, /* Used to provide the device's MEID to be included
229 * in attestation */ 735 * in attestation */
230 ATTESTATION_ID_MANUFACTURER = 736
231 TagType:BYTES | 716, /* Used to provide the device's manufacturer 737 /**
232 * name to be included in attestation */ 738 * Tag::ATTESTATION_ID_MANUFACTURER provides the device's manufacturer name, as returned by
233 ATTESTATION_ID_MODEL = TagType:BYTES | 717, /* Used to provide the device's model name to be 739 * Build.MANUFACTURER in Android, to attstKey(). This field is set only when requesting
234 * included in attestation */ 740 * attestation of the device's identifiers.
235 741 *
236 /** 742 * If the device does not support ID attestation (or destroyAttestationIds() was previously
237 * Patch level of vendor image. The value is an integer of the form YYYYMM, where YYYY is the 743 * called and the device can no longer attest its IDs), any key attestation request that
238 * four-digit year when the vendor image was released and MM is the two-digit month. During 744 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
239 * each boot, the bootloader must provide the patch level of the vendor image to keymaser 745 *
240 * (mechanism is implemntation-defined). When keymaster keys are created or updated, the 746 * Must never appear in KeyCharacteristics.
241 * VENDOR_PATCHLEVEL tag must be cryptographically bound to the keys, with the current value as 747 */
242 * provided by the bootloader. When keys are used, keymaster must verify that the 748 ATTESTATION_ID_MANUFACTURER = TagType:BYTES | 716,
243 * VENDOR_PATCHLEVEL bound to the key matches the current value. If they do not match, 749
244 * keymaster must return ErrorCode::KEY_REQUIRES_UPGRADE. The client must then call upgradeKey. 750 /**
751 * Tag::ATTESTATION_ID_MODEL provides the device's model name, as returned by Build.MODEL in
752 * Android, to attestKey(). This field is set only when requesting attestation of the device's
753 * identifiers.
754 *
755 * If the device does not support ID attestation (or destroyAttestationIds() was previously
756 * called and the device can no longer attest its IDs), any key attestation request that
757 * includes this tag must fail with ErrorCode::CANNOT_ATTEST_IDS.
758 *
759 * Must never appear in KeyCharacteristics.
760 */
761 ATTESTATION_ID_MODEL = TagType:BYTES | 717,
762
763 /**
764 * Tag::VENDOR_PATCHLEVEL specifies the vendor image security patch level with which the key may
765 * be used. This tag is never sent to the keymaster TA, but is added to the hardware-enforced
766 * authorization list by the TA. Any attempt to use a key with a Tag::VENDOR_PATCHLEVEL value
767 * different from the currently-running system patchlevel must cause begin(),
768 * getKeyCharacteristics() or exportKey() to return ErrorCode::KEY_REQUIRES_UPGRADE. See
769 * upgradeKey() for details.
770 *
771 * The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of
772 * the last update, MM is the two-digit month and DD is the two-digit day of the last
773 * update. For example, for a key generated on an Android device last updated on June 5, 2018,
774 * the value would be 20180605.
775 *
776 * The IKeymasterDevice HAL must read the current vendor patchlevel from the system property
777 * ro.vendor.build.security_patch and deliver it to the secure environment when the HAL is first
778 * loaded (mechanism is implementation-defined). The secure environment must not accept another
779 * patchlevel until after the next boot.
780 *
781 * Must be hardware-enforced.
245 */ 782 */
246 VENDOR_PATCHLEVEL = TagType:UINT | 718, 783 VENDOR_PATCHLEVEL = TagType:UINT | 718,
247 784
248 /** 785 /**
249 * Patch level of boot image. The value is an integer of the form YYYYMM, where YYYY is the 786 * Tag::BOOT_PATCHLEVEL specifies the boot image (kernel) security patch level with which the
250 * four-digit year when the boot image was released and MM is the two-digit month. During each 787 * key may be used. This tag is never sent to the keymaster TA, but is added to the
251 * boot, the bootloader must provide the patch level of the boot image to keymaser (mechanism is 788 * hardware-enforced authorization list by the TA. Any attempt to use a key with a
252 * implemntation-defined). When keymaster keys are created or updated, the BOOT_PATCHLEVEL tag 789 * Tag::BOOT_PATCHLEVEL value different from the currently-running system patchlevel must
253 * must be cryptographically bound to the keys, with the current value as provided by the 790 * cause begin(), getKeyCharacteristics() or exportKey() to return
254 * bootloader. When keys are used, keymaster must verify that the BOOT_PATCHLEVEL bound to the 791 * ErrorCode::KEY_REQUIRES_UPGRADE. See upgradeKey() for details.
255 * key matches the current value. If they do not match, keymaster must return 792 *
256 * ErrorCode::KEY_REQUIRES_UPGRADE. The client must then call upgradeKey. 793 * The value of the tag is an integer of the form YYYYMMDD, where YYYY is the four-digit year of
794 * the last update, MM is the two-digit month and DD is the two-digit day of the last
795 * update. For example, for a key generated on an Android device last updated on June 5, 2018,
796 * the value would be 20180605. If the day is not known, 00 may be substituted.
797 *
798 * During each boot, the bootloader must provide the patch level of the boot image to the secure
799 * envirionment (mechanism is implementation-defined).
800 *
801 * Must be hardware-enforced.
257 */ 802 */
258 BOOT_PATCHLEVEL = TagType:UINT | 719, 803 BOOT_PATCHLEVEL = TagType:UINT | 719,
259 804
260 /* Tags used only to provide data to or receive data from operations */ 805 /**
261 ASSOCIATED_DATA = TagType:BYTES | 1000, /* Used to provide associated data for AEAD modes. */ 806 * Tag::ASSOCIATED_DATA Provides "associated data" for AES-GCM encryption or decryption. This
262 NONCE = TagType:BYTES | 1001, /* Nonce or Initialization Vector */ 807 * tag is provided to update and specifies data that is not encrypted/decrypted, but is used in
263 MAC_LENGTH = TagType:UINT | 1003, /* MAC or AEAD authentication tag length in bits. */ 808 * computing the GCM tag.
809 *
810 * Must never appear KeyCharacteristics.
811 */
812 ASSOCIATED_DATA = TagType:BYTES | 1000,
264 813
265 RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004, /* Whether the device has beeen factory reset 814 /**
266 * since the last unique ID rotation. Used for 815 * Tag::NONCE is used to provide or return a nonce or Initialization Vector (IV) for AES-GCM,
267 * key attestation. */ 816 * AES-CBC, AES-CTR, or 3DES-CBC encryption or decryption. This tag is provided to begin during
817 * encryption and decryption operations. It is only provided to begin if the key has
818 * Tag::CALLER_NONCE. If not provided, an appropriate nonce or IV will be randomly generated by
819 * Keymaster and returned from begin.
820 *
821 * The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend on the mode:
822 * GCM nonces are 12 bytes in length; AES-CBC and AES-CTR IVs are 16 bytes in length, 3DES-CBC
823 * IVs are 8 bytes in length.
824 *
825 * Must never appear in KeyCharacteristics.
826 */
827 NONCE = TagType:BYTES | 1001,
268 828
269 /** 829 /**
270 * CONFIRMATION_TOKEN is used to deliver a cryptographic token proving that the user confirmed a 830 * Tag::MAC_LENGTH provides the requested length of a MAC or GCM authentication tag, in bits.
271 * signing request. The content is a full-length HMAC-SHA256 value. See the ConfirmationUI HAL 831 *
272 * for details of token computation. 832 * The value is the MAC length in bits. It must be a multiple of 8 and at least as large as the
833 * value of Tag::MIN_MAC_LENGTH associated with the key. Otherwise, begin() must return
834 * ErrorCode::INVALID_MAC_LENGTH.
835 *
836 * Must never appear in KeyCharacteristics.
837 */
838 MAC_LENGTH = TagType:UINT | 1003,
839
840 /**
841 * Tag::RESET_SINCE_ID_ROTATION specifies whether the device has been factory reset since the
842 * last unique ID rotation. Used for key attestation.
843 *
844 * Must never appear in KeyCharacteristics.
845 */
846 RESET_SINCE_ID_ROTATION = TagType:BOOL | 1004,
847
848 /**
849 * Tag::CONFIRMATION_TOKEN is used to deliver a cryptographic token proving that the user
850 * confirmed a signing request. The content is a full-length HMAC-SHA256 value. See the
851 * ConfirmationUI HAL for details of token computation.
852 *
853 * Must never appear in KeyCharacteristics.
273 */ 854 */
274 CONFIRMATION_TOKEN = TagType:BYTES | 1005, 855 CONFIRMATION_TOKEN = TagType:BYTES | 1005,
275}; 856};
276 857
277/** 858/**
278 * Algorithms provided by keymaser implementations. 859 * Algorithms provided by IKeymasterDevice implementations.
279 */ 860 */
280enum Algorithm : uint32_t { 861enum Algorithm : uint32_t {
281 /** Asymmetric algorithms. */ 862 /** Asymmetric algorithms. */
282 RSA = 1, 863 RSA = 1,
283 // DSA = 2, -- Removed, do not re-use value 2. 864 // 2 removed, do not reuse.
284 EC = 3, 865 EC = 3,
285 866
286 /** Block ciphers algorithms */ 867 /** Block cipher algorithms */
287 AES = 32, 868 AES = 32,
288 TRIPLE_DES = 33, 869 TRIPLE_DES = 33,
289 870
@@ -393,12 +974,12 @@ enum KeyBlobUsageRequirements : uint32_t {
393 * Possible purposes of a key (or pair). 974 * Possible purposes of a key (or pair).
394 */ 975 */
395enum KeyPurpose : uint32_t { 976enum KeyPurpose : uint32_t {
396 ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */ 977 ENCRYPT = 0, /* Usable with RSA, EC and AES keys. */
397 DECRYPT = 1, /* Usable with RSA, EC and AES keys. */ 978 DECRYPT = 1, /* Usable with RSA, EC and AES keys. */
398 SIGN = 2, /* Usable with RSA, EC and HMAC keys. */ 979 SIGN = 2, /* Usable with RSA, EC and HMAC keys. */
399 VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */ 980 VERIFY = 3, /* Usable with RSA, EC and HMAC keys. */
400 /* 4 is reserved */ 981 /* 4 is reserved */
401 WRAP_KEY = 5, /* Usable with wrapping keys. */ 982 WRAP_KEY = 5, /* Usable with wrapping keys. */
402}; 983};
403 984
404/** 985/**
@@ -481,6 +1062,8 @@ enum ErrorCode : int32_t {
481 VERSION_MISMATCH = -101, 1062 VERSION_MISMATCH = -101,
482 1063
483 UNKNOWN_ERROR = -1000, 1064 UNKNOWN_ERROR = -1000,
1065
1066 // Implementer's namespace for error codes starts at -10000.
484}; 1067};
485 1068
486/** 1069/**
@@ -521,39 +1104,10 @@ enum SecurityLevel : uint32_t {
521 SOFTWARE = 0, 1104 SOFTWARE = 0,
522 TRUSTED_ENVIRONMENT = 1, 1105 TRUSTED_ENVIRONMENT = 1,
523 /** 1106 /**
524 * STRONGBOX specifies that the secure hardware satisfies the following requirements: 1107 * STRONGBOX specifies that the secure hardware satisfies the requirements specified in CDD
525 * 1108 * 9.11.2.
526 * a) Has a discrete CPU. The StrongBox device must not be the same CPU that is used to run
527 * the Android non-secure world, or any other untrusted code. The StrongBox CPU must not
528 * share cache, RAM or any other critical resources with any device that runs untrusted
529 * code.
530 *
531 * b) Has integral secure storage. The StrongBox device must have its own non-volatile
532 * storage that is not accessible by any other hardware component.
533 *
534 * c) Has a high-quality True Random Number Generator. The StrongBox device must have sole
535 * control of and access to a high-quality TRNG which it uses for generating necessary
536 * random bits. It must combine the output of this TRNG with caller-provided entropy in a
537 * strong CPRNG, as do non-Strongbox Keymaster implementations.
538 *
539 * d) Is enclosed in tamper-resistant packaging. The StrongBox device must have
540 * tamper-resistant packaging which provides obstacles to physical penetration which are
541 * higher than those provided by normal integrated circuit packages.
542 *
543 * e) Provides side-channel resistance. The StrongBox device must implement resistance
544 * against common side-channel attacks, including power analysis, timing analysis, EM
545 * snooping, etc.
546 *
547 * Devices with StrongBox Keymasters must also have a non-StrongBox Keymaster, which lives in
548 * the higher-performance TEE. Keystore must load both StrongBox (if available) and
549 * non-StrongBox HALs and route key generation/import requests appropriately. Callers that want
550 * StrongBox keys must add Tag::HARDWARE_TYPE with value SecurityLevel::STRONGBOX to the key
551 * description provided to generateKey or importKey. Keytore must route the request to a
552 * StrongBox HAL (a HAL whose isStrongBox method returns true). Keymaster implementations that
553 * receive a request for a Tag::HARDWARE_TYPE that is inappropriate must fail with
554 * ErrorCode::HARDWARE_TYPE_UNAVAILABLE.
555 */ 1109 */
556 STRONGBOX = 2, /* See IKeymaster::isStrongBox */ 1110 STRONGBOX = 2,
557}; 1111};
558 1112
559/** 1113/**
@@ -564,17 +1118,19 @@ enum KeyFormat : uint32_t {
564 X509 = 0, 1118 X509 = 0,
565 /** PCKS#8 format, asymmetric key pair import. */ 1119 /** PCKS#8 format, asymmetric key pair import. */
566 PKCS8 = 1, 1120 PKCS8 = 1,
567 /** Raw bytes, for symmetric key import and export. */ 1121 /** Raw bytes, for symmetric key import. */
568 RAW = 3, 1122 RAW = 3,
569}; 1123};
570 1124
571struct KeyParameter { 1125struct KeyParameter {
572 /** 1126 /**
573 * Discriminates the uinon/blob field used. The blob cannot be coincided with the union, but 1127 * Discriminates the union/blob field used. The blob cannot be placed in the union, but only
574 * only one of "f" and "blob" is ever used at a time. */ 1128 * one of "f" and "blob" may ever be used at a time.
1129 */
575 Tag tag; 1130 Tag tag;
1131
576 union IntegerParams { 1132 union IntegerParams {
577 /** Enum types */ 1133 /* Enum types */
578 Algorithm algorithm; 1134 Algorithm algorithm;
579 BlockMode blockMode; 1135 BlockMode blockMode;
580 PaddingMode paddingMode; 1136 PaddingMode paddingMode;
@@ -587,7 +1143,7 @@ struct KeyParameter {
587 HardwareAuthenticatorType hardwareAuthenticatorType; 1143 HardwareAuthenticatorType hardwareAuthenticatorType;
588 SecurityLevel hardwareType; 1144 SecurityLevel hardwareType;
589 1145
590 /** Other types */ 1146 /* Other types */
591 bool boolValue; // Always true, if a boolean tag is present. 1147 bool boolValue; // Always true, if a boolean tag is present.
592 uint32_t integer; 1148 uint32_t integer;
593 uint64_t longInteger; 1149 uint64_t longInteger;
@@ -597,20 +1153,68 @@ struct KeyParameter {
597 vec<uint8_t> blob; 1153 vec<uint8_t> blob;
598}; 1154};
599 1155
1156/**
1157 * KeyCharacteristics defines the attributes of a key, including cryptographic parameters, and usage
1158 * restrictions. It consits of two vectors of KeyParameters, one for "softwareEnforced" attributes
1159 * and one for "hardwareEnforced" attributes.
1160 *
1161 * KeyCharacteristics objects are returned by generateKey, importKey, importWrappedKey and
1162 * getKeyCharacteristics. The IKeymasterDevice secure environment is responsible for allocating the
1163 * parameters, all of which are Tags with associated values, to the correct vector. The
1164 * hardwareEnforced vector must contain only those attributes which are enforced by secure hardware.
1165 * All others should be in the softwareEnforced vector. See the definitions of individual Tag enums
1166 * for specification of which must be hardware-enforced, which may be software-enforced and which
1167 * must never appear in KeyCharacteristics.
1168 */
600struct KeyCharacteristics { 1169struct KeyCharacteristics {
601 vec<KeyParameter> softwareEnforced; 1170 vec<KeyParameter> softwareEnforced;
602 vec<KeyParameter> hardwareEnforced; 1171 vec<KeyParameter> hardwareEnforced;
603}; 1172};
604 1173
605/** 1174/**
606 * Data used to prove successful authentication. 1175 * HardwareAuthToken is used to prove successful user authentication, to unlock the use of a key.
1176 *
1177 * HardwareAuthTokens are produced by other secure environment applications, notably GateKeeper and
1178 * Fingerprint, in response to successful user authentication events. These tokens are passed to
1179 * begin(), update(), and finish() to prove that authentication occurred. See those methods for
1180 * more details. It is up to the caller to determine which of the generated auth tokens is
1181 * appropriate for a given key operation.
607 */ 1182 */
608struct HardwareAuthToken { 1183struct HardwareAuthToken {
1184 /**
1185 * challenge is a value that's used to enable authentication tokens to authorize specific
1186 * events. The primary use case for challenge is to authorize an IKeymasterDevice cryptographic
1187 * operation, for keys that require authentication per operation. See begin() for details.
1188 */
609 uint64_t challenge; 1189 uint64_t challenge;
610 uint64_t userId; // Secure User ID, not Android user ID. 1190
611 uint64_t authenticatorId; // Secure authenticator ID. 1191 /**
1192 * userId is the a "secure" user ID. It is not related to any Android user ID or UID, but is
1193 * created in the Gatekeeper application in the secure environment.
1194 */
1195 uint64_t userId;
1196
1197 /**
1198 * authenticatorId is the a "secure" user ID. It is not related to any Android user ID or UID,
1199 * but is created in an authentication application in the secure environment, such as the
1200 * Fingerprint application.
1201 */
1202 uint64_t authenticatorId; // Secure authenticator ID.
1203
1204 /**
1205 * authenticatorType describes the type of authentication that took place, e.g. password or
1206 * fingerprint.
1207 */
612 HardwareAuthenticatorType authenticatorType; 1208 HardwareAuthenticatorType authenticatorType;
1209
1210 /**
1211 * timestamp indicates when the user authentication took place, in milliseconds since some
1212 * starting point (generally the most recent device boot) which all of the applications within
1213 * one secure environment must agree upon. This timestamp is used to determine whether or not
1214 * the authentication occurred recently enough to unlock a key (see Tag::AUTH_TIMEOUT).
1215 */
613 Timestamp timestamp; 1216 Timestamp timestamp;
1217
614 /** 1218 /**
615 * MACs are computed with a backward-compatible method, used by Keymaster 3.0, Gatekeeper 1.0 1219 * MACs are computed with a backward-compatible method, used by Keymaster 3.0, Gatekeeper 1.0
616 * and Fingerprint 1.0, as well as pre-treble HALs. 1220 * and Fingerprint 1.0, as well as pre-treble HALs.
@@ -623,7 +1227,8 @@ struct HardwareAuthToken {
623 * where ``||'' represents concatenation, the leading zero is a single byte, and all integers 1227 * where ``||'' represents concatenation, the leading zero is a single byte, and all integers
624 * are represented as unsigned values, the full width of the type. The challenge, userId and 1228 * are represented as unsigned values, the full width of the type. The challenge, userId and
625 * authenticatorId values are in machine order, but authenticatorType and timestamp are in 1229 * authenticatorId values are in machine order, but authenticatorType and timestamp are in
626 * network order. This odd construction is compatible with the hw_auth_token_t structure, 1230 * network order (big-endian). This odd construction is compatible with the hw_auth_token_t
1231 * structure,
627 * 1232 *
628 * Note that mac is a vec rather than an array, not because it's actually variable-length but 1233 * Note that mac is a vec rather than an array, not because it's actually variable-length but
629 * because it could be empty. As documented in the IKeymasterDevice::begin, 1234 * because it could be empty. As documented in the IKeymasterDevice::begin,