Tham chiếu cấu trúc keymaster2_device

Hủy bỏ một hoạt động mã hóa bắt đầu bằng Begin() , giải phóng tất cả tài nguyên nội bộ và vô hiệu hóa operation_handle .

Định nghĩa tại dòng 415 của file keymaster2.h .

Thêm entropy vào RNG được keymaster sử dụng. Entropy được thêm vào thông qua phương pháp này được đảm bảo không phải là nguồn entropy duy nhất được sử dụng và chức năng trộn bắt buộc phải an toàn, theo nghĩa là nếu RNG được gieo mầm (từ bất kỳ nguồn nào) với bất kỳ dữ liệu nào thì kẻ tấn công không thể dự đoán (hoặc control), thì đầu ra RNG không thể phân biệt được với ngẫu nhiên. Vì vậy, nếu entropy từ bất kỳ nguồn nào tốt thì đầu ra sẽ tốt.

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	dữ liệu	Dữ liệu ngẫu nhiên được trộn lẫn vào.
[TRONG]	dữ liệu_độ dài	Độ dài của data .

Định nghĩa tại dòng 74 của file keymaster2.h .

Tạo chuỗi chứng chỉ X.509 đã ký xác nhận sự hiện diện của key_to_attest trong keymaster (TODO(swillden): Mô tả nội dung chứng chỉ chi tiết hơn). Chứng chỉ sẽ chứa phần mở rộng có OID 1.3.6.1.4.1.11129.2.1.17 và giá trị được xác định trong <TODO:swillden – chèn liên kết vào đây> chứa mô tả khóa.

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	key_to_attest	Khóa keymaster mà chứng chỉ chứng thực sẽ được tạo.
[TRONG]	chứng thực_params	Các tham số xác định cách thực hiện chứng thực. Hiện tại, tham số duy nhất là KM_TAG_ALGORITHM, tham số này phải là KM_ALGORITHM_EC hoặc KM_ALGORITHM_RSA. Thao tác này sẽ chọn khóa chứng thực được cung cấp nào sẽ được sử dụng để ký chứng chỉ.
[ngoài]	cert_chain	Một loạt chứng chỉ X.509 được mã hóa DER. Đầu tiên sẽ là chứng chỉ cho key_to_attest . Các mục còn lại sẽ xâu chuỗi trở lại thư mục gốc. Người gọi có quyền sở hữu và phải phân bổ bằng keymaster_free_cert_chain.

Định nghĩa tại dòng 239 của file keymaster2.h .

Bắt đầu một hoạt động mã hóa bằng cách sử dụng khóa được chỉ định. Nếu tất cả đều ổn, Begin() sẽ trả về KM_ERROR_OK và tạo một bộ điều khiển thao tác phải được chuyển cho các lệnh gọi tiếp theo tới update() , finish() hoặc abort() .

Điều quan trọng là mỗi lệnh gọi hàm started() phải được ghép nối với lệnh gọi tiếp theo tới finish() hoặc abort() để cho phép quá trình triển khai keymaster dọn sạch mọi trạng thái hoạt động nội bộ. Việc không thực hiện điều này có thể làm rò rỉ không gian trạng thái nội bộ hoặc các tài nguyên nội bộ khác và cuối cùng có thể khiến start() trả về KM_ERROR_TOO_MANY_OPERATIONS khi hết dung lượng cho các hoạt động. Bất kỳ kết quả nào khác ngoài KM_ERROR_OK từ Begin() , update() hoặc finish() đều ngầm hủy bỏ thao tác, trong trường hợp đó abort() không cần được gọi (và sẽ trả về KM_ERROR_INVALID_OPERATION_HANDLE nếu được gọi).

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	mục đích	Mục đích của hoạt động, một trong các KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN hoặc KM_PURPOSE_VERIFY. Lưu ý rằng đối với chế độ AEAD, mã hóa và giải mã ngụ ý việc ký và xác minh tương ứng nhưng phải được chỉ định là KM_PURPOSE_ENCRYPT và KM_PURPOSE_DECRYPT.
[TRONG]	chìa khóa	Chìa khóa được sử dụng cho hoạt động. key phải có mục đích tương thích với purpose và tất cả các yêu cầu sử dụng của nó phải được đáp ứng, nếu không Begin() sẽ trả về mã lỗi thích hợp.
[TRONG]	in_params	Các thông số bổ sung cho hoạt động. Điều này thường được sử dụng để cung cấp dữ liệu xác thực với KM_TAG_AUTH_TOKEN. Nếu KM_TAG_APPLICATION_ID hoặc KM_TAG_APPLICATION_DATA được cung cấp trong quá trình tạo thì chúng phải được cung cấp ở đây, nếu không thao tác sẽ không thành công với KM_ERROR_INVALID_KEY_BLOB. Đối với các thao tác yêu cầu nonce hoặc IV, trên các khóa được tạo bằng KM_TAG_CALLER_NONCE, in_params có thể chứa thẻ KM_TAG_NONCE.
[ngoài]	out_params	Các thông số đầu ra. Được sử dụng để trả về dữ liệu bổ sung từ quá trình khởi tạo hoạt động, đặc biệt là trả về IV hoặc nonce từ các hoạt động tạo ra IV hoặc nonce. Người gọi có quyền sở hữu mảng tham số đầu ra và phải giải phóng nó bằng keymaster_free_param_set() . out_params có thể được đặt thành NULL nếu không có tham số đầu ra nào được mong đợi. Nếu out_params là NULL và các tham số đầu ra được tạo, thì Begin() sẽ trả về KM_ERROR_OUTPUT_PARAMETER_NULL.
[ngoài]	thao tác_xử lý	Bộ điều khiển thao tác mới được tạo phải được chuyển tới update() , finish() hoặc abort() . Nếu Operation_handle là NULL, thì Begin() sẽ trả về KM_ERROR_OUTPUT_PARAMETER_NULL.

Định nghĩa tại dòng 332 của file keymaster2.h .

Các phương pháp phổ biến của thiết bị keymaster. Đây phải là thành viên đầu tiên của keymaster_device vì người dùng cấu trúc này sẽ truyền một con trỏ hw_device_t tới keymaster_device trong các ngữ cảnh đã biết hw_device_t tham chiếu đến keymaster_device.

Định nghĩa tại dòng 35 của file keymaster2.h .

Định cấu hình keymaster. Phương thức này phải được gọi một lần sau khi thiết bị được mở và trước khi sử dụng. Nó được sử 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ị được cung cấp bởi phương pháp này chỉ được keymaster chấp nhận một lần cho mỗi lần khởi động. Các cuộc gọi tiếp theo sẽ trả về KM_ERROR_OK nhưng không làm gì cả.

Nếu việc triển khai keymaster trong phần cứng bảo mật và các giá trị phiên bản hệ điều hành cũng như mức bản vá được cung cấp không khớp với các giá trị được bộ tải khởi động cung cấp cho phần cứng bảo mật (hoặc nếu bộ 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 pháp khác sẽ tiếp tục trả về KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Định nghĩa tại dòng 58 của file keymaster2.h .

Định nghĩa tại dòng 37 của file keymaster2.h .

Xóa tất cả các khóa trong kho khóa phần cứng. Được sử dụng khi kho khóa được đặt lại hoàn toàn. Sau khi gọi hàm này, bạn sẽ không thể sử dụng bất kỳ đốm màu khóa nào được tạo hoặc nhập trước đó cho bất kỳ thao tác nào.

Chức năng này là tùy chọn và phải được đặt thành NULL nếu nó không được triển khai.

Thông số

[TRONG]

nhà phát triển

Cấu trúc thiết bị keymaster

Định nghĩa tại dòng 288 của file keymaster2.h .

Xóa khóa hoặc cặp khóa được liên kết với blob khóa. Sau khi gọi hàm này, bạn sẽ không thể sử dụng phím này cho bất kỳ thao tác nào khác. Có thể được áp dụng cho các khóa từ nguồn gốc tin cậy nước ngoài (các khóa không thể sử dụng được theo nguồn gốc tin cậy hiện tại).

Chức năng này là tùy chọn và phải được đặt thành NULL nếu nó không được triển khai.

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	chìa khóa	Chìa khóa cần xóa.

Định nghĩa tại dòng 276 của file keymaster2.h .

Xuất khóa chung hoặc khóa đối xứng, trả về một mảng byte theo định dạng đã chỉ định.

Lưu ý rằng chỉ cho phép xuất khóa đối xứng nếu khóa được tạo bằng KM_TAG_EXPORTABLE và chỉ khi đáp ứng tất cả các yêu cầu về việc sử dụng khóa (ví dụ: xác thực).

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	định dạng xuất	Định dạng được sử dụng để xuất khóa.
[TRONG]	key_to_export	Chìa khóa để xuất khẩu.
[TRONG]	client_id	blob ID khách hàng phải khớp với blob được cung cấp trong KM_TAG_APPLICATION_ID trong quá trình tạo khóa (nếu có).
[TRONG]	dữ liệu chương trình	Blob dữ liệu ứng dụng phải khớp với blob được cung cấp trong KM_TAG_APPLICATION_DATA trong quá trình tạo khóa (nếu có).
[ngoài]	xuất dữ liệu	Vật liệu chính được xuất khẩu. Người gọi thừa nhận quyền sở hữu.

Định nghĩa tại dòng 213 của file keymaster2.h .

Hoàn tất một thao tác mã hóa bắt đầu bằng start() và vô hiệu hóa operation_handle .

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	thao tác_xử lý	Bộ điều khiển thao tác được trả về bởi Begin() . Tay cầm này sẽ bị vô hiệu.
[TRONG]	in_params	Các thông số bổ sung cho hoạt động. Đối với chế độ AEAD, điều này được sử dụng để chỉ định KM_TAG_ADDITIONAL_DATA, nhưng chỉ khi không có dữ liệu đầu vào nào được cung cấp cho update() .
[TRONG]	đầu vào	Dữ liệu cần được xử lý, theo các tham số được thiết lập trong lệnh gọi hàm started() . finish() phải sử dụng tất cả dữ liệu được cung cấp hoặc trả về KM_ERROR_INVALID_INPUT_LENGTH.
[TRONG]	chữ ký	Chữ ký cần được xác minh nếu mục đích được chỉ định trong lệnh gọi start() là KM_PURPOSE_VERIFY.
[ngoài]	đầu ra	Dữ liệu đầu ra, nếu có. Người gọi giả định quyền sở hữu bộ đệm được phân bổ.

Nếu thao tác đang kết thúc là xác minh chữ ký hoặc giải mã và xác minh ở chế độ AEAD không thành công thì kết thúc() sẽ trả về KM_ERROR_VERIFICATION_FAILED.

Định nghĩa tại dòng 405 của file keymaster2.h .

Xem các cờ được xác định cho keymaster0_devices::flags trong keymaster_common.h . Chỉ được sử dụng để tương thích ngược; các thiết bị phần cứng keymaster2 phải đặt giá trị này về 0.

Định nghĩa tại dòng 43 của file keymaster2.h .

Tạo một khóa hoặc cặp khóa, trả về một blob khóa và/hoặc mô tả về khóa.

Các tham số tạo khóa được xác định là cặp thẻ/giá trị keymaster, được cung cấp trong params . Xem keymaster_tag_t để biết danh sách đầy đủ. Một số giá trị luôn được yêu cầu để tạo khóa hữu ích là:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; Và
• (KM_TAG_USER_SECURE_ID và KM_TAG_USER_AUTH_TYPE) hoặc KM_TAG_NO_AUTH_REQUIRED.

Nói chung, nên chỉ định KM_TAG_AUTH_TIMEOUT trừ khi có KM_TAG_NO_AUTH_REQUIRED, nếu không người dùng sẽ phải xác thực cho mỗi lần sử dụng.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH và KM_TAG_DIGEST phải được chỉ định cho các thuật toán yêu cầu chúng.

Các thẻ sau có thể không được chỉ định; giá trị của chúng sẽ được cung cấp bởi việc thực hiện.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	thông số	Mảng thông số tạo khóa
[ngoài]	key_blob	trả về khóa được tạo. key_blob không được là NULL. Người gọi thừa nhận quyền sở hữu key_blob->key_material và phải giải phóng() nó.
[ngoài]	đặc trưng	trả về các đặc điểm của khóa đã được tạo nếu không phải là NULL. Nếu không phải là NULL, người gọi sẽ có quyền sở hữu và phải phân bổ keymaster_free_characteristics() . Lưu ý rằng KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA không bao giờ được trả lại.

Định nghĩa tại dòng 112 của file keymaster2.h .

Trả về các đặc điểm của khóa được chỉ định hoặc KM_ERROR_INVALID_KEY_BLOB nếu key_blob không hợp lệ (việc triển khai phải xác thực đầy đủ tính toàn vẹn của khóa). client_id và app_data phải là ID và dữ liệu được cung cấp khi khóa được tạo hoặc nhập hoặc trống nếu KM_TAG_APPLICATION_ID và/hoặc KM_TAG_APPLICATION_DATA không được cung cấp trong quá trình tạo. Những giá trị đó không được bao gồm trong các đặc tính được trả về. Người gọi giả định quyền sở hữu đối tượng đặc điểm được phân bổ, đối tượng này phải được giải phóng bằng keymaster_free_characteristics() .

Lưu ý rằng KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA không bao giờ được trả lại.

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	key_blob	Chìa khóa để lấy lại các đặc điểm từ.
[TRONG]	client_id	Dữ liệu ID khách hàng hoặc NULL nếu không được liên kết.
[TRONG]	id ứng dụng	Dữ liệu ứng dụng hoặc NULL nếu không được liên kết.
[ngoài]	đặc trưng	Các đặc điểm chính. Nó không vô giá trị. Người gọi thừa nhận quyền sở hữu nội dung và phải phân bổ keymaster_free_characteristics() .

Định nghĩa tại dòng 139 của file keymaster2.h .

Nhập một khóa hoặc cặp khóa, trả về một blob khóa và/hoặc mô tả về khóa.

Hầu hết các tham số nhập khóa được xác định dưới dạng cặp thẻ/giá trị keymaster, được cung cấp trong "params". Xem keymaster_tag_t để biết danh sách đầy đủ. Các giá trị luôn được yêu cầu để nhập các khóa hữu ích là:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; Và
• (KM_TAG_USER_SECURE_ID và KM_TAG_USER_AUTH_TYPE) hoặc KM_TAG_NO_AUTH_REQUIRED.

Nói chung nên chỉ định KM_TAG_AUTH_TIMEOUT. Nếu không được chỉ định, người dùng sẽ phải xác thực cho mỗi lần sử dụng.

Các thẻ sau sẽ nhận giá trị mặc định nếu không được chỉ định:

• KM_TAG_KEY_SIZE sẽ mặc định theo kích thước của khóa được cung cấp.
• KM_TAG_RSA_PUBLIC_EXPONENT sẽ mặc định có giá trị trong khóa được cung cấp (đối với khóa RSA)

Các thẻ sau có thể không được chỉ định; giá trị của chúng sẽ được cung cấp bởi việc thực hiện.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	thông số	Các tham số xác định khóa được nhập.
[TRONG]	thông số_count	Số lượng mục trong params .
[TRONG]	key_format	chỉ định định dạng của dữ liệu chính trong key_data.
[ngoài]	key_blob	Được sử dụng để trả về đốm màu khóa mờ. Phải là non-NULL. Người gọi thừa nhận quyền sở hữu key_material chứa trong đó.
[ngoài]	đặc trưng	Được sử dụng để trả về các đặc tính của khóa đã nhập. Có thể là NULL, trong trường hợp đó sẽ không có đặc điểm nào được trả về. Nếu không phải là NULL, người gọi sẽ thừa nhận quyền sở hữu nội dung và phải phân bổ keymaster_free_characteristics() . Lưu ý rằng KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA không bao giờ được trả lại.

Định nghĩa tại dòng 186 của file keymaster2.h .

Cung cấp dữ liệu và có thể nhận đầu ra từ một hoạt động mã hóa đang diễn ra bắt đầu bằng Begin() .

Nếu Operation_handle không hợp lệ, update() sẽ trả về KM_ERROR_INVALID_OPERATION_HANDLE.

update() có thể không tiêu thụ hết dữ liệu được cung cấp trong bộ đệm dữ liệu. update() sẽ trả về số tiền đã tiêu thụ trong *data_consumed. Người gọi sẽ cung cấp dữ liệu chưa được sử dụng trong cuộc gọi tiếp theo.

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	thao tác_xử lý	Bộ điều khiển thao tác được trả về bởi Begin() .
[TRONG]	in_params	Các thông số bổ sung cho hoạt động. Đối với chế độ AEAD, điều này được sử dụng để chỉ định KM_TAG_ADDITIONAL_DATA. Lưu ý rằng dữ liệu bổ sung có thể được cung cấp trong nhiều lệnh gọi tới update() , nhưng chỉ cho đến khi dữ liệu đầu vào được cung cấp.
[TRONG]	đầu vào	Dữ liệu cần được xử lý, theo các tham số được thiết lập trong lệnh gọi hàm started() . Lưu ý rằng update() có thể tiêu thụ hoặc không tiêu thụ tất cả dữ liệu được cung cấp. Xem input_consumed .
[ngoài]	đầu vào_tiêu thụ	Lượng dữ liệu đã được sử dụng bởi update() . Nếu số tiền này nhỏ hơn số tiền được cung cấp, người gọi sẽ cung cấp phần còn lại trong lệnh gọi tiếp theo tới update() .
[ngoài]	out_params	Các thông số đầu ra. Được sử dụng để trả về dữ liệu bổ sung từ thao tác Người gọi có quyền sở hữu mảng tham số đầu ra và phải giải phóng nó bằng keymaster_free_param_set() . out_params có thể được đặt thành NULL nếu không có tham số đầu ra nào được mong đợi. Nếu out_params là NULL và các tham số đầu ra được tạo, thì Begin() sẽ trả về KM_ERROR_OUTPUT_PARAMETER_NULL.
[ngoài]	đầu ra	Dữ liệu đầu ra, nếu có. Người gọi giả định quyền sở hữu bộ đệm được phân bổ. đầu ra không được là NULL.

Lưu ý rằng update() có thể không cung cấp bất kỳ đầu ra nào, trong trường hợp đó, đầu ra->data_length sẽ bằng 0 và đầu ra->dữ liệu có thể là NULL hoặc có độ dài bằng 0 (vì vậy người gọi phải luôn free() nó).

Định nghĩa tại dòng 376 của file keymaster2.h .

Nâng cấp chìa khóa cũ. Khóa có thể trở nên "cũ" theo hai cách: Keymaster có thể được nâng cấp lên phiên bản mới hoặc có thể cập nhật hệ thống để vô hiệu hóa phiên bản hệ điều hành và/hoặc cấp độ bản vá. Trong cả hai trường hợp, việc cố gắng sử dụng khóa cũ sẽ dẫn đến việc keymaster trả về KM_ERROR_KEY_REQUIRES_UPGRADE. Phương pháp này sau đó sẽ được gọi để nâng cấp khóa.

Thông số

[TRONG]	nhà phát triển	Cấu trúc thiết bị keymaster
[TRONG]	key_to_upgrade	Chìa khóa keymaster để nâng cấp.
[TRONG]	nâng cấp_params	Các thông số cần thiết để hoàn thành nâng cấp. Đặc biệt, KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA sẽ được yêu cầu nếu chúng được xác định cho khóa.
[ngoài]	nâng cấp_key	Các đốm màu chính được nâng cấp.

Định nghĩa tại dòng 260 của file keymaster2.h .