Anahtar Yöneticisi İşlevleri

Bu sayfa, Keymaster Donanım Soyutlama Katmanlarının (HAL'ler) uygulayıcılarına yardımcı olacak ayrıntılar sağlar. API'deki her işlevi ve bu işlevin hangi Keymaster sürümünde mevcut olduğunu kapsar ve varsayılan uygulamayı açıklar. 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 olabilir. Arayanın yer tutucu sağlaması gerekmez. Örneğin, bazı anahtar türleri ve kipleri inParams bağımsız değişkeninden hiçbir değeri başlangıç ​​için kullanmayabilir, bu nedenle çağıran inParams NULL olarak ayarlayabilir veya boş bir parametre seti sağlayabilir. Arayanlar ayrıca kullanılmayan parametreler sağlayabilir ve Keymaster yöntemleri hata vermemelidir.

Gerekli bir giriş parametresi NULL ise, Keymaster yöntemleri ErrorCode::UNEXPECTED_NULL_POINTER döndürmelidir.

Keymaster 3'ten başlayarak, işaretçi parametresi yoktur. Tüm parametreler değer veya const referanslarıyla iletilir.

Çı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 NULL olduğu bulunan bir çıktı parametresinde veri döndürmesi gerekiyorsa, ErrorCode::OUTPUT_PARAMETER_NULL .

Keymaster 3'ten başlayarak, işaretçi parametresi yoktur. Tüm parametreler değer veya const referanslarıyla iletilir.

API kötüye kullanımı

Sürüm : 1, 2, 3

Arayanların mantıklı olmayan veya aptalca ancak teknik olarak yanlış olmayan isteklerde bulunmalarının birçok yolu vardır. Keymaster uygulamalarının bu gibi durumlarda başarısız olması veya bir teşhis yayınlaması gerekli değildir. Çok küçük anahtarların kullanımı, alakasız giriş parametrelerinin belirtilmesi, IV'lerin veya nonce'ların yeniden kullanımı, amaçsız (dolayısıyla işe yaramaz) anahtarların oluşturulması ve benzeri uygulamalar tarafından teşhis edilmemelidir. Gerekli parametrelerin atlanması, geçersiz gerekli parametrelerin belirtilmesi ve benzer hatalar teşhis edilmelidir.

Keymaster modüllerine yapılan çağrıların mantıklı ve kullanışlı olmasını sağlamak uygulamaların, çerçevenin ve Android anahtar deposunun sorumluluğundadır.

Fonksiyonlar

getDonanımÖzellikleri

Sürüm : 3

Yeni getHardwareFeatures yöntemi, istemcilere temeldeki güvenli donanımın bazı önemli özelliklerini gösterir. Yöntem hiçbir argüman almaz ve tümü boole olan dört değer döndürür:

  • Anahtarlar güvenli donanımda (TEE, vb.) saklanıyorsa ve asla terk isSecure true .
  • supportsEllipticCurve , donanım NIST eğrileri (P-224, P-256, P-384 ve P-521) ile Eliptik Eğri kriptografisini destekliyorsa true .
  • DestekSimetrik Şifreleme, donanım AES ve HMAC dahil olmak üzere simetrik şifrelemeyi supportsSymmetricCryptography true .
  • Donanım, güvenli bir ortama enjekte edilmiş bir anahtarla imzalanmış Keymaster ortak anahtar doğrulama sertifikalarının oluşturulmasını supportsAttestation , supportAttestation true .

Bu yöntemin döndürebileceği tek hata kodları ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED veya güvenli donanımla iletişim kurma başarısızlığını gösteren hata kodlarından biridir.

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 tanıtılmış ve Keymaster 3'te kullanımdan kaldırılmıştır, çünkü bu bilgi sistem özellikleri dosyalarında mevcuttur ve üretici uygulamaları bu dosyaları başlatma sırasında okur.

Anahtar yöneticisini yapılandırır. Bu yöntem, cihaz açıldıktan sonra ve kullanılmadan önce bir kez çağrılır. Keymaster'a KM_TAG_OS_VERSION ve KM_TAG_OS_PATCHLEVEL sağlamak için kullanılır. Bu yöntem çağrılana kadar diğer tüm yöntemler KM_ERROR_KEYMASTER_NOT_CONFIGURED . Bu yöntem tarafından sağlanan değerler, anahtar yöneticisi tarafından önyükleme başına yalnızca bir kez kabul edilir. Sonraki çağrılar KM_ERROR_OK , ancak hiçbir şey yapmaz.

Anahtar yöneticisi uygulaması güvenli donanımdaysa ve sağlanan işletim sistemi sürümü ve yama düzeyi değerleri, önyükleyici tarafından güvenli donanıma sağlanan değerlerle eşleşmiyorsa (veya önyükleyici değer sağlamadıysa), bu yöntem KM_ERROR_INVALID_ARGUMENT ve diğer tüm öğeleri döndürür. yöntemler KM_ERROR_KEYMASTER_NOT_CONFIGURED döndürmeye devam ediyor.

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

addRngEntropi

Sürüm : 1, 2, 3

Bu işlev Keymaster 1'de add_rng_entropy olarak tanıtıldı ve Keymaster 3'te yeniden adlandırıldı.

Keymaster 1 uygulaması tarafından anahtarlar, IV'ler vb. için rastgele sayılar üretmek için kullanılan havuza arayan tarafından sağlanan entropiyi ekler.

Keymaster uygulamalarının, sağlanan entropiyi kendi havuzlarına güvenli bir şekilde karıştırması gerekir; bu, aynı zamanda bir donanım rasgele sayı üretecinden dahili olarak oluşturulmuş entropiyi de içermelidir. Karıştırma, addRngEntropy tarafından sağlanan bitler veya donanım tarafından oluşturulan bitler üzerinde tam denetime sahip olan bir saldırganın entropi havuzundan oluşturulan bitleri tahmin etmede göz ardı edilemez bir avantajı olmayacak şekilde ele alınmalıdır.

Dahili havuzlarındaki entropiyi tahmin etmeye çalışan anahtar yöneticisi uygulamaları, addRngEntropy tarafından sağlanan verilerin entropi içermediğini varsayar. Tek bir çağrıda 2 KiB'den fazla veri verilirse, keymaster uygulamaları ErrorCode::INVALID_INPUT_LENGTH döndürebilir.

anahtar oluştur

Sürüm : 1, 2, 3

Bu işlev Keymaster 1'de generate_key olarak tanıtıldı ve Keymaster 3'te yeniden adlandırıldı.

Anahtara kalıcı olarak bağlı olan ilişkili yetkileri belirterek yeni bir şifreleme anahtarı oluşturur. Keymaster uygulamaları, üretim zamanında belirtilen yetkilerle tutarsız bir anahtarın herhangi bir şekilde kullanılmasını imkansız hale getirir. Güvenli donanımın uygulayamadığı yetkilendirmelerle ilgili olarak, güvenli donanımın yükümlülüğü, anahtarla ilişkili uygulanamaz yetkilerin değiştirilememesini sağlamakla sınırlıdır, böylece getKeyCharacteristics'e yapılan her çağrı orijinal değeri döndürür. Ayrıca, generateKey tarafından döndürülen özellikler, donanım tarafından zorunlu kılınan ve yazılım tarafından zorunlu kılınan listeler arasında yetkilendirmeleri doğru bir şekilde tahsis eder. Daha fazla ayrıntı için getKeyCharacteristics'e bakın.

createKey için sağlanan parametreler, generateKey anahtarın türüne bağlıdır. Bu bölüm, her bir anahtar türü için gerekli ve isteğe bağlı etiketleri özetlemektedir. Etiket::ALGORİTMA , türü belirtmek için her zaman gereklidir.

RSA anahtarları

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

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

Aşağıdaki parametreler bir RSA anahtarı oluşturmak için gerekli değildir, ancak bunlar olmadan bir RSA anahtarı oluşturmak, kullanılamaz bir anahtar üretir. Ancak, bu parametreler atlanırsa, generateKey işlevi bir hata döndürmez.

  • Tag::PURPOSE izin verilen amaçları belirtir. Herhangi bir kombinasyonda RSA anahtarları için tüm amaçların desteklenmesi gerekir.
  • Tag::DIGEST , yeni anahtarla kullanılabilecek özet algoritmalarını belirtir. Tüm özet algoritmalarını desteklemeyen uygulamaların, desteklenmeyen özetler içeren anahtar oluşturma isteklerini kabul etmesi gerekir. Desteklenmeyen özetler, döndürülen anahtar özelliklerde "yazılım tarafından uygulanan" listeye yerleştirilmelidir. Bunun nedeni, anahtarın bu diğer özetlerle kullanılabilir olması, ancak özetlemenin yazılımda gerçekleştirilmesidir. Ardından Digest::NONE ile işlemi gerçekleştirmek için donanım çağrılır.
  • Etiket::PADDING , yeni anahtarla kullanılabilecek dolgu modlarını belirtir. Desteklenmeyen herhangi bir özet algoritması belirtilirse, tüm özet algoritmalarını desteklemeyen uygulamaların PaddingMode::RSA_PSS ve PaddingMode::RSA_OAEP yazılım tarafından zorlanan temel özellikler listesine yerleştirmesi gerekir.

ECDSA anahtarları

Bir ECDSA anahtarı oluşturmak için yalnızca Etiket::KEY_SIZE gereklidir. EC grubunu seçmek için kullanılır. Desteklenen değerler sırasıyla NIST p-224, p-256, p-384 ve p521 eğrilerini gösteren 224, 256, 384 ve 521'dir.

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

AES anahtarları

Bir AES anahtarı oluşturmak için yalnızca Etiket::KEY_SIZE gereklidir. Atlanırsa, yöntem ErrorCode::UNSUPPORTED_KEY_SIZE döndürür. Desteklenen değerler, isteğe bağlı olarak 192 bit AES anahtarları desteğiyle 128 ve 256'dır.

Aşağıdaki parametreler özellikle AES anahtarlarıyla ilgilidir, ancak bir tane oluşturmak için gerekli değildir:

  • Tag::BLOCK_MODE , yeni anahtarın kullanılabileceği blok modlarını belirtir.
  • Tag::PADDING , kullanılabilecek dolgu modlarını belirtir. Bu yalnızca ECB ve CBC modları için geçerlidir.

GCM blok modu belirtilirse, Tag::MIN_MAC_LENGTH'yi sağlayın . Atlanırsa, yöntem ErrorCode::MISSING_MIN_MAC_LENGTH döndürür. Etiketin değeri 8'in katıdır ve 96 ile 128 arasındadır.

HMAC anahtarları

HMAC anahtar üretimi için aşağıdaki parametreler gereklidir:

  • Etiket::KEY_SIZE , anahtar boyutunu bit olarak belirtir. 64'ten küçük değerler ve 8'in katı olmayan değerler desteklenmez. 64'ten 512'ye kadar 8'in tüm katları desteklenir. Daha büyük değerler desteklenebilir.
  • Tag::MIN_MAC_LENGTH , bu anahtarla oluşturulabilecek veya doğrulanabilecek minimum MAC uzunluğunu belirtir. Değer, 8'in katı ve en az 64'tür.
  • Tag::DIGEST , anahtar için özet algoritmasını belirtir. Tam olarak bir özet belirtildi, aksi takdirde ErrorCode::UNSUPPORTED_DIGEST . Özet güven tarafından desteklenmiyorsa, ErrorCode::UNSUPPORTED_DIGEST döndürün.

Temel özellikler

Özellikler bağımsız değişkeni NULL değilse, createKey, yeni generateKey anahtarın özelliklerini uygun şekilde donanım ve yazılım tarafından zorlanan listelere bölünmüş olarak döndürür. Hangi özelliklerin hangi listeye girdiğinin açıklaması için getKeyCharacteristics'e bakın. Döndürülen özellikler, Tag::APPLICATION_ID ve Tag::APPLICATION_DATA dışında, anahtar oluşturma için belirtilen tüm parametreleri içerir. Bu etiketler anahtar parametrelere dahil edilmişse, döndürülen anahtar blobu incelenerek değerlerinin bulunması mümkün olmaması için döndürülen özelliklerden kaldırılır. Ancak, anahtar blobuna kriptografik olarak bağlıdırlar, böylece anahtar kullanıldığında doğru değerler sağlanmazsa kullanım başarısız olur. Benzer şekilde, Tag::ROOT_OF_TRUST anahtara kriptografik olarak bağlıdır, ancak anahtar oluşturma veya içe aktarma sırasında belirtilmeyebilir ve asla döndürülmez.

Sağlanan etiketlere ek olarak, güvenilen kişi ayrıca KeyOrigin::GENERATED değeriyle Tag::ORIGIN ekler ve anahtar geri alma dirençliyse,

Etiket::ROLLBACK_RESISTANT .

geri alma direnci

Geri alma direnci, bir anahtarın deleteKey veya deleteAllKeys ile bir kez silinmesinin, güvenli donanım tarafından bir daha asla kullanılamayacağının garanti edilmesi anlamına gelir. Geri alma direnci olmayan uygulamalar, genellikle oluşturulan veya içe aktarılan anahtar malzemesini arayana bir anahtar blobu, şifreli ve kimliği doğrulanmış bir form olarak döndürür. Anahtar deposu, anahtar bloğunu sildiğinde, anahtar kaybolur, ancak daha önce anahtar malzemesini almayı başaran bir saldırgan, potansiyel olarak onu cihaza geri yükleyebilir.

Güvenli donanım, silinen anahtarların daha sonra geri yüklenemeyeceğini garanti ediyorsa, bir anahtar geri alınmaya karşı dayanıklıdır. Bu genellikle, bir saldırgan tarafından manipüle edilemeyen güvenilir bir konumda ek anahtar meta verileri depolayarak yapılır. Mobil cihazlarda bunun için kullanılan mekanizma genellikle Tekrardan Korumalı Bellek Bloklarıdır (RPMB). Oluşturulabilecek anahtarların sayısı esasen sınırsız olduğundan ve geri alma direnci için kullanılan güvenilir depolamanın boyutu sınırlı olabileceğinden, yeni anahtar için geri alma direnci sağlanamasa bile bu yöntemin başarılı olması gerekir. Bu durumda, anahtar özelliklere Tag::ROLLBACK_RESISTANT eklenmemelidir.

getKeyÖzellikleri

Sürüm : 1, 2, 3

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

Sağlanan anahtarla ilişkili parametreleri ve yetkileri iki kümeye bölünmüş olarak döndürür: donanım tarafından uygulanan ve yazılım tarafından zorlanan. Buradaki açıklama, createKey ve importKey tarafından döndürülen anahtar özellikler listelerine eşit olarak uygulanır.

Anahtar oluşturma veya içe aktarma sırasında Tag::APPLICATION_ID sağlandıysa, clientId bağımsız değişkeninde bu yönteme aynı değer sağlanır. Aksi takdirde, yöntem ErrorCode::INVALID_KEY_BLOB döndürür. Benzer şekilde, oluşturma veya içe aktarma sırasında Tag::APPLICATION_DATA sağlandıysa, appData bağımsız değişkeninde bu yönteme aynı değer sağlanır.

Bu yöntemin döndürdüğü özellikler, belirtilen anahtarın türünü ve kullanımını tamamen açıklar.

Belirli bir etiketin donanım tarafından zorunlu tutulan veya yazılım tarafından zorunlu kılınan listeye ait olup olmadığına karar vermek için genel kural, etiketin anlamının güvenli donanım tarafından tamamen güvence altına alınması durumunda donanım tarafından zorunlu kılınmasıdır. Aksi takdirde, yazılım tarafından zorlanır. Aşağıda, doğru tahsisi belirsiz olabilecek belirli etiketlerin bir listesi bulunmaktadır:

  • Tag ::ALGORITHM , Tag::KEY_SIZE ve Tag::RSA_PUBLIC_EXPONENT , anahtarın içsel özellikleridir. Donanım tarafından güvence altına alınan herhangi bir anahtar için bu etiketler donanım tarafından zorunlu kılınan listede olacaktır.
  • Güvenli donanım tarafından desteklenen Tag::DIGEST değerleri donanım tarafından desteklenenler listesine yerleştirilir. Desteklenmeyen özetler, yazılım destekli listeye girer.
  • Etiket::PADDING değerleri, yazılım tarafından belirli bir doldurma modunun gerçekleştirilmesi gerekmedikçe, genellikle donanım destekli listede bulunur. Bu durumda, yazılım tarafından zorunlu kılınan listeye girerler. Böyle bir olasılık, güvenli donanım tarafından desteklenmeyen özet algoritmaları ile PSS veya OAEP doldurmaya izin veren RSA anahtarları için ortaya çıkar.
  • Etiket::USER_SECURE_ID ve Etiket::USER_AUTH_TYPE , yalnızca kullanıcı kimlik doğrulaması donanım tarafından zorunlu tutuluyorsa donanım tarafından uygulanır. Bunu başarmak için, Keymaster güven uygulamasının ve ilgili kimlik doğrulama güven uygulamasının güvenli olması ve kimlik doğrulama belirteçlerini imzalamak ve doğrulamak için kullanılan gizli bir HMAC anahtarını paylaşması gerekir. Ayrıntılar için Kimlik Doğrulama sayfasına bakın.
  • Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME ve Tag::USAGE_EXPIRE_DATETIME etiketleri, doğrulanabilir şekilde doğru bir duvar saatine erişim gerektirir. Çoğu güvenli donanım, yalnızca güvenli olmayan işletim sistemi tarafından sağlanan zaman bilgilerine erişebilir, bu da etiketlerin yazılım tarafından zorunlu kılındığı anlamına gelir.
  • Etiket::ORIGIN , donanıma bağlı anahtarlar için her zaman donanım listesindedir. Bu listedeki varlığı, daha yüksek katmanların bir anahtarın donanım destekli olduğunu belirleme şeklidir.

ithalatAnahtarı

Sürüm : 1, 2, 3

Bu işlev Keymaster 1'de import_key olarak tanıtıldı ve Keymaster 3'te yeniden adlandırıldı.

Anahtar materyali Keymaster donanımına aktarır. Anahtar tanımı parametreleri ve çıktı özellikleri, aşağıdaki istisnalar dışında, generateKey ile aynı şekilde işlenir:

  • Giriş parametrelerinde Tag::KEY_SIZE ve Tag::RSA_PUBLIC_EXPONENT (yalnızca RSA anahtarları için) gerekli değildir. Sağlanmamışsa, güven, sağlanan anahtar malzemeden değerleri çıkarır ve anahtar özelliklere uygun etiketler ve değerler ekler. Parametreler sağlanırsa, güven onları anahtar malzemeye göre doğrular. Uyuşmazlık durumunda, yöntem ErrorCode::IMPORT_PARAMETER_MISMATCH döndürür.
  • Döndürülen Tag::ORIGIN , KeyOrigin::IMPORTED ile aynı değere sahiptir.

ihracatAnahtarı

Sürüm : 1, 2, 3

Bu işlev Keymaster 1'de export_key olarak tanıtıldı ve Keymaster 3'te yeniden adlandırıldı.

Bir Keymaster RSA veya EC anahtar çiftinden bir genel anahtarı dışa aktarır.

Anahtar oluşturma veya içe aktarma sırasında Tag::APPLICATION_ID sağlandıysa, clientId bağımsız değişkeninde bu yönteme aynı değer sağlanır. Aksi takdirde, yöntem ErrorCode::INVALID_KEY_BLOB döndürür. Benzer şekilde, oluşturma veya içe aktarma sırasında Tag::APPLICATION_DATA sağlandıysa, appData bağımsız değişkeninde bu yönteme aynı değer sağlanır.

silAnahtarı

Sürüm : 1, 2, 3

Bu işlev Keymaster 1'de delete_key olarak tanıtıldı ve Keymaster 3'te yeniden adlandırıldı.

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

Tüm Anahtarları sil

Sürüm : 1, 2, 3

Bu işlev Keymaster 1'de delete_all_keys olarak tanıtıldı ve Keymaster 3'te yeniden adlandırıldı.

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

destroyAttestationIds

Sürüm : 3

destroyAttestationIds() yöntemi, yeni (isteğe bağlı, ancak şiddetle tavsiye edilir) kimlik doğrulama özelliğini kalıcı olarak devre dışı bırakmak için kullanılır. TEE'nin bu yöntem çağrıldıktan sonra kimlik doğrulamanın kalıcı olarak devre dışı bırakılmasını sağlamanın bir yolu yoksa, kimlik doğrulamanın hiç uygulanmaması gerekir, bu durumda bu yöntem hiçbir şey yapmaz ve ErrorCode::UNIMPLEMENTED döndürür. Kimlik doğrulama destekleniyorsa, bu yöntemin uygulanması gerekir ve gelecekteki tüm kimlik doğrulama girişimlerini kalıcı olarak devre dışı bırakmalıdır. Yöntem herhangi bir sayıda çağrılabilir. Kimlik doğrulama zaten kalıcı olarak devre dışı bırakılmışsa, yöntem hiçbir şey yapmaz ve ErrorCode::OK döndürür.

Bu yöntemin döndürebileceği tek hata kodu ErrorCode::UNIMPLEMENTED (kimlik doğrulaması desteklenmiyorsa), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED veya güvenli donanımla iletişim başarısızlığını gösteren hata kodlarından biridir.

başlamak

Sürüm : 1, 2, 3

Belirtilen amaç için, belirtilen parametrelerle (uygun olduğu şekilde) belirtilen anahtarı kullanarak bir şifreleme işlemi başlatır ve işlemi tamamlamak için güncelleme ve bitiş ile kullanılan bir işlem tanıtıcısı döndürür. İşlem tanıtıcı, kimliği doğrulanmış işlemlerde "zorlama" belirteci olarak da kullanılır ve bu tür işlemler için kimlik doğrulama belirtecinin challenge alanına dahil edilir.

Bir Keymaster uygulaması, en az 16 eşzamanlı işlemi destekler. Anahtar deposu 15'e kadar kullanır ve bir tanesini parola şifrelemesi için kullanmak üzere vold'a bırakır. Anahtar deposunun devam eden 15 işlemi olduğunda ( begin ​​çağrıldı, ancak finish veya abort henüz çağrılmadı) ve 16'ncısını başlatmak için bir istek aldığında, etkin işlemlerin sayısını azaltmak için en son kullanılan işlemde abort çağrısı yapar. 14'e kadar aramadan önce yeni istenen işlemi begin başlayın.

Anahtar oluşturma veya içe aktarma sırasında Tag::APPLICATION_ID veya Tag::APPLICATION_DATA belirtildiyse, begin çağrıları, bu yöntemin inParams bağımsız değişkeninde orijinal olarak belirtilen değerlere sahip etiketleri içerir.

yetkilendirme yaptırımı

Bu yöntem sırasında, uygulama bunları "donanım tarafından zorlanan" özelliklere yerleştirdiyse ve işlem bir ortak anahtar işlemi değilse, aşağıdaki anahtar yetkilendirmeleri güven tarafından uygulanır. RSA veya EC anahtarlarıyla KeyPurpose::ENCRYPT ve KeyPurpose::VERIFY anlamına gelen genel anahtar işlemlerinin, yetkilendirme gereksinimleri karşılanmasa bile başarılı olmasına izin verilir.

  • Tag::PURPOSE : istenen işlem bir genel anahtar işlemi değilse, begin() çağrısında belirtilen amaç, anahtar yetkilendirmelerindeki amaçlardan biriyle eşleşmelidir. Belirtilen amaç eşleşmiyorsa ve işlem bir genel anahtar işlemi değilse, start, ErrorCode::UNSUPPORTED_PURPOSE begin döndürür. Açık anahtar işlemleri asimetrik şifreleme veya doğrulama işlemleridir.
  • Etiket::ACTIVE_DATETIME yalnızca güvenilir bir UTC saat kaynağı mevcutsa uygulanabilir. Geçerli tarih ve saat, etiket değerinden önceyse, yöntem ErrorCode::KEY_NOT_YET_VALID değerini döndürür.
  • Etiket::ORIGINATION_EXPIRE_DATETIME yalnızca güvenilir bir UTC saat kaynağı mevcutsa uygulanabilir. Geçerli tarih ve saat, etiket değerinden sonraysa ve amaç KeyPurpose::ENCRYPT veya KeyPurpose::SIGN ise, yöntem ErrorCode::KEY_EXPIRED döndürür.
  • Etiket::USAGE_EXPIRE_DATETIME yalnızca güvenilir bir UTC zaman kaynağı mevcutsa uygulanabilir. Geçerli tarih ve saat etiket değerinden sonraysa ve amaç KeyPurpose::DECRYPT veya KeyPurpose::VERIFY ise, yöntem ErrorCode::KEY_EXPIRED döndürür.
  • Tag::MIN_SECONDS_BETWEEN_OPS , anahtarın son kullanımını gösteren güvenilir bir göreli zamanlayıcı ile karşılaştırılır. Son kullanım süresi artı etiket değeri geçerli zamandan küçükse, yöntem ErrorCode::KEY_RATE_LIMIT_EXCEEDED döndürür. Önemli uygulama ayrıntıları için etiket açıklamasına bakın.
  • Tag::MAX_USES_PER_BOOT , önyükleme zamanından beri anahtarın kullanımlarını izleyen güvenli bir sayaçla karşılaştırılır. Önceki kullanımların sayısı etiket değerini aşarsa, yöntem ErrorCode::KEY_MAX_OPS_EXCEEDED değerini döndürür.
  • Tag::USER_SECURE_ID , yalnızca anahtarda Tag::AUTH_TIMEOUT varsa, bu yöntemle uygulanır. Anahtarda her ikisi de varsa, bu yöntem inParams içinde geçerli bir Tag::AUTH_TOKEN inParams . Kimlik doğrulama belirtecinin geçerli olması için aşağıdakilerin tümünün doğru olması gerekir:
    • HMAC alanı doğru şekilde doğrulanır.
    • Anahtardaki Tag::USER_SECURE_ID değerlerinden en az biri, belirteçteki güvenli kimlik değerlerinden en az biriyle eşleşir.
    • Anahtarın, belirteçteki kimlik doğrulama türüyle eşleşen bir Tag::USER_AUTH_TYPE vardır.

    Bu koşullardan herhangi biri karşılanmazsa, yöntem ErrorCode::KEY_USER_NOT_AUTHENTICATED döndürür.

  • Tag::CALLER_NONCE , arayanın bir nonce veya başlatma vektörü (IV) belirtmesine izin verir. Anahtarda bu etiket yoksa ancak arayan kişi bu yönteme Tag::NONCE sağladıysa , ErrorCode::CALLER_NONCE_PROHIBITED döndürülür.
  • Tag::BOOTLOADER_ONLY , anahtarı yalnızca önyükleyicinin kullanabileceğini belirtir. Bu yöntem, önyükleyici yürütmeyi bitirdikten sonra yalnızca önyükleyici anahtarıyla çağrılırsa, ErrorCode::INVALID_KEY_BLOB döndürür.

RSA anahtarları

Tüm RSA anahtar işlemleri, inParams içinde tam olarak bir doldurma modu belirtir. Belirtilmemişse veya birden fazla belirtilmişse, yöntem ErrorCode::UNSUPPORTED_PADDING_MODE döndürür.

RSA imzalama ve doğrulama işlemleri, OAEP doldurma moduyla RSA şifreleme ve şifre çözme işlemleri gibi bir özete ihtiyaç duyar. Bu durumlarda, arayan kişi inParams içinde tam olarak bir özet belirtir. Belirtilmemişse veya birden fazla belirtilmişse, yöntem ErrorCode::UNSUPPORTED_DIGEST döndürür.

Özel anahtar işlemleri ( KeyPurpose::DECYPT ve KeyPurpose::SIGN ) özet ve dolgu yetkilendirmesi gerektirir, bu da anahtar yetkilendirmelerinin belirtilen değerleri içermesi gerektiği anlamına gelir. Değilse, yöntem ErrorCode::INCOMPATIBLE_DIGEST veya ErrorCode::INCOMPATIBLE_PADDING uygun şekilde döndürür. Ortak anahtar işlemlerine ( KeyPurpose::ENCRYPT ve KeyPurpose::VERIFY ) yetkisiz özet veya dolgu ile izin verilir.

PaddingMode::NONE dışında, tüm RSA dolgu modları yalnızca belirli amaçlar için geçerlidir. Özellikle, PaddingMode::RSA_PKCS1_1_5_SIGN ve PaddingMode::RSA_PSS yalnızca imzalama ve doğrulamayı desteklerken, PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT ve PaddingMode::RSA_OAEP yalnızca şifreleme ve şifre çözmeyi destekler. Belirtilen mod belirtilen amacı desteklemiyorsa, yöntem ErrorCode::UNSUPPORTED_PADDING_MODE döndürür.

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

  • PaddingMode::NONE , bir "ham" RSA işleminin gerçekleştirildiğini gösterir. İmzalanıyor veya doğrulanıyorsa, özet için Digest::NONE belirtilir. Doldurulmamış şifreleme veya şifre çözme için özet gerekmez.
  • PaddingMode::RSA_PKCS1_1_5_SIGN dolgusu bir özet gerektirir. Özet, Digest::NONE olabilir, bu durumda Keymaster uygulaması, DigestInfo yapısını ekleyemediği için uygun bir PKCS#1 v1.5 imza yapısı oluşturamaz. Bunun yerine, uygulama 0x00 || 0x01 || PS || 0x00 || M , burada M sağlanan mesajdır ve PS dolgu dizesidir. RSA anahtarının boyutu iletiden en az 11 bayt daha büyük olmalıdır, aksi takdirde yöntem ErrorCode::INVALID_INPUT_LENGTH döndürür.
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT dolgusu bir özet gerektirmez.
  • PaddingMode::RSA_PSS dolgusu, Digest::NONE olmayabilecek bir özet gerektirir. Digest::NONE belirtilirse, yöntem ErrorCode::INCOMPATIBLE_DIGEST döndürür. Ayrıca, RSA anahtarının boyutu, özetin çıkış boyutundan en az 2 + D bayt daha büyük olmalıdır; burada D, bayt cinsinden özetin boyutudur. Aksi takdirde, yöntem ErrorCode::INCOMPATIBLE_DIGEST döndürür. Tuz boyutu D'dir.
  • PaddingMode::RSA_OAEP dolgusu, Digest::NONE olmayabilecek bir özet gerektirir. Digest::NONE belirtilirse, yöntem ErrorCode::INCOMPATIBLE_DIGEST döndürür.

EC anahtarları

EC tuş işlemleri, inParams içinde tam olarak bir doldurma modu belirtir. Belirtilmemişse veya birden fazla belirtilmişse, yöntem ErrorCode::UNSUPPORTED_PADDING_MODE döndürür.

Özel anahtar işlemleri ( KeyPurpose::SIGN ) özet ve doldurma yetkisi gerektirir, bu da anahtar yetkilendirmelerinin belirtilen değerleri içermesi gerektiği anlamına gelir. Değilse, ErrorCode::INCOMPATIBLE_DIGEST . Ortak anahtar işlemlerine ( KeyPurpose::VERIFY ) yetkisiz özet veya dolgu ile izin verilir.

AES anahtarları

AES tuş işlemleri, inParams içinde tam olarak bir blok modu ve bir dolgu modu belirtir. Değerlerden biri belirtilmemişse veya birden fazla belirtilmişse, ErrorCode::UNSUPPORTED_BLOCK_MODE veya ErrorCode::UNSUPPORTED_PADDING_MODE . Belirtilen modlar anahtar tarafından yetkilendirilmelidir, aksi takdirde yöntem ErrorCode::INCOMPATIBLE_BLOCK_MODE veya ErrorCode::INCOMPATIBLE_PADDING_MODE döndürür.

Blok modu BlockMode::GCM ise, inParams Tag::MAC_LENGTH belirtir ve belirtilen değer, anahtar yetkilendirmelerindeki Tag::MIN_MAC_LENGTH değerinden 128'den büyük veya daha küçük olmayan 8'in katıdır. 128'den büyük veya 8'in katı olmayan MAC uzunlukları için ErrorCode::UNSUPPORTED_MAC_LENGTH . Anahtarın minimum uzunluğundan daha küçük değerler için ErrorCode::INVALID_MAC_LENGTH .

Blok modu BlockMode::GCM veya BlockMode::CTR ise, belirtilen doldurma modu PaddingMode::NONE olmalıdır. BlockMode::ECB veya BlockMode::CBC için mod, PaddingMode::NONE veya PaddingMode::PKCS7 olabilir. Doldurma modu bu koşulları karşılamıyorsa, ErrorCode::INCOMPATIBLE_PADDING_MODE .

Blok modu BlockMode::CBC , BlockMode::CTR veya BlockMode::GCM ise, bir başlatma vektörü veya nonce gereklidir. Çoğu durumda, arayanlar IV veya nonce sağlamamalıdır. Bu durumda, Keymaster uygulaması rastgele bir IV veya nonce oluşturur ve bunu OutParams içinde Tag::NONCE outParams döndürür. CBC ve CTR IV'ler 16 bayttır. GCM nonce'ları 12 bayttır. Anahtar yetkilendirmeleri Tag::CALLER_NONCE içeriyorsa, arayan kişi inParams içinde Tag::NONCE inParams bir IV/nonce sağlayabilir. Tag::CALLER_NONCE yetkilendirilmediğinde bir nonce sağlanırsa, ErrorCode::CALLER_NONCE_PROHIBITED . Tag::CALLER_NONCE yetkilendirildiğinde bir nonce sağlanmazsa, rastgele bir IV/nonce oluşturun.

HMAC anahtarları

HMAC anahtar işlemleri, inParams içinde Tag::MAC_LENGTH inParams . Belirtilen değer, özet uzunluğundan büyük olmayan veya anahtar yetkilendirmelerindeki Tag::MIN_MAC_LENGTH değerinden küçük olmayan 8'in katı olmalıdır. Özet uzunluğundan büyük veya 8'in katı olmayan MAC uzunlukları için ErrorCode::UNSUPPORTED_MAC_LENGTH . Anahtarın minimum uzunluğundan daha küçük değerler için ErrorCode::INVALID_MAC_LENGTH .

Güncelleme

Sürüm : 1, 2, 3

start ile başlayan devam eden bir işlemde işlenecek verileri sağlar. İşlem, operationHandle parametresi tarafından belirtilir.

Arabellek işleme için daha fazla esneklik sağlamak için bu yöntemin uygulamaları, sağlanandan daha az veri tüketme seçeneğine sahiptir. Arayan, sonraki aramalarda verilerin geri kalanını beslemek için döngü yapmaktan sorumludur. Tüketilen girdi miktarı inputConsumed parametresinde döndürülür. İşlem daha fazlasını kabul edemedikçe, uygulamalar her zaman en az bir bayt tüketir; sıfırdan fazla bayt sağlanır ve sıfır bayt tüketilirse, arayanlar bunu bir hata olarak kabul eder ve işlemi iptal eder.

Uygulamalar, güncellemenin bir sonucu olarak ne kadar veri döndürüleceğini de seçebilir. Bu, yalnızca şifreleme ve şifre çözme işlemleri için geçerlidir, çünkü imzalama ve doğrulama, bitene kadar hiçbir veri döndürmez. Verileri arabelleğe almak yerine mümkün olduğunca erken döndürün.

Hata yönetimi

Bu yöntem ErrorCode::OK dışında bir hata kodu döndürürse, işlem iptal edilir ve işlem tanıtıcısı geçersiz kılınır. Bu yöntemle, bitiş veya iptal ile tanıtıcının gelecekteki herhangi bir kullanımı, ErrorCode::INVALID_OPERATION_HANDLE döndürür.

yetkilendirme yaptırımı

Anahtar yetkilendirme uygulaması öncelikle başlangıçta gerçekleştirilir. Tek istisna, anahtarın aşağıdakilere sahip olduğu durumdur:

Bu durumda, anahtar, işlem başına bir yetkilendirme gerektirir ve güncelleme yöntemi, inParams bağımsız değişkeninde bir Tag::AUTH_TOKEN alır. HMAC, belirtecin geçerli olduğunu ve eşleşen bir güvenli kullanıcı kimliği içerdiğini doğrular, anahtarın Tag::USER_AUTH_TYPE ile eşleşir ve sorgulama alanında geçerli işlemin işlem tanıtıcısını içerir. Bu koşullar karşılanmazsa, ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Arayan, güncellemek ve bitirmek için her çağrıya kimlik doğrulama belirtecini sağlar. Uygulamanın, eğer isterse belirteci yalnızca bir kez doğrulaması gerekir.

RSA anahtarları

Digest::NONE ile imzalama ve doğrulama işlemleri için bu yöntem, tüm bloğun tek bir güncellemede imzalanmasını veya doğrulanmasını kabul eder. Bloğun sadece bir kısmını tüketemez. Ancak, arayan kişi verileri birden çok güncellemede sağlamayı seçerse, bu yöntem bunu kabul eder. Arayan, kullanılabilecekten daha fazla imzalamak için veri sağlıyorsa (veri uzunluğu RSA anahtar boyutunu aşıyor), ErrorCode::INVALID_INPUT_LENGTH .

ECDSA anahtarları

Digest::NONE ile imzalama ve doğrulama işlemleri için bu yöntem, tüm bloğun tek bir güncellemede imzalanmasını veya doğrulanmasını kabul eder. Bu yöntem bloğun sadece bir kısmını tüketmeyebilir.

Ancak, arayan kişi verileri birden çok güncellemede sağlamayı seçerse, bu yöntem bunu kabul eder. Arayan, imzalamak için kullanılabilecekten daha fazla veri sağlıyorsa, veriler sessizce kesilir. (Bu, benzer RSA işlemlerinde sağlanan fazla verilerin işlenmesinden farklıdır. Bunun nedeni eski istemcilerle uyumluluktur.)

AES anahtarları

AES GCM modu, inParams bağımsız değişkeninde Tag::ASSOCIATED_DATA etiketi aracılığıyla sağlanan "ilişkili kimlik doğrulama verilerini" destekler. İlişkili veriler, tekrarlanan aramalarda sağlanabilir (veriler tek bir blokta gönderilemeyecek kadar büyükse önemlidir), ancak her zaman şifrelenecek veya şifresi çözülecek verilerden önce gelir. Bir güncelleme çağrısı, şifrelemek/şifresini çözmek için hem ilişkili verileri hem de verileri alabilir, ancak sonraki güncellemeler ilişkili verileri içermeyebilir. Arayan, şifreleme/şifre çözme verileri içeren bir çağrıdan sonra bir güncelleme çağrısına ilişkili veriler sağlarsa, ErrorCode::INVALID_TAG .

GCM şifrelemesi için etiket, bitiş ile şifreli metne eklenir. Şifre çözme sırasında, son güncelleme çağrısına sağlanan verilerin son Tag::MAC_LENGTH baytı etikettir. Belirli bir güncelleme çağrısı, bunun son çağrı olup olmadığını bilemediği için, etiket uzunluğu dışında hepsini işler ve bitiş sırasında olası etiket verilerini arabelleğe alır.

bitiş

Sürüm : 1, 2, 3

Start ile başlatılan devam eden bir işlemi, güncelleme (ler) tarafından sağlanan henüz işlenmemiş tüm verileri işleyerek tamamlar.

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure