Thẻ uỷ quyền Keymaster

Trang này cung cấp thông tin chi tiết để hỗ trợ 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.

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à 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ị là một số nguyên 64 bit biểu thị mili giây kể từ ngày 1 tháng 1, Năm 1970.

Thẻ::ALGORITHM

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à khoá được sử dụng.

Các giá trị có thể có được xác định theo cách liệt kê sau đây:

Keymaster 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 trở xuống 
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.

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 nên dự kiến sẽ không có TEE nào có thể cung cấp chế độ 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 không cung cấp dữ liệu chính xác, hàm sẽ trả về ErrorCode::INVALID_KEY_BLOB.

Nội dung của thẻ này được liên kết với khoá bằng mã hoá, có nghĩa là không thể đối thủ cạnh tranh có quyền truy cập vào tất cả bảo mật thế giới, nhưng không có quyền truy cập vào nội dung thẻ để giải mã mà không cần buộc chặn nội dung thẻ. Các ứng dụng này có thể ngăn chặn bằng cách xác định nội dung entropy đủ 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 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ị trong thông số clientId và để bắt đầu cần được cung cấp thẻ này và cùng dữ liệu được liên kết 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 khoá bằng mã hoá, nghĩa là một đối thủ có thể tiếp cận mọi bí mật an toàn của thế giới — nhưng không có quyền truy cập vào nội dung thẻ—không thể giải mã khoá (không ép buộc 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 là đượ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 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 một tập hợp các ứng dụng có thể áp dụng của một đã bắt đầu quy trình chứng thực khoá.

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

Thẻ::ATTESTATION_CHALLENGE

Phiên bản: 3, 4

Có thể lặp lại? Không

Dùng để đưa ra thử thách trong quá 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 của mã 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 của mã 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_IMEI

Phiên bản: 3, 4

Có thể lặp lại? Có

Cung cấp số IMEI cho mọi đà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ợ 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_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ợ 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_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 sẽ 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_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ị, như được trả về bởi Build.MODEL 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_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ị, 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 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_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ợ 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ẻ::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 nhưng 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ị là một số nguyên 32 bit chỉ định thời gian tính bằng giây sau xác thực thành công người dùng do Tag::USER_SECURE_ID chỉ định bằng phương pháp xác thực do Tag::USER_XÁC_TYPE chỉ định rằng khoá có thể đã 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 xác thực mã để bắt đầu, cập nhật hoặc hoàn tất, chứng minh việc xác thực người dùng cho một thao tác khoá yêu cầu nó (khoá có Thẻ::USER_SECURE_ID).

Giá trị là một blob 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 cho thuộc tính để sử dụng.

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,
};
Keymaster 2 trở xuống 
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á phải có thể sử dụng được trong điều kiện được chỉ định. Cần phải trả về nó cùng với khoá đặc điểm của generateKey và getKeyCharacteristics. Nếu phương thức gọi chỉ định Tag::BLOB_USAGE_REQUIREMENTS bằng giá trị KeyBlobUsageRequirements::STANDALONE, tin cậy sẽ trả về một blob khoá có thể 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 hoạt động cho đến sau khi dùng khoá Keymaster để giải mã ổ đĩa.

Thẻ::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 theo cách liệt kê sau đây:

Keymaster 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 trở xuống 
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

Thẻ::BOOT_PATCHLEVEL chỉ định cấp bản vá bảo mật hình ảnh khởi động (hạt nhân) mà khoá có thể được 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.

Thẻ::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ẻ này) 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.

Thẻ::Call_NONCE

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

Có thể lặp lại? Không

Chỉ định việc 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ẻ này) 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, 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 theo cách liệt kê sau đây:

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ở xuống 
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 chuỗi đại diện liên kết với khoá, thì chuỗi đại diện này không thực hiện được thao tác 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 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,
};
Keymaster 2 trở xuống 
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 đường cong được chỉ định bởi Tag::EC_CURVE và xác thực rằng kích thước khoá được chỉ định là phù hợp với đường cong đó. Nếu không, hãy trả lại 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 khoá để cho biết rằng quá trình chứng thực chứng chỉ cho khoá được tạo phải chứa thông tin mã nhận dạng duy nhất của thiết bị có giới hạn thời gian, được chỉ định bởi Thẻ::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ẻ).

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 khoá, đo theo cách thông thường cho 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, tuỳ chọn này 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 thời lượng đượ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. Đây là bội số của 8 và với tối thiểu 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ột khoá có thể được sử dụng giữa hệ thống khởi động lại. Đây là một cơ chế khác để sử dụng khoá giới hạn số lượng yêu cầu.

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

Khi khoá có thẻ này được dùng trong một thao tác, bộ đếm liên kết với khoá sẽ được tăng lên trong bắt đầu. Sau khoá bộ đếm đã vượt quá giá trị này, tất cả các lần thử sử dụng khoá tiếp theo đều 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 chương trình tin cậy lưu giữ một bảng bộ đếm sử dụng cho các khoá bằng . Do bộ nhớ Keymaster thường bị giới hạn, bảng này có thể có mã và Keymaster có thể không thực hiện được các thao tác cố sử dụng khoá có thẻ này khi bảng đã đầy. Bảng 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 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. Cho 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 khoảng thời gian cho phép bằng cách sử dụng khoá. Có thể dùng tính năng này để giới hạn số lần sử dụng khoá trong ngữ cảnh Trong đó, 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 brute force.

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

Khi một khoá có thẻ này được dùng trong một thao tác, hãy bắt đầu hẹn giờ trong khi hoàn tất hoặc huỷ lệnh gọi. 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. Chiến dịch này ngụ ý rằng chương trình tin cậy lưu giữ một 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 các ô trong 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ẻ này) 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ề một số chỉ dùng một lần hoặc Vectơ khởi tạo (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 sẽ đượ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.

Thẻ::ORIGINAL

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. Thẻ này có thể không được chỉ định 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 3

Cá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,
};
Keymaster 2 trở xuống

Các giá trị có thể có đượ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 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 phần cứng.

DERIVED cho biết khoá này được lấy từ Keymaster. Có thể 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 trong danh sách được thực thi phần cứng, nó bị ràng buộc phần cứng vĩnh viễn, 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 được 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.

Thẻ::SOURCEATION_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, bất kỳ lần thử dùng khoá nào có Key Mục đích::SIGN hoặc KeyTarget::ENCRYPT được cung cấp không thể bắt đầu cùng với ErrorCode::KEY_EXPIRED.

Giá trị là một 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à 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.

Những khoá có cấp bản vá khác với cấp bản vá hiện tại hữu dụng. Việc cố gắng sử dụng một khoá như vậy là nguyên nhân bắt đầu! 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, 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 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.

Thẻ::PADDING

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

Có thể lặp lại? Có

Chỉ định các chế độ khoảng đệ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,
};
Keymaster 2 trở xuống 
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à Dùng PaddingMode::RSA_PKCS1_1_5_ENCRYPT chỉ dành cho khoá mã hoá/giải mã RSA và chỉ định RSA PKCS#1v2 OAEP đệm và khoảng đệm ngẫu nhiên RSA PKCS#1 v1.5, tương ứng. PaddingMode::RSA_PSS và PaddingMode::RSA_PKCS1_1_5_SIGN chỉ được dùng cho RSA khoá ký/xác minh và chỉ định RSA PKCS#1v2 PSS khoảng đệm và khoảng đệm xác định RSA PKCS#1 v1.5, tương ứng.

Có thể dùng PaddingMode::NONE với RSA hoặc khoá 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 về chiều dài, lệnh gọi để kết thúc không thành công với ErrorCode::INVALID_INPUT_LENGTH.

Chỉ có thể dùng PaddingMode::PKCS7 với khoá AES và chỉ với các chế độ ECB và CBC.

Thẻ này có thể lặp lại. 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 cấp phép cho khoá, thao tác sẽ không thành công 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 nhóm mục đích mà khoá có thể được sử dụng.

Các giá trị có thể có được xác định theo cách liệt kê sau đây:

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ở xuống 
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 đặt lại về trạng thái ban đầu hay chưa kể từ lần xoay vòng mã nhận dạng duy nhất gần nhất. 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ẻ này) và false (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 khoá có khả năng khôi phục, tức là khi bị xoá bằng deleteKey hoặc deleteAllKeys, chúng tôi đảm bảo khoá sẽ bị xoá vĩnh viễn và không 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ẻ này) 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 của sự tin cậy, khoá được quy trình xác minh quy trình khởi động 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.

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 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à số nguyên tố. Quỹ tín thác 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ũ đã 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 giá trị 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ỳ ý.

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ờ mà khoá hết hạn để xác minh và cho mục đích 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à một số nguyên 64 bit biểu thị mili giây kể từ Ngày 1 tháng 1 năm 1970.

Thẻ::USER_GCS_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 để cho phép . 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 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à một mặt nạ bit số nguyên 32 bit của các giá trị từ bản 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ở xuống 
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 sử dụng theo 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á. Bất kỳ hạng nào gọi để bắt đầu bằng khóa có thẻ này mà 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 trùng khớp thì 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.

Thẻ::bổ sung 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 sử dụng có thể được sử dụ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. 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 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.

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 một patchlevel cho đến sau lần khởi động tiếp theo.

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