keymaster2_device 구조체 참조

begin() 로 시작된 암호화 작업을 중단하여 모든 내부 리소스를 해제하고 operation_handle 를 무효화합니다.

keymaster2.h 파일의 415 번 행에 정의되어 있습니다.

키마스터에서 사용하는 RNG에 엔트로피를 추가합니다. 이 메서드를 통해 추가된 엔트로피는 사용되는 유일한 엔트로피 소스가 아닙니다. 또한 혼합 함수는 공격자가 예측하거나 제어할 수 없는 데이터로 RNG가 시드된 경우 RNG 출력이 무작위와 구별할 수 없다는 의미에서 안전해야 합니다. 따라서 소스의 엔트로피가 좋으면 출력도 좋습니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	데이터	혼합할 임의 데이터입니다.
[in]	data_length	data 의 길이입니다.

keymaster2.h 파일의 74 번 째 줄에 정의되어 있습니다.

키 마스터에 key_to_attest 가 있음을 증명하는 서명된 X.509 인증서 체인을 생성합니다 (TODO(swillden): 인증서 콘텐츠를 더 자세히 설명하세요). 인증서에는 OID 1.3.6.1.4.1.11129.2.1.17의 확장자가 포함되며 키 설명이 포함된 값은 <TODO:swillden – 여기에 링크 삽입>에 정의됩니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	key_to_attest	증명 인증서가 생성될 키마스터 키입니다.
[in]	attest_params	증명 방법을 정의하는 매개변수입니다. 현재 유일한 매개변수는 KM_TAG_ALGORITHM이며 KM_ALGORITHM_EC 또는 KM_ALGORITHM_RSA여야 합니다. 이렇게 하면 인증서 서명에 사용할 프로비저닝된 증명 키 중 하나가 선택됩니다.
[out]	cert_chain	DER로 인코딩된 X.509 인증서 배열입니다. 첫 번째는 key_to_attest 의 인증서입니다. 나머지 항목은 루트로 다시 연결됩니다. 호출자가 소유권을 가져오며 keymaster_free_cert_chain으로 할당 해제해야 합니다.

keymaster2.h FILE의 239 행에 정의되어 있습니다.

지정된 키를 사용하여 암호화 작업을 시작합니다. 문제가 없으면 begin() 는 KM_ERROR_OK를 반환하고 작업 핸들을 만듭니다. 이 핸들은 이후 update() , finish() 또는 abort() 호출에 전달해야 합니다.

키마스터 구현에서 내부 작업 상태를 정리할 수 있도록 하려면 begin() 를 호출할 때마다 후속 finish() 또는 abort() 호출과 페어링해야 합니다. 이렇게 하지 않으면 내부 상태 공간 또는 기타 내부 리소스가 유출될 수 있으며 결국 작업 공간이 부족할 때 begin() 이 KM_ERROR_TOO_MANY_OPERATIONS를 반환할 수 있습니다. begin() , update() 또는 finish() 의 KM_ERROR_OK 이외의 결과는 작업을 암시적으로 중단합니다. 이 경우 abort() 를 호출할 필요가 없으며 호출하면 KM_ERROR_INVALID_OPERATION_HANDLE이 반환됩니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	목적	작업의 목적입니다. KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN 또는 KM_PURPOSE_VERIFY 중 하나입니다. AEAD 모드의 경우 암호화 및 복호화는 각각 서명 및 인증을 의미하지만 KM_PURPOSE_ENCRYPT 및 KM_PURPOSE_DECRYPT로 지정해야 합니다.
[in]	키	작업에 사용할 키입니다. key 는 purpose 와 호환되는 목적을 가져야 하며 모든 사용 요구사항이 충족되어야 합니다. 그렇지 않으면 begin() 이 적절한 오류 코드를 반환합니다.
[in]	in_params	작업의 추가 매개변수입니다. 일반적으로 KM_TAG_AUTH_TOKEN과 함께 인증 데이터를 제공하는 데 사용됩니다. 생성 중에 KM_TAG_APPLICATION_ID 또는 KM_TAG_APPLICATION_DATA가 제공된 경우 여기에 제공해야 합니다. 그러지 않으면 KM_ERROR_INVALID_KEY_BLOB과 함께 작업이 실패합니다. nonce 또는 IV가 필요한 작업의 경우 KM_TAG_CALLER_NONCE로 생성된 키에서 in_params에 KM_TAG_NONCE 태그가 포함될 수 있습니다.
[out]	out_params	출력 매개변수 작업 초기화에서 추가 데이터를 반환하는 데 사용됩니다. 특히 IV 또는 nonce를 생성하는 작업에서 IV 또는 nonce를 반환하는 데 사용됩니다. 호출자는 출력 매개변수 배열의 소유권을 가져와 keymaster_free_param_set() 을 사용하여 해제해야 합니다. 출력 매개변수가 예상되지 않는 경우 out_params는 NULL로 설정될 수 있습니다. out_params가 NULL이고 출력 매개변수가 생성되면 begin() 은 KM_ERROR_OUTPUT_PARAMETER_NULL을 반환합니다.
[out]	operation_handle	새로 만든 작업 핸들로, update() , finish() 또는 abort() 에 전달해야 합니다. operation_handle이 NULL이면 begin() 이 KM_ERROR_OUTPUT_PARAMETER_NULL을 반환합니다.

keymaster2.h FILE의 332 행에 정의되어 있습니다.

Keymaster 기기의 일반적인 메서드입니다. 이 구조체의 사용자는 hw_device_t 가 keymaster_device를 참조하는 것으로 알려진 컨텍스트에서 hw_device_t 를 keymaster_device 포인터로 변환하므로 이 필드는 keymaster_device의 첫 번째 구성원이어야 합니다.

keymaster2.h 파일의 35 번 행에 정의되어 있습니다.

Keymaster를 구성합니다. 이 메서드는 기기를 연 후 사용하기 전에 한 번 호출해야 합니다. 이 메서드는 Keymaster에 KM_TAG_OS_VERSION 및 KM_TAG_OS_PATCHLEVEL을 제공하는 데 사용됩니다. 이 메서드가 호출될 때까지 다른 모든 메서드는 KM_ERROR_KEYMASTER_NOT_CONFIGURED를 반환합니다. Keymaster에서는 이 메서드에서 제공하는 값을 부팅당 한 번만 적용합니다. 후속 호출은 KM_ERROR_OK를 반환하지만 아무 작업도 하지 않습니다.

키마스터 구현이 보안 하드웨어에 있고 제공된 OS 버전 및 패치 수준 값이 부트로더가 보안 하드웨어에 제공한 값과 일치하지 않거나 부트로더가 값을 제공하지 않은 경우 이 메서드는 KM_ERROR_INVALID_ARGUMENT를 반환하고 다른 모든 메서드는 계속해서 KM_ERROR_KEYMASTER_NOT_CONFIGURED를 반환합니다.

keymaster2.h FILE의 58 행에 정의되어 있습니다.

keymaster2.h FILE의 37 행에 정의되어 있습니다.

하드웨어 키 저장소의 모든 키를 삭제합니다. 키 저장소가 완전히 재설정될 때 사용됩니다. 이 함수를 호출한 후에는 이전에 생성되거나 가져온 키 블롭을 작업에 사용할 수 없습니다.

이 함수는 선택사항이며 구현되지 않은 경우 NULL로 설정해야 합니다.

매개변수

[in]

dev

Keymaster 기기 구조입니다.

keymaster2.h 파일의 288 번 행에 정의되어 있습니다.

키 블록과 연결된 키 또는 키 쌍을 삭제합니다. 이 함수를 호출한 후에는 다른 작업에 키를 사용할 수 없습니다. 외부 신뢰할 수 있는 루트의 키 (현재 신뢰할 수 있는 루트에서 사용할 수 없는 키)에 적용될 수 있습니다.

이 함수는 선택사항이며 구현되지 않은 경우 NULL로 설정해야 합니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	키	삭제할 키입니다.

keymaster2.h FILE의 276 라인에 정의되어 있습니다.

공개 키 또는 대칭 키를 내보내 지정된 형식의 바이트 배열을 반환합니다.

대칭 키 내보내기는 키가 KM_TAG_EXPORTABLE로 생성된 경우에만 허용되며 키 사용에 관한 모든 요구사항 (예: 인증)이 충족된 경우에만 허용됩니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	export_format	키를 내보내는 데 사용할 형식입니다.
[in]	key_to_export	내보낼 키입니다.
[in]	client_id	키 생성 중에 KM_TAG_APPLICATION_ID에 제공된 blob (있는 경우)과 일치해야 하는 고객 ID blob
[in]	app_data	애플리케이션 데이터 blob은 키 생성 중에 KM_TAG_APPLICATION_DATA에 제공된 blob (있는 경우)과 일치해야 합니다.
[out]	export_data	내보낸 키 자료입니다. 호출자가 소유권을 가정합니다.

keymaster2.h 파일의 213 행에 정의되어 있습니다.

begin() 으로 시작된 암호화 작업을 완료하고 operation_handle 를 무효화합니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	operation_handle	begin() 에서 반환된 작업 핸들입니다. 이 핸들은 무효화됩니다.
[in]	in_params	작업의 추가 매개변수입니다. AEAD 모드의 경우 update() 에 입력 데이터가 제공되지 않은 경우에만 KM_TAG_ADDITIONAL_DATA를 지정하는 데 사용됩니다.
[in]	입력	begin() 호출에서 설정된 매개변수에 따라 처리할 데이터입니다. finish() 는 제공된 모든 데이터를 사용하거나 KM_ERROR_INVALID_INPUT_LENGTH를 반환해야 합니다.
[in]	서명	begin() 호출에 지정된 목적이 KM_PURPOSE_VERIFY인 경우 확인할 서명입니다.
[out]	output	출력 데이터(있는 경우) 호출자가 할당된 버퍼의 소유권을 가정합니다.

완료 중인 작업이 서명 확인 또는 AEAD 모드 복호화이고 확인에 실패하면 finish() 는 KM_ERROR_VERIFICATION_FAILED를 반환합니다.

keymaster2.h 파일의 405 번 행에 정의되어 있습니다.

keymaster_common.h 에서 keymaster0_devices::flags에 정의된 플래그를 참고하세요. 이전 버전과의 호환성에만 사용됩니다. keymaster2 하드웨어 기기는 이를 0으로 설정해야 합니다.

keymaster2.h 파일의 43 번 라인에 정의되어 있습니다.

키 또는 키 쌍을 생성하여 키 blob 또는 키 설명을 반환합니다.

키 생성 매개변수는 params 에 제공된 키마스터 태그/값 쌍으로 정의됩니다. 전체 목록은 keymaster_tag_t를 참고하세요. 유용한 키를 생성하는 데 항상 필요한 몇 가지 값은 다음과 같습니다.

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE;
• (KM_TAG_USER_SECURE_ID 및 KM_TAG_USER_AUTH_TYPE) 또는 KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_NO_AUTH_REQUIRED가 있는 것이 아니라면 일반적으로 KM_TAG_AUTH_TIMEOUT을 지정해야 합니다. 그렇지 않으면 사용자가 사용할 때마다 인증해야 합니다.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH, KM_TAG_DIGEST는 이러한 속성이 필요한 알고리즘에 지정해야 합니다.

다음 태그는 지정할 수 없습니다. 값은 구현에서 제공합니다.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	params	키 생성 매개변수 배열
[out]	key_blob	생성된 키를 반환합니다. key_blob 은 null이 아니어야 합니다. 호출자는 key_blob->key_material의 소유권을 가정하고 free()해야 합니다.
[out]	특성	생성된 키의 특성을 반환합니다(NULL이 아닐 경우). NULL이 아닌 경우 호출자가 소유권을 가정하고 keymaster_free_characteristics() 를 사용하여 할당 해제해야 합니다. KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID, KM_TAG_APPLICATION_DATA는 반환되지 않습니다.

keymaster2.h FILE의 112 라인에 정의되어 있습니다.

지정된 키의 특성을 반환하거나 key_blob이 잘못된 경우 KM_ERROR_INVALID_KEY_BLOB을 반환합니다 (구현은 키의 무결성을 완전히 검증해야 함). client_id 및 app_data는 키가 생성 또는 가져올 때 제공된 ID 및 데이터여야 하며, 생성 중에 KM_TAG_APPLICATION_ID 또는 KM_TAG_APPLICATION_DATA가 제공되지 않은 경우에는 비어 있어야 합니다. 이러한 값은 반환된 특성에 포함되지 않습니다. 호출자는 할당된 특성 객체의 소유권을 가정하며, 이 객체는 keymaster_free_characteristics() 로 할당 해제해야 합니다.

KM_TAG_APPLICATION_ID 및 KM_TAG_APPLICATION_DATA는 반환되지 않습니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	key_blob	특성을 가져올 키입니다.
[in]	client_id	클라이언트 ID 데이터 또는 연결된 항목이 없는 경우 NULL입니다.
[in]	app_id	앱 데이터 또는 연결된 데이터가 없는 경우 NULL입니다.
[out]	특성	주요 특징 null이 아니어야 합니다. 호출자는 콘텐츠의 소유권을 가정하고 keymaster_free_characteristics() 로 할당 해제해야 합니다.

keymaster2.h 파일의 139 행에 정의되어 있습니다.

키 또는 키 쌍을 가져와 키 blob 또는 키 설명을 반환합니다.

대부분의 키 가져오기 매개변수는 'params'에 제공된 키마스터 태그/값 쌍으로 정의됩니다. 전체 목록은 keymaster_tag_t를 참고하세요. 유용한 키를 가져올 때 항상 필요한 값은 다음과 같습니다.

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE;
• (KM_TAG_USER_SECURE_ID 및 KM_TAG_USER_AUTH_TYPE) 또는 KM_TAG_NO_AUTH_REQUIRED.

일반적으로 KM_TAG_AUTH_TIMEOUT을 지정해야 합니다. 지정하지 않으면 사용자는 매번 인증해야 합니다.

다음 태그는 지정되지 않은 경우 기본값을 사용합니다.

• KM_TAG_KEY_SIZE는 기본적으로 제공된 키의 크기로 설정됩니다.
• KM_TAG_RSA_PUBLIC_EXPONENT는 기본적으로 제공된 키의 값으로 설정됩니다 (RSA 키의 경우).

다음 태그는 지정할 수 없습니다. 값은 구현에서 제공합니다.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	params	가져온 키를 정의하는 매개변수입니다.
[in]	params_count	params 의 항목 수입니다.
[in]	key_format	key_data에 있는 키 데이터의 형식을 지정합니다.
[out]	key_blob	불투명 키 blob을 반환하는 데 사용됩니다. NULL이 아니어야 합니다. 호출자는 포함된 key_material의 소유권을 가정합니다.
[out]	특성	가져온 키의 특성을 반환하는 데 사용됩니다. NULL일 수 있으며, 이 경우 특성이 반환되지 않습니다. NULL이 아닌 경우 호출자가 콘텐츠의 소유권을 가정하고 keymaster_free_characteristics() 를 사용하여 할당 해제해야 합니다. KM_TAG_APPLICATION_ID 및 KM_TAG_APPLICATION_DATA는 반환되지 않습니다.

keymaster2.h 파일의 186 번 행에 정의되어 있습니다.

begin() 로 시작된 진행 중인 암호화 작업에 데이터를 제공하고 출력을 수신할 수 있습니다.

operation_handle이 잘못된 경우 update() 는 KM_ERROR_INVALID_OPERATION_HANDLE을 반환합니다.

update() 는 데이터 버퍼에 제공된 모든 데이터를 사용하지 않을 수 있습니다. update() 는 *data_consumed에서 소비된 양을 반환합니다. 호출자는 후속 호출에서 사용되지 않은 데이터를 제공해야 합니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	operation_handle	begin() 에서 반환된 작업 핸들입니다.
[in]	in_params	작업의 추가 매개변수입니다. AEAD 모드의 경우 KM_TAG_ADDITIONAL_DATA를 지정하는 데 사용됩니다. update() 를 여러 번 호출할 때 추가 데이터가 제공될 수 있지만, 입력 데이터가 제공될 때까지만 제공됩니다.
[in]	입력	begin() 호출에서 설정된 매개변수에 따라 처리할 데이터입니다. update() 는 제공된 모든 데이터를 사용할 수도 있고 사용하지 않을 수도 있습니다. input_consumed 를 참고하세요.
[out]	input_consumed	update() 에서 소비된 데이터 양입니다. 이 값이 제공된 금액보다 적으면 호출자는 후속 update() 호출에서 나머지를 제공해야 합니다.
[out]	out_params	출력 매개변수 작업에서 추가 데이터를 반환하는 데 사용됩니다. 호출자는 출력 매개변수 배열의 소유권을 가져와야 하며 keymaster_free_param_set() 을 사용하여 이를 해제해야 합니다. 출력 매개변수가 예상되지 않는 경우 out_params는 NULL로 설정될 수 있습니다. out_params가 NULL이고 출력 매개변수가 생성되면 begin() 은 KM_ERROR_OUTPUT_PARAMETER_NULL을 반환합니다.
[out]	output	출력 데이터(있는 경우) 호출자는 할당된 버퍼의 소유권을 가정합니다. 출력은 NULL이 아니어야 합니다.

update() 는 출력을 제공하지 않을 수 있습니다. 이 경우 output->data_length는 0이 되고 output->data는 NULL이거나 길이가 0일 수 있습니다 (따라서 호출자는 항상 free()해야 함).

keymaster2.h 파일의 376 줄에 정의되어 있습니다.

이전 키를 업그레이드합니다. 키가 '오래된' 상태가 되는 방법에는 두 가지가 있습니다. Keymaster를 새 버전으로 업그레이드하거나 시스템을 업데이트하여 OS 버전 또는 패치 수준을 무효화할 수 있습니다. 두 경우 모두 이전 키를 사용하려고 하면 키 마스터가 KM_ERROR_KEY_REQUIRES_UPGRADE를 반환합니다. 그런 다음 이 메서드를 호출하여 키를 업그레이드해야 합니다.

매개변수

[in]	dev	Keymaster 기기 구조입니다.
[in]	key_to_upgrade	업그레이드할 Keymaster 키입니다.
[in]	upgrade_params	업그레이드를 완료하는 데 필요한 매개변수입니다. 특히 KM_TAG_APPLICATION_ID 및 KM_TAG_APPLICATION_DATA가 키에 정의된 경우 필요합니다.
[out]	upgraded_key	업그레이드된 키 blob입니다.

keymaster2.h 파일의 260 번 행에 정의되어 있습니다.