कीमास्टर फ़ंक्शंस, कीमास्टर फ़ंक्शंस

यह पृष्ठ कीमास्टर हार्डवेयर एब्स्ट्रैक्शन लेयर्स (एचएएल) के कार्यान्वयनकर्ताओं की सहायता के लिए विवरण प्रदान करता है। यह एपीआई में प्रत्येक फ़ंक्शन को कवर करता है और वह फ़ंक्शन किस कीमास्टर संस्करण में उपलब्ध है और डिफ़ॉल्ट कार्यान्वयन का वर्णन करता है। टैग के लिए, कीमास्टर टैग पृष्ठ देखें।

सामान्य कार्यान्वयन दिशानिर्देश

निम्नलिखित दिशानिर्देश एपीआई में सभी कार्यों पर लागू होते हैं।

इनपुट सूचक पैरामीटर

संस्करण : 1, 2

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

यदि आवश्यक इनपुट पैरामीटर शून्य है, तो कीमास्टर विधियों को ErrorCode::UNEXPECTED_NULL_POINTER लौटाना चाहिए।

कीमास्टर 3 में प्रारंभ से, कोई सूचक पैरामीटर नहीं हैं। सभी पैरामीटर मान या स्थिरांक संदर्भ द्वारा पारित किए जाते हैं।

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

संस्करण : 1, 2

इनपुट पॉइंटर पैरामीटर के समान, अप्रयुक्त आउटपुट पॉइंटर पैरामीटर NULL हो सकते हैं। यदि किसी विधि को NULL पाए गए आउटपुट पैरामीटर में डेटा वापस करने की आवश्यकता है, तो उसे ErrorCode::OUTPUT_PARAMETER_NULL वापस आना चाहिए।

कीमास्टर 3 में प्रारंभ से, कोई सूचक पैरामीटर नहीं हैं। सभी पैरामीटर मान या स्थिरांक संदर्भ द्वारा पारित किए जाते हैं।

एपीआई का दुरुपयोग

संस्करण : 1, 2, 3

ऐसे कई तरीके हैं जिनसे कॉल करने वाले ऐसे अनुरोध कर सकते हैं जिनका कोई मतलब नहीं है या वे मूर्खतापूर्ण हैं लेकिन तकनीकी रूप से गलत नहीं हैं। ऐसे मामलों में कीमास्टर कार्यान्वयन के विफल होने या डायग्नोस्टिक जारी करने की आवश्यकता नहीं है। बहुत छोटी कुंजियों का उपयोग, अप्रासंगिक इनपुट मापदंडों का विनिर्देशन, IVs या नॉनसेस का पुन: उपयोग, बिना किसी उद्देश्य के कुंजियों का निर्माण (इसलिए बेकार) और इस तरह का कार्यान्वयन द्वारा निदान नहीं किया जाना चाहिए। आवश्यक मापदंडों की चूक, अमान्य आवश्यक मापदंडों की विशिष्टता और इसी तरह की त्रुटियों का निदान किया जाना चाहिए।

यह सुनिश्चित करना ऐप्स, फ्रेमवर्क और एंड्रॉइड कीस्टोर की जिम्मेदारी है कि कीमास्टर मॉड्यूल पर कॉल समझदार और उपयोगी हों।

कार्य

हार्डवेयर विशेषताएँ प्राप्त करें

वर्जन : 3

नई getHardwareFeatures विधि ग्राहकों को अंतर्निहित सुरक्षित हार्डवेयर की कुछ महत्वपूर्ण विशेषताओं को उजागर करती है। विधि कोई तर्क नहीं लेती है और चार मान लौटाती है, सभी बूलियन:

  • यदि कुंजियाँ सुरक्षित हार्डवेयर (TEE, आदि) में संग्रहित हैं और इसे कभी न छोड़ें तो isSecure true है।
  • यदि हार्डवेयर NIST कर्व्स (P-224, P-256, P-384, और P-521) के साथ एलिप्टिक कर्व क्रिप्टोग्राफी का समर्थन करता है, तो supportsEllipticCurve true है।
  • यदि हार्डवेयर AES और HMAC सहित सममित क्रिप्टोग्राफी का समर्थन करता है, तो supportsSymmetricCryptography true है।
  • यदि हार्डवेयर एक सुरक्षित वातावरण में इंजेक्ट की गई कुंजी के साथ हस्ताक्षरित कीमास्टर सार्वजनिक कुंजी सत्यापन प्रमाणपत्रों के निर्माण का समर्थन करता है, तो 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

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

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

यदि कीमास्टर कार्यान्वयन सुरक्षित हार्डवेयर में है और प्रदान किए गए OS संस्करण और पैच स्तर मान बूटलोडर द्वारा सुरक्षित हार्डवेयर को प्रदान किए गए मानों से मेल नहीं खाते हैं (या यदि बूटलोडर ने मान प्रदान नहीं किया है), तो यह विधि 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 में इसका नाम बदल दिया गया था।

कुंजी, IVs आदि के लिए यादृच्छिक संख्याएँ उत्पन्न करने के लिए कीमास्टर 1 कार्यान्वयन द्वारा उपयोग किए जाने वाले पूल में कॉलर द्वारा प्रदान की गई एन्ट्रॉपी जोड़ता है।

कीमास्टर कार्यान्वयन को प्रदान की गई एन्ट्रॉपी को अपने पूल में सुरक्षित रूप से मिश्रित करने की आवश्यकता होती है, जिसमें हार्डवेयर यादृच्छिक संख्या जनरेटर से आंतरिक रूप से उत्पन्न एन्ट्रॉपी भी शामिल होनी चाहिए। मिश्रण को इस तरह से संभाला जाना चाहिए कि एक हमलावर जिसके पास addRngEntropy -प्रदत्त बिट्स या हार्डवेयर-जनरेट किए गए बिट्स का पूरा नियंत्रण है, लेकिन दोनों का नहीं, उसे एन्ट्रॉपी पूल से उत्पन्न बिट्स की भविष्यवाणी करने में कोई गैर-नगण्य लाभ नहीं है।

कीमास्टर कार्यान्वयन जो अपने आंतरिक पूल में एन्ट्रापी का अनुमान लगाने का प्रयास करते हैं, यह मानते हैं कि addRngEntropy द्वारा प्रदान किए गए डेटा में कोई एन्ट्रापी नहीं है। यदि उन्हें एक ही कॉल में 2 KiB से अधिक डेटा दिया जाता है, तो कीमास्टर कार्यान्वयन ErrorCode::INVALID_INPUT_LENGTH लौटा सकता है।

जेनरेटकी

संस्करण : 1, 2, 3

इस फ़ंक्शन को Keymaster 1 में generate_key के रूप में पेश किया गया था और Keymaster 3 में इसका नाम बदल दिया गया था।

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

generateKey को प्रदान किए गए पैरामीटर जेनरेट की जा रही कुंजी के प्रकार पर निर्भर करते हैं। यह अनुभाग प्रत्येक प्रकार की कुंजी के लिए आवश्यक और वैकल्पिक टैग का सारांश देता है। प्रकार निर्दिष्ट करने के लिए टैग::एल्गोरिदम हमेशा आवश्यक होता है।

आरएसए कुंजी

RSA कुंजी उत्पन्न करने के लिए निम्नलिखित पैरामीटर आवश्यक हैं।

  • टैग::KEY_SIZE सार्वजनिक मापांक का आकार बिट्स में निर्दिष्ट करता है। यदि छोड़ा गया है, तो विधि ErrorCode::UNSUPPORTED_KEY_SIZE लौटाती है। समर्थित मान 1024, 2048, 3072 और 4096 हैं। अनुशंसित मान सभी प्रमुख आकार हैं जो 8 के गुणज हैं।
  • Tag::RSA_PUBLIC_EXPONENT RSA सार्वजनिक घातांक मान निर्दिष्ट करता है। यदि छोड़ा गया है, तो विधि ErrorCode::INVALID_ARGUMENT लौटाती है। समर्थित मान 3 और 65537 हैं। अनुशंसित मान 2^64 तक के सभी अभाज्य मान हैं।

RSA कुंजी उत्पन्न करने के लिए निम्नलिखित पैरामीटर आवश्यक नहीं हैं, लेकिन उनके बिना RSA कुंजी बनाने से एक कुंजी उत्पन्न होती है जो अनुपयोगी है। हालाँकि, यदि ये पैरामीटर छोड़ दिए जाते हैं तो generateKey फ़ंक्शन कोई त्रुटि नहीं लौटाता है।

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

ईसीडीएसए कुंजी

ECDSA कुंजी उत्पन्न करने के लिए केवल Tag::KEY_SIZE आवश्यक है। इसका उपयोग EC समूह का चयन करने के लिए किया जाता है। समर्थित मान 224, 256, 384 और 521 हैं, जो क्रमशः एनआईएसटी पी-224, पी-256, पी-384 और पी521 वक्र दर्शाते हैं।

टैग::डाइजेस्ट एक उपयोगी ईसीडीएसए कुंजी के लिए भी आवश्यक है, लेकिन पीढ़ी के लिए आवश्यक नहीं है।

एईएस चाबियाँ

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

निम्नलिखित पैरामीटर एईएस कुंजियों के लिए विशेष रूप से प्रासंगिक हैं, लेकिन एक उत्पन्न करने के लिए आवश्यक नहीं हैं:

  • Tag::BLOCK_MODE उन ब्लॉक मोड को निर्दिष्ट करता है जिनके साथ नई कुंजी का उपयोग किया जा सकता है।
  • Tag::PADDING उन पैडिंग मोड को निर्दिष्ट करता है जिनका उपयोग किया जा सकता है। यह केवल ईसीबी और सीबीसी मोड के लिए प्रासंगिक है।

यदि GCM ब्लॉक मोड निर्दिष्ट है, तो Tag::MIN_MAC_LENGTH प्रदान करें। यदि छोड़ा गया है, तो विधि ErrorCode::MISSING_MIN_MAC_LENGTH लौटाती है। टैग का मान 8 का गुणज है और 96 और 128 के बीच है।

एचएमएसी कुंजी

HMAC कुंजी निर्माण के लिए निम्नलिखित पैरामीटर आवश्यक हैं:

  • टैग::KEY_SIZE बिट्स में कुंजी आकार निर्दिष्ट करता है। 64 से छोटे मान और 8 के गुणज न होने वाले मान समर्थित नहीं हैं। 64 से 512 तक 8 के सभी गुणज समर्थित हैं। बड़े मूल्यों का समर्थन किया जा सकता है.
  • टैग::MIN_MAC_LENGTH MAC की न्यूनतम लंबाई निर्दिष्ट करता है जिसे इस कुंजी से उत्पन्न या सत्यापित किया जा सकता है। मान 8 का गुणज है और कम से कम 64 है।
  • टैग::डाइजेस्ट कुंजी के लिए डाइजेस्ट एल्गोरिदम निर्दिष्ट करता है। बिल्कुल एक डाइजेस्ट निर्दिष्ट है, अन्यथा ErrorCode::UNSUPPORTED_DIGEST लौटाएँ। यदि डाइजेस्ट ट्रस्टलेट द्वारा समर्थित नहीं है, तो ErrorCode::UNSUPPORTED_DIGEST लौटाएँ।

मुख्य गुण

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

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

टैग::रोलबैक_रेसिस्टेंट

रोलबैक प्रतिरोध

रोलबैक प्रतिरोध का मतलब है कि एक बार जब कुंजी को deleteKey या deleteAllKeys के साथ हटा दिया जाता है, तो सुरक्षित हार्डवेयर द्वारा इसकी गारंटी दी जाती है कि यह फिर से उपयोग करने योग्य नहीं होगा। रोलबैक प्रतिरोध के बिना कार्यान्वयन आम तौर पर कॉलर को कुंजी ब्लॉब, एक एन्क्रिप्टेड और प्रमाणित रूप में उत्पन्न या आयातित कुंजी सामग्री लौटाता है। जब कीस्टोर कुंजी ब्लॉब को हटा देता है, तो कुंजी चली जाती है, लेकिन एक हमलावर जो पहले कुंजी सामग्री को पुनः प्राप्त करने में कामयाब रहा है, वह संभावित रूप से इसे डिवाइस पर पुनर्स्थापित कर सकता है।

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

getKeyCharacteristics

संस्करण : 1, 2, 3

इस फ़ंक्शन को Keymaster 1 में get_key_characteristics के रूप में पेश किया गया था और Keymaster 3 में इसका नाम बदल दिया गया था।

प्रदान की गई कुंजी से जुड़े पैरामीटर और प्राधिकरण लौटाता है, जिसे दो सेटों में विभाजित किया गया है: हार्डवेयर-प्रबलित और सॉफ़्टवेयर-प्रबलित। यहां विवरण generateKey और आयातKey द्वारा लौटाई गई प्रमुख विशेषता सूचियों पर समान रूप से लागू होता है।

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

इस विधि द्वारा लौटाई गई विशेषताएँ निर्दिष्ट कुंजी के प्रकार और उपयोग का पूरी तरह से वर्णन करती हैं।

यह तय करने का सामान्य नियम कि कोई दिया गया टैग हार्डवेयर-प्रवर्तित या सॉफ़्टवेयर-प्रबलित सूची में है या नहीं, यदि टैग का अर्थ सुरक्षित हार्डवेयर द्वारा पूरी तरह से आश्वस्त है, तो यह हार्डवेयर लागू है। अन्यथा, यह सॉफ़्टवेयर द्वारा लागू किया गया है। नीचे उन विशिष्ट टैगों की सूची दी गई है जिनका सही आवंटन अस्पष्ट हो सकता है:

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

आयातकुंजी

संस्करण : 1, 2, 3

इस फ़ंक्शन को कीमास्टर 1 में import_key के रूप में पेश किया गया था और कीमास्टर 3 में इसका नाम बदल दिया गया था।

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

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

निर्यातकुंजी

संस्करण : 1, 2, 3

इस फ़ंक्शन को कीमास्टर 1 में export_key के रूप में पेश किया गया था और कीमास्टर 3 में इसका नाम बदल दिया गया था।

कीमास्टर आरएसए या ईसी कुंजी जोड़ी से सार्वजनिक कुंजी निर्यात करता है।

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

हटाएँकुंजी

संस्करण : 1, 2, 3

यह फ़ंक्शन Keymaster 1 में delete_key के रूप में पेश किया गया था और Keymaster 3 में इसका नाम बदल दिया गया था।

प्रदत्त कुंजी को हटा देता है. यह विधि वैकल्पिक है, और केवल कीमास्टर मॉड्यूल द्वारा कार्यान्वित की जाती है जो रोलबैक प्रतिरोध प्रदान करती है।

सभी कुंजी हटाएं

संस्करण : 1, 2, 3

यह फ़ंक्शन Keymaster 1 में delete_all_keys के रूप में पेश किया गया था और Keymaster 3 में इसका नाम बदल दिया गया था।

सभी कुंजियाँ हटा देता है. यह विधि वैकल्पिक है, और केवल कीमास्टर मॉड्यूल द्वारा कार्यान्वित की जाती है जो रोलबैक प्रतिरोध प्रदान करती है।

नष्टप्रमाणन आईडी

वर्जन : 3

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

यह विधि जो एकमात्र त्रुटि कोड लौटा सकती है, वे हैं ErrorCode::UNIMPLEMENTED (यदि आईडी सत्यापन समर्थित नहीं है), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED या सुरक्षित हार्डवेयर के साथ संचार में विफलता का संकेत देने वाले त्रुटि कोड में से एक।

शुरू

संस्करण : 1, 2, 3

निर्दिष्ट पैरामीटर (जैसा उपयुक्त हो) के साथ, निर्दिष्ट उद्देश्य के लिए निर्दिष्ट कुंजी का उपयोग करके एक क्रिप्टोग्राफ़िक ऑपरेशन शुरू करता है, और एक ऑपरेशन हैंडल लौटाता है जिसका उपयोग ऑपरेशन को पूरा करने के लिए अपडेट और फिनिश के साथ किया जाता है। ऑपरेशन हैंडल का उपयोग प्रमाणित संचालन में "चुनौती" टोकन के रूप में भी किया जाता है, और ऐसे संचालन के लिए प्रमाणीकरण टोकन के challenge क्षेत्र में शामिल किया जाता है।

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

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

प्राधिकरण प्रवर्तन

इस पद्धति के दौरान, निम्नलिखित प्रमुख प्राधिकरणों को ट्रस्टलेट द्वारा लागू किया जाता है यदि कार्यान्वयन ने उन्हें "हार्डवेयर-प्रबलित" विशेषताओं में रखा है और यदि ऑपरेशन सार्वजनिक कुंजी ऑपरेशन नहीं है। सार्वजनिक कुंजी संचालन, जिसका अर्थ है KeyPurpose::ENCRYPT और KeyPurpose::VERIFY , RSA या EC कुंजियों के साथ, प्राधिकरण आवश्यकताओं को पूरा न करने पर भी सफल होने की अनुमति है।

  • टैग::उद्देश्य : begin() कॉल में निर्दिष्ट उद्देश्य को मुख्य प्राधिकरणों में से एक उद्देश्य से मेल खाना चाहिए, जब तक कि अनुरोधित ऑपरेशन एक सार्वजनिक कुंजी ऑपरेशन न हो। यदि निर्दिष्ट उद्देश्य मेल नहीं खाता है और ऑपरेशन सार्वजनिक कुंजी ऑपरेशन नहीं है, begin ErrorCode::UNSUPPORTED_PURPOSE लौटाएगा। सार्वजनिक कुंजी संचालन असममित एन्क्रिप्शन या सत्यापन संचालन हैं।
  • टैग::ACTIVE_DATETIME को केवल तभी लागू किया जा सकता है जब कोई विश्वसनीय UTC समय स्रोत उपलब्ध हो। यदि वर्तमान दिनांक और समय टैग मान से पहले है, तो विधि ErrorCode::KEY_NOT_YET_VALID लौटाती है।
  • टैग::ORIGINATION_EXPIRE_DATETIME को केवल तभी लागू किया जा सकता है जब कोई विश्वसनीय UTC समय स्रोत उपलब्ध हो। यदि वर्तमान दिनांक और समय टैग मान के बाद का है और उद्देश्य KeyPurpose::ENCRYPT या KeyPurpose::SIGN है, तो विधि ErrorCode::KEY_EXPIRED लौटाती है।
  • टैग::USAGE_EXPIRE_DATETIME को केवल तभी लागू किया जा सकता है जब कोई विश्वसनीय UTC समय स्रोत उपलब्ध हो। यदि वर्तमान दिनांक और समय टैग मान के बाद का है और उद्देश्य KeyPurpose::DECRYPT या KeyPurpose::VERIFY है, तो विधि ErrorCode::KEY_EXPIRED लौटाती है।
  • टैग::MIN_SECONDS_BETWEEN_OPS की तुलना कुंजी के अंतिम उपयोग को दर्शाने वाले विश्वसनीय सापेक्ष टाइमर से की जाती है। यदि अंतिम उपयोग समय और टैग मान वर्तमान समय से कम है, तो विधि ErrorCode::KEY_RATE_LIMIT_EXCEEDED लौटाती है। महत्वपूर्ण कार्यान्वयन विवरण के लिए टैग विवरण देखें।
  • टैग::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 मान टोकन में सुरक्षित आईडी मानों में से कम से कम एक से मेल खाता है।
    • कुंजी में एक टैग::USER_AUTH_TYPE है जो टोकन में प्रमाणीकरण प्रकार से मेल खाता है।

    यदि इनमें से कोई भी शर्त पूरी नहीं होती है, तो विधि ErrorCode::KEY_USER_NOT_AUTHENTICATED लौटाती है।

  • टैग::CALLER_NONCE कॉल करने वाले को नॉन्स या इनिशियलाइज़ेशन वेक्टर (IV) निर्दिष्ट करने की अनुमति देता है। यदि कुंजी में यह टैग नहीं है, लेकिन कॉलर ने इस विधि में Tag::NONCE प्रदान किया है, ErrorCode::CALLER_NONCE_PROHIBITED वापस आ जाता है।
  • टैग::BOOTLOADER_ONLY निर्दिष्ट करता है कि केवल बूटलोडर ही कुंजी का उपयोग कर सकता है। यदि बूटलोडर का निष्पादन समाप्त होने के बाद इस विधि को केवल बूटलोडर कुंजी के साथ कॉल किया जाता है, तो यह ErrorCode::INVALID_KEY_BLOB लौटाता है।

आरएसए कुंजी

सभी RSA कुंजी ऑपरेशन inParams में बिल्कुल एक पैडिंग मोड निर्दिष्ट करते हैं। यदि अनिर्दिष्ट या एक से अधिक बार निर्दिष्ट किया गया है, तो विधि ErrorCode::UNSUPPORTED_PADDING_MODE लौटाती है।

आरएसए हस्ताक्षर और सत्यापन संचालन के लिए एक डाइजेस्ट की आवश्यकता होती है, जैसे कि ओएईपी पैडिंग मोड के साथ आरएसए एन्क्रिप्शन और डिक्रिप्शन संचालन के लिए। उन मामलों के लिए, कॉलर inParams में बिल्कुल एक डाइजेस्ट निर्दिष्ट करता है। यदि अनिर्दिष्ट या एक से अधिक बार निर्दिष्ट किया गया है, तो विधि ErrorCode::UNSUPPORTED_DIGEST लौटाती है।

निजी कुंजी संचालन ( KeyPurpose::DECYPT और KeyPurpose::SIGN ) को डाइजेस्ट और पैडिंग के प्राधिकरण की आवश्यकता होती है, जिसका अर्थ है कि मुख्य प्राधिकरणों में निर्दिष्ट मान शामिल होने चाहिए। यदि नहीं, तो विधि उचित के रूप में ErrorCode::INCOMPATIBLE_DIGEST या ErrorCode::INCOMPATIBLE_PADDING लौटाती है। सार्वजनिक कुंजी संचालन ( KeyPurpose::ENCRYPT और KeyPurpose::VERIFY ) को अनधिकृत डाइजेस्ट या पैडिंग के साथ अनुमति है।

PaddingMode::NONE के अपवाद के साथ, सभी RSA पैडिंग मोड केवल कुछ उद्देश्यों के लिए लागू होते हैं। विशेष रूप से, 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 इंगित करता है कि एक "कच्चा" RSA ऑपरेशन किया गया है। यदि हस्ताक्षर कर रहे हैं या सत्यापित कर रहे हैं, तो Digest::NONE डाइजेस्ट के लिए निर्दिष्ट किया गया है। अनपैडेड एन्क्रिप्शन या डिक्रिप्शन के लिए कोई डाइजेस्ट आवश्यक नहीं है।
  • PaddingMode::RSA_PKCS1_1_5_SIGN पैडिंग के लिए एक डाइजेस्ट की आवश्यकता होती है। डाइजेस्ट Digest::NONE हो सकता है, ऐसी स्थिति में कीमास्टर कार्यान्वयन एक उचित PKCS#1 v1.5 हस्ताक्षर संरचना नहीं बना सकता है, क्योंकि यह DigestInfo संरचना नहीं जोड़ सकता है। इसके बजाय, कार्यान्वयन 0x00 || 0x01 || PS || 0x00 || M का निर्माण करता है 0x00 || 0x01 || PS || 0x00 || M , जहां एम प्रदत्त संदेश है और पीएस पैडिंग स्ट्रिंग है। RSA कुंजी का आकार संदेश से कम से कम 11 बाइट बड़ा होना चाहिए, अन्यथा विधि ErrorCode::INVALID_INPUT_LENGTH लौटाती है।
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT पैडिंग के लिए डाइजेस्ट की आवश्यकता नहीं होती है।
  • PaddingMode::RSA_PSS पैडिंग के लिए एक डाइजेस्ट की आवश्यकता होती है, जो Digest::NONE नहीं हो सकता है। यदि Digest::NONE निर्दिष्ट है, तो विधि ErrorCode::INCOMPATIBLE_DIGEST लौटाती है। इसके अलावा, आरएसए कुंजी का आकार डाइजेस्ट के आउटपुट आकार से कम से कम 2 + डी बाइट्स बड़ा होना चाहिए, जहां डी बाइट्स में डाइजेस्ट का आकार है। अन्यथा विधि ErrorCode::INCOMPATIBLE_DIGEST लौटाती है। नमक का आकार D है.
  • PaddingMode::RSA_OAEP पैडिंग के लिए एक डाइजेस्ट की आवश्यकता होती है, जो Digest::NONE नहीं हो सकता है। यदि Digest::NONE निर्दिष्ट है, तो विधि ErrorCode::INCOMPATIBLE_DIGEST लौटाती है।

ईसी कुंजी

EC कुंजी संचालन inParams में बिल्कुल एक पैडिंग मोड निर्दिष्ट करते हैं। यदि अनिर्दिष्ट या एक से अधिक बार निर्दिष्ट किया गया है, तो विधि ErrorCode::UNSUPPORTED_PADDING_MODE लौटाती है।

निजी कुंजी संचालन ( KeyPurpose::SIGN ) को डाइजेस्ट और पैडिंग के प्राधिकरण की आवश्यकता होती है, जिसका अर्थ है कि कुंजी प्राधिकरणों में निर्दिष्ट मान शामिल होने चाहिए। यदि नहीं, तो ErrorCode::INCOMPATIBLE_DIGEST लौटाएँ। सार्वजनिक कुंजी परिचालन ( KeyPurpose::VERIFY ) को अनधिकृत डाइजेस्ट या पैडिंग के साथ अनुमति है।

एईएस चाबियाँ

एईएस कुंजी संचालन 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 के गैर-गुणकों वाली MAC लंबाई के लिए, 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 है, तो एक इनिशियलाइज़ेशन वेक्टर या नॉन की आवश्यकता होती है। ज्यादातर मामलों में, कॉल करने वालों को IV या नॉन नहीं देना चाहिए। उस स्थिति में, कीमास्टर कार्यान्वयन एक यादृच्छिक IV या नॉन उत्पन्न करता है और इसे outParams में Tag::NONCE के माध्यम से लौटाता है। सीबीसी और सीटीआर IV 16 बाइट्स हैं। जीसीएम नॉन्सेस 12 बाइट्स हैं। यदि मुख्य प्राधिकरणों में Tag::CALLER_NONCE शामिल है, तो कॉल करने वाला inParams में Tag::NONCE के साथ एक IV/nonce प्रदान कर सकता है। यदि Tag::CALLER_NONCE अधिकृत नहीं होने पर कोई नॉन प्रदान किया जाता है, तो ErrorCode::CALLER_NONCE_PROHIBITED लौटाएं। यदि Tag::CALLER_NONCE अधिकृत होने पर कोई नॉन प्रदान नहीं किया जाता है, तो एक यादृच्छिक IV/नॉनस उत्पन्न करें।

एचएमएसी कुंजी

HMAC कुंजी संचालन inParams में Tag::MAC_LENGTH निर्दिष्ट करते हैं। निर्दिष्ट मान 8 का गुणज होना चाहिए जो डाइजेस्ट लंबाई से अधिक नहीं हो या मुख्य प्राधिकरणों में Tag::MIN_MAC_LENGTH के मान से कम न हो। डाइजेस्ट लंबाई से अधिक या 8 के गैर-गुणकों वाली MAC लंबाई के लिए, ErrorCode::UNSUPPORTED_MAC_LENGTH लौटाएँ। कुंजी की न्यूनतम लंबाई से कम मान के लिए, ErrorCode::INVALID_MAC_LENGTH लौटाएँ।

अद्यतन

संस्करण : 1, 2, 3

प्रारंभ से शुरू किए गए चालू ऑपरेशन में संसाधित करने के लिए डेटा प्रदान करता है। ऑपरेशन operationHandle पैरामीटर द्वारा निर्दिष्ट किया गया है।

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

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

त्रुटि प्रबंधन

यदि यह विधि ErrorCode::OK के अलावा कोई त्रुटि कोड लौटाती है, तो ऑपरेशन निरस्त कर दिया जाता है और ऑपरेशन हैंडल अमान्य हो जाता है। इस विधि, फिनिश या एबॉर्ट के साथ हैंडल का भविष्य में कोई भी उपयोग, ErrorCode::INVALID_OPERATION_HANDLE लौटाता है।

प्राधिकरण प्रवर्तन

मुख्य प्राधिकरण प्रवर्तन मुख्य रूप से शुरुआत में किया जाता है। एक अपवाद वह मामला है जहां कुंजी है:

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

कॉलर प्रत्येक कॉल को अद्यतन करने और समाप्त करने के लिए प्रमाणीकरण टोकन प्रदान करता है। कार्यान्वयन को टोकन को केवल एक बार सत्यापित करने की आवश्यकता है यदि वह चाहे।

आरएसए कुंजी

Digest::NONE के साथ हस्ताक्षर और सत्यापन संचालन के लिए, यह विधि पूरे ब्लॉक को एक ही अद्यतन में हस्ताक्षरित या सत्यापित करने के लिए स्वीकार करती है। यह ब्लॉक के केवल एक हिस्से का उपभोग नहीं कर सकता है। हालाँकि, यदि कॉल करने वाला कई अपडेट में डेटा प्रदान करना चुनता है, तो यह विधि इसे स्वीकार करती है। यदि कॉल करने वाला उपयोग किए जाने से अधिक डेटा हस्ताक्षर करने के लिए प्रदान करता है (डेटा की लंबाई आरएसए कुंजी आकार से अधिक है), तो ErrorCode::INVALID_INPUT_LENGTH लौटाएं।

ईसीडीएसए कुंजी

Digest::NONE के साथ हस्ताक्षर और सत्यापन संचालन के लिए, यह विधि पूरे ब्लॉक को एक ही अद्यतन में हस्ताक्षरित या सत्यापित करने के लिए स्वीकार करती है। यह विधि ब्लॉक के केवल एक हिस्से का उपभोग नहीं कर सकती है।

हालाँकि, यदि कॉल करने वाला कई अपडेट में डेटा प्रदान करना चुनता है, तो यह विधि इसे स्वीकार करती है। यदि कॉल करने वाला उपयोग किए जाने से अधिक डेटा हस्ताक्षर करने के लिए प्रदान करता है, तो डेटा चुपचाप काट दिया जाता है। (यह समान आरएसए परिचालनों में प्रदान किए गए अतिरिक्त डेटा के प्रबंधन से भिन्न है। इसका कारण पुराने ग्राहकों के साथ संगतता है।)

एईएस चाबियाँ

एईएस जीसीएम मोड inParams तर्क में टैग::ASSOCIATED_DATA टैग के माध्यम से प्रदान किए गए "संबद्ध प्रमाणीकरण डेटा" का समर्थन करता है। संबंधित डेटा बार-बार कॉल में प्रदान किया जा सकता है (महत्वपूर्ण यदि डेटा एक ब्लॉक में भेजने के लिए बहुत बड़ा है) लेकिन हमेशा डेटा को एन्क्रिप्ट या डिक्रिप्ट करने से पहले प्रदान किया जाता है। एक अपडेट कॉल को एन्क्रिप्ट/डिक्रिप्ट करने के लिए संबंधित डेटा और डेटा दोनों प्राप्त हो सकते हैं, लेकिन बाद के अपडेट में संबंधित डेटा शामिल नहीं हो सकता है। यदि कॉल करने वाला कॉल के बाद अपडेट कॉल से संबंधित डेटा प्रदान करता है जिसमें एन्क्रिप्ट/डिक्रिप्ट करने के लिए डेटा शामिल है, तो ErrorCode::INVALID_TAG लौटाएं।

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

खत्म करना

संस्करण : 1, 2, 3

अपडेट (ओं) द्वारा प्रदान किए गए सभी अभी तक असंसाधित डेटा को संसाधित करते हुए, प्रारंभ के साथ शुरू किए गए एक चालू ऑपरेशन को समाप्त करता है।

यह विधि किसी ऑपरेशन में बुलाई जाने वाली अंतिम विधि है, इसलिए सभी संसाधित डेटा वापस कर दिया जाता है।

चाहे यह सफलतापूर्वक पूरा हो या कोई त्रुटि लौटाए, यह विधि ऑपरेशन को अंतिम रूप देती है और इसलिए दिए गए ऑपरेशन हैंडल को अमान्य कर देती है। हैंडल का कोई भी भविष्य का उपयोग, इस विधि या अद्यतन या गर्भपात के साथ, ErrorCode::INVALID_OPERATION_HANDLE

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

प्राधिकरण प्रवर्तन

मुख्य प्राधिकरण प्रवर्तन मुख्य रूप से शुरुआत में किया जाता है। एक अपवाद मामला है जहां कुंजी है:

इस मामले में, कुंजी के लिए प्रति ऑपरेशन एक प्राधिकरण की आवश्यकता होती है, और अपडेट विधि को inParams तर्क में एक टैग :::: auth_token प्राप्त होता है। HMAC सत्यापित करता है कि टोकन मान्य है और इसमें एक मैचिंग सिक्योर यूजर आईडी है, कुंजी के टैग से मेल खाता है :: user_auth_type , और इसमें चैलेंज फ़ील्ड में वर्तमान ऑपरेशन के ऑपरेशन हैंडल शामिल हैं। यदि ये शर्तें पूरी नहीं होती हैं, तो ErrorCode::KEY_USER_NOT_AUTHENTICATED

कॉलर अपडेट और खत्म करने के लिए हर कॉल को प्रमाणीकरण टोकन प्रदान करता है। यदि यह पसंद करता है तो कार्यान्वयन को केवल एक बार टोकन को मान्य करने की आवश्यकता होती है।

आरएसए कुंजी

कुछ अतिरिक्त आवश्यकताएं, पैडिंग मोड के आधार पर:

  • PaddingMode::NONE । अप्रकाशित हस्ताक्षर और एन्क्रिप्शन संचालन के लिए, यदि प्रदान किया गया डेटा कुंजी से कम है, तो डेटा साइनिंग/एन्क्रिप्शन से पहले बाईं ओर शून्य-गद्देदार है। यदि डेटा कुंजी के समान लंबाई है, लेकिन संख्यात्मक रूप से बड़ा है, तो ErrorCode::INVALID_ARGUMENT । सत्यापन और डिक्रिप्शन संचालन के लिए, डेटा की कुंजी के रूप में बिल्कुल होना चाहिए। अन्यथा, ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS । पीएसएस-पैडेड हस्ताक्षर संचालन के लिए, पीएसएस नमक संदेश डाइजेस्ट का आकार है और बेतरतीब ढंग से उत्पन्न होता है। टैग के साथ निर्दिष्ट डाइजेस्ट :: inputParams में डाइजेस्ट शुरू पर पीएसएस डाइजेस्ट एल्गोरिथ्म के रूप में उपयोग किया जाता है, और MGF1 डाइजेस्ट एल्गोरिथ्म के रूप में।
  • PaddingMode::RSA_OAEPटैग के साथ निर्दिष्ट डाइजेस्ट :: inputParams में डाइजेस्ट शुरू पर OAEP डाइजेस्ट एल्गोरिथ्म के रूप में उपयोग किया जाता है, और SHA1 का उपयोग MGF1 डाइजेस्ट एल्गोरिथ्म के रूप में किया जाता है।

Ecdsa keys

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

एईएस चाबियाँ

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

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

गर्भपात

संस्करण : 1, 2, 3

इन-प्रोग्रेस ऑपरेशन को रोकता है। Abort करने के लिए कॉल के बाद, ErrorCode::INVALID_OPERATION_HANDLE अद्यतन , फिनिश या एबॉर्ट के साथ प्रदान किए गए ऑपरेशन हैंडल के किसी भी बाद के उपयोग के लिए Invalid_operation_handle।

get_supported_algorithms

संस्करण 1

कीमास्टर हार्डवेयर कार्यान्वयन द्वारा समर्थित एल्गोरिदम की सूची लौटाता है। एक सॉफ्टवेयर कार्यान्वयन एक खाली सूची लौटाता है; एक हाइब्रिड कार्यान्वयन एक सूची देता है जिसमें केवल एल्गोरिदम होता है जो हार्डवेयर द्वारा समर्थित होते हैं।

कीमास्टर 1 कार्यान्वयन आरएसए, ईसी, एईएस और एचएमएसी का समर्थन करते हैं।

get_supported_block_modes

संस्करण 1

एक निर्दिष्ट एल्गोरिथ्म और उद्देश्य के लिए कीमास्टर हार्डवेयर कार्यान्वयन द्वारा समर्थित एईएस ब्लॉक मोड की सूची लौटाता है।

आरएसए, ईसी और एचएमएसी के लिए, जो सिफर को ब्लॉक नहीं कर रहे हैं, विधि सभी मान्य उद्देश्यों के लिए एक खाली सूची लौटाती है। अमान्य उद्देश्यों को ErrorCode::INVALID_PURPOSE वापस करने के लिए विधि का कारण होना चाहिए।

कीमास्टर 1 कार्यान्वयन एईएस एन्क्रिप्शन और डिक्रिप्शन के लिए ईसीबी, सीबीसी, सीटीआर और जीसीएम का समर्थन करते हैं।

get_supported_padding_modes

संस्करण 1

एक निर्दिष्ट एल्गोरिथ्म और उद्देश्य के लिए कीमास्टर हार्डवेयर कार्यान्वयन द्वारा समर्थित पैडिंग मोड की सूची लौटाता है।

एचएमएसी और ईसी में पैडिंग की कोई धारणा नहीं है इसलिए विधि सभी वैध उद्देश्यों के लिए एक खाली सूची लौटाती है। अमान्य उद्देश्यों को ErrorCode::INVALID_PURPOSE वापस करने के लिए विधि का कारण होना चाहिए।

आरएसए के लिए, कीमास्टर 1 कार्यान्वयन समर्थन:

  • अप्रकाशित एन्क्रिप्शन, डिक्रिप्शन, हस्ताक्षर और सत्यापन। अप्रकाशित एन्क्रिप्शन और हस्ताक्षर के लिए, यदि संदेश सार्वजनिक मापांक से कम है, तो कार्यान्वयन को शून्य के साथ छोड़ दिया जाना चाहिए। अप्रकाशित डिक्रिप्शन और सत्यापन के लिए, इनपुट लंबाई को सार्वजनिक मापांक आकार से मेल खाना चाहिए।
  • PKCS#1 V1.5 एन्क्रिप्शन और साइनिंग पैडिंग मोड
  • 20 की न्यूनतम नमक लंबाई के साथ पीएसएस
  • OAEP

ईसीबी और सीबीसी मोड में एईएस के लिए, कीमास्टर 1 कार्यान्वयन कोई पैडिंग और पीकेसीएस#7-पैडिंग का समर्थन करता है। CTR और GCM मोड केवल कोई पैडिंग नहीं करते हैं।

get_supported_digests

संस्करण 1

एक निर्दिष्ट एल्गोरिथ्म और उद्देश्य के लिए कीमास्टर हार्डवेयर कार्यान्वयन द्वारा समर्थित डाइजेस्ट मोड की सूची लौटाता है।

कोई एईएस मोड का समर्थन नहीं करता है या पचाने की आवश्यकता नहीं है, इसलिए विधि वैध उद्देश्यों के लिए एक खाली सूची लौटाती है।

Keymaster 1 कार्यान्वयन परिभाषित डाइजेस्ट के सबसेट को लागू कर सकते हैं। कार्यान्वयन SHA-256 प्रदान करते हैं और MD5, SHA1, SHA-224, SHA-256, SHA384 और SHA512 (परिभाषित पाचन का पूरा सेट) प्रदान कर सकते हैं।

get_supported_import_formats

संस्करण 1

एक निर्दिष्ट एल्गोरिथ्म के कीमास्टर हार्डवेयर कार्यान्वयन द्वारा समर्थित आयात प्रारूपों की सूची लौटाता है।

Keymaster 1 कार्यान्वयन RSA और EC कुंजी जोड़े आयात करने के लिए PKCS#8 प्रारूप (पासवर्ड सुरक्षा के बिना) का समर्थन करते हैं, और AE और HMAC कुंजी सामग्री के कच्चे आयात का समर्थन करते हैं।

get_supported_export_formats

संस्करण 1

एक निर्दिष्ट एल्गोरिथ्म के कीमास्टर हार्डवेयर कार्यान्वयन द्वारा समर्थित निर्यात प्रारूपों की सूची लौटाता है।

Keymaster1 कार्यान्वयन RSA और EC सार्वजनिक कुंजी के निर्यात के लिए X.509 प्रारूप का समर्थन करते हैं। निजी कुंजियों या असममित कुंजियों का निर्यात समर्थित नहीं है।

ऐतिहासिक कार्य

कीमास्टर ०

निम्नलिखित कार्य मूल कीमास्टर 0 परिभाषा से संबंधित हैं। वे Keymaster 1 संरचना keymaster1_device_t में मौजूद थे। हालांकि, कीमास्टर 1.0 में उन्हें लागू नहीं किया गया था, और उनके फ़ंक्शन पॉइंटर्स को अशक्त करने के लिए सेट किया गया था।

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

कीमास्टर 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

कीमास्टर 2

निम्नलिखित कार्य Keymaster 2 परिभाषा से संबंधित हैं, लेकिन Keymaster 3 में हटाए गए थे, साथ ही ऊपर सूचीबद्ध Keymaster 1 फ़ंक्शन के साथ।

  • configure