Keymaster के फ़ंक्शन

इस पेज पर, Keymaster हार्डवेयर एब्स्ट्रैक्शन लेयर (एचएएल) को लागू करने वालों के लिए जानकारी दी गई है. इसमें एपीआई के हर फ़ंक्शन के बारे में बताया गया है. साथ ही, यह भी बताया गया है कि वह फ़ंक्शन Keymaster के किस वर्शन में उपलब्ध है. इसमें डिफ़ॉल्ट तौर पर लागू होने के बारे में भी बताया गया है. टैग के लिए, KeyMaster टैग पेज देखें.

लागू करने के सामान्य दिशा-निर्देश

एपीआई में मौजूद सभी फ़ंक्शन पर नीचे दिए गए दिशा-निर्देश लागू होते हैं.

इनपुट पॉइंटर पैरामीटर

वर्शन: 1, 2

ऐसे इनपुट पॉइंटर पैरामीटर जो किसी कॉल के लिए इस्तेमाल नहीं किए जाते हैं वे NULL हो सकते हैं. कॉल करने वाले व्यक्ति को प्लेसहोल्डर देने की ज़रूरत नहीं है. उदाहरण के लिए, हो सकता है कि कुछ कुंजी टाइप और मोड, शुरू करें के लिए inParams आर्ग्युमेंट की किसी भी वैल्यू का इस्तेमाल न करें. इसलिए, कॉलर inParams को NULL पर सेट कर सकता है या खाली पैरामीटर सेट कर सकता है. कॉलर, इस्तेमाल न किए गए पैरामीटर भी दे सकते हैं. साथ ही, Keymaster के तरीकों से गड़बड़ियां नहीं होनी चाहिए.

अगर ज़रूरी इनपुट पैरामीटर शून्य है, तो कीमास्टर तरीकों को ErrorCode::UNEXPECTED_NULL_POINTER लौटाना चाहिए.

Keymaster 3 में, पॉइंटर पैरामीटर नहीं होते. सभी पैरामीटर को वैल्यू या const रेफ़रंस के ज़रिए पास किया जाता है.

आउटपुट पॉइंटर पैरामीटर

वर्शन: 1, 2

इनपुट पॉइंटर पैरामीटर की तरह ही, इस्तेमाल न किए गए आउटपुट पॉइंटर पैरामीटर, NULL हो सकते हैं. अगर किसी तरीके को NULL के तौर पर पाए जाने वाले आउटपुट पैरामीटर में डेटा दिखाना है, तो उसे ErrorCode::OUTPUT_PARAMETER_NULL दिखाना चाहिए.

Keymaster 3 में, पॉइंटर पैरामीटर नहीं होते. सभी पैरामीटर को वैल्यू या const रेफ़रंस के ज़रिए पास किया जाता है.

एपीआई का गलत इस्तेमाल

वर्शन: 1, 2, 3

कॉल करने वाले कई तरह से ऐसे अनुरोध कर सकते हैं जो समझ में न आएं या बेवकूफ़ी भरे हों, लेकिन तकनीकी तौर पर गलत न हों. ऐसे मामलों में, Keymaster लागू करने के लिए, डिवाइस के काम न करने या गड़बड़ी की जानकारी देने की ज़रूरत नहीं होती. बहुत छोटी कुंजियों का इस्तेमाल, काम के न होने वाले इनपुट पैरामीटर की जानकारी, आईवी या नॉन्स का फिर से इस्तेमाल, बिना किसी मकसद के कुंजियों का जनरेशन (इसलिए बेकार) वगैरह का पता लगाने के लिए, लागू करने की प्रक्रिया का इस्तेमाल नहीं किया जाना चाहिए. ज़रूरी पैरामीटर को शामिल न करने, अमान्य ज़रूरी पैरामीटर की जानकारी देने, और ऐसी ही अन्य गड़बड़ियों का पता लगाया जाना चाहिए.

ऐप्लिकेशन, फ़्रेमवर्क, और Android कीस्टोर की यह ज़िम्मेदारी है कि वे यह पक्का करें कि Keymaster मॉड्यूल को किए जाने वाले कॉल सही और काम के हों.

फ़ंक्शन

getHardwareFeatures

वर्शन: 3

getHardwareFeatures के नए तरीके से, क्लाइंट को इसके सुरक्षित हार्डवेयर की कुछ अहम विशेषताओं की जानकारी मिलती है. यह तरीका कोई तर्क नहीं लेता और चार मान दिखाता है, यानी सभी बूलियन:

  • अगर कुंजियों को सुरक्षित हार्डवेयर (टीईई वगैरह) में सेव किया जाता है और उन्हें कभी भी वहां से नहीं हटाया जाता, तो isSecure true होता है.
  • supportsEllipticCurve true है, अगर हार्डवेयर में एनआईएसटी कर्व (P-224, P-256, P-384, और P-521) के साथ एलिप्टिक कर्व क्रिप्टोग्राफ़ी की सुविधा काम करती है.
  • supportsSymmetricCryptography true होता है अगर हार्डवेयर, एईएस और एचएमएसी के साथ-साथ सिमेट्रिक क्रिप्टोग्राफ़ी के साथ काम करता है.
  • अगर हार्डवेयर, KeyMaster के सार्वजनिक पासकोड की पुष्टि करने के सर्टिफ़िकेट जनरेट करने की सुविधा देता है, तो supportsAttestation को true माना जाता है. इन सर्टिफ़िकेट को सुरक्षित तरीके से इंजेक्ट करने वाली कुंजी से साइन किया जाता है.

इस तरीके से, गड़बड़ी के सिर्फ़ ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED या गड़बड़ी के कोड ही दिखाए जा सकते हैं. ये कोड, सुरक्षित हार्डवेयर से कनेक्ट नहीं हो पाने के बारे में बताते हैं. 

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

कॉन्फ़िगर करो

वर्शन: 2

इस फ़ंक्शन को Keymaster 2 में लॉन्च किया गया था और Keymaster 3 में बंद कर दिया गया था. इसकी वजह यह है कि यह जानकारी सिस्टम प्रॉपर्टी फ़ाइलों में उपलब्ध होती है और मैन्युफ़ैक्चरर के लागू होने की प्रोसेस, स्टार्टअप के दौरान उन फ़ाइलों को पढ़ती है.

कीमास्टर को कॉन्फ़िगर करता है. डिवाइस खुलने के बाद और उसका इस्तेमाल करने से पहले, इस तरीके को एक बार कॉल किया जाता है. इसका इस्तेमाल, keymaster को KM_TAG_OS_VERSION और KM_TAG_OS_PATCHLEVEL देने के लिए किया जाता है. जब तक इस तरीके को कॉल नहीं किया जाता, तब तक अन्य सभी तरीके KM_ERROR_KEYMASTER_NOT_CONFIGURED दिखाते हैं. इस तरीके से दी गई वैल्यू को कीमास्टर, हर बूट के लिए सिर्फ़ एक बार स्वीकार करती है. इसके बाद के कॉल, KM_ERROR_OK दिखाते हैं, लेकिन कुछ नहीं करते.

अगर पासकोड मैनेजर को सुरक्षित हार्डवेयर में लागू किया गया है और दिए गए ओएस वर्शन और पैच लेवल की वैल्यू, बूटलोडर से सुरक्षित हार्डवेयर को दी गई वैल्यू से मेल नहीं खाती हैं (या बूटलोडर ने वैल्यू नहीं दी हैं), तो यह तरीका KM_ERROR_INVALID_ARGUMENT दिखाता है. साथ ही, अन्य सभी तरीके KM_ERROR_KEYMASTER_NOT_CONFIGURED दिखाते रहेंगे.

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

addRngEntropy

वर्शन: 1, 2, 3

इस फ़ंक्शन को Keymaster 1 में add_rng_entropy के तौर पर लॉन्च किया गया था और Keymaster 3 में इसका नाम बदल दिया गया.

कुंजी, IV, वगैरह के लिए रैंडम नंबर जनरेट करने के लिए, KeyMaster 1 को लागू करने वाले पूल में कॉलर से मिली एंट्रॉपी जोड़ता है.

Keymaster लागू करने के लिए, दिए गए एन्ट्रापी को अपने पूल में सुरक्षित तरीके से मिलाना ज़रूरी है. इसमें, हार्डवेयर रैंडम नंबर जनरेटर से जनरेट किया गया एन्ट्रापी भी शामिल होना चाहिए. डेटा को इस तरह मिक्स किया जाना चाहिए कि addRngEntropy से मिले बिट या हार्डवेयर से जनरेट हुए बिट, दोनों पर पूरी तरह कंट्रोल रखने वाले हमलावर को, एन्ट्रापी पूल से जनरेट हुए बिट का अनुमान लगाने में कोई फ़ायदा न मिले.

Keymaster के ऐसे लागू होने की कोशिश करने वाले जो अपने इंटरनल पूल में एन्ट्रापी का अनुमान लगाते हैं, वे यह मानते हैं कि addRngEntropy से मिले डेटा में कोई एन्ट्रापी नहीं है. अगर Keymaster को एक ही कॉल में 2 से ज़्यादा कि॰ब॰ डेटा दिया जाता है, तो वह ErrorCode::INVALID_INPUT_LENGTH दिखा सकता है.

generateKey

वर्शन: 1, 2, 3

यह फ़ंक्शन कीमास्टर 1 में generate_key के तौर पर शुरू हुआ था और इसका नाम KeyMaster 3 में रखा गया.

इससे एक नई क्रिप्टोग्राफ़िक कुंजी जनरेट होती है. इसमें, उससे जुड़ी अनुमतियां भी शामिल होती हैं, जो कुंजी से हमेशा जुड़ी रहती हैं. KeyMaster लागू करने की वजह से किसी कुंजी का इस्तेमाल, जनरेशन के समय तय की गई अनुमतियों के साथ नहीं किया जा सकता. जिन अनुमतियों को सुरक्षित हार्डवेयर लागू नहीं कर सकता उनके लिए, सुरक्षित हार्डवेयर की ज़िम्मेदारी सिर्फ़ यह पक्का करना है कि कुंजी से जुड़ी उन अनुमतियों में बदलाव न किया जा सके जिन्हें लागू नहीं किया जा सकता. इससे, getKeyCharacteristics को हर बार कॉल करने पर मूल वैल्यू दिखती है. इसके अलावा, generateKey से मिली विशेषताओं की मदद से, अनुमतियों को हार्डवेयर और सॉफ़्टवेयर से लागू होने वाली सूचियों के बीच सही तरीके से बांटा जाता है. ज़्यादा जानकारी के लिए, getKeyCharacteristics देखें.

generateKey फ़ंक्शन में दिए गए पैरामीटर, जनरेट की जा रही कुंजी के टाइप पर निर्भर करते हैं. इस सेक्शन में, हर तरह की कुंजी के लिए ज़रूरी और वैकल्पिक टैग की खास जानकारी दी गई है. टाइप की जानकारी देने के लिए, Tag::ALGORITHM का इस्तेमाल करना हमेशा ज़रूरी होता है.

आरएसए कुंजियां

आरएसए पासकोड जनरेट करने के लिए, ये पैरामीटर ज़रूरी हैं.

  • Tag::KEY_SIZE सार्वजनिक मॉड्यूल का साइज़, बिट में बताता है. अगर इसे छोड़ दिया जाता है, तो यह तरीका ErrorCode::UNSUPPORTED_KEY_SIZE दिखाता है. इसके लिए, 1024, 2048, 3072, और 4096 वैल्यू डाली जा सकती हैं. सुझाई गई वैल्यू, ऐसे सभी पासकोड साइज़ हैं जो 8 के मल्टीपल हैं.
  • Tag::RSA_PUBLIC_EXPONENT आरएसए सार्वजनिक एक्सपोनेंट की वैल्यू बताता है. अगर इसे छोड़ दिया जाता है, तो यह तरीका ErrorCode::INVALID_ARGUMENT दिखाता है. इन वैल्यू का इस्तेमाल किया जा सकता है: 3 और 65537. सुझाई गई वैल्यू, 2^64 तक की सभी प्राइम वैल्यू हैं.

आरएसए कुंजी जनरेट करने के लिए, नीचे दिए गए पैरामीटर ज़रूरी नहीं हैं. हालांकि, इनके बिना आरएसए कुंजी बनाने पर, ऐसी कुंजी बनती है जिसका इस्तेमाल नहीं किया जा सकता. हालांकि, अगर इन पैरामीटर को छोड़ दिया जाता है, तो generateKey फ़ंक्शन कोई गड़बड़ी नहीं दिखाता.

  • Tag::PURPOSE से, अनुमति वाले मकसद के बारे में पता चलता है. आरएसए कुंजियों के लिए, सभी कामों के लिए काम करना चाहिए.
  • टैग::DIGEST डाइजेस्ट एल्गोरिदम के बारे में बताता है जिसे नई कुंजी के साथ इस्तेमाल किया जा सकता है. डाइजेस्ट के सभी एल्गोरिदम के साथ काम न करने वाले वर्शन को लागू करने के लिए, कुंजी जनरेट करने के ऐसे अनुरोधों को स्वीकार करना होगा जिनमें काम न करने वाले डाइजेस्ट शामिल हों. काम न करने वाले डाइजेस्ट को, रिटर्न की गई मुख्य विशेषताओं में "सॉफ़्टवेयर से लागू" सूची में रखा जाना चाहिए. ऐसा इसलिए है, क्योंकि कुंजी को अन्य डाइजेस्ट के साथ इस्तेमाल किया जा सकता है, लेकिन डाइजेस्ट करने का काम सॉफ़्टवेयर में किया जाता है. इसके बाद, Digest::NONE के साथ ऑपरेशन करने के लिए हार्डवेयर को कॉल किया जाता है.
  • Tag::PADDING, पैडिंग के उन मोड के बारे में बताता है जिनका इस्तेमाल नई कुंजी के साथ किया जा सकता है. अगर डिजेस्ट एल्गोरिदम के इस्तेमाल की जानकारी दी गई है, तो ऐसे एल्गोरिदम के लिए, PaddingMode::RSA_PSS और PaddingMode::RSA_OAEP को मुख्य विशेषताओं की सूची में शामिल करना होगा. ऐसा उन एल्गोरिदम के लिए करना होगा जो काम नहीं करते.

ईसीडीएसए कुंजियां

ECDSA कुंजी जनरेट करने के लिए, सिर्फ़ Tag::KEY_SIZE ज़रूरी है. इसका इस्तेमाल ईसी ग्रुप को चुनने के लिए किया जाता है. इन वैल्यू का इस्तेमाल किया जा सकता है: 224, 256, 384, और 521. ये वैल्यू, क्रमशः NIST p-224, p-256, p-384, और p521 कर्व दिखाती हैं.

Tag::DIGEST काम की ईसीडीएसए कुंजी के लिए भी ज़रूरी है, लेकिन जनरेट करने के लिए यह ज़रूरी नहीं है.

AES कुंजियां

AES कुंजी जनरेट करने के लिए, सिर्फ़ Tag::KEY_SIZE ज़रूरी होता है. अगर इसे छोड़ दिया जाता है, तो यह तरीका ErrorCode::UNSUPPORTED_KEY_SIZE दिखाता है. इन वैल्यू का इस्तेमाल किया जा सकता है: 128 और 256. साथ ही, 192-बिट एईएस कुंजियों के लिए वैकल्पिक सहायता भी उपलब्ध है.

नीचे दिए गए पैरामीटर, खास तौर पर AES पासकोड के लिए ज़रूरी हैं. हालांकि, इन्हें पासकोड जनरेट करने के लिए इस्तेमाल करना ज़रूरी नहीं है:

  • Tag::BLOCK_MODE, ब्लॉक मोड के बारे में बताता है जिनके साथ नई कुंजी का इस्तेमाल किया जा सकता है.
  • Tag::PADDING उन पैडिंग मोड के बारे में बताता है जिनका इस्तेमाल किया जा सकता है. यह सिर्फ़ ईसीबी और सीबीसी मोड के लिए काम का है.

अगर GCM ब्लॉक मोड की जानकारी दी गई है, तो Tag::MIN_MAC_LENGTH सबमिट करें. अगर इसे छोड़ दिया जाता है, तो यह तरीका ErrorCode::MISSING_MIN_MAC_LENGTH दिखाता है. टैग की वैल्यू 8 का गुणांक है और यह 96 और 128 के बीच होती है.

एचएमएसी कुंजियां

एचएमएसी कुंजी जनरेट करने के लिए, ये पैरामीटर ज़रूरी हैं:

  • Tag::KEY_SIZE 'की' का साइज़ बिट में बताता है. 64 से कम वैल्यू और ऐसी वैल्यू जिनमें 8 का गुणक न हो, इस्तेमाल नहीं की जा सकतीं. 64 से 512 के बीच, आठ के सभी गुणक इस्तेमाल किए जा सकते हैं. ज़्यादा वैल्यू का इस्तेमाल किया जा सकता है.
  • Tag::MIN_MAC_LENGTH एट्रिब्यूट की वैल्यू से, इस कुंजी से जनरेट किए जा सकने वाले या पुष्टि किए जा सकने वाले एमएसी की कम से कम लंबाई तय होती है. वैल्यू, आठ की múltiplo है और कम से कम 64 है.
  • टैग::DIGEST कुंजी के डाइजेस्ट एल्गोरिदम के बारे में बताता है. सिर्फ़ एक डाइजेस्ट दिया गया हो. ऐसा न होने पर, ErrorCode::UNSUPPORTED_DIGEST दिखाएं. अगर ट्रस्टलेट में डाइजेस्ट काम नहीं करता है, तो ErrorCode::UNSUPPORTED_DIGEST दिखाएं.

मुख्य विशेषताएं

अगर characteristics आर्ग्युमेंट में कोई वैल्यू दी गई है, तो generateKey, नए जनरेट किए गए पासकोड की विशेषताओं को, हार्डवेयर और सॉफ़्टवेयर के हिसाब से बांटकर दिखाता है. कौनसी विशेषताओं को किस सूची में शामिल किया जाए, इसकी जानकारी के लिए getKeyCharacteristics देखें. रिटर्न एट्रिब्यूट में, Tag::APPLICATION_ID और Tag::APPLICATION_DATA को छोड़कर, कुंजी जनरेट करने के लिए तय किए गए सभी पैरामीटर शामिल होते हैं. अगर इन टैग को मुख्य पैरामीटर में शामिल किया गया था, तो उन्हें दिखाए गए एट्रिब्यूट से हटा दिया जाता है, ताकि दिखाए गए की-ब्लॉब की जांच करके उनकी वैल्यू न मिल सके. हालांकि, ये एन्क्रिप्शन की मदद से, पासकोड ब्लॉब से जुड़े होते हैं. इसलिए, अगर पासकोड का इस्तेमाल करते समय सही वैल्यू नहीं दी जाती हैं, तो पासकोड का इस्तेमाल नहीं किया जा सकता. इसी तरह, Tag::ROOT_OF_TRUST को पासकोड से क्रिप्टोग्राफ़िक तरीके से जोड़ा जाता है. हालांकि, पासकोड बनाने या इंपोर्ट करने के दौरान इसकी जानकारी नहीं दी जा सकती और इसे कभी भी नहीं दिखाया जाता.

दिए गए टैग के अलावा, ट्रस्टलेट KeyOrigin::GENERATED वैल्यू के साथ Tag::ORIGIN भी जोड़ता है. अगर पासकोड को वापस नहीं लाया जा सकता, तो

Tag::ROLLBACK_RESISTANT.

रोलबैक रेज़िस्टेंस (कुंजी का दोबारा इस्तेमाल न हो पाना)

रोलबैक रेज़िस्टेंस का मतलब है कि deleteKey या deleteAllKeys का इस्तेमाल करके किसी पासकोड को मिटाने के बाद, उसे फिर से इस्तेमाल नहीं किया जा सकता. ऐसा, सुरक्षित हार्डवेयर की मदद से किया जाता है. रोलबैक रेज़िस्टेंस के बिना लागू करने पर, आम तौर पर कॉलर को की ब्लॉब के तौर पर जनरेट या इंपोर्ट किया गया मुख्य कॉन्टेंट वापस मिलता है. यह एक एन्क्रिप्ट किया गया और पुष्टि किया गया फ़ॉर्म है. जब पासकोड स्टोर, पासकोड ब्लॉब को मिटा देता है, तो पासकोड हट जाता है. हालांकि, अगर कोई हमलावर पहले पासकोड का डेटा वापस पा लेता है, तो वह उसे डिवाइस पर वापस ला सकता है.

अगर सुरक्षित हार्डवेयर इस बात की गारंटी देता है कि मिटाई गई कुंजियों को बाद में वापस नहीं पाया जा सकता, तो उस कुंजी को रोलबैक नहीं किया जा सकता. आम तौर पर, ऐसा किसी भरोसेमंद जगह पर अतिरिक्त कुंजी का मेटाडेटा सेव करके किया जाता है. इस मेटाडेटा में हमलावर हेर-फेर नहीं कर सकता. मोबाइल डिवाइसों पर, आम तौर पर रिप्ले प्रोटेक्टेड मेमोरी ब्लॉक (आरपीएमबी) का इस्तेमाल किया जाता है. बनाई जा सकने वाली कुंजियों की संख्या निश्चित तौर पर अनबाउंड होती है और रोलबैक रेज़िस्टेंस के लिए इस्तेमाल किए जाने वाले भरोसेमंद स्टोरेज का साइज़ सीमित हो सकता है. इसलिए, इस तरीके को सफल होना ज़रूरी है, भले ही नई कुंजी के लिए रोलबैक रेज़िस्टेंस न दिया जा सकता हो. ऐसे में, मुख्य विशेषताओं में Tag::ROLLBACK_RESISTANT को नहीं जोड़ा जाना चाहिए.

getKeyCharacteristics

वर्शन: 1, 2, 3

इस फ़ंक्शन को KeyMaster 1 में get_key_characteristics के तौर पर शुरू किया गया था और इसका नाम KeyMaster 3 में बदला गया.

यह, दी गई कुंजी से जुड़े पैरामीटर और अनुमतियां दिखाता है. इन्हें दो सेट में बांटा गया है: हार्डवेयर से लागू होने वाली अनुमतियां और सॉफ़्टवेयर से लागू होने वाली अनुमतियां. यहां दिया गया ब्यौरा, generateKey और importKey से मिली मुख्य विशेषताओं की सूचियों पर भी लागू होता है.

अगर कुंजी जनरेट या इंपोर्ट करने के दौरान Tag::APPLICATION_ID दिया गया था, तो clientId आर्ग्युमेंट में इस तरीके के लिए वही वैल्यू दी जाती है. ऐसा न होने पर, तरीका ErrorCode::INVALID_KEY_BLOB दिखाता है. इसी तरह, अगर जनरेट करने या इंपोर्ट करने के दौरान Tag::APPLICATION_DATA दिया गया था, तो appData आर्ग्युमेंट में इस तरीके के लिए वही वैल्यू दी जाती है.

इस तरीके से मिलने वाली विशेषताएं, बताई गई कुंजी के टाइप और इस्तेमाल के बारे में पूरी जानकारी देती हैं.

यह तय करने का सामान्य नियम है कि कोई टैग, हार्डवेयर से लागू होने वाली पाबंदियों की सूची में आता है या सॉफ़्टवेयर से लागू होने वाली पाबंदियों की सूची में, यह इस बात पर निर्भर करता है कि टैग का मतलब, सुरक्षित हार्डवेयर से पूरी तरह से पक्का किया गया है या नहीं. ऐसा न करने पर, इसे सॉफ़्टवेयर से लागू किया जाता है. यहां कुछ खास टैग की सूची दी गई है, जिनके सही ऐलोकेशन के बारे में शायद साफ़ तौर पर न पता हो:

  • टैग::ALGORITHM, Tag::KEY_SIZE, और टैग::RSA_PUBLIC_EXPONENT कुंजी की मूल प्रॉपर्टी हैं. हार्डवेयर से सुरक्षित की गई किसी भी कुंजी के लिए, ये टैग, हार्डवेयर से लागू की गई सूची में होते हैं.
  • Tag::DIGEST की ऐसी वैल्यू जो सुरक्षित हार्डवेयर के साथ काम करती हैं उन्हें हार्डवेयर के साथ काम करने वाली सूची में रखा जाता है. काम न करने वाले डाइजेस्ट, काम करने वाले सॉफ़्टवेयर की सूची में शामिल हो जाते हैं.
  • Tag::PADDING वैल्यू, आम तौर पर हार्डवेयर के साथ काम करने वाले डिवाइसों की सूची में शामिल होती हैं. ऐसा तब तक होता है, जब तक कि किसी खास पैडिंग मोड को सॉफ़्टवेयर से पूरा नहीं किया जाता. ऐसे में, उन्हें सॉफ़्टवेयर से लागू होने वाली पाबंदियों की सूची में शामिल किया जाता है. ऐसा उन आरएसए कुंजियों के लिए हो सकता है जो ऐसे डाइजेस्ट एल्गोरिदम के साथ PSS या OAEP पैडिंग की अनुमति देते हैं जो सुरक्षित हार्डवेयर के साथ काम नहीं करते.
  • Tag::USER_SECURE_ID और Tag::USER_AUTH_TYPE हार्डवेयर का इस्तेमाल सिर्फ़ तब किया जाता है, जब उपयोगकर्ता की पुष्टि करने की सुविधा हार्डवेयर से लागू की गई हो. ऐसा करने के लिए, Keymaster ट्रस्टलेट और पुष्टि करने वाले ट्रस्टलेट, दोनों को सुरक्षित होना चाहिए. साथ ही, दोनों को एक ऐसी एचएमएसी कुंजी शेयर करनी चाहिए जिसका इस्तेमाल, पुष्टि करने वाले टोकन पर हस्ताक्षर करने और उनकी पुष्टि करने के लिए किया जाता है. ज़्यादा जानकारी के लिए, पुष्टि पेज देखें.
  • Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME, और Tag::USAGE_EXPIRE_DATETIME टैग के लिए, ऐसी दीवार घड़ी का ऐक्सेस ज़रूरी है जिसकी पुष्टि की जा सके. ज़्यादातर सुरक्षित हार्डवेयर के पास, सिर्फ़ उस समय की जानकारी का ऐक्सेस होता है जो असुरक्षित ओएस से मिलती है. इसका मतलब है कि टैग, सॉफ़्टवेयर से लागू होते हैं.
  • हार्डवेयर से जुड़ी कुंजियों के लिए, Tag::ORIGIN हमेशा हार्डवेयर की सूची में शामिल होता है. इस सूची में मौजूद होने का मतलब है कि ऊपर की लेयर यह तय करती हैं कि कुंजी, हार्डवेयर से सुरक्षित है या नहीं.

importKey

वर्शन: 1, 2, 3

इस फ़ंक्शन को Keymaster 1 में import_key के तौर पर लॉन्च किया गया था और Keymaster 3 में इसका नाम बदल दिया गया.

Keymaster हार्डवेयर में पासकोड इंपोर्ट करता है. मुख्य परिभाषा पैरामीटर और आउटपुट की विशेषताओं को generateKey की तरह ही मैनेज किया जाता है. हालांकि, इनमें ये अपवाद हैं:

  • इनपुट पैरामीटर में, Tag::KEY_SIZE और Tag::RSA_PUBLIC_EXPONENT (सिर्फ़ आरएसए कुंजियों के लिए) ज़रूरी नहीं है. अगर यह वैल्यू नहीं दी गई है, तो ट्रस्टलेट, दी गई मुख्य सामग्री से वैल्यू का पता लगाता है. साथ ही, मुख्य विशेषताओं के लिए सही टैग और वैल्यू जोड़ता है. अगर पैरामीटर दिए जाते हैं, तो ट्रस्टलेट उनकी पुष्टि, पासकोड के आधार पर करता है. अगर वैल्यू मेल नहीं खाती है, तो यह तरीका ErrorCode::IMPORT_PARAMETER_MISMATCH दिखाता है.
  • लौटाए गए Tag::ऑरिजिन की वैल्यू वही है जो KeyOrigin::IMPORTED है.

exportKey

वर्शन: 1, 2, 3

यह फ़ंक्शन कीमास्टर 1 में export_key के तौर पर शुरू हुआ था और इसका नाम KeyMaster 3 में रखा गया.

Keymaster आरएसए या ईसी पासकोड पेयर से सार्वजनिक पासकोड एक्सपोर्ट करता है.

अगर कुंजी जनरेट करने या इंपोर्ट करने के दौरान Tag::APPLICATION_ID दिया गया था, तो clientId आर्ग्युमेंट में इस तरीके के लिए वही वैल्यू दी जाती है. ऐसा न होने पर, यह तरीका ErrorCode::INVALID_KEY_BLOB दिखाता है. इसी तरह, अगर जनरेट करने या इंपोर्ट करने के दौरान Tag::APPLICATION_DATA दी गई थी, तो appData आर्ग्युमेंट में इस तरीके के लिए वही वैल्यू दी जाती है.

deleteKey

वर्शन: 1, 2, 3

इस फ़ंक्शन को Keymaster 1 में delete_key के तौर पर लॉन्च किया गया था और Keymaster 3 में इसका नाम बदल दिया गया.

दी गई कुंजी को मिटाता है. यह तरीका ज़रूरी नहीं है. इसे सिर्फ़ ऐसे Keymaster मॉड्यूल लागू करते हैं जो रोलबैक रेज़िस्टेंस देते हैं.

DeleteAllKeys

वर्शन: 1, 2, 3

इस फ़ंक्शन को Keymaster 1 में delete_all_keys के तौर पर लॉन्च किया गया था और Keymaster 3 में इसका नाम बदल दिया गया.

सभी कुंजियों को मिटाता है. यह तरीका ज़रूरी नहीं है. इसे सिर्फ़ ऐसे Keymaster मॉड्यूल लागू करते हैं जो रोलबैक रेज़िस्टेंस देते हैं.

प्रमाणित करने वाले आईडी बंद करें

वर्शन: 3

destroyAttestationIds() तरीके का इस्तेमाल, नई (ज़रूरी नहीं, लेकिन खास तौर पर सुझाया गया) आईडी की पुष्टि करने की सुविधा को हमेशा के लिए बंद करने के लिए किया जाता है. अगर टीईई के पास यह पक्का करने का कोई तरीका नहीं है कि इस तरीके को कॉल करने के बाद, आईडी की पुष्टि की सुविधा हमेशा के लिए बंद हो गई है, तो आईडी की पुष्टि की सुविधा को बिलकुल भी लागू नहीं किया जाना चाहिए. इस मामले में, यह तरीका कुछ नहीं करता और ErrorCode::UNIMPLEMENTED दिखाता है. अगर आईडी की पुष्टि करने की सुविधा काम करती है, तो इस तरीके को लागू करना ज़रूरी है. साथ ही, आने वाले समय में आईडी की पुष्टि करने की सभी कोशिशों को हमेशा के लिए बंद करना होगा. इस तरीके को कितनी बार भी कॉल किया जा सकता है. अगर आईडी से पुष्टि करने की सुविधा हमेशा के लिए बंद है, तो यह तरीका कुछ नहीं करता और ErrorCode::OK दिखाता है.

इस तरीके से सिर्फ़ ये गड़बड़ी कोड दिख सकते हैं: ErrorCode::UNIMPLEMENTED (अगर आईडी की पुष्टि करने की सुविधा काम नहीं करती), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED या सुरक्षित हार्डवेयर के साथ कम्यूनिकेट करने में हुई गड़बड़ी का कोई एक कोड.

शुरू करें

वर्शन: 1, 2, 3

यह फ़ंक्शन, तय की गई कुंजी का इस्तेमाल करके, तय किए गए मकसद के लिए, तय किए गए पैरामीटर के साथ क्रिप्टोग्राफ़िक ऑपरेशन शुरू करता है. साथ ही, ऑपरेशन को पूरा करने के लिए, update और finish के साथ इस्तेमाल किया जाने वाला ऑपरेशन हैंडल दिखाता है. पुष्टि किए गए ऑपरेशन में, ऑपरेशन हैंडल का इस्तेमाल "चैलेंज" टोकन के तौर पर भी किया जाता है. साथ ही, ऐसे ऑपरेशन के लिए, पुष्टि करने वाले टोकन के challenge फ़ील्ड में शामिल किया जाता है.

Keymaster लागू करने पर, एक साथ कम से कम 16 ऑपरेशन किए जा सकते हैं. कीस्टोर 15 तक का उपयोग करता है, जिसमें एक को पासवर्ड एन्क्रिप्शन के लिए वॉल्ड के रूप में छोड़ दिया जाता है. जब कीस्टोर में 15 कार्रवाइयां चल रही हैं (begin को कॉल किया जा चुका है, लेकिन finish या abort को कॉल नहीं किया गया है) और उसे 16 तारीख को शुरू करने का अनुरोध मिलता है, तो वह सबसे कम इस्तेमाल की गई कार्रवाई abort को कम करके begin को कॉल करने से पहले, सबसे कम इस्तेमाल की गई कार्रवाई को कम करके 14 कर देता है.

अगर कुंजी जनरेट करने या इंपोर्ट करने के दौरान, Tag::APPLICATION_ID या Tag::APPLICATION_DATA तय किए गए थे, तो begin के कॉल में उन टैग को शामिल किया जाता है जिनकी वैल्यू, इस तरीके के inParams आर्ग्युमेंट में मूल रूप से तय की गई थी.

अनुमति लागू करना

इस तरीके के दौरान, ट्रस्टलेट इन कुंजियों के लिए अनुमति देता है. ऐसा तब होता है, जब लागू करने के दौरान उन्हें "हार्डवेयर से लागू की गई" विशेषताओं में रखा गया हो और कार्रवाई, सार्वजनिक कुंजी से जुड़ी कार्रवाई न हो. आरएसए या ईसी कुंजियों के साथ, सार्वजनिक कुंजी के ऑपरेशन, यानी KeyPurpose::ENCRYPT और KeyPurpose::VERIFY को अनुमति की ज़रूरी शर्तें पूरी न होने पर भी पूरा करने की अनुमति है.

  • Tag::PURPOSE: begin() कॉल में बताए गए मकसद को, पासकोड की अनुमतियों में बताए गए किसी एक मकसद से मैच करना होगा. ऐसा तब तक करना होगा, जब तक अनुरोध किया गया ऑपरेशन, सार्वजनिक पासकोड से जुड़ा ऑपरेशन न हो. अगर बताई गई वजह मेल नहीं खाती और कार्रवाई, सार्वजनिक कुंजी से जुड़ी कार्रवाई नहीं है, तो begin ErrorCode::UNSUPPORTED_PURPOSE दिखाता है. सार्वजनिक पासकोड से जुड़ी कार्रवाइयां, ऐसिमेट्रिक एन्क्रिप्शन या पुष्टि करने की कार्रवाइयां होती हैं.
  • टैग::ACTIVE_DATETIME को सिर्फ़ तब लागू किया जा सकता है, जब कोई भरोसेमंद यूटीसी टाइम सोर्स उपलब्ध हो. अगर मौजूदा तारीख और समय, टैग की वैल्यू से पहले का है, तो यह तरीका ErrorCode::KEY_NOT_YET_VALID दिखाता है.
  • Tag::ORIGINATION_EXPIRE_DATETIME एट्रिब्यूट का इस्तेमाल सिर्फ़ तब किया जा सकता है, जब यूटीसी टाइम सोर्स उपलब्ध हो. अगर मौजूदा तारीख और समय, टैग की वैल्यू से बाद का है और मकसद KeyPurpose::ENCRYPT या KeyPurpose::SIGN है, तो यह तरीका ErrorCode::KEY_EXPIRED दिखाता है.
  • Tag::USAGE_EXPIRE_DATETIME एट्रिब्यूट का इस्तेमाल सिर्फ़ तब किया जा सकता है, जब भरोसेमंद यूटीसी टाइम सोर्स उपलब्ध हो. अगर मौजूदा तारीख और समय, टैग की वैल्यू से बाद का है और मकसद KeyPurpose::DECRYPT या KeyPurpose::VERIFY है, तो यह तरीका ErrorCode::KEY_EXPIRED दिखाता है.
  • Tag::MIN_SECONDS_BETWEEN_OPS की तुलना, भरोसेमंद रिलेटिव टाइमर से की जाती है. इससे, कुंजी के आखिरी इस्तेमाल की जानकारी मिलती है. अगर आखिरी बार इस्तेमाल करने का समय और टैग की वैल्यू, मौजूदा समय से कम है, तो यह तरीका ErrorCode::KEY_RATE_LIMIT_EXCEEDED दिखाता है. लागू करने से जुड़ी ज़रूरी जानकारी के लिए, टैग की जानकारी देखें.
  • Tag::MAX_USES_PER_BOOT की तुलना, एक सुरक्षित काउंटर से की जाती है. यह काउंटर, डिवाइस के चालू होने के बाद से कुंजी के इस्तेमाल को ट्रैक करता है. अगर पिछले इस्तेमाल की संख्या, टैग की वैल्यू से ज़्यादा है, तो यह तरीका ErrorCode::KEY_MAX_OPS_EXCEEDED दिखाता है.
  • Tag::USER_SECURE_ID को इस तरीके से सिर्फ़ तब लागू किया जाता है, जब पासकोड में Tag::AUTH_TIMEOUT भी मौजूद हो. अगर कुंजी में दोनों हैं, तो इस तरीके को inParams में एक मान्य Tag::AUTH_TOKEN मिलना चाहिए. पुष्टि करने वाला टोकन मान्य हो, इसके लिए ये सभी बातें सही होनी चाहिए:
    • HMAC फ़ील्ड की पुष्टि सही तरीके से की गई हो.
    • पासकोड में मौजूद कम से कम एक Tag::USER_SECURE_ID वैल्यू, टोकन में मौजूद कम से कम एक सुरक्षित आईडी वैल्यू से मेल खाती हो.
    • कुंजी में एक Tag::USER_AUTH_TYPE है, जो टोकन में पुष्टि करने के तरीके से मेल खाता है.

    अगर इनमें से कोई भी शर्त पूरी नहीं होती है, तो यह तरीका ErrorCode::KEY_USER_NOT_AUTHENTICATED दिखाता है.

  • Tag::CALLER_NONCE की मदद से, कॉलर कोई नॉन्स या इनिशिएलाइज़ेशन वेक्टर (IV) तय कर सकता है. अगर पासकोड में यह टैग नहीं है, लेकिन कॉलर ने इस तरीके के लिए Tag::NONCE दिया है, तो ErrorCode::CALLER_NONCE_PROHIBITED दिखाया जाता है.
  • Tag::BOOTLOADER_ONLY इससे पता चलता है कि कुंजी का इस्तेमाल सिर्फ़ बूटलोडर कर सकता है. अगर बूटलोडर के काम पूरा हो जाने के बाद, इस तरीके को सिर्फ़ बूटलोडर पासकोड के साथ कॉल किया जाता है, तो यह ErrorCode::INVALID_KEY_BLOB दिखाता है.

आरएसए कुंजियां

आरएसए कुंजी के सभी ऑपरेशन, inParams में सिर्फ़ एक पैडिंग मोड तय करते हैं. अगर कोई वैल्यू नहीं दी गई है या एक से ज़्यादा बार बताया गया है, तो यह तरीका ErrorCode::UNSUPPORTED_PADDING_MODE दिखाता है.

आरएसए साइनिंग और पुष्टि करने की कार्रवाइयों के लिए डाइजेस्ट की ज़रूरत होती है. OAEP पैडिंग मोड के साथ आरएसए एन्क्रिप्शन और डिक्रिप्शन की कार्रवाइयों के लिए भी डाइजेस्ट की ज़रूरत होती है. ऐसे मामलों में, कॉलर inParams में सिर्फ़ एक डाइजेस्ट तय करता है. अगर तय नहीं किया गया है या एक से ज़्यादा बार बताया गया है, तो यह तरीका ErrorCode::UNSUPPORTED_DIGEST दिखाता है.

निजी कुंजी के ऑपरेशन (KeyPurpose::DECYPT और KeyPurpose::SIGN) के लिए, डाइजेस्ट और पैडिंग की अनुमति की ज़रूरत होती है. इसका मतलब है कि कुंजी की अनुमतियों में बताई गई वैल्यू होनी चाहिए. अगर ऐसा नहीं है, तो यह तरीका ErrorCode::INCOMPATIBLE_DIGEST या ErrorCode::INCOMPATIBLE_PADDING दिखाता है. बिना अनुमति वाले डाइजेस्ट या पैडिंग के साथ, सार्वजनिक कुंजी वाले ऑपरेशन (KeyPurpose::ENCRYPT और KeyPurpose::VERIFY) की अनुमति है.

PaddingMode::NONE को छोड़कर, आरएसए पैडिंग के सभी मोड सिर्फ़ कुछ कामों के लिए लागू होते हैं. खास तौर पर, PaddingMode::RSA_PKCS1_1_5_SIGN और PaddingMode::RSA_PSS सिर्फ़ हस्ताक्षर करने और पुष्टि करने की सुविधा देते हैं. वहीं, PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT और PaddingMode::RSA_OAEP सिर्फ़ एन्क्रिप्ट (सुरक्षित) और डिक्रिप्ट (सुरक्षित करने की प्रक्रिया को वापस पहले जैसा करना) करने की सुविधा देते हैं. अगर तय किया गया मोड, तय किए गए मकसद के साथ काम नहीं करता है, तो यह तरीका ErrorCode::UNSUPPORTED_PADDING_MODE दिखाता है.

पैडिंग मोड और डाइजेस्ट के बीच कुछ अहम इंटरैक्शन होते हैं:

  • PaddingMode::NONE से पता चलता है कि "रॉ" आरएसए ऑपरेशन किया गया है. अगर हस्ताक्षर या पुष्टि की जा रही है, तो डाइजेस्ट के लिए Digest::NONE का इस्तेमाल किया जाता है. बिना पैड वाले एन्क्रिप्शन या डिक्रिप्शन के लिए, कोई डाइजेस्ट ज़रूरी नहीं है.
  • PaddingMode::RSA_PKCS1_1_5_SIGN पैडिंग के लिए, डाइजेस्ट की ज़रूरत होती है. डाइजेस्ट Digest::NONE हो सकता है. ऐसे में, Keymaster लागू करने पर, सही PKCS#1 v1.5 हस्ताक्षर स्ट्रक्चर नहीं बनाया जा सकता, क्योंकि यह DigestInfo स्ट्रक्चर नहीं जोड़ सकता. इसके बजाय, लागू करने की प्रोसेस में 0x00 || 0x01 || PS || 0x00 || M को बनाया जाता है, जहां दिया गया मैसेज M है और PS पैडिंग स्ट्रिंग है. आरएसए कुंजी का साइज़, मैसेज से कम से कम 11 बाइट बड़ा होना चाहिए. ऐसा न होने पर, यह तरीका ErrorCode::INVALID_INPUT_LENGTH दिखाता है.
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT पैडिंग के लिए, डाइजेस्ट की ज़रूरत नहीं होती.
  • PaddingMode::RSA_PSS पैडिंग के लिए डाइजेस्ट की ज़रूरत होती है, जो Digest::NONE नहीं हो सकता. अगर Digest::NONE तय किया गया है, तो तरीका ErrorCode::INCOMPATIBLE_DIGEST दिखाता है. इसके अलावा, आरएसए कुंजी का साइज़, डाइजेस्ट के आउटपुट साइज़ से कम से कम दो + D बाइट होना चाहिए. इसमें D, बाइट में डाइजेस्ट का साइज़ है. ऐसा न होने पर, यह तरीका ErrorCode::INCOMPATIBLE_DIGEST दिखाता है. नमक का साइज़ D है.
  • PaddingMode::RSA_OAEP पैडिंग के लिए एक डाइजेस्ट की ज़रूरत होती है, जो Digest::NONE नहीं हो सकता. अगर Digest::NONE तय किया गया है, तो यह तरीका ErrorCode::INCOMPATIBLE_DIGEST दिखाता है.

ईसी कुंजियां

ईसी पासकोड के ऑपरेशन, inParams में सिर्फ़ एक पैडिंग मोड तय करते हैं. अगर तय नहीं किया गया है या एक से ज़्यादा बार बताया गया है, तो तरीका ErrorCode::UNSUPPORTED_PADDING_MODE दिखाता है.

निजी कुंजी से जुड़ी कार्रवाइयों (KeyPurpose::SIGN) को डाइजेस्ट और पैडिंग की अनुमति की ज़रूरत होती है, जिसका मतलब है कि कुंजी की अनुमतियों में तय मान शामिल होने चाहिए. अगर ऐसा नहीं है, तो ErrorCode::INCOMPATIBLE_DIGEST दिखाएं. सार्वजनिक पासकोड से जुड़ी कार्रवाइयों (KeyPurpose::VERIFY) के लिए, अनुमति के बिना डाइजेस्ट या पैडिंग का इस्तेमाल किया जा सकता है.

AES कुंजियां

AES कुंजी कार्रवाइयों से inParams में सिर्फ़ एक ब्लॉक मोड और एक पैडिंग मोड तय होता है. अगर कोई वैल्यू तय नहीं की गई है या एक से ज़्यादा बार तय की गई है, तो ErrorCode::UNSUPPORTED_BLOCK_MODE या ErrorCode::UNSUPPORTED_PADDING_MODE दिखाएं. बताए गए मोड के लिए, पासकोड की अनुमति होनी चाहिए. ऐसा न होने पर, यह तरीका ErrorCode::INCOMPATIBLE_BLOCK_MODE या ErrorCode::INCOMPATIBLE_PADDING_MODE दिखाता है.

अगर ब्लॉक मोड BlockMode::GCM है, तो inParams Tag::MAC_LENGTH तय करता है. साथ ही, बताई गई वैल्यू 8 का मल्टीपल होनी चाहिए, जो 128 से ज़्यादा या पासकोड की अनुमतियों में Tag::MIN_MAC_LENGTH की वैल्यू से कम न हो. अगर एमएसी की लंबाई 128 से ज़्यादा है या 8 का multiple नहीं है, तो ErrorCode::UNSUPPORTED_MAC_LENGTH दिखाएं. अगर वैल्यू, पासकोड की तय सीमा से कम है, तो ErrorCode::INVALID_MAC_LENGTH दिखाएं.

अगर ब्लॉक मोड BlockMode::GCM या BlockMode::CTR है, तो पैडिंग मोड PaddingMode::NONE होना चाहिए. BlockMode::ECB या BlockMode::CBC के लिए, मोड PaddingMode::NONE या PaddingMode::PKCS7 हो सकता है. अगर पैडिंग मोड इन शर्तों को पूरा नहीं करता है, तो ErrorCode::INCOMPATIBLE_PADDING_MODE दिखाएं.

अगर ब्लॉक मोड BlockMode::CBC, BlockMode::CTR या BlockMode::GCM है, तो इनिशलाइज़ेशन वेक्टर या नॉन्स की ज़रूरत होती है. ज़्यादातर मामलों में, कॉल करने वालों को आईवी या नॉन्स देने की ज़रूरत नहीं होती. ऐसे मामले में, KeyMaster लागू करने पर एक रैंडम IV या नॉन्स जनरेट होता है और उसे outParams में Tag::NONCE के साथ वापस भेजा जाता है. CBC और CTR IV, 16 बाइट के होते हैं. GCM नॉन्स 12 बाइट के होते हैं. अगर पासकोड की अनुमतियों में Tag::CALLER_NONCE शामिल है, तो कॉलर inParams में Tag::NONCE के साथ आईवी या नॉन्स दे सकता है. अगर Tag::CALLER_NONCE के पास अनुमति नहीं है, लेकिन कोई नॉन्स दिया गया है, तो ErrorCode::CALLER_NONCE_PROHIBITED दिखाएं. Tag::CALLER_NONCE की अनुमति होने पर, अगर नॉन्स नहीं दिया जाता है, तो कोई भी IV/nonce जनरेट करें.

एचएमएसी कुंजियां

एचएमएसी कुंजी के ऑपरेशन, inParams में Tag::MAC_LENGTH तय करते हैं. दी गई वैल्यू, 8 की गुना होनी चाहिए. यह डाइजेस्ट की लंबाई से ज़्यादा नहीं होनी चाहिए या पासकोड की अनुमतियों में Tag::MIN_MAC_LENGTH की वैल्यू से कम नहीं होनी चाहिए. अगर मैक की लंबाई, डाइजेस्ट की लंबाई से ज़्यादा है या आठ की गुना नहीं है, तो ErrorCode::UNSUPPORTED_MAC_LENGTH दिखाएं. अगर वैल्यू, पासकोड की तय सीमा से कम है, तो ErrorCode::INVALID_MAC_LENGTH दिखाएं.

अपडेट करें

वर्शन: 1, 2, 3

begin से शुरू की गई, चल रही कार्रवाई को प्रोसेस करने के लिए डेटा देता है. कार्रवाई, operationHandle पैरामीटर से तय की जाती है.

बफ़र मैनेज करने के लिए ज़्यादा सुविधाएं देने के लिए, इस तरीके को लागू करने पर, दिए गए डेटा से कम डेटा का इस्तेमाल किया जा सकता है. कॉल करने वाले व्यक्ति को, बाद के कॉल में बाकी डेटा फ़ीड करने के लिए, लूपिंग की ज़िम्मेदारी लेनी होगी. इस्तेमाल किए गए इनपुट की संख्या, inputConsumed पैरामीटर में दिखती है. लागू करने के लिए, कम से कम एक बाइट का इस्तेमाल हमेशा किया जाता है. ऐसा तब तक किया जाता है, जब तक कि ऑपरेशन में एक से ज़्यादा बाइट का इस्तेमाल न किया जा सके. अगर शून्य से ज़्यादा बाइट दिए जाते हैं और शून्य बाइट का इस्तेमाल किया जाता है, तो कॉलर इसे गड़बड़ी मानते हैं और ऑपरेशन को रोक देते हैं.

अपडेट के नतीजे के तौर पर, लागू करने वाले यह भी चुन सकते हैं कि कितना डेटा दिखाना है. यह सिर्फ़ एन्क्रिप्शन और डिक्रिप्शन के लिए काम का है, क्योंकि साइन करने और पुष्टि करने की प्रोसेस पूरी होने तक कोई डेटा नहीं दिखाती. डेटा को बफ़र करने के बजाय, जल्द से जल्द दिखाएं.

गड़बड़ी ठीक करना

अगर यह तरीका ErrorCode::OK के अलावा कोई दूसरा गड़बड़ी कोड दिखाता है, तो ऑपरेशन को रोक दिया जाता है और ऑपरेशन हैंडल अमान्य हो जाता है. इस तरीके का इस्तेमाल करके, हैंडल को बाद में इस्तेमाल करने पर, finish या abort के तौर पर ErrorCode::INVALID_OPERATION_HANDLE दिखता है.

अनुमति लागू करने का तरीका

पासकोड की पुष्टि करने की प्रोसेस, मुख्य रूप से begin में की जाती है. हालांकि, अगर पासकोड में ये चीज़ें शामिल हैं, तो यह अपवाद लागू नहीं होगा:

इस मामले में, हर कार्रवाई के लिए पासकोड की अनुमति की ज़रूरत होती है. साथ ही, अपडेट करने वाले मैथड को inParams आर्ग्युमेंट में Tag::AUTH_TOKEN मिलता है. HMAC इस बात की पुष्टि करता है कि टोकन मान्य है और उसमें मैच करने वाला सुरक्षित उपयोगकर्ता आईडी है. साथ ही, वह कुंजी के Tag::USER_AUTH_TYPE से मैच करता है और चैलेंज फ़ील्ड में मौजूद मौजूदा ऑपरेशन का ऑपरेशन हैंडल है. अगर ये शर्तें पूरी नहीं होती हैं, तो ErrorCode::KEY_USER_NOT_AUTHENTICATED दिखाएं.

कॉल करने वाला व्यक्ति, हर कॉल के लिए पुष्टि करने वाला टोकन उपलब्ध कराता है, ताकि अपडेट और पूरा किया जा सके. अगर टोकन लागू करना है, तो उसे सिर्फ़ एक बार पुष्टि करने की ज़रूरत है.

आरएसए कुंजियां

Digest::NONE से हस्ताक्षर करने और पुष्टि करने की कार्रवाइयों के लिए, यह तरीका पूरे ब्लॉक को एक ही अपडेट में हस्ताक्षर करने या पुष्टि करने के लिए स्वीकार करता है. यह ब्लॉक के सिर्फ़ एक हिस्से का इस्तेमाल नहीं कर सकता. हालांकि, अगर कॉल करने वाला व्यक्ति एक से ज़्यादा अपडेट में डेटा देने का विकल्प चुनता है, तो यह तरीका उसे स्वीकार कर लेता है. अगर कॉलर, हस्ताक्षर करने के लिए ज़्यादा डेटा देता है, तो ErrorCode::INVALID_INPUT_LENGTH दिखाएं. ऐसा तब होता है, जब डेटा का साइज़, आरएसए पासकोड के साइज़ से ज़्यादा हो.

ईसीडीएसए कुंजियां

Digest::NONE के साथ हस्ताक्षर करने और पुष्टि करने के लिए, यह तरीका पूरे ब्लॉक को एक ही अपडेट में हस्ताक्षर करने या पुष्टि करने के लिए स्वीकार करता है. इस तरीके से, ब्लॉक के सिर्फ़ एक हिस्से का इस्तेमाल नहीं किया जा सकता.

हालांकि, अगर कॉल करने वाला व्यक्ति एक से ज़्यादा अपडेट में डेटा देने का विकल्प चुनता है, तो यह तरीका उसे स्वीकार कर लेता है. अगर कॉलर, हस्ताक्षर करने के लिए ज़रूरत से ज़्यादा डेटा उपलब्ध कराता है, तो डेटा में अपने-आप काट-छांट हो जाती है. (यह, मिलते-जुलते आरएसए ऑपरेशन में दिए गए अतिरिक्त डेटा को मैनेज करने से अलग है. ऐसा इसलिए है, क्योंकि यह लेगसी क्लाइंट के साथ काम करता है.)

AES कुंजियां

AES GCM मोड, inParams आर्ग्युमेंट में Tag::ASSOCIATED_DATA टैग के ज़रिए दिए गए "पुष्टि से जुड़े डेटा" के साथ काम करता है. इससे जुड़ा डेटा, बार-बार किए जाने वाले कॉल में दिया जा सकता है. यह तब ज़रूरी होता है, जब एक ही ब्लॉक में भेजने के लिए डेटा काफ़ी बड़ा हो. हालांकि, एन्क्रिप्ट (सुरक्षित) या डिक्रिप्ट (अनचाहे कोड को मूल कोड में बदलना) किए जाने वाले डेटा से पहले, यह डेटा हमेशा दिया जाता है. अपडेट कॉल में, एन्क्रिप्ट (सुरक्षित)/डिक्रिप्ट (सुरक्षित से सामान्य में बदलना) करने के लिए डेटा और उससे जुड़ा डेटा, दोनों शामिल किए जा सकते हैं. हालांकि, इसके बाद के अपडेट में उससे जुड़ा डेटा शामिल नहीं किया जा सकता. अगर कॉलर, एन्क्रिप्ट/डिक्रिप्ट करने के लिए डेटा वाले कॉल के बाद, अपडेट कॉल के लिए उससे जुड़ा डेटा उपलब्ध कराता है, तो ErrorCode::INVALID_TAG दिखाएं.

GCM एन्क्रिप्शन के लिए, टैग को finish की मदद से साइफ़रटेक्स्ट में जोड़ा जाता है. डिक्रिप्शन के दौरान, आखिरी अपडेट कॉल को दिए गए डेटा के आखिरी Tag::MAC_LENGTH बाइट टैग होते हैं. update के किसी एक बार इस्तेमाल करने से यह पता नहीं चलता कि यह आखिरी बार इस्तेमाल किया जा रहा है या नहीं. इसलिए, यह टैग की लंबाई को छोड़कर बाकी सभी चीज़ों को प्रोसेस करता है. साथ ही, finish के दौरान, संभावित टैग डेटा को बफ़र करता है.

पूरा करें

वर्शन: 1, 2, 3

begin से शुरू की गई प्रोसेस को पूरा करता है. साथ ही, update से मिले उस डेटा को प्रोसेस करता है जो अब तक प्रोसेस नहीं हुआ है.

यह तरीका, किसी ऑपरेशन में आखिरी बार कॉल किया जाता है, ताकि प्रोसेस किया गया सारा डेटा दिखाया जा सके.

भले ही, यह कार्रवाई पूरी हो जाए या कोई गड़बड़ी दिखे, यह तरीका कार्रवाई को पूरा कर देता है. इसलिए, दिए गए ऑपरेशन हैंडल को अमान्य कर दिया जाता है. आने वाले समय में, इस तरीके को अपडेट करने या रद्द करने के लिए, हैंडल को इस्तेमाल करने पर ErrorCode::INVALID_OPERATION_HANDLE दिखेगा.

हस्ताक्षर करने की कार्रवाइयां, आउटपुट के तौर पर हस्ताक्षर दिखाती हैं. पुष्टि करने वाले ऑपरेशन, signature पैरामीटर में मौजूद हस्ताक्षर को स्वीकार करते हैं और कोई आउटपुट नहीं दिखाते.

अनुमति लागू करना

पासकोड की पुष्टि करने की प्रोसेस, मुख्य तौर पर begin में की जाती है. एक अपवाद यह है कि कुंजी में:

इस मामले में, हर कार्रवाई के लिए पासकोड की अनुमति की ज़रूरत होती है. साथ ही, अपडेट करने वाले मैथड को inParams आर्ग्युमेंट में Tag::AUTH_TOKEN मिलता है. एचएमएससी यह पुष्टि करता है कि टोकन मान्य है और उसमें सुरक्षित उपयोगकर्ता आईडी मौजूद है. साथ ही, यह कुंजी के Tag::USER_AUTH_TYPE से मेल खाता है और चैलेंज फ़ील्ड में मौजूदा ऑपरेशन का ऑपरेशन हैंडल शामिल है. अगर ये शर्तें पूरी नहीं होती हैं, तो ErrorCode::KEY_USER_NOT_AUTHENTICATED दिखाएं.

कॉल करने वाला व्यक्ति, हर कॉल के लिए ऑथेंटिकेशन टोकन उपलब्ध कराता है, ताकि अपडेट और पूरा किया जा सके. अगर ज़रूरत हो, तो लागू करने के लिए टोकन की पुष्टि सिर्फ़ एक बार करनी होगी.

आरएसए कुंजियां

पैडिंग मोड के आधार पर, कुछ अन्य ज़रूरी शर्तें:

  • PaddingMode::NONE. बिना पैड वाले हस्ताक्षर और एन्क्रिप्ट (सुरक्षित) करने की सुविधा से जुड़ी कार्रवाइयों के लिए, अगर दिया गया डेटा कुंजी से छोटा है, तो डेटा को साइन या एन्क्रिप्ट (सुरक्षित) करने से पहले, बाईं ओर शून्य पैडेड लगा दिया जाता है. अगर डेटा की लंबाई, कुंजी की लंबाई के बराबर है, लेकिन संख्या में ज़्यादा है, तो ErrorCode::INVALID_ARGUMENT दिखाएं. पुष्टि करने और डेटा को डिक्रिप्ट करने के लिए, डेटा का साइज़, कुंजी के साइज़ के बराबर होना चाहिए. अगर ऐसा नहीं है, तो ErrorCode::INVALID_INPUT_LENGTH. दिखाएं
  • PaddingMode::RSA_PSS. PSS की मदद से हस्ताक्षर की जाने वाली कार्रवाइयों के लिए, PSS सॉल्ट, मैसेज डाइजेस्ट का साइज़ होता है और यह किसी भी क्रम में जनरेट होता है. begin पर inputParams में Tag::DIGEST के साथ बताए गए डाइजेस्ट का इस्तेमाल, पीएसएस डाइजेस्ट एल्गोरिदम और एमजीएफ़1 डाइजेस्ट एल्गोरिदम के तौर पर किया जाता है.
  • PaddingMode::RSA_OAEP. begin पर inputParams में, Tag::DIGEST के साथ बताए गए डाइजेस्ट का इस्तेमाल, OAEP डाइजेस्ट एल्गोरिदम के तौर पर किया जाता है. साथ ही, SHA1 का इस्तेमाल MGF1 डाइजेस्ट एल्गोरिदम के तौर पर किया जाता है.

ईसीडीएसए कुंजियां

अगर बिना पैड किए हस्ताक्षर करने या पुष्टि करने के लिए दिया गया डेटा बहुत लंबा है, तो उसे छोटा करें.

एईएस कुंजियां

ब्लॉक मोड के आधार पर, कुछ और शर्तें:

  • BlockMode::ECB या BlockMode::CBC. अगर पैडिंग PaddingMode::NONE है और डेटा की लंबाई, AES ब्लॉक साइज़ का मल्टीपल नहीं है, तो ErrorCode::INVALID_INPUT_LENGTH दिखाएं. अगर पैडिंग की वैल्यू PaddingMode::PKCS7 है, तो डेटा को PKCS#7 स्पेसिफ़िकेशन के मुताबिक पैड करें. ध्यान दें कि PKCS#7 का सुझाव है कि अगर डेटा, ब्लॉक की लंबाई का मल्टीपल है, तो एक और पैडिंग ब्लॉक जोड़ें.
  • BlockMode::GCM. एन्क्रिप्ट (सुरक्षित) करने के दौरान, सभी सादे टेक्स्ट को प्रोसेस करने के बाद, टैग (टैग::MAC_LENGTH बाइट) का कैलकुलेशन करें और उसे, दिखाए गए सादे टेक्स्ट में जोड़ें. डिक्रिप्ट करने के दौरान, आखिरी Tag::MAC_LENGTH बाइट को टैग के तौर पर प्रोसेस करें. अगर टैग की पुष्टि नहीं हो पाती है, तो ErrorCode::VERIFICATION_FAILED दिखाएं.

रहने दो

वर्शन: 1, 2, 3

चल रही कार्रवाई को रोक देता है. 'रद्द करें' कॉल के बाद, अपडेट करें, पूरा करें या रद्द करें के साथ दिए गए ऑपरेशन हैंडल के बाद के किसी भी इस्तेमाल के लिए, ErrorCode::INVALID_OPERATION_HANDLE दिखाएं.

get_supported_algorithms

वर्शन: 1

Keymaster हार्डवेयर के लागू होने पर काम करने वाले एल्गोरिदम की सूची दिखाता है. सॉफ़्टवेयर लागू करने पर एक खाली सूची मिलती है; हाइब्रिड लागू करने से सिर्फ़ हार्डवेयर के साथ काम करने वाले एल्गोरिदम वाली सूची मिलती है.

Keymaster 1 लागू करने पर, आरएसए, ईसी, एईएस, और एचएमएसी का इस्तेमाल किया जा सकता है.

get_supported_block_modes

वर्शन: 1

यह फ़ंक्शन किसी खास एल्गोरिदम और मकसद के लिए, कीमास्टर हार्डवेयर लागू करने की सुविधा के साथ काम करने वाले एईएस ब्लॉक मोड की सूची दिखाता है.

RSA, EC, और HMAC, ब्लॉक सिफर नहीं हैं. इसलिए, इनके लिए यह तरीका सभी मान्य कामों के लिए, खाली सूची दिखाता है. अमान्य मकसद की वजह से, यह तरीका ErrorCode::INVALID_PURPOSE दिखाता है.

Keymaster 1 लागू करने पर, एईएस एन्क्रिप्शन और डिक्रिप्शन के लिए, ईसीबी, सीबीसी, सीटीआर, और जीसीएम का इस्तेमाल किया जा सकता है.

get_supported_जगह_modes

वर्शन: 1

यह किसी खास एल्गोरिदम और मकसद के लिए, Keymaster हार्डवेयर के लागू होने पर काम करने वाले पैडिंग मोड की सूची दिखाता है.

HMAC और ईसी में पैडिंग का कोई मतलब नहीं है. इसलिए, यह तरीका सभी मान्य कामों के लिए खाली सूची दिखाता है. अमान्य मकसद की वजह से, यह तरीका ErrorCode::INVALID_PURPOSE दिखाता है.

आरएसए के लिए, कीमास्टर 1 को लागू करने के तरीके:

  • बिना पैड किए एन्क्रिप्शन, डिक्रिप्शन, हस्ताक्षर, और पुष्टि. बिना पैड किए एन्क्रिप्ट (सुरक्षित) करने और हस्ताक्षर करने के लिए, अगर मैसेज पब्लिक मॉड्यूल से छोटा है, तो उसे लागू करने के लिए, बाईं ओर शून्य जोड़ना होगा. बिना पैड किए डिक्रिप्ट करने और पुष्टि करने के लिए, इनपुट की लंबाई, सार्वजनिक मॉड्यूल के साइज़ से मेल खानी चाहिए.
  • PKCS#1 v1.5 एन्क्रिप्शन और हस्ताक्षर करने के लिए पैडिंग मोड
  • कम से कम 20 वर्णों का नमक वाला पीएसएस
  • OAEP

ईसीबी और सीबीसी मोड में एईएस के लिए, Keymaster 1 के लागू होने पर, पैडिंग नहीं और PKCS#7-पैडिंग का इस्तेमाल किया जा सकता है. सीटीआर और जीसीएम मोड में, सिर्फ़ बिना पैडिंग वाला विकल्प काम करता है.

get_supported_डाइजेस्टs

वर्शन: 1

किसी खास एल्गोरिदम और मकसद के लिए, Keymaster हार्डवेयर के लागू होने पर काम करने वाले डाइजेस्ट मोड की सूची दिखाता है.

कोई भी एईएस मोड काम नहीं करता या डाइजेस्टिंग की ज़रूरत नहीं होती. इसलिए, यह तरीका मान्य मकसद के लिए खाली सूची दिखाता है.

Keymaster 1 लागू करने पर, तय किए गए डाइजेस्ट का कोई सब-सेट लागू किया जा सकता है. लागू करने पर, SHA-256 मिलता है. साथ ही, MD5, SHA1, SHA-224, SHA-256, SHA384, और SHA512 (तय किए गए डाइजेस्ट का पूरा सेट) मिल सकता है.

get_supported_import_formats

वर्शन: 1

किसी खास एल्गोरिदम के Keymaster हार्डवेयर लागू करने से, इंपोर्ट किए जा सकने वाले फ़ॉर्मैट की सूची दिखाता है.

Keymaster 1 के लागू होने से, आरएसए और ईसी की कुंजी के पेयर को इंपोर्ट करने के लिए, पासवर्ड की सुरक्षा के बिना PKCS#8 फ़ॉर्मैट का इस्तेमाल किया जा सकता है. साथ ही, एईएस और एचएमएसी की कुंजी के मटीरियल को रॉ फ़ॉर्मैट में इंपोर्ट किया जा सकता है.

get_supported_export_formats

वर्शन: 1

किसी खास एल्गोरिदम के Keymaster हार्डवेयर लागू करने से, एक्सपोर्ट किए जा सकने वाले फ़ॉर्मैट की सूची दिखाता है.

Keymaster1 लागू करने पर, आरएसए और ईसी सार्वजनिक कुंजियों को एक्सपोर्ट करने के लिए, X.509 फ़ॉर्मैट का इस्तेमाल किया जा सकता है. निजी कुंजियों या असिमेट्रिक कुंजियों को एक्सपोर्ट नहीं किया जा सकता.

पुराने फ़ंक्शन

Keymaster 0

यहां दिए गए फ़ंक्शन, Keymaster 0 की मूल परिभाषा से जुड़े हैं. ये, Keymaster 1 के स्ट्रक्चर keymaster1_device_t में मौजूद थे. हालांकि, Keymaster 1.0 में इन्हें लागू नहीं किया गया था और उनके फ़ंक्शन पॉइंटर को NULL पर सेट किया गया था.

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

Keymaster 1

नीचे दिए गए फ़ंक्शन, Keymaster 1 की परिभाषा से जुड़े हैं. हालांकि, इन्हें Keymaster 2 में हटा दिया गया है. साथ ही, ऊपर दिए गए Keymaster 0 के फ़ंक्शन भी हटा दिए गए हैं.

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

Keymaster 2

नीचे दिए गए फ़ंक्शन, Keymaster 2 की परिभाषा से जुड़े हैं. हालांकि, इन्हें Keymaster 3 में हटा दिया गया है. साथ ही, ऊपर दिए गए Keymaster 1 के फ़ंक्शन भी हटा दिए गए हैं.

  • configure