Bu sayfa, Keymaster HAL'lerinin uygulayıcılarına yardımcı olacak ayrıntılar sağlar. 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 belirtilenler dışında, aşağıdaki etiketlerin tümü, anahtar özellikleri belirtmek için anahtar oluşturma sırasında kullanılır.
Keymaster 4 için etiketler, Keymaster 3 için 3.0/types.hal ve Keymaster 4 için 4.0/types.hal gibi platform/hardware/interfaces/keymaster/ keymaster-version /types.hal
içinde tanımlanır. Keymaster 2 ve altı için, etiketler platform/hardware/libhardware/include/hardware/keymaster_defs.h
içinde tanımlanır.
İşlevler için Keymaster İşlevleri sayfasına bakın.
Etiket::ACTIVE_DATETIME
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Anahtarın etkin hale geldiği tarih ve saati belirtir. Bu zamandan önce, anahtarı kullanma girişimleri ErrorCode::KEY_NOT_YET_VALID
ile başarısız oluyor.
Değer, 1 Ocak 1970'den bu yana milisaniyeyi temsil eden 64 bitlik bir tamsayıdır.
Etiket::ALGORİTMA
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Anahtarın birlikte kullanıldığı şifreleme algoritmasını belirtir.
Olası değerler aşağıdaki numaralandırma ile tanımlanır:
Keymaster 3enum class Algorithm : uint32_t { RSA = 1, EC = 3, AES = 32, HMAC = 128, };Keymaster 2 ve önceki sürümler
typedef enum { KM_ALGORITHM_RSA = 1, KM_ALGORITHM_EC = 3, KM_ALGORITHM_AES = 32, KM_ALGORITHM_HMAC = 128, } keymaster_algorithm_t;
Etiket::ALL_APPLICATIONS
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Gelecekte kullanılmak üzere rezerve edilmiştir.
Etiket::ALLOW_WHILE_ON_BODY
Sürüm : 2, 3, 4
Tekrarlanabilir mi? Numara
Bu etiket yalnızca vücut sensörlerine sahip Android Wear cihazları için geçerlidir. Bu noktada, herhangi bir TEE'nin bir vücut üstü sensöre güvenli erişim sağlaması veya vücut üstü sensörlerin çok güvenli olması beklenmemektedir, dolayısıyla bunun tamamen yazılım tarafından uygulanan bir özellik olması beklenmektedir.
Etiket::ALL_USERS
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Gelecekte kullanılmak üzere rezerve edilmiştir.
Etiket::APPLICATION_DATA
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
createKey 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
parametresine aynı değeri sağlaması gerekir ve başlama çağrılarının inParams
kümesinin bir parçası olarak bu etiketi ve 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, yani tüm güvenli dünya sırlarına erişimi olan ancak etiket içeriğine erişimi olmayan bir düşmanın, etiketi kaba zorlamadan anahtarın şifresini çözmesi mümkün olmamalıdır. Uygulamaların yeterince yüksek entropi içeriği belirterek önleyebileceği içerik.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::UYGULAMA_Kimliği
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
createKey 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 başlama çağrılarının inParams
kümesinin bir parçası olarak bu etiketi ve 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, yani tüm güvenli dünya sırlarına erişebilen ancak etiket içeriğine erişimi olmayan bir düşman anahtarın şifresini çözemez (etiket içeriğini kaba zorlamadan) ).
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ASSOCIATED_DATA
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
AES-GCM şifreleme veya şifre çözme için "ilişkili veriler" sağlar. Bu etiket, şifrelenmemiş/şifresi çözülmemiş, ancak GCM etiketinin hesaplanmasında kullanılan verileri güncellemek ve belirtmek için sağlanmıştır.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_APPLICATION_ID
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Birinin bir anahtar tasdik başlattığı olası uygulamalar kümesini belirlemek için kullanılır.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_CHALLENGE
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Onaylamada meydan okuma sağlamak için kullanılır.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_BRAND
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
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 onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_DEVICE
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Android'de Build.DEVICE
tarafından döndürüldüğü şekliyle cihazın cihaz adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_IMEI
Sürüm : 3, 4
Tekrarlanabilir mi? Evet
Cihazdaki tüm telsizler için IMEI'leri sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_ÜRETİCİ
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Android'de Build.MANUFACTURER
tarafından döndürüldüğü şekliyle cihazın üretici adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_MEID
Sürüm : 3, 4
Tekrarlanabilir mi? Evet
Cihazdaki tüm telsizler için MEID'leri sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanacaktır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_MODEL
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Android'de Build.MODEL
tarafından döndürüldüğü şekliyle cihazın model adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_PRODUCT
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Android'de Build.PRODUCT
tarafından döndürüldüğü şekliyle cihazın ürün adını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::ATTESTATION_ID_SERIAL
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Cihazın seri numarasını sağlar. Bu alan yalnızca cihazın tanımlayıcılarının onaylanması istenirken ayarlanır.
Cihaz kimlik doğrulamasını desteklemiyorsa (veya destroyAttestationIds()
daha önce çağrıldıysa ve cihaz artık kimliklerini doğrulayamazsa), bu etiketi içeren herhangi bir anahtar doğrulama isteği ErrorCode::CANNOT_ATTEST_IDS
ile başarısız olur.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::AUTH_TIMEOUT
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Kimlik doğrulamadan sonra anahtarın kullanım için yetkilendirildiği süreyi saniye cinsinden belirtir. Etiket::USER_SECURE_ID varsa 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 bkz. başla ).
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, anahtarın kullanılabileceği başarılı bir kimlik doğrulamasından sonraki saniye cinsinden süreyi belirten 32 bitlik bir tamsayıdır.
Etiket::AUTH_TOKEN
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Bunu gerektiren bir anahtar işlemi için kullanıcı kimlik doğrulamasını kanıtlamak için başlamak , güncellemek veya bitirmek için bir kimlik doğrulama belirteci sağlar (anahtarın Tag::USER_SECURE_ID'si vardır).
Değer, hw_auth_token_t yapısını içeren bir hw_auth_token_t
.
Etiket::BLOB_USAGE_REQUIREMENTS
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Oluşturulan anahtarın kullanılması için gerekli sistem ortamı koşullarını belirtir.
Olası değerler aşağıdaki numaralandırma ile tanımlanır:
Keymaster 3enum class KeyBlobUsageRequirements : uint32_t { STANDALONE = 0, REQUIRES_FILE_SYSTEM = 1, };Keymaster 2 ve önceki sürümler
typedef enum { KM_BLOB_STANDALONE = 0, KM_BLOB_REQUIRES_FILE_SYSTEM = 1, } keymaster_key_blob_usage_requirements_t;
Bu etiket, anahtarın belirtilen koşulda kullanılabilir olmasını gerektirmek için anahtar oluşturma sırasında belirtilebilir. createKey ve getKeyCharacteristics anahtar özellikleriyle döndürülmesi gerekir. Çağıran, KeyBlobUsageRequirements::STANDALONE
değeriyle Tag::BLOB_USAGE_REQUIREMENTS
belirtirse, güvenilen dosya sistemi desteği olmadan kullanılabilecek bir anahtar blobu döndürür. Bu, diskin şifresini çözmek için bir Keymaster anahtarı kullanılana kadar dosya sisteminin kullanılamayacağı, şifreli diskleri olan cihazlar için kritik öneme sahiptir.
Etiket::BLOCK_MODE
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Evet
Anahtarın kullanılabileceği blok şifreleme modlarını belirtir. Bu etiket yalnızca AES anahtarlarıyla ilgilidir.
Olası değerler aşağıdaki numaralandırma ile tanımlanır:
Keymaster 3enum class BlockMode : uint32_t { ECB = 1, CBC = 2, CTR = 3, GCM = 32, };tutucu5 Keymaster 2 ve önceki sürümler
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 additionalParams
start argümanında 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
Sürüm : 4
Tag::BOOT_PATCHLEVEL, anahtarın kullanılabileceği önyükleme görüntüsü (çekirdek) güvenlik düzeltme eki düzeyini belirtir. Bu etiket hiçbir zaman keymaster TA'ya gönderilmez, ancak TA tarafından donanım tarafından zorunlu kılınan yetkilendirme listesine eklenir. Şu anda çalışan sistem patchlevel değerinden farklı bir Tag::BOOT_PATCHLEVEL
değerine sahip bir anahtar kullanma girişimi, start( begin()
, getKeyCharacteristics()
veya exportKey()
ErrorCode::KEY_REQUIRES_UPGRADE
döndürmesine neden olur. Ayrıntılar için upgradeKey()
'e bakın.
Etiketin değeri, YYYYMMDD biçiminde bir tamsayıdır; burada YYYY, son güncellemenin dört basamaklı yılıdır, AA iki basamaklı aydır ve DD, son güncellemenin iki basamaklı 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 olur. Gün bilinmiyorsa, 00 değiştirilebilir.
Her önyükleme sırasında, önyükleyici, güvenli ortama önyükleme görüntüsünün yama düzeyini sağlamalıdır (mekanizma uygulama tanımlıdır).
Donanım zorlamalı olmalıdır.
Etiket::BOOTLOADER_ONLY
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Anahtarı yalnızca önyükleyicinin kullanabileceğini belirtir.
Bu etiket booleandır, bu nedenle olası değerler true (etiket varsa) ve false (etiket yoksa).
Android sisteminden Tag::BOOTLOADER_ONLY
ile bir anahtar kullanma girişimi ErrorCode::INVALID_KEY_BLOB
ile başarısız olur.
Etiket::CALLER_NONCE
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Çağıranın, gerekli olmayan işlemler için bir nonce sağlayabileceğini belirtir.
Bu etiket booleandır, bu nedenle olası değerler true (etiket varsa) ve false (etiket yoksa).
Bu etiket yalnızca AES anahtarları için kullanılır ve yalnızca CBC, CTR ve GCM blok modları için geçerlidir. Etiket mevcut değilse, uygulamaların ErrorCode::CALLER_NONCE_PROHIBITED
ile başlaması için Tag::NONCE sağlayan herhangi bir işlemi reddetmesi gerekir.
Etiket::CREATION_DATETIME
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
1 Ocak 1970'den bu yana milisaniye cinsinden anahtarın oluşturulduğu tarih ve saati belirtir. Bu etiket isteğe bağlıdır ve yalnızca bilgi amaçlıdır.
Etiket::ÖZET
Sürüm : 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ırma ile tanımlanır:
Keymaster 3enum 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 sürümler
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, start öğesinin ekParams bağımsız değişkeninde bir additionalParams
belirtin. Belirtilen özet, anahtarla ilişkili özetlerde değilse, işlem ErrorCode::INCOMPATIBLE_DIGEST
ile başarısız olur.
Etiket::EC_CURVE
Sürüm : 2, 3, 4
Tekrarlanabilir mi? Numara
Keymaster 1'de, EC anahtarları için kullanılan eğri, belirtilen anahtar boyutundan tahmin edildi. İleriye dönük esnekliği artırmak için Keymaster 2, eğrileri belirlemenin açık bir yolunu sundu. EC anahtar oluşturma istekleri Tag::EC_CURVE
, Tag::KEY_SIZE
veya her ikisini birden içerebilir.
Olası değerler aşağıdaki numaralandırma ile tanımlanır:
Keymaster 3enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };Keymaster 2 ve önceki sürümler
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 sonraki sürümleri için eğriler EcCurve
içinde tanımlanır. Keymaster 2 ve önceki sürümler 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
.
Etiket::INCLUDE_UNIQUE_ID
Sürüm : 2, 3, 4
Tekrarlanabilir mi? Numara
Bu etiket, oluşturulan anahtar için bir onay sertifikasının, Tag::UNIQUE_ID tarafından belirtildiği gibi, uygulama kapsamındaki ve zamana bağlı benzersiz bir cihaz kimliği içermesi gerektiğini belirtmek için anahtar oluşturma sırasında belirtilir.
Bu etiket booleandır, bu nedenle olası değerler true (etiket varsa) ve false (etiket yoksa).
Etiket::KEY_SIZE
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Anahtarın algoritması için normal şekilde ölçülen 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 malzemesinin uzunluğunu belirtir.
Etiket::MAC_LENGTH
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Bir MAC veya GCM kimlik doğrulama etiketinin istenen uzunluğunu bit olarak sağlar.
Değer, bit cinsinden MAC uzunluğudur. 8'in katıdır ve en azından anahtarla ilişkili Tag::MIN_MAC_LENGTH değeri kadar büyüktür.
Etiket::MAX_USES_PER_BOOT
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Sistem yeniden başlatmaları arasında bir anahtarın kullanılabileceği maksimum sayıyı belirtir. Bu, anahtar kullanımını oran sınırlamak için başka bir mekanizmadır.
Değer, önyükleme başına kullanımları temsil eden 32 bitlik bir tamsayıdır.
Bir işlemde bu etikete sahip bir tuş kullanıldığında, arama başlatma sırasında tuşla ilişkili bir sayaç artırılmalıdır. Anahtar sayacı bu değeri aştıktan sonra, sonraki tüm anahtarı kullanma girişimleri, cihaz yeniden başlatılana kadar ErrorCode::MAX_OPS_EXCEEDED
ile başarısız olur. Bu, bir güven uygulamasının 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 etiketle anahtarları kullanmayı deneyen işlemlerde başarısız olabilir. Tablonun en az 16 anahtarı barındırması gerekir. Tablo dolu olduğu için bir işlem başarısız olursa, ErrorCode::TOO_MANY_OPERATIONS
döndürür.
Etiket::MIN_MAC_LENGTH
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Bu etiket, GCM modunu destekleyen HMAC anahtarları ve AES anahtarları için bu anahtarla talep edilebilecek 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 ve 128'den fazla değildir.
Etiket::MIN_SECONDS_BETWEEN_OPS
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Bir anahtar kullanılarak 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ını mümkün kılabileceğ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 tamsayıdır.
Bir işlemde bu etikete sahip bir tuş kullanıldığında, aramayı bitirme veya iptal etme sırasında bir zamanlayıcı başlatın. Zamanlayıcıdan önce alınan herhangi bir başlatma çağrısı, Tag::MIN_SECONDS_BETWEEN_OPS
tarafından belirtilen aralığın geçtiğini belirtir ve ErrorCode::KEY_RATE_LIMIT_EXCEEDED
ile başarısız olur. Bu, bir güven uygulamasının 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 etiketle anahtarları kullanmayı deneyen 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. Tablo dolu olduğu için bir işlem başarısız olursa, ErrorCode::TOO_MANY_OPERATIONS
döndürür.
Etiket::NO_AUTH_REQUIRED
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
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, bu nedenle olası değerler true (etiket varsa) ve false (etiket yoksa).
Etiket::YOK
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
AES GCM, CBC veya CTR şifreleme veya şifre çözme için nonce 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şlamak için sağlanır. Yalnızca anahtarın Tag::CALLER_NONCE varsa başlaması sağlanır. Sağlanmazsa, Keymaster tarafından rastgele bir nonce veya IV oluşturulur ve baştan döndürülür.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur. İzin verilen uzunluklar moda bağlıdır: GCM nonces uzunluğu 12 bayttır; CBC ve CTR IV'ler 16 bayt uzunluğundadır.
Etiket::KÖKEN
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Biliniyorsa, anahtarın nerede oluşturulduğunu belirtir. Bu etiket, anahtar oluşturma veya içe aktarma sırasında belirtilemez ve güvenilen kişi tarafından anahtar özelliklere eklenmelidir.
anahtar yöneticisi 3 Olası değerler android::hardware::keymaster::v3_0::KeyOrigin
içinde tanımlanmıştır:
enum class KeyOrigin : uint32_t { GENERATED = 0, DERIVED = 1, IMPORTED = 2, UNKNOWN = 3, };Keymaster 2 ve önceki sürümler
Olası değerler keymaster_origin_t
içinde 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 zorunlu kılınan veya yazılım tarafından zorunlu kılınan özellikler listesinde bulunup bulunmadığına da bağlıdır.
GENERATED
, Keymaster'ın anahtarı oluşturduğunu gösterir. Donanım tarafından zorunlu kılınan listedeyse, anahtar güvenli donanımda oluşturulmuştur ve kalıcı olarak donanıma bağlıdır. Yazılım tarafından zorunlu kılınan listedeyse, anahtar SoftKeymaster'da oluşturulmuştur ve donanıma bağlı değildir.
DERIVED
, anahtarın Keymaster içinde türetildiğini gösterir. Muhtemelen cihaz dışında var.
IMPORTED
, anahtarın Keymaster dışında oluşturulduğunu ve Keymaster'a aktarıldığını gösterir. Donanım tarafından zorunlu kılınan listedeyse, güvenli donanımın dışında kopyalar bulunabilse de, kalıcı olarak donanıma bağlıdır. Yazılım zorlar listesindeyse, anahtar SoftKeymaster'a aktarılmıştır ve donanıma bağlı değildir.
UNKNOWN
yalnızca donanım tarafından zorunlu kılınan listede görünmelidir. Anahtarın donanıma bağlı olduğunu belirtir, ancak anahtarın orijinal olarak güvenli donanımda mı yoksa içe aktarılarak mı oluşturulduğu bilinmiyor. Bu, yalnızca keymaster1 hizmetlerine öykünmek için keymaster0 donanımı kullanıldığında oluşur.
Etiket::ORIGINATION_EXPIRE_DATETIME
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Anahtarın imzalama ve şifreleme amaçlarıyla süresinin dolacağı tarih ve saati belirtir. Bu süreden sonra, başlamak için sağlanan KeyPurpose::SIGN veya KeyPurpose::ENCRYPT ile bir anahtar kullanma girişimi ErrorCode::KEY_EXPIRED
ile başarısız olur.
Değer, 1 Ocak 1970'den bu yana milisaniyeyi temsil eden 64 bitlik bir tamsayıdır.
Etiket::OS_PATCHLEVEL
Sürüm : 2, 3, 4
Tekrarlanabilir mi? Numara
Bu etiket hiçbir zaman keymaster TA'ya gönderilmez, ancak TA tarafından donanım tarafından zorunlu kılınan yetkilendirme listesine eklenir.
Etiketin değeri, YYYY'nin son güncellemenin dört basamaklı yılı ve AA'nın son güncellemenin iki basamaklı ayı olduğu YYYYMM biçiminde bir tamsayı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 düzeyinden farklı bir yama düzeyine sahip anahtarlar kullanılamaz. Böyle bir anahtar kullanma girişimi, start, 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
Sürüm : 2, 3, 4
Tekrarlanabilir mi? Numara
Bu etiket hiçbir zaman keymaster TA'ya gönderilmez, ancak TA tarafından donanım tarafından zorunlu kılınan yetkilendirme listesine eklenir.
Etiketin değeri, MMmmss biçiminde bir tamsayıdır; burada MM ana sürüm numarası, mm alt 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::DOLGULAMA
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Evet
Tuşla kullanılabilecek dolgu modlarını belirtir. Bu etiket, RSA ve AES anahtarlarıyla ilgilidir.
Olası değerler aşağıdaki numaralandırma ile tanımlanır:
Keymaster 3enum 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, };tutucu13 Keymaster 2 ve önceki sürümler
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 modu ile PaddingMode::NONE
kullanılıyorsa ve şifrelenecek veya şifresi çözülecek veriler AES blok boyutunun katları değilse, bitirme çağrısı ErrorCode::INVALID_INPUT_LENGTH
ile başarısız olur.
PaddingMode::PKCS7
yalnızca AES tuşlarıyla ve yalnızca ECB ve CBC modlarıyla kullanılabilir.
Bu etiket tekrarlanabilir. Başlamak için çağrıda bir dolgu modu belirtilmelidir. Belirtilen mod anahtar için yetkilendirilmemişse, işlem ErrorCode::INCOMPATIBLE_BLOCK_MODE
ile başarısız olur.
Etiket::AMAÇ
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Evet
Anahtarın kullanılabileceği amaçlar kümesini belirtir.
Olası değerler aşağıdaki numaralandırma ile tanımlanır:
Keymaster 3enum class KeyPurpose : uint32_t { ENCRYPT = 0, DECRYPT = 1, SIGN = 2, VERIFY = 3, DERIVE_KEY = 4, // since 3.0 WRAP_KEY = 5, // since 3.0 };tutucu15 Keymaster 2 ve önceki sürümler
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 çok değerle oluşturulabilir. Bir işlemi başlatmak için start fonksiyonu çağrıldığında, işlemin amacı belirtilir. İşlem için belirtilen amaç anahtar tarafından yetkilendirilmemişse, işlem ErrorCode::INCOMPATIBLE_PURPOSE
ile başarısız olur.
Etiket::RESET_SINCE_ID_ROTATION
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Son benzersiz kimlik dönüşünden bu yana cihazın fabrika ayarlarına sıfırlanıp sıfırlanmadığını belirtir. Anahtar onayı için kullanılır.
Bu etiket booleandır, bu nedenle olası değerler true (etiket varsa) ve false (etiket yoksa).
Etiket::ROLLBACK_RESISTANT
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Anahtarın geri alınmaya karşı dayanıklı olduğunu belirtir, yani deleteKey veya deleteAllKeys tarafından silindiğinde, anahtarın kalıcı olarak silineceği ve kullanılamaz olacağı garanti edilir. Bu etikete sahip olmayan anahtarların silinmesi ve ardından yedekten geri yüklenmesi mümkündür.
Bu etiket booleandır, bu nedenle olası değerler true (etiket varsa) ve false (etiket yoksa).
Etiket::ROOT_OF_TRUST
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Önyüklenen işletim sistemini (varsa) doğrulamak için doğrulanmış önyükleme tarafından kullanılan anahtar olan güven kökünü belirtir. Bu etiket, anahtar özelliklerde hiçbir zaman Keymaster'a sağlanmaz veya bundan döndürülmez.
Etiket::RSA_PUBLIC_EXPONENT
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
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 bir asal sayı olmalıdır. Güven grupları 2^16+1 değerini destekler ve diğer makul değerleri, özellikle 3 değerini destekleyebilir. Hiçbir üs belirtilmemişse veya belirtilen üs desteklenmiyorsa, anahtar oluşturma ErrorCode::INVALID_ARGUMENT
ile başarısız olur.
Etiket::UNIQUE_ID
Sürüm : 3, 4
Tekrarlanabilir mi? Numara
Onayda benzersiz kimlik sağlamak için kullanılır.
Değer, rasgele uzunlukta bir bayt dizisi olan bir blob'dur.
Etiket::USAGE_EXPIRE_DATETIME
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Doğrulama ve şifre çözme amacıyla anahtarın süresinin dolacağı tarih ve saati belirtir. Bu süreden sonra, başlamak için sağlanan 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'den bu yana milisaniyeyi temsil eden 64 bitlik bir tamsayıdır.
Etiket::USER_AUTH_TYPE
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
Bu anahtarı yetkilendirmek için kullanılabilecek kullanıcı kimlik doğrulayıcı türlerini belirtir. Keymaster'ın bu etiketle bir anahtarla işlem yapması istendiğinde, bir kimlik doğrulama jetonu alır ve jetonun 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 bir tamsayı bit maskesidir:
Keymaster 3enum class HardwareAuthenticatorType : uint32_t { NONE = 0u, // 0 PASSWORD = 1 << 0, FINGERPRINT = 1 << 1, ANY = UINT32_MAX, };tutucu17 Keymaster 2 ve önceki sürümler
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
Sürüm : 1, 2, 3, 4
Tekrarlanabilir mi? Numara
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 şartıyla) bulunması gereken kimlik doğrulama politikası durum değerini belirten 64 bitlik bir tamsayıdır. Kimlik doğrulama belirteci sağlamayan veya eşleşen bir ilke durumu değeri olmadan bir kimlik doğrulama belirteci sağlayan bu etikete sahip bir anahtarla başlamak için yapılan herhangi bir çağrı başarısız olur.
Bu etiket tekrarlanabilir. Sağlanan değerlerden herhangi biri, kimlik doğrulama belirtecindeki herhangi bir ilke durumu değeriyle eşleşirse, anahtar kullanım için yetkilendirilir. Aksi takdirde işlem ErrorCode::KEY_USER_NOT_AUTHENTICATED
ile başarısız olur.
Etiket::VENDOR_PATCHLEVEL
Sürüm : 4
Bu etiket, anahtarın kullanılabileceği satıcı resmi güvenlik düzeltme eki düzeyini belirtir. Bu etiket hiçbir zaman keymaster TA'ya gönderilmez, ancak TA tarafından donanım tarafından zorunlu kılınan yetkilendirme listesine eklenir. Şu anda çalışan sistem yama düzeyinden farklı bir Tag::VENDOR_PATCHLEVEL
değerine sahip bir anahtar kullanma girişimi, start( begin()
, getKeyCharacteristics()
veya exportKey()
ErrorCode::KEY_REQUIRES_UPGRADE
döndürmesine neden olmalıdır. Ayrıntılar için upgradeKey()
'e bakın.
Etiketin değeri, YYYYMMDD biçiminde bir tamsayıdır; burada YYYY, son güncellemenin dört basamaklı yılıdır, AA iki basamaklı aydır ve DD, son güncellemenin iki basamaklı 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 olur.
IKeymasterDevice HAL, ro.vendor.build.security_patch
sistem özelliğinden geçerli satıcı yama düzeyini okumalı ve HAL ilk yüklendiğinde (mekanizma uygulama tanımlıdır) güvenli ortama teslim etmelidir. Güvenli ortam, bir sonraki önyüklemeye kadar başka bir yama düzeyini kabul etmemelidir.
Donanım zorlamalı olmalıdır.