Chức năng 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 Keymaster (HAL). Nó bao gồm từng chức năng trong API và phiên bản Keymaster mà chức năng đó có sẵn và mô tả việc triển khai mặc định. Đối với các thẻ, hãy xem trang Thẻ Keymaster .

Hướng dẫn thực hiện chung

Các nguyên tắc sau áp dụng cho tất cả các chức năng 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 sử dụng cho một cuộc gọi nhất định có thể là NULL . Người gọi không bắt buộc phải cung cấp phần giữ chỗ. Ví dụ: một số kiểu và chế độ khóa có thể không sử dụng bất kỳ giá trị nào từ đối số inParams để bắt đầu , vì vậy người gọi có thể đặt inParams thành NULL hoặc cung cấp một tập tham số trống. Người gọi cũng có thể cung cấp các tham số không sử dụng và các phương thức Keymaster sẽ không gây ra lỗi.

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

Bắt đầu từ Keymaster 3, không có tham số con trỏ. Tất cả các tham số được truyền bởi tham chiếu giá trị hoặc const.

Tham số con trỏ đầu ra

Phiên bản : 1, 2

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

Bắt đầu từ Keymaster 3, không có tham số con trỏ. Tất cả các tham số được truyền bởi tham chiếu giá trị hoặc const.

Sử dụng sai API

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

Có nhiều cách mà người gọi có thể đưa ra những yêu cầu không có ý nghĩa hoặc là 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 thất bại trong những trường hợp như vậy hoặc đưa ra chẩn đoán. Sử dụng các khóa quá nhỏ, đặc tả các tham số đầu vào không liên quan, tái sử dụng IV hoặc nonces, tạo khóa không có mục đích (do đó vô dụng) và những thứ tương tự không nên được chẩn đoán bằng triển khai. Việc bỏ sót các tham số bắt buộc, đặc tả các tham số bắt buộc không hợp lệ và các lỗi tương tự phải được chẩn đoán.

Các ứng dụng, khuôn khổ và kho khóa 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.

Chức năng

getHardwareFeatures

Phiên bản : 3

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

  • isSecure là true nếu các khóa được lưu trữ trong phần cứng an toàn (TEE, v.v.) và không bao giờ rời khỏi nó.
  • supportsEllipticCurve là true nếu phần cứng hỗ trợ mật mã Elliptic Curve 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ợ mật mã đối xứng, bao gồm AES và HMAC.
  • supportsAttestation là true nếu phần cứng hỗ trợ tạo chứng chỉ chứng thực khóa công khai Keymaster, được ký bằng khóa được đưa vào trong môi trường an toàn.

Các mã lỗi duy nhất mà phương pháp này có thể trả về là Mã lỗi ErrorCode:OK , Mã lỗi 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 an toàn.

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

cấu hình

Phiên bản : 2

Chức năng này đã được giới thiệu trong Keymaster 2 và không được dùng nữa trong Keymaster 3, vì thông tin này có sẵn trong các tệp thuộc tính hệ thống và việc triển khai của nhà sản xuất sẽ đọc các tệp đó trong khi khởi động.

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

Nếu triển khai keymaster trong phần cứng an toàn và phiên bản hệ điều hành cũng như các giá trị cấp bản vá được cung cấp không khớp với các giá trị được bootloader cung cấp cho phần cứng an toàn (hoặc nếu bootloader không cung cấp các giá trị) thì phương thức này trả về KM_ERROR_INVALID_ARGUMENT và tất cả các giá trị khác các phương thức 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 với tên add_rng_entropy và được đổi tên trong Keymaster 3.

Thêm entropy do người gọi cung cấp vào nhóm được triển khai Keymaster 1 sử dụng để tạo số ngẫu nhiên, cho khóa, IV, v.v.

Việc triển khai Keymaster cần trộn một cách an toàn entropy đã cung cấp vào nhóm của chúng, cũng phải chứa entropy được tạo bên trong từ bộ tạo số ngẫu nhiên phần cứng. Việc trộn phải được xử lý để kẻ tấn công có quyền kiểm soát hoàn toàn 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ế không thể bỏ qua trong việc dự đoán các bit được tạo ra từ nhóm entropy.

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

Tạo khóa

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

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

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

Các tham số được cung cấp để generateKey phụ thuộc vào loại khóa được tạo. Phần này tóm tắt các thẻ cần thiết và tùy chọn cho từng loại khóa. Thẻ :: THUẬT TOÁN luôn cần thiết, để chỉ định loại.

Khóa RSA

Các tham số sau là cần thiết để tạo khóa RSA.

  • Thẻ :: 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 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ả các kích thước khóa là bội số của 8.
  • Thẻ :: 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. Các giá trị được đề xuất là tất cả các giá trị nguyên tố lên đến 2 ^ 64.

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

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

Khóa ECDSA

Chỉ Thẻ :: KEY_SIZE là cần thiết để tạo khóa ECDSA. Nó được sử dụng để chọn nhóm EC. Các giá trị được hỗ trợ là 224, 256, 384 và 521, tương ứng cho biết các đường cong NIST p-224, p-256, p-384 và p521.

Tag :: DIGEST cũng cần thiết cho một khóa ECDSA hữu ích, nhưng không cần thiết để tạo.

Các khóa AES

Chỉ Thẻ :: KEY_SIZE là cần thiết để tạo khóa AES. Nếu bị bỏ qua, phương thức trả về ErrorCode::UNSUPPORTED_KEY_SIZE . Các giá trị được hỗ trợ là 128 và 256, với hỗ trợ tùy chọn cho các khóa AES 192-bit.

Các tham số sau đặc biệt liên quan đến khóa AES, nhưng không cần thiết để tạo một:

  • Tag::BLOCK_MODE chỉ định các chế độ khối mà khóa mới có thể được sử dụng.
  • Tag::PADDING chỉ định các chế độ đệm có thể được sử dụng. Điều này chỉ phù hợp với các chế độ ECB và CBC.

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

Khóa HMAC

Các thông số sau là bắt buộc để tạo khóa HMAC:

  • Thẻ :: KEY_SIZE chỉ định kích thước khóa tính bằng bit. Các giá trị nhỏ hơn 64 và các giá trị không phải là bội số của 8 không được hỗ trợ. Tất cả các bội số của 8, từ 64 đến 512, đều được hỗ trợ. Giá trị lớn hơn có thể được hỗ trợ.
  • Thẻ :: 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 khóa này. Giá trị là bội số của 8 và ít nhất là 64.
  • Thẻ :: DIGEST chỉ định thuật toán thông báo cho khóa. Chính xác một thông báo được chỉ định, nếu không, hãy trả về ErrorCode::UNSUPPORTED_DIGEST . Nếu thông báo không được ủy thác hỗ trợ, 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, thì generateKey trả về các đặc điểm của khóa mới tạo được chia một cách thích hợp thành các danh sách được thực thi bằng phần cứng và phần mềm được thực thi. Xem getKeyCharacteristics để biết mô tả về những đặc điểm nào sẽ có trong danh sách đó. Các đặc điểm được trả về bao gồm tất cả các tham số được chỉ định để tạo khóa, ngoại trừ Thẻ :: APPLICATION_ID và Thẻ :: APPLICATION_DATA . Nếu các thẻ này được bao gồm trong các tham số chính, chúng sẽ bị loại bỏ khỏi các đặc tính được trả về để không thể tìm thấy giá trị của chúng bằng cách kiểm tra đốm màu khóa được trả về. Tuy nhiên, chúng được liên kết bằng mật mã với khối khóa, do đó nếu các giá trị chính xác không được cung cấp khi khóa được sử dụng, thì việc sử dụng sẽ không thành công. Tương tự, Thẻ :: ROOT_OF_TRUST được liên kết mật mã với khóa, nhưng nó có thể không được chỉ định trong quá trình tạo hoặc nhập khóa và không bao giờ được trả lại.

Ngoài các thẻ được cung cấp, trustlet cũng thêm Tag :: ORIGIN , với giá trị KeyOrigin::GENERATED và nếu khóa có khả năng chống khôi phục,

Thẻ :: ROLLBACK_RESISTANT .

Khả năng hồi phục

Khả năng chống khôi phục có nghĩa là sau khi một khóa bị xóa bằng deleteKey hoặc deleteAllKeys , nó được đảm bảo bằng phần cứng an toàn không bao giờ có thể sử dụng lại được nữa. Việc triển khai không có khả năng chống khôi phục thường trả về tài liệu khóa đã tạo hoặc đã nhập cho người gọi dưới dạng một khối khóa, một biểu mẫu được mã hóa và xác thực. Khi kho khóa xóa đốm màu khóa, khóa sẽ biến mất, nhưng kẻ tấn công trước đó đã quản lý để lấy tài liệu khóa có khả năng khôi phục nó vào thiết bị.

Khóa có khả năng chống khôi phục nếu phần cứng an toàn đảm bảo rằng không thể khôi phục các khóa đã xóa sau này. Điều này thường được thực hiện bằng cách lưu trữ siêu dữ liệu khóa 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ế được sử dụng cho việc này thường là Phát lại Khối bộ nhớ được Bảo vệ (RPMB). Vì số lượng khóa có thể được tạo về cơ bản là không bị giới hạn và bộ nhớ đáng tin cậy được sử dụng cho khả năng chống khôi phục có thể bị giới hạn về kích thước, phương pháp này cần thành công ngay cả khi không thể cung cấp khả năng chống khôi phục cho khóa mới. Trong trường hợp đó, không nên thêm Thẻ :: 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 với tên get_key_characteristics và được đổi tên trong Keymaster 3.

Trả về các tham số và quyền được liên kết với khóa đã cung cấp, được chia thành hai tập hợp: thực thi phần cứng và thực thi phần mềm. Mô tả ở đây áp dụng tương tự cho các danh sách đặc điểm chính được trả về bởi createKey và importKey .

Nếu Tag::APPLICATION_ID được cung cấp trong quá trình tạo hoặc nhập khóa, 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 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, giá trị tương tự sẽ được cung cấp cho phương thức này trong đối số appData .

Các đặc tính được trả về bởi phương thức này hoàn toàn mô tả loại và cách sử dụng khóa được chỉ định.

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

  • Thẻ :: THUẬT TOÁN , Thẻ :: KEY_SIZE và Thẻ :: RSA_PUBLIC_EXPONENT là các thuộc tính nội tại của khóa. Đối với bất kỳ khóa nào được bảo mật bằng phần cứng, các thẻ này sẽ nằm trong danh sách được thực thi bởi phần cứng.
  • Các giá trị Tag :: DIGEST được hỗ trợ bởi phần cứng an toàn được đặt trong danh sách được phần cứng hỗ trợ. Các thông báo 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ợ, không có khả năng rằng một chế độ đệm cụ thể có thể phải được thực hiện bởi phần mềm. Trong trường hợp đó, chúng sẽ nằm trong danh sách được thực thi bởi phần mềm. Khả năng như vậy nảy sinh đối với các khóa RSA cho phép đệm PSS hoặc OAEP với các thuật toán thông báo không được phần cứng an toàn hỗ trợ.
  • Thẻ :: USER_SECURE_ID và Thẻ :: USER_AUTH_TYPE chỉ được thực thi bằng phần cứng nếu xác thực người dùng được thực thi bằng phần cứng. Để thực hiện điều này, ủy thác Keymaster và ủy thác xác thực có liên quan đều phải được bảo mật và chia sẻ khóa HMAC bí mật được sử dụng để ký và xác thực mã thông báo xác thực. Xem trang Xác thực để biết chi tiết.
  • Các thẻ Tag :: ACTIVE_DATETIME , Tag :: ORIGINATION_EXPIRE_DATETIME và Tag :: USAGE_EXPIRE_DATETIME yêu cầu quyền truy cập vào đồng hồ treo tường chính xác có thể xác minh được. Hầu hết phần cứng an toàn chỉ có quyền truy cập vào thông tin thời gian được cung cấp bởi Hệ điều hành không an toàn, có nghĩa là các thẻ được thực thi bằng phần mềm.
  • Tag :: ORIGIN luôn nằm trong danh sách phần cứng cho các khóa được ràng buộc phần cứng. Sự hiện diện của nó trong danh sách đó là cách các lớp cao hơn xác định rằng một khóa được hỗ trợ bằng phần cứng.

importKey

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

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

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

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

exportKey

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

Chức năng này được giới thiệu trong Keymaster 1 với tên export_key và được đổi tên trong Keymaster 3.

Xuất khóa công khai từ cặp khóa Keymaster RSA hoặc EC.

Nếu Tag::APPLICATION_ID được cung cấp trong quá trình tạo hoặc nhập khóa, 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 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, giá trị tương tự sẽ được cung cấp cho phương thức này trong đối số appData .

phím xoá

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

Chức năng này được giới thiệu trong Keymaster 1 với tên delete_key và được đổi tên trong Keymaster 3.

Xóa khóa đã cung cấp. Phương pháp này là tùy chọn và chỉ được thực hiện bởi các mô-đun Keymaster 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 với tên delete_all_keys và được đổi tên trong Keymaster 3.

Xóa tất cả các khóa. Phương pháp này là tùy chọn và chỉ được thực hiện bởi các mô-đun Keymaster cung cấp khả năng chống khôi phục.

killAttestationIds

Phiên bản : 3

Phương thức destroyAttestationIds() được sử dụng để vô hiệu hóa vĩnh viễn tính năng chứng thực ID mới (tùy chọn, nhưng rất được khuyến khích). Nếu TEE không có cách nào để đảm bảo rằng chứng thực ID bị vô hiệu hóa vĩnh viễn sau khi phương thức này được gọi, thì chứng thực ID hoàn toàn không được thực hiện, trong trường hợp đó, phương thức này không làm gì cả và trả về ErrorCode::UNIMPLEMENTED . Nếu chứng thực ID được hỗ trợ, phương pháp này cần được triển khai và phải vô hiệu hóa vĩnh viễn tất cả các lần thử chứng thực ID trong tương lai. Phương thức có thể được gọi bất kỳ số lần nào. Nếu chứng thực ID đã bị vô hiệu hóa 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 pháp này có thể trả về là ErrorCode::UNIMPLEMENTED (nếu chứng thực ID không được hỗ trợ), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED hoặc một trong những mã lỗi cho biết không kết nối được với phần cứng an toàn.

bắt đầu

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

Bắt đầu một hoạt động mật mã, sử dụng khóa được chỉ định, cho mục đích được chỉ định, với các tham số được chỉ định (nếu thích hợp) và trả về một xử lý hoạt động được sử dụng với cập nhật và kết thúc để hoàn tất hoạt động. Xử lý hoạt động cũng được sử dụng làm mã thông báo "thách thức" trong các hoạt động được xác thực và đối với các hoạt động như vậy được bao gồm trong trường challenge của mã thông báo xác thực.

Triển khai Keymaster hỗ trợ ít nhất 16 hoạt động đồng thời. Kho khóa sử dụng tối đa 15, để lại một cho vold sử dụng để mã hóa mật khẩu. Khi Keystore có 15 hoạt động đang được thực hiện ( begin đã được gọi, nhưng finish hoặc abort chưa được gọi) và nó nhận được yêu cầu bắt đầu ngày 16, nó sẽ gọi abort trên hoạt động ít được sử dụng nhất để giảm số lượng hoạt động đang hoạt động đến 14 trước khi begin gọi để bắt đầu hoạt động mới được yêu cầu.

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

Thực thi ủy quyền

Trong phương pháp này, ủy quyền khóa sau được thực thi bởi ủy thác nếu việc triển khai đặt chúng trong các đặc điểm "được thực thi bằng phần cứng" và nếu hoạt động không phải là hoạt động khóa công khai. Các hoạt động khóa công khai, nghĩa là KeyPurpose::ENCRYPT và KeyPurpose::VERIFY , với khóa RSA hoặc EC, được phép thành công ngay cả khi các yêu cầu ủy quyền không được đáp ứng.

  • 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 ủy quyền khóa, trừ khi thao tác được yêu cầu là thao tác khóa công khai. Nếu mục đích được chỉ định không phù hợp và thao tác không phải là thao tác khóa công khai, begin sẽ trả về ErrorCode::UNSUPPORTED_PURPOSE . Các hoạt động khóa công khai là các hoạt động xác minh hoặc mã hóa không đối xứng.
  • Thẻ :: ACTIVE_DATETIME chỉ có thể được thực thi nếu có sẵn 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 trả về ErrorCode::KEY_NOT_YET_VALID .
  • Thẻ :: ORIGINATION_EXPIRE_DATETIME chỉ có thể được thực thi nếu có sẵn 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 , phương thức trả về ErrorCode::KEY_EXPIRED .
  • Thẻ :: USAGE_EXPIRE_DATETIME chỉ có thể được thực thi nếu có sẵn 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 , phương thức trả về ErrorCode::KEY_EXPIRED .
  • Thẻ :: MIN_SECONDS_BETWEEN_OPS được so sánh với bộ đếm thời gian tương đối đáng tin cậy cho biết lần sử dụng khóa cuối cùng. Nếu thời gian sử dụng cuối cùng cộng với giá trị thẻ nhỏ hơn thời gian hiện tại, phương thức trả về ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Xem mô tả thẻ để biết chi tiết triển khai quan trọng.
  • Thẻ :: MAX_USES_PER_BOOT được so sánh với một bộ đếm an toàn theo dõi việc sử dụng khóa kể từ thời gian khởi động. Nếu số lần sử dụng trước đó vượt quá giá trị thẻ, phương thức trả về ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • Thẻ :: USER_SECURE_ID chỉ được thực thi theo phương pháp này nếu khóa cũng có Thẻ :: AUTH_TIMEOUT . Nếu khóa có cả hai, thì phương thức này phải nhận được Thẻ hợp lệ :: AUTH_TOKEN trong inParams . Để mã thông báo xác thực hợp lệ, tất cả những điều sau đây phải đúng:
    • Trường HMAC xác thực chính xác.
    • Ít nhất một trong các giá trị Thẻ :: USER_SECURE_ID từ khóa khớp với ít nhất một trong các giá trị ID bảo mật trong mã thông báo.
    • Khóa có Thẻ :: USER_AUTH_TYPE khớp với loại xác thực trong mã thông báo.

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

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

Khóa RSA

Tất cả các thao tác khóa RSA 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 trả về ErrorCode::UNSUPPORTED_PADDING_MODE .

Các hoạt động ký và xác minh RSA cần một thông báo, cũng như các hoạt động mã hóa và giải mã RSA với chế độ đệm OAEP. Đối với những trường hợp đó, người gọi chỉ định chính xác một thông báo 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 hoạt động khóa cá nhân ( KeyPurpose::DECYPT và KeyPurpose::SIGN ) cần ủy quyền thông báo và đệm, có nghĩa là ủy quyền khóa cần phải chứa các giá trị được chỉ định. Nếu không, phương thức trả về ErrorCode::INCOMPATIBLE_DIGEST hoặc ErrorCode::INCOMPATIBLE_PADDING , nếu thích hợp. Hoạt động khóa công khai ( KeyPurpose::ENCRYPT và KeyPurpose::VERIFY ) được phép với thông báo hoặc đệm trái phép.

Ngoại trừ PaddingMode::NONE , tất cả các chế độ đệm RSA chỉ có thể á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, trong khi PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT và PaddingMode::RSA_OAEP chỉ hỗ trợ mã hóa và giải mã. Phương thức trả về Mã ErrorCode::UNSUPPORTED_PADDING_MODE nếu chế độ được chỉ định không hỗ trợ mục đích đã chỉ định.

Có một số tương tác quan trọng giữa chế độ đệm và tiêu hóa:

  • PaddingMode::NONE chỉ ra rằng hoạt động RSA "thô" được thực hiện. Nếu ký hoặc xác minh, Digest::NONE được chỉ định cho thông báo. Không cần thông báo để mã hóa hoặc giải mã không được đánh dấu.
  • PaddingMode::RSA_PKCS1_1_5_SIGN padding yêu cầu một thông báo. Thông báo có thể là Digest::NONE , trong trường hợp này, việc triển khai Keymaster không thể xây dựng cấu trúc chữ ký PKCS # 1 v1.5 thích hợp, vì nó không thể thêm cấu trúc DigestInfo. Thay vào đó, việc triển khai xây dựng 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 của khóa RSA phải lớn hơn thông báo ít nhất 11 byte, nếu không phương thức trả về ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding không yêu cầu thông báo.
  • PaddingMode::RSA_PSS padding yêu cầu một thông báo, có thể không phải là Digest::NONE . Nếu Digest::NONE được chỉ định, phương thức trả về ErrorCode::INCOMPATIBLE_DIGEST . Ngoài ra, kích thước của khóa RSA phải lớn hơn ít nhất 2 + D byte so với kích thước đầu ra của thông báo, trong đó D là kích thước của thông báo, tính bằng byte. Nếu không, phương thức trả về ErrorCode::INCOMPATIBLE_DIGEST . Kích thước muối là D.
  • PaddingMode::RSA_OAEP padding yêu cầu một thông báo, có thể không phải là Digest::NONE . Nếu Digest::NONE được chỉ định, phương thức trả về ErrorCode::INCOMPATIBLE_DIGEST .

Phím EC

Các thao tác phím 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 trả về ErrorCode::UNSUPPORTED_PADDING_MODE .

Các hoạt động khóa cá nhân ( KeyPurpose::SIGN ) cần ủy quyền thông báo và đệm, có nghĩa là ủy quyền khóa cần phải chứa các giá trị được chỉ định. Nếu không, hãy trả về ErrorCode::INCOMPATIBLE_DIGEST . Các hoạt động khóa công khai ( KeyPurpose::VERIFY ) được phép với thông báo hoặc phần đệm trái phép.

Các khóa AES

Các thao tác phím AES chỉ định chính xác một chế độ khối và một chế độ đệ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 cấp quyền bởi khóa, nếu không, phương thức trả về ErrorCode::INCOMPATIBLE_BLOCK_MODE hoặc ErrorCode::INCOMPATIBLE_PADDING_MODE .

Nếu chế độ khối là BlockMode::GCM , inParams 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 ủy quyền khóa. Đố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 khóa, hãy trả về ErrorCode::INVALID_MAC_LENGTH .

Nếu chế độ khối là BlockMode::GCM hoặc BlockMode::CTR , thì chế độ đệ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ế độ đệ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ì cần có vectơ khởi tạo hoặc nonce. Trong hầu hết các trường hợp, người gọi không nên cung cấp IV hoặc nonce. Trong trường hợp đó, việc triển khai Keymaster tạo ra một IV hoặc nonce ngẫu nhiên và trả về nó qua Tag :: NONCE trong outParams . CBC và CTR IV là 16 byte. GCM nonces là 12 byte. Nếu ủy quyền khóa chứa Tag :: CALLER_NONCE , thì người gọi có thể cung cấp IV / nonce với Tag :: NONCE trong inParams . Nếu một nonce được cung cấp khi Thẻ :: CALLER_NONCE không được ủy quyền, hãy trả về ErrorCode::CALLER_NONCE_PROHIBITED . Nếu nonce không được cung cấp khi Thẻ :: CALLER_NONCE được cấp phép, hãy tạo IV / nonce ngẫu nhiên.

Khóa HMAC

Các hoạt động chính của 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 độ dài thông báo hoặc nhỏ hơn giá trị của Tag::MIN_MAC_LENGTH trong ủy quyền khóa. Đối với độ dài MAC lớn hơn độ dài thông báo 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 khóa, 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 hoạt động liên tục bắt đầu từ đầu . Hoạt động được chỉ định bởi tham số operationHandle .

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

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

Xử lý lỗi

Nếu phương thức này trả về mã lỗi khác với Mã lỗi ErrorCode::OK , thì thao tác sẽ bị hủy và xử lý thao tác bị vô hiệu. Bất kỳ lần sử dụng tay cầm nào trong tương lai, với phương pháp này, kết thúc hoặc hủy bỏ , đều trả về ErrorCode::INVALID_OPERATION_HANDLE .

Thực thi ủy quyền

Thực thi ủy quyền chính được thực hiện chủ yếu từ đầu . Một ngoại lệ là trường hợp khóa có:

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

Người gọi cung cấp mã xác thực cho mọi cuộc gọi để cập nhật và kết thúc . Việc triển khai chỉ cần xác thực mã thông báo một lần nếu nó thích.

Khóa RSA

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

Khóa ECDSA

Đối với các hoạt động ký và xác minh với Digest::NONE , phương pháp này chấp nhận toàn bộ khối được ký hoặc xác minh trong một bản cập nhật duy nhất. Phương pháp này có thể không chỉ tiêu thụ một phần của khối.

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

Các khóa AES

Chế độ AES GCM hỗ trợ "dữ liệu xác thực được liên kết", được cung cấp qua thẻ Tag :: ASSOCIATED_DATA trong đối số inParams . Dữ liệu liên quan có thể được cung cấp trong các cuộc 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 đặt trước dữ liệu được mã hóa hoặc giải mã. Một lệnh gọi cập nhật có thể nhận được cả dữ liệu được liên kết và dữ liệu để mã hóa / giải mã, nhưng các bản cập nhật tiếp theo có thể không bao gồm dữ liệu được liên kết. Nếu người gọi cung cấp dữ liệu liên quan đến cuộc gọi cập nhật sau cuộc gọi bao gồm dữ liệu để mã hóa / giải mã, hãy trả về ErrorCode::INVALID_TAG .

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

kết thúc

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

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

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure