Google cam kết thúc đẩy công bằng chủng tộc cho Cộng đồng người da đen. Xem cách thực hiện.

Thẻ ủy quyền Keymaster

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Trang này cung cấp thông tin chi tiết để hỗ trợ những người triển khai Keymaster HALs. Nó 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ư đã 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 / styles.hal cho Keymaster 3 và 4.0 / styles.hal cho Keymaster 4. Đối với Keymaster 2 trở xuống, các thẻ được định nghĩa 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

Lặp lại ? Không

Chỉ định ngày và giờ mà khóa sẽ 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 Mã lỗi ErrorCode::KEY_NOT_YET_VALID .

Giá trị 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ẻ :: THUẬT TOÁN

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

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 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

Lặp lại ? Không

Để dành mai sau dùng.

Thẻ :: ALLOW_WHILE_ON_BODY

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

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 có hy vọng rằng bất kỳ TEE nào sẽ 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ác cảm biến trên cơ thể rất an toàn, vì vậy đây được kỳ vọng 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

Lặp lại ? Không

Để dành mai sau dùng.

Thẻ :: APPLICATION_DATA

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

Lặp lại ? Không

Khi được cung cấp cho createKey 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 đến exportKeygetKeyCharacteristics cần phải 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 một dữ liệu được liên kết như một phần của tập hợp inParams . Nếu dữ liệu chính xác không được cung cấp, hàm 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à đối thủ không thể có quyền truy cập vào tất cả các bí mật thế giới an toàn nhưng không có quyền truy cập vào nội dung thẻ để giải mã khóa mà không cần é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ó hàm lượng entropy đủ cao.

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

Thẻ :: APPLICATION_ID

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

Lặp lại ? Không

Khi được cung cấp cho createKey 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 đến exportKeygetKeyCharacteristics 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 một dữ liệu được liên kết như một phần của tập hợp inParams . Nếu dữ liệu chính xác không được cung cấp, hàm 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à nó là kẻ thù có thể truy cập 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ẻ — không thể giải mã khóa (mà không có nội dung thẻ bắt buộc ).

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

Thẻ :: ASSOCIATED_DATA

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

Lặp lại ? Không

Cung cấp "dữ liệu được liên kết" để 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 đốm màu, một mảng byte có độ dài tùy ý.

Thẻ :: ATTESTATION_APPLICATION_ID

Phiên bản : 3, 4

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 đốm màu, một mảng byte có độ dài tùy ý.

Thẻ :: ATTESTATION_CHALLENGE

Phiên bản : 3, 4

Lặp lại ? Không

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

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

Thẻ :: ATTESTATION_ID_BRAND

Phiên bản : 3, 4

Lặp lại ? Không

Cung cấp tên thương hiệu của thiết bị, do Build.BRAND trả lại 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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_DEVICE

Phiên bản : 3, 4

Lặp lại ? Không

Cung cấp tên thiết bị của thiết bị, như được trả về bởi Build.DEVICE 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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_IMEI

Phiên bản : 3, 4

Lặp lại ? Đúng

Cung cấp IMEI cho tất cả các đài 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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_MANUFACTURER

Phiên bản : 3, 4

Lặp lại ? Không

Cung cấp tên nhà sản xuất của thiết bị, do Build.MANUFACTURER trả lại 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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_MEID

Phiên bản : 3, 4

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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_MODEL

Phiên bản : 3, 4

Lặp lại ? Không

Cung cấp tên kiểu máy của thiết bị, do Build.MODEL trả lại 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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_PRODUCT

Phiên bản : 3, 4

Lặp lại ? Không

Cung cấp tên sản phẩm của thiết bị, như được trả về bởi Build.PRODUCT 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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: ATTESTATION_ID_SERIAL

Phiên bản : 3, 4

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() trước đó đã được gọi và thiết bị không còn có thể chứng thực các ID của nó nữa), thì bất kỳ yêu cầu chứng thực khóa nào bao gồm thẻ này đều không thành công với Mã lỗi ErrorCode::CANNOT_ATTEST_IDS .

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

Thẻ :: AUTH_TIMEOUT

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

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 có Thẻ :: USER_SECURE_ID và không có thẻ này, 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ề quy trình xác thực cho mỗi thao tác).

Giá trị 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 đượ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

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

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 đã 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 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ừ createKeygetKeyCharacteristics . Nếu người gọi chỉ định Tag::BLOB_USAGE_REQUIREMENTS với giá trị KeyBlobUsageRequirements::STANDALONE thì Trustlet trả về một key blob có thể được sử dụng mà không cần hệ thống tệp hỗ trợ. Đ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 sau khi khóa Keymaster được sử dụng để giải mã đĩa.

Thẻ :: BLOCK_MODE

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

Lặp lại ? Đúng

Chỉ định (các) chế độ mật mã khối mà khóa có thể được sử dụng. Thẻ này chỉ liên quan đến các 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 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 phím AES chỉ định một chế độ trong đối số additionalParams sungParams của begin . Nếu mã được chỉ định không có trong các chế độ được liên kết với khóa, thì hoạt động không thành công với Mã lỗi ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Thẻ :: BOOT_PATCHLEVEL

Phiên bản : 4

Thẻ :: BOOT_PATCHLEVEL chỉ định mức vá bảo mật hình ảnh khởi động (nhân) mà khóa có thể được sử dụng. Thẻ này không bao giờ được gửi đến TA quản trị khóa, nhưng được TA thêm vào danh sách ủy quyền được thực thi bằng phần cứng. Bất kỳ nỗ lực nào sử dụng khóa có giá trị Tag::BOOT_PATCHLEVEL khác với giá trị cấp vá lỗi của hệ thống hiện đang chạy đều gây ra begin() , getKeyCharacteristics() hoặc exportKey() để trả về ErrorCode::KEY_REQUIRES_UPGRADE . Xem upgradeKey() để biết thêm chi tiết.

Giá trị của thẻ là một 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 cuối cùng, 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 cuối cùng. 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 xác định được ngày, 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 hình ảnh khởi động cho môi trường an toàn (cơ chế được xác định bởi việc 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

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à true (nếu thẻ có mặt) và false (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 Mã lỗi ErrorCode::INVALID_KEY_BLOB .

Thẻ :: CALLER_NONCE

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

Lặp lại ? Không

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

Thẻ này là boolean, vì vậy các giá trị có thể là true (nếu thẻ có mặt) và false (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 thẻ không có, việc triển khai sẽ từ chối bất kỳ hoạt động nào cung cấp Thẻ :: NONCE để bắt đầu bằng ErrorCode::CALLER_NONCE_PROHIBITED .

Thẻ :: CREATION_DATETIME

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

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ỉ là tùy chọn và chỉ mang tính thông tin.

Thẻ :: DIGEST

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

Lặp lại ? Đúng

Chỉ định các thuật toán thông báo có thể được sử dụng với khóa để thực hiện các hoạt động ký và xác minh. Thẻ này có 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 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 một thông báo trong đối additionalParams addParams của begin . 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 này không thành công với Mã lỗi ErrorCode::INCOMPATIBLE_DIGEST .

Thẻ :: EC_CURVE

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

Lặp lại ? Không

Trong Keymaster 1, đường cong được sử dụng cho các 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 khi di chuyển về phía trước, 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 một 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 đượ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ở 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 có phù hợp với đường cong đó không. Nếu không, hãy trả về ErrorCode::INVALID_ARGUMENT .

Thẻ :: INCLUDE_UNIQUE_ID

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

Lặp lại ? Không

Thẻ này được chỉ định trong quá trình tạo khóa để chỉ ra rằng chứng chỉ chứng thực cho khóa được tạo phải chứa ID duy nhất thiết bị có giới hạn thời gian và phạm vi ứng dụng, như được chỉ định bởi Thẻ :: UNIQUE_ID .

Thẻ này là boolean, vì vậy các giá trị có thể là true (nếu thẻ có mặt) và false (nếu không có thẻ).

Thẻ :: KEY_SIZE

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

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 cho 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

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 bằng giá trị của Thẻ :: 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

Lặp lại ? Không

Chỉ định số lần tối đa mà 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à một số nguyên 32 bit đại diện cho các lần sử dụng mỗi lần khởi động.

Khi một khóa có thẻ này được sử dụng trong một hoạt động, bộ đếm liên quan đến khóa sẽ được tăng lên trong khi bắt đầu cuộc gọi. Sau khi bộ đếm khóa vượt quá giá trị này, tất cả các nỗ lực tiếp theo để sử dụng khóa đều không thành công với Mã lỗ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 cho các khóa có thẻ này. Vì bộ nhớ Keymaster thường bị giới hạ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 có ít nhất 16 chìa khóa. Nếu một thao tác không thành công vì bảng đã đầy, Keymaster trả về Mã lỗi ErrorCode::TOO_MANY_OPERATIONS .

Thẻ :: MIN_MAC_LENGTH

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

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 cho các 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

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 một phím. Điều này có thể được sử dụng để giới hạn tỷ lệ sử dụng các khóa trong bối cảnh mà việc sử dụng không giới hạn có thể kích hoạt các cuộc tấn công bạo lực.

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

Thẻ :: NO_AUTH_REQUIRED

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

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 Thẻ :: USER_SECURE_ID .

Thẻ này là boolean, vì vậy các giá trị có thể là true (nếu thẻ có mặt) và false (nếu không có thẻ).

Thẻ :: NONCE

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

Lặp lại ? Không

Cung cấp hoặc trả về nonce hoặc vectơ 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ó Thẻ :: CALLER_NONCE . Nếu không được cung cấp, một 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 đốm màu, một mảng byte có độ dài tùy ý. Độ dài cho phép tùy thuộc vào chế độ: Các ký tự nonx GCM có độ dài 12 byte; CBC và CTR IV có độ dài 16 byte.

Thẻ :: XUẤT XỨ

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

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 thêm vào các đặc điểm chính của ủy thác.

Keymaster 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 tìm thấy trong danh sách các đặc điểm được thực thi bởi phần cứng hay phần mềm.

GENERATED chỉ ra rằng Keymaster đã tạo ra khóa. Nếu nằm trong danh sách do phần cứng thực thi, thì khóa được tạo trong phần cứng an toàn và bị ràng buộc vĩnh viễn với phần cứng. Nếu nằm trong danh sách do phần mềm thực thi, thì 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ó nguồn gốc bên trong Keymaster. Có thể tồn tại ngoài thiết bị.

IMPORTED chỉ ra rằng khóa được tạo bên ngoài Keymaster và được nhập vào Keymaster. Nếu nằm trong danh sách được thực thi bởi phần cứng, nó sẽ bị ràng buộc vĩnh viễn bởi 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 nằm 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 phần cứng.

UNKNOWN sẽ chỉ xuất hiện trong danh sách do phần cứng thực thi. 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 được tạo ban đầu trong phần cứng an toàn 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

Lặp lại ? Không

Chỉ định ngày và giờ mà 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 Mã lỗi ErrorCode::KEY_EXPIRED .

Giá trị 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

Lặp lại ? Không

Thẻ này không bao giờ được gửi đến TA quản trị khóa, nhưng được TA thêm vào danh sách ủy quyền được thực thi bằng 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 cuối cùng và MM là tháng có hai chữ số của lần cập nhật cuối cùng. 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.

Không thể sử dụng các khóa có cấp bản vá khác với cấp bản vá hiện tại. Nỗ lực sử dụng các nguyên nhân chính như vậy bắt đầu , getKeyCharacteristics hoặc exportKey để 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

Lặp lại ? Không

Thẻ này không bao giờ được gửi đến TA quản trị khóa, nhưng được TA thêm vào danh sách ủy quyền được thực thi bằng phần cứng.

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ẻ :: PADDING

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

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 các 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 các 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 về độ dài, 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 các chế độ ECB và CBC.

Thẻ này có thể lặp lại. Chế độ đệm phải được chỉ định trong cuộc gọi để bắt đầu . Nếu chế độ đã chỉ định không được ủy quyền cho khóa, thì hoạt động không thành công với Mã lỗi ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Thẻ :: MỤC ĐÍCH

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

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 hoạt động có một mục đích duy nhất. Khi hàm begin được gọi để bắt đầu một hoạt động, mục đích của hoạt động đượ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 Mã lỗi ErrorCode::INCOMPATIBLE_PURPOSE .

Thẻ :: RESET_SINCE_ID_ROTATION

Phiên bản : 3, 4

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 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à true (nếu thẻ có mặt) và false (nếu không có thẻ).

Thẻ :: ROLLBACK_RESISTANT

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

Lặp lại ? Không

Cho biết rằng 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ể xóa các khóa không có thẻ này và sau đó 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à true (nếu thẻ có mặt) và false (nếu không có thẻ).

Thẻ :: ROOT_OF_TRUST

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

Lặp lại ? Không

Chỉ định gốc của sự tin cậy , khóa được sử dụng bởi khởi động đã xác minh để 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

Lặp lại ? Không

Chỉ định giá trị của số mũ công khai cho một cặp khóa RSA. Thẻ này chỉ liên quan đến các khóa RSA và cần thiết cho tất cả các khóa RSA.

Giá trị là một 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à 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 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 không thành công với ErrorCode::INVALID_ARGUMENT .

Thẻ :: UNIQUE_ID

Phiên bản : 3, 4

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 đốm màu, một mảng byte có độ dài tùy ý.

Thẻ :: USAGE_EXPIRE_DATETIME

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

Lặp lại ? Không

Chỉ định ngày và giờ mà 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 để bắt đầu đều không thành công với Mã lỗi ErrorCode::KEY_EXPIRED .

Giá trị 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ẻ :: USER_AUTH_TYPE

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

Lặp lại ? Không

Chỉ định loại trình xác thực người dùng có thể được sử dụng để ủy quyền khóa này. Khi Keymaster được yêu cầu thực hiện một 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à một hàm chuyển đổi số nguyên theo thứ tự mạng thành số nguyên được sắp xếp theo thứ tự trên máy chủ và auth_type_tag_value là giá trị của thẻ này.

Giá trị là một mặt nạ bit số nguyên 32 bit của các giá trị từ kiểu 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

Lặp lại ? Không

Chỉ định rằng một khóa chỉ có thể được sử dụng trong một 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 Thẻ :: NO_AUTH_REQUIRED .

Giá trị là một số nguyên 64 bit chỉ định giá trị trạng thái chính sách xác thực cần phải có trong mã thông báo xác thực (được cung cấp để bắt đầu bằng Thẻ :: AUTH_TOKEN ) để cho phép sử dụng khóa. Bất kỳ lệnh 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 mà 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, hoạt động không thành công với Mã lỗi ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Thẻ :: 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à khóa có thể được sử dụng. Thẻ này không bao giờ được gửi đến TA quản trị khóa, nhưng được TA thêm vào danh sách ủy quyền được thực thi bằng phần cứng. Mọi nỗ lực sử dụng khóa có giá trị Tag::VENDOR_PATCHLEVEL khác với cấp vá lỗi hệ thống hiện đang chạy phải khiến begin() , getKeyCharacteristics() hoặc exportKey() trả về ErrorCode::KEY_REQUIRES_UPGRADE . Xem upgradeKey() để biết thêm chi tiết.

Giá trị của thẻ là một 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 cuối cùng, 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 cuối cùng. 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á lỗi 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 thực thi xác định). Môi trường an toàn không được chấp nhận một mức vá lỗi khác cho đến sau lần khởi động tiếp theo.

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