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 destekliyorsatrue
. - 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
, supportAttestationtrue
.
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
vePaddingMode::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,
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
veyaKeyPurpose::SIGN
ise, yöntemErrorCode::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
veyaKeyPurpose::VERIFY
ise, yöntemErrorCode::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çinDigest::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, uygulama0x00 || 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öntemErrorCode::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öntemErrorCode::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öntemErrorCode::INCOMPATIBLE_DIGEST
döndürür. Tuz boyutu D'dir. -
PaddingMode::RSA_OAEP
dolgusu,Digest::NONE
olmayabilecek bir özet gerektirir.Digest::NONE
belirtilirse, yöntemErrorCode::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:
- Bir veya daha fazla Tag::USER_SECURE_IDs ve
- Etiketi yok::AUTH_TIMEOUT
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:
- One or more Tag::USER_SECURE_IDs , and
- Does not have a Tag::AUTH_TIMEOUT
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, returnErrorCode::INVALID_ARGUMENT
. For verification and decryption operations, the data must be exactly as long as the key. Otherwise, returnErrorCode::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 ininputParams
on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm. -
PaddingMode::RSA_OAEP
. The digest specified with Tag::DIGEST ininputParams
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
orBlockMode::CBC
. If padding isPaddingMode::NONE
and the data length is not a multiple of the AES block size, returnErrorCode::INVALID_INPUT_LENGTH
. If padding isPaddingMode::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, returnErrorCode::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