Keymaster İşlevleri

Bu sayfada, Keymaster'ı uygulayanlara yardımcı olacak ayrıntılar sunulmaktadır Donanım Soyutlama Katmanları (HAL). Bu bölüm, Bu işlevin hangi Keymaster sürümünün mevcut olduğu ve bölümünde varsayılan uygulama açıklanmaktadır. Etiketler için Keymaster Etiketleri sayfasına bakın.

Genel uygulama yönergeleri

Aşağıdaki yönergeler, API'deki tüm işlevler için geçerlidir.

Giriş işaretçisi parametreleri

Sürüm: 1, 2

Belirli bir çağrı için kullanılmayan giriş işaretçisi parametreleri NULL Arayanın yer tutucu sağlaması gerekmez. Örneğin, bazı anahtar türleri ve modları inParams bağımsız değişkeni başlayacak, böylece arayan inParams öğesini NULL olarak ayarlayın veya boş bir parametre sağlayın ayarlandı. Arayanlar ayrıca kullanılmayan parametreler sağlayabilir. Keymaster yöntemlerinde değildir.

Gerekli giriş parametresi NULL ise Keymaster yöntemlerinin değeri ErrorCode::UNEXPECTED_NULL_POINTER

Keymaster 3'ten itibaren herhangi bir işaretçi parametresi yoktur. Tüm parametreler değer veya const başvuruları ile geçirilir.

Çıkış işaretçisi parametreleri

Sürüm: 1, 2

Giriş işaretçisi parametrelerine benzer şekilde, kullanılmayan çıkış işaretçisi parametreleri NULL olabilir. Bir yöntemin çıkışta veri döndürmesi gerekiyorsa parametresinin NULL olduğu tespit edildiyse, bu parametrenin ErrorCode::OUTPUT_PARAMETER_NULL.

Keymaster 3'ten itibaren herhangi bir işaretçi parametresi yoktur. Tüm parametreler değer veya const başvuruları ile geçirilir.

API'nin hatalı kullanımı

Sürüm: 1, 2, 3

Arayanlar anlamsız taleplerde bulunabilir. aptalca ama teknik olarak yanlış değil. Keymaster uygulamaları veya bir teşhis koymanız gerekir. Çok küçük tuşların kullanılması, Alakasız giriş parametrelerinin spesifikasyonu, rastgele URL'lerin veya nonce'ların yeniden kullanımı, bir amaca hizmet eden anahtarların üretilmesidir (böylece, bu tür anahtarların teşhisi koyduk. Gerekli parametrelerin atlanması, Geçersiz zorunlu parametreler ve benzer hataların teşhis edilmesi gerekir.

Bunu yapmak, uygulamaların, çerçevenin ve Android anahtar deposunun sorumluluğundadır. Keymaster modüllerine yapılan çağrıların makul ve yararlı olduğundan emin olun.

Fonksiyonlar

getDonanımÖzellikleri

Sürüm: 3

Yeni getHardwareFeatures yöntemi, müşterilere donanımının önemli özelliklerine değineceğiz. Yöntem bağımsız değişken almaz ve tümü boole değerleri olmak üzere dört değer döndürür:

  • Anahtarlar şurada depolanırsa isSecure true olur: gibi güvenli bir donanıma (TEE vb.) sahip olabilir ve asla
  • supportsEllipticCurve, şu durumda true olur: donanım, NIST eğrileriyle (P-224, P-256, P-384 ve P-521) içerir.
  • supportsSymmetricCryptography özelliği true durumda donanım, AES ve HMAC dahil simetrik kriptografiyi destekliyorsa.
  • supportsAttestation, şu durumda true olur: Donanım, Keymaster ortak anahtar onayı sertifikalarının oluşturulmasını destekler, bir anahtarla imzalandığından emin olun.

Bu yöntemin döndürebileceği hata kodları yalnızca ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED veya hata kodlarından biri güvenli donanımla iletişim kurulamadı. 

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

yapılandır

Sürüm: 2

Bu işlev Keymaster 2'de kullanıma sunulmuş ve Keymaster'da kullanımdan kaldırılmıştır 3. Bu bilgiler sistem özellikleri dosyalarında ve üretici uygulamaları başlangıç sırasında bu dosyaları okur.

Keymaster'ı yapılandırır. Bu yöntem, cihaz açıldıktan sonra bir kez çağrılır yardımcı olabilir. Bu analiz ekibi, KM_TAG_OS_VERSION ve KM_TAG_OS_PATCHLEVEL - anahtar yöneticisidir. Bu yöntem çağrılana kadar diğer tüm yöntemler KM_ERROR_KEYMASTER_NOT_CONFIGURED Bu işlemin sağladığı değerler yöntemi, keymaster tarafından başlatma başına yalnızca bir kez kabul edilir. Sonraki aramaları KM_ERROR_OK değerini döndürür, ancak hiçbir şey yapmaz.

Keymaster uygulaması güvenli donanımda ve işletim sistemi sürümündeyse ve sağlanan yama düzeyi değerleri, güvenlik sunucusu için sağlanan değerlerle eşleşmiyor donanım yüklememesini sağlayabilir (veya bootloader değer sağlamadıysa) bu yöntem KM_ERROR_INVALID_ARGUMENT değerini ve diğer tüm yöntemleri KM_ERROR_KEYMASTER_NOT_CONFIGURED değerini döndürmeye devam eder.

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

AdRngEntropi

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de add_rng_entropy olarak kullanıma sunuldu ve Keymaster 3'te yeniden adlandırıldı.

Keymaster 1 uygulaması tarafından kullanılan havuza arayan tarafından sağlanan entropi ekler anahtar, IV vb. için rastgele sayılar oluşturma amacıyla kullanılır.

Keymaster uygulamalarının, sağlanan mevcut havuzlarına eklemesi gereken bir donanım rastgele sayı oluşturucudan dahili olarak oluşturulmuş entropi. Karıştırma, tam kontrole sahip bir saldırganın addRngEntropy tarafından sağlanan bitlerden veya donanım tarafından oluşturulan bitlerden her ikisi için olmasa da, bitlerin tahmin edilmesinde göz ardı edilebilir bir avantaja sahip değildir. türetilir.

Entropiyi tahmin etmeye çalışan Keymaster uygulamaları dahili havuzda, Arkadaş Bitkiler Projesi’nin addRngEntropy entropi içermiyor. Keymaster uygulamaları, 2'den fazla verilirse ErrorCode::INVALID_INPUT_LENGTH değerini döndürür Tek bir aramada KiB cinsinden veri miktarı.

oluşturmaAnahtarı

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de generate_key olarak kullanıma sunuldu ve Keymaster 3'te yeniden adlandırıldı.

İlişkili yetkilendirmeleri belirten yeni bir şifreleme anahtarı oluşturur Bunlar kalıcı olarak anahtara bağlıdır. Keymaster uygulamaları, bir anahtarın, yetkilendirmelerle tutarlı olmayan bir şekilde kullanılması sırasında belirtilmiş olmalıdır. Güvenli güvenli donanımın yükümlülüğü, donanımın gerektirdiği şekilde anahtarla ilişkili uygulanamayan yetkilendirmelerin Böylece yapılacak her çağrının getKeyCharacteristics orijinal değeri döndürür. Ayrıca, bir proje yöneticisinin generateKey, yetkilendirmeleri donanım ve yazılım tarafından zorunlu kılınan listelerdir. Görüntüleyin getKeyCharacteristics bölümüne göz atın.

generateKey için sağlanan parametreler anahtarın türüne bağlıdır devreye giriyor. Bu bölümde, şu URL’ler için gerekli ve isteğe bağlı etiketler özetlenmiştir: her bir anahtar türünü görebilirsiniz. Etiket: ALGORİTMA her zaman gereklidir.

RSA anahtarları

RSA anahtarı oluşturmak için aşağıdaki parametreler gereklidir.

  • Etiket::KEY_SIZE genel modülün boyutunu bit cinsinden belirtir. Atlanırsa yöntem ErrorCode::UNSUPPORTED_KEY_SIZE değerini döndürür. 1024, 2048, 3072 ve 4096 değerleri desteklenir. Önerilen değerler tüm anahtar boyutları 8'in katlarıdır.
  • Etiket::RSA_PUBLIC_EXPONENT RSA herkese açık üs değerini belirtir. Atlanırsa yöntem ErrorCode::INVALID_ARGUMENT değerini döndürür. Desteklenen değerler: 3 ve 65537. Önerilen değerler: 2^64'e kadar olan tüm asal değerler.

Aşağıdaki parametreler RSA anahtarı oluşturmak için gerekli değildir, ancak olmadan bir RSA anahtarı oluşturmak, kullanılamayan bir anahtara neden olur. Ancak Bu parametreler aşağıdaki durumlarda generateKey işlevi hata döndürmez: atlanır.

  • Tag::PURPOSE amaçlar. RSA anahtarları için tüm amaçların desteklenmesi gerekir. herhangi bir kombinasyonda.
  • Etiket::DIGEST yeni anahtarla kullanılabilecek özet algoritmalarına yer verir. Uygulamalar tüm özet algoritmalarını desteklemeyen uygulamaların anahtar oluşturma sürecini kabul etmesi gerekir desteklenmeyen özetler içeren isteklerdir. Desteklenmeyen özetler "yazılım tarafından zorunlu kılınan" listesi oluşturun. Bunun nedeni, anahtarın diğer özetlerle kullanılabilmesidir. ne olduğunu öğreneceğiz. Ardından, işlemi gerçekleştirmek için donanım çağrılır Digest::NONE ile birlikte.
  • Tag::PADDING, dolgu modlarını kullanabilirsiniz. Uygulamalar tüm özet algoritmalarını desteklemeyen PaddingMode::RSA_PSS ve PaddingMode::RSA_OAEP inç desteklenmeyen özellikler varsa bunların yazılımla zorunlu kılınan temel özellikleri belirtildiğinden emin olun.

ECDSA anahtarları

Yalnızca Etiket::KEY_SIZE bir ECDSA anahtarı oluşturmak için gereklidir. EC grubunu seçmek için kullanılır. Desteklenen değerler 224, 256, 384 ve 521'dir. Bunlar, Sırasıyla NIST p-224, p-256, p-384 ve p521 eğrileri.

Etiket::DIGEST yararlı bir ECDSA anahtarı için de gereklidir. ancak üretim için gerekli değildir.

AES anahtarları

Yalnızca Etiket::KEY_SIZE AES anahtarı oluşturmak için gereklidir. Atlanırsa yöntem ErrorCode::UNSUPPORTED_KEY_SIZE Desteklenen değerler: 128 ve 256. İsteğe bağlı olarak 192 bit AES anahtarları desteklenir.

Aşağıdaki parametreler özellikle AES anahtarları için geçerlidir oluşturmak için gereklidir:

  • Tag::BLOCK_MODE, yeni anahtar kullanılabilir.
  • Tag::PADDING, kullanılır. Bu, yalnızca ECB ve CBC modları için geçerlidir.

GCM engelleme modu belirtildiyse Etiket::MIN_MAC_LENGTH. Atlanırsa yöntem ErrorCode::MISSING_MIN_MAC_LENGTH değerini döndürür. Etiketin değeri 8'in katıdır ve 96 ile 128 arasındadır.

HMAC anahtarları

HMAC anahtarı oluşturmak için aşağıdaki parametreler gereklidir:

  • Etiket::KEY_SIZE anahtar boyutunu bit cinsinden belirtir. 64'ten küçük değerler ve 8'in katları olmayan değerler desteklenmez. Tümü 64 ile 512 arasında 8'in katları desteklenir. Daha büyük değerler desteklenir.
  • Etiket::MIN_MAC_LENGTH Bu anahtarla oluşturulabilen veya doğrulanabilen MAC'ler. Değer katları 8 ve en az 64'tür.
  • Etiket::DIGEST anahtara ait özet algoritmasını belirtir. Tam olarak bir özet belirtildi, aksi takdirde döndürülür ErrorCode::UNSUPPORTED_DIGEST Özet desteklenmiyorsa güvenilir sertifikanız üzerinden, ErrorCode::UNSUPPORTED_DIGEST

Temel özellikleri

Özellikler bağımsız değişkeni NULL değilse generateKey şunu döndürür: özellikleri, yeni oluşturulan anahtarın özelliklerini donanım ve yazılım tarafından zorunlu kılınan listelerdir. Görüntüleyin Bir açıklama için getKeyCharacteristics hangi özelliklerin hangi listede yer aldığı. Döndürülen özellikler anahtar oluşturma için belirtilen tüm parametreleri içermelidir. Etiket::APPLICATION_ID ve Etiket::APPLICATION_DATA. Bu etiketler anahtar parametrelere eklenmişse ve bu özelliklerin değerlerinin bulunamaması için inceleyerek başlayın. Ancak kriptografik olarak bağlıdırlar. bunu anahtar blob'a ekleyerek, kullanım başarısız olur. Aynı şekilde, Etiket::ROOT_OF_TRUST kriptografik olarak anahtara bağlıdır, ancak anahtar oluşturma veya içe aktarma işlemi yapılır ve hiçbir zaman döndürülmez.

Sağlanan etiketlere ek olarak, Etiket::ortak değerini ekler. KeyOrigin::GENERATED değerine sahip olduğunuzda, Anahtar geri almaya karşı dirençliyse

Etiket::ROLLBACK_RESISTANT.

Geri alma direnci

Geri alma direnci, bir anahtarın silindiği zaman deleteKey veya deleteAllKeys ise, güvenli donanım bir daha kullanılamaz. Geri alma direnci olmadan uygulamalar genellikle oluşturulan veya içe aktarılan anahtar materyalini, arayan kişiye anahtar blobu, şifrelenmiş ve kimliği doğrulanmış formdur. Anahtar deposu, anahtar blobunu sildiğinde anahtar ancak daha önce anahtar materyalini ele geçirmiş olan bir saldırgan gitti bu verileri cihaza geri yükleyebilir.

Güvenli donanım, silindiğini garanti ediyorsa geri almaya karşı dayanıklıdır. anahtarları daha sonra geri yüklenemez. Bu genellikle ek anahtarlar depolanıp saldırgan tarafından değiştirilemeyen, güvenilir bir konumda bulunan meta verilerdir. Şu tarihte: bu işlem için kullanılan mekanizma genellikle Tekrar Oynatma Korumalı Hafıza'dır Bloklar (BGBGB). Çünkü oluşturulabilecek anahtarların sayısı sınırsız ve geri alma direnci için kullanılan güvenilir depolama alanı sınırlı olabilir geri alma direnci söz konusu olsa bile bu yöntemin yeni anahtar için sağlanamıyor. Böyle bir durumda, Etiket::ROLLBACK_RESISTANT temel özelliklere eklenmemelidir.

getKeyCharacteristics

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de get_key_characteristics ve Keymaster 3'te yeniden adlandırıldı.

Sağlanan anahtarla ilişkili parametreleri ve yetkilendirmeleri döndürür. donanımla ve yazılımla zorlanan olmak üzere iki gruba ayrılır. Açıklama burada generateKey ve importKey tarafından döndürülen temel özellik listeleri için aynı şekilde geçerlidir.

Anahtar oluşturma sırasında Tag::APPLICATION_ID sağlanmışsa veya içe aktarıldığında, aynı değer bu yöntemi clientId bağımsız değişkenine ekleyin. Aksi halde, yöntemi ErrorCode::INVALID_KEY_BLOB değerini döndürür. Aynı şekilde, Tag::APPLICATION_DATA oluşturma sırasında sağlanmışsa veya içe aktarıldığında, aynı değer bu yöntemi appData bağımsız değişkenine ekleyin.

Bu yöntemin döndürdüğü özellikler, modelin ve belirtilen anahtarın kullanımı.

Belirli bir etiketin donanımla veya yazılımla zorlanan listesine göre, etiketin anlamı tam anlamıyla güvenli bir donanımdır ve donanımla zorunlu kılınmıştır. Aksi takdirde emin olun. Aşağıda, doğru ayırması olan belirli etiketlerin listesi net olmayabilir:

  • Etiket::ALGORİTMA, Etiket::KEY_SIZE, ve Etiket::RSA_PUBLIC_EXPONENT anahtarın öz özellikleridir. Güvenliği donanımla korunan herhangi bir anahtarda bu etiketler donanım tarafından zorlananlar listesinde yer alır.
  • Etiket::DIGEST değerleri ve güvenli donanım tarafından desteklenen cihazlar, bir donanım destekli liste değildir. Desteklenmeyen özetler, yazılım destekli uygulamalar listesinde yer alır.
  • Etiket::PADDING değerleri genellikle donanım destekli cihazlar listesine girer. yazılım tarafından belirli bir dolgu modunun uygulanması gerekme olasılığı. Bu durumda, cihazlar yazılımla zorunlu kılınan uygulamalar listesine girer. Böyle bir olasılık özet algoritmaları ile PSS veya OAEP dolgusuna izin veren RSA anahtarları için ortaya çıkar desteklenmeyen bazı yazılımlar olabilir.
  • Etiket::USER_SECURE_ID ve Etiket::USER_AUTH_TYPE yalnızca kullanıcı kimlik doğrulaması donanım tarafından zorunlu kılındığında donanımla zorunlu kılınır. Alıcı: Keymaster güven seti ve ilgili kimlik doğrulama anahtarı, güvenilir olması ve hem güvenli hem de gizli bir HMAC anahtarını paylaşması gerekir. kimlik doğrulama jetonlarını doğrulayacaktır. Bkz. Kimlik doğrulama sayfasına göz atın.
  • Etiket::ACTIVE_DATETIME, Etiket::hakikat_ verince_EXPIRE_DATETIME, ve Etiket::USAGE_EXPIRE_DATETIME etiketleri ve doğrulanabilir nitelikte bir duvar saatine erişmelerine gerek yoktur. En güvenli donanım sadece güvenli olmayan işletim sisteminin sağladığı saat bilgilerine erişebilir. Etiketlerin yazılımla zorunlu kılındığı anlamına gelir.
  • Etiket::origin donanıma bağlı anahtarlar için her zaman donanım listesindedir. Dijital pazarlamanın listesi, daha üst katmanların bir anahtarın donanım destekli olduğunu belirleme yöntemidir.

içe aktarmaAnahtarı

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de import_key olarak kullanıma sunuldu ve Keymaster 3'te yeniden adlandırıldı.

Anahtar materyalini Keymaster donanımına içe aktarır. Anahtar tanım parametreleri ve çıkış özellikleri, generateKey için olduğu gibi işlenir. şu istisnalarla birlikte:

  • Etiket::KEY_SIZE ve Etiket::RSA_PUBLIC_EXPONENT (yalnızca RSA anahtarları için) gerekli değildir. Sağlanmamışsa güvenilir sertifika, sağlanan anahtar materyalinden değerleri çıkartır ve temel özelliklere uygun etiketler ve değerler sunmaktır. Parametreler anahtar materyalle karşılaştırarak doğrular. olursa yöntem ErrorCode::IMPORT_PARAMETER_MISMATCH değerini döndürür.
  • Döndürülen Etiket::GU, KeyOrigin::IMPORTED ile aynı değere sahiptir.

disaaktarmaanahtarı

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de export_key olarak kullanıma sunuldu ve Keymaster 3'te yeniden adlandırıldı.

Keymaster RSA veya EC anahtar çiftinden ortak anahtar dışa aktarır.

Tag::APPLICATION_ID, anahtar oluşturma sırasında sağlandıysa veya içe aktarma işlemi yapılırsa bu yönteme aynı değer clientId bağımsız değişken. Aksi takdirde, yöntem ErrorCode::INVALID_KEY_BLOB Aynı şekilde Tag::APPLICATION_DATA. oluşturma veya içe aktarma sırasında sağlanmışsa bu yöntemi appData bağımsız değişkenine ekleyin.

silKey

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de delete_key olarak kullanıma sunuldu ve Keymaster 3'te yeniden adlandırıldı.

Sağlanan anahtarı siler. Bu yöntem isteğe bağlıdır ve yalnızca Keymaster modülleri tarafından uygulanır.

deleteAllKeys

Sürüm: 1, 2, 3

Bu işlev Keymaster 1'de delete_all_keys olarak kullanıma sunuldu ve Keymaster 3'te yeniden adlandırıldı.

Tüm anahtarları siler. Bu yöntem isteğe bağlıdır ve yalnızca uygulanır geri alma direnci sağlayan Keymaster modülleri tarafından oluşturulur.

kaldırma

Sürüm: 3

destroyAttestationIds() yöntemi, şu işlemler için kullanılır: yenini devre dışı bırak (isteğe bağlıdır, ancak kesinlikle önerilir) Kimlik onayı özelliğini kullanabilirsiniz. TEE, kimlik onayını kalıcı olarak belirleyemiyorsa çağrıldıktan sonra devre dışı bırakılırsa kimlik onayı, Bu durumda, bu yöntem hiçbir şey yapmaz ve ErrorCode::UNIMPLEMENTED değerini döndürür. Kimlik onayı destekleniyorsa bu yöntemin uygulanması ve kalıcı olarak devre dışı bırakılması gerekir kimlik doğrulama girişimlerinin tümü. Yöntem, herhangi bir sayıda kez. Kimlik onayı kalıcı olarak devre dışı bırakılmışsa yöntem hiçbir şey yapmaz ve ErrorCode::OK değerini döndürür.

Bu yöntemin döndürebileceği hata kodları yalnızca şunlardır: ErrorCode::UNIMPLEMENTED (kimlik onayı desteklenmiyorsa): ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED veya güvenli cihazla iletişim kurulamadığını gösteren hata kodlarından birini donanım.

başla

Sürüm: 1, 2, 3

Belirtilen anahtar için şifreleme işlemini başlatır. amacı, belirtilen parametrelerle (uygun olduğu şekilde) belirtir ve update ve finish ile birlikte kullanılan işlem herkese açık kullanıcı adı. İşlem tutma yeri "meydan okuma" olarak da kullanılır kimlik doğrulaması yapılmış işlemlerde ve bunun için işlemleri,challenge kimlik doğrulama jetonu.

Keymaster uygulaması, en az 16 eşzamanlı anlamına gelir. Anahtar deposu 15 adede kadar veri kullanır, bir tanesi şifre için kullanılabilir bahsedeceğim. Anahtar Deposu'nda devam eden 15 işlem olduğunda (begin, çağrıldı, ancak finish veya abort henüz çağrılmadı çağrıldığında) ve ayın 16'sını başlatmak için bir istek alır. sayısını azaltmak için son kullanılan işlemde abort başlatmak için begin çağrısından önce etkin işlemleri 14'e Yeni istenen işlem.

Etiket::APPLICATION_ID veya Etiket::APPLICATION_DATA belirtildi anahtar oluşturma veya içe aktarma işlemi sırasında, begin çağrılarına inParams bağımsız değişkeninde orijinal olarak belirtilen değerlere sahip etiketler .

Yetkilendirme yaptırımı

Bu yöntem sırasında aşağıdaki anahtar yetkilendirmeleri güven seti, uygulama tarafından "donanım tarafından zorunlu kılınan" özellikleri ve işlemin ortak anahtar işlemi değilse. Ortak anahtar işlemleri (yani KeyPurpose::ENCRYPT ve KeyPurpose::VERIFY), anahtarların kimlik doğrulaması gerçekleştirilse bile başarılı olabilmesine karşılanmadığından emin olun.

  • Etiket::AMAÇ: Amaç begin() çağrısında belirtilen amaçlardan biriyle eşleşmelidir anahtar yetkilendirmelerinde (istenen işlem bir ortak anahtar olmadığı sürece) işlemidir. Belirtilen amaç ve işlem eşleşmiyorsa bir ortak anahtar işlemi söz konusuysa begin, ErrorCode::UNSUPPORTED_PURPOSE. Ortak anahtar işlemleri asimetrik şifreleme veya doğrulama işlemlerine izin verir.
  • Etiket::ACTIVE_DATETIME Yalnızca güvenilir bir UTC saat kaynağı varsa zorunlu kılınabilir. Öğe geçerli tarih ve saat etiket değerinden önceyse yöntem, ErrorCode::KEY_NOT_YET_VALID
  • Etiket::SOURCEATION_EXPIRE_DATETIME Yalnızca güvenilir bir UTC saat kaynağı varsa zorunlu kılınabilir. Öğe geçerli tarih ve saat, etiketin değerinden daha sonradır ve amacı KeyPurpose::ENCRYPT veya KeyPurpose::SIGN, yöntem ErrorCode::KEY_EXPIRED değerini döndürür.
  • Etiket::USAGE_EXPIRE_DATETIME Yalnızca güvenilir bir UTC saat kaynağı varsa zorunlu kılınabilir. Öğe geçerli tarih ve saat, etiketin değerinden daha sonradır ve amacı KeyPurpose::DECRYPT veya KeyPurpose::VERIFY, yöntem ErrorCode::KEY_EXPIRED değerini döndürür.
  • Etiket::MIN_SECONDS_BETWEEN_OPS güvenilir bir göreli zamanlayıcıyla karşılaştırıldığında, gerekir. Son kullanım zamanı artı etiket değeri, geçerli zamandan kısaysa yöntem ErrorCode::KEY_RATE_LIMIT_EXCEEDED değerini döndürür. Bkz. etiket açıklaması ziyaret edin.
  • Etiket::MAX_USES_PER_BOOT anahtarın kullanımlarını izleyen güvenli bir sayaçla karşılaştırılır. ilk çalışma zamanı. Önceki kullanımların sayısı etiket değerini aşarsa yöntemi ErrorCode::KEY_MAX_OPS_EXCEEDED değerini döndürür.
  • Etiket::USER_SECURE_ID bu yöntem yalnızca anahtarda Etiket::AUTH_TIMEOUT. Anahtarda her ikisi de varsa bu yöntem, geçerli bir Etiket::AUTH_TOKEN inParams. Yetkilendirme jetonunun geçerli olması için aşağıdakilerin tümü şu değerin doğru olması gerekir:

    Bu koşullardan herhangi biri karşılanmazsa yöntem ErrorCode::KEY_USER_NOT_AUTHENTICATED

  • Etiket::CALLER_NONCE çağrının bir tek seferlik rastgele sayı veya başlatma vektörü (IV) belirtmesine olanak tanır. Anahtar bu etikete sahip değil, ancak arayan kullanıcı tarafından sağlandı Tag::NONCE kodunu ekleyerek ErrorCode::CALLER_NONCE_PROHIBITED döndürüldü.
  • Etiket::BOOTLOADER_ONLY anahtarı yalnızca bootloader'ın kullanabileceğini belirtir. Bu yöntem Bootloader'ın yürütme işlemini bitirdikten sonra yalnızca bootloader'ı içeren bir anahtarla çağrıldığını ErrorCode::INVALID_KEY_BLOB değerini döndürür.

RSA anahtarları

Tüm RSA anahtar işlemleri, inParams ürününde tam olarak bir dolgu modu belirtir. Belirtilmezse veya birden fazla kez belirtilirse yöntem, ErrorCode::UNSUPPORTED_PADDING_MODE

RSA imzalama ve doğrulama işlemlerinin yanı sıra RSA şifrelemesi de bir özete ihtiyaç duyar. ve şifre çözme işlemlerini destekler. Bu durumlarda arayan, inParams içinde tam olarak bir özet belirtir. Belirtilmemişse veya belirtilmişse birden çok kez işlev gördüğünde, yöntem ErrorCode::UNSUPPORTED_DIGEST değerini döndürür.

Özel anahtar işlemleri (KeyPurpose::DECYPT ve KeyPurpose::SIGN) için özet ve dolgu yetkilendirilmesi gerekir. Bu da anahtar yetkilendirmelerinin belirtilen değerleri içermesi gerekir. Aksi takdirde yöntem, ErrorCode::INCOMPATIBLE_DIGEST. veya ErrorCode::INCOMPATIBLE_PADDING uygun şekilde. Ortak anahtar işlemleri (KeyPurpose::ENCRYPT ve KeyPurpose::VERIFY) şununla birlikte izin verilir: veya dolgu içerebilir.

PaddingMode::NONE hariç tüm RSA dolgu modları yalnızca belirli amaçlar için geçerli olur. Özellikle, PaddingMode::RSA_PKCS1_1_5_SIGN PaddingMode::RSA_PSS yalnızca imzalama ve doğrulama desteklerken PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT ve PaddingMode::RSA_OAEP yalnızca şifreleme ve şifre çözmeyi destekler. Yöntem, ErrorCode::UNSUPPORTED_PADDING_MODE belirtilen mod, belirtilen amacı desteklemiyor.

Dolgu modları ve özetler arasında bazı önemli etkileşimler vardır:

  • PaddingMode::NONE, "ham" olduğunu gösterir RSA işlemi gerçekleştirildi. İmzalıyor veya doğrulanıyorsa Digest::NONE özet için belirtilir. Doldurulmayan şifreleme için özet gerekmez veya şifre çözme.
  • PaddingMode::RSA_PKCS1_1_5_SIGN dolgusu bir özet gerektiriyor. İlgili içeriği oluşturmak için kullanılan özet Digest::NONE olabilir; bu durumda Keymaster uygulanması uygun bir PKCS#1 v1.5 imza yapısı oluşturamaz. DigestInfo yapısını ekleyemez. Bunun yerine, 0x00 || 0x01 || PS || 0x00 || M oluşturur; burada M sağlanan mesajdır ve PS, dolgu dizesidir. RSA anahtarının boyutu en az 11 bayt daha büyük olmalıdır, aksi takdirde yöntem ErrorCode::INVALID_INPUT_LENGTH
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT dolgusu özet gerektirmez.
  • PaddingMode::RSA_PSS dolgusu bir özet gerektiriyor ve bu özet Digest::NONE. Digest::NONE belirtilirse yöntemi ErrorCode::INCOMPATIBLE_DIGEST değerini döndürür. Ayrıca, RSA anahtarının boyutunun çıkıştan en az 2 + D bayt daha büyük olması gerekir özetin bayt cinsinden boyutudur. Burada D özetin boyutudur. Aksi halde yöntem ErrorCode::INCOMPATIBLE_DIGEST değerini döndürür. Tuz boyutu D.
  • PaddingMode::RSA_OAEP dolgusu bir özet gerektiriyor ve bu özet Digest::NONE. Digest::NONE belirtilirse yöntemi ErrorCode::INCOMPATIBLE_DIGEST değerini döndürür.

EC anahtarları

EC anahtar işlemleri, inParams içinde tam olarak bir dolgu modu belirtir. Belirtilmezse veya birden fazla kez belirtilirse yöntem ErrorCode::UNSUPPORTED_PADDING_MODE değerini döndürür.

Özel anahtar işlemleri (KeyPurpose::SIGN) için yetkilendirme gerekiyor yani temel yetkilendirmelerin devreye girmesini belirtilen değerleri içermesi gerekir. Değilse geri dönün ErrorCode::INCOMPATIBLE_DIGEST Ortak anahtar işlemleri (KeyPurpose::VERIFY) yetkisiz özet veya dolgu ile kullanılmasına izin verilir.

AES anahtarları

AES anahtar işlemleri, tam olarak bir engelleme modu ve bir dolgu modu belirtir inParams içinde. Değerlerden biri belirtilmemişse veya daha fazla belirtilmişse bir defadan fazla, ErrorCode::UNSUPPORTED_BLOCK_MODE veya ErrorCode::UNSUPPORTED_PADDING_MODE. Belirtilen modların anahtar tarafından yetkilendirilmişse yöntem, ErrorCode::INCOMPATIBLE_BLOCK_MODE veya ErrorCode::INCOMPATIBLE_PADDING_MODE.

Engelleme modu BlockMode::GCM ise inParams Tag::MAC_LENGTH belirtir ve belirtilen değer, 128'den büyük olmayan 8'in katıdır veya daha küçük bir değer içinde Tag::MIN_MAC_LENGTH anahtar yetkilendirmeleridir. 128'den büyük veya şunun katı olmayan MAC uzunlukları için: 8, ErrorCode::UNSUPPORTED_MAC_LENGTH değerini döndürün. Daha az değerler için anahtarın minimum uzunluğundan fazlaysa ErrorCode::INVALID_MAC_LENGTH değerini döndürün.

Engelleme modu BlockMode::GCM veya BlockMode::CTR ise belirtilen dolgu modu PaddingMode::NONE olmalıdır. BlockMode::ECB veya BlockMode::CBC için mod şu olabilir: PaddingMode::NONE veya PaddingMode::PKCS7. Dolgu modu bu koşulları karşılamıyorsa ErrorCode::INCOMPATIBLE_PADDING_MODE değerini döndürün.

Engelleme modu BlockMode::CBC, BlockMode::CTR ise ya da BlockMode::GCM ise bir başlatma vektörü veya tek seferlik rastgele sayı gerekir. Çoğu durumda, arayanlar damardan damar veya tek seferlik rastgele sayı vermemelidir. Böyle bir durumda, Keymaster uygulaması rastgele bir IV veya tek seferlik rastgele sayı oluşturur ve bunu outParams konumunda Tag::NONCE. CBC ve TO IV'ler 16 bayttır. GCM nonce'lar 12 bayttır. Anahtar yetkilendirmeler şunları içerir: Etiket::CALLER_NONCE, arayan kişi, Etiket::NONCE inParams içinde. Tek seferlik rastgele sayı sağlanırsa Etiket::CALLER_NONCE yetkili değil, ErrorCode::CALLER_NONCE_PROHIBITED değerini döndürün. Tek seferlik rastgele sayı sağlanmazsa Etiket::CALLER_NONCE yetkilendirildi, rastgele bir IV/nonce oluşturun.

HMAC anahtarları

HMAC anahtar işlemleri, inParams bölgesinde Tag::MAC_LENGTH öğesini belirtir. Belirtilen değer, şundan büyük olmayan 8'in bir katı olmalıdır: özet uzunluğu veya Tag::MIN_MAC_LENGTH değerinden küçük anahtar yetkilendirmeleri girmelisiniz. Özet uzunluğundan daha uzun MAC uzunlukları veya 8'in katları olmayanlar için ErrorCode::UNSUPPORTED_MAC_LENGTH değerini döndürün. Anahtarın minimum uzunluğundan kısa değerler için şunu döndürün: ErrorCode::INVALID_MAC_LENGTH

güncelleme

Sürüm: 1, 2, 3

begin ile başlayan devam eden bir işlemde işlenecek veriler sağlar. İşlem, operationHandle parametresiyle belirtilir.

Tampon işleme konusunda daha fazla esneklik sağlamak için bu yöntemin uygulanması daha az veri tüketme seçeneğine sahip olmalıdır. Arayan döngüden sorumludur ve sonraki çağrılarda diğer verileri iletmektir. İlgili içeriği oluşturmak için kullanılan tüketilen giriş miktarı, inputConsumed parametresinde döndürülür. işlemi artık kabul edemez; Sıfırdan fazla bayt sağlanırsa ve arayanlar tarafından bir hata olarak kabul edilir ve işlemi iptal eder.

Uygulamalar ayrıca, anahtar/değer çiftlerinin bir sonucu olarak güncelleyin. Bu yalnızca şifreleme ve şifre çözme işlemleriyle ilgilidir, çünkü İmzalama ve doğrulama işlemleri tamamlanana kadar veri döndürmez. Verileri arabelleğe almak yerine mümkün olduğunca erken geri gönderin.

Hata işleme

Bu yöntem ErrorCode::OK dışında bir hata kodu döndürürse işlem iptal edilir ve işlem işleyici geçersiz kılınır. Herhangi biri herkese açık kullanıcı adları için finish veya iptal edin ErrorCode::INVALID_OPERATION_HANDLE değerini döndürür.

Yetkilendirme yaptırımı

Anahtar yetkilendirmesinin zorunlu kılınması esas olarak başlangıçta gerçekleştirilir. Bunun tek istisnası, anahtarda şunlardır:

Bu durumda, anahtar işlem başına yetkilendirme gerektirir ve yöntemi bir Etiket:AUTH_TOKEN alır. inParams bağımsız değişkenine ekleyin. HMAC, jetonun geçerli olduğunu ve jetonun bulunduğunu doğrular eşleşen güvenli bir kullanıcı kimliği, anahtarın Etiket::USER_AUTH_TYPE, ve isteyebilirsiniz. Bu koşullar karşılanmazsa geri dön ErrorCode::KEY_USER_NOT_AUTHENTICATED

Arayan, güncelleme işlemini yapmak ve her çağrıya bittir. Uygulama sırasında jetonun istenirse yalnızca bir kez doğrulanması yeterlidir.

RSA anahtarları

Digest::NONE ile yapılan imzalama ve doğrulama işlemleri için, bu yöntem tüm blokun tek bir girişte imzalanmasını veya doğrulanmasını kabul eder güncelleyin. Engellemenin yalnızca bir kısmını kaplamayabilir. Ancak, arayan verileri birden çok güncellemede sağlamayı seçerse bu yöntem kabul eder. Arayan kişi imzalamak için kullanılabilecekten daha fazla veri sağlarsa ( RSA anahtar boyutunu aşıyorsa ErrorCode::INVALID_INPUT_LENGTH değerini döndürün.

ECDSA anahtarları

Digest::NONE ile yapılan imzalama ve doğrulama işlemleri için, bu yöntem tüm blokun tek bir girişte imzalanmasını veya doğrulanmasını kabul eder güncelleyin. Bu yöntem, engellemenin yalnızca bir kısmını kullanmayabilir.

Bununla birlikte, arayan kişi verileri birden fazla güncellemede sağlamayı seçerse bu yöntemi kabul eder. Arayan kişi imzalamak için daha fazla veri sağlıyorsa bu işlemden sonra veriler sessizce kesilir. (Bu, benzer RSA işlemlerinde sağlanan aşırı verilerin işlenmesine neden olur. Bunun nedeni eski istemcilerle uyumludur.)

AES anahtarları

AES GCM modu "ilişkili kimlik doğrulama verilerini" destekler, sağlayan Etiket::ASSOCIATED_DATA etiketi inParams bağımsız değişkeninde. İlişkili veriler, tekrarlanan aramalarda sağlanabilir ( veriler tek bir blokta gönderilemeyecek kadar büyük) ancak her zaman verilerden önce geliyor şifresini çözemez. Bir güncelleme araması, ilişkili her iki veriyi de alabilir ve verilerin şifrelenmesi/şifresini çözmek için kullanılır, ancak sonraki güncellemeler dışı verilerdir. Arayan, aramadan sonra bir güncelleme aramasıyla ilişkilendirilmiş veriler sağlıyorsa şifrelenecek/şifresini çözülecek verileri içeren URL'ler için ErrorCode::INVALID_TAG hatası döndürür.

GCM şifrelemesi için etiket, şifrelenmiş metne şu şekilde eklenir: finish olarak ayarlayın. Şifre çözme işlemi sırasında, Sonuncuya kadar sağlanan verilerin Tag::MAC_LENGTH baytı güncelleme çağrısı, etikettir. update bunun son çağrı olup olmadığını bilemez. Etiket uzunluğu hariç tüm verileri işler ve olası etiket verilerini arabelleğe alır bitti.

tamamla

Sürüm: 1, 2, 3

Başla ile başlayan devam eden bir işlemi bitirir. Google tarafından sağlanan, henüz işlenmemiş tüm verileri güncellemeler var.

Bu yöntem, işlemde çağrılan son yöntem olduğundan döndürüldüğünden emin olun.

İster başarılı bir şekilde tamamlanır ister bir hata döndürürse bu yöntem, işlemi, dolayısıyla sağlanan işlem herkese açık kullanıcı adını geçersiz kılar. Herhangi biri herkese açık kullanıcı adını bu yöntemle veya update ya da abort, ErrorCode::INVALID_OPERATION_HANDLE değerini döndürür.

İmzalama işlemleri, çıkış olarak imzayı döndürür. Doğrulama işlemleri signature parametresindeki imzayı kabul eder ve herhangi bir çıkış döndürmez.

Yetkilendirme yaptırımı

Anahtar yetkilendirmesinin zorunlu kılınması temel olarak şu ülkede gerçekleştirilir: begin. Bunun tek istisnası, anahtarda şunlardır:

Bu durumda, anahtar işlem başına yetkilendirme gerektirir ve yöntemi bir Etiket:AUTH_TOKEN alır. inParams bağımsız değişkenine ekleyin. HMAC, jetonun geçerlidir ve eşleşen bir güvenli kullanıcı kimliği içerir, anahtarın Etiket::USER_AUTH_TYPE ve mevcut işlemin isteyebilirsiniz. Bu koşullar karşılanmazsa geri dön ErrorCode::KEY_USER_NOT_AUTHENTICATED

Arayan, her çağrıya kimlik doğrulama jetonunu güncelleyin ve tamamlayın. Uygulama sırasında jetonun istenirse yalnızca bir kez doğrulanması yeterlidir.

RSA anahtarları

Dolgu moduna bağlı olarak bazı ek koşullar:

  • PaddingMode::NONE Doldurulmamış imzalama ve şifreleme işlemleri için sağlanan veriler anahtardan kısaysa, veriler sıfır ile doldurulur. soluna girin. Veriler anahtarla aynı uzunluktaysa ancak sayısal olarak daha büyük, ErrorCode::INVALID_ARGUMENT değerini döndürün. Örneğin, doğrulama ve şifre çözme işlemlerinde olduğu gibi, veriler de tam olarak seçeceğiz. Aksi takdirde ErrorCode::INVALID_INPUT_LENGTH. değerini döndürün
  • PaddingMode::RSA_PSS PSS dolgulu imza işlemleri için PSS takviyesi, ileti özetinin boyutudur ve rastgele oluşturulur. Tag::DIGEST ile belirtilen özet başlangıçtaki inputParams işlevinde PSS özeti olarak kullanılır algoritması olarak kullanılmaktadır.
  • PaddingMode::RSA_OAEP Özet Etiket::DIGEST kategorisinde Başlangıçtaki inputParams OAEP olarak kullanılır özet algoritmasını destekler ve MGF1 özet algoritması olarak SHA1 kullanılır.

ECDSA anahtarları

Doldurulmamış imzalama veya doğrulama için sağlanan veriler çok uzunsa bu verileri kısaltın. somut olarak ortaya koyar.

AES anahtarları

Engelleme moduna bağlı olarak bazı ek koşullar:

  • BlockMode::ECB veya BlockMode::CBC. Dolgu PaddingMode::NONE ise ve veri uzunluğu, AES blok boyutunun katı değildir, ErrorCode::INVALID_INPUT_LENGTH. Dolgu PaddingMode::PKCS7, verileri PKCS#7 spesifikasyonuna göre doldurun. PKCS#7'nin ek bir dolgu bloğu eklenmesini önerdiğini unutmayın veriler blok uzunluğunun katıysa.
  • BlockMode::GCM Şifreleme sırasında, işlemeden sonra tümü düz metinler, etiketi hesaplama (Etiket::MAC_LENGTH bayt) ve döndürülen şifrelenmiş metne ekleyin. Şifre çözme sırasında, son Etiket::MAC_LENGTH bayt olarak ifade eder. Etiket doğrulaması başarısız olursa ErrorCode::VERIFICATION_FAILED

bırak yapma

Sürüm: 1, 2, 3

Devam eden işlemi iptal eder. İptal etme çağrısından sonra geri dönün Şunun için ErrorCode::INVALID_OPERATION_HANDLE: sağlanan işlem herkese açık kullanıcı adını update ile bitebilir veya iptal edebilirsiniz.

get_supported_algorithms

Sürüm: 1

Keymaster donanımı tarafından desteklenen algoritmaların listesini döndürür hakkında bilgi edindiniz. Bir yazılım uygulaması boş bir liste döndürür; hibrit komutu yalnızca şuna ait algoritmaları içeren bir liste döndürür: donanım tarafından desteklendiğini unutmayın.

Keymaster 1 uygulamaları RSA, EC, AES ve HMAC'yi destekler.

get_supported_block_modes

Sürüm: 1

Keymaster donanımı tarafından desteklenen AES blok modlarının listesini döndürür en iyi uygulamaları izleyeceksiniz.

Engelleme şifresi olmayan RSA, EC ve HMAC için yöntem, boş listeye ekleyin. Geçersiz amaçlar, yöntemin iade ErrorCode::INVALID_PURPOSE.

Keymaster 1 uygulamaları AES için ECB, CBC, TO ve GCM'yi destekler şifreleme ve şifre çözme.

get_supported_fill_modes

Sürüm: 1

Keymaster donanımı tarafından desteklenen dolgu modlarının listesini döndürür en iyi uygulamaları izleyeceksiniz.

HMAC ve EC'de dolgu kavramı olmadığından yöntem boş bir liste döndürür kabul edersiniz. Geçersiz amaçlar, yöntemin döndürülmesine neden olmalıdır ErrorCode::INVALID_PURPOSE

RSA için Keymaster 1 uygulamaları şunları destekler:

  • Dolgusuz şifreleme, şifre çözme, imzalama ve doğrulama. Pedsiz için ve imzalaması gerektiğini unutmayın. İleti, herkese açık modülün uygulamanın sol üst kısmı sıfırlarla tamamlanmalıdır. Doldurulmamış şifre çözme ve giriş uzunluğu, herkese açık modül boyutuyla eşleşmelidir.
  • PKCS#1 v1.5 şifreleme ve imzalama dolgu modları
  • Minimum tuz uzunluğu 20 olan PSS
  • OAEP

ECB ve CBC modlarında AES için Keymaster 1 uygulamaları dolgu ve PKCS#7-dolgu. TO ve GCM modları yalnızca dolguyu desteklemez.

get_supported_digests

Sürüm: 1

Keymaster donanımı tarafından desteklenen özet modlarının listesini döndürür en iyi uygulamaları izleyeceksiniz.

AES modları, özetleme işlemini desteklemez veya gerektirmez. Bu nedenle, yöntem boş bir bu listeye eklenir.

Keymaster 1 uygulamaları, tanımlanan özet. Uygulamalar SHA-256 sağlar ve MD5, SHA1, SHA-224, SHA-256, SHA384 ve SHA512 (tanımlanmış özetlerin tamamı).

get_supported_import_formats

Sürüm: 1

Keymaster donanımı tarafından desteklenen içe aktarma biçimlerinin listesini döndürür uygulanmasıdır.

Keymaster 1 uygulamaları, PKCS#8 biçimini destekler (şifre olmadan koruması) ve RAW içe aktarmayı destekler AES ve HMAC anahtar materyali.

get_supported_export_formats

Sürüm: 1

Keymaster donanımı tarafından desteklenen dışa aktarma biçimlerinin listesini döndürür uygulanmasıdır.

Keymaster1 uygulamaları, RSA'yı dışa aktarmak için X.509 biçimini destekler ve EC ortak anahtarları. Özel anahtarların veya asimetrik anahtarların dışa aktarılması desteklenmez.

Tarihi işlevler

Anahtar Yöneticisi 0

Aşağıdaki işlevler orijinal Keymaster 0 tanımına aittir. Onlar Keymaster 1 struct keymaster1_device_t içinde mevcuttu. Ancak Keymaster'da 1.0 uygulanmadı ve işlev işaretçileri NULL değerine ayarlandı.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Anahtar Yöneticisi 1

Aşağıdaki işlevler Keymaster 1 tanımına aittir, ancak yukarıda listelenen Keymaster 0 işlevleriyle birlikte Keymaster 2'de kaldırılır.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Anahtar Yöneticisi 2

Aşağıdaki işlevler Keymaster 2 tanımına aittir, ancak yukarıda listelenen Keymaster 1 işlevleriyle birlikte Keymaster 3'te kaldırılır.

  • configure