นโยบาย HMAC

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X
ข้อมูล

ประมวลผลและยืนยันโค้ดการตรวจสอบสิทธิ์ข้อความตามแฮช (HMAC) HMAC จะใช้ฟังก์ชันแฮชแบบเข้ารหัส เช่น SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 หรือ MD-5 กับ "ข้อความ" พร้อมกับคีย์ลับ เพื่อสร้างรหัสการตรวจสอบสิทธิ์ลายเซ็นหรือข้อความในข้อความนั้น บางครั้งเรียกว่ารหัสการตรวจสอบสิทธิ์ข้อความแบบคีย์หรือแฮชแบบคีย์ คำว่า "message" ในที่นี้หมายถึงสตรีมของไบต์ใดก็ได้ ผู้ส่งข้อความยังส่ง HMAC ไปยังผู้รับได้ด้วย และผู้รับจะใช้ HMAC เพื่อตรวจสอบสิทธิ์ข้อความได้

ดูข้อมูลเพิ่มเติมเกี่ยวกับ HMAC ได้ที่ HMAC: Keyed-Hashing for Message Authentication (rfc2104)

ลองฟัง

สร้าง 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>

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

</HMAC>

ยืนยัน 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 จะคำนวณ HMAC และอาจยืนยันลายเซ็นที่คำนวณกับค่าที่คาดไว้ได้ องค์ประกอบ VerificationValue ที่ไม่บังคับ (หากมี) จะสั่งให้นโยบายตรวจสอบค่าที่คำนวณกับค่าที่ทราบหรือค่าที่ระบุ


การอ้างอิงองค์ประกอบสำหรับ HMAC

ข้อมูลอ้างอิงนโยบายจะอธิบายองค์ประกอบและแอตทริบิวต์ของนโยบาย HMAC

แอตทริบิวต์ที่ใช้กับองค์ประกอบระดับบนสุด

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

แอตทริบิวต์ต่อไปนี้มีอยู่ในองค์ประกอบระดับบนสุดของนโยบายทั้งหมด

แอตทริบิวต์ คำอธิบาย ค่าเริ่มต้น การปรากฏ
ชื่อ ชื่อภายในของนโยบาย จำกัดอักขระที่ใช้ในชื่อได้ดังต่อไปนี้ A-Z0-9._\-$ % อย่างไรก็ตาม UI ของ Apigee จะบังคับใช้ข้อจํากัดเพิ่มเติม เช่น นําอักขระที่ไม่ใช่ตัวอักษรและตัวเลขคละกันออกโดยอัตโนมัติ

(ไม่บังคับ) ใช้องค์ประกอบ <displayname></displayname> เพื่อติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซี UI ของ Apigee ด้วยชื่อที่เป็นภาษาธรรมชาติที่แตกต่างออกไป

ไม่มีข้อมูล จำเป็น
continueOnError ตั้งค่าเป็น false เพื่อแสดงผลข้อผิดพลาดเมื่อนโยบายล้มเหลว ซึ่งถือเป็นเรื่องปกติสำหรับนโยบายส่วนใหญ่

ตั้งค่าเป็น true เพื่อให้การดำเนินการโฟลว์ดำเนินต่อไปได้แม้ว่านโยบายจะล้มเหลวก็ตาม

false ไม่บังคับ
เปิดใช้อยู่ ตั้งค่าเป็น true เพื่อบังคับใช้นโยบาย

ตั้งค่าเป็น false เพื่อ "ปิด" นโยบาย ระบบจะไม่บังคับใช้นโยบายแม้ว่าจะยังแนบอยู่กับขั้นตอนก็ตาม

จริง ไม่บังคับ
async แอตทริบิวต์นี้เลิกใช้งานแล้ว false เลิกใช้

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

ระบุอัลกอริทึมแฮชเพื่อประมวลผล HMAC

ค่าเริ่มต้น ไม่มีข้อมูล
การปรากฏ จำเป็น
ประเภท สตริง
ค่าที่ถูกต้อง SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 และ MD-5

การกำหนดค่านโยบายจะยอมรับชื่ออัลกอริทึมโดยไม่แยกตัวพิมพ์เล็ก/ใหญ่ รวมถึงมีหรือไม่มีเครื่องหมายขีดกลางระหว่างตัวอักษรและตัวเลข เช่น SHA256 และ SHA-256 และ sha256 มีค่าเท่ากัน

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

ใช้นอกเหนือจากแอตทริบิวต์ name เพื่อติดป้ายกำกับนโยบายในเครื่องมือแก้ไขพร็อกซี UI ของ Apigee ด้วยชื่อที่เป็นภาษาธรรมชาติที่แตกต่างออกไป

ค่าเริ่มต้น หากคุณไม่ใส่องค์ประกอบนี้ ระบบจะใช้ค่าของแอตทริบิวต์ชื่อของนโยบาย
การปรากฏ ไม่บังคับ
ประเภท สตริง

<Message>

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

ระบุเพย์โหลดของข้อความที่จะลงนาม อินพุตขององค์ประกอบนี้รองรับเทมเพลตข้อความ (การแทนที่ตัวแปร) เพื่อให้รวมรายการเพิ่มเติมขณะรันไทม์ได้ เช่น การประทับเวลา ค่านันทนาการ รายการส่วนหัว หรือข้อมูลอื่นๆ เช่น

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

เทมเพลตข้อความอาจมีส่วนที่เปลี่ยนแปลงได้และแบบคงที่ รวมถึงการขึ้นบรรทัดใหม่และฟังก์ชันแบบคงที่ ช่องว่างมีนัยสำคัญ

ค่าเริ่มต้น ไม่มีข้อมูล
การปรากฏ จำเป็น
ประเภท สตริง
ค่าที่ถูกต้อง สตริงใดก็ตามใช้ได้กับค่าข้อความ หากคุณระบุแอตทริบิวต์ ref แอตทริบิวต์ดังกล่าวจะมีลำดับความสำคัญเหนือค่าข้อความ นโยบายจะประเมินค่าข้อความหรือตัวแปรที่อ้างอิงเป็นเทมเพลตข้อความ

<เอาต์พุต>

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

ระบุชื่อตัวแปรที่นโยบายควรตั้งค่าด้วยค่า HMAC ที่คำนวณไว้ รวมถึงระบุการเข้ารหัสที่จะใช้สำหรับเอาต์พุต

ค่าเริ่มต้น

ตัวแปรเอาต์พุตเริ่มต้นคือ hmac.POLICYNAME.output

ค่าเริ่มต้นสำหรับแอตทริบิวต์ encoding คือ base64

การปรากฏ ไม่บังคับ หากไม่มีองค์ประกอบนี้ นโยบายจะตั้งค่าตัวแปรโฟลว์ hmac.POLICYNAME.output ด้วยค่าที่เข้ารหัส base64
ประเภท สตริง
ค่าที่ถูกต้อง

สำหรับการเข้ารหัส hex, base16, base64, base64url

ค่าต่างๆ ไม่คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ โดย hex และ base16 คือคําพ้องความหมาย

ค่าข้อความขององค์ประกอบ Output อาจเป็นชื่อตัวแปรโฟลว์ที่ถูกต้องก็ได้

<SecretKey>

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

ระบุคีย์ข้อมูลลับที่ใช้ในการคำนวณ HMAC คีย์จะได้มาจากตัวแปรที่อ้างอิงซึ่งถอดรหัสตามการเข้ารหัสที่เฉพาะเจาะจง

ค่าเริ่มต้น

ไม่มีค่าเริ่มต้นของตัวแปรที่อ้างอิง คุณต้องระบุแอตทริบิวต์ ref

หากไม่มีแอตทริบิวต์ encoding โดยค่าเริ่มต้น นโยบายจะถอดรหัสสตริงคีย์ลับด้วย UTF-8 เพื่อรับไบต์ของคีย์

การปรากฏ จำเป็น
ประเภท สตริง
ค่าที่ถูกต้อง

สำหรับ 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] (แต่ละไบต์แสดงเป็นเลขฐาน 16) อีกตัวอย่างหนึ่งคือ หาก 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
การปรากฏ ไม่บังคับ
ประเภท สตริง
ค่าที่ถูกต้อง

ค่าที่ถูกต้องสำหรับแอตทริบิวต์การเข้ารหัสคือ hex, base16, base64, base64url ค่าต่างๆ ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ โดย hex และ base16 เป็นคําพ้องความหมาย

การเข้ารหัสของ VerificationValue ไม่จำเป็นต้องเหมือนกับการเข้ารหัสที่ใช้สำหรับองค์ประกอบ Output

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

ตั้งค่าเป็น false หากต้องการให้นโยบายแสดงข้อผิดพลาดเมื่อแก้ไขตัวแปรที่อ้างอิงที่ระบุในนโยบายไม่ได้ ตั้งค่าเป็น true เพื่อรักษาตัวแปรที่แปลงไม่ได้เป็นสตริงว่าง (Null)

บูลีน DisallowUnresolvedVariable มีผลกับตัวแปรที่เทมเพลตข้อความอ้างอิงเท่านั้น แม้ว่า SecretKey และ VerificationValue จะอ้างอิงตัวแปรได้ แต่ทั้ง 2 อย่างนี้จะต้องแปลงค่าได้ ดังนั้นการตั้งค่า ignore จึงไม่มีผลกับค่าเหล่านั้น

ค่าเริ่มต้น เท็จ
การปรากฏ ไม่บังคับ
ประเภท บูลีน
ค่าที่ถูกต้อง จริงหรือเท็จ

ตัวแปรโฟลว์

นโยบายนี้จะตั้งค่าตัวแปรเหล่านี้ได้ระหว่างการดำเนินการ

ตัวแปร คำอธิบาย ตัวอย่าง
hmac.policy_name.message นโยบายจะกำหนดตัวแปรนี้ด้วยข้อความที่มีประสิทธิภาพ ซึ่งเป็นผลมาจากการประเมินเทมเพลตข้อความที่ระบุในองค์ประกอบ Message hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output รับผลการคำนวณ HMAC เมื่อองค์ประกอบ Output ไม่ได้ระบุชื่อตัวแปร hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding รับชื่อของการเข้ารหัสเอาต์พุต hmac.HMAC-Policy.outputencoding = base64

การอ้างอิงข้อผิดพลาด

ส่วนนี้จะอธิบายโค้ดข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่แสดงผลและตัวแปรความผิดที่ Apigee กำหนดเมื่อนโยบายนี้ทริกเกอร์ข้อผิดพลาด ข้อมูลนี้เป็นสิ่งสำคัญที่ต้องทราบหากคุณกำลังกำหนดกฎข้อผิดพลาดเพื่อจัดการกับข้อผิดพลาด ดูข้อมูลเพิ่มเติมได้ที่สิ่งที่คุณต้องทราบเกี่ยวกับข้อผิดพลาดของนโยบายและการจัดการข้อผิดพลาด

ข้อผิดพลาดเกี่ยวกับรันไทม์

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อนโยบายทำงาน

รหัสข้อผิดพลาด สถานะ HTTP เกิดขึ้นเมื่อ
steps.hmac.UnresolvedVariable 401

ข้อผิดพลาดนี้เกิดขึ้นหากตัวแปรที่ระบุในนโยบาย HMAC มีลักษณะดังนี้

  • อยู่นอกขอบเขต (ใช้ไม่ได้ในขั้นตอนเฉพาะเจาะจงที่มีการใช้นโยบาย)

    หรือ

  • แก้ไขไม่ได้ (ไม่ได้กำหนดไว้)
steps.hmac.HmacVerificationFailed 401 การยืนยัน HMAC ล้มเหลว ค่าการยืนยันที่ระบุไม่ตรงกับมูลค่าที่คำนวณไว้
steps.hmac.HmacCalculationFailed 401 นโยบายนี้คำนวณ HMAC ไม่ได้
steps.hmac.EmptySecretKey 401 ค่าของตัวแปรคีย์ลับว่างเปล่า
steps.hmac.EmptyVerificationValue 401 ตัวแปรที่มีค่าการยืนยันว่างเปล่า

ข้อผิดพลาดในการทำให้ใช้งานได้

ข้อผิดพลาดเหล่านี้อาจเกิดขึ้นเมื่อคุณใช้พร็อกซีที่มีนโยบายนี้

ชื่อข้อผิดพลาด สถานะ HTTP เกิดขึ้นเมื่อ
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>