Keymaster 함수

이 페이지에서는 Keymaster HAL(하드웨어 추상화 계층)의 구현자에게 도움이 되는 세부정보를 제공합니다. API의 각 함수와 함수를 사용할 수 있는 Keymaster 버전에 관한 내용뿐 아니라 기본 구현에 관해 설명합니다. 태그는 Keymaster 태그 페이지를 참조하세요.

참고: 이전 스타일인 C-구조 HAL에서 새 HIDL(하드웨어 인터페이스 정의 언어)의 정의에서 생성된 C++ HAL 인터페이스로의 Keymaster 3 전환을 지원하기 위해 Android 8.0에서는 함수 이름이 변경되었습니다. 이를 지원하기 위해 함수는 이제 카멜 표기법을 사용합니다. 예를 들어, get_key_characteristics는 이제 getKeyCharacteristics입니다.

일반 구현 가이드라인

다음 가이드라인은 API의 모든 함수에 적용됩니다.

입력 포인터 매개변수

버전: 1, 2

지정된 호출에 사용되지 않는 입력 포인터 매개변수는 NULL일 수 있습니다. 호출자는 자리표시자를 제공할 필요가 없습니다. 예를 들어, 일부 키 유형과 모드는 begin의 inParams 인수 값을 사용하지 않을 수 있으므로 호출자는 inParams를 NULL로 설정하거나 빈 매개변수 집합을 제공합니다. 호출자는 사용하지 않는 매개변수를 제공할 수도 있으며 Keymaster 메서드에서 오류가 발생해서는 안 됩니다.

필수 입력 매개변수가 NULL이면 Keymaster 메서드는 ErrorCode::UNEXPECTED_NULL_POINTER를 반환합니다.

Keymaster 3부터는 포인터 매개변수가 없습니다. 모든 매개변수는 값 또는 const 참조로 전달됩니다.

출력 포인터 매개변수

버전: 1, 2

입력 포인터 매개변수와 마찬가지로 사용되지 않는 출력 포인터 매개변수는 NULL일 수 있습니다. 메서드가 출력 매개변수에 데이터를 반환해야 하는데 그 값이 NULL이라면 메서드는 ErrorCode::OUTPUT_PARAMETER_NULL을 반환해야 합니다.

Keymaster 3부터는 포인터 매개변수가 없습니다. 모든 매개변수는 값 또는 const 참조로 전달됩니다.

API 오용

버전: 1, 2, 3

호출자가 부적절하거나 비합리적이지만 기술적으로 틀리지 않는 요청을 하는 방법에는 여러 가지가 있습니다. Keymaster 구현은 이러한 경우에 실패할 필요가 없으며 진단을 실행합니다. 너무 작은 키 사용, 무관한 입력 매개변수의 지정, IV 또는 nonce의 재사용, 목적이 없어 불필요한 키의 생성 등을 구현에서 진단해서는 안 됩니다. 필수 매개변수의 누락, 잘못된 필수 매개변수의 지정 및 유사한 오류는 진단되어야 합니다.

앱, 프레임워크, Android 키 저장소에는 Keymaster 모듈 호출이 합리적이고 유용한지 확인할 책임이 있습니다.

함수

getHardwareFeatures

버전: 3

새 getHardwareFeatures 메서드는 클라이언트에게 기본 보안 하드웨어의 일부 중요한 특성을 노출합니다. 이 메서드는 인수를 사용하지 않고 다음 네 개의 부울 값을 반환합니다.

키가 보안 하드웨어(TEE 등)에 저장되고 그 하드웨어에서 나가지 않으면 isSecure는 true입니다.
하드웨어가 NIST 곡선(P-224, P-256, P-384 및 P-521)으로 타원 곡선 암호를 지원하면 supportsEllipticCurve는 true입니다.
하드웨어가 AES 및 HMAC와 같은 대칭형 암호화를 지원한다면 supportsSymmetricCryptography는 true입니다.
하드웨어가 보안 환경에 삽입된 키로 서명된 Keymaster 공개 키 증명 인증서를 생성하도록 지원하면 supportsAttestation은 true입니다.

이 메서드에서 반환할 수 있는 오류 코드는 ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED 또는 보안 하드웨어와 통신하는 데 실패한 것을 나타내는 오류 코드 중 하나뿐입니다.

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

구성

버전: 2

이 함수는 Keymaster 2에서 도입되었고 Keymaster 3에서 지원이 중단되었으며 그 이유는 시스템 속성 파일에서 이 정보를 사용할 수 있고 시작하는 동안 제조업체 구현에서 이 파일을 읽기 때문입니다.

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

Keymaster 구현이 보안 하드웨어에 있고 제공된 OS 버전과 패치 레벨 값이 부트로더에서 보안 하드웨어에 제공한 값과 일치하지 않으면(또는 부트로더가 값을 제공하지 않았다면) 이 메서드는 KM_ERROR_INVALID_ARGUMENT를 반환하고 다른 모든 메서드는 계속 KM_ERROR_KEYMASTER_NOT_CONFIGURED를 반환합니다.

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

addRngEntropy

버전: 1, 2, 3

이 함수는 Keymaster 1에서 add_rng_entropy로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

Keymaster 1 구현에서 키와 IV 등의 랜덤 숫자를 생성하는 데 사용한 풀에 호출자 제공 엔트로피를 추가합니다.

Keymaster 구현은 하드웨어 랜덤 숫자 생성기에서 내부적으로 생성된 엔트로피도 포함해야 하는 풀에 제공된 엔트로피를 안전하게 혼합해야 합니다. 혼합은 addRngEntropy 제공 비트 또는 하드웨어에서 생성한 비트 중 하나(둘 다는 아님)를 완전히 제어하는 공격자가 엔트로피 풀에서 생성된 비트를 예측할 때 상당한 이점이 없도록 처리되어야 합니다.

내부 풀의 엔트로피를 추정하도록 시도하는 Keymaster 구현은 addRngEntropy에서 제공하는 데이터에 엔트로피가 포함되지 않는다고 가정합니다. 단일 호출로 2KiB를 초과하는 데이터가 제공된다면 Keymaster 구현은 ErrorCode::INVALID_INPUT_LENGTH를 반환할 수 있습니다.

generateKey

버전: 1, 2, 3

이 함수는 Keymaster 1에서 generate_key로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

키에 영구적으로 결합한 연결된 승인을 지정하는 새 암호화 키를 생성합니다. Keymaster 구현에서는 생성 시 지정된 승인과 일치하지 않는 키는 어떤 방식으로든 사용할 수 없습니다. 보안 하드웨어에서 시행할 수 없는 승인과 관련하여 보안 하드웨어의 의무는 getKeyCharacteristics의 모든 호출에서 원래 값을 반환하도록 키와 연결된 유효하지 않은 승인이 수정되지 않게 하는 것으로 제한됩니다. 또한, generateKey에서 반환되는 특성은 하드웨어 시행 목록과 소프트웨어 시행 목록 간에 승인을 정확하게 할당합니다. 자세한 내용은 getKeyCharacteristics를 참조하세요.

generateKey에 제공된 매개변수는 생성되는 키의 유형에 따라 다릅니다. 이 섹션에서는 각 키 유형의 필수 태그 및 선택 태그에 관해 요약합니다. Tag::ALGORITHM은 유형을 지정하는 데 항상 필요합니다.

RSA 키

다음 매개변수는 RSA 키를 생성하는 데 필요합니다.

Tag::KEY_SIZE는 공개 모듈러스의 크기를 비트 단위로 지정합니다. 이 태그를 생략하면 메서드는 ErrorCode::UNSUPPORTED_KEY_SIZE를 반환합니다. 지원되는 값은 1024, 2048, 3072 및 4096입니다. 권장 값은 8의 배수인 모든 키 크기입니다.
Tag::RSA_PUBLIC_EXPONENT는 RSA 공개 지수 값을 지정합니다. 이 태그를 생략하면 메서드는 ErrorCode::INVALID_ARGUMENT를 반환합니다. 지원되는 값은 3 및 65537입니다. 권장 값은 2^64까지의 모든 소수 값입니다.

RSA 키를 생성하는 데 다음 매개변수가 필수는 아니지만, 매개변수가 없이 RSA 키를 만들면 사용할 수 없는 키가 생성됩니다. 하지만 이러한 매개변수를 생략해도 generateKey 함수는 오류를 반환하지 않습니다.

Tag::PURPOSE는 허용되는 목적을 지정합니다. 모든 목적은 어떤 조합으로든 RSA 키에서 지원되어야 합니다.
Tag::DIGEST는 새 키와 함께 사용할 수 있는 다이제스트 알고리즘을 지정합니다. 모든 다이제스트 알고리즘을 지원하지 않는 구현은 지원되지 않는 다이제스트를 포함하는 키 생성 요청을 수락해야 합니다. 지원되지 않는 다이제스트는 반환된 키 특성의 '소프트웨어 시행' 목록에 배치해야 합니다. 키는 다른 다이제스트와 함께 사용할 수 있지만, 다이제스트는 소프트웨어에서 실행되기 때문입니다. 그런 다음 Digest::NONE으로 작업을 실행하기 위해 하드웨어가 호출됩니다.
Tag::PADDING은 새 키와 함께 사용할 수 있는 패딩 모드를 지정합니다. 지원되지 않는 다이제스트 알고리즘이 지정되어 있다면 모든 다이제스트 알고리즘을 지원하지 않는 구현은 키 특성의 소프트웨어 시행 목록에 PaddingMode::RSA_PSS와 PaddingMode::RSA_OAEP를 배치해야 합니다.

ECDSA 키

ECDSA 키를 생성하기 위해서는 Tag::KEY_SIZE만 있으면 됩니다. 이 태그는 EC 그룹을 선택하는 데 사용됩니다. 지원되는 값은 224, 256, 384 및 521이며 각각 NIST p-224, p-256, p-384 및 p521 곡선을 나타냅니다.

Tag::DIGEST도 유용한 ECDSA 키에 필요하지만 생성하는 데 필요한 것은 아닙니다.

AES 키

AES 키를 생성하기 위해서는 Tag::KEY_SIZE만 있으면 됩니다. 이 태그를 생략하면 메서드는 ErrorCode::UNSUPPORTED_KEY_SIZE를 반환합니다. 지원되는 값은 128 및 256이며 192비트 AES 키는 선택적으로 지원됩니다.

다음 매개변수는 AES 키와 특별히 관련이 있지만, AES 키를 생성하는 데 필요한 것은 아닙니다.

Tag::BLOCK_MODE는 새 키와 함께 사용될 수 있는 차단 모드를 지정합니다.
Tag::PADDING은 사용될 수 있는 패딩 모드를 지정합니다. 이는 ECB 및 CBC 모드에만 관련이 있습니다.

GCM 차단 모드가 지정되어 있다면 Tag::MIN_MAC_LENGTH를 제공합니다. 이 태그를 생략하면 메서드는 ErrorCode::MISSING_MIN_MAC_LENGTH를 반환합니다. 태그의 값은 96과 128 사이의 8의 배수입니다.

HMAC 키

다음 매개변수는 HMAC 키 생성에 필요합니다.

Tag::KEY_SIZE는 키 크기를 비트 단위로 지정합니다. 64 미만의 값과 8의 배수가 아닌 값은 지원되지 않습니다. 64에서 512까지의 모든 8의 배수가 지원됩니다. 더 큰 값이 지원될 수도 있습니다.
Tag::MIN_MAC_LENGTH는 이 키로 생성하거나 인증할 수 있는 MAC의 최소 길이를 지정합니다. 값은 8의 배수이며 최소 64 이상입니다.
Tag::DIGEST는 키의 다이제스트 알고리즘을 지정합니다. 정확히 하나의 다이제스트가 지정되며, 그렇지 않으면 ErrorCode::UNSUPPORTED_DIGEST를 반환합니다. Trustlet에서 다이제스트를 지원하지 않으면 ErrorCode::UNSUPPORTED_DIGEST를 반환합니다.

키 특성

특성 인수가 NULL이 아니면 generateKey는 하드웨어 시행 목록과 소프트웨어 시행 목록으로 적절하게 분할하여 생성된 새 키 특성을 반환합니다. 특성이 포함되는 목록에 관한 설명은 getKeyCharacteristics를 참조하세요. 반환되는 특성에는 키 생성에 지정된 모든 매개변수(Tag::APPLICATION_ID와 Tag::APPLICATION_DATA 제외)가 포함됩니다. 이러한 태그가 키 매개변수에 포함되었다면 반환된 키 blob을 검사하여 태그 값을 찾을 수 없도록 태그는 반환된 특성에서 삭제됩니다. 그러나 태그는 키 blob에 암호화 방식으로 결합하므로 키가 사용될 때 올바른 값이 제공되지 않으면 사용에 실패합니다. 마찬가지로 Tag::ROOT_OF_TRUST는 키에 암호화 방식으로 결합되어 있지만, 키를 생성하거나 가져오는 동안 지정될 수 없으며 반환되지 않습니다.

제공된 태그 외에도 trustlet은 KeyOrigin::GENERATED 값을 가진 Tag::ORIGIN도 추가하며 키의 롤백이 방지되면

Tag::ROLLBACK_RESISTANT를 추가합니다.

롤백 방지

롤백 방지는 deleteKey 또는 deleteAllKeys로 키가 한 번 삭제되면 보안 하드웨어에서 다시 사용되지 않도록 보장된다는 의미입니다. 롤백 방지가 없는 구현은 일반적으로 생성하거나 가져온 키 자료를 호출자에게 키 blob 및 암호화된 인증 양식으로 반환합니다. 키 저장소가 키 blob을 삭제하면 키는 없어지지만, 이전에 키 자료를 검색한 적이 있는 공격자가 잠재적으로 키 blob을 기기에 복원할 수 있습니다.

보안 하드웨어에서 삭제된 키를 나중에 복원되지 않도록 보장하면 키의 롤백이 방지됩니다. 이는 일반적으로 신뢰할 수 있는 위치에 추가 키 메타데이터를 저장하여 실행됩니다. 이 위치는 공격자가 조작할 수 없습니다. 휴대기기에서는 일반적으로 롤백 방지에 RPMB(Replay Protected Memory Blocks) 메커니즘을 사용합니다. 생성될 수 있는 키의 수는 기본적으로 무제한이며 롤백 방지에 사용되는 신뢰할 수 있는 저장소의 크기는 제한될 수 있기 때문에 새 키의 롤백을 방지할 수 없는 경우에도 이 메서드는 성공해야 합니다. 이 경우 Tag::ROLLBACK_RESISTANT가 키 특성에 추가되어서는 안 됩니다.

getKeyCharacteristics

버전: 1, 2, 3

이 함수는 Keymaster 1에서 get_key_characteristics로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

이 함수는 제공된 키와 연결된 매개변수 및 승인을 하드웨어 시행 및 소프트웨어 시행의 두 세트로 나누어 반환합니다. 여기의 설명은 generateKey 및 importKey에 의해 반환되는 키 특성 목록에 동일하게 적용됩니다.

키를 생성하거나 가져오는 동안 Tag::APPLICATION_ID가 제공되었다면 동일한 값이 이 메서드의 clientId 인수에 제공됩니다. 그렇지 않으면 메서드는 ErrorCode::INVALID_KEY_BLOB를 반환합니다. 마찬가지로 키를 생성하거나 가져오는 동안 Tag::APPLICATION_DATA가 제공되었다면 동일한 값이 이 메서드의 appData 인수에 제공됩니다.

이 메서드가 반환하는 특성은 지정된 키의 유형과 사용법을 완벽하게 설명합니다.

지정된 태그가 하드웨어 시행 목록과 소프트웨어 시행 목록 중 어디에 속할지 결정하는 일반적인 규칙은 태그의 의미를 보아 보안 하드웨어에서 완전히 보장되면 그 태그는 하드웨어 시행에 속하는 것입니다. 그렇지 않으면 소프트웨어 시행에 속하게 됩니다. 다음은 적용 기준이 명확하지 않을 수 있는 특정 태그의 목록입니다.

Tag::ALGORITHM, Tag::KEY_SIZE 및 Tag::RSA_PUBLIC_EXPONENT는 키의 고유한 속성입니다. 하드웨어에서 보호하는 키의 경우 이러한 태그는 하드웨어 시행 목록에 포함됩니다.
보안 하드웨어에서 지원하는 Tag::DIGEST 값은 하드웨어 지원 목록에 배치됩니다. 지원되지 않는 다이제스트는 소프트웨어 지원 목록에 포함됩니다.
Tag::PADDING 값은 소프트웨어에서 특정 패딩 모드를 실행해야 할 가능성이 없다면 일반적으로 하드웨어 지원 목록에 포함됩니다. 그렇지 않은 경우 소프트웨어 시행 목록에 포함됩니다. 이런 가능성은 보안 하드웨어에서 지원하지 않는 다이제스트 알고리즘으로 PSS 또는 OAEP 패딩을 허용하는 RSA 키에서 발생합니다.
Tag::USER_SECURE_ID 및 Tag::USER_AUTH_TYPE은 사용자 인증이 하드웨어에서 시행되는 경우에만 하드웨어 시행 목록에 포함됩니다. 이를 실행하기 위해 Keymaster trustlet과 관련 인증 trustlet은 모두 안전해야 하며 서명하고 인증 토큰의 유효성을 검사하는 데 사용되는 비밀 HMAC 키를 공유해야 합니다. 자세한 내용은 인증 페이지를 참조하세요.
Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME 및 Tag::USAGE_EXPIRE_DATETIME 태그는 확인 가능한 정확한 실제 시간에 액세스해야 합니다. 대부분의 보안 하드웨어는 비보안 OS에서 제공하는 시간 정보에만 액세스할 수 있으므로 이러한 태그는 소프트웨어에서 실행됩니다.
Tag::ORIGIN은 하드웨어에 결합한 키의 경우 항상 하드웨어 목록에 있습니다. 이 목록에 있는 것이 상위 계층에서 하드웨어가 지원하는 키라고 판단하는 방식입니다.

importKey

버전: 1, 2, 3

이 함수는 Keymaster 1에서 import_key로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

이 함수는 Keymaster 하드웨어로 키 자료를 가져옵니다. 키 정의 매개변수 및 출력 특성은 generateKey와 같은 방식으로 처리되며 다음과 같은 예외가 있습니다.

Tag::KEY_SIZE와 Tag::RSA_PUBLIC_EXPONENT(RSA 키만 해당)는 입력 매개변수에 필수는 아닙니다. 태그가 제공되지 않으면, trustlet은 제공된 키 자료에서 값을 추론하고 적절한 태그와 값을 키 특성에 추가합니다. 매개변수가 제공되면 trustlet은 키 자료에 맞는지 매개변수의 유효성을 검사합니다. 일치하지 않는 경우 메서드는 ErrorCode::IMPORT_PARAMETER_MISMATCH를 반환합니다.
반환된 Tag::ORIGIN은 KeyOrigin::IMPORTED와 같은 값을 가집니다.

exportKey

버전: 1, 2, 3

이 함수는 Keymaster 1에서 export_key로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

이 함수는 Keymaster RSA 또는 EC 키 쌍에서 공개 키를 내보냅니다.

deleteKey

버전: 1, 2, 3

이 함수는 Keymaster 1에서 delete_key로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

이 함수는 제공된 키를 삭제합니다. 이 메서드는 선택사항이며 롤백을 방지하는 Keymaster 모듈에서만 구현됩니다.

deleteAllKeys

버전: 1, 2, 3

이 함수는 Keymaster 1에서 delete_all_keys로 도입되었으며 Keymaster 3에서 이름이 변경되었습니다.

이 함수는 모든 키를 삭제합니다. 이 메서드는 선택사항이며 롤백을 방지하는 Keymaster 모듈에서만 구현됩니다.

destroyAttestationIds

버전: 3

destroyAttestationIds() 메서드는 새 ID 증명(선택사항이지만 사용하는 것이 좋음) 기능을 영구적으로 중지하는 데 사용됩니다. 이 메서드가 호출된 후에 TEE에서 ID 증명이 영구적으로 중지된 것을 확인할 수 없다면 ID 증명은 전혀 구현되지 않은 것이며 이런 경우 이 메서드는 아무 작업도 하지 않고 ErrorCode::UNIMPLEMENTED를 반환합니다. ID 증명이 지원된다면 이 메서드를 구현해야 하며 향후 발생하는 모든 ID 증명 시도를 영구적으로 중지해야 합니다. 메서드는 여러 번 호출될 수 있습니다. ID 증명이 이미 영구적으로 중지되어 있으면 메서드는 아무 작업도 실행하지 않고 ErrorCode::OK를 반환합니다.

이 메서드에서 반환할 수 있는 오류 코드는 ErrorCode::UNIMPLEMENTED(ID 증명을 지원하지 않는 경우), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED 또는 보안 하드웨어와의 통신에 실패한 것을 나타내는 오류 코드 중 하나밖에 없습니다.

begin

버전: 1, 2, 3

이 함수는 지정된 키를 사용하여 명시된 목적을 위해 적절하게 지정된 매개변수를 가지고 암호와 작업을 시작하고 update 및 finish와 함께 사용되는 작업 핸들을 반환하여 작업을 완료합니다. 작업 핸들은 인증된 작업의 'challenge' 토큰으로도 사용되며 이러한 작업의 경우 인증 토큰의 challenge 필드에서 작업 핸들을 포함합니다.

Keymaster 구현은 최소 16개의 동시 작업을 지원합니다. 키 저장소는 최대 15개까지 사용하며 vold가 비밀번호 암호화에 하나를 사용합니다. 키 저장소에 15개의 작업이 진행 중(begin은 호출되었지만, finish 또는 abort가 아직 호출되지 않은 상태)이고 16번째 작업을 시작하라는 요청을 수신했다면 begin을 호출하여 새로 요청받은 작업을 시작하기 전에 가장 오래전에 사용된 작업에 abort를 호출하여 활성 작업 수를 14로 줄입니다.

키를 생성하거나 가져오는 동안 Tag::APPLICATION_ID 또는 Tag::APPLICATION_DATA가 지정되었다면 begin의 호출은 이 메서드의 inParams 인수에 원래 지정된 값을 가진 태그를 포함합니다.

승인 시행

이 메서드 실행 시 구현이 '하드웨어 시행' 특성에 키 인증을 배치했고 작업이 공개 키 연산이 아니면 trustlet에서 다음의 키 인증을 시행합니다. RSA 또는 EC 키를 사용한 공개 키 연산(KeyPurpose::ENCRYPT와 KeyPurpose::VERIFY를 의미)은 승인 요구사항이 충족되지 않아도 성공할 수 있습니다.

Tag::PURPOSE: 요청된 작업이 공개 키 연산이 아니라면 begin() 호출에 지정된 목적은 키 승인의 목적 중 하나와 일치해야 합니다. 지정된 목적이 일치하지 않고 작업이 공개 키 연산이 아니면 begin은 ErrorCode::UNSUPPORTED_PURPOSE를 반환합니다. 공개 키 연산은 비대칭 암호화 또는 인증 작업입니다.
Tag::ACTIVE_DATETIME은 신뢰할 수 있는 UTC 시간 소스를 사용할 수 있는 경우에만 시행될 수 있습니다. 현재 날짜 및 시간이 태그 값보다 이전이면 메서드는 ErrorCode::KEY_NOT_YET_VALID를 반환합니다.
Tag::ORIGINATION_EXPIRE_DATETIME은 신뢰할 수 있는 UTC 시간 소스를 사용할 수 있는 경우에만 시행될 수 있습니다. 현재 날짜 및 시간이 태그 값보다 이후이고 목적이 KeyPurpose::ENCRYPT 또는 KeyPurpose::SIGN이면 메서드는 ErrorCode::KEY_EXPIRED를 반환합니다.
Tag::USAGE_EXPIRE_DATETIME은 신뢰할 수 있는 UTC 시간 소스를 사용할 수 있는 경우에만 시행될 수 있습니다. 현재 날짜 및 시간이 태그 값보다 이후이고 목적이 KeyPurpose::DECRYPT 또는 KeyPurpose::VERIFY이면 메서드는 ErrorCode::KEY_EXPIRED를 반환합니다.
Tag::MIN_SECONDS_BETWEEN_OPS는 키의 마지막 사용을 나타내는 신뢰할 수 있는 상대 타이머와 비교됩니다. 마지막 사용 시간과 태그 값을 더한 값이 현재 시간보다 작으면 메서드는 ErrorCode::KEY_RATE_LIMIT_EXCEEDED를 반환합니다. 중요한 구현 세부정보는 태그 설명을 참고하세요.
Tag::MAX_USES_PER_BOOT는 부팅 시간 이후의 키 사용을 추적하는 보안 카운터와 비교됩니다. 이전 사용 횟수가 태그 값을 초과하면 메서드는 ErrorCode::KEY_MAX_OPS_EXCEEDED를 반환합니다.
Tag::USER_SECURE_ID는 키에 Tag::AUTH_TIMEOUT도 있는 경우에만 이 메서드에 의해 시행됩니다. 키에 양쪽 모두가 있다면 이 메서드는 inParams에 유효한 Tag::AUTH_TOKEN을 수신해야 합니다. 인증 토큰이 유효하려면 다음 조건이 모두 충족되어야 합니다.
- HMAC 필드가 정확하게 유효성 검사를 실행합니다.
- 키의 Tag::USER_SECURE_ID 값 중 하나 이상은 토큰의 보안 ID 값 중 하나 이상과 일치합니다.
- 키에 토큰의 인증 유형과 일치하는 Tag::USER_AUTH_TYPE이 있습니다.
이러한 조건 중 하나라도 충족되지 않으면 메서드는 ErrorCode::KEY_USER_NOT_AUTHENTICATED를 반환합니다.
Tag::CALLER_NONCE는 호출자가 nonce 또는 초기화 벡터(IV)를 지정하도록 허용합니다. 키에 이 태그가 없지만, 호출자가 이 메서드에 Tag::NONCE를 제공했다면 ErrorCode::CALLER_NONCE_PROHIBITED가 반환됩니다.
Tag::BOOTLOADER_ONLY는 부트로더만 키를 사용할 수 있도록 지정합니다. 부트로더가 실행을 종료한 후에 부트로더 전용 키로 이 메서드를 호출하면 메서드는 ErrorCode::INVALID_KEY_BLOB을 반환합니다.

RSA 키

모든 RSA 키 연산은 inParams에 정확히 하나의 패딩 모드를 지정합니다. 다이제스트가 지정되지 않거나 두 번 이상 지정되면 메서드는 ErrorCode::UNSUPPORTED_PADDING_MODE를 반환합니다.

RSA 서명 및 인증 작업에는 OAEP 패딩 모드로 RSA 암호화 및 복호화 작업을 하는 것과 마찬가지로 다이제스트가 필요합니다. 이러한 경우 호출자는 inParams에 정확히 하나의 다이제스트를 지정합니다. 다이제스트가 지정되지 않거나 두 번 이상 지정되면 메서드는 ErrorCode::UNSUPPORTED_DIGEST를 반환합니다.

비공개 키 연산(KeyPurpose::DECYPT 및 KeyPurpose::SIGN)은 다이제스트와 패딩의 승인이 필요하며 이는 키 승인에 지정된 값이 포함되어야 한다는 것을 의미합니다. 그렇지 않은 경우 메서드는 ErrorCode::INCOMPATIBLE_DIGEST 또는 ErrorCode::INCOMPATIBLE_PADDING을 적절하게 반환합니다. 공개 키 연산(KeyPurpose::ENCRYPT 및 KeyPurpose::VERIFY)은 승인되지 않은 다이제스트 또는 패딩으로 가능합니다.

PaddingMode::NONE을 제외하고 모든 RSA 패딩 모드는 특정 목적에만 적용할 수 있습니다. 구체적으로 PaddingMode::RSA_PKCS1_1_5_SIGN과 PaddingMode::RSA_PSS는 서명과 인증만 지원하는 반면 PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT와 PaddingMode::RSA_OAEP는 암호화와 복호화만 지원합니다. 지정된 모드가 특정 목적을 지원하지 않는다면 이 메서드는 ErrorCode::UNSUPPORTED_PADDING_MODE를 반환합니다.

패딩 모드와 다이제스트 간에는 다음과 같은 중요한 상호작용이 있습니다.

PaddingMode::NONE은 '원시' RSA 작업이 실행된 것을 나타냅니다. 서명 또는 인증 작업이라면 다이제스트에 Digest::NONE이 지정됩니다. 패딩되지 않은 암호화 또는 복호화에 다이제스트는 필요하지 않습니다.
PaddingMode::RSA_PKCS1_1_5_SIGN 패딩에는 다이제스트가 필요합니다. DigestInfo 구조를 추가할 수 없어서 Keymaster 구현이 적절한 PKCS#1 v1.5 서명 구조를 빌드할 수 없는 경우 다이제스트는 Digest::NONE이 될 수 있습니다. 대신 구현은 0x00 || 0x01 || PS || 0x00 || M을 구성하며 여기에서 M은 제공된 메시지이고 PS는 패딩 문자열입니다. RSA 키의 크기는 메시지보다 최소 11바이트가 커야 하며 그렇지 않으면 메서드에서 ErrorCode::INVALID_INPUT_LENGTH를 반환합니다.
PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT 패딩에는 다이제스트가 필요하지 않습니다.
PaddingMode::RSA_PSS 패딩에는 다이제스트가 필요하며 다이제스트는 Digest::NONE이어서는 안됩니다. Digest::NONE이 지정되면 메서드는 ErrorCode::INCOMPATIBLE_DIGEST를 반환합니다. 또한 RSA 키의 크기는 다이제스트의 출력 크기보다 2 + D 바이트 이상 커야 하며, 여기서 D는 바이트 단위의 다이제스트의 크기입니다. 그렇지 않으면 메서드는 ErrorCode::INCOMPATIBLE_DIGEST를 반환합니다. 솔트의 크기는 D입니다.
PaddingMode::RSA_OAEP 패딩에는 다이제스트가 필요하며 다이제스트는 Digest::NONE이어서는 안됩니다. Digest::NONE이 지정되면 메서드는 ErrorCode::INCOMPATIBLE_DIGEST를 반환합니다.

EC 키

EC 키 연산은 inParams에 정확히 하나의 패딩 모드를 지정합니다. 다이제스트가 지정되지 않거나 두 번 이상 지정되면 메서드는 ErrorCode::UNSUPPORTED_PADDING_MODE를 반환합니다.

비공개 키 연산(KeyPurpose::SIGN)은 다이제스트 및 패딩 승인이 필요합니다. 즉, 키 승인에 지정된 값이 포함되어야 합니다. 적합하지 않으면 ErrorCode::INCOMPATIBLE_DIGEST를 반환합니다. 공개 키 연산(KeyPurpose::VERIFY)은 승인되지 않은 다이제스트 또는 패딩으로 가능합니다.

AES 키

AES 키 연산은 inParams에 정확히 하나의 블록 모드와 하나의 패딩 모드를 지정합니다. 값이 지정되지 않았거나 두 번 이상 지정되면 ErrorCode::UNSUPPORTED_BLOCK_MODE 또는 ErrorCode::UNSUPPORTED_PADDING_MODE를 반환합니다. 지정된 모드는 키로 승인되어야 하며, 그렇지 않으면 메서드는 ErrorCode::INCOMPATIBLE_BLOCK_MODE 또는 ErrorCode::INCOMPATIBLE_PADDING_MODE를 반환합니다.

차단 모드가 BlockMode::GCM이면 inParams는 Tag::MAC_LENGTH를 지정하고 지정된 값은 128보다 크지 않은 8의 배수이거나 키 승인의 Tag::MIN_MAC_LENGTH 값보다 작습니다. MAC 길이가 128보다 크거나 8의 배수가 아닌 경우 ErrorCode::UNSUPPORTED_MAC_LENGTH를 반환합니다. 값이 키의 최소 길이보다 작은 경우 ErrorCode::INVALID_MAC_LENGTH를 반환합니다.

차단 모드가 BlockMode::GCM 또는 BlockMode::CTR이면 지정된 패딩 모드는 PaddingMode::NONE이어야 합니다. BlockMode::ECB 또는 BlockMode::CBC의 경우 모드는 PaddingMode::NONE 또는 PaddingMode::PKCS7이 될 수 있습니다. 패딩 모드가 이러한 조건을 충족하지 않으면 ErrorCode::INCOMPATIBLE_PADDING_MODE를 반환합니다.

차단 모드가 BlockMode::CBC, BlockMode::CTR 또는 BlockMode::GCM이면 초기화 벡터 또는 nonce가 필요합니다. 대부분의 경우 호출자가 IV 또는 nonce를 제공해서는 안 됩니다. 이 경우 Keymaster 구현은 임의의 IV나 nonce를 생성하고 outParams에 Tag::NONCE를 통해 반환합니다. CBC 및 CTR IV는 16바이트입니다. GCM nonce는 12바이트입니다. 키 승인에 Tag::CALLER_NONCE가 포함된다면 호출자는 Tag::NONCE를 사용하여 IV/nonce를 inParams에 제공할 수 있습니다. Tag::CALLER_NONCE가 승인되지 않은 상태에서 nonce가 제공되면 ErrorCode::CALLER_NONCE_PROHIBITED를 반환합니다. Tag::CALLER_NONCE가 승인된 상태에서 nonce가 제공되지 않으면 임의의 IV/nonce를 생성합니다.

HMAC 키

HMAC 키 연산은 inParams에 Tag::MAC_LENGTH를 지정합니다. 지정된 값은 다이제스트 길이보다 크지 않거나 키 인증의 Tag::MIN_MAC_LENGTH 값보다 작은 8의 배수여야 합니다. MAC 길이가 다이제스트 길이보다 크거나 8의 배수가 아닌 경우 ErrorCode::UNSUPPORTED_MAC_LENGTH를 반환합니다. 값이 키의 최소 길이보다 작은 경우 ErrorCode::INVALID_MAC_LENGTH를 반환합니다.

업데이트

버전: 1, 2, 3

begin으로 시작하는 진행 중인 작업에서 처리할 데이터를 제공합니다. 작업은 operationHandle 매개변수로 지정됩니다.

버퍼의 처리를 보다 유연하게 하기 위해 이 메서드의 구현에는 제공된 데이터보다 적은 데이터를 소비하는 옵션이 있습니다. 호출자는 후속 호출에서 나머지 데이터를 피드하는 루프를 담당합니다. 소비된 입력 양은 inputConsumed 매개변수에 반환됩니다. 작업이 더 이상 수락할 수 없는 것이 아니라면 구현은 항상 최소 1바이트를 소비하며 1바이트 이상 제공되고 0바이트가 소비되면 호출자는 이를 오류로 보고 작업을 취소합니다.

구현은 업데이트의 결과에 따라 반환할 데이터양도 선택할 수 있습니다. 서명 및 확인 작업은 finish까지 데이터를 반환하지 않으므로 이는 암호화 및 복호화 작업에만 관련이 있습니다. 데이터를 버퍼링하는 대신 가능한 한 빨리 반환합니다.

오류 처리

이 메서드가 ErrorCode::OK 외의 오류 코드를 반환하면 작업이 취소되고 작업 핸들이 무효화됩니다. 향후 finish 또는 abort 메서드에서 핸들을 사용하면 ErrorCode::INVALID_OPERATION_HANDLE을 반환합니다.

승인 시행

키 승인 시행은 주로 begin에서 실행됩니다. 한 가지 예외는 키가 다음과 같은 경우입니다.

키에 하나 이상의 Tag::USER_SECURE_ID가 있음
키에 Tag::AUTH_TIMEOUT이 없음

이 경우 키는 작업당 승인이 필요하며 update 메서드는 inParams 인수에 Tag::AUTH_TOKEN을 수신합니다. HMAC는 토큰이 유효하고 일치하는 보안 사용자 ID를 포함하며 키의 Tag::USER_AUTH_TYPE과 일치하고 challenge 필드에 현재 작업의 작업 핸들을 포함하는지 확인합니다. 이러한 조건이 충족되지 않으면 ErrorCode::KEY_USER_NOT_AUTHENTICATED를 반환합니다.

호출자는 update 및 finish의 모든 호출에 인증 토큰을 제공합니다. 원한다면 구현은 토큰의 유효성을 한 번만 검사해야 합니다.

RSA 키

Digest::NONE으로 서명 및 인증 작업을 하는 경우 이 메서드는 단일 업데이트에서 서명되거나 인증되는 전체 블록을 허용합니다. 블록 일부만을 소비할 수는 없습니다. 그러나 호출자가 여러 업데이트에서 데이터를 제공하기로 선택하면 이 메서드는 블록의 일부를 허용합니다. 호출자가 사용할 수 있는 것보다 더 많은 데이터(RSA 키 크기를 초과하는 데이터 길이)를 서명에 제공하면 ErrorCode::INVALID_INPUT_LENGTH를 반환합니다.

ECDSA 키

Digest::NONE으로 서명 및 인증 작업을 하는 경우 이 메서드는 단일 업데이트에서 서명되거나 인증되는 전체 블록을 허용합니다. 이 메서드는 블록 일부만 소비할 수는 없습니다.

그러나 호출자가 여러 업데이트에서 데이터를 제공하기로 선택하면 이 메서드는 블록의 일부를 허용합니다. 호출자가 사용할 수 있는 것보다 더 많은 데이터를 서명에 제공하면 데이터는 자동으로 잘립니다. (이는 유사한 RSA 작업에서 제공되는 초과 데이터 처리와는 다릅니다. 이렇게 하는 이유는 기존 클라이언트와의 호환성 때문입니다.)

AES 키

AES GCM 모드는 inParams 인수의 Tag::ASSOCIATED_DATA를 통해 제공되는 '연결된 인증 데이터'를 지원합니다. 연결된 데이터는 반복 호출에 제공될 수 있지만(데이터가 너무 커서 단일 블록에서 전송할 수 없는 경우 중요함), 항상 암호화되거나 복호화되는 데이터 앞에 옵니다. 업데이트 호출은 연결된 데이터와 암호화 및 복호화할 데이터를 모두 수신할 수 있지만, 후속 업데이트에는 연결된 데이터가 포함되지 않을 수 있습니다. 호출자가 암호화 또는 복호화할 데이터가 포함된 호출 이후 업데이트 호출에 연결된 데이터를 제공하면 ErrorCode::INVALID_TAG를 반환합니다.

GCM 암호화의 경우 태그는 finish의 암호문에 추가됩니다. 복호화 시 마지막 업데이트 호출에 제공된 데이터의 마지막 Tag::MAC_LENGTH 바이트는 태그입니다. update의 특정 호출이 마지막 호출인지 알 수 없기 때문에 호출은 finish 도중에 태그 길이와 가능한 태그 데이터의 버퍼를 제외하고 모두 처리합니다.

finish

버전: 1, 2, 3

begin으로 시작되어 update로 제공된 아직 처리되지 않은 모든 데이터를 처리하는 진행 중인 작업을 완료합니다.

이 메서드는 작업에서 마지막으로 호출되는 메서드이므로 처리된 모든 데이터가 반환됩니다.

작업을 성공적으로 완료하든 오류를 반환하든 이 메서드는 작업을 마무리하고 제공된 작업 핸들을 무효화합니다. 향후 이 메서드나 update 또는 abort에서 핸들을 사용하려고 하면 ErrorCode::INVALID_OPERATION_HANDLE을 반환합니다.

서명 작업은 서명을 출력으로 반환합니다. 인증 작업은 signature 매개변수에 서명을 사용하고 출력을 반환하지 않습니다.

승인 시행

키 승인 시행은 주로 begin에서 실행됩니다. 한 가지 예외는 키가 다음과 같은 경우입니다.

키에 하나 이상의 Tag::USER_SECURE_ID가 있음
키에 Tag::AUTH_TIMEOUT이 없음

호출자는 update 및 finish의 모든 호출에 인증 토큰을 제공합니다. 원한다면 구현은 토큰의 유효성을 한 번만 검사해야 합니다.

RSA 키

패딩 모드에 따른 몇 가지 추가 요구사항은 다음과 같습니다.

PaddingMode::NONE. 패딩되지 않은 서명 및 암호화 작업의 경우 제공된 데이터가 키보다 짧으면 서명 또는 암호화 전에 데이터 왼쪽이 0으로 채워집니다. 데이터가 키와 길이가 같지만 숫자가 더 크면 ErrorCode::INVALID_ARGUMENT를 반환합니다. 인증 및 복호화 작업의 경우 데이터는 키와 길이가 정확히 일치해야 합니다. 그렇지 않으면 ErrorCode::INVALID_INPUT_LENGTH.를 반환합니다.
PaddingMode::RSA_PSS. PSS로 채워진 서명 작업의 경우 PSS 솔트는 메시지 다이제스트의 크기이며 무작위로 생성됩니다. begin의 inputParams에 Tag::DIGEST로 지정된 다이제스트는 PSS 다이제스트 알고리즘과 MGF1 다이제스트 알고리즘으로 사용됩니다.
PaddingMode::RSA_OAEP. begin의 inputParams에 Tag::DIGEST로 지정된 다이제스트는 OAEP 다이제스트 알고리즘으로 사용되고 SHA1은 MGF1 다이제스트 알고리즘으로 사용됩니다.

ECDSA 키

패딩이 적용되지 않은 서명 또는 인증에 제공된 데이터가 너무 길면 잘라냅니다.

AES 키

차단 모드에 따라 다음과 같은 몇 가지 추가 조건이 적용됩니다.

BlockMode::ECB 또는 BlockMode::CBC. 패딩이 PaddingMode::NONE이고 데이터 길이가 AES 블록 크기의 배수가 아니면 ErrorCode::INVALID_INPUT_LENGTH를 반환합니다. 패딩이 PaddingMode::PKCS7이면 PKCS#7 사양에 따라 데이터를 채웁니다. PKCS#7은 데이터가 블록 길이의 배수이면 추가 패딩 블록을 추가하는 것이 좋습니다.
BlockMode::GCM. 암호화 중에 모든 일반 텍스트를 처리한 후 태그(Tag::MAC_LENGTH 바이트)를 계산하여 반환된 암호문에 추가합니다. 복호화 중에 마지막 Tag::MAC_LENGTH 바이트를 태그로 처리합니다. 태그 인증에 실패하면 ErrorCode::VERIFICATION_FAILED를 반환합니다.

취소

버전: 1, 2, 3

진행 중인 작업을 취소합니다. 취소를 호출한 후 update, finish 또는 abort에서 제공된 작업 핸들을 사용하면 ErrorCode::INVALID_OPERATION_HANDLE을 반환합니다.

get_supported_algorithms

버전: 1

Keymaster 하드웨어 구현에서 지원하는 알고리즘의 목록을 반환합니다. 소프트웨어 구현은 빈 목록을 반환하며 하이브리드 구현은 하드웨어에서 지원하는 알고리즘만 포함하는 목록을 반환합니다.

Keymaster 1 구현은 RSA, EC, AES 및 HMAC를 지원합니다.

get_supported_block_modes

버전: 1

지정된 알고리즘과 목적에 따라 Keymaster 하드웨어 구현에서 지원하는 AES 블록 모드 목록을 반환합니다.

블록 암호화가 아닌 RSA, EC 및 HMAC의 경우 이 메서드는 모든 유효한 목적을 위해 빈 목록을 반환합니다. 목적이 잘못되면 메서드는 ErrorCode::INVALID_PURPOSE를 반환해야 합니다.

Keymaster 1 구현은 AES 암호화 및 복호화를 위해 ECB, CBC, CTR 및 GCM을 지원합니다.

get_supported_padding_modes

버전: 1

지정된 알고리즘과 목적에 따라 Keymaster 하드웨어 구현에서 지원하는 패딩 모드 목록을 반환합니다.

HMAC와 EC에는 패딩의 개념이 없으므로 메서드는 모든 유효한 목적을 위해 빈 목록을 반환합니다. 목적이 잘못되면 메서드는 ErrorCode::INVALID_PURPOSE를 반환해야 합니다.

RSA의 경우 Keymaster 1 구현은 다음을 지원합니다.

패딩되지 않은 암호화, 복호화, 서명 및 인증입니다. 패딩되지 않은 암호화 및 서명의 경우 메시지가 공개 모듈러스보다 짧으면 구현은 메시지 왼쪽을 0으로 채워야 합니다. 패딩되지 않은 복호화 및 인증의 경우 입력 길이가 공개 모듈러스 크기와 일치해야 합니다.
PKCS#1 v1.5 암호화 및 서명 패딩 모드
솔트 길이가 최소 20인 PSS
OAEP

ECB 및 CBC 모드의 AES의 경우 Keymaster 1 구현은 패딩 및 PKCS#7 패딩을 지원하지 않습니다. CTR 및 GCM 모드는 패딩이 없는 모드만 지원합니다.

get_supported_digests

버전: 1

지정된 알고리즘과 목적에 따라 Keymaster 하드웨어 구현에서 지원하는 다이제스트 모드의 목록을 반환합니다.

AES 모드는 다이제스트를 지원하거나 필요로 하지 않으므로 메서드가 유효한 목적을 위해 빈 목록을 반환합니다.

Keymaster 1 구현은 정의된 다이제스트의 하위 집합을 구현할 수 있습니다. 구현은 SHA-256을 제공하며 MD5, SHA1, SHA-224, SHA-256, SHA384 및 SHA512(정의된 다이제스트의 전체 집합)를 제공할 수 있습니다.

get_supported_import_formats

버전: 1

지정된 알고리즘의 Keymaster 하드웨어 구현에서 지원하는 가져오기 형식 목록을 반환합니다.

Keymaster 1 구현은 RSA 및 EC 키 쌍을 가져오기 위해 비밀번호 보호가 적용되지 않는 PKCS#8 형식을 지원하고 AES 및 HMAC 키 자료의 RAW 가져오기를 지원합니다.

get_supported_export_formats

버전: 1

지정된 알고리즘의 Keymaster 하드웨어 구현에서 지원하는 내보내기 형식 목록을 반환합니다.

Keymaster1 구현은 RSA 및 EC 공개 키를 내보내기 위해 X.509 형식을 지원합니다. 비공개 키 또는 비대칭 키 내보내기는 지원되지 않습니다.

이전 함수

Keymaster 0

다음 함수는 원래 Keymaster 0 정의에 속합니다. 이러한 함수는 Keymaster 1 struct keymaster1_device_t에 있었습니다. 하지만 Keymaster 1.0에서 구현되지 않았고 함수 포인터는 NULL로 설정되었습니다.

generate_keypair
import_keypair
get_keypair_public
delete_keypair
delete_all
sign_data
Verify_data

Keymaster 1

다음 함수는 Keymaster 1 정의에 속하지만, 위에 나열된 Keymaster 0 함수와 함께 Keymaster 2에서 삭제되었습니다.

get_supported_algorithms
get_supported_block_modes
get_supported_padding_modes
get_supported_digests
get_supported_import_formats
get_supported_export_formats

Keymaster 2

다음 함수는 Keymaster 2 정의에 속하지만, 위에 나열된 Keymaster 1 함수와 함께 Keymaster 3에서 삭제되었습니다.

configure