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

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

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

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

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

संस्करण : 1, 2

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

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

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

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

संस्करण : 1, 2

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

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

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

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

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

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

कार्यों

हार्डवेयर सुविधाएँ प्राप्त करें

संस्करण : 3

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

  • यदि सुरक्षित हार्डवेयर (TEE, आदि) में कुंजियों को संग्रहीत किया जाता है और इसे कभी नहीं छोड़ा जाता है, तो isSecure true है।
  • supportsEllipticCurve है EllipticCurve true अगर हार्डवेयर NIST कर्व्स (P-224, P-256, P-384, और P-521) के साथ Elliptic Curve क्रिप्टोग्राफी को सपोर्ट करता है।
  • यदि हार्डवेयर एईएस और true सहित सममित क्रिप्टोग्राफी का supportsSymmetricCryptography करता है, तो सिमेट्रिक क्रिप्टोग्राफी का समर्थन करता है।
  • supportsAttestation true यदि हार्डवेयर कीमास्टर सार्वजनिक कुंजी सत्यापन प्रमाणपत्र के निर्माण का समर्थन करता है, जो एक सुरक्षित वातावरण में एक कुंजी के साथ हस्ताक्षरित है।

यह विधि केवल त्रुटि कोड लौटा सकती है ErrorCode 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

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

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

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

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

जनरेटकी

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

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

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

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

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

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

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

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

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

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

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

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

एईएस कुंजी

एईएस कुंजी उत्पन्न करने के लिए केवल टैग :: 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 के बीच है।

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

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

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

मुख्य गुण

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

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

टैग::ROLLBACK_RESISTANT ।

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

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

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

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

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

आयातकुंजी

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

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

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

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

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

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

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

किसी Keymaster RSA या EC कुंजी युग्म से सार्वजनिक कुंजी निर्यात करता है।

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

हटाएंकुंजी

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

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

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

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

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

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

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

नष्टसत्यापन आईडी

संस्करण : 3

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

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

शुरू करना

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

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

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

यदि टैग::APPLICATION_ID या टैग::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 में एक मान्य टैग :: AUTH_TOKEN inParams होना चाहिए। प्रमाणीकरण टोकन के मान्य होने के लिए, निम्नलिखित सभी को सत्य होना चाहिए:
    • HMAC फ़ील्ड सही ढंग से मान्य करता है।
    • कुंजी में से कम से कम एक टैग :: USER_SECURE_ID मान टोकन में सुरक्षित आईडी मानों में से कम से कम एक से मेल खाता है।
    • कुंजी में एक टैग::USER_AUTH_TYPE है जो टोकन में प्रमाणन प्रकार से मेल खाता है।

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

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

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

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

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

निजी कुंजी संचालन ( KeyPurpose::DECYPT और KeyPurpose::SIGN ) को डाइजेस्ट और पैडिंग के प्राधिकरण की आवश्यकता होती है, जिसका अर्थ है कि प्रमुख प्राधिकरणों में निर्दिष्ट मान शामिल होने चाहिए। यदि नहीं, तो विधि उपयुक्त के रूप में ErrorCode::INCOMPATIBLE_DIGEST या ErrorCode::INCOMPATIBLE_PADDING 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 इंगित करता है कि एक "कच्चा" आरएसए ऑपरेशन किया जाता है। यदि हस्ताक्षर या सत्यापन करते हैं, तो Digest::NONE के लिए निर्दिष्ट है। पैड न किए गए एन्क्रिप्शन या डिक्रिप्शन के लिए कोई डाइजेस्ट आवश्यक नहीं है।
  • PaddingMode::RSA_PKCS1_1_5_SIGN पैडिंग के लिए डाइजेस्ट की आवश्यकता होती है। Digest::NONE हो सकता है, जिस स्थिति में Keymaster कार्यान्वयन उचित PKCS#1 v1.5 हस्ताक्षर संरचना नहीं बना सकता है, क्योंकि यह DigestInfo संरचना को नहीं जोड़ सकता है। इसके बजाय, कार्यान्वयन 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 लौटाती है।

ईसी कुंजी

ईसी कुंजी संचालन 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 BlockMode::GCM है, तो inParams Tag::MAC_LENGTH inParams करता है, और निर्दिष्ट मान 8 का एक गुणक है जो 128 से अधिक या प्रमुख प्राधिकरणों में Tag::MIN_MAC_LENGTH के मान से कम नहीं है। 128 से अधिक मैक लंबाई या 8 के गैर-गुणकों के लिए, 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 या गैर उत्पन्न करता है और इसे Tag:: NONCE के माध्यम से outParams में लौटाता है। CBC और CTR IVs 16 बाइट्स हैं। GCM नॉन 12 बाइट्स हैं। यदि मुख्य प्राधिकरणों में Tag::CALLER_NONCE है, तो कॉलर inParams में Tag :: inParams के साथ IV/nonce प्रदान कर सकता है। यदि टैग :: CALLER_NONCE अधिकृत नहीं होने पर एक गैर प्रदान किया जाता है, तो ErrorCode::CALLER_NONCE_PROHIBITED । अगर Tag::CALLER_NONCE के अधिकृत होने पर नॉन प्रदान नहीं किया जाता है, तो एक रैंडम IV/nonce जेनरेट करें।

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

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

अपडेट करें

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

एईएस कुंजी

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

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

समाप्त

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

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

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

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

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

Authorization enforcement

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

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

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

RSA keys

Some additional requirements, depending on the padding mode:

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

ECDSA keys

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

AES keys

Some additional conditions, depending on block mode:

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

abort

Version : 1, 2, 3

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

get_supported_algorithms

Version : 1

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

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

get_supported_block_modes

Version : 1

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

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

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

get_supported_padding_modes

Version : 1

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

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

For RSA, Keymaster 1 implementations support:

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

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

get_supported_digests

Version : 1

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

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

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

get_supported_import_formats

Version : 1

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

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

get_supported_export_formats

Version : 1

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

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

Historical functions

Keymaster 0

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

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

Keymaster 1

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

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

Keymaster 2

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

  • configure