Thẻ ủy quyền của Keymaster

Trang này cung cấp thông tin chi tiết để hỗ trợ người triển khai Keymaster HAL. Nó bao gồm từng thẻ trong HAL, phiên bản Keymaster nào có sẵn thẻ đó và liệu thẻ có thể lặp lại hay không. Trừ khi được lưu ý trong phần mô tả thẻ, tất cả các thẻ bên dưới đều được sử dụng trong quá trình tạo khóa để chỉ định các đặc điểm chính.

Đối với Keymaster 4, các 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, các thẻ được xác định trong platform/hardware/libhardware/include/hardware/keymaster_defs.h .

Để biết các chức năng, hãy xem trang Chức năng Keymaster .

Thẻ::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à khóa bắt đầu hoạt động. Trước thời điểm này, mọi nỗ lực sử dụng khóa đều không thành công với ErrorCode::KEY_NOT_YET_VALID .

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.

Tag::thuật toán

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Chỉ định thuật toán mật mã mà khóa được sử dụng.

Các giá trị có thể đượ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,
};
Keymaster 2 trở về trước
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 mai sau dùng.

Thẻ::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 thời điểm này, không thể kỳ vọng rằng bất kỳ TEE nào cũng có thể cung cấp quyền truy cập an toàn vào 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 đây dự kiến ​​sẽ là một tính năng hoàn toàn được thực thi bằng phần mềm.

Thẻ::ALL_USERS

Phiên bản : 3, 4

Có thể lặp lại ? KHÔNG

Để dành mai sau dùng.

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 importKey , thẻ này chỉ định dữ liệu cần thiết trong tất cả các lần sử dụng khóa. Cụ thể, các lệnh gọi tớiexportKeygetKeyCharacteristics cần cung cấp cùng một giá trị cho tham 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 liên quan như một phần của bộ inParams . Nếu dữ liệu chính xác không được cung cấp, hàm sẽ trả về ErrorCode::INVALID_KEY_BLOB .

Nội dung của thẻ này được liên kết với khóa bằng mật mã , có nghĩa là kẻ thù có quyền truy cập vào tất cả các bí mật của thế giới an toàn nhưng không có quyền truy cập vào nội dung thẻ sẽ không thể giải mã được khóa mà không dùng vũ lực ép buộc thẻ nội dung mà ứng dụng có thể ngăn chặn bằng cách chỉ định nội dung có entropy đủ cao.

Giá trị là một blob, một mảng byte có độ dài tùy ý.

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 tất cả các lần sử dụng khóa. Cụ thể, các lệnh gọi tớiexportKeygetKeyCharacteristics cần cung cấp cùng một giá trị trong tham 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 liên quan như một phần của bộ inParams . Nếu dữ liệu chính xác không được cung cấp, hàm sẽ trả về ErrorCode::INVALID_KEY_BLOB .

Nội dung của thẻ này được liên kết với khóa bằng mật mã , nghĩa là kẻ thù có thể truy cập tất cả bí mật của thế giới an toàn—nhưng không có quyền truy cập vào nội dung thẻ—không thể giải mã khóa (không ép buộc nội dung thẻ). ).

Giá trị là một blob, một mảng byte có độ dài tùy ý.

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 liên quan" để mã hóa 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ã hóa/giải mã nhưng được sử dụng để tính toán thẻ GCM.

Giá trị là một blob, một mảng byte có độ dài tùy ý.

Thẻ::ATTESTATION_APPLICATION_ID

Phiên bản : 3, 4

Có thể lặp lại ? KHÔNG

Được sử 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 khóa.

Giá trị là một blob, một mảng byte có độ dài tùy ý.

Thẻ::ATTESTATION_CHALLENGE

Phiên bản : 3, 4

Có thể lặp lại ? KHÔNG

Được sử dụng để đưa ra thách thức trong việc chứng thực.

Giá trị là một blob, một mảng byte có độ dài tùy ý.

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 số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

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ị của 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 số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

Thẻ::ATTESTATION_ID_IMEI

Phiên bản : 3, 4

Có thể lặp lại ? Đúng

Cung cấp IMEI cho tất cả radio trên thiết bị. Trường này chỉ được đặt khi yêu cầu chứng thực số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

Thẻ::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 thiết bị, do Build.MANUFACTURER trả về trong Android. Trường này chỉ được đặt khi yêu cầu chứng thực số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

Thẻ::ATTESTATION_ID_MEID

Phiên bản : 3, 4

Có thể lặp lại ? Đúng

Cung cấp MEID cho tất cả các đài trên thiết bị. Trường này sẽ chỉ được đặt khi yêu cầu chứng thực số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

Thẻ::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 số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

Thẻ::ATTESTATION_ID_PRODVEL

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 số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

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 số nhận dạng của thiết bị.

Nếu thiết bị không hỗ trợ chứng thực ID (hoặc destroyAttestationIds() đã được gọi trước đó và thiết bị không còn có thể chứng thực ID của nó nữa), mọi yêu cầu chứng thực khóa bao gồm thẻ này đều 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 tùy ý.

Thẻ::AUTH_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à khóa được phép sử dụng sau khi xác thực. Nếu Thẻ::USER_SECURE_ID hiện diện và thẻ này không có thì khóa cần xác thực cho mỗi lần sử dụng (xem phần bắt đầu để biết chi tiết về luồng xác thực cho mỗi thao tác).

Giá trị là 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 được chỉ định bởi Tag::USER_SECURE_ID với phương thức xác thực được chỉ định bởi Tag::USER_AUTH_TYPE mà khóa có thể được sử dụng.

Thẻ::AUTH_TOKEN

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Cung cấp mã thông báo xác thực để bắt đầu , cập nhật hoặc kết thúc , để chứng minh xác thực người dùng cho một thao tác khóa yêu cầu nó (khóa có Tag::USER_SECURE_ID ).

Giá trị là một đốm màu chứa cấu trúc hw_auth_token_t .

Thẻ::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 khóa được tạo.

Các giá trị có thể được xác định bằng cách liệt kê sau:

Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 trở về trước
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

Thẻ này có thể được chỉ định trong quá trình tạo khóa để yêu cầu khóa có thể sử dụng được trong điều kiện đã chỉ định. Nó cần được trả về với các đặc điểm chính từ generateKeygetKeyCharacteristics . Nếu người gọi chỉ định Tag::BLOB_USAGE_REQUIREMENTS với giá trị KeyBlobUsageRequirements::STANDALONE thì ủy thác sẽ trả về một blob khóa 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ị có ổ đĩa được mã hóa, trong đó hệ thống tệp có thể không khả dụng cho đến khi sử dụng khóa Keymaster để giải mã ổ đĩa.

Thẻ::BLOCK_MODE

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? Đúng

Chỉ định (các) chế độ mã hóa khối mà khóa có thể được sử dụng. Thẻ này chỉ liên quan đến khóa AES.

Các giá trị có thể đượ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,
};
Keymaster 2 trở về trước
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 khóa AES, hãy chỉ định một chế độ trong đối số additionalParams của Begin . Nếu chế độ được chỉ định không nằm trong các chế độ được liên kết với khóa thì thao tác sẽ không thành công 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 hình ảnh khởi động (kernel) mà khóa có thể được sử dụng. Thẻ này không bao giờ được gửi đến TA keymaster mà được TA thêm vào danh sách ủy quyền do phần cứng thực thi. Bất kỳ nỗ lực nào nhằm sử dụng khóa có giá trị Tag::BOOT_PATCHLEVEL khác với patchlevel hệ thống hiện đang chạy sẽ khiến begin() , getKeyCharacteristics() exportKey() trả về ErrorCode::KEY_REQUIRES_UPGRADE . Xem upgradeKey() để biết chi tiết.

Giá trị của thẻ là số nguyên có dạng YYYYMMDD, trong đó YYYY là năm có bốn chữ số của lần cập nhật gần đây nhất, MM là tháng có hai chữ số và DD là ngày có hai chữ số của lần cập nhật gần đây nhất. Ví dụ: đối với khóa được tạo trên thiết bị Android được cập nhật lần cuối vào ngày 5 tháng 6 năm 2018, giá trị sẽ là 20180605. Nếu không biết ngày thì 00 có thể được thay thế.

Trong mỗi lần khởi động, bộ nạp khởi động phải cung cấp mức độ vá lỗi của ảnh khởi động cho môi trường an toàn (cơ chế được xác định theo cách triển khai).

Phải được thực thi bằng phần cứng.

Thẻ::BOOTLOADER_ONLY

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Chỉ định chỉ bộ nạp khởi động mới có thể sử dụng khóa.

Thẻ này là boolean, vì vậy các giá trị có thể là đúng (nếu có thẻ) và sai (nếu không có thẻ).

Mọi nỗ lực sử dụng khóa có Tag::BOOTLOADER_ONLY từ hệ thống Android đều không thành công với ErrorCode::INVALID_KEY_BLOB .

Thẻ::CALLER_NONCE

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Chỉ định rằng người gọi có thể cung cấp số nonce cho các hoạt động không yêu cầu.

Thẻ này là boolean, vì vậy các giá trị có thể là đúng (nếu có thẻ) và sai (nếu không có thẻ).

Thẻ này chỉ được sử dụng cho các khóa AES và chỉ liên quan đến các chế độ khối CBC, CTR và GCM. Nếu không có thẻ, quá trình triển khai sẽ từ chối mọi thao tác cung cấp Tag::NONCE để bắt đầu bằng 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ờ khóa được tạo, tính bằng mili giây kể từ ngày 1 tháng 1 năm 1970. Thẻ này chỉ mang tính tùy chọn và mang tính thông tin.

Thẻ::TIÊU HÓA

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? Đúng

Chỉ định các thuật toán tóm tắt có thể được sử dụng cùng với khóa để thực hiện các hoạt động ký và xác minh. Thẻ này liên quan đến các khóa RSA, ECDSA và HMAC.

Các giá trị có thể đượ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,
};
Keymaster 2 trở về trước
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 các hoạt động ký và xác minh, hãy chỉ định thông báo trong đối số additionalParams của started . Nếu thông báo được chỉ định không có trong thông báo được liên kết với khóa thì thao tác sẽ không thành công với ErrorCode::INCOMPATIBLE_DIGEST .

Thẻ::EC_CURVE

Phiên bản : 2, 3, 4

Có thể lặp lại ? KHÔNG

Trong Keymaster 1, đường cong được sử dụng cho khóa EC được đoán từ kích thước khóa được chỉ định. Để cải thiện tính linh hoạt trong tương lai, Keymaster 2 đã giới thiệu một cách rõ ràng để chỉ định các đường cong. Yêu cầu tạo khóa EC có thể có Tag::EC_CURVE , Tag::KEY_SIZE hoặc cả hai.

Các giá trị có thể được xác định bằng cách liệt kê sau:

Keymaster 3
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 trở về trước
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 , hãy quay lại logic Keymaster 1, chọn đường cong NIST thích hợp.

Nếu yêu cầu chỉ chứa Tag::EC_CURVE , hãy sử dụng đường cong đã 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ở về trước, 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 đường cong được chỉ định bởi Tag::EC_CURVE và xác thực rằng kích thước khóa được chỉ định phù hợp với đường cong đó. Nếu không, hãy trả về ErrorCode::INVALID_ARGUMENT .

Thẻ::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 khóa để cho biết rằng chứng chỉ chứng thực cho khóa được tạo phải chứa ID duy nhất của thiết bị trong phạm vi ứng dụng và 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ể là đúng (nếu có thẻ) và sai (nếu không có thẻ).

Thẻ::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 khóa, đo theo cách thông thường đối với thuật toán của khóa. Ví dụ: đối với khóa RSA, Tag::KEY_SIZE chỉ định kích thước của mô-đun công khai. Đối với khóa AES, nó chỉ định độ dài của vật liệu khóa 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 được 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. Nó 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 được liên kết với khóa.

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ột khóa 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 để sử dụng khóa giới hạn tỷ lệ.

Giá trị là số nguyên 32 bit biểu thị số lần sử dụng trên mỗi lần khởi động.

Khi một khóa có thẻ này được sử dụng trong một thao tác, bộ đếm liên quan đến khóa sẽ được tăng lên trong lệnh gọi bắt đầu . Sau khi bộ đếm khóa vượt quá giá trị này, tất cả các lần thử sử dụng khóa tiếp theo đều không thành công với ErrorCode::MAX_OPS_EXCEEDED cho đến khi thiết bị được khởi động lại. Điều này ngụ ý rằng một ủy thác giữ một bảng đếm sử dụng các khóa 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 các khóa có thẻ này khi bảng đầy. Bàn cần chứa ít nhất 16 phím. Nếu một thao tác không thành công do bảng đã đầy, Keymaster 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 tối thiểu của MAC có thể được yêu cầu hoặc xác minh bằng khóa này đối với khóa HMAC và khóa AES hỗ trợ chế độ GCM.

Giá trị này là độ dài MAC tối thiểu, tính bằng bit. Nó là bội số của 8. Đối với khóa HMAC, giá trị ít nhất là 64. Đối với khóa GCM, giá trị ít nhất 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 lượng thời gian tối thiểu trôi qua giữa các thao tác được phép sử dụng một phím. Điều này có thể được sử dụng để giới hạn tỷ lệ sử dụng khóa trong các bối cảnh mà việc sử dụng không giới hạn có thể tạo điều kiện cho các cuộc tấn công vũ phu.

Giá trị là số nguyên 32 bit biểu thị số giây giữa các hoạt động được phép.

Khi một phím có thẻ này được sử dụng trong một thao tác, hãy bắt đầu hẹn giờ trong khi kết thúc hoặc hủy cuộc gọi. Bất kỳ cuộc gọi bắt đầu nào được nhận trước bộ hẹn giờ đều 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 ủy thác giữ một bảng đếm sử dụng các khóa 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 các khóa có thẻ này khi bảng đầy. Bảng cần chứa ít nhất 32 khóa đang được sử dụng và tích cực sử dụng lại các vị trí trên bảng khi hết khoảng thời gian sử dụng tối thiểu của khóa. Nếu một thao tác không thành công do bảng đã đầy, Keymaster trả về ErrorCode::TOO_MANY_OPERATIONS .

Thẻ::NO_AUTH_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 khóa này. Thẻ này loại trừ lẫn nhau với Tag::USER_SECURE_ID .

Thẻ này là boolean, vì vậy các giá trị có thể là đúng (nếu có thẻ) và sai (nếu không có thẻ).

Thẻ::KHÔNG CÓ

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Cung cấp hoặc trả về một nonce hoặc Vector khởi tạo (IV) cho mã hóa hoặc giải mã AES GCM, CBC hoặc CTR. Thẻ này được cung cấp để bắt đầu trong quá trình mã hóa và giải mã. Nó chỉ được cung cấp để bắt đầu nếu khóa có Tag::CALLER_NONCE . Nếu không được cung cấp, nonce hoặc IV thích hợp sẽ được Keymaster tạo ngẫu nhiên và trả về từ đầu.

Giá trị là một blob, một mảng byte có độ dài tùy ý. Độ dài được phép tùy thuộc vào chế độ: nonces GCM có độ dài 12 byte; CBC và CTR IV có độ dài 16 byte.

Từ khóa::XUẤT XỨ

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Chỉ định nơi khóa được tạo, nếu biết. Thẻ này có thể không được chỉ định trong quá trình tạo hoặc nhập khóa và phải được ủy thác thêm vào các đặc điểm chính.

Chủ bàn phím 3

Các giá trị có thể được xác định trong android::hardware::keymaster::v3_0::KeyOrigin :

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 trở về trước

Các giá trị có thể được xác định 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 nó có được tìm thấy trong danh sách các đặc tính được thực thi bằng phần cứng hay phần mềm hay không.

GENERATED chỉ ra rằng Keymaster đã tạo khóa. Nếu trong danh sách được thực thi bằng phần cứng, khóa được tạo trong phần cứng bảo mật và bị ràng buộc phần cứng vĩnh viễn. Nếu trong danh sách được thực thi bằng phần mềm, khóa được tạo trong SoftKeymaster và không bị ràng buộc về phần cứng.

DERIVED chỉ ra rằng khóa được lấy từ Keymaster. Có khả năng tồn tại ngoài thiết bị.

IMPORTED cho biết rằng khóa được tạo bên ngoài Keymaster và được nhập vào Keymaster. Nếu trong danh sách được thực thi bằng phần cứng, nó bị ràng buộc vĩnh viễn về phần cứng, mặc dù có thể tồn tại các bản sao bên ngoài phần cứng an toàn. Nếu trong danh sách thực thi phần mềm, khóa đã được nhập vào SoftKeymaster và không bị ràng buộc về phần cứng.

UNKNOWN chỉ nên xuất hiện trong danh sách được thực thi bằng phần cứng. Nó chỉ ra rằng khóa bị ràng buộc phần cứng, nhưng không biết liệu khóa ban đầu được tạo trong phần cứng bảo mật hay đã được nhập. Điều này chỉ xảy ra khi phần cứng keymaster0 đang được sử dụng để mô phỏng các dịch vụ keymaster1.

Thẻ::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ờ khóa hết hạn cho mục đích ký và mã hóa. Sau thời gian này, mọi nỗ lực sử dụng khóa có KeyPurpose::SIGN hoặc KeyPurpose::ENCRYPT được cung cấp để bắt đầu đều không thành 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ẻ::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à được TA thêm vào danh sách ủy quyền do phần cứng thực thi.

Giá trị của thẻ là số nguyên có dạng YYYYMM, trong đó YYYY là năm có bốn chữ số của lần cập nhật gần đây nhất và MM là tháng có hai chữ số của lần cập nhật gần đây nhất. Ví dụ: đối với khóa được tạo trên thiết bị Android được cập nhật lần cuối vào tháng 12 năm 2015, giá trị sẽ là 201512.

Các khóa có cấp độ bản vá khác với cấp độ bản vá hiện tại sẽ không thể sử dụng được. Việc cố gắng sử dụng khóa như vậy sẽ khiến cho started , getKeyCharacteristics hoặcexportKey trả về ErrorCode::KEY_REQUIRES_UPGRADE . Xem Ràng buộc 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 mà được TA thêm vào danh sách ủy 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à số phiên bản chính, mm là số phiên bản phụ và ss là số phiên bản phụ. Ví dụ: đối với khóa được tạo trên Android phiên bản 4.0.3, giá trị sẽ là 040003.

Thẻ::ĐỆM

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? Đúng

Chỉ định các chế độ đệm có thể được sử dụng với phím. Thẻ này có liên quan đến khóa RSA và AES.

Các giá trị có thể được xác định bằng cách liệt kê sau:

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,
};
Keymaster 2 trở về trước
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_OAEPPaddingMode::RSA_PKCS1_1_5_ENCRYPT chỉ được sử dụng cho các khóa mã hóa/giải mã RSA và chỉ định phần đệm RSA PKCS#1v2 OAEP và phần đệm ngẫu nhiên RSA PKCS#1 v1.5 tương ứng. PaddingMode::RSA_PSSPaddingMode::RSA_PKCS1_1_5_SIGN chỉ được sử dụng cho các khóa ký/xác minh RSA và chỉ định phần đệm RSA PKCS#1v2 PSS và phần đệm xác định RSA PKCS#1 v1.5 tương ứng.

PaddingMode::NONE có thể được sử dụng với khóa RSA hoặc AES. Đối với khóa AES, nếu PaddingMode::NONE được sử dụng với chế độ khối ECB hoặc CBC và dữ liệu được mã hóa hoặc giải mã không phải là bội số của kích thước khối AES, thì lệnh gọi kết thúc không thành công với ErrorCode::INVALID_INPUT_LENGTH .

PaddingMode::PKCS7 chỉ có thể được sử dụng với các khóa AES và chỉ với chế độ ECB và CBC.

Thẻ này có thể lặp lại. Chế độ đệm phải được chỉ định trong lệnh gọi bắt đầu . Nếu chế độ đã chỉ định không được cấp phép cho khóa, thao tác sẽ không thành công với ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Thẻ::MỤC ĐÍCH

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? Đúng

Chỉ định tập hợp các mục đích mà khóa có thể được sử dụng.

Các giá trị có thể đượ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
};
Keymaster 2 trở về trước
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; khóa có thể được tạo với nhiều giá trị, mặc dù một thao tác chỉ có một mục đích. Khi hàm bắt đầu đượ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 thao tác không được khóa cho phép thì thao tác sẽ không thành công với ErrorCode::INCOMPATIBLE_PURPOSE .

Thẻ::RESET_SINCE_ID_ROTATION

Phiên bản : 3, 4

Có thể lặp lại ? KHÔNG

Chỉ định xem thiết bị đã được khôi phục cài đặt gốc kể từ lần xoay ID duy nhất gần đây nhất hay chưa. Được sử dụng để chứng thực chìa khóa.

Thẻ này là boolean, vì vậy các giá trị có thể là đúng (nếu có thẻ) và sai (nếu không có thẻ).

Thẻ::ROLLBACK_RESISTANT

Phiên bản : 1, 2, 3, 4

Có thể lặp lại ? KHÔNG

Cho biết khóa có khả năng chống khôi phục, nghĩa là khi bị xóa bởi deleteKey hoặc deleteAllKeys , khóa được đảm bảo sẽ bị xóa vĩnh viễn và không thể sử dụng được. Có thể các khóa không có thẻ này có thể bị xóa và sau đó được khôi phục từ bản sao lưu.

Thẻ này là boolean, vì vậy các giá trị có thể là đúng (nếu có thẻ) và sai (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 của sự tin cậy , khóa được xác minh boot sử dụng để xác thực hệ điều hành đã khởi động (nếu có). Thẻ này không bao giờ được cung cấp hoặc trả lại từ Keymaster trong các đặc điểm chính.

Thẻ::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 số mũ công khai cho cặp khóa RSA. Thẻ này chỉ liên quan đến khóa RSA và cần thiết cho tất cả các khóa RSA.

Giá trị là số nguyên không dấu 64 bit đáp ứng các yêu cầu của số mũ công khai RSA. Giá trị này phải là số nguyên tố. Trustlets hỗ trợ giá trị 2^16+1 và có thể hỗ trợ các giá trị hợp lý khác, đặc biệt là giá trị 3. Nếu không có số mũ nào được chỉ định hoặc nếu số mũ được chỉ định không được hỗ trợ, việc tạo khóa sẽ không thành công với ErrorCode::INVALID_ARGUMENT .

Thẻ::UNIQUE_ID

Phiên bản : 3, 4

Có thể lặp lại ? KHÔNG

Được sử dụng để cung cấp ID duy nhất trong chứng thực.

Giá trị là một blob, một mảng byte có độ dài tùy ý.

Thẻ::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ờ khóa hết hạn cho mục đích xác minh và giải mã. Sau thời gian này, mọi nỗ lực sử dụng khóa có KeyPurpose::VERIFY hoặc KeyPurpose::DECRYPT được cung cấp đều không thành 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ể được sử dụng để cấp phép cho khóa này. Khi Keymaster được yêu cầu thực hiện thao tác với khóa có thẻ này, nó sẽ nhận được mã thông báo xác thực và trường authenticator_type của mã thông báo cần khớp với giá trị trong thẻ. Ví dụ: (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , trong đó ntoh là hàm chuyển đổi số nguyên theo thứ tự mạng thành số nguyên theo thứ tự máy chủ và auth_type_tag_value là giá trị của thẻ này.

Giá trị là bitmask số nguyên 32 bit của các giá trị từ bảng liệt kê:

Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 trở về trước
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 ? KHÔNG

Chỉ định rằng một khóa chỉ có thể được sử dụng trong trạng thái xác thực người dùng an toàn cụ thể. Thẻ này loại trừ lẫn nhau với Tag::NO_AUTH_REQUIRED .

Giá trị này là số nguyên 64 bit chỉ định giá trị trạng thái chính sách xác thực cần có trong mã thông báo xác thực (được cung cấp để bắt đầu bằng Tag::AUTH_TOKEN ) để cho phép sử dụng khóa. Bất kỳ cuộc gọi nào bắt đầu bằng khóa 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 phù hợp đều không thành công.

Thẻ này có thể lặp lại. Nếu bất kỳ giá trị nào được cung cấp khớp với bất kỳ giá trị trạng thái chính sách nào trong mã thông báo xác thực thì khóa sẽ được phép sử dụng. Nếu không thì thao tác không thành công với ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Thẻ::VENDOR_PATCHLEVEL

Phiên bản : 4

Thẻ này chỉ định mức bản vá bảo mật hình ảnh của nhà cung cấp mà khóa có thể được sử dụng. Thẻ này không bao giờ được gửi đến TA keymaster mà được TA thêm vào danh sách ủy quyền do phần cứng thực thi. Mọi nỗ lực sử dụng khóa có giá trị Tag::VENDOR_PATCHLEVEL khác với patchlevel hệ thống hiện đang chạy đều phải khiến cho begin() , getKeyCharacteristics() exportKey() trả về ErrorCode::KEY_REQUIRES_UPGRADE . Xem upgradeKey() để biết chi tiết.

Giá trị của thẻ là số nguyên có dạng YYYYMMDD, trong đó YYYY là năm có bốn chữ số của lần cập nhật gần đây nhất, MM là tháng có hai chữ số và DD là ngày có hai chữ số của lần cập nhật gần đây nhất. Ví dụ: đối với khóa được tạo trên thiết bị Android được cập nhật lần cuối vào ngày 5 tháng 6 năm 2018, giá trị sẽ là 20180605.

IKeymasterDevice HAL phải đọc bản vá của nhà cung cấp hiện tại từ thuộc tính hệ thống ro.vendor.build.security_patch và phân phối nó đến môi trường an toàn khi HAL được tải lần đầu tiên (cơ chế được xác định khi triển khai). Môi trường an toàn không được chấp nhận một mức vá khác cho đến lần khởi động tiếp theo.

Phải được thực thi bằng phần cứng.