Keymaster Yetkilendirme Etiketleri

Bu sayfada Keymaster HAL'lerin uygulayıcılarına yardımcı olacak ayrıntılar sağlanmaktadır. HAL'deki her etiketi, bu etiketin hangi Keymaster sürümünde mevcut olduğunu ve etiketin tekrarlanabilir olup olmadığını kapsar. Etiket açıklamalarında belirtilmediği sürece, aşağıdaki etiketlerin tümü anahtar oluşturma sırasında anahtar özellikleri belirtmek için kullanılır.

Keymaster 4 için etiketler platform/hardware/interfaces/keymaster/ keymaster-version /types.hal dosyasında tanımlanır; örneğin Keymaster 3 için 3.0/types.hal ve Keymaster 4 için 4.0/types.hal. Keymaster 2 ve altı için, Etiketler platform/hardware/libhardware/include/hardware/keymaster_defs.h dosyasında tanımlanır.

İşlevler için Keymaster İşlevleri sayfasına bakın.

Etiket::ACTIVE_DATETIME

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Anahtarın etkin olacağı tarih ve saati belirtir. Bu süreden önce, anahtarı kullanma girişimleri ErrorCode::KEY_NOT_YET_VALID ile başarısız oluyor.

Değer, 1 Ocak 1970'ten bu yana milisaniyeyi temsil eden 64 bitlik bir tam sayıdır.

Etiket::ALGORİTMA

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Anahtarın kullanıldığı şifreleme algoritmasını belirtir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

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

Etiket::ALL_APPLICATIONS

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Gelecekte kullanılmak üzere rezerve edilmiştir.

Etiket::ALLOW_WHILE_ON_BODY

Versiyon : 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu etiket yalnızca gövde üstü sensörlere sahip Android Wear cihazları için geçerlidir. Bu noktada herhangi bir TEE'nin vücut üstü sensöre güvenli erişim sağlaması veya vücut üstü sensörlerin çok güvenli olması beklenmiyor, dolayısıyla bunun tamamen yazılımla zorlanan bir özellik olması bekleniyor.

Etiket::ALL_USERS

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Gelecekte kullanılmak üzere rezerve edilmiştir.

Etiket::APPLICATION_DATA

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

createdKey veya importKey için sağlandığında bu etiket, anahtarın tüm kullanımları sırasında gerekli olan verileri belirtir. Özellikle, importKey ve getKeyCharacteristics çağrılarının clientId parametresine aynı değeri sağlaması gerekir ve start çağrılarının bu etiketi ve inParams kümesinin bir parçası olarak aynı ilişkili verileri sağlaması gerekir. Doğru veriler sağlanmazsa işlev ErrorCode::INVALID_KEY_BLOB döndürür.

Bu etiketin içeriği anahtara kriptografik olarak bağlıdır; bu, tüm güvenli dünya sırlarına erişimi olan ancak etiket içeriğine erişimi olmayan bir saldırganın, etiketi kaba kuvvet uygulamadan anahtarın şifresini çözmesinin mümkün olmaması gerektiği anlamına gelir. uygulamaların yeterince yüksek entropili içerik belirterek engelleyebileceği içerik.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::APPLICATION_ID

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

createdKey veya importKey için sağlandığında bu etiket, anahtarın tüm kullanımları sırasında gerekli olan verileri belirtir. Özellikle, ExportKey ve getKeyCharacteristics çağrılarının clientId parametresinde aynı değeri sağlaması gerekir ve start çağrılarının bu etiketi ve inParams kümesinin bir parçası olarak aynı ilişkili verileri sağlaması gerekir. Doğru veriler sağlanmazsa işlev ErrorCode::INVALID_KEY_BLOB döndürür.

Bu etiketin içeriği anahtara kriptografik olarak bağlıdır; bu, tüm güvenli dünya sırlarına erişebilen ancak etiket içeriğine erişimi olmayan bir düşmanın anahtarın şifresini çözemeyeceği (etiket içeriğine kaba kuvvet uygulamadan) anlamına gelir. ).

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ASSOCIATED_DATA

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

AES-GCM şifrelemesi veya şifre çözmesi için "ilişkili veriler" sağlar. Bu etiket, şifrelenmemiş/şifresi çözülmemiş verileri güncellemek ve belirtmek için sağlanmıştır, ancak GCM etiketinin hesaplanmasında kullanılır.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_APPLICATION_ID

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Önemli bir doğrulamanın başlatıldığı olası uygulama kümesini tanımlamak için kullanılır.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_CHALLENGE

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Kanıtlamada zorluk sağlamak için kullanılır.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_BRAND

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Android'de Build.BRAND tarafından döndürüldüğü şekliyle cihazın marka adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_DEVICE

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Android'de Build.DEVICE tarafından döndürülen cihazın cihaz adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_IMEI

Versiyon : 3, 4

Tekrarlanabilir mi ? Evet

Cihazdaki tüm radyoların IMEI'lerini sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_MANUFACTURER

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Android'de Build.MANUFACTURER tarafından döndürülen cihazın üretici adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_MEID

Versiyon : 3, 4

Tekrarlanabilir mi ? Evet

Cihazdaki tüm radyolar için MEID'leri sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanacaktır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_MODEL

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Android'de Build.MODEL tarafından döndürülen cihazın model adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_product

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Android'de Build.PRODUCT tarafından döndürülen cihazın ürün adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::ATTESTATION_ID_SERIAL

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Cihazın seri numarasını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının doğrulanması istendiğinde ayarlanır.

Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds() daha önce çağrılmışsa ve cihaz artık kimliklerini doğrulayamıyorsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS ile başarısız olur.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::AUTH_TIMEOUT

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Kimlik doğrulama sonrasında anahtarın kullanım için yetkilendirildiği süreyi saniye cinsinden belirtir. Tag::USER_SECURE_ID mevcutsa ve bu etiket yoksa, anahtarın her kullanım için kimlik doğrulaması gerekir (işlem başına kimlik doğrulama akışının ayrıntıları için başlangıca bakın).

Değer, Tag::USER_SECURE_ID tarafından belirtilen kullanıcının , Tag::USER_AUTH_TYPE tarafından belirtilen kimlik doğrulama yöntemiyle başarılı bir şekilde kimlik doğrulamasından sonra anahtarın kullanılabileceği süreyi saniye cinsinden belirten 32 bitlik bir tam sayıdır.

Etiket::AUTH_TOKEN

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bunu gerektiren bir anahtar işlemi için kullanıcı kimlik doğrulamasını kanıtlamak üzere başlamak , güncellemek veya bitirmek için bir kimlik doğrulama belirteci sağlar (anahtarın Etiketi::USER_SECURE_ID vardır).

Değer, hw_auth_token_t yapısını içeren bir blobdur.

Etiket::BLOB_USAGE_REQUIREMENTS

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Oluşturulan anahtarın kullanılması için gerekli sistem ortamı koşullarını belirtir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

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

Bu etiket, anahtarın belirtilen durumda kullanılabilir olmasını gerektirmek için anahtar oluşturma sırasında belirtilebilir. GenerateKey ve getKeyCharacteristics öğelerinin temel özellikleriyle birlikte döndürülmesi gerekir. Arayan, KeyBlobUsageRequirements::STANDALONE değeriyle Tag::BLOB_USAGE_REQUIREMENTS belirtirse, güvenilen uygulama, dosya sistemi desteği olmadan kullanılabilecek bir anahtar blobu döndürür. Bu, diskin şifresini çözmek için bir Keymaster anahtarı kullanılıncaya kadar dosya sisteminin kullanılamadığı şifrelenmiş disklere sahip cihazlar için kritik öneme sahiptir.

Etiket::BLOCK_MODE

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? Evet

Anahtarın kullanılabileceği blok şifreleme modunu/modlarını belirtir. Bu etiket yalnızca AES anahtarlarıyla ilgilidir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

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

Bu etiket tekrarlanabilir ve AES anahtar işlemleri için begin öğesinin additionalParams bağımsız değişkeninde bir mod belirtin. Belirtilen mod, anahtarla ilişkili modlarda değilse, işlem ErrorCode::INCOMPATIBLE_BLOCK_MODE ile başarısız olur.

Etiket::BOOT_PATCHLEVEL

Versiyon : 4

Tag::BOOT_PATCHLEVEL, anahtarın kullanılabileceği önyükleme görüntüsü (çekirdek) güvenlik yaması düzeyini belirtir. Bu etiket hiçbir zaman anahtar yöneticisi TA'ya gönderilmez, ancak TA tarafından donanım tarafından uygulanan yetkilendirme listesine eklenir. Şu anda çalışan sistem yama düzeyinden farklı bir Tag::BOOT_PATCHLEVEL değerine sahip bir anahtar kullanma girişimi begin() , getKeyCharacteristics() veya exportKey() işlevinin ErrorCode::KEY_REQUIRES_UPGRADE döndürmesine neden olur. Ayrıntılar için upgradeKey() e bakın.

Etiketin değeri YYYYAAGG biçiminde bir tamsayıdır; burada YYYY, son güncellemenin dört haneli yılı, MM iki haneli ay ve DD, son güncellemenin iki haneli günüdür. Örneğin, en son 5 Haziran 2018'de güncellenen bir Android cihazda oluşturulan bir anahtar için değer 20180605 olacaktır. Gün bilinmiyorsa 00 yerine kullanılabilir.

Her önyükleme sırasında, önyükleyicinin önyükleme görüntüsünün yama düzeyini güvenli ortama sağlaması gerekir (mekanizma uygulama tarafından tanımlanır).

Donanım tarafından zorlanmalıdır.

Etiket::BOOTLOADER_ONLY

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Anahtarı yalnızca önyükleyicinin kullanabileceğini belirtir.

Bu etiket booleandır, dolayısıyla olası değerler true (etiket varsa) ve false (etiket yoksa) şeklindedir.

Android sisteminden Tag::BOOTLOADER_ONLY içeren bir anahtarı kullanma girişimleri ErrorCode::INVALID_KEY_BLOB ile başarısız olur.

Etiket::CALLER_NONCE

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Arayanın, bir kez gerektirmeyen işlemler için bir kezlik sağlayabileceğini belirtir.

Bu etiket booleandır, dolayısıyla olası değerler true (etiket varsa) ve false (etiket yoksa) şeklindedir.

Bu etiket yalnızca AES anahtarları için kullanılır ve yalnızca CBC, CTR ve GCM blok modlarıyla ilgilidir. Etiket mevcut değilse, uygulamalar Tag::NONCE'un ErrorCode::CALLER_NONCE_PROHIBITED ile başlamasını sağlayan tüm işlemleri reddetmelidir.

Etiket::CREATION_DATETIME

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

1 Ocak 1970'den bu yana anahtarın oluşturulduğu tarih ve saati milisaniye cinsinden belirtir. Bu etiket isteğe bağlıdır ve yalnızca bilgi amaçlıdır.

Etiket::ÖZET

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? Evet

İmzalama ve doğrulama işlemlerini gerçekleştirmek için anahtarla kullanılabilecek özet algoritmalarını belirtir. Bu etiket RSA, ECDSA ve HMAC anahtarlarıyla ilgilidir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

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 ve önceki
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;

Bu etiket tekrarlanabilir. İmzalama ve doğrulama işlemleri için, begin öğesinin additionalParams bağımsız değişkeninde bir özet belirtin. Belirtilen özet anahtarla ilişkili özetlerde değilse, işlem ErrorCode::INCOMPATIBLE_DIGEST ile başarısız olur.

Etiket::EC_CURVE

Versiyon : 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Keymaster 1'de EC anahtarları için kullanılan eğri, belirtilen anahtar boyutundan tahmin ediliyordu. İleriye dönük olarak esnekliği artırmak için Keymaster 2, eğrileri belirtmenin açık bir yolunu sundu. EC anahtar oluşturma istekleri Tag::EC_CURVE , Tag::KEY_SIZE veya her ikisine birden sahip olabilir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

Keymaster 3
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 ve önceki
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

Bir oluşturma isteği yalnızca Tag::KEY_SIZE içeriyorsa uygun NIST eğrisini seçerek Keymaster 1 mantığına geri dönün.

İstek yalnızca Tag::EC_CURVE içeriyorsa belirtilen eğriyi kullanın. Keymaster 3 ve üzeri için eğriler EcCurve tanımlanır. Keymaster 2 ve öncesi için eğriler keymaster_ec_curve_t içinde tanımlanır.

İstek her ikisini de içeriyorsa Tag::EC_CURVE tarafından belirtilen eğriyi kullanın ve belirtilen anahtar boyutunun bu eğri için uygun olduğunu doğrulayın. Değilse, ErrorCode::INVALID_ARGUMENT değerini döndürün.

Etiket::INCLUDE_UNIQUE_ID

Versiyon : 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu etiket, anahtar oluşturma sırasında, oluşturulan anahtara yönelik bir doğrulama sertifikasının Tag::UNIQUE_ID tarafından belirtildiği gibi uygulama kapsamlı ve zaman sınırlı cihaza özgü bir kimlik içermesi gerektiğini belirtmek üzere belirtilir.

Bu etiket booleandır, dolayısıyla olası değerler true (etiket varsa) ve false (etiket yoksa) şeklindedir.

Etiket::KEY_SIZE

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Anahtarın algoritması için normal şekilde ölçerek anahtarın boyutunu bit cinsinden belirtir. Örneğin, RSA anahtarları için Tag::KEY_SIZE genel modülün boyutunu belirtir. AES anahtarları için gizli anahtar materyalinin uzunluğunu belirtir.

Etiket::MAC_LENGTH

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bir MAC veya GCM kimlik doğrulama etiketinin istenen uzunluğunu bit cinsinden sağlar.

Değer, bit cinsinden MAC uzunluğudur. 8'in katıdır ve en az anahtarla ilişkili Tag::MIN_MAC_LENGTH değeri kadar büyüktür.

Etiket::MAX_USES_PER_BOOT

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Sistemin yeniden başlatılması arasında bir anahtarın maksimum kaç kez kullanılabileceğini belirtir. Bu, anahtar kullanımını hız sınırlamaya yönelik başka bir mekanizmadır.

Değer, önyükleme başına kullanımı temsil eden 32 bitlik bir tam sayıdır.

Bu etikete sahip bir anahtar bir işlemde kullanıldığında, başlangıç ​​çağrısı sırasında anahtarla ilişkili bir sayaç artırılmalıdır. Anahtar sayacı bu değeri aştıktan sonra, cihaz yeniden başlatılana kadar anahtarı kullanmaya yönelik sonraki tüm girişimler ErrorCode::MAX_OPS_EXCEEDED ile başarısız olur. Bu, bir Trustlet'in bu etikete sahip anahtarlar için bir kullanım sayacı tablosu tuttuğu anlamına gelir. Keymaster belleği genellikle sınırlı olduğundan, bu tablonun sabit bir maksimum boyutu olabilir ve Keymaster, tablo dolduğunda bu etikete sahip anahtarları kullanmaya çalışan işlemlerde başarısız olabilir. Masanın en az 16 anahtarı barındırması gerekiyor. Tablonun dolu olması nedeniyle bir işlem başarısız olursa, Keymaster ErrorCode::TOO_MANY_OPERATIONS değerini döndürür.

Etiket::MIN_MAC_LENGTH

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu etiket, GCM modunu destekleyen HMAC anahtarları ve AES anahtarları için bu anahtarla istenebilecek veya doğrulanabilecek minimum MAC uzunluğunu belirtir.

Bu değer, bit cinsinden minimum MAC uzunluğudur. 8'in katıdır. HMAC anahtarları için değer en az 64'tür. GCM anahtarları için değer en az 96, en fazla 128'dir.

Etiket::MIN_SECONDS_BETWEEN_OPS

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bir anahtarın kullanılmasına izin verilen işlemler arasında geçen minimum süreyi belirtir. Bu, sınırsız kullanımın kaba kuvvet saldırılarına olanak sağlayabileceği bağlamlarda anahtarların kullanım oranlarını sınırlamak için kullanılabilir.

Değer, izin verilen işlemler arasındaki saniyeleri temsil eden 32 bitlik bir tam sayıdır.

Bu etikete sahip bir tuş bir işlemde kullanıldığında, çağrıyı bitirirken veya iptal ederken bir zamanlayıcı başlatın. Zamanlayıcıdan önce alınan herhangi bir başlama çağrısı, Tag::MIN_SECONDS_BETWEEN_OPS tarafından belirtilen aralığın geçtiğini belirtir ErrorCode::KEY_RATE_LIMIT_EXCEEDED ile başarısız olur. Bu, bir Trustlet'in bu etikete sahip anahtarlar için bir kullanım sayacı tablosu tuttuğu anlamına gelir. Keymaster belleği genellikle sınırlı olduğundan, bu tablonun sabit bir maksimum boyutu olabilir ve Keymaster, tablo dolduğunda bu etikete sahip anahtarları kullanmaya çalışan işlemlerde başarısız olabilir. Tablonun en az 32 kullanımdaki anahtarı barındırması ve anahtar minimum kullanım aralıkları sona erdiğinde tablo yuvalarını agresif bir şekilde yeniden kullanması gerekir. Tablonun dolu olması nedeniyle bir işlem başarısız olursa, Keymaster ErrorCode::TOO_MANY_OPERATIONS değerini döndürür.

Etiket::NO_AUTH_REQUIRED

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu anahtarı kullanmak için kimlik doğrulama gerekmediğini belirtir. Bu etiket, Tag::USER_SECURE_ID ile birbirini dışlar.

Bu etiket booleandır, dolayısıyla olası değerler true (etiket varsa) ve false (etiket yoksa) şeklindedir.

Etiket::NACE

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

AES GCM, CBC veya CTR şifreleme veya şifre çözme için tek seferlik veya Başlatma Vektörü (IV) sağlar veya döndürür. Bu etiket, şifreleme ve şifre çözme işlemleri sırasında başlaması sağlanır. Yalnızca anahtarda Tag::CALLER_NONCE varsa başlaması sağlanır. Sağlanmazsa uygun bir nonce veya IV, Keymaster tarafından rastgele oluşturulacak ve başlangıçtan döndürülecektir.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur. İzin verilen uzunluklar moda bağlıdır: GCM tekrarları 12 bayt uzunluğundadır; CBC ve CTR IV'lerin uzunluğu 16 bayttır.

Etiket::KÖKEN

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Biliniyorsa anahtarın nerede oluşturulduğunu belirtir. Bu etiket, anahtar oluşturma veya içe aktarma sırasında belirtilmeyebilir ve güven uygulaması tarafından temel özelliklere eklenmesi gerekir.

Anahtar Yöneticisi 3

Olası değerler android::hardware::keymaster::v3_0::KeyOrigin tanımlanmıştır:

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 ve öncesi

Olası değerler keymaster_origin_t dosyasında tanımlanmıştır:

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

Değerin tam anlamı yalnızca değere değil, donanım tarafından zorlanan özellikler listesinde mi yoksa yazılım tarafından zorlanan özellikler listesinde mi bulunduğuna bağlıdır.

GENERATED , Keymaster'ın anahtarı oluşturduğunu belirtir. Donanım tarafından zorlanan listedeyse, anahtar güvenli donanımda oluşturulmuştur ve kalıcı olarak donanıma bağlıdır. Yazılım tarafından zorlanan listedeyse anahtar SoftKeymaster'da oluşturulmuştur ve donanıma bağlı değildir.

DERIVED anahtarın Keymaster içinden türetildiğini belirtir. Muhtemelen cihaz dışında mevcuttur.

IMPORTED , anahtarın Keymaster dışında oluşturulduğunu ve Keymaster'a aktarıldığını belirtir. Donanım tarafından zorlanan listedeyse, güvenli donanımın dışında kopyalar mevcut olsa da, kalıcı olarak donanıma bağlanır. Yazılım tarafından uygulananlar listesindeyse, anahtar SoftKeymaster'a aktarılmıştır ve donanıma bağlı değildir.

UNKNOWN yalnızca donanım tarafından zorlanan listede görünmelidir. Anahtarın donanıma bağlı olduğunu gösterir ancak anahtarın orijinal olarak güvenli donanımda mı oluşturulduğu yoksa içe aktarılıp aktarılmadığı bilinmemektedir. Bu yalnızca keymaster1 hizmetlerini taklit etmek için keymaster0 donanımı kullanıldığında meydana gelir.

Etiket::ORIGINATION_EXPIRE_DATETIME

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

İmzalama ve şifreleme amacıyla anahtarın süresinin dolduğu tarih ve saati belirtir. Bu süreden sonra, başlamak için KeyPurpose::SIGN veya KeyPurpose::ENCRYPT sağlanan bir anahtarı kullanma girişimleri ErrorCode::KEY_EXPIRED ile başarısız olur.

Değer, 1 Ocak 1970'ten bu yana milisaniyeyi temsil eden 64 bitlik bir tam sayıdır.

Etiket::OS_PATCHLEVEL

Versiyon : 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu etiket hiçbir zaman anahtar yöneticisi TA'ya gönderilmez, ancak TA tarafından donanım tarafından uygulanan yetkilendirme listesine eklenir.

Etiketin değeri YYYYMM biçiminde bir tam sayıdır; burada YYYY, son güncellemenin dört basamaklı yılı ve MM, son güncellemenin iki basamaklı ayıdır. Örneğin, en son Aralık 2015'te güncellenen bir Android cihazda oluşturulan bir anahtar için değer 201512 olacaktır.

Geçerli yama seviyesinden farklı bir yama seviyesine sahip olan tuşlar kullanılamaz. Böyle bir anahtarı kullanma girişimi, begin , getKeyCharacteristics veya ExportKey'in ErrorCode::KEY_REQUIRES_UPGRADE döndürmesine neden olur. Daha fazla ayrıntı için Sürüm Bağlama'ya bakın.

Etiket::OS_VERSION

Versiyon : 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu etiket hiçbir zaman anahtar yöneticisi TA'ya gönderilmez, ancak TA tarafından donanım tarafından uygulanan yetkilendirme listesine eklenir.

Etiketin değeri MMmmss biçiminde bir tam sayıdır; burada MM ana sürüm numarası, mm ikincil sürüm numarası ve ss alt alt sürüm numarasıdır. Örneğin, Android 4.0.3 sürümünde oluşturulan bir anahtar için değer 040003 olacaktır.

Etiket::DOLGU

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? Evet

Anahtarla kullanılabilecek dolgu modlarını belirtir. Bu etiket RSA ve AES anahtarlarıyla ilgilidir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

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 ve önceki
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 ve PaddingMode::RSA_PKCS1_1_5_ENCRYPT yalnızca RSA şifreleme/şifre çözme anahtarları için kullanılır ve sırasıyla RSA PKCS#1v2 OAEP dolgusunu ve RSA PKCS#1 v1.5 rastgele dolgusunu belirtir. PaddingMode::RSA_PSS ve PaddingMode::RSA_PKCS1_1_5_SIGN yalnızca RSA imzalama/doğrulama anahtarları için kullanılır ve sırasıyla RSA PKCS#1v2 PSS dolgusunu ve RSA PKCS#1 v1.5 deterministik dolgusunu belirtir.

PaddingMode::NONE RSA veya AES anahtarlarıyla kullanılabilir. AES anahtarları için, ECB veya CBC blok moduyla PaddingMode::NONE kullanılıyorsa ve şifrelenecek veya şifresi çözülecek veriler AES blok boyutunun katı uzunlukta değilse, bitirme çağrısı ErrorCode::INVALID_INPUT_LENGTH ile başarısız olur.

PaddingMode::PKCS7 yalnızca AES anahtarlarıyla ve yalnızca ECB ve CBC modlarıyla kullanılabilir.

Bu etiket tekrarlanabilir. Başlamak için çağrıda bir doldurma modu belirtilmelidir. Belirtilen mod anahtar için yetkilendirilmemişse, işlem ErrorCode::INCOMPATIBLE_BLOCK_MODE ile başarısız olur.

Etiket::AMAÇ

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? Evet

Anahtarın kullanılabileceği amaçlar kümesini belirtir.

Olası değerler aşağıdaki numaralandırmayla tanımlanır:

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 ve önceki
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Bu etiket tekrarlanabilir; Bir işlemin tek bir amacı olmasına rağmen anahtarlar birden fazla değerle oluşturulabilir. Bir işlemi başlatmak için begin fonksiyonu çağrıldığında işlemin amacı belirtilir. İşlem için belirtilen amaç anahtar tarafından yetkilendirilmezse, işlem ErrorCode::INCOMPATIBLE_PURPOSE ile başarısız olur.

Etiket::RESET_SINCE_ID_ROTATION

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Son benzersiz kimlik rotasyonundan bu yana cihazın fabrika ayarlarına sıfırlanıp sıfırlanmadığını belirtir. Anahtar doğrulama için kullanılır.

Bu etiket booleandır, dolayısıyla olası değerler true (etiket varsa) ve false (etiket yoksa) şeklindedir.

Etiket::ROLLBACK_RESISTANT

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Anahtarın geri alınmaya karşı dayanıklı olduğunu belirtir; bu, deleteKey veya deleteAllKeys tarafından silindiğinde anahtarın kalıcı olarak silineceğinin ve kullanılamaz olacağının garanti edildiği anlamına gelir. Bu etikete sahip olmayan anahtarların silinmesi ve ardından yedekten geri yüklenmesi mümkündür.

Bu etiket booleandır, dolayısıyla olası değerler true (etiket varsa) ve false (etiket yoksa) şeklindedir.

Etiket::ROOT_OF_TRUST

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Doğrulanmış önyükleme tarafından önyüklenen işletim sistemini (varsa) doğrulamak için kullanılan anahtar olan güvenin kökünü belirtir. Bu etiket, anahtar özelliklerde hiçbir zaman Keymaster'a sağlanmaz veya Keymaster'dan iade edilmez.

Etiket::RSA_PUBLIC_EXPONENT

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bir RSA anahtar çifti için genel üssün değerini belirtir. Bu etiket yalnızca RSA anahtarlarıyla ilgilidir ve tüm RSA anahtarları için gereklidir.

Değer, bir RSA genel üssünün gereksinimlerini karşılayan 64 bitlik işaretsiz bir tamsayıdır. Bu değer asal sayı olmalıdır. Trustlet'ler 2^16+1 değerini destekler ve diğer makul değerleri, özellikle de 3 değerini destekleyebilir. Herhangi bir üs belirtilmemişse veya belirtilen üs desteklenmiyorsa, anahtar oluşturma ErrorCode::INVALID_ARGUMENT ile başarısız olur.

Etiket::UNIQUE_ID

Versiyon : 3, 4

Tekrarlanabilir mi ? HAYIR

Onaylamada benzersiz kimlik sağlamak için kullanılır.

Değer, isteğe bağlı uzunlukta bir bayt dizisi olan bir blobdur.

Etiket::USAGE_EXPIRE_DATETIME

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Doğrulama ve şifre çözme amacıyla anahtarın süresinin dolduğu tarih ve saati belirtir. Bu süreden sonra, başlamak için KeyPurpose::VERIFY veya KeyPurpose::DECRYPT ile bir anahtar kullanma girişimi ErrorCode::KEY_EXPIRED ile başarısız olur.

Değer, 1 Ocak 1970'ten bu yana milisaniyeyi temsil eden 64 bitlik bir tam sayıdır.

Etiket::USER_AUTH_TYPE

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bu anahtarı yetkilendirmek için kullanılabilecek kullanıcı kimlik doğrulayıcılarının türlerini belirtir. Keymaster'ın bu etikete sahip bir anahtarla işlem yapması istendiğinde, bir kimlik doğrulama belirteci alır ve belirtecin authenticator_type alanının etiketteki değerle eşleşmesi gerekir. Örneğin, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 ; burada ntoh , ağ sıralı tam sayıları ana bilgisayar sıralı tam sayılara dönüştüren bir işlevdir ve auth_type_tag_value bu etiketin değeridir.

Değer, numaralandırmadaki değerlerin 32 bitlik tamsayı bit maskesidir:

Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 ve önceki
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;

Etiket::USER_SECURE_ID

Versiyon : 1, 2, 3, 4

Tekrarlanabilir mi ? HAYIR

Bir anahtarın yalnızca belirli bir güvenli kullanıcı kimlik doğrulama durumu altında kullanılabileceğini belirtir. Bu etiket, Tag::NO_AUTH_REQUIRED ile birbirini dışlar.

Değer, anahtarın kullanımına yetki vermek için bir kimlik doğrulama belirtecinde ( Tag::AUTH_TOKEN ile başlamak üzere sağlanır) bulunması gereken kimlik doğrulama politikası durumu değerini belirten 64 bitlik bir tamsayıdır. Kimlik doğrulama belirteci sağlamayan veya eşleşen bir politika durumu değeri olmayan bir kimlik doğrulama belirteci sağlayan, bu etikete sahip bir anahtarla başlayan herhangi bir çağrı başarısız olur.

Bu etiket tekrarlanabilir. Sağlanan değerlerden herhangi biri kimlik doğrulama belirtecindeki herhangi bir politika durumu değeriyle eşleşirse anahtarın kullanım yetkisi verilir. Aksi takdirde işlem ErrorCode::KEY_USER_NOT_AUTHENTICATED ile başarısız olur.

Etiket::VENDOR_PATCHLEVEL

Versiyon : 4

Bu etiket, anahtarın kullanılabileceği satıcı görseli güvenlik yaması düzeyini belirtir. Bu etiket hiçbir zaman anahtar yöneticisi TA'ya gönderilmez, ancak TA tarafından donanım tarafından uygulanan yetkilendirme listesine eklenir. Şu anda çalışan sistem yama düzeyinden farklı bir Tag::VENDOR_PATCHLEVEL değerine sahip bir anahtar kullanma girişimi begin() , getKeyCharacteristics() veya exportKey() işlevinin ErrorCode::KEY_REQUIRES_UPGRADE döndürmesine neden olmalıdır. Ayrıntılar için upgradeKey() e bakın.

Etiketin değeri YYYYAAGG biçiminde bir tamsayıdır; burada YYYY, son güncellemenin dört haneli yılı, MM iki haneli ay ve DD, son güncellemenin iki haneli günüdür. Örneğin, en son 5 Haziran 2018'de güncellenen bir Android cihazda oluşturulan bir anahtar için değer 20180605 olacaktır.

IKeymasterDevice HAL, ro.vendor.build.security_patch sistem özelliğinden geçerli satıcı yama düzeyini okumalı ve HAL ilk yüklendiğinde bunu güvenli ortama teslim etmelidir (mekanizma uygulama tarafından tanımlanır). Güvenli ortam, bir sonraki önyüklemeye kadar başka bir yama düzeyini kabul etmemelidir.

Donanım tarafından zorlanmalıdır.