Hàm Keymaster

Trang này cung cấp thông tin chi tiết để hỗ trợ những người triển khai Lớp trừu tượng phần cứng (HAL) Keymaster. Tài liệu này trình bày về từng hàm trong API và phiên bản Keymaster có chứa hàm đó, đồng thời mô tả cách triển khai mặc định. Đối với thẻ, hãy xem trang Thẻ Keymaster.

Lưu ý: Để hỗ trợ quá trình chuyển đổi của Keymaster 3 từ HAL cấu trúc C kiểu cũ sang giao diện HAL C++ được tạo từ một định nghĩa trong Ngôn ngữ định nghĩa giao diện phần cứng (HIDL) mới, tên hàm đã thay đổi trong Android 8.0. Để hỗ trợ việc này, các hàm hiện được viết theo kiểu camel case. Ví dụ: get_key_characteristics hiện là getKeyCharacteristics.

Nguyên tắc chung về việc triển khai

Các nguyên tắc sau đây áp dụng cho tất cả hàm trong API.

Tham số con trỏ đầu vào

Phiên bản: 1, 2

Các tham số con trỏ đầu vào không được dùng cho một lệnh gọi nhất định có thể là NULL. Phương thức gọi không bắt buộc phải cung cấp phần giữ chỗ. Ví dụ: một số loại và chế độ khoá có thể không sử dụng bất kỳ giá trị nào từ đối số inParams để bắt đầu. Vì vậy, phương thức gọi có thể đặt inParams thành NULL hoặc cung cấp một tập hợp tham số trống. Phương thức gọi cũng có thể cung cấp các tham số không dùng đến và phương thức Keymaster không được phát hành lỗi.

Nếu tham số đầu vào bắt buộc là NULL, thì các phương thức Keymaster sẽ trả về ErrorCode::UNEXPECTED_NULL_POINTER.

Kể từ Keymaster 3, không có tham số con trỏ nào. Tất cả tham số được truyền theo giá trị hoặc tham chiếu const.

Tham số con trỏ đầu ra

Phiên bản: 1, 2

Tương tự như tham số con trỏ đầu vào, tham số con trỏ đầu ra không dùng đến có thể là NULL. Nếu một phương thức cần trả về dữ liệu trong một tham số đầu ra được tìm thấy là NULL, thì phương thức đó sẽ trả về ErrorCode::OUTPUT_PARAMETER_NULL.

Kể từ Keymaster 3, không có tham số con trỏ. Tất cả tham số được truyền theo giá trị hoặc tham chiếu const.

Sử dụng API sai mục đích

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

Có nhiều cách mà phương thức gọi có thể đưa ra các yêu cầu không hợp lý hoặc ngu ngốc nhưng không sai về mặt kỹ thuật. Việc triển khai Keymaster không bắt buộc phải không thành công trong những trường hợp như vậy hoặc đưa ra chẩn đoán. Việc sử dụng khoá quá nhỏ, thông số kỹ thuật của các tham số đầu vào không liên quan, sử dụng lại IV hoặc số chỉ dùng một lần, tạo khoá không có mục đích (do đó không hữu ích) và các vấn đề tương tự không được chẩn đoán bằng cách triển khai. Bạn cần phải chẩn đoán việc thiếu tham số bắt buộc, quy cách của tham số bắt buộc không hợp lệ và các lỗi tương tự.

Ứng dụng, khung và kho khoá Android có trách nhiệm đảm bảo rằng các lệnh gọi đến mô-đun Keymaster là hợp lý và hữu ích.

Thận trọng: Việc triển khai Keymaster nên cố gắng chẩn đoán các lỗi nghiêm trọng, chẳng hạn như bỏ qua các tham số bắt buộc, chỉ định các tham số bắt buộc không hợp lệ và các lỗi tương tự làm tổn hại đến tính toàn vẹn của việc triển khai Keymaster.

Hàm

getHardwareFeatures

Phiên bản: 3

Phương thức getHardwareFeatures mới hiển thị cho ứng dụng một số đặc điểm quan trọng của phần cứng bảo mật cơ bản. Phương thức này không nhận đối số và trả về 4 giá trị, tất cả đều là boolean:

• isSecure là true nếu khoá được lưu trữ trong phần cứng bảo mật (TEE, v.v.) và không bao giờ rời khỏi phần cứng đó.
• supportsEllipticCurve là true nếu phần cứng hỗ trợ tiêu chuẩn mã hoá Đường cong Elliptic với các đường cong NIST (P-224, P-256, P-384 và P-521).
• supportsSymmetricCryptography là true nếu phần cứng hỗ trợ phương thức mã hoá đối xứng, bao gồm cả AES và HMAC.
• supportsAttestation là true nếu phần cứng hỗ trợ việc tạo chứng chỉ chứng thực khoá công khai Keymaster, được ký bằng khoá được chèn trong môi trường bảo mật.

Các mã lỗi duy nhất mà phương thức này có thể trả về là ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED hoặc một trong các mã lỗi cho biết không thể giao tiếp với phần cứng bảo mật.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

định cấu hình

Phiên bản: 2

Hàm này được giới thiệu trong Keymaster 2 và không còn được dùng trong Keymaster 3, vì thông tin này có trong các tệp thuộc tính hệ thống và các hoạt động triển khai của nhà sản xuất sẽ đọc các tệp đó trong quá trình khởi động.

Định cấu hình keymaster. Phương thức này được gọi một lần sau khi mở thiết bị và trước khi sử dụng thiết bị. Thuộc tính này dùng để cung cấp KM_TAG_OS_VERSION và KM_TAG_OS_PATCHLEVEL cho keymaster. Cho đến khi phương thức này được gọi, tất cả các phương thức khác sẽ trả về KM_ERROR_KEYMASTER_NOT_CONFIGURED. Các giá trị do phương thức này cung cấp chỉ được keymaster chấp nhận một lần mỗi khi khởi động. Các lệnh gọi tiếp theo sẽ trả về KM_ERROR_OK nhưng không làm gì cả.

Nếu phương thức triển khai keymaster nằm trong phần cứng bảo mật và phiên bản hệ điều hành cũng như giá trị cấp bản vá được cung cấp không khớp với giá trị mà trình tải khởi động cung cấp cho phần cứng bảo mật (hoặc nếu trình tải khởi động không cung cấp giá trị), thì phương thức này sẽ trả về KM_ERROR_INVALID_ARGUMENT và tất cả các phương thức khác sẽ tiếp tục trả về KM_ERROR_KEYMASTER_NOT_CONFIGURED.

keymaster_error_t (*configure)(const struct keymaster2_device* dev,
                               const keymaster_key_param_set_t* params);

addRngEntropy

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng add_rng_entropy và được đổi tên trong Keymaster 3.

Thêm entropy do phương thức gọi cung cấp vào nhóm được sử dụng theo quy trình triển khai Keymaster 1 để tạo số ngẫu nhiên cho các khoá, IV, v.v.

Các hoạt động triển khai Keymaster cần phải trộn lẫn entropy được cung cấp một cách an toàn vào nhóm của chúng, đồng thời nhóm này cũng phải chứa entropy được tạo nội bộ từ trình tạo số ngẫu nhiên phần cứng. Bạn nên xử lý việc trộn để kẻ tấn công có toàn quyền kiểm soát các bit do addRngEntropy cung cấp hoặc các bit do phần cứng tạo ra, nhưng không phải cả hai, không có lợi thế đáng kể nào trong việc dự đoán các bit được tạo từ nhóm entropy.

Các phương thức triển khai Keymaster cố gắng ước tính entropy trong nhóm nội bộ giả định rằng dữ liệu do addRngEntropy cung cấp không chứa entropy. Các phương thức triển khai Keymaster có thể trả về ErrorCode::INVALID_INPUT_LENGTH nếu được cung cấp hơn 2 KiB dữ liệu trong một lệnh gọi.

generateKey

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng generate_key và được đổi tên trong Keymaster 3.

Tạo một khoá mã hoá mới, chỉ định các quyền truy cập được liên kết, được liên kết vĩnh viễn với khoá. Việc triển khai Keymaster khiến bạn không thể sử dụng khoá theo bất kỳ cách nào không nhất quán với các quyền uỷ quyền được chỉ định tại thời điểm tạo. Đối với các quyền truy cập mà phần cứng bảo mật không thể thực thi, nghĩa vụ của phần cứng bảo mật chỉ giới hạn ở việc đảm bảo rằng các quyền truy cập không thực thi được liên kết với khoá không thể được sửa đổi, để mọi lệnh gọi đến getKeyCharacteristics đều trả về giá trị ban đầu. Ngoài ra, các đặc điểm do generateKey trả về sẽ phân bổ các hoạt động uỷ quyền một cách chính xác giữa danh sách được thực thi phần cứng và danh sách được thực thi bằng phần mềm. Hãy xem phần getKeyCharacteristics để biết thêm thông tin chi tiết.

Các tham số được cung cấp cho generateKey phụ thuộc vào loại khoá đang được tạo. Phần này tóm tắt các thẻ cần thiết và không bắt buộc cho từng loại khoá. Tag::ALGORITHM luôn cần thiết để chỉ định loại.

Khoá RSA

Bạn cần có các tham số sau để tạo khoá RSA.

• Tag::KEY_SIZE chỉ định kích thước của mô-đun công khai, tính bằng bit. Nếu bị bỏ qua, phương thức này sẽ trả về ErrorCode::UNSUPPORTED_KEY_SIZE. Các giá trị được hỗ trợ là 1024, 2048, 3072 và 4096. Các giá trị được đề xuất là tất cả kích thước khoá đều là bội số của 8.
• Tag::RSA_PUBLIC_EXPONENT chỉ định giá trị số mũ công khai RSA. Nếu bị bỏ qua, phương thức này sẽ trả về ErrorCode::INVALID_ARGUMENT. Các giá trị được hỗ trợ là 3 và 65537. Giá trị đề xuất là tất cả giá trị số nguyên tố, tối đa là 2^64.

Bạn không cần các tham số sau để tạo khoá RSA, nhưng việc tạo khoá RSA mà không có các tham số này sẽ tạo ra một khoá không sử dụng được. Tuy nhiên, hàm generateKey sẽ không trả về lỗi nếu bạn bỏ qua các tham số này.

• Thẻ::PURPOSE xác định các mục đích được phép. Tất cả các mục đích đều cần được hỗ trợ cho khoá RSA, theo mọi cách kết hợp.
• Tag::DIGEST chỉ định các thuật toán chuỗi đại diện có thể dùng với khoá mới. Các phương thức triển khai không hỗ trợ tất cả thuật toán chuỗi đại diện cần chấp nhận các yêu cầu tạo khoá bao gồm chuỗi đại diện không được hỗ trợ. Bạn nên đặt các chuỗi đại diện không được hỗ trợ trong danh sách "được thực thi phần mềm" trong phần đặc điểm chính được trả về. Điều này là do khoá có thể sử dụng được với các chuỗi đại diện khác đó, nhưng việc tạo chuỗi đại diện được thực hiện trong phần mềm. Sau đó, phần cứng được gọi để thực hiện thao tác bằng Digest::NONE.
• Tag::PADDING chỉ định các chế độ khoảng đệm có thể dùng với khoá mới. Các phương thức triển khai không hỗ trợ tất cả thuật toán chuỗi đại diện cần đặt PaddingMode::RSA_PSS và PaddingMode::RSA_OAEP vào danh sách các đặc điểm chính do phần mềm thực thi nếu có bất kỳ thuật toán chuỗi đại diện nào không được hỗ trợ.

Khoá ECDSA

Bạn chỉ cần có Tag::KEY_SIZE để tạo khoá ECDSA. Dùng để chọn nhóm EC. Các giá trị được hỗ trợ là 224, 256, 384 và 521, tương ứng với các đường cong NIST p-224, p-256, p-384 và p521.

Tag::DIGEST cũng cần thiết cho một khoá ECDSA hữu ích, nhưng không bắt buộc phải tạo.

Khoá AES

Bạn chỉ cần Tag::KEY_SIZE để tạo khoá AES. Nếu bị bỏ qua, phương thức này sẽ trả về ErrorCode::UNSUPPORTED_KEY_SIZE. Các giá trị được hỗ trợ là 128 và 256, với khả năng hỗ trợ không bắt buộc cho khoá AES 192 bit.

Các tham số sau đây đặc biệt phù hợp với khoá AES, nhưng không cần thiết để tạo:

• Tag::BLOCK_MODE chỉ định các chế độ khối mà bạn có thể sử dụng khoá mới.
• Tag::PADDING chỉ định các chế độ khoảng đệm có thể sử dụng. Điều này chỉ áp dụng cho chế độ ECB và CBC.

Nếu bạn chỉ định chế độ chặn GCM, hãy cung cấp Tag::MIN_MAC_LENGTH. Nếu bị bỏ qua, phương thức này sẽ trả về ErrorCode::MISSING_MIN_MAC_LENGTH. Giá trị của thẻ là bội số của 8 và nằm trong khoảng từ 96 đến 128.

Khoá HMAC

Các tham số sau đây là bắt buộc để tạo khoá HMAC:

• Tag::KEY_SIZE chỉ định kích thước khoá theo bit. Chúng tôi sẽ không hỗ trợ những giá trị nhỏ hơn 64 và những giá trị không phải là bội số của 8. Tất cả các bội số của 8, từ 64 đến 512 đều được hỗ trợ. Các giá trị lớn hơn có thể được hỗ trợ.
• Tag::MIN_MAC_LENGTH chỉ định độ dài tối thiểu của MAC có thể được tạo hoặc xác minh bằng khoá này. Giá trị là bội số của 8 và ít nhất là 64.
• Tag::DIGEST chỉ định thuật toán tổng hợp cho khoá. Chỉ định đúng một chuỗi đại diện, nếu không thì trả về ErrorCode::UNSUPPORTED_DIGEST. Nếu trustlet không hỗ trợ chuỗi đại diện, hãy trả về ErrorCode::UNSUPPORTED_DIGEST.

Đặc điểm chính

Nếu đối số đặc điểm không phải là NULL, generateKey sẽ trả về các đặc điểm của khoá mới tạo được chia thành danh sách được thực thi bằng phần cứng và danh sách được thực thi bằng phần mềm. Hãy xem getKeyCharacteristics để biết nội dung mô tả về những đặc điểm sẽ thuộc danh sách nào. Các đặc điểm được trả về bao gồm tất cả các tham số được chỉ định để tạo khoá, ngoại trừ Tag::APPLICATION_ID và Tag::APPLICATION_DATA. Nếu các thẻ này có trong tham số khoá, thì các thẻ này sẽ bị xoá khỏi các đặc điểm được trả về để không thể tìm thấy giá trị của các thẻ đó bằng cách kiểm tra blob khoá được trả về. Tuy nhiên, các giá trị này được liên kết bằng phương thức mã hoá với blob khoá, vì vậy, nếu bạn không cung cấp đúng giá trị khi sử dụng khoá, thì việc sử dụng sẽ không thành công. Tương tự, Tag::ROOT_OF_TRUST được liên kết bằng mật mã với khoá, nhưng không thể được chỉ định trong quá trình tạo hoặc nhập khoá và không bao giờ được trả về.

Ngoài các thẻ được cung cấp, bộ tin cậy cũng thêm Tag::ORIGINAL với giá trị KeyOrigin::GENERATED và nếu khoá có khả năng chống khôi phục,

Tag::ROLLBACK_RESISTANT.

Tính năng chống khôi phục

Khả năng chống rollback (hoạt động khôi phục phiên bản cũ) có nghĩa là sau khi một khoá bị xoá bằng deleteKey hoặc deleteAllKeys, phần cứng bảo mật sẽ đảm bảo rằng khoá đó không bao giờ được sử dụng lại. Các phương thức triển khai không có khả năng chống lại việc khôi phục thường trả về tài liệu khoá đã tạo hoặc nhập cho phương thức gọi dưới dạng blob khoá, một biểu mẫu đã mã hoá và được xác thực. Khi kho khoá xoá blob khoá, khoá này sẽ biến mất, nhưng kẻ tấn công trước đó đã tìm được cách truy xuất nội dung khoá có thể khôi phục khoá đó về thiết bị.

Khoá có khả năng chống khôi phục nếu phần cứng bảo mật đảm bảo rằng sau này bạn sẽ không khôi phục được khoá đã xoá. Thông thường, việc này được thực hiện bằng cách lưu trữ siêu dữ liệu khoá bổ sung ở một vị trí đáng tin cậy mà kẻ tấn công không thể thao túng. Trên thiết bị di động, cơ chế dùng cho việc này thường là Khối bộ nhớ được bảo vệ chống phát lại (RPMB). Vì số lượng khoá có thể tạo về cơ bản là không giới hạn và bộ nhớ đáng tin cậy dùng để chống lại việc khôi phục có thể bị giới hạn về kích thước, nên phương thức này cần thành công ngay cả khi không thể cung cấp khả năng chống lại việc khôi phục cho khoá mới. Trong trường hợp đó, bạn không nên thêm Tag::ROLLBACK_RESISTANT vào các đặc điểm chính.

getKeyCharacteristics

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng get_key_characteristics và được đổi tên trong Keymaster 3.

Trả về các thông số và quyền được liên kết với khoá đã cung cấp, được chia thành hai nhóm: do phần cứng thực thi và do phần mềm thực thi. Nội dung mô tả ở đây áp dụng tương tự cho các danh sách đặc điểm chính do generateKey và importKey trả về.

Nếu bạn đã cung cấp Tag::APPLICATION_ID trong quá trình tạo hoặc nhập khoá, thì giá trị tương tự sẽ được cung cấp cho phương thức này trong đối số clientId. Nếu không, phương thức này sẽ trả về ErrorCode::INVALID_KEY_BLOB. Tương tự, nếu Tag::APPLICATION_DATA được cung cấp trong quá trình tạo hoặc nhập, thì giá trị tương tự sẽ được cung cấp cho phương thức này trong đối số appData.

Các đặc điểm do phương thức này trả về mô tả đầy đủ loại và cách sử dụng khoá được chỉ định.

Quy tắc chung để quyết định xem một thẻ nhất định có thuộc danh sách do phần cứng thực thi hay do phần mềm thực thi hay không là nếu ý nghĩa của thẻ được đảm bảo đầy đủ bằng phần cứng bảo mật, thì thẻ đó sẽ do phần cứng thực thi. Nếu không, hệ thống sẽ thực thi bằng phần mềm. Dưới đây là danh sách các thẻ cụ thể có thể không rõ cách phân bổ chính xác:

• Tag::ALGORITHM, Tag::KEY_SIZE, và Tag::RSA_PUBLIC_EXPONENT là các thuộc tính nội tại của khoá. Đối với mọi khoá được bảo mật bằng phần cứng, các thẻ này sẽ nằm trong danh sách do phần cứng thực thi.
• Những giá trị Tag::IARC được hỗ trợ bởi phần cứng bảo mật này sẽ được đưa vào danh sách hỗ trợ phần cứng. Các chuỗi đại diện không được hỗ trợ sẽ nằm trong danh sách được phần mềm hỗ trợ.
• Các giá trị Tag::PADDING thường nằm trong danh sách được phần cứng hỗ trợ, trừ phi có khả năng là một chế độ khoảng đệm cụ thể có thể phải do phần mềm thực hiện. Trong trường hợp đó, chúng sẽ được đưa vào danh sách được thực thi bằng phần mềm. Khả năng này xảy ra đối với các khoá RSA cho phép thêm khoảng đệm PSS hoặc OAEP bằng các thuật toán chuỗi đại diện không được phần cứng bảo mật hỗ trợ.
• Thẻ::USER_SECURE_ID và Tag::USER_XÁC_TYPE chỉ được thực thi bằng phần cứng nếu quy trình xác thực người dùng được thực thi bằng phần cứng. Để thực hiện việc này, cả vùng chứa tin cậy Keymaster và vùng chứa tin cậy xác thực liên quan đều phải an toàn và chia sẻ một khoá HMAC bí mật dùng để ký và xác thực mã thông báo xác thực. Hãy xem trang Xác thực để biết thông tin chi tiết.
• Các thẻ Thẻ::ACTIVE_DATETIME, Thẻ::originATION_EXPIRE_DATETIME, và các thẻ Tag::USAGE_EXPIRE_DATETIME cần có quyền truy cập vào một đồng hồ treo tường có thể xác minh được. Hầu hết phần cứng bảo mật chỉ có quyền truy cập vào thông tin thời gian do hệ điều hành không bảo mật cung cấp, nghĩa là các thẻ được thực thi bằng phần mềm.
• Tag::ORIGIN luôn có trong danh sách phần cứng cho các khoá liên kết với phần cứng. Sự hiện diện của khoá trong danh sách đó là cách các lớp cao hơn xác định rằng khoá được hỗ trợ phần cứng.

khoá-nhập

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng import_key và được đổi tên trong Keymaster 3.

Nhập tài liệu khoá vào phần cứng Keymaster. Các tham số định nghĩa khoá và đặc điểm đầu ra được xử lý giống như đối với generateKey, ngoại trừ các trường hợp ngoại lệ sau:

• Tag::KEY_SIZE và Tag::RSA_PUBLIC_EXPONENT (chỉ dành cho khoá RSA) không cần thiết trong các tham số đầu vào. Nếu không được cung cấp, tin cậy sẽ suy ra các giá trị từ tài liệu khoá đã cung cấp rồi thêm các thẻ và giá trị thích hợp vào các đặc điểm khoá. Nếu bạn cung cấp các tham số, thì trustlet sẽ xác thực các tham số đó dựa trên tài liệu khoá. Trong trường hợp giá trị không khớp, phương thức này sẽ trả về ErrorCode::IMPORT_PARAMETER_MISMATCH.
• Tag::ORIGINAL được trả về có cùng giá trị với KeyOrigin::IMPORTED.

khoá xuất

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng export_key và được đổi tên trong Keymaster 3.

Xuất khoá công khai từ cặp khoá RSA hoặc EC của Keymaster.

Nếu bạn đã cung cấp Tag::APPLICATION_ID trong quá trình tạo hoặc nhập khoá, thì cùng một giá trị sẽ được cung cấp cho phương thức này trong đối số clientId. Nếu không, phương thức này sẽ trả về ErrorCode::INVALID_KEY_BLOB. Tương tự, nếu bạn cung cấp Tag::APPLICATION_DATA trong quá trình tạo hoặc nhập, thì giá trị tương tự sẽ được cung cấp cho phương thức này trong đối số appData.

deleteKey

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng delete_key và được đổi tên trong Keymaster 3.

Xoá khoá đã cung cấp. Phương thức này là không bắt buộc và chỉ được các mô-đun Keymaster triển khai nhằm cung cấp khả năng chống khôi phục.

deleteAllKeys

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

Hàm này được giới thiệu trong Keymaster 1 dưới dạng delete_all_keys và được đổi tên trong Keymaster 3.

Xoá tất cả khoá. Phương thức này là không bắt buộc và chỉ được các mô-đun Keymaster cung cấp khả năng chống khôi phục triển khai.

destroyAttestationIds

Phiên bản: 3

Phương thức destroyAttestationIds() được dùng để tắt vĩnh viễn tính năng chứng thực giấy tờ tuỳ thân mới (không bắt buộc nhưng bạn nên dùng). Nếu TEE không có cách nào để đảm bảo rằng tính năng chứng thực giấy tờ tuỳ thân bị vô hiệu hoá vĩnh viễn sau khi phương thức này được gọi, thì bạn không được triển khai tính năng chứng thực giấy tờ tuỳ thân. Trong trường hợp này, phương thức này sẽ không làm gì cả và trả về ErrorCode::UNIMPLEMENTED. Nếu tính năng chứng thực giấy tờ tuỳ thân được hỗ trợ, bạn cần triển khai phương thức này và phải tắt vĩnh viễn mọi lần thử chứng thực giấy tờ tuỳ thân trong tương lai. Bạn có thể gọi phương thức này bất kỳ số lần nào. Nếu tính năng chứng thực giấy tờ tuỳ thân đã bị tắt vĩnh viễn, thì phương thức này sẽ không làm gì cả và trả về ErrorCode::OK.

Các mã lỗi duy nhất mà phương thức này có thể trả về là ErrorCode::UNIMPLEMENTED (nếu không hỗ trợ chứng thực mã nhận dạng), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED hoặc một trong các mã lỗi cho biết không kết nối được với phần cứng bảo mật.

bắt đầu

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

Bắt đầu thao tác mã hoá bằng khoá đã chỉ định cho mục đích đã chỉ định với các tham số được chỉ định (nếu phù hợp) và trả về một ô điều khiển thao tác dùng cùng với thao tác update và finish để hoàn tất thao tác. Tên hoạt động cũng được dùng làm mã thông báo "thách thức" trong các hoạt động đã xác thực và đối với các hoạt động như vậy, tên hoạt động sẽ nằm trong trường challenge của mã thông báo xác thực.

Việc triển khai Keymaster hỗ trợ ít nhất 16 thao tác đồng thời. Kho khoá sử dụng tối đa 15 khoá, để lại một mã cho vold dùng để mã hoá mật khẩu. Khi Kho khoá có 15 thao tác đang diễn ra (begin đã được gọi, nhưng finish hoặc abort chưa được gọi) và nhận được yêu cầu bắt đầu thao tác thứ 16, Kho khoá sẽ gọi abort trên thao tác ít được sử dụng gần đây nhất để giảm số lượng thao tác đang hoạt động xuống còn 14 trước khi gọi begin để bắt đầu thao tác mới được yêu cầu.

Nếu Tag::APPLICATION_ID hoặc Tag::APPLICATION_DATA được chỉ định trong quá trình tạo hoặc nhập khoá, thì các lệnh gọi đến begin sẽ bao gồm các thẻ đó có giá trị được chỉ định ban đầu trong đối số inParams cho phương thức này.

Thực thi việc uỷ quyền

Trong phương thức này, các hoạt động uỷ quyền khoá sau đây sẽ được trustlet thực thi nếu quá trình triển khai đặt các hoạt động đó vào các đặc điểm "do phần cứng thực thi" và nếu hoạt động đó không phải là hoạt động khoá công khai. Các thao tác khoá công khai, nghĩa là KeyPurpose::ENCRYPT và KeyPurpose::VERIFY, với khoá RSA hoặc EC, được phép thành công ngay cả khi không đáp ứng các yêu cầu về việc uỷ quyền.

• Tag::PURPOSE: Mục đích được chỉ định trong lệnh gọi begin() phải khớp với một trong các mục đích trong các hoạt động uỷ quyền khoá, trừ phi thao tác được yêu cầu là thao tác khoá công khai. Nếu mục đích đã chỉ định không khớp và thao tác không phải là thao tác khoá công khai, thì begin sẽ trả về ErrorCode::UNSUPPORTED_PURPOSE. Các thao tác khoá công khai là các thao tác xác minh hoặc mã hoá bất đối xứng.
• Bạn chỉ có thể thực thi Tag::ACTIVE_DATETIME nếu có nguồn thời gian UTC đáng tin cậy. Nếu ngày và giờ hiện tại trước giá trị thẻ, phương thức này sẽ trả về ErrorCode::KEY_NOT_YET_VALID.
• Bạn chỉ có thể thực thi Tag::ORIGINATION_EXPIRE_DATETIME nếu có nguồn thời gian UTC đáng tin cậy. Nếu ngày và giờ hiện tại muộn hơn giá trị thẻ và mục đích là KeyPurpose::ENCRYPT hoặc KeyPurpose::SIGN, thì phương thức này sẽ trả về ErrorCode::KEY_EXPIRED.
• Bạn chỉ có thể thực thi Tag::USAGE_EXPIRE_DATETIME nếu có nguồn thời gian UTC đáng tin cậy. Nếu ngày và giờ hiện tại muộn hơn giá trị thẻ và mục đích là KeyPurpose::DECRYPT hoặc KeyPurpose::VERIFY, thì phương thức này sẽ trả về ErrorCode::KEY_EXPIRED.
• Tag::MIN_SECONDS_BETWEEN_OPS được so sánh với một bộ hẹn giờ tương đối đáng tin cậy cho biết lần sử dụng khoá gần đây nhất. Nếu thời gian sử dụng gần đây nhất cộng với giá trị thẻ nhỏ hơn thời gian hiện tại, thì phương thức sẽ trả về ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Hãy xem nội dung mô tả thẻ để biết thông tin chi tiết quan trọng về cách triển khai.
• Tag::MAX_USES_PER_BOOT được so sánh với một bộ đếm bảo mật theo dõi số lần sử dụng khoá kể từ thời điểm khởi động. Nếu số lần sử dụng trước đó vượt quá giá trị thẻ, phương thức này sẽ trả về ErrorCode::KEY_MAX_OPS_EXCEEDED.
• Tag::USER_SECURE_ID chỉ được phương thức này thực thi nếu khoá cũng có Tag::AUTH_TIMEOUT. Nếu khoá có cả hai, thì phương thức này phải nhận được một Tag::AUTH_TOKEN hợp lệ trong inParams. Để mã xác thực hợp lệ, tất cả các điều kiện sau đây đều phải đúng:
  • Trường HMAC xác thực chính xác.
  • Ít nhất một trong các giá trị Tag::USER_SECURE_ID từ khoá khớp với ít nhất một trong các giá trị mã nhận dạng bảo mật trong mã thông báo.
  • Khoá này có Tag::USER_XÁC_TYPE khớp với loại xác thực trong mã thông báo.

  Nếu không đáp ứng bất kỳ điều kiện nào trong số này, phương thức này sẽ trả về ErrorCode::KEY_USER_NOT_AUTHENTICATED.

• Tag::CALLER_NONCE cho phép phương thức gọi chỉ định một số chỉ dùng một lần hoặc vectơ khởi tạo (IV). Nếu khoá không có thẻ này nhưng phương thức gọi đã cung cấp Tag::NONCE cho phương thức này, thì ErrorCode::CALLER_NONCE_PROHIBITED sẽ được trả về.
• Tag::BOOTLOADER_ONLY chỉ định rằng chỉ trình tải khởi động mới có thể sử dụng khoá. Nếu phương thức này được gọi bằng khoá chỉ dành cho trình tải khởi động sau khi trình tải khởi động hoàn tất quá trình thực thi, thì phương thức này sẽ trả về ErrorCode::INVALID_KEY_BLOB.

Khoá RSA

Tất cả các thao tác với khoá RSA đều chỉ định chính xác một chế độ đệm trong inParams. Nếu không được chỉ định hoặc được chỉ định nhiều lần, phương thức này sẽ trả về ErrorCode::UNSUPPORTED_PADDING_MODE.

Hoạt động ký và xác minh RSA cần một chuỗi đại diện, cũng như hoạt động mã hoá và giải mã RSA với chế độ khoảng đệm OAEP. Đối với những trường hợp đó, phương thức gọi chỉ định chính xác một chuỗi đại diện trong inParams. Nếu không được chỉ định hoặc được chỉ định nhiều lần, phương thức này sẽ trả về ErrorCode::UNSUPPORTED_DIGEST.

Các thao tác với khoá riêng tư (KeyPurpose::DECYPT và KeyPurpose::SIGN) cần được uỷ quyền cho hàm băm và độ đệm, tức là các uỷ quyền khoá cần chứa các giá trị đã chỉ định. Nếu không, phương thức này sẽ trả về ErrorCode::INCOMPATIBLE_DIGEST hoặc ErrorCode::INCOMPATIBLE_PADDING, tuỳ thích. Thao tác khoá công khai (KeyPurpose::ENCRYPT và KeyPurpose::VERIFY) được phép kèm theo chuỗi đại diện hoặc khoảng đệm trái phép.

Ngoại trừ PaddingMode::NONE, tất cả các chế độ khoảng đệm RSA chỉ áp dụng cho một số mục đích nhất định. Cụ thể, PaddingMode::RSA_PKCS1_1_5_SIGN và PaddingMode::RSA_PSS chỉ hỗ trợ ký và xác minh, còn PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT và PaddingMode::RSA_OAEP chỉ hỗ trợ mã hoá và giải mã. Phương thức này sẽ trả về ErrorCode::UNSUPPORTED_PADDING_MODE nếu chế độ đã chỉ định không hỗ trợ mục đích đã chỉ định.

Có một số hoạt động tương tác quan trọng giữa chế độ đệm và chuỗi đại diện:

• PaddingMode::NONE cho biết rằng thao tác RSA "thô" được thực hiện. Nếu ký hoặc xác minh, Digest::NONE sẽ được chỉ định cho chuỗi đại diện. Không cần hàm băm để mã hoá hoặc giải mã không được thêm khoảng đệm.
• Khoảng đệm PaddingMode::RSA_PKCS1_1_5_SIGN cần có chuỗi đại diện. Giá trị tổng hợp có thể là Digest::NONE, trong trường hợp này, việc triển khai Keymaster không thể tạo cấu trúc chữ ký PKCS#1 phiên bản 1.5 thích hợp vì không thể thêm cấu trúc DigestInfo. Thay vào đó, quá trình triển khai sẽ tạo 0x00 || 0x01 || PS || 0x00 || M, trong đó M là thông báo được cung cấp và PS là chuỗi đệm. Kích thước khoá RSA phải lớn hơn thông báo ít nhất 11 byte, nếu không phương thức này sẽ trả về ErrorCode::INVALID_INPUT_LENGTH.
• Khoảng đệm PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT không yêu cầu chuỗi đại diện.
• Khoảng đệm PaddingMode::RSA_PSS yêu cầu một chuỗi đại diện không được là Digest::NONE. Nếu bạn chỉ định Digest::NONE, phương thức này sẽ trả về ErrorCode::INCOMPATIBLE_DIGEST. Ngoài ra, kích thước của khoá RSA phải lớn hơn kích thước đầu ra của chuỗi đại diện ít nhất là 2 + D byte, trong đó D là kích thước của chuỗi đại diện, tính bằng byte. Nếu không, phương thức này sẽ trả về ErrorCode::INCOMPATIBLE_DIGEST. Kích thước muối là D.
• Khoảng đệm PaddingMode::RSA_OAEP yêu cầu một chuỗi đại diện không được là Digest::NONE. Nếu bạn chỉ định Digest::NONE, phương thức này sẽ trả về ErrorCode::INCOMPATIBLE_DIGEST.

Khoá EC

Các thao tác khoá EC chỉ định chính xác một chế độ đệm trong inParams. Nếu không được chỉ định hoặc được chỉ định nhiều lần, phương thức này sẽ trả về ErrorCode::UNSUPPORTED_PADDING_MODE.

Thao tác khoá riêng tư (KeyPurpose::SIGN) cần được uỷ quyền cho chuỗi đại diện và khoảng đệm, tức là các hoạt động uỷ quyền khoá cần chứa các giá trị đã chỉ định. Nếu không, hãy trả về ErrorCode::INCOMPATIBLE_DIGEST. Các thao tác với khoá công khai (KeyPurpose::VERIFY) được phép sử dụng chuỗi đại diện hoặc khoảng đệm không được phép.

Khoá AES

Các thao tác phím AES chỉ định chính xác một chế độ khối và một chế độ khoảng đệm trong inParams. Nếu một trong hai giá trị không được chỉ định hoặc được chỉ định nhiều lần, hãy trả về ErrorCode::UNSUPPORTED_BLOCK_MODE hoặc ErrorCode::UNSUPPORTED_PADDING_MODE. Các chế độ đã chỉ định phải được khoá uỷ quyền, nếu không phương thức sẽ trả về ErrorCode::INCOMPATIBLE_BLOCK_MODE hoặc ErrorCode::INCOMPATIBLE_PADDING_MODE.

Nếu chế độ chặn là BlockMode::GCM, thì inParams sẽ chỉ định Tag::MAC_LENGTH và giá trị được chỉ định là bội số của 8 không lớn hơn 128 hoặc nhỏ hơn giá trị của Tag::MIN_MAC_LENGTH trong các quyền uỷ quyền khoá. Đối với độ dài MAC lớn hơn 128 hoặc không phải bội số của 8, hãy trả về ErrorCode::UNSUPPORTED_MAC_LENGTH. Đối với các giá trị nhỏ hơn độ dài tối thiểu của khoá, hãy trả về ErrorCode::INVALID_MAC_LENGTH.

Nếu chế độ khối là BlockMode::GCM hoặc BlockMode::CTR, thì chế độ khoảng đệm được chỉ định phải là PaddingMode::NONE. Đối với BlockMode::ECB hoặc BlockMode::CBC, chế độ có thể là PaddingMode::NONE hoặc PaddingMode::PKCS7. Nếu chế độ khoảng đệm không đáp ứng các điều kiện này, hãy trả về ErrorCode::INCOMPATIBLE_PADDING_MODE.

Nếu chế độ khối là BlockMode::CBC, BlockMode::CTR hoặc BlockMode::GCM, thì bạn cần có một vectơ khởi tạo hoặc số chỉ dùng một lần. Trong hầu hết các trường hợp, phương thức gọi không nên cung cấp IV hoặc số chỉ dùng một lần. Trong trường hợp đó, quá trình triển khai Keymaster sẽ tạo một IV hoặc số chỉ dùng một lần ngẫu nhiên và trả về số đó bằng Tag::NONCE trong outParams. CBC và CTR IV có kích thước 16 byte. Số chỉ dùng một lần của GCM có kích thước 12 byte. Nếu các quyền truy cập khoá chứa Tag::CALLER_NONCE, thì phương thức gọi có thể cung cấp IV hoặc số chỉ dùng một lần bằng Tag::NONCE trong inParams. Nếu bạn cung cấp số chỉ dùng một lần khi Tag::CALLER_NONCE không được uỷ quyền, hãy trả về ErrorCode::CALLER_NONCE_PROHIBITED. Nếu không cung cấp số chỉ dùng một lần khi Tag::CALLER_NONCE được uỷ quyền, hãy tạo một IV/số chỉ dùng một lần ngẫu nhiên.

Khoá HMAC

Các thao tác khoá HMAC chỉ định Tag::MAC_LENGTH trong inParams. Giá trị được chỉ định phải là bội số của 8 không lớn hơn chiều dài chuỗi đại diện hoặc nhỏ hơn giá trị của Tag::MIN_MAC_LENGTH trong các quyền uỷ quyền khoá. Đối với độ dài MAC lớn hơn độ dài chuỗi đại diện hoặc không phải là bội số của 8, hãy trả về ErrorCode::UNSUPPORTED_MAC_LENGTH. Đối với các giá trị nhỏ hơn độ dài tối thiểu của khoá, hãy trả về ErrorCode::INVALID_MAC_LENGTH.

cập nhật

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

Cung cấp dữ liệu để xử lý trong một thao tác đang diễn ra bắt đầu bằng begin. Thao tác này do tham số operationHandle chỉ định.

Để xử lý vùng đệm linh hoạt hơn, việc triển khai phương thức này có thể sử dụng ít dữ liệu hơn so với dữ liệu được cung cấp. Phương thức gọi chịu trách nhiệm lặp lại để cung cấp phần dữ liệu còn lại trong các lệnh gọi tiếp theo. Lượng dữ liệu đầu vào đã tiêu thụ được trả về trong tham số inputConsumed. Hoạt động triển khai luôn sử dụng ít nhất một byte, trừ phi thao tác không thể chấp nhận thêm nữa; nếu nhiều hơn 0 byte được cung cấp và sử dụng 0 byte, thì phương thức gọi sẽ coi đây là lỗi và huỷ thao tác.

Quá trình triển khai cũng có thể chọn lượng dữ liệu cần trả về, do bản cập nhật. Điều này chỉ liên quan đến các hoạt động mã hoá và giải mã, vì quá trình ký và xác minh sẽ không trả về dữ liệu nào cho đến khi hoàn tất. Trả về dữ liệu càng sớm càng tốt, thay vì lưu dữ liệu vào vùng đệm.

Xử lý lỗi

Nếu phương thức này trả về một mã lỗi khác với ErrorCode::OK, thao tác sẽ bị huỷ và tay điều khiển thao tác sẽ không hợp lệ. Mọi hoạt động sử dụng handle trong tương lai, với phương thức này, finish hoặc abort, sẽ trả về ErrorCode::INVALID_OPERATION_HANDLE.

Thực thi việc uỷ quyền

Việc thực thi uỷ quyền khoá chủ yếu được thực hiện trong begin. Ngoại lệ duy nhất là trường hợp khoá có:

• Một hoặc nhiều Thẻ::USER_SECURE_IDs và
• Không có Tag::AUTH_TIMEOUT

Trong trường hợp này, khoá yêu cầu uỷ quyền cho mỗi thao tác và phương thức cập nhật sẽ nhận được Tag::AUTH_TOKEN trong đối số inParams. HMAC xác minh rằng mã thông báo hợp lệ và chứa mã nhận dạng người dùng bảo mật phù hợp, khớp với Tag::USER_AUTH_TYPE của khoá và chứa tên xử lý thao tác của thao tác hiện tại trong trường thách thức. Nếu không đáp ứng các điều kiện này, hãy trả về ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Phương thức gọi cung cấp mã xác thực cho mọi lệnh gọi để cập nhật và hoàn tất. Trong quá trình triển khai, bạn chỉ cần xác thực mã thông báo một lần nếu muốn.

Khoá RSA

Đối với các thao tác ký và xác minh bằng Digest::NONE, phương thức này chấp nhận toàn bộ khối để ký hoặc xác minh trong một lần cập nhật. Mô-đun này không thể chỉ sử dụng một phần của khối. Tuy nhiên, nếu phương thức gọi chọn cung cấp dữ liệu trong nhiều bản cập nhật, thì phương thức này sẽ chấp nhận dữ liệu đó. Nếu phương thức gọi cung cấp nhiều dữ liệu để ký hơn mức có thể sử dụng (độ dài dữ liệu vượt quá kích thước khoá RSA), hãy trả về ErrorCode::INVALID_INPUT_LENGTH.

Khoá ECDSA

Đối với các thao tác ký và xác minh bằng Digest::NONE, phương thức này chấp nhận toàn bộ khối để ký hoặc xác minh trong một lần cập nhật. Phương thức này không thể chỉ sử dụng một phần của khối.

Tuy nhiên, nếu phương thức gọi chọn cung cấp dữ liệu trong nhiều lần cập nhật, thì phương thức này sẽ chấp nhận dữ liệu đó. Nếu phương thức gọi cung cấp nhiều dữ liệu hơn mức có thể dùng để ký, thì dữ liệu sẽ bị cắt bớt một cách tự động. (Điều này khác với việc xử lý dữ liệu thừa được cung cấp trong các thao tác RSA tương tự. Lý do là để tương thích với các ứng dụng cũ.)

Khoá AES

Chế độ AES GCM hỗ trợ "dữ liệu xác thực được liên kết", được cung cấp thông qua thẻ Tag::ASSOCIATED_DATA trong đối số inParams. Dữ liệu liên quan có thể được cung cấp trong các lệnh gọi lặp lại (quan trọng nếu dữ liệu quá lớn để gửi trong một khối) nhưng luôn đứng trước dữ liệu cần mã hoá hoặc giải mã. Lệnh gọi cập nhật có thể nhận cả dữ liệu và dữ liệu liên quan để mã hoá/giải mã, nhưng các bản cập nhật tiếp theo không thể bao gồm dữ liệu liên quan. Nếu phương thức gọi cung cấp dữ liệu liên kết cho lệnh gọi cập nhật sau một lệnh gọi chứa dữ liệu để mã hoá/giải mã, hãy trả về ErrorCode::INVALID_TAG.

Đối với phương thức mã hoá GCM, thẻ sẽ được thêm vào bản mã bằng cách finish. Trong quá trình giải mã, Tag::MAC_LENGTH byte cuối cùng của dữ liệu được cung cấp cho lệnh gọi cập nhật gần đây nhất là thẻ. Vì một lệnh gọi cụ thể của update không thể biết liệu đó có phải là lệnh gọi cuối cùng hay không, nên lệnh gọi này sẽ xử lý tất cả ngoại trừ độ dài thẻ và lưu vào bộ đệm dữ liệu thẻ có thể có trong quá trình hoàn tất.

hoàn tất

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

Kết thúc một thao tác đang diễn ra bắt đầu bằng begin, xử lý tất cả dữ liệu chưa được xử lý do(các) update cung cấp.

Phương thức này là phương thức cuối cùng được gọi trong một thao tác, vì vậy, tất cả dữ liệu đã xử lý đều được trả về.

Dù hoàn tất thành công hay trả về lỗi, phương thức này vẫn sẽ kết thúc thao tác và do đó làm mất hiệu lực xử lý thao tác đã cung cấp. Mọi hoạt động sử dụng handle trong tương lai, bằng phương thức này hoặc cập nhật hoặc huỷ, sẽ trả về ErrorCode::INVALID_OPERATION_HANDLE.

Thao tác ký sẽ trả về chữ ký dưới dạng kết quả. Các hoạt động xác minh sẽ chấp nhận chữ ký trong tham số signature và không trả về kết quả nào.

Thực thi uỷ quyền

Việc thực thi hoạt động uỷ quyền khoá chủ yếu được thực hiện khi bắt đầu. Ngoại lệ duy nhất là trường hợp khoá có:

• Một hoặc nhiều Thẻ::USER_SECURE_IDs và
• Không có Tag::AUTH_TIMEOUT

Trong trường hợp này, khoá yêu cầu uỷ quyền cho mỗi thao tác và phương thức cập nhật sẽ nhận được Tag::AUTH_TOKEN trong đối số inParams. HMAC xác minh rằng mã thông báo này là hợp lệ và chứa một mã nhận dạng người dùng bảo mật trùng khớp, khớp với Tag::USER_XÁC_TYPE của khoá và chứa tên người dùng của thao tác hiện tại trong trường thử thách. Nếu không đáp ứng các điều kiện này, hãy trả về ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Phương thức gọi cung cấp mã thông báo xác thực cho mọi lệnh gọi để cập nhật và hoàn tất. Trong quá trình triển khai, bạn chỉ cần xác thực mã thông báo một lần nếu muốn.

Khoá RSA

Một số yêu cầu bổ sung, tuỳ thuộc vào chế độ khoảng đệm:

• PaddingMode::NONE. Đối với các thao tác ký và mã hoá không được thêm khoảng đệm, nếu dữ liệu được cung cấp ngắn hơn khoá, thì dữ liệu sẽ được thêm khoảng đệm bằng 0 ở bên trái trước khi ký/mã hoá. Nếu dữ liệu có cùng độ dài với khoá nhưng lớn hơn về mặt số, hãy trả về ErrorCode::INVALID_ARGUMENT. Đối với các thao tác xác minh và giải mã, dữ liệu phải dài đúng bằng khoá. Nếu không, hãy trả về ErrorCode::INVALID_INPUT_LENGTH.
• PaddingMode::RSA_PSS. Đối với các thao tác chữ ký có đệm PSS, dữ liệu ngẫu nhiên của PSS là kích thước của chuỗi đại diện thông báo và được tạo ngẫu nhiên. Chuỗi đại diện được chỉ định bằng Tag::DIGEST trong inputParams trên begin được dùng làm thuật toán chuỗi đại diện PSS và thuật toán chuỗi đại diện MGF1.
• PaddingMode::RSA_OAEP. Chuỗi đại diện được chỉ định bằng Tag::PWA trong inputParams trên begin được dùng làm thuật toán chuỗi đại diện OAEP, còn SHA1 được dùng làm thuật toán chuỗi đại diện MGF1.

Khoá ECDSA

Nếu dữ liệu được cung cấp để ký hoặc xác minh không được thêm khoảng đệm quá dài, hãy cắt ngắn dữ liệu đó.

Khoá AES

Một số điều kiện bổ sung, tuỳ thuộc vào chế độ chặn:

• BlockMode::ECB hoặc BlockMode::CBC. Nếu khoảng đệm là PaddingMode::NONE và chiều dài dữ liệu không phải là bội số của kích thước khối AES, hãy trả về ErrorCode::INVALID_INPUT_LENGTH. Nếu khoảng đệm là PaddingMode::PKCS7, hãy thêm khoảng đệm cho dữ liệu theo quy cách PKCS#7. Xin lưu ý rằng PKCS#7 đề xuất thêm một khối đệm bổ sung nếu dữ liệu là bội số của chiều dài khối.
• BlockMode::GCM. Trong quá trình mã hoá, sau khi xử lý tất cả văn bản thuần tuý, hãy tính toán thẻ (Tag::MAC_LENGTH byte) và thêm thẻ đó vào văn bản đã mã hoá được trả về. Trong quá trình giải mã, hãy xử lý các byte Tag::MAC_LENGTH cuối cùng dưới dạng thẻ. Nếu không xác minh được thẻ, hãy trả về ErrorCode::VERIFICATION_FAILED.

hủy đi

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

Huỷ thao tác đang diễn ra. Sau lệnh gọi huỷ, hãy trả về ErrorCode::INVALID_OPERATION_HANDLE cho mọi lần sử dụng tiếp theo của tay điều khiển thao tác được cung cấp bằng cập nhật, hoàn tất hoặc huỷ.

get_supported_algorithms

Phiên bản: 1

Trả về danh sách các thuật toán được quá trình triển khai phần cứng Keymaster hỗ trợ. Quá trình triển khai phần mềm sẽ trả về một danh sách trống; phương thức triển khai kết hợp trả về một danh sách chỉ chứa các thuật toán được phần cứng hỗ trợ.

Các phương thức triển khai Keymaster 1 hỗ trợ RSA, EC, AES và HMAC.

get_supported_block_modes

Phiên bản: 1

Trả về danh sách các chế độ khối AES mà việc triển khai phần cứng Keymaster hỗ trợ cho một thuật toán và mục đích đã chỉ định.

Đối với RSA, EC và HMAC (không phải là thuật toán mật mã khối), phương thức này sẽ trả về một danh sách trống cho tất cả các mục đích hợp lệ. Mục đích không hợp lệ sẽ khiến phương thức trả về ErrorCode::INVALID_PURPOSE.

Các phương thức triển khai Keymaster 1 hỗ trợ ECB, CBC, CTR và GCM để mã hoá và giải mã AES.

get_supported_padding_modes

Phiên bản: 1

Trả về danh sách các chế độ khoảng đệm được triển khai phần cứng Keymaster hỗ trợ cho một thuật toán và mục đích đã chỉ định.

HMAC và EC không có khái niệm về khoảng đệm nên phương thức này sẽ trả về một danh sách trống cho tất cả các mục đích hợp lệ. Mục đích không hợp lệ sẽ khiến phương thức trả về ErrorCode::INVALID_PURPOSE.

Đối với RSA, các phương thức triển khai Keymaster 1 hỗ trợ:

• Mã hoá, giải mã, ký và xác minh không có khoảng đệm. Đối với hoạt động mã hoá và ký không có khoảng đệm, nếu thông báo ngắn hơn mô-đun công khai, thì quá trình triển khai phải chuyển thông báo sang trái bằng số 0. Đối với việc giải mã và xác minh không thêm khoảng đệm, chiều dài đầu vào phải khớp với kích thước mô-đun công khai.
• Chế độ mã hoá và ký tên PKCS#1 v1.5
• PSS có độ dài muối tối thiểu là 20
• OAEP

Đối với AES ở chế độ ECB và CBC, các phương thức triển khai Keymaster 1 không hỗ trợ tính năng thêm khoảng đệm và thêm khoảng đệm PKCS#7. Chế độ CTR và GCM chỉ hỗ trợ không có khoảng đệm.

get_supported_digests

Phiên bản: 1

Trả về danh sách các chế độ chuỗi đại diện được quá trình triển khai phần cứng Keymaster hỗ trợ cho một thuật toán và mục đích đã chỉ định.

Không có chế độ AES hỗ trợ hoặc yêu cầu thông báo, vì vậy, phương thức này sẽ trả về một danh sách trống cho các mục đích hợp lệ.

Các phương thức triển khai Keymaster 1 có thể triển khai một tập hợp con của các chuỗi đại diện đã xác định. Các phương thức triển khai cung cấp SHA-256 và có thể cung cấp MD5, SHA1, SHA-224, SHA-256, SHA384 và SHA512 (tập hợp đầy đủ các chuỗi đại diện đã xác định).

get_supported_nhập_định dạng

Phiên bản: 1

Trả về danh sách các định dạng nhập được hỗ trợ trong việc triển khai phần cứng Keymaster của một thuật toán được chỉ định.

Các phương thức triển khai Keymaster 1 hỗ trợ định dạng PKCS#8 (không có tính năng bảo vệ bằng mật khẩu) để nhập các cặp khoá RSA và EC, đồng thời hỗ trợ nhập RAW của nội dung khoá AES và HMAC.

get_supported_export_formats

Phiên bản: 1

Trả về danh sách các định dạng xuất được hỗ trợ bằng cách triển khai phần cứng Keymaster của một thuật toán đã chỉ định.

Các hoạt động triển khai Keymaster1 hỗ trợ định dạng X.509 để xuất khoá công khai RSA và EC. Không hỗ trợ xuất khoá riêng tư hoặc khoá bất đối xứng.

Hàm trước đây

Keymaster 0

Các hàm sau đây thuộc định nghĩa Keymaster 0 ban đầu. Các thành phần này có trong Keymaster 1 struct keymaster1_device_t. Tuy nhiên, trong Keymaster 1.0, các hàm này chưa được triển khai và con trỏ hàm của chúng được đặt thành NULL.

• generate_keypair
• import_keypair
• get_keypair_public
• delete_keypair
• delete_all
• sign_data
• Verify_data

Keymaster 1

Các hàm sau thuộc định nghĩa Keymaster 1, nhưng đã bị xoá trong Keymaster 2, cùng với các hàm Keymaster 0 được liệt kê ở trên.

• get_supported_algorithms
• get_supported_block_modes
• get_supported_padding_modes
• get_supported_digests
• get_supported_import_formats
• get_supported_export_formats

Keymaster 2

Các hàm sau thuộc định nghĩa Keymaster 2, nhưng đã bị xoá trong Keymaster 3, cùng với các hàm Keymaster 1 được liệt kê ở trên.

• configure