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 3enum 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 3enum 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 3enum 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 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
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 3enum 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ğlıdı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 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, };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 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 };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
Cihazın son benzersiz kimlik rotasyonundan bu yana 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 3enum 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.