HMAC नीति

Apigee Edge दस्तावेज़ देखा जा रहा है.
Apigee X दस्तावेज़ पर जाएं.
जानकारी

यह हैश पर आधारित मैसेज ऑथेंटिकेशन कोड (एचएमएसी) का इस्तेमाल करता है और उसकी पुष्टि करता है. एचएमएसी, कभी-कभी कुंजी वाले मैसेज की पुष्टि करने वाला कोड या कुंजी वाले हैश के रूप में जाना जाता है. एचएमएसी, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 या MD-5 जैसे क्रिप्टोग्राफ़िक हैश फ़ंक्शन का इस्तेमाल करता है. इसे "मैसेज" के साथ एक खास कुंजी के साथ लागू किया जाता है, ताकि मैसेज पर हस्ताक्षर या मैसेज की पुष्टि करने वाला कोड बनाया जा सके. यहां "मैसेज" शब्द का मतलब है, किसी भी बाइट स्ट्रीम को. मैसेज भेजने वाला व्यक्ति, मैसेज पाने वाले व्यक्ति को एचएमएसी भी भेज सकता है. साथ ही, मैसेज पाने वाला व्यक्ति मैसेज की पुष्टि करने के लिए एचएमएसी का इस्तेमाल कर सकता है.

एचएमएसी के बारे में ज़्यादा जानने के लिए, HMAC: Message Authentication (rfc2104) के लिए HMAC: Keyed-Ha मुफ़्तिंग देखें.

सैंपल

एचएमएसी जनरेट करें

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <SecretKey ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The "message" can include fixed and multiple variable parts,
    including newlines and static functions.
    Whitespace is significant.
   -->
  <Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
  </Message>

  <!-- default encoding is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

एचएमएसी की पुष्टि करें

<HMAC name='HMAC-1'>

  <Algorithm>SHA256</Algorithm>

  <SecretKey ref='private.secretkey'/>

  <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional -->

  <!--
    The "message" can include fixed and multiple variable parts,
    including newlines and static functions.
    Whitespace is significant.
   -->
  <Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
  </Message>

  <!--
    VerificationValue is optional.
    Include it to perform an HMAC check.
  -->
  <VerificationValue encoding='base16' ref='expected_hmac_value'/>

  <!-- default encoding is base64 -->
  <Output encoding='base16'>name_of_variable</Output>

</HMAC>

हस्ताक्षर का आकलन करने और उसकी पुष्टि करने की प्रक्रिया, दोनों में से किसी एक तरीके का ही इस्तेमाल होता है. एचएमएसी नीति एक एचएमएसी की गणना करती है और वैकल्पिक रूप से किसी अनुमानित वैल्यू के लिए कंप्यूट किए गए हस्ताक्षर की पुष्टि कर सकती है. पुष्टि करने वाला वैकल्पिक एलिमेंट (अगर मौजूद है), नीति को इस बात के लिए भेजता है कि कंप्यूट किए गए मान की जांच के लिए, जाने-पहचाने या दिए गए मान के साथ किया गया है.


एचएमएसी के लिए एलिमेंट रेफ़रंस

नीति के रेफ़रंस में, एचएमएसी नीति के एलिमेंट और एट्रिब्यूट के बारे में बताया गया है.

टॉप-लेवल एलिमेंट पर लागू होने वाले एट्रिब्यूट

<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">

ये एट्रिब्यूट, नीति के सभी पैरंट एलिमेंट के लिए एक जैसे होते हैं.

एट्रिब्यूट Description डिफ़ॉल्ट मौजूदगी
नाम नीति का अंदरूनी नाम. नाम में इस्तेमाल किए जाने वाले वर्ण, इन तक सीमित हैं: A-Z0-9._\-$ %. हालांकि, Apigee यूज़र इंटरफ़ेस (यूआई), अतिरिक्त पाबंदियां लागू करता है. जैसे, उन वर्णों को अपने-आप हटाना जो अक्षर और अंक नहीं हैं.

इसके अलावा, Apigee यूज़र इंटरफ़ेस (यूआई) के प्रॉक्सी एडिटर में, आम बोलचाल की भाषा में नीति को लेबल करने के लिए, <displayname></displayname> एलिमेंट का इस्तेमाल करें.

लागू नहीं ज़रूरी है
continueOnError इस नीति को false पर सेट करें, ताकि नीति के काम न करने पर गड़बड़ी का मैसेज दिखे. ज़्यादातर नीतियों में, ऐसा आम तौर पर किया जाता है.

किसी नीति के काम न करने पर भी फ़्लो एक्ज़ीक्यूट करने की प्रोसेस को जारी रखने के लिए, true पर सेट करें.

false ज़रूरी नहीं
चालू किया गया नीति लागू करने के लिए, true पर सेट करें.

नीति को "बंद" करने के लिए, false पर सेट करें. भले ही, यह नीति किसी फ़्लो से जुड़ी हुई हो, लेकिन उसे लागू नहीं किया जाएगा.

सही ज़रूरी नहीं
async यह एट्रिब्यूट अब काम नहीं करता. false बहिष्कृत

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

एचएमएसी को कंप्यूट करने के लिए हैश एल्गोरिदम तय करता है.

डिफ़ॉल्ट लागू नहीं
मौजूदगी ज़रूरी है
स्ट्रीम किस तरह की है String
मान्य वैल्यू SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, और MD-5

नीति कॉन्फ़िगरेशन, केस में अंतर किए बिना और अक्षरों और संख्याओं के बीच डैश के साथ या उसके बिना, एल्गोरिदम के नाम स्वीकार करता है . उदाहरण के लिए, SHA256 और SHA-256 और sha256 एक जैसे हैं.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Apigee यूज़र इंटरफ़ेस (यूआई) प्रॉक्सी एडिटर में, नीति को आम भाषा में अलग नाम से लेबल करने के लिए, नाम एट्रिब्यूट के साथ-साथ इसका इस्तेमाल करें.

डिफ़ॉल्ट अगर इस एलिमेंट को छोड़ दिया जाता है, तो नीति के नाम वाले एट्रिब्यूट की वैल्यू का इस्तेमाल किया जाता है.
मौजूदगी ज़रूरी नहीं
स्ट्रीम किस तरह की है String

<Message>

<Message>message_template_here</Message>
or
<Message ref='variable_here'/>

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

<Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
</Message>

मैसेज टेंप्लेट में, तय किए गए और वैरिएबल हिस्से शामिल हो सकते हैं. इनमें नई लाइनें और स्टैटिक फ़ंक्शन शामिल हैं. व्हाइटस्पेस अहम है.

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

<आउटपुट>

<Output encoding='encoding_name'>variable_name</Output>

इस वैरिएबल के नाम से यह तय होता है कि नीति को कंप्यूट किए गए एचएमएसी वैल्यू के साथ वैरिएबल को सेट करना चाहिए या नहीं. यह आउटपुट के लिए इस्तेमाल की जाने वाली एन्कोडिंग भी तय करता है.

डिफ़ॉल्ट

डिफ़ॉल्ट आउटपुट वैरिएबल hmac.POLICYNAME.output है.

encoding एट्रिब्यूट की डिफ़ॉल्ट वैल्यू base64 है.

मौजूदगी ज़रूरी नहीं. अगर यह एलिमेंट मौजूद नहीं है, तो नीति, base64 कोड में बदली गई वैल्यू के साथ फ़्लो वैरिएबल hmac.POLICYNAME.output को सेट करती है.
स्ट्रीम किस तरह की है String
मान्य वैल्यू

कोड में बदलने के लिए, hex, base16, base64, base64url.

वैल्यू केस-इनसेंसिटिव होती हैं. hex और base16 समानार्थी शब्द हैं.

Output एलिमेंट की टेक्स्ट वैल्यू, कोई भी मान्य फ़्लो वैरिएबल नाम हो सकता है.

<SecretKey>

<SecretKey encoding='encoding_name' ref='private.secretkey'/>

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

डिफ़ॉल्ट

रेफ़र किए गए वैरिएबल के लिए कोई डिफ़ॉल्ट वैल्यू नहीं है; ref एट्रिब्यूट ज़रूरी है.

encoding एट्रिब्यूट न होने की स्थिति में, नीति डिफ़ॉल्ट रूप से कुंजी की बाइट पाने के लिए, सीक्रेट कुंजी स्ट्रिंग को UTF-8 से डिकोड करती है.

मौजूदगी ज़रूरी है
स्ट्रीम किस तरह की है String
मान्य वैल्यू

encoding के लिए, मान्य वैल्यू hex, base16, base64, utf8 हैं. डिफ़ॉल्ट तौर पर, यह UTF8 होता है. वैल्यू, केस-इनसेंसिटिव होती हैं और डैश कोई खास नहीं होते. Base16, base-16 और bAse16 एक जैसे हैं. Base16 और Hex समानार्थी शब्द हैं.

एन्कोडिंग एट्रिब्यूट का इस्तेमाल करके, ऐसी कुंजी तय की जा सकती है जिसमें प्रिंट किए जा सकने वाले UTF-8 वर्णों की रेंज से बाहर के बाइट शामिल हों. उदाहरण के लिए, मान लें कि नीति के कॉन्फ़िगरेशन में यह शामिल है:

 <SecretKey encoding='hex' ref='private.encodedsecretkey'/>

और मान लें कि private.encodedsecretkey में 536563726574313233 स्ट्रिंग है.

इस मामले में, कुंजी बाइट को इस तरह से डिकोड किया जाएगा: [53 65 63 72 65 74 31 32 33] (हर बाइट को हेक्स में दिखाया जाता है). दूसरे उदाहरण के तौर पर, अगर encoding='base64' और private.encodedsecretkey में स्ट्रिंग U2VjcmV0MTIz होती है, तो इससे कुंजी के लिए भी उतने ही बाइट सेट मिलेंगे. कोड में बदलने के लिए इस्तेमाल होने वाले एट्रिब्यूट या UTF8 एट्रिब्यूट के साथ, स्ट्रिंग की वैल्यू Secret123 का इस्तेमाल करने पर भी स्ट्रिंग का एक ही सेट मिलेगा.

<VerificationValue>

<VerificationValue encoding='encoding_name' ref='variable_name'/>
or
<VerificationValue encoding='encoding_name'>string_value</VerificationValue>

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

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

एन्कोडिंग एट्रिब्यूट के लिए मान्य वैल्यू हैं: hex, base16, base64, base64url. वैल्यू केस-इनसेंसिटिव होती हैं. hex और base16 समानार्थी शब्द हैं.

यह ज़रूरी नहीं है कि VerificationValue की एन्कोडिंग और Output एलिमेंट के लिए इस्तेमाल की गई एन्कोडिंग एक जैसी न हो.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

अगर नीति में बताए गए किसी भी रेफ़र किए गए वैरिएबल को ठीक नहीं किया जा सकता, तो नीति से गड़बड़ी होने पर उसे false पर सेट करें. हल न किए जा सकने वाले किसी भी वैरिएबल को खाली स्ट्रिंग (शून्य) के तौर पर मेज़र करने के लिए, true पर सेट करें.

ignoreUnresolvedVariables बूलियन सिर्फ़ उन वैरिएबल पर असर डालता है जिन्हें मैसेज टेंप्लेट में रेफ़र किया गया है. SecretKey और VerificationValue किसी वैरिएबल का रेफ़रंस दे सकते हैं. हालांकि, इन दोनों को ठीक करना ज़रूरी है. इसलिए, उन पर ignore सेटिंग लागू नहीं होती.

डिफ़ॉल्ट गलत
मौजूदगी ज़रूरी नहीं
स्ट्रीम किस तरह की है बूलियन
मान्य वैल्यू सही या गलत

फ़्लो वैरिएबल

एक्ज़ीक्यूट करने के दौरान, नीति इन वैरिएबल को सेट कर सकती है.

वैरिएबल ब्यौरा उदाहरण
hmac.policy_name.message यह नीति, इस वैरिएबल को असरदार मैसेज के लिए सेट करती है. ऐसा करने से, Message एलिमेंट में दिए गए मैसेज टेंप्लेट की जांच की जाती है. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output इससे एचएमएसी कंप्यूटेशन का नतीजा मिलता है. ऐसा तब होता है, जब Output एलिमेंट, वैरिएबल का नाम नहीं बताता. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding आउटपुट एन्कोडिंग का नाम पाता है. hmac.HMAC-Policy.outputencoding = base64

गड़बड़ी का रेफ़रंस

इस सेक्शन में, गड़बड़ी के कोड और दिखाए गए गड़बड़ी के मैसेज के बारे में बताया गया है. साथ ही, इस नीति से किसी गड़बड़ी को ट्रिगर करने पर Apigee की ओर से सेट किए गए, गड़बड़ी के वैरिएबल के बारे में बताया गया है. यह जानकारी जानना ज़रूरी है कि क्या गड़बड़ियों को ठीक करने के लिए, गड़बड़ी से जुड़े नियम बनाए जा रहे हैं. ज़्यादा जानने के लिए, नीति से जुड़ी गड़बड़ियों के बारे में आपके लिए ज़रूरी जानकारी और गड़बड़ियों को ठीक करने के तरीके देखें.

रनटाइम से जुड़ी गड़बड़ियां

नीति के लागू होने पर ये गड़बड़ियां हो सकती हैं.

गड़बड़ी का कोड एचटीटीपी कोड स्थिति कब होता है
steps.hmac.UnresolvedVariable 401

यह गड़बड़ी तब होती है, जब एचएमएसी नीति में बताया गया कोई वैरिएबल:

  • दायरे से बाहर है (यह सुविधा उस फ़्लो में उपलब्ध नहीं होती जहां नीति लागू की जा रही है)

    या

  • रिज़ॉल्व नहीं किया जा सकता (तय नहीं किया गया है)
steps.hmac.HmacVerificationFailed 401 एचएमएसी पुष्टि नहीं हो सकी; पुष्टि करने के लिए दिया गया मान, दिए गए मान से मेल नहीं खाता है.
steps.hmac.HmacCalculationFailed 401 नीति एचएमएसी की गिनती नहीं कर सकी.
steps.hmac.EmptySecretKey 401 सीक्रेट कुंजी वैरिएबल की वैल्यू खाली है.
steps.hmac.EmptyVerificationValue 401 पुष्टि करने की वैल्यू रखने वाला वैरिएबल खाली है.

डिप्लॉयमेंट से जुड़ी गड़बड़ियां

ये गड़बड़ियां तब हो सकती हैं, जब इस नीति वाले किसी प्रॉक्सी को डिप्लॉय किया जाता है.

गड़बड़ी का नाम एचटीटीपी कोड स्थिति कब होता है
steps.hmac.MissingConfigurationElement 401 यह गड़बड़ी तब होती है, जब कोई ज़रूरी एलिमेंट या एट्रिब्यूट मौजूद नहीं होता.
steps.hmac.InvalidValueForElement 401 यह गड़बड़ी तब होती है, जब एल्गोरिदम एलिमेंट में दी गई वैल्यू, इनमें से कोई वैल्यू न हो: SHA-1, SHA-224, SHA-256, SHA-512 या MD-5.
steps.hmac.InvalidSecretInConfig 401 यह गड़बड़ी तब दिखती है, जब SecretKey के लिए साफ़ तौर पर टेक्स्ट वैल्यू दी गई हो.
steps.hmac.InvalidVariableName 401 यह गड़बड़ी तब होती है, जब SecretKey वैरिएबल में private प्रीफ़िक्स (private.) न हो.

गड़बड़ी वाले वैरिएबल

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

वैरिएबल जगह उदाहरण
fault.name="fault_name" fault_name, गड़बड़ी का नाम है, जैसा कि ऊपर दी गई रनटाइम की गड़बड़ियां टेबल में बताया गया है. गड़बड़ी का नाम, गड़बड़ी के कोड का आखिरी हिस्सा होता है. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed सफल न होने की स्थिति में, नीति इस वैरिएबल को सेट करती है. hmac.HMAC-Policy.failed = true

गड़बड़ी के जवाब का उदाहरण

गड़बड़ी को ठीक करने के लिए, सबसे सही तरीका यह है कि आप गड़बड़ी के रिस्पॉन्स के errorcode वाले हिस्से को फंसा दें. faultstring के टेक्स्ट पर भरोसा न करें, क्योंकि यह बदल सकता है.

गड़बड़ी के नियम का उदाहरण

<FaultRules>
    <FaultRule name="HMAC Policy Errors">
        <Step>
            <Name>AM-Unauthorized</Name>
            <Condition>(fault.name Matches "HmacVerificationFailed")</Condition>
        </Step>
        <Condition>hmac.HMAC-1.failed = true</Condition>
    </FaultRule>
</FaultRules>