diff options
author | android-build-team Robot | 2018-05-24 02:22:13 -0500 |
---|---|---|
committer | android-build-team Robot | 2018-05-24 02:22:13 -0500 |
commit | 19131e0f82af2ed99c3eb34d6cb3c52e3dac9393 (patch) | |
tree | 69d85c62937985b05bf990533c172249b19d5081 | |
parent | e4db4f546c3453e741d688311ce60ee3f55f7fe3 (diff) | |
parent | 1f74538cdb297a0a2ecd4ac1cc40214e83edb11f (diff) | |
download | platform-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
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 | ||
139 | Return<void> TunerCallbackMock::onCurrentProgramInfoChanged(const ProgramInfo& info) { | 139 | Return<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) { | |||
46 | TEST(IdentifierIteratorTest, empty) { | 46 | TEST(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) { | |||
66 | TEST(IdentifierIteratorTest, increments) { | 66 | TEST(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 | ||
123 | TEST(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 | ||
84 | IdentifierIterator begin(const V2_0::ProgramSelector& sel) { | ||
85 | return IdentifierIterator(sel); | ||
86 | } | ||
87 | |||
88 | IdentifierIterator end(const V2_0::ProgramSelector& sel) { | ||
89 | return IdentifierIterator(sel) + 1 /* primary id */ + sel.secondaryIds.size(); | ||
90 | } | ||
91 | |||
92 | FrequencyBand getBand(uint64_t freq) { | 84 | FrequencyBand 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 | |||
407 | namespace V2_0 { | ||
408 | |||
409 | utils::IdentifierIterator begin(const ProgramSelector& sel) { | ||
410 | return utils::IdentifierIterator(sel); | ||
411 | } | ||
412 | |||
413 | utils::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 | ||
72 | IdentifierIterator begin(const V2_0::ProgramSelector& sel); | ||
73 | IdentifierIterator 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, | |||
153 | V2_0::ProgramIdentifier make_hdradio_station_name(const std::string& name); | 150 | V2_0::ProgramIdentifier make_hdradio_station_name(const std::string& name); |
154 | 151 | ||
155 | } // namespace utils | 152 | } // namespace utils |
153 | |||
154 | namespace V2_0 { | ||
155 | |||
156 | utils::IdentifierIterator begin(const ProgramSelector& sel); | ||
157 | utils::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. |
36 | static constexpr size_t CAMERA_RESULT_METADATA_QUEUE_SIZE = 1 << 20 /* 1MB */; | 36 | static 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 | ||
42 | static constexpr int METADATA_SHRINK_ABS_THRESHOLD = 4096; | ||
43 | static constexpr int METADATA_SHRINK_REL_THRESHOLD = 2; | ||
44 | |||
38 | HandleImporter CameraDeviceSession::sHandleImporter; | 45 | HandleImporter CameraDeviceSession::sHandleImporter; |
39 | const int CameraDeviceSession::ResultBatcher::NOT_BATCHED; | 46 | const 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 | ||
1371 | void 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 | |||
1406 | bool 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 | |||
1417 | camera_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 | |||
332 | private: | 343 | private: |
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) | |||
66 | LOCAL_KERNEL_CONFIG_DATA_PATHS := \ | 66 | LOCAL_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 | ||
71 | include $(BUILD_FRAMEWORK_COMPATIBILITY_MATRIX) | 71 | include $(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 @@ | |||
1 | service 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 | |||
3 | hidl_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 | */ | ||
16 | package android.hardware.configstore@1.1; | ||
17 | |||
18 | import @1.0::ISurfaceFlingerConfigs; | ||
19 | |||
20 | /** | ||
21 | * New revision of ISurfaceFlingerConfigs | ||
22 | */ | ||
23 | interface 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 | ################################################################################ |
4 | include $(CLEAR_VARS) | 4 | include $(CLEAR_VARS) |
5 | LOCAL_MODULE := android.hardware.configstore@1.0-service | 5 | LOCAL_MODULE := android.hardware.configstore@1.1-service |
6 | # seccomp is not required for coverage build. | 6 | # seccomp is not required for coverage build. |
7 | ifneq ($(NATIVE_COVERAGE),true) | 7 | ifneq ($(NATIVE_COVERAGE),true) |
8 | LOCAL_REQUIRED_MODULES_arm64 := configstore@1.0.policy | 8 | LOCAL_REQUIRED_MODULES_arm64 := configstore@1.1.policy |
9 | endif | 9 | endif |
10 | LOCAL_PROPRIETARY_MODULE := true | 10 | LOCAL_PROPRIETARY_MODULE := true |
11 | LOCAL_MODULE_CLASS := EXECUTABLES | 11 | LOCAL_MODULE_CLASS := EXECUTABLES |
12 | LOCAL_MODULE_RELATIVE_PATH := hw | 12 | LOCAL_MODULE_RELATIVE_PATH := hw |
13 | LOCAL_INIT_RC := android.hardware.configstore@1.0-service.rc | 13 | LOCAL_INIT_RC := android.hardware.configstore@1.1-service.rc |
14 | LOCAL_SRC_FILES:= service.cpp | 14 | LOCAL_SRC_FILES:= service.cpp |
15 | 15 | ||
16 | include $(LOCAL_PATH)/surfaceflinger.mk | 16 | include $(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 | ||
27 | include $(BUILD_EXECUTABLE) | 28 | include $(BUILD_EXECUTABLE) |
28 | 29 | ||
29 | # seccomp filter for configstore | 30 | # seccomp filter for configstore |
30 | ifeq ($(TARGET_ARCH), $(filter $(TARGET_ARCH), arm64)) | 31 | ifeq ($(TARGET_ARCH), $(filter $(TARGET_ARCH), arm64)) |
31 | include $(CLEAR_VARS) | 32 | include $(CLEAR_VARS) |
32 | LOCAL_MODULE := configstore@1.0.policy | 33 | LOCAL_MODULE := configstore@1.1.policy |
33 | LOCAL_MODULE_CLASS := ETC | 34 | LOCAL_MODULE_CLASS := ETC |
34 | LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/etc/seccomp_policy | 35 | LOCAL_MODULE_PATH := $(TARGET_OUT_VENDOR)/etc/seccomp_policy |
35 | LOCAL_SRC_FILES := seccomp_policy/configstore@1.0-$(TARGET_ARCH).policy | 36 | LOCAL_SRC_FILES := seccomp_policy/configstore@1.1-$(TARGET_ARCH).policy |
36 | include $(BUILD_PREBUILT) | 37 | include $(BUILD_PREBUILT) |
37 | endif | 38 | endif |
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 | |||
19 | namespace android { | 22 | namespace android { |
20 | namespace hardware { | 23 | namespace hardware { |
21 | namespace configstore { | 24 | namespace configstore { |
22 | namespace V1_0 { | 25 | namespace V1_1 { |
23 | namespace implementation { | 26 | namespace 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 | ||
149 | static_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 | |||
154 | Return<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 | ||
8 | namespace android { | 8 | namespace android { |
9 | namespace hardware { | 9 | namespace hardware { |
10 | namespace configstore { | 10 | namespace configstore { |
11 | namespace V1_0 { | 11 | namespace V1_1 { |
12 | namespace implementation { | 12 | namespace implementation { |
13 | 13 | ||
14 | using ::android::hardware::configstore::V1_0::ISurfaceFlingerConfigs; | 14 | using ::android::hardware::configstore::V1_1::ISurfaceFlingerConfigs; |
15 | using ::android::hardware::Return; | 15 | using ::android::hardware::Return; |
16 | using ::android::hardware::Void; | 16 | using ::android::hardware::Void; |
17 | using ::android::sp; | 17 | using ::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 @@ | |||
1 | service 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 | ||
25 | using android::hardware::configureRpcThreadpool; | 25 | using android::hardware::configureRpcThreadpool; |
26 | using android::hardware::joinRpcThreadpool; | 26 | using android::hardware::joinRpcThreadpool; |
27 | using android::hardware::configstore::V1_0::ISurfaceFlingerConfigs; | 27 | using android::hardware::configstore::V1_1::ISurfaceFlingerConfigs; |
28 | using android::hardware::configstore::V1_0::implementation::SurfaceFlingerConfigs; | 28 | using android::hardware::configstore::V1_1::implementation::SurfaceFlingerConfigs; |
29 | using android::hardware::SetupMinijail; | 29 | using android::hardware::SetupMinijail; |
30 | using android::sp; | 30 | using android::sp; |
31 | using android::status_t; | 31 | using android::status_t; |
@@ -34,7 +34,7 @@ using android::OK; | |||
34 | int main() { | 34 | int 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 | |||
58 | ifneq ($(SF_START_GRAPHICS_ALLOCATOR_SERVICE),) | 58 | ifneq ($(SF_START_GRAPHICS_ALLOCATOR_SERVICE),) |
59 | LOCAL_CFLAGS += -DSTART_GRAPHICS_ALLOCATOR_SERVICE | 59 | LOCAL_CFLAGS += -DSTART_GRAPHICS_ALLOCATOR_SERVICE |
60 | endif | 60 | endif |
61 | |||
62 | ifneq ($(SF_PRIMARY_DISPLAY_ORIENTATION),) | ||
63 | LOCAL_CFLAGS += -DPRIMARY_DISPLAY_ORIENTATION=$(SF_PRIMARY_DISPLAY_ORIENTATION) | ||
64 | endif | ||
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 | */ | ||
16 | package android.hardware.configstore@1.1; | ||
17 | |||
18 | /** | ||
19 | * Orientation in degrees. | ||
20 | */ | ||
21 | enum DisplayOrientation : uint8_t { | ||
22 | ORIENTATION_0, | ||
23 | ORIENTATION_90, | ||
24 | ORIENTATION_180, | ||
25 | ORIENTATION_270, | ||
26 | }; | ||
27 | |||
28 | struct 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 | ||
36 | namespace configstore { | 37 | namespace configstore { |
37 | // import types from V1_0 | 38 | // import types from configstore |
39 | using ::android::hardware::configstore::V1_1::DisplayOrientation; | ||
38 | using ::android::hardware::configstore::V1_0::OptionalBool; | 40 | using ::android::hardware::configstore::V1_0::OptionalBool; |
39 | using ::android::hardware::configstore::V1_0::OptionalInt32; | 41 | using ::android::hardware::configstore::V1_0::OptionalInt32; |
40 | using ::android::hardware::configstore::V1_0::OptionalUInt32; | 42 | using ::android::hardware::configstore::V1_0::OptionalUInt32; |
41 | using ::android::hardware::configstore::V1_0::OptionalInt64; | 43 | using ::android::hardware::configstore::V1_0::OptionalInt64; |
42 | using ::android::hardware::configstore::V1_0::OptionalUInt64; | 44 | using ::android::hardware::configstore::V1_0::OptionalUInt64; |
43 | using ::android::hardware::configstore::V1_0::OptionalString; | 45 | using ::android::hardware::configstore::V1_0::OptionalString; |
46 | using ::android::hardware::configstore::V1_1::OptionalDisplayOrientation; | ||
47 | |||
48 | static 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 | ||
152 | template <typename I, android::hardware::Return<void> (I::*func)( | ||
153 | std::function<void(const OptionalDisplayOrientation&)>)> | ||
154 | DisplayOrientation 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 | |||
325 | 812fa66aa10ba0cba27cfddc2fd7f0ee27a8ab65a1f15aa79fdad97d403e6a14 android.hardware.camera.device@3.4::ICameraDeviceSession | 325 | 812fa66aa10ba0cba27cfddc2fd7f0ee27a8ab65a1f15aa79fdad97d403e6a14 android.hardware.camera.device@3.4::ICameraDeviceSession |
326 | cc288f1f78d1e643eb3d3dbc16e1401d44033d8e6856761f5156814a29986ec7 android.hardware.camera.device@3.4::types | 326 | cc288f1f78d1e643eb3d3dbc16e1401d44033d8e6856761f5156814a29986ec7 android.hardware.camera.device@3.4::types |
327 | f9278c8beb9d42d96e26d73ecabe1dff1d7e2fb301ab7f737d93e5ffae8d3312 android.hardware.camera.metadata@3.3::types | 327 | f9278c8beb9d42d96e26d73ecabe1dff1d7e2fb301ab7f737d93e5ffae8d3312 android.hardware.camera.metadata@3.3::types |
328 | f858091b10f7d5927be60573c06df4805275d37226bbb41a732190bfb81457ec android.hardware.configstore@1.1::ISurfaceFlingerConfigs | ||
329 | 5b0fb9842f8b0eb3730b93c30a7925290ab44763ab86bb493bfa58d0f2eeb369 android.hardware.configstore@1.1::types | ||
328 | 1a46aeae45b7a0e47f79b7207300532986f9d9cd7060779afc7a529f54d712ab android.hardware.confirmationui@1.0::IConfirmationResultCallback | 330 | 1a46aeae45b7a0e47f79b7207300532986f9d9cd7060779afc7a529f54d712ab android.hardware.confirmationui@1.0::IConfirmationResultCallback |
329 | 6d8347ff3cd7de471065ac3e8e68385073630cdeebe9f8fa58cb91cf44436c95 android.hardware.confirmationui@1.0::IConfirmationUI | 331 | 6d8347ff3cd7de471065ac3e8e68385073630cdeebe9f8fa58cb91cf44436c95 android.hardware.confirmationui@1.0::IConfirmationUI |
330 | a3ff916784dce87a56c757ab5c86433f0cdf562280999a5f978a6e8a0f3f19e7 android.hardware.confirmationui@1.0::types | 332 | a3ff916784dce87a56c757ab5c86433f0cdf562280999a5f978a6e8a0f3f19e7 android.hardware.confirmationui@1.0::types |
@@ -345,8 +347,8 @@ dd83be076b6b3f10ed62ab34d8c8b95f2415961fb785200eb842e7bfb2b0ee92 android.hardwar | |||
345 | 675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth | 347 | 675682dd3007805c985eaaec91612abc88f4c25b3431fb84070b7584a1a741fb android.hardware.health@2.0::IHealth |
346 | 434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback | 348 | 434c4c32c00b0e54bb05e40c79503208b40f786a318029a2a4f66e34f10f2a76 android.hardware.health@2.0::IHealthInfoCallback |
347 | c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types | 349 | c9e498f1ade5e26f00d290b4763a9671ec6720f915e7d592844b62e8cb1f9b5c android.hardware.health@2.0::types |
348 | a6cf986593c6ad15fe2ae3a1995d2cae233500bc32c055912a42723bdc076868 android.hardware.keymaster@4.0::IKeymasterDevice | 350 | 5c8e06f9945276d1a9e8f7e37cf0ea8894bdb906fa80809cb06c36abb39afc4f android.hardware.keymaster@4.0::IKeymasterDevice |
349 | e15ebdf1e0a326ff5b8a59668d4d8cd3852bd88388eae91de13f5f7e1af50ed1 android.hardware.keymaster@4.0::types | 351 | 6695eb5744108035506004dd136068b1aaebe809cf9d4a69c2fe33b73058bb85 android.hardware.keymaster@4.0::types |
350 | 6d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor | 352 | 6d5c646a83538f0f9d8438c259932509f4353410c6c76e56db0d6ca98b69c3bb android.hardware.media.bufferpool@1.0::IAccessor |
351 | b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager | 353 | b8c7ed58aa8740361e63d0ce9e7c94227572a629f356958840b34809d2393a7c android.hardware.media.bufferpool@1.0::IClientManager |
352 | 4a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 android.hardware.media.bufferpool@1.0::IConnection | 354 | 4a2c0dc82780e6c90731725a103feab8ab6ecf85a64e049b9cbd2b2c61620fe1 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; | |||
20 | import android.hardware.keymaster@3.0::KeyFormat; | 20 | import 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 | |||
26 | interface IKeymasterDevice { | 199 | interface 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 { | |||
59 | enum Tag : uint32_t { | 59 | enum 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 | */ |
280 | enum Algorithm : uint32_t { | 861 | enum 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 | */ |
395 | enum KeyPurpose : uint32_t { | 976 | enum 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 | ||
571 | struct KeyParameter { | 1125 | struct 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 | */ | ||
600 | struct KeyCharacteristics { | 1169 | struct 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 | */ |
608 | struct HardwareAuthToken { | 1183 | struct 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, |