Tài liệu tham khảo về cấu trúc keymaster2_device

Huỷ một thao tác mã hoá bắt đầu bằng begin() , giải phóng tất cả tài nguyên nội bộ và vô hiệu hoá operation_handle .

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

Thêm entropy vào RNG do keymaster sử dụng. Độ hỗn loạn được thêm thông qua phương thức này được đảm bảo không phải là nguồn độ hỗn loạn duy nhất được sử dụng và hàm trộn phải an toàn, theo nghĩa là nếu RNG được tạo hạt (từ bất kỳ nguồn nào) bằng bất kỳ dữ liệu nào mà kẻ tấn công không thể dự đoán (hoặc kiểm soát), thì đầu ra của RNG không thể phân biệt được với dữ liệu ngẫu nhiên. Do đó, nếu entropy từ bất kỳ nguồn nào đều tốt, thì kết quả sẽ tốt.

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	khác	Dữ liệu ngẫu nhiên sẽ được trộn vào.
[in]	data_length	Độ dài của data .

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

Tạo một chuỗi chứng chỉ X.509 đã ký chứng thực sự hiện diện của key_to_attest trong keymaster (VIỆC CẦN LÀM(swillden): Mô tả chi tiết hơn về nội dung chứng chỉ). Chứng chỉ sẽ chứa một 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 – insert link here>, trong đó chứa nội dung mô tả khoá.

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	key_to_attest	Khoá keymaster mà chứng chỉ chứng thực sẽ được tạo.
[in]	attest_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, phải là KM_ALGORITHM_EC hoặc KM_ALGORITHM_RSA. Thao tác này sẽ chọn khoá chứng thực đã cấp để dùng ký chứng chỉ.
[out]	cert_chain	Một mảng gồm các chứng chỉ X.509 được mã hoá theo DER. Chứng chỉ đầu tiên sẽ là chứng chỉ cho key_to_attest . Các mục còn lại sẽ liên kết trở lại thư mục gốc. Phương thức gọi nắm quyền sở hữu và phải giải phóng bằng keymaster_free_cert_chain.

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

Bắt đầu một thao tác mã hoá bằng khoá đã chỉ định. Nếu mọi thứ đều ổn, begin() sẽ trả về KM_ERROR_OK và tạo một handle thao tác phải được truyền đến các lệnh gọi tiếp theo đến update() , finish() hoặc abort() .

Điều quan trọng là mỗi lệnh gọi đến begin() phải được ghép nối với lệnh gọi tiếp theo đến finish() hoặc abort() để cho phép triển khai keymaster dọn dẹp mọi trạng thái hoạt động nội bộ. Nếu không làm như vậ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 begin() trả về lỗi KM_ERROR_TOO_MANY_OPERATIONS khi hết không gian cho các thao tác. Mọi kết quả khác với KM_ERROR_OK từ begin() , update() hoặc finish() sẽ ngầm huỷ thao tác, trong trường hợp đó, bạn không cần gọi abort() (và sẽ trả về KM_ERROR_INVALID_OPERATION_HANDLE nếu được gọi).

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	mục đích	Mục đích của thao tác, một trong các giá trị KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN hoặc KM_PURPOSE_VERIFY. Xin lưu ý rằng đối với các chế độ AEAD, việc mã hoá và giải mã tương ứng với việc ký và xác minh, nhưng phải được chỉ định là KM_PURPOSE_ENCRYPT và KM_PURPOSE_DECRYPT.
[in]	key	Khoá được dùng cho thao tác. key phải có mục đích tương thích với purpose và phải đáp ứng tất cả các yêu cầu về việc sử dụng, nếu không begin() sẽ trả về một mã lỗi thích hợp.
[in]	in_params	Các tham số bổ sung cho toán tử. Thuộc tính này thường được dùng để cung cấp dữ liệu xác thực, với KM_TAG_AUTH_TOKEN. Nếu bạn đã cung cấp KM_TAG_APPLICATION_ID hoặc KM_TAG_APPLICATION_DATA trong quá trình tạo, thì bạn phải cung cấp các giá trị này tại đây, nếu không thao tác sẽ không thành công với lỗi KM_ERROR_INVALID_KEY_BLOB. Đối với các thao tác yêu cầu số chỉ dùng một lần hoặc IV, trên các khoá được tạo bằng KM_TAG_CALLER_NONCE, in_params có thể chứa thẻ KM_TAG_NONCE.
[out]	out_params	Tham số đầu ra. Dùng để trả về dữ liệu bổ sung từ quá trình khởi chạy thao tác, đặc biệt là để trả về IV hoặc số chỉ dùng một lần từ các thao tác tạo IV hoặc số chỉ dùng một lần. Phương thức gọi nắm quyền sở hữu mảng tham số đầu ra và phải giải phóng mảng đó bằng keymaster_free_param_set() . Bạn có thể đặt out_params thành NULL nếu không có tham số đầu ra nào được dự kiến. 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.
[out]	handle_operation	Tay điều khiển thao tác mới tạo phải được chuyển đến 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 tệp keymaster2.h .

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

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

Định cấu hình keymaster. Bạn phải gọi phương thức này một lần sau khi mở thiết bị và trước khi sử dụng thiết bị. Phương thức 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 việ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.

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

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

Xoá tất cả khoá trong kho khoá phần cứng. Được dùng khi kho khoá đượ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ỳ blob khoá nào đã tạo hoặc nhập trước đó cho bất kỳ thao tác nào.

Hàm này là không bắt buộc và bạn nên đặt thành NULL nếu không triển khai.

Tham số

[in]

dev

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

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

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

Hàm này là không bắt buộc và bạn nên đặt thành NULL nếu không triển khai.

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	key	Khoá cần xoá.

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

Xuất khoá công khai hoặc khoá đối xứng, trả về một mảng byte ở định dạng đã chỉ định.

Xin lưu ý rằng bạn chỉ được phép xuất khoá đối xứng nếu khoá đượ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 khoá (ví dụ: xác thực).

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	export_format	Định dạng dùng để xuất khoá.
[in]	key_to_export	Khoá để xuất.
[in]	client_id	Blob mã ứng dụng khách, phải khớp với blob được cung cấp trong KM_TAG_APPLICATION_ID trong quá trình tạo khoá (nếu có).
[in]	app_data	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 khoá (nếu có).
[out]	export_data	Tài liệu khoá đã xuất. Phương thức gọi giả định quyền sở hữu.

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

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

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	handle_operation	Tay điều khiển thao tác do begin() trả về. Tên người dùng này sẽ không hợp lệ.
[in]	in_params	Các tham số bổ sung cho toán tử. Đối với các chế độ AEAD, giá trị này được 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() .
[in]	input	Dữ liệu cần xử lý, theo các tham số được thiết lập trong lệnh gọi đến begin() . 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.
[in]	Chữ ký	Chữ ký cần được xác minh nếu mục đích được chỉ định trong lệnh gọi begin() là KM_PURPOSE_VERIFY.
[out]	output	Dữ liệu đầu ra, nếu có. Phương thức gọi giả định quyền sở hữu vùng đệm được phân bổ.

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

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

Xem các cờ được xác định cho keymaster0_devices::flags trong keymaster_common.h . Chỉ 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 thành 0.

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

Tạo một khoá hoặc cặp khoá, trả về một blob khoá và/hoặc nội dung mô tả khoá.

Các tham số tạo khoá được xác định là cặp thẻ/giá trị keymaster, được cung cấp trong params . Hãy xem keymaster_tag_t để biết danh sách đầy đủ. Một số giá trị luôn bắt buộc để tạo khoá 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.

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

Bạn phải chỉ định KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH và KM_TAG_DIGEST cho các thuật toán yêu cầu các giá trị này.

Bạn không thể chỉ định các thẻ sau; giá trị của các thẻ này sẽ do quá trình triển khai cung cấp.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	tham số	Mảng tham số tạo khoá
[out]	key_blob	trả về khoá đã tạo. key_blob không được là NULL. Phương thức gọi giả định quyền sở hữu key_blob->key_material và phải giải phóng() quyền đó.
[out]	đặc điểm	trả về các đặc điểm của khoá đã được tạo, nếu không phải là giá trị NULL. Nếu không phải là NULL, phương thức gọi sẽ giả định quyền sở hữu và phải giải phóng bằng keymaster_free_characteristics() . Xin lưu ý rằng KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA không bao giờ được trả về.

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

Trả về các đặc điểm của khoá đã chỉ định hoặc KM_ERROR_INVALID_KEY_BLOB nếu key_blob không hợp lệ (các hoạt động triển khai phải xác thực đầy đủ tính toàn vẹn của khoá). client_id và app_data phải là mã nhận dạng và dữ liệu được cung cấp khi khoá đượ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. Các giá trị đó không được đưa vào các đặc điểm được trả về. Phương thức 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() .

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

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	key_blob	Khoá để truy xuất các đặc điểm.
[in]	client_id	Dữ liệu mã ứng dụng hoặc giá trị NULL nếu không có mã nào được liên kết.
[in]	app_id	Dữ liệu ứng dụng hoặc NULL nếu không có dữ liệu nào được liên kết.
[out]	đặc điểm	Các đặc điểm chính. Không được để trống. Phương thức gọi giả định quyền sở hữu nội dung và phải giải phóng bằng keymaster_free_characteristics() .

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

Nhập một khoá hoặc cặp khoá, trả về một blob khoá và/hoặc nội dung mô tả khoá.

Hầu hết các tham số nhập khoá được xác định là cặp thẻ/giá trị keymaster, được cung cấp trong "params". Hãy xem keymaster_tag_t để biết danh sách đầy đủ. Các giá trị luôn bắt buộc để nhập các khoá 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.

Bạn thường phải chỉ định KM_TAG_AUTH_TIMEOUT. Nếu không 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 đây sẽ lấy giá trị mặc định nếu không được chỉ định:

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

Bạn không thể chỉ định các thẻ sau; giá trị của các thẻ này sẽ do quá trình triển khai cung cấp.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	tham số	Các tham số xác định khoá đã nhập.
[in]	params_count	Số mục nhập trong params .
[in]	key_format	chỉ định định dạng của dữ liệu khoá trong key_data.
[out]	key_blob	Dùng để trả về blob khoá mờ. Không được là giá trị NULL. Phương thức gọi giả định quyền sở hữu đối với key_material được chứa.
[out]	đặc điểm	Dùng để trả về các đặc điểm của khoá đã nhập. Có thể là giá trị NULL, trong trường hợp này, hệ thống sẽ không trả về đặc điểm nào. Nếu không phải là NULL, phương thức gọi sẽ giả định quyền sở hữu nội dung và phải giải phóng bằng keymaster_free_characteristics() . Xin lưu ý rằng KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA không bao giờ được trả về.

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

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

Nếu operation_handle không hợp lệ, thì update() sẽ trả về lỗi KM_ERROR_INVALID_OPERATION_HANDLE.

update() có thể không sử dụng hết tất cả dữ liệu được cung cấp trong vùng đệm dữ liệu. update() sẽ trả về lượng dữ liệu đã tiêu thụ trong *data_consumed. Phương thức gọi phải cung cấp dữ liệu chưa được sử dụng trong lệnh gọi tiếp theo.

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	handle_operation	Tay điều khiển thao tác do begin() trả về.
[in]	in_params	Các tham số bổ sung cho toán tử. Đối với các chế độ AEAD, thuộc tính này được dùng để chỉ định KM_TAG_ADDITIONAL_DATA. Xin lưu ý rằng dữ liệu bổ sung có thể được cung cấp trong nhiều lệnh gọi đến update() , nhưng chỉ cho đến khi dữ liệu đầu vào được cung cấp.
[in]	input	Dữ liệu cần xử lý, theo các tham số được thiết lập trong lệnh gọi đến begin() . Xin lưu ý rằng update() có thể sử dụng hoặc không sử dụng tất cả dữ liệu được cung cấp. Xem input_consumed .
[out]	input_consumed	Lượng dữ liệu mà update() đã sử dụng. Nếu số lượng này ít hơn số lượng đã cung cấp, thì phương thức gọi phải cung cấp số lượng còn lại trong lệnh gọi tiếp theo đến update() .
[out]	out_params	Tham số đầu ra. Dùng để trả về dữ liệu bổ sung từ thao tác. Phương thức gọi sẽ sở hữu mảng tham số đầu ra và phải giải phóng mảng đó bằng keymaster_free_param_set() . Bạn có thể đặt out_params thành NULL nếu không có tham số đầu ra nào được dự kiến. 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.
[out]	output	Dữ liệu đầu ra, nếu có. Phương thức gọi giả định quyền sở hữu vùng đệm được phân bổ. đầu ra không được là giá trị NULL.

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

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

Nâng cấp khoá cũ. Khoá có thể trở thành "cũ" theo hai cách: Keymaster có thể được nâng cấp lên phiên bản mới hoặc hệ thống có thể được cập nhật để vô hiệu hoá 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 khoá cũ sẽ khiến keymaster trả về KM_ERROR_KEY_REQUIRES_UPGRADE. Sau đó, bạn nên gọi phương thức này để nâng cấp khoá.

Tham số

[in]	dev	Cấu trúc thiết bị keymaster.
[in]	key_to_upgrade	Khoá keymaster cần nâng cấp.
[in]	upgrade_params	Các tham số cần thiết để hoàn tất quá trình nâng cấp. Cụ thể, bạn phải có KM_TAG_APPLICATION_ID và KM_TAG_APPLICATION_DATA nếu các giá trị này được xác định cho khoá.
[out]	upgraded_key	Blob khoá đã nâng cấp.

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