Keymaster के फ़ंक्शन

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

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

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

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

वर्शन: 1, 2

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

अगर ज़रूरी इनपुट पैरामीटर 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 होता है अगर हार्डवेयर, एईएस और एचएमएसी के साथ-साथ सिमेट्रिक क्रिप्टोग्राफ़ी के साथ काम करता है.
  • supportsAttestation true होता है, अगर हार्डवेयर में, सुरक्षित माहौल में डाली गई कुंजी से हस्ताक्षर किए गए, Keymaster के सार्वजनिक पासकोड की पुष्टि करने वाले सर्टिफ़िकेट जनरेट करने की सुविधा होती है.

इस तरीके से, सिर्फ़ 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 दिखाते हैं. इस तरीके से दी गई वैल्यू को, keymaster हर बार सिर्फ़ एक बार स्वीकार करता है. इसके बाद के कॉल, 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 में इसका नाम बदल दिया गया.

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

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

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

generateKey

वर्शन: 1, 2, 3

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

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

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

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

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

एईएस पासकोड जनरेट करने के लिए, सिर्फ़ 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 है.
  • Tag::DIGEST कुंजी के लिए डाइजेस्ट एल्गोरिदम तय करता है. सिर्फ़ एक डाइजेस्ट दिया गया हो. ऐसा न होने पर, ErrorCode::UNSUPPORTED_DIGEST दिखाएं. अगर ट्रस्टलेट में डाइजेस्ट काम नहीं करता है, तो ErrorCode::UNSUPPORTED_DIGEST दिखाएं.

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

अगर विशेषताओं वाला आर्ग्युमेंट NULL नहीं है, तो 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 आर्ग्युमेंट में इस तरीके के लिए वही वैल्यू दी जाती है.

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

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

  • Tag::ALGORITHM, Tag::KEY_SIZE, और Tag::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::ORIGIN की वैल्यू, KeyOrigin::IMPORTED की वैल्यू के बराबर होती है.

exportKey

वर्शन: 1, 2, 3

इस फ़ंक्शन को Keymaster 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 मॉड्यूल लागू करते हैं जो रोलबैक रेज़िस्टेंस देते हैं.

destroyAttestationIds

वर्शन: 3

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

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

चालू करें

वर्शन: 1, 2, 3

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

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

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

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

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

  • Tag::PURPOSE: begin() कॉल में बताए गए मकसद को, पासकोड की अनुमतियों में बताए गए किसी एक मकसद से मैच करना होगा. ऐसा तब तक ज़रूरी है, जब तक अनुरोध किया गया ऑपरेशन, सार्वजनिक पासकोड से जुड़ा ऑपरेशन न हो. अगर बताई गई वजह मेल नहीं खाती और कार्रवाई, सार्वजनिक कुंजी से जुड़ी कार्रवाई नहीं है, तो begin ErrorCode::UNSUPPORTED_PURPOSE दिखाता है. सार्वजनिक कुंजी से जुड़े ऑपरेशन, एसिमेट्रिक एन्क्रिप्शन या पुष्टि करने वाले ऑपरेशन होते हैं.
  • Tag::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 दिखाता है. इसके अलावा, आरएसए कुंजी का साइज़, डाइजेस्ट के आउटपुट साइज़ से कम से कम 2 + 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 कुंजी के ऑपरेशन में, 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 के अनुमति मिलने पर कोई नॉन्स नहीं दिया गया है, तो कोई रैंडम आईवी/नॉन्स जनरेट करें.

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

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

अपडेट करें

वर्शन: 1, 2, 3

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

पूरा करें

वर्शन: 1, 2, 3

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

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

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

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

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

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

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

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

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

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

  • 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. एन्क्रिप्ट (सुरक्षित) करने के दौरान, सभी सादा टेक्स्ट को प्रोसेस करने के बाद, टैग (Tag::MAC_LENGTH बाइट) का हिसाब लगाएं और उसे वापस मिले सिफरटेक्स्ट में जोड़ें. डिक्रिप्ट करने के दौरान, आखिरी Tag::MAC_LENGTH बिट को टैग के तौर पर प्रोसेस करें. अगर टैग की पुष्टि नहीं हो पाती है, तो ErrorCode::VERIFICATION_FAILED दिखाएं.

रहने दो

वर्शन: 1, 2, 3

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

get_supported_algorithms

वर्शन: 1

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

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

get_supported_block_modes

वर्शन: 1

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

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

Keymaster 1 के लागू होने से, एईएस एन्क्रिप्शन और डिक्रिप्शन के लिए ECB, CBC, CTR, और GCM का इस्तेमाल किया जा सकता है.

get_supported_padding_modes

वर्शन: 1

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

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

आरएसए के लिए, Keymaster 1 के लागू होने पर ये काम किए जा सकते हैं:

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

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

get_supported_digests

वर्शन: 1

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

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

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