Keymaster 승인 태그

이 페이지에서는 Keymaster HAL의 구현자를 지원하기 위한 세부정보를 제공합니다. HAL의 각 태그, 태그를 사용할 수 있는 Keymaster 버전, 태그의 반복 가능 여부 등을 다룹니다. 태그 설명에 명시된 경우를 제외하고 아래의 모든 태그는 키 생성 중에 키 특성을 지정하는 데 사용됩니다.

Keymaster 4의 태그는 Keymaster 3의 경우 3.0/types.hal, Keymaster 4의 경우 4.0/types.hal과 같이 platform/hardware/interfaces/keymaster/keymaster-version/types.hal에서 정의됩니다. Keymaster 2 이하의 경우 태그는 platform/hardware/libhardware/include/hardware/keymaster_defs.h에서 정의됩니다.

함수는 Keymaster 함수 페이지를 참조하세요.

Tag::ACTIVE_DATETIME

버전: 1, 2, 3, 4

반복 가능 아니요

키가 활성화되는 날짜와 시간을 지정합니다. 이 시간 전에 키를 사용하려고 시도하면 ErrorCode::KEY_NOT_YET_VALID와 함께 실패합니다.

값은 1970년 1월 1일 이후 밀리초를 나타내는 64비트 정수입니다.

Tag::ALGORITHM

버전: 1, 2, 3, 4

반복 가능 아니요

키가 사용되는 암호화 알고리즘을 지정합니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 이하
typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Tag::ALL_APPLICATIONS

버전: 1, 2, 3, 4

반복 가능 아니요

나중에 사용하기 위해 예약되어 있습니다.

Tag::ALLOW_WHILE_ON_BODY

버전: 2, 3, 4

반복 가능 아니요

이 태그는 신체 활동 센서가 있는 Android Wear 기기에만 적용됩니다. 이 시점에서 TEE는 신체 활동 센서에 안전하게 액세스하는 기능을 제공할 수 있거나 신체 활동 센서가 매우 안전할 것으로 예상되지 않으므로 소프트웨어 적용 기능만을 할 것으로 예상됩니다.

Tag::ALL_USERS

버전: 3, 4

반복 가능 아니요

나중에 사용하기 위해 예약되어 있습니다.

Tag::APPLICATION_DATA

버전: 1, 2, 3, 4

반복 가능 아니요

generateKey 또는 importKey에 제공될 때 이 태그는 키를 사용하는 모든 경우에 필요한 데이터를 지정합니다. 특히 exportKey 및 getKeyCharacteristics를 호출하려면 clientId 매개변수에 동일한 값을 제공해야 하며 begin을 호출하려면 이 태그 및 inParams 세트의 일부와 동일한 관련 데이터를 제공해야 합니다. 올바른 데이터가 제공되지 않으면 함수는 ErrorCode::INVALID_KEY_BLOB을 반환합니다.

이 태그의 콘텐츠는 암호화 방식으로 키에 결합됩니다. 즉, 모든 안전한 환경의 보안 비밀에 액세스할 수 있지만 태그 콘텐츠에 액세스할 수 없는 공격자가 태그 콘텐츠를 강제로 파헤치지 않은 채 키를 복호화하는 것이 불가능해야 합니다. 애플리케이션이 충분히 엔트로피가 높은 콘텐츠를 지정하여 이를 방지할 수 있습니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::APPLICATION_ID

버전: 1, 2, 3, 4

반복 가능 아니요

generateKey 또는 importKey에 제공될 때 이 태그는 키를 사용하는 모든 경우에 필요한 데이터를 지정합니다. 특히 exportKey 및 getKeyCharacteristics를 호출하려면 clientId 매개변수에 동일한 값을 제공해야 하며 begin을 호출하려면 이 태그 및 inParams 세트의 일부와 동일한 관련 데이터를 제공해야 합니다. 올바른 데이터가 제공되지 않으면 함수는 ErrorCode::INVALID_KEY_BLOB을 반환합니다.

이 태그의 콘텐츠는 암호화 방식으로 키에 결합됩니다. 즉, 모든 안전한 환경의 보안 비밀에 액세스할 수 있지만 태그 콘텐츠에 액세스할 수 없는 공격자가 태그 콘텐츠를 강제로 파헤치지 않은 채 키를 복호화할 수 없습니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ASSOCIATED_DATA

버전: 1, 2, 3, 4

반복 가능 아니요

AES-GCM 암호화 또는 복호화를 위한 '관련 데이터'를 제공합니다. 이 태그는 update에 제공되며 암호화/복호화되지 않지만 GCM 태그를 계산하는 데 사용되는 데이터를 지정합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_APPLICATION_ID

버전: 3, 4

반복 가능 아니요

키 증명을 시작한 애플리케이션이 포함되었을 수 있는 집합을 식별하는 데 사용됩니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_CHALLENGE

버전: 3, 4

반복 가능 아니요

증명에서 도전과제를 제공하는 데 사용됩니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_BRAND

버전: 3, 4

반복 가능 아니요

Android에서 Build.BRAND가 반환한 기기의 브랜드 이름을 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_DEVICE

버전: 3, 4

반복 가능 아니요

Android에서 Build.DEVICE가 반환한 기기의 기기 이름을 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_IMEI

버전: 3, 4

반복 가능 예

기기의 모든 무선 통신에 IMEI를 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_MANUFACTURER

버전: 3, 4

반복 가능 아니요

Android에서 Build.MANUFACTURER가 반환한 기기의 제조업체 이름을 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_MEID

버전: 3, 4

반복 가능 예

기기의 모든 무선 통신에 MEID를 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_MODEL

버전: 3, 4

반복 가능 아니요

Android에서 Build.MODEL이 반환한 기기의 모델 이름을 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_PRODUCT

버전: 3, 4

반복 가능 아니요

Android에서 Build.PRODUCT가 반환한 기기의 제품 이름을 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::ATTESTATION_ID_SERIAL

버전: 3, 4

반복 가능 아니요

기기의 일련번호를 제공합니다. 이 필드는 기기 식별자의 증명을 요청할 때만 설정됩니다.

기기에서 ID 증명을 지원하지 않는다면(또는 destroyAttestationIds()가 이전에 호출되었고 기기에서 더 이상 ID를 증명할 수 없다면) 이러한 태그를 포함하는 키 증명 요청은 ErrorCode::CANNOT_ATTEST_IDS와 함께 실패합니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::AUTH_TIMEOUT

버전: 1, 2, 3, 4

반복 가능 아니요

인증 후 키 사용이 승인된 시간을 초 단위로 지정합니다. Tag::USER_SECURE_ID가 있고 이 태그가 없으면 키를 사용할 때마다 인증이 필요합니다(작업별 인증 흐름에 관한 자세한 내용은 begin 참조).

이 값은 키를 사용할 수 있는 Tag::USER_AUTH_TYPE에 지정된 인증 방법으로 Tag::USER_SECURE_ID로 지정된 사용자를 인증한 이후의 시간을 초 단위로 지정하는 32비트 정수입니다.

Tag::AUTH_TOKEN

버전: 1, 2, 3, 4

반복 가능 아니요

키 작업을 위한 사용자 인증을 증명하기 위해 begin, update 또는 finish에 인증 토큰을 제공합니다(키에 Tag::USER_SECURE_ID 있음).

값은 hw_auth_token_t 구조를 포함한 blob입니다.

Tag::BLOB_USAGE_REQUIREMENTS

버전: 1, 2, 3, 4

반복 가능 아니요

생성된 키를 사용하는 데 필요한 시스템 환경 조건을 지정합니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 이하
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

이 태그는 지정된 조건에서 키를 사용할 수 있도록 키 생성 중에 지정할 수 있습니다. generateKey 및 getKeyCharacteristics의 키 특성과 함께 반환되어야 합니다. 호출자가 KeyBlobUsageRequirements::STANDALONE 값으로 Tag::BLOB_USAGE_REQUIREMENTS를 지정하면 trustlet은 파일 시스템 지원 없이 사용할 수 있는 키 blob을 반환합니다. 이는 Keymaster 키를 사용하여 디스크를 복호화할 때까지 파일 시스템을 사용하지 못할 수 있는 암호화된 디스크가 있는 기기에 매우 중요합니다.

Tag::BLOCK_MODE

버전: 1, 2, 3, 4

반복 가능 예

키를 사용할 수 있는 블록 암호화 모드를 지정합니다. 이 태그는 AES 키와만 관련이 있습니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 이하
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

이 태그는 반복 가능합니다. AES 키 작업의 경우 begin의 additionalParams 인수에서 모드를 지정하세요. 지정된 모드가 키와 관련된 모드가 아닌 경우 ErrorCode::INCOMPATIBLE_BLOCK_MODE와 함께 작업이 실패합니다.

Tag::BOOT_PATCHLEVEL

버전: 4

Tag::BOOT_PATCHLEVEL은 키가 사용될 수 있는 부팅 이미지(커널) 보안 패치 수준을 지정합니다. 이 태그는 keymaster TA로 전송되지 않지만 TA에 의해 하드웨어 적용 승인 목록에 추가됩니다. 현재 실행 중인 시스템 패치 수준과 다른 Tag::BOOT_PATCHLEVEL 값이 있는 키를 사용하려고 하면 begin(), getKeyCharacteristics() 또는 exportKey()가 ErrorCode::KEY_REQUIRES_UPGRADE를 반환합니다. 자세한 내용은 upgradeKey()를 참조하세요.

태그의 값은 YYYYMMDD 형식의 정수이며 여기서 YYYY는 마지막으로 업데이트한 네 자리 숫자 연도, MM은 두 자리 숫자 월, DD는 마지막으로 업데이트한 두 자리 숫자 날짜입니다. 예를 들어 2018년 6월 5일에 마지막으로 업데이트된 Android 기기에서 생성된 키 값은 20180605가 됩니다. 날짜를 알 수 없는 경우 00으로 대체될 수 있습니다.

부팅할 때마다 부트로더는 부팅 이미지의 패치 수준을 안전한 환경에 제공해야 합니다(메커니즘은 구현으로 정의됨).

하드웨어에서 시행해야 합니다.

Tag::BOOTLOADER_ONLY

버전: 1, 2, 3, 4

반복 가능 아니요

부트로더만 키를 사용할 수 있도록 지정합니다.

이 태그는 부울이므로 가능한 값은 참(태그가 있는 경우)과 거짓(태그가 없는 경우)입니다.

Android 시스템에서 Tag::BOOTLOADER_ONLY가 있는 키를 사용하려고 하면 ErrorCode::INVALID_KEY_BLOB과 함께 실패합니다.

Tag::CALLER_NONCE

버전: 1, 2, 3, 4

반복 가능 아니요

호출자가 nonce가 필요한 작업에 nonce를 제공할 수 있도록 지정합니다.

이 태그는 부울이므로 가능한 값은 참(태그가 있는 경우)과 거짓(태그가 없는 경우)입니다.

이 태그는 AES 키에만 사용되며 CBC, CTR 및 GCM 블록 모드와만 관련이 있습니다. 태그가 없는 경우 구현 시 ErrorCode::CALLER_NONCE_PROHIBITED와 함께 begin에 Tag::NONCE를 제공하는 모든 작업을 거부해야 합니다.

Tag::CREATION_DATETIME

버전: 1, 2, 3, 4

반복 가능 아니요

1970년 1월 1일 이후의 키 생성 날짜 및 시간을 밀리초 단위로 지정합니다. 이 태그는 선택사항이며 정보 제공용입니다.

Tag::DIGEST

버전: 1, 2, 3, 4

반복 가능 예

서명 및 확인 작업을 실행하기 위해 키와 함께 사용할 수 있는 다이제스트 알고리즘을 지정합니다. 이 태그는 RSA, ECDSA 및 HMAC 키와 관련이 있습니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};
Keymaster 2 이하
typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

이 태그는 반복 가능합니다. 서명 및 확인 작업의 경우 begin의 additionalParams 인수에서 다이제스트를 지정합니다. 지정된 다이제스트가 키와 관련된 다이제스트에 없는 경우 ErrorCode::INCOMPATIBLE_DIGEST와 함께 작업이 실패합니다.

Tag::EC_CURVE

버전: 2, 3, 4

반복 가능 아니요

Keymaster 1에서 EC 키에 사용된 곡선은 지정된 키 크기에서 추측되었습니다. 유연성을 개선하기 위해 Keymaster 2에서는 곡선을 지정하는 명확한 방법을 도입했습니다. EC 키 생성 요청에는 Tag::EC_CURVE, Tag::KEY_SIZE 또는 둘 다를 포함할 수 있습니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 이하
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

생성 요청에 Tag::KEY_SIZE만 포함된 경우 적절한 NIST 곡선을 선택하여 Keymaster 1 로직으로 대체합니다.

요청에 Tag::EC_CURVE만 포함된 경우 지정된 곡선을 사용합니다. Keymaster 3 이상에서는 곡선이 EcCurve로 정의됩니다. Keymaster 2 이하의 경우 곡선은 keymaster_ec_curve_t로 정의됩니다.

요청에 둘 다 포함된 경우 Tag::EC_CURVE로 지정된 곡선을 사용하고 지정된 키 크기가 곡선에 적합한지 확인합니다. 적합하지 않으면 ErrorCode::INVALID_ARGUMENT를 반환합니다.

Tag::INCLUDE_UNIQUE_ID

버전: 2, 3, 4

반복 가능 아니요

이 태그는 키 생성 중에 지정되어 Tag::UNIQUE_ID에 지정된 대로 생성된 키의 증명 인증서에 애플리케이션 범위의 시간이 제한된 기기 고유 ID를 포함해야 함을 나타냅니다.

이 태그는 부울이므로 가능한 값은 참(태그가 있는 경우)과 거짓(태그가 없는 경우)입니다.

Tag::KEY_SIZE

버전: 1, 2, 3, 4

반복 가능 아니요

키 알고리즘의 일반적인 방식으로 측정하여 키의 크기를 비트 단위로 지정합니다. 예를 들어 RSA 키의 경우 Tag::KEY_SIZE는 공개 모듈의 크기를 지정합니다. AES 키의 경우 보안 비밀 키 자료의 길이를 지정합니다.

Tag::MAC_LENGTH

버전: 1, 2, 3, 4

반복 가능 아니요

요청된 MAC 또는 GCM 인증 태그의 길이를 비트 단위로 제공합니다.

값은 비트 단위의 MAC 길이입니다. 8의 배수이며 크기는 키와 연관된 Tag::MIN_MAC_LENGTH 이상이어야 합니다.

Tag::MAX_USES_PER_BOOT

버전: 1, 2, 3, 4

반복 가능 아니요

시스템 재부팅 사이에 키를 사용할 수 있는 최대 횟수를 지정합니다. 이는 키 사용을 비율로 제한하는 또 다른 메커니즘입니다.

값은 부팅당 사용을 나타내는 32비트 정수입니다.

이 태그가 있는 키가 작업에 사용되면 begin 호출 중에 키 관련 카운터를 증가시켜야 합니다. 키 카운터가 이 값을 초과하면 기기가 다시 시작될 때까지 이후 모든 키 사용 시도는 ErrorCode::MAX_OPS_EXCEEDED와 함께 실패합니다. 이는 trustlet이 이 태그가 있는 키에서 사용 카운터의 테이블을 유지함을 의미합니다. Keymaster 메모리는 종종 제한되므로 이 테이블은 고정된 최대 크기를 가질 수 있으며 테이블이 꽉 찼을 때 이 태그가 있는 키를 사용하려는 Keymaster 작업은 실패할 수 있습니다. 테이블은 최소 16개의 키를 수용할 수 있어야 합니다. 테이블이 꽉 차서 작업이 실패하면 Keymaster는 ErrorCode::TOO_MANY_OPERATIONS를 반환합니다.

Tag::MIN_MAC_LENGTH

버전: 1, 2, 3, 4

반복 가능 아니요

이 태그는 GCM 모드를 지원하는 HMAC 키 및 AES 키를 이 키로 요청하거나 확인할 수 있는 MAC의 최소 길이를 지정합니다.

이 값은 비트 단위의 최소 MAC 길이이며 8의 배수입니다. HMAC 키의 경우 값은 64 이상이어야 합니다. GCM 키의 경우 값은 96 이상 128 이하여야 합니다.

Tag::MIN_SECONDS_BETWEEN_OPS

버전: 1, 2, 3, 4

반복 가능 아니요

키를 사용하여 허용되는 작업 사이에 경과하는 최소 시간을 지정합니다. 무제한 사용이 무차별 공격을 허용할 수 있는 상황에서 키 사용을 비율로 제한하는 데 사용할 수 있습니다.

값은 허용되는 작업 사이의 초를 나타내는 32비트 정수입니다.

이 태그가 있는 키가 작업에 사용되면 finish 또는 abort 호출 중에 타이머를 시작합니다. Tag::MIN_SECONDS_BETWEEN_OPS에 의해 지정된 간격이 경과했다고 타이머에서 나타내기 전에 수신된 begin 호출은 ErrorCode::KEY_RATE_LIMIT_EXCEEDED와 함께 실패합니다. 이는 trustlet이 이 태그가 있는 키에서 사용 카운터의 테이블을 유지함을 의미합니다. Keymaster 메모리는 종종 제한되므로 이 테이블은 고정된 최대 크기를 가질 수 있으며 테이블이 꽉 찼을 때 이 태그가 있는 키를 사용하려는 Keymaster 작업은 실패할 수 있습니다. 테이블은 적어도 32개의 사용 중인 키를 수용해야 하며 키 최소 사용 간격이 만료될 때 테이블 슬롯을 적극적으로 재사용해야 합니다. 테이블이 꽉 차서 작업이 실패하면 Keymaster는 ErrorCode::TOO_MANY_OPERATIONS를 반환합니다.

Tag::NO_AUTH_REQUIRED

버전: 1, 2, 3, 4

반복 가능 아니요

이 키를 사용하는 데 인증이 필요 없다는 것을 지정합니다. 이 태그는 Tag::USER_SECURE_ID와 함께 사용할 수 없습니다.

이 태그는 부울이므로 가능한 값은 참(태그가 있는 경우)과 거짓(태그가 없는 경우)입니다.

Tag::NONCE

버전: 1, 2, 3, 4

반복 가능 아니요

AES GCM, CBC 또는 CTR의 암호화 또는 복호화에 관한 nonce 또는 초기화 벡터(IV)를 제공하거나 반환합니다. 이 태그는 암호화 및 복호화 작업 중에 begin에 제공됩니다. 키에 Tag::CALLER_NONCE가 있는 경우에만 begin에 제공됩니다. 제공되지 않으면 적절한 nonce나 IV가 Keymaster에 의해 임의로 생성되고 begin에서 반환됩니다.

값은 임의의 길이의 바이트 배열인 blob입니다. 허용되는 길이는 모드에 따라 다릅니다. 가령, GCM nonce의 길이는 12바이트이고 CBC 및 CTR IV의 길이는 16바이트입니다.

Tag::ORIGIN

버전: 1, 2, 3, 4

반복 가능 아니요

키가 생성된 곳을 지정합니다(알려진 경우). 이 태그는 키 생성 또는 가져오기 중에 지정할 수 없으며 trustlet에 의해 키 특성에 추가되어야 합니다.

Keymaster 3

가능한 값은 android::hardware::keymaster::v3_0::KeyOrigin에서 정의됩니다.

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 이하

가능한 값은 keymaster_origin_t에서 정의됩니다.

typedef enum {
    KM_ORIGIN_GENERATED = 0,
    KM_ORIGIN_IMPORTED = 2,
    KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t

값의 전체 의미는 값뿐 아니라 하드웨어 적용 특성 목록에서 발견되는지 소프트웨어 적용 특성 목록에서 발견되는지에 따라 달라집니다.

GENERATED는 Keymaster가 키를 생성했음을 나타냅니다. 하드웨어 적용 목록에 있는 경우 키는 안전한 하드웨어에서 생성된 것이며 하드웨어에 영구적으로 결합됩니다. 소프트웨어 적용 목록에 있는 경우 키는 SoftKeymaster에서 생성된 것이며 하드웨어에 결합되지 않습니다.

DERIVED는 키가 Keymaster 내부에서 파생되었음을 나타냅니다. 기기 외부에 존재할 수 있습니다.

IMPORTED는 Keymaster 외부에서 생성되어 Keymaster로 가져온 키임을 나타냅니다. 하드웨어 적용 목록에 있는 경우 안전한 하드웨어의 외부에 사본이 존재할 수 있지만 하드웨어에 영구적으로 결합됩니다. 소프트웨어 적용 목록에 있는 경우 SoftKeymaster로 키를 가져온 것이며 하드웨어에 결합되지 않습니다.

UNKNOWN은 하드웨어 적용 목록에만 표시되어야 합니다. 이는 키가 하드웨어에 결합됨을 나타내지만 키를 안전한 하드웨어에서 원래 생성한 것인지 가져온 것인지는 알 수 없습니다. keymaster0 하드웨어를 사용하여 keymaster1 서비스를 에뮬레이션하는 경우에만 발생합니다.

Tag::ORIGINATION_EXPIRE_DATETIME

버전: 1, 2, 3, 4

반복 가능 아니요

서명 및 암호화 목적으로 키가 만료되는 날짜와 시간을 지정합니다. 이 시간 이후 begin에 제공된 KeyPurpose::SIGN 또는 KeyPurpose::ENCRYPT가 있는 키를 사용하려면 하면 ErrorCode::KEY_EXPIRED와 함께 실패합니다.

값은 1970년 1월 1일 이후 밀리초를 나타내는 64비트 정수입니다.

Tag::OS_PATCHLEVEL

버전: 2, 3, 4

반복 가능 아니요

이 태그는 keymaster TA로 전송되지 않지만 TA에 의해 하드웨어 적용 승인 목록에 추가됩니다.

태그의 값은 YYYYMM 형식의 정수이며 여기서 YYYY는 마지막으로 업데이트한 네 자리 숫자 연도이고 MM은 마지막으로 업데이트한 두 자리 숫자 월입니다. 예를 들어 2015년 12월에 마지막으로 업데이트된 Android 기기에서 생성된 키 값은 201512입니다.

패치 수준이 현재 패치 수준과 다른 키는 사용할 수 없습니다. 그러한 키를 사용하려고 하면 begin, getKeyCharacteristics 또는 exportKey가 ErrorCode::KEY_REQUIRES_UPGRADE를 반환합니다. 자세한 내용은 버전 결합을 참조하세요.

Tag::OS_VERSION

버전: 2, 3, 4

반복 가능 아니요

이 태그는 keymaster TA로 전송되지 않지만 TA에 의해 하드웨어 적용 승인 목록에 추가됩니다.

태그의 값은 MMmmss 형식의 정수이며 여기서 MM은 주 버전 번호이고 mm은 부 버전 번호이며 ss는 하위 부 버전 번호입니다. 예를 들어 Android 버전 4.0.3에서 생성된 키 값은 040003입니다.

Tag::PADDING

버전: 1, 2, 3, 4

반복 가능 예

키와 함께 사용할 수 있는 패딩 모드를 지정합니다. 이 태그는 RSA 및 AES 키와 관련이 있습니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};
Keymaster 2 이하
typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP 및 PaddingMode::RSA_PKCS1_1_5_ENCRYPT는 RSA 암호화/복호화 키에만 사용되며 각각 RSA PKCS#1v2 OAEP 패딩 및 RSA PKCS#1 v1.5 무작위 패딩을 지정합니다. PaddingMode::RSA_PSS 및 PaddingMode::RSA_PKCS1_1_5_SIGN은 RSA 서명/확인 키에만 사용되며 각각 RSA PKCS#1v2 PSS 패딩 및 RSA PKCS#1 v1.5 결정적 패딩을 지정합니다.

PaddingMode::NONE은 RSA 또는 AES 키와 함께 사용할 수 있습니다. AES 키의 경우 PaddingMode::NONE을 블록 모드 ECB 또는 CBC와 함께 사용하고 암호화 또는 복호화할 데이터의 길이가 AES 블록 크기의 배수가 아닌 경우 finish 호출은 ErrorCode::INVALID_INPUT_LENGTH와 함께 실패합니다.

PaddingMode::PKCS7은 AES 키와만 그리고 ECB 및 CBC 모드와만 사용할 수 있습니다.

이 태그는 반복 가능합니다. begin 호출에서 패딩 모드를 지정해야 합니다. 지정된 모드가 키에서 승인되지 않으면 ErrorCode::INCOMPATIBLE_BLOCK_MODE와 함께 작업이 실패합니다.

Tag::PURPOSE

버전: 1, 2, 3, 4

반복 가능 예

키를 사용할 수 있는 목적의 집합을 지정합니다.

가능한 값은 다음과 같은 열거로 정의됩니다.

Keymaster 3
enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};
Keymaster 2 이하
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

이 태그는 반복 가능합니다. 작업마다 하나의 목적만 있지만 여러 값으로 키를 생성할 수 있습니다. begin 함수를 호출하여 작업을 시작하면 작업의 목적이 지정됩니다. 작업에 지정된 목적을 키가 승인하지 않으면 ErrorCode::INCOMPATIBLE_PURPOSE와 함께 작업이 실패합니다.

Tag::RESET_SINCE_ID_ROTATION

버전: 3, 4

반복 가능 아니요

마지막 고유 ID 순환 이후 기기가 초기화되었는지 지정합니다. 키 증명에 사용됩니다.

이 태그는 부울이므로 가능한 값은 참(태그가 있는 경우)과 거짓(태그가 없는 경우)입니다.

Tag::ROLLBACK_RESISTANT

버전: 1, 2, 3, 4

반복 가능 아니요

키가 롤백이 방지됨을 나타냅니다. 즉, deleteKey 또는 deleteAllKeys에 의해 삭제될 때 키가 영구적으로 삭제되어 사용할 수 없게 됩니다. 이 태그가 없는 키는 삭제한 다음 백업에서 복원할 수 있습니다.

이 태그는 부울이므로 가능한 값은 참(태그가 있는 경우)과 거짓(태그가 없는 경우)입니다.

Tag::ROOT_OF_TRUST

버전: 1, 2, 3, 4

반복 가능 아니요

자체 검사 부팅에서 부팅된 운영체제(있는 경우)를 검증하는 데 사용하는 키인 신뢰할 수 있는 루트를 지정합니다. 이 태그는 키 특성에서 Keymaster에 제공되거나 Keymaster로부터 반환되지 않습니다.

Tag::RSA_PUBLIC_EXPONENT

버전: 1, 2, 3, 4

반복 가능 아니요

RSA 키 쌍의 공개 지수 값을 지정합니다. 이 태그는 RSA 키와만 관련되며 모든 RSA 키에 필요합니다.

값은 RSA 공개 지수의 요구사항을 충족하는 부호 없는 64비트 정수입니다. 이 값은 소수여야 합니다. Trustlet은 값 2^16+1을 지원하며 다른 합당한 값, 특히 값 3을 지원할 수 있습니다. 지수를 지정하지 않거나 지정된 지수가 지원되지 않는 경우 ErrorCode::INVALID_ARGUMENT와 함께 키 생성이 실패합니다.

Tag::UNIQUE_ID

버전: 3, 4

반복 가능 아니요

증명에서 고유 ID를 제공하는 데 사용됩니다.

값은 임의의 길이의 바이트 배열인 blob입니다.

Tag::USAGE_EXPIRE_DATETIME

버전: 1, 2, 3, 4

반복 가능 아니요

키가 확인 및 복호화 목적으로 만료되는 날짜와 시간을 지정합니다. 이 시간 이후 begin에 제공된 KeyPurpose::VERIFY 또는 KeyPurpose::DECRYPT가 있는 키를 사용하려고 하면 ErrorCode::KEY_EXPIRED와 함께 실패합니다.

값은 1970년 1월 1일 이후 밀리초를 나타내는 64비트 정수입니다.

Tag::USER_AUTH_TYPE

버전: 1, 2, 3, 4

반복 가능 아니요

이 키를 승인하는 데 사용할 수 있는 사용자 인증자 유형을 지정합니다. 이 태그가 있는 키로 작업하도록 요청하는 경우 Keymaster는 인증 토큰을 받으며 토큰의 authenticator_type 필드는 태그의 값과 일치해야 합니다. 예를 들어 (ntoh(token.authenticator_type) & auth_type_tag_value) != 0의 경우 ntoh는 네트워크 순서 정수를 호스트 순서 정수로 변환하는 함수이고 auth_type_tag_value는 이 태그의 값입니다.

값은 열거에서 온 값의 32비트 정수 비트 마스크입니다.

Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 이하
typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

Tag::USER_SECURE_ID

버전: 1, 2, 3, 4

반복 가능 아니요

특별한 보안 사용자 인증 상태에서만 키를 사용할 수 있도록 지정합니다. 이 태그는 Tag::NO_AUTH_REQUIRED와 함께 사용할 수 없습니다.

이 값은 키의 사용 권한을 부여하기 위해 인증 토큰(Tag::AUTH_TOKEN과 함께 begin에 제공됨)에 있어야 하는 인증 정책 상태 값을 지정하는 64비트 정수입니다. 인증 토큰을 제공하지 않거나 일치하는 정책 상태 값 없이 인증 토큰을 제공하는 이 태그가 있는 키로 begin을 호출하면 실패합니다.

이 태그는 반복 가능합니다. 제공된 값 중 하나라도 인증 토큰의 정책 상태 값과 일치하면 키 사용이 승인됩니다. 일치하지 않으면 ErrorCode::KEY_USER_NOT_AUTHENTICATED와 함께 작업이 실패합니다.

Tag::VENDOR_PATCHLEVEL

버전: 4

이 태그는 키를 사용할 수 있는 공급업체 이미지 보안 패치 수준을 지정합니다. 이 태그는 keymaster TA로 전송되지 않지만 TA에 의해 하드웨어 적용 승인 목록에 추가됩니다. 현재 실행 중인 시스템 패치 수준과 다른 Tag::VENDOR_PATCHLEVEL 값이 있는 키를 사용하려고 하면 begin(), getKeyCharacteristics() 또는 exportKey()가 ErrorCode::KEY_REQUIRES_UPGRADE를 반환합니다. 자세한 내용은 upgradeKey()를 참조하세요.

태그의 값은 YYYYMMDD 형식의 정수이며 여기서 YYYY는 마지막으로 업데이트한 네 자리 숫자 연도, MM은 두 자리 숫자 월, DD는 마지막으로 업데이트한 두 자리 숫자 날짜입니다. 예를 들어 2018년 6월 5일에 마지막으로 업데이트된 Android 기기에서 생성된 키 값은 20180605가 됩니다.

IKeymasterDevice HAL은 시스템 속성 ro.vendor.build.security_patch에서 현재 공급업체 패치 수준을 읽고 HAL이 처음 로드될 때 안전한 환경으로 전달해야 합니다(메커니즘은 구현으로 정의됨). 안전한 환경은 다음에 부팅할 때까지 다른 패치 수준을 허용하지 않아야 합니다.

하드웨어에서 시행해야 합니다.