คุณกำลังดูเอกสารประกอบของ 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 จะบังคับใช้ข้อจํากัดเพิ่มเติม เช่น นําอักขระที่ไม่ใช่ตัวอักษรและตัวเลขคละกันออกโดยอัตโนมัติ
(ไม่บังคับ) ใช้องค์ประกอบ |
ไม่มีข้อมูล | จำเป็น |
continueOnError |
ตั้งค่าเป็น false เพื่อแสดงผลข้อผิดพลาดเมื่อนโยบายล้มเหลว ซึ่งถือเป็นเรื่องปกติสำหรับนโยบายส่วนใหญ่
ตั้งค่าเป็น |
false | ไม่บังคับ |
เปิดใช้อยู่ |
ตั้งค่าเป็น true เพื่อบังคับใช้นโยบาย
ตั้งค่าเป็น |
จริง | ไม่บังคับ |
async | แอตทริบิวต์นี้เลิกใช้งานแล้ว | false | เลิกใช้ |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
ระบุอัลกอริทึมแฮชเพื่อประมวลผล HMAC
ค่าเริ่มต้น | ไม่มีข้อมูล |
การปรากฏ | จำเป็น |
ประเภท | สตริง |
ค่าที่ถูกต้อง | SHA-1 , SHA-224 , SHA-256 , SHA-384 , SHA-512 และ MD-5
การกำหนดค่านโยบายจะยอมรับชื่ออัลกอริทึมโดยไม่แยกตัวพิมพ์เล็ก/ใหญ่ รวมถึงมีหรือไม่มีเครื่องหมายขีดกลางระหว่างตัวอักษรและตัวเลข เช่น |
<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 ด้วยค่าที่เข้ารหัส base64 |
ประเภท | สตริง |
ค่าที่ถูกต้อง | สำหรับการเข้ารหัส ค่าต่างๆ ไม่คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ โดย ค่าข้อความขององค์ประกอบ |
<SecretKey>
<SecretKey encoding='encoding_name' ref='private.secretkey'/>
ระบุคีย์ข้อมูลลับที่ใช้ในการคำนวณ HMAC คีย์จะได้มาจากตัวแปรที่อ้างอิงซึ่งถอดรหัสตามการเข้ารหัสที่เฉพาะเจาะจง
ค่าเริ่มต้น |
ไม่มีค่าเริ่มต้นของตัวแปรที่อ้างอิง คุณต้องระบุแอตทริบิวต์ หากไม่มีแอตทริบิวต์ |
การปรากฏ | จำเป็น |
ประเภท | สตริง |
ค่าที่ถูกต้อง | สำหรับ การใช้แอตทริบิวต์การเข้ารหัสช่วยให้คุณระบุคีย์ที่มีไบต์ที่อยู่นอกช่วงอักขระที่พิมพ์ได้ UTF-8 เช่น สมมติว่าการกำหนดค่านโยบายมีสิ่งต่อไปนี้ <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
และสมมติว่า
ในกรณีนี้ ระบบจะถอดรหัสไบต์คีย์เป็น [53 65 63 72 65 74 31 32 33]
(แต่ละไบต์แสดงเป็นเลขฐาน 16) อีกตัวอย่างหนึ่งคือ หาก |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
(ไม่บังคับ) ระบุค่าการยืนยันรวมถึงอัลกอริทึมการเข้ารหัสที่ใช้เพื่อเข้ารหัสค่าการยืนยัน โดยนโยบายจะใช้อัลกอริทึมนี้เพื่อถอดรหัสค่า
ค่าเริ่มต้น | ไม่มีค่าการยืนยันเริ่มต้น หากมีองค์ประกอบแต่ไม่มีแอตทริบิวต์ encoding นโยบายจะใช้การเข้ารหัสตามค่าเริ่มต้นเป็น base64 |
การปรากฏ | ไม่บังคับ |
ประเภท | สตริง |
ค่าที่ถูกต้อง |
ค่าที่ถูกต้องสำหรับแอตทริบิวต์การเข้ารหัสคือ การเข้ารหัสของ |
<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>