Trang này cung cấp thông tin chi tiết để hỗ trợ những người triển khai HAL Keymaster. Thẻ này bao gồm từng thẻ trong HAL, phiên bản Keymaster mà thẻ có sẵn và liệu thẻ có thể lặp lại hay không. Ngoại trừ như được lưu ý trong phần mô tả thẻ, tất cả các thẻ bên dưới được sử dụng trong quá trình tạo khóa để chỉ định khóa đặc điểm.
Đối với Keymaster 4, thẻ được xác định trong
platform/hardware/interfaces/keymaster/keymaster-version/types.hal!
chẳng hạn như
3.0/types.hal cho Keymaster 3 và
4.0/types.hal cho Keymaster 4. Đối với Keymaster 2 trở xuống, thẻ được xác định trong
platform/hardware/libhardware/include/hardware/keymaster_defs.h.
Để biết các hàm, hãy xem Trang Keymaster Functions.
Tag::ACTIVE_DATETIME
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định ngày và giờ mà khoá bắt đầu hoạt động. Trước đó
bất kỳ lần nào cố gắng sử dụng khoá sẽ không thành công với
ErrorCode::KEY_NOT_YET_VALID.
Giá trị này là một số nguyên 64 bit đại diện cho mili giây kể từ ngày 1 tháng 1 năm 1970.
Tag::ALGORITHM
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định thuật toán mã hoá dùng để sử dụng khoá.
Các giá trị có thể có được xác định bằng cách liệt kê sau:
Keymaster 3
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Thẻ::ALL_APPLICATIONS
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Dành riêng để sử dụng trong tương lai.
Tag::ALLOW_WHILE_ON_BODY
Phiên bản: 2, 3, 4
Có thể lặp lại? Không
Thẻ này chỉ áp dụng cho các thiết bị Android Wear có cảm biến trên cơ thể. Tại nên không thể kỳ vọng rằng bất kỳ TEE nào cũng có thể cung cấp hoạt động truy cập an toàn với cảm biến trên cơ thể hoặc cảm biến trên cơ thể rất an toàn, vì vậy dự kiến sẽ là một tính năng hoàn toàn dựa trên phần mềm.
Thẻ::ALL_USERS
Phiên bản: 3, 4
Có thể lặp lại? Không
Dành riêng để sử dụng trong tương lai.
Thẻ::APPLICATION_DATA
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Khi được cung cấp cho
generateKey
hoặc nhậpKey
thẻ này chỉ định dữ liệu cần thiết trong tất cả các lần sử dụng khoá. Ngang bằng
cụ thể, cuộc gọi đến
exportKey và
getKeyCharacteristics
cần cung cấp cùng một giá trị cho thông số clientId, và các lệnh gọi
để bắt đầu cần cung cấp
thẻ này và cùng dữ liệu được liên kết như một phần của inParams
thiết lập. Nếu bạn không cung cấp dữ liệu chính xác, hàm này sẽ trả về ErrorCode::INVALID_KEY_BLOB.
Nội dung của thẻ này được liên kết với khoá theo phương thức mã hoá, nghĩa là đối phương không thể truy cập vào tất cả các bí mật bảo mật trên thế giới nhưng không có quyền truy cập vào nội dung thẻ để giải mã khoá mà không cần phải tấn công nội dung thẻ. Ứng dụng có thể ngăn chặn điều này bằng cách chỉ định nội dung có độ hỗn loạn đủ cao.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::APPLICATION_ID
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Khi được cung cấp cho generateKey hoặc importKey, thẻ này chỉ định dữ liệu cần thiết trong mọi trường hợp sử dụng khoá. Cụ thể, các lệnh gọi đến exportKey và getKeyCharacteristics cần cung cấp cùng một giá trị trong tham số clientId, còn các lệnh gọi đến begin cần cung cấp thẻ này và cùng một dữ liệu liên kết trong tập hợp inParams. Nếu bạn không cung cấp dữ liệu chính xác, hàm này sẽ trả về ErrorCode::INVALID_KEY_BLOB.
Nội dung của thẻ này được liên kết với khoá theo phương thức mã hoá, nghĩa là đối thủ có thể truy cập vào tất cả bí mật an toàn trên thế giới nhưng không có quyền truy cập vào nội dung thẻ và không thể giải mã khoá (mà không cần phải dùng phương thức tấn công brute-force vào nội dung thẻ).
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::ASSOCIATED_DATA
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Cung cấp "dữ liệu được liên kết" để mã hoá hoặc giải mã AES-GCM. Thẻ này được cung cấp để cập nhật và chỉ định dữ liệu không được mã hoá/giải mã, nhưng được dùng trong việc tính toán thẻ GCM.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::ATTESTATION_APPLICATION_ID
Phiên bản: 3, 4
Có thể lặp lại? Không
Dùng để xác định tập hợp các ứng dụng có thể có, trong đó một ứng dụng đã bắt đầu chứng thực khoá.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Tag::ATTESTATION_CHALLENGE
Phiên bản: 3, 4
Có thể lặp lại? Không
Dùng để đưa ra thách thức trong quy trình chứng thực.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::ATTESTATION_ID_BRAND
Phiên bản: 3, 4
Có thể lặp lại? Không
Cung cấp tên thương hiệu của thiết bị do Build.BRAND trả về
trong Android. Trường này chỉ được đặt khi yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ quy trình chứng thực giấy tờ tuỳ thân (hoặc
destroyAttestationIds() đã từng được gọi và thiết bị có thể
không còn chứng thực mã nhận dạng), mọi yêu cầu chứng thực khoá bao gồm
thẻ này sẽ không hoạt động với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::ATTESTATION_ID_DEVICE
Phiên bản: 3, 4
Có thể lặp lại? Không
Cung cấp tên thiết bị do Build.DEVICE trả về
trong Android. Trường này chỉ được đặt khi yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ quy trình chứng thực giấy tờ tuỳ thân (hoặc
destroyAttestationIds() đã từng được gọi và thiết bị có thể
không còn chứng thực mã nhận dạng), mọi yêu cầu chứng thực khoá bao gồm
thẻ này sẽ không hoạt động với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Tag::ATTESTATION_ID_IMEI
Phiên bản: 3, 4
Có thể lặp lại? Có
Cung cấp IMEI cho tất cả đài phát trên thiết bị. Trường này chỉ được đặt khi yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ chứng thực mã nhận dạng (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không thể chứng thực mã nhận dạng của mình nữa), thì mọi yêu cầu chứng thực khoá có chứa thẻ này sẽ không thành công với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Tag::ATTESTATION_ID_MANUFACTURER
Phiên bản: 3, 4
Có thể lặp lại? Không
Cung cấp tên nhà sản xuất của thiết bị, như được trả về bởi
Build.MANUFACTURER trong Android. Trường này chỉ được đặt khi
yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ chứng thực mã nhận dạng (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không thể chứng thực mã nhận dạng của mình nữa), thì mọi yêu cầu chứng thực khoá có chứa thẻ này sẽ không thành công với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::ATTESTATION_ID_MEID
Phiên bản: 3, 4
Có thể lặp lại? Có
Cung cấp MEID cho tất cả các đài phát trên thiết bị. Trường này chỉ được đặt khi yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ chứng thực mã nhận dạng (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không thể chứng thực mã nhận dạng của mình nữa), thì mọi yêu cầu chứng thực khoá có chứa thẻ này sẽ không thành công với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Tag::ATTESTATION_ID_MODEL
Phiên bản: 3, 4
Có thể lặp lại? Không
Cung cấp tên kiểu máy của thiết bị, do Build.MODEL trả về trong Android. Trường này chỉ được đặt khi
yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ chứng thực mã nhận dạng (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không thể chứng thực mã nhận dạng của mình nữa), thì mọi yêu cầu chứng thực khoá có chứa thẻ này sẽ không thành công với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Tag::ATTESTATION_ID_PRODUCT
Phiên bản: 3, 4
Có thể lặp lại? Không
Cung cấp tên sản phẩm của thiết bị, do Build.PRODUCT trả về trong Android. Trường này chỉ được đặt khi
yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ chứng thực mã nhận dạng (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không thể chứng thực mã nhận dạng của mình nữa), thì mọi yêu cầu chứng thực khoá có chứa thẻ này sẽ không thành công với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::ATTESTATION_ID_SERIAL
Phiên bản: 3, 4
Có thể lặp lại? Không
Cung cấp số sê-ri của thiết bị. Trường này chỉ được đặt khi yêu cầu chứng thực giá trị nhận dạng của thiết bị.
Nếu thiết bị không hỗ trợ chứng thực mã nhận dạng (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không thể chứng thực mã nhận dạng của mình nữa), thì mọi yêu cầu chứng thực khoá có chứa thẻ này sẽ không thành công với ErrorCode::CANNOT_ATTEST_IDS.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Thẻ::Save_TIMEOUT
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định thời gian tính bằng giây mà khoá được phép sử dụng, sau khi xác thực. Nếu là Thẻ::USER_SECURE_ID có tồn tại còn thẻ này thì không, thì khoá này cần được xác thực cho mỗi (xem bắt đầu để biết thông tin chi tiết của quy trình xác thực cho mỗi thao tác).
Giá trị này là một số nguyên 32 bit chỉ định thời gian tính bằng giây sau khi xác thực thành công người dùng do Tag::USER_SECURE_ID chỉ định bằng phương thức xác thực do Tag::USER_AUTH_TYPE chỉ định mà khoá có thể được sử dụng.
Thẻ::GCS_TOKEN
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Cung cấp mã xác thực để bắt đầu, cập nhật hoặc hoàn tất, nhằm chứng minh việc xác thực người dùng cho một thao tác khoá cần mã xác thực (khoá có Tag::USER_SECURE_ID).
Giá trị này là một blob chứa cấu trúc hw_auth_token_t.
Tag::BLOB_USAGE_REQUIREMENTS
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định các điều kiện môi trường hệ thống cần thiết để sử dụng khoá được tạo.
Các giá trị có thể có được xác định theo cách liệt kê sau đây:
Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
typedef enum {
KM_BLOB_STANDALONE = 0,
KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;
Bạn có thể chỉ định thẻ này trong quá trình tạo khoá để yêu cầu khoá có thể sử dụng được trong điều kiện đã chỉ định. Bạn cần trả về khoá này cùng với các đặc điểm khoá từ generateKey và getKeyCharacteristics.
Nếu phương thức gọi chỉ định Tag::BLOB_USAGE_REQUIREMENTS với giá trị KeyBlobUsageRequirements::STANDALONE, thì trustlet sẽ trả về một blob khoá có thể được sử dụng mà không cần hỗ trợ hệ thống tệp. Điều này rất quan trọng đối với các thiết bị
với các ổ đĩa được mã hoá, trong đó hệ thống tệp có thể không sử dụng được cho đến
sau khi dùng khoá Keymaster để giải mã ổ đĩa.
Tag::BLOCK_MODE
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Có
Chỉ định các chế độ mật mã khối mà khoá có thể được sử dụng. Thẻ này chỉ liên quan đến khoá AES.
Các giá trị có thể có được xác định bằng cách liệt kê sau:
Keymaster 3
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
typedef enum {
KM_MODE_ECB = 1,
KM_MODE_CBC = 2,
KM_MODE_CTR = 3,
KM_MODE_GCM = 32,
} keymaster_block_mode_t;
Thẻ này có thể lặp lại và đối với các thao tác chính AES, hãy chỉ định chế độ trong
đối số additionalParams của
bắt đầu.
Nếu chế độ được chỉ định không nằm trong các chế độ được liên kết với khoá, thì
không thực hiện được thao tác với ErrorCode::INCOMPATIBLE_BLOCK_MODE.
Thẻ::BOOT_PATCHLEVEL
Phiên bản: 4
Tag::BOOT_PATCHLEVEL chỉ định cấp bản vá bảo mật của hình ảnh khởi động (hạt nhân) mà khoá có thể sử dụng. Thẻ này không bao giờ được gửi tới TA keymaster, nhưng
được TA thêm vào danh sách uỷ quyền do phần cứng thực thi. Mọi nỗ lực nhằm
hãy sử dụng khoá có giá trị Tag::BOOT_PATCHLEVEL khác với
mức bản vá hệ thống hiện đang chạy gây ra begin(),
getKeyCharacteristics() hoặc exportKey() để trả lại hàng
ErrorCode::KEY_REQUIRES_UPGRADE. Xem upgradeKey()
để biết thông tin chi tiết.
Giá trị của thẻ là một số nguyên có dạng YYYYMMDD, trong đó YYYY là năm gồm bốn chữ số của lần cập nhật gần đây nhất, MM là tháng gồm hai chữ số và DD là ngày hai chữ số của lần cập nhật gần đây nhất. Ví dụ: đối với khoá được tạo trên Thiết bị Android được cập nhật lần gần đây nhất vào ngày 5 tháng 6 năm 2018, giá trị sẽ là 20180605. Nếu không xác định ngày, số 00 có thể được thay thế.
Trong mỗi lần khởi động, trình tải khởi động phải cung cấp cấp bản vá của hình ảnh khởi động vào môi trường bảo mật (cơ chế được triển khai xác định).
Phải được thực thi phần cứng.
Tag::BOOTLOADER_ONLY
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ trình tải khởi động mới có thể sử dụng khoá này.
Thẻ này là boolean, vì vậy, các giá trị có thể có là true (nếu có thẻ) và false (nếu không có thẻ).
Bất kỳ lần nào cố gắng sử dụng một khoá với Tag::BOOTLOADER_ONLY trong
Hệ thống Android gặp lỗi ErrorCode::INVALID_KEY_BLOB.
Tag::CALLER_NONCE
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định rằng phương thức gọi có thể cung cấp số chỉ dùng một lần cho các thao tác yêu cầu số chỉ dùng một lần.
Thẻ này là boolean, vì vậy, các giá trị có thể có là true (nếu có thẻ) và false (nếu không có thẻ).
Thẻ này chỉ dùng cho khoá AES và chỉ liên quan cho CBC, CTR và GCM
chế độ khối. Nếu không có thẻ này thì quá trình triển khai sẽ từ chối mọi
hoạt động cung cấp Tag::NONCE để
bắt đầu
cùng với ErrorCode::CALLER_NONCE_PROHIBITED.
Thẻ::CREATION_DATETIME
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định ngày và giờ tạo khoá, tính bằng mili giây kể từ Ngày 1 tháng 1 năm 1970. Thẻ này là không bắt buộc và chỉ để cung cấp thông tin.
Thẻ:::
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Có
Chỉ định các thuật toán chuỗi đại diện có thể dùng với khoá để thực hiện ký và xác minh. Thẻ này liên quan đến RSA, ECDSA và Khoá HMAC.
Các giá trị có thể có được xác định bằng cách liệt kê sau:
Keymaster 3
enum class Digest : uint32_t {
NONE = 0,
MD5 = 1,
SHA1 = 2,
SHA_2_224 = 3,
SHA_2_256 = 4,
SHA_2_384 = 5,
SHA_2_512 = 6,
};
typedef enum {
KM_DIGEST_NONE = 0,
KM_DIGEST_MD5 = 1,
KM_DIGEST_SHA1 = 2,
KM_DIGEST_SHA_2_224 = 3,
KM_DIGEST_SHA_2_256 = 4,
KM_DIGEST_SHA_2_384 = 5,
KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;
Thẻ này có thể lặp lại. Đối với hoạt động ký và xác minh, hãy chỉ định
một chuỗi đại diện trong đối số additionalParams của
bắt đầu.
Nếu chuỗi đại diện được chỉ định không có trong các chuỗi đại diện liên kết với khoá, thì thao tác sẽ không thành công với ErrorCode::INCOMPATIBLE_DIGEST.
Tag::EC_CURVE
Phiên bản: 2, 3, 4
Có thể lặp lại? Không
Trong Keymaster 1, đường cong dùng cho các khoá EC được đoán từ khoá được chỉ định
kích thước. Để cải thiện tính linh hoạt trong tương lai, Keymaster 2 đã giới thiệu một
để chỉ định đường cong. Các yêu cầu tạo khoá EC có thể có
Tag::EC_CURVE, Tag::KEY_SIZE hoặc cả hai.
Các giá trị có thể có được xác định theo cách liệt kê sau đây:
Keymaster 3
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Nếu yêu cầu tạo chỉ chứa Tag::KEY_SIZE,
quay lại logic Keymaster 1, chọn đường cong NIST phù hợp.
Nếu yêu cầu chỉ chứa Tag::EC_CURVE, hãy sử dụng phương thức
đường cong được chỉ định. Đối với Keymaster 3 trở lên, các đường cong được xác định trong EcCurve. Đối với Keymaster 2 trở xuống, các đường cong được xác định trong keymaster_ec_curve_t.
Nếu yêu cầu chứa cả hai, hãy sử dụng hàm số do Tag::EC_CURVE chỉ định và xác thực rằng kích thước khoá được chỉ định phù hợp với hàm số đó. Nếu không, hãy trả về ErrorCode::INVALID_ARGUMENT.
Tag::INCLUDE_UNIQUE_ID
Phiên bản: 2, 3, 4
Có thể lặp lại? Không
Thẻ này được chỉ định trong quá trình tạo khoá để cho biết rằng chứng chỉ chứng thực cho khoá đã tạo phải chứa mã nhận dạng duy nhất của thiết bị trong phạm vi ứng dụng và có giới hạn thời gian, như được chỉ định bởi Tag::UNIQUE_ID.
Thẻ này là boolean, vì vậy các giá trị có thể có là true (nếu có thẻ này) và false (nếu không có thẻ).
Tag::KEY_SIZE
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định kích thước (tính bằng bit) của khoá, đo theo cách thông thường cho thuật toán của khoá. Ví dụ: đối với khoá RSA, Tag::KEY_SIZE chỉ định kích thước của mô-đun công khai. Đối với khoá AES, nó chỉ định độ dài của tài liệu khoá bí mật.
Thẻ::MAC_LENGTH
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Cung cấp độ dài yêu cầu của thẻ xác thực MAC hoặc GCM, tính bằng bit.
Giá trị là độ dài MAC tính bằng bit. Đây là bội số của 8 và ít nhất phải lớn bằng giá trị của Tag::MIN_MAC_LENGTH liên kết với khoá.
Thẻ::MAX_USES_PER_BOOT
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định số lần tối đa mà một khoá có thể được sử dụng giữa các lần khởi động lại hệ thống. Đây là một cơ chế khác để giới hạn tốc độ sử dụng khoá.
Giá trị này là một số nguyên 32 bit thể hiện số lần sử dụng mỗi lần khởi động.
Khi một khoá có thẻ này được sử dụng trong một thao tác, bộ đếm liên kết với khoá sẽ được tăng trong lệnh gọi bắt đầu. Sau khi bộ đếm khoá vượt quá giá trị này, tất cả các lần tiếp theo để sử dụng khoá sẽ không thành công với ErrorCode::MAX_OPS_EXCEEDED, cho đến khi thiết bị khởi động lại.
Điều này có nghĩa là một trustlet sẽ lưu giữ bảng bộ đếm sử dụng cho các khoá có thẻ này. Vì bộ nhớ Keymaster thường bị giới hạn, nên bảng này có thể có kích thước tối đa cố định và Keymaster có thể không thực hiện được các thao tác cố gắng sử dụng khoá có thẻ này khi bảng đã đầy. Bảng cần chứa ít nhất 16 khoá.
Nếu một thao tác không thành công do bảng đã đầy, Keymaster sẽ trả về ErrorCode::TOO_MANY_OPERATIONS.
Thẻ::MIN_MAC_LENGTH
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Thẻ này chỉ định độ dài MAC tối thiểu có thể được yêu cầu hoặc đã xác minh bằng khoá này cho khoá HMAC và khoá AES có hỗ trợ chế độ GCM.
Giá trị này là độ dài MAC tối thiểu, tính bằng bit. Đây là bội số của 8. Để Khoá HMAC, có giá trị tối thiểu là 64. Đối với khoá GCM, bạn phải có giá trị tối thiểu là 96 và không quá 128.
Thẻ::MIN_SECONDS_BETWEEN_OPS
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định khoảng thời gian tối thiểu trôi qua giữa các thao tác được phép bằng cách sử dụng một khoá. Bạn có thể dùng tính năng này để giới hạn tốc độ sử dụng khoá trong các ngữ cảnh mà việc sử dụng không giới hạn có thể cho phép các cuộc tấn công bằng phương thức brute force.
Giá trị này là một số nguyên 32 bit biểu thị số giây giữa các thao tác được phép.
Khi một khoá có thẻ này được sử dụng trong một thao tác, hãy bắt đầu một bộ hẹn giờ trong lệnh gọi finish (hoàn tất) hoặc abort (huỷ). Bất kỳ hạng nào
gọi để begin đó là
đã nhận được trước bộ tính giờ cho biết rằng khoảng thời gian được chỉ định bởi
Tag::MIN_SECONDS_BETWEEN_OPS đã trôi qua không thành công với
ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Điều này ngụ ý rằng một trustlet sẽ lưu giữ bảng bộ đếm sử dụng cho các khoá có thẻ này.
Do bộ nhớ Keymaster thường bị giới hạn, nên bảng này có thể có giá trị tối đa cố định
và Keymaster có thể không thực hiện được các thao tác cố gắng sử dụng khoá có thẻ này
khi bảng đã đầy. Bảng này phải chứa được ít nhất 32 người dùng đang sử dụng
và sử dụng lại đồng thời các ô bảng khi hết khoảng thời gian sử dụng khoá tối thiểu.
Nếu một thao tác không thành công do bảng đã đầy, Keymaster sẽ trả về
ErrorCode::TOO_MANY_OPERATIONS.
Thẻ::NO_ CHO_REQUIRED
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định rằng không cần xác thực để sử dụng khoá này. Thẻ này là loại trừ lẫn nhau bằng Thẻ::USER_SECURE_ID.
Thẻ này là boolean, vì vậy, các giá trị có thể có là true (nếu có thẻ) và false (nếu không có thẻ).
Thẻ::NONCE
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Cung cấp hoặc trả về vectơ khởi tạo hoặc số chỉ dùng một lần (IV) cho AES GCM, CBC, hoặc mã hoá/giải mã CTR. Thẻ này được cung cấp cho bắt đầu trong quá trình mã hoá và giải mã. Thông tin này chỉ được cung cấp cho bắt đầu nếu khoá có Thẻ::gdpr_NONCE. Nếu không được cung cấp, một số chỉ dùng một lần hoặc IV thích hợp được tạo ngẫu nhiên bởi Keymaster và trả về từ đầu.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý. Độ dài cho phép phụ thuộc vào chế độ: Số chỉ dùng một lần GCM có độ dài 12 byte; CBC và CTR IV là 16 byte.
Tag::ORIGIN
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định nơi tạo khoá, nếu biết. Không thể chỉ định thẻ này trong khi tạo hoặc nhập khoá và phải được thêm vào các đặc điểm chính bởi người tin cậy.
Keymaster 3Các giá trị có thể có được xác định trong
android::hardware::keymaster::v3_0::KeyOrigin:
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
Các giá trị có thể có được định nghĩa trong keymaster_origin_t:
typedef enum {
KM_ORIGIN_GENERATED = 0,
KM_ORIGIN_IMPORTED = 2,
KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t
Ý nghĩa đầy đủ của giá trị không chỉ phụ thuộc vào giá trị mà còn phụ thuộc vào việc liệu có trong danh sách đặc điểm được thực thi bằng phần cứng hoặc thực thi phần mềm.
GENERATED cho biết Keymaster đã tạo khoá.
Nếu nằm trong danh sách được thực thi phần cứng,
khoá này được tạo trong phần cứng bảo mật và bị liên kết vĩnh viễn với phần cứng. Nếu
trong danh sách được thực thi bằng phần mềm, khoá được tạo trong SoftKeymaster và
không bị ràng buộc bởi phần cứng.
DERIVED cho biết khoá này được lấy từ Keymaster.
Có khả năng tồn tại bên ngoài thiết bị.
IMPORTED cho biết khoá được tạo bên ngoài
của Keymaster và được nhập vào
Keymaster. Nếu nằm trong danh sách do phần cứng thực thi, thì khoá sẽ liên kết vĩnh viễn với phần cứng, mặc dù có thể có các bản sao bên ngoài phần cứng bảo mật. Nếu trong phần
phần mềm thực thi, khoá đã được nhập vào SoftKeymaster và không
ràng buộc phần cứng.
UNKNOWN chỉ nên xuất hiện trong danh sách được thực thi phần cứng.
Nó cho biết rằng khoá
ràng buộc phần cứng, nhưng không biết liệu khoá có được tạo ban đầu bằng
phần cứng bảo mật hoặc đã được nhập. Điều này chỉ xảy ra khi phần cứng keymaster0
đang được dùng để mô phỏng các dịch vụ keymaster1.
Tag::ORIGINATION_EXPIRE_DATETIME
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định ngày và giờ mà khoá hết hạn để ký và
cho mục đích mã hóa. Sau thời gian này, mọi nỗ lực sử dụng khoá có KeyPurpose::SIGN hoặc KeyPurpose::ENCRYPT được cung cấp để bắt đầu sẽ không thành công với ErrorCode::KEY_EXPIRED.
Giá trị này là một số nguyên 64 bit đại diện cho mili giây kể từ ngày 1 tháng 1 năm 1970.
Thẻ::OS_PATCHLEVEL
Phiên bản: 2, 3, 4
Có thể lặp lại? Không
Thẻ này không bao giờ được gửi đến TA keymaster, mà sẽ được thêm vào danh sách uỷ quyền do TA thực thi phần cứng.
Giá trị của thẻ là một số nguyên có dạng YYYYMM, trong đó YYYY là năm gồm bốn chữ số của lần cập nhật gần nhất và MM là hai chữ số của tháng cuối cùng cập nhật. Ví dụ: đối với khoá được tạo trên thiết bị Android lần gần nhất cập nhật sau Tháng 12 năm 2015, giá trị sẽ là 201512.
Bạn không thể sử dụng các khoá có cấp độ bản vá khác với cấp độ bản vá hiện tại. Việc cố gắng sử dụng khoá như vậy sẽ khiến begin, getKeyCharacteristics hoặc exportKey trả về ErrorCode::KEY_REQUIRES_UPGRADE. Xem
Liên kết phiên bản để biết thêm
chi tiết.
Thẻ::OS_VERSION
Phiên bản: 2, 3, 4
Có thể lặp lại? Không
Thẻ này không bao giờ được gửi đến TA keymaster, nhưng được TA thêm vào danh sách uỷ quyền do phần cứng thực thi.
Giá trị của thẻ là một số nguyên có dạng MMmmss, trong đó MM là mã chính số phiên bản, mm là số phiên bản nhỏ và ss là phiên bản nhỏ số. Ví dụ: đối với khoá được tạo trên Android phiên bản 4.0.3, giá trị sẽ là 040003.
Tag::PADDING
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Có
Chỉ định các chế độ đệm có thể dùng với khoá. Thẻ này là phù hợp với khoá RSA và AES.
Các giá trị có thể có được xác định theo cách liệt kê sau đây:
Keymaster 3
enum class PaddingMode : uint32_t {
NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
RSA_PKCS1_1_5_SIGN = 5,
PKCS7 = 64,
};
typedef enum {
KM_PAD_NONE = 1,
KM_PAD_RSA_OAEP = 2,
KM_PAD_RSA_PSS = 3,
KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
KM_PAD_PKCS7 = 64,
} keymaster_padding_t;
PaddingMode::RSA_OAEP và PaddingMode::RSA_PKCS1_1_5_ENCRYPT chỉ được dùng cho khoá mã hoá/giải mã RSA và chỉ định lần lượt khoảng đệm RSA PKCS#1v2 OAEP và khoảng đệm ngẫu nhiên RSA PKCS#1 v1.5.
PaddingMode::RSA_PSS và
PaddingMode::RSA_PKCS1_1_5_SIGN chỉ được dùng cho khoá ký/xác minh RSA và chỉ định khoảng đệm PSS
RSA PKCS#1v2 và khoảng đệm xác định trước RSA PKCS#1 v1.5 tương ứng.
Bạn có thể sử dụng PaddingMode::NONE với khoá RSA hoặc AES. Đối với khoá AES, nếu dùng PaddingMode::NONE
với chế độ khối ECB hoặc CBC và dữ liệu cần được mã hoá hoặc giải mã
không phải là bội số của kích thước khối AES, lệnh gọi để kết thúc
không thành công với ErrorCode::INVALID_INPUT_LENGTH.
Bạn chỉ có thể sử dụng PaddingMode::PKCS7 với các khoá AES và chỉ với chế độ ECB và CBC.
Bạn có thể lặp lại thẻ này. Chế độ khoảng đệm phải được chỉ định trong lệnh gọi đến
bắt đầu.
Nếu chế độ đã chỉ định không được uỷ quyền cho khoá, thì thao tác sẽ không thành công với ErrorCode::INCOMPATIBLE_BLOCK_MODE.
Thẻ::PURPOSE
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Có
Chỉ định tập hợp các mục đích mà khoá có thể được sử dụng.
Các giá trị có thể có được xác định bằng cách liệt kê sau:
Keymaster 3
enum class KeyPurpose : uint32_t {
ENCRYPT = 0,
DECRYPT = 1,
SIGN = 2,
VERIFY = 3,
DERIVE_KEY = 4, // since 3.0
WRAP_KEY = 5, // since 3.0
};
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
Thẻ này có thể lặp lại; có thể được tạo bằng nhiều giá trị,
mặc dù thao tác có mục đích duy nhất. Khi
hàm begin được gọi
để bắt đầu một thao tác, mục đích của thao tác đó sẽ được chỉ định.
Nếu mục đích được chỉ định cho hoạt động không được cho phép bởi
, thì thao tác sẽ không thành công với ErrorCode::INCOMPATIBLE_PURPOSE.
Thẻ::: reset_DEADLINE_ID_ROTATION
Phiên bản: 3, 4
Có thể lặp lại? Không
Chỉ định xem thiết bị có được đặt lại về trạng thái ban đầu kể từ lần xoay mã nhận dạng duy nhất gần đây nhất hay không. Dùng để chứng thực khoá.
Thẻ này là boolean, vì vậy, các giá trị có thể có là true (nếu có thẻ) và false (nếu không có thẻ).
Tag::ROLLBACK_RESISTANT
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Cho biết khoá có khả năng chống rollback, nghĩa là khi bị xoá bằng deleteKey hoặc deleteAllKeys, khoá sẽ được đảm bảo xoá vĩnh viễn và không thể sử dụng được. Có khả năng những khoá không có thẻ này có thể bị xoá rồi khôi phục từ bản sao lưu.
Thẻ này là boolean, vì vậy, các giá trị có thể có là true (nếu có thẻ) và false (nếu không có thẻ).
Thẻ::ROOT_OF_TRUST
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định gốc tin cậy, khoá mà tính năng khởi động đã xác minh sử dụng để xác thực hệ điều hành đã khởi động (nếu có). Thẻ này chưa bao giờ được cung cấp hoặc được trả về từ Keymaster trong phần đặc điểm chính.
Tag::RSA_PUBLIC_EXPONENT
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định giá trị của hệ số công khai cho một cặp khoá RSA. Thẻ này là chỉ liên quan đến khoá RSA và cần thiết cho mọi khoá RSA.
Giá trị là số nguyên 64 bit chưa ký đáp ứng các yêu cầu của
Số mũ công khai của RSA. Giá trị này phải là một số nguyên tố. Trustlet hỗ trợ giá trị 2^16+1 và có thể hỗ trợ các giá trị hợp lý khác, cụ thể là giá trị 3.
Nếu không có số mũ nào được chỉ định hoặc nếu số mũ đã chỉ định không được hỗ trợ,
không tạo được khoá bằng ErrorCode::INVALID_ARGUMENT.
Thẻ::UNIQUE_ID
Phiên bản: 3, 4
Có thể lặp lại? Không
Dùng để cung cấp mã nhận dạng duy nhất trong quy trình chứng thực.
Giá trị là một blob, một mảng byte có độ dài tuỳ ý.
Tag::USAGE_EXPIRE_DATETIME
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định ngày và giờ mà khoá hết hạn cho mục đích xác minh và giải mã. Sau thời gian này, bất kỳ lần thử dùng khoá nào có
Mục đích chính::XÁC MINH hoặc
KeyMục đích::DECRYPT được cung cấp cho
bắt đầu không thành công
cùng với ErrorCode::KEY_EXPIRED.
Giá trị là số nguyên 64 bit biểu thị mili giây kể từ Ngày 1 tháng 1 năm 1970.
Thẻ::USER_AUTH_TYPE
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Không
Chỉ định các loại trình xác thực người dùng có thể dùng để uỷ quyền cho khoá này. Khi Keymaster được yêu cầu thực hiện thao tác bằng khoá có khoá này
thẻ sẽ nhận được mã thông báo xác thực và mã thông báo
Trường authenticator_type cần phải khớp với giá trị trong thẻ.
Ví dụ: (ntoh(token.authenticator_type) &
auth_type_tag_value) != 0, trong đó ntoh là một hàm chuyển đổi số nguyên được sắp xếp theo mạng thành số nguyên được sắp xếp theo máy chủ lưu trữ và auth_type_tag_value là giá trị của thẻ này.
Giá trị này là một mặt nạ bit số nguyên 32 bit của các giá trị từ enum:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
typedef enum {
HW_AUTH_NONE = 0,
HW_AUTH_PASSWORD = 1 << 0,
HW_AUTH_FINGERPRINT = 1 << 1,
// Additional entries should be powers of 2.
HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;
Thẻ::USER_SECURE_ID
Phiên bản: 1, 2, 3, 4
Có thể lặp lại? Có
Chỉ định rằng khoá chỉ có thể được dùng cho một người dùng bảo mật cụ thể trạng thái xác thực. Thẻ này loại trừ lẫn nhau bằng Thẻ::NO_GCS_REQUIRED.
Giá trị là một số nguyên 64 bit chỉ định trạng thái của chính sách xác thực giá trị cần có trong mã thông báo xác thực (được cung cấp cho bắt đầu bằng Thẻ::XÁC_Mã_) để cho phép sử dụng khoá. Mọi lệnh gọi để bắt đầu bằng một khoá có thẻ này không cung cấp mã thông báo xác thực hoặc cung cấp mã thông báo xác thực không có giá trị trạng thái chính sách khớp sẽ không thành công.
Thẻ này có thể lặp lại. Nếu bất kỳ giá trị nào đã cung cấp khớp với bất kỳ chính sách nào
trong mã thông báo xác thực, thì khoá này đã được cho phép sử dụng.
Nếu không, thao tác sẽ không thực hiện được với
ErrorCode::KEY_USER_NOT_AUTHENTICATED.
Tag::VENDOR_PATCHLEVEL
Phiên bản: 4
Thẻ này chỉ định cấp bản vá bảo mật hình ảnh của nhà cung cấp mà khoá
có thể được sử dụng với. Thẻ này không bao giờ được gửi đến TA keymaster, mà sẽ được thêm vào
danh sách uỷ quyền do TA thực thi phần cứng. Bất kỳ lần nào cố gắng dùng khoá có
Giá trị Tag::VENDOR_PATCHLEVEL khác với giá trị hiện đang chạy
bản vá hệ thống phải gây ra begin(),
getKeyCharacteristics() hoặc exportKey() để trả lại hàng
ErrorCode::KEY_REQUIRES_UPGRADE. Xem upgradeKey()
để biết thông tin chi tiết.
Giá trị của thẻ là một số nguyên ở dạng YYYYMMDD, trong đó YYYY là năm gồm 4 chữ số của lần cập nhật gần đây nhất, MM là tháng gồm 2 chữ số và DD là ngày gồm 2 chữ số của lần cập nhật gần đây nhất. Ví dụ: đối với khoá được tạo trên Thiết bị Android được cập nhật lần gần đây nhất vào ngày 5 tháng 6 năm 2018, giá trị sẽ là 20180605.
HAL IKeymasterDevice phải đọc cấp bản vá hiện tại của nhà cung cấp từ hệ thống
thuộc tính ro.vendor.build.security_patch và phân phối thuộc tính đó đến
môi trường an toàn khi HAL được tải lần đầu (cơ chế
do phương thức triển khai xác định). Môi trường bảo mật không được chấp nhận cấp độ bản vá khác cho đến sau lần khởi động tiếp theo.
Phải được thực thi phần cứng.