Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về
Apigee X. thông tin
Tính toán và xác minh Mã xác thực thư dựa trên hàm băm (HMAC). Đôi khi được gọi là Mã xác thực thông báo được khoá hoặc Hàm băm được khoá, HMAC sử dụng hàm băm mật mã như SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 hoặc MD-5, áp dụng cho "tin nhắn" cùng với khoá bí mật để tạo mã xác thực chữ ký hoặc thông báo trên thông báo đó. Thuật ngữ "tin nhắn" ở đây đề cập đến mọi luồng byte. Người gửi thư cũng có thể gửi HMAC cho người nhận và người nhận có thể sử dụng HMAC để xác thực thư.
Để tìm hiểu thêm về HMAC, hãy xem nội dung HMAC: Băm khoá để xác thực thông báo (rfc2104).
Mẫu
Tạo 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>
Xác minh 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>
Việc tính toán chữ ký và xác minh chữ ký đó tuân theo y hệt một quy trình. Chính sách HMAC tính toán HMAC và có thể tuỳ ý xác minh chữ ký đã tính toán dựa trên giá trị dự kiến. Phần tử VerifyValue không bắt buộc (nếu có) hướng dẫn chính sách kiểm tra giá trị đã tính toán so với một giá trị đã biết hoặc đã cho.
Tham chiếu phần tử cho HMAC
Tài liệu tham khảo chính sách mô tả các phần tử và thuộc tính của chính sách HMAC.
Những thuộc tính áp dụng cho phần tử cấp cao nhất
<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">
Những thuộc tính sau đây là những thuộc tính chung của tất cả phần tử mẹ của chính sách.
Thuộc tính | Mô tả | Mặc định | Sự hiện diện |
---|---|---|---|
tên |
Tên nội bộ của chính sách. Bạn chỉ được dùng các ký tự sau đây trong tên:
A-Z0-9._\-$ % . Tuy nhiên, giao diện người dùng Apigee thực thi các hạn chế bổ sung, chẳng hạn như tự động xoá các ký tự không phải là chữ và số.
Nếu muốn, bạn có thể sử dụng phần tử |
Không áp dụng | Bắt buộc |
continueOnError |
Đặt thành false để trả về lỗi khi một chính sách không hoạt động. Đây là hành vi dự kiến đối với hầu hết các chính sách.
Đặt thành |
false | Không bắt buộc |
đang bật |
Đặt thành true để thực thi chính sách.
Đặt thành |
đúng | Không bắt buộc |
async | Thuộc tính này không được dùng nữa. | false | Không được dùng nữa |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
Chỉ định thuật toán băm để tính toán HMAC.
Mặc định | Không áp dụng |
Sự hiện diện | Bắt buộc |
Loại | Chuỗi |
Giá trị hợp lệ | SHA-1 , SHA-224 , SHA-256 , SHA-384 , SHA-512 và MD-5
Cấu hình chính sách chấp nhận tên thuật toán mà không phân biệt chữ hoa chữ thường, có hoặc không có dấu gạch ngang giữa chữ cái và số . Ví dụ: |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Sử dụng cùng với thuộc tính tên để gắn nhãn cho chính sách bằng một tên khác bằng ngôn ngữ tự nhiên trong trình chỉnh sửa proxy giao diện người dùng của Apigee.
Mặc định | Nếu bạn bỏ qua phần tử này, giá trị của thuộc tính tên của chính sách sẽ được sử dụng. |
Sự hiện diện | Không bắt buộc |
Loại | Chuỗi |
<Message>
<Message>message_template_here</Message> or <Message ref='variable_here'/>
Chỉ định tải trọng thông báo để ký. Dữ liệu đầu vào của phần tử này hỗ trợ mẫu thông báo (thay thế biến) để cho phép đưa thêm các mục khác vào thời gian chạy, chẳng hạn như dấu thời gian, nonces, danh sách tiêu đề hoặc thông tin khác. Ví dụ:
<Message>Fixed Part {a_variable} {timeFormatUTCMs(timeFormatString1,system.timestamp)} {nonce} </Message>
Mẫu thông báo có thể bao gồm các phần cố định và có thể thay đổi, bao gồm cả các dòng mới và các hàm tĩnh. Khoảng trắng rất quan trọng.
Mặc định | Không áp dụng |
Sự hiện diện | Bắt buộc |
Loại | Chuỗi |
Giá trị hợp lệ | Bất kỳ chuỗi nào cũng đều hợp lệ đối với giá trị văn bản. Nếu bạn cung cấp thuộc tính ref thì thuộc tính này sẽ được ưu tiên hơn giá trị văn bản. Chính sách này đánh giá giá trị văn bản hoặc biến được tham chiếu như một mẫu thông báo. |
<Đầu ra>
<Output encoding='encoding_name'>variable_name</Output>
Chỉ định tên của biến mà chính sách cần đặt bằng giá trị HMAC đã tính toán. Đồng thời chỉ định phương thức mã hoá để sử dụng cho dữ liệu đầu ra.
Mặc định |
Biến đầu ra mặc định là Giá trị mặc định của thuộc tính |
Sự hiện diện | Không bắt buộc. Nếu không có phần tử này, thì chính sách sẽ đặt biến luồng hmac.POLICYNAME.output với giá trị được mã hoá base64. |
Loại | Chuỗi |
Giá trị hợp lệ | Để mã hoá, Các giá trị không phân biệt chữ hoa chữ thường; Giá trị văn bản của phần tử |
<SecretKey>
<SecretKey encoding='encoding_name' ref='private.secretkey'/>
Chỉ định khoá bí mật dùng để tính toán HMAC. Khoá được lấy từ biến được tham chiếu, được giải mã theo phương thức mã hoá cụ thể.
Mặc định |
Không có giá trị mặc định cho biến được tham chiếu; bạn bắt buộc phải thuộc tính Khi không có thuộc tính |
Sự hiện diện | Bắt buộc |
Loại | Chuỗi |
Giá trị hợp lệ | Đối với Việc sử dụng thuộc tính mã hoá cho phép bạn chỉ định một khoá có chứa các byte nằm ngoài phạm vi các ký tự UTF-8 có thể in. Ví dụ: giả sử cấu hình chính sách có chứa: <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
Giả sử
Trong trường hợp này, các byte khoá sẽ được giải mã dưới dạng: [53 65 63 72 65 74 31 32 33] (mỗi byte được biểu thị bằng hệ thập lục phân). Một ví dụ khác: nếu |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
(Không bắt buộc) Chỉ định giá trị xác minh, cũng như thuật toán mã hoá dùng để mã hoá giá trị xác minh. Chính sách sẽ sử dụng thuật toán này để giải mã giá trị.
Mặc định | Không có giá trị xác minh mặc định. Nếu phần tử này có mặt nhưng không có thuộc tính encoding , thì chính sách sẽ sử dụng phương thức mã hoá mặc định là base64 |
Sự hiện diện | Không bắt buộc |
Loại | Chuỗi |
Giá trị hợp lệ |
Các giá trị hợp lệ cho thuộc tính mã hoá là: Phương thức mã hoá của |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Đặt thành false
nếu bạn muốn chính sách này báo lỗi khi không thể giải quyết mọi biến được tham chiếu đã chỉ định
trong chính sách. Đặt thành true
để coi mọi biến không thể phân giải là chuỗi trống (null).
Boolean IgnoreUnresolvedVariables chỉ ảnh hưởng đến các biến mà mẫu thông báo tham chiếu đến. Mặc dù SecretKey
và VerificationValue
có thể tham chiếu một biến, nhưng cả hai đều cần phân giải được. Vì vậy, chế độ cài đặt ignore
không áp dụng cho các biến đó.
Mặc định | Sai |
Sự hiện diện | Không bắt buộc |
Loại | Boolean |
Giá trị hợp lệ | true hoặc false |
Biến luồng
Chính sách có thể đặt các biến này trong quá trình thực thi.
Biến | Nội dung mô tả | Ví dụ: |
---|---|---|
hmac.policy_name.message |
Chính sách này đặt biến này bằng thông điệp hiệu quả,
là kết quả đánh giá mẫu thông báo được chỉ định trong
phần tử Message . |
hmac.HMAC-Policy.message = "Hello, World" |
hmac.policy_name.output |
Lấy kết quả của phép tính HMAC, khi phần tử Output không chỉ định tên biến. |
hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4= |
hmac.policy_name.outputencoding |
Lấy tên của mã hoá đầu ra. | hmac.HMAC-Policy.outputencoding = base64 |
Tham chiếu lỗi
Phần này mô tả các mã lỗi và thông báo lỗi được trả về cũng như các biến lỗi mà Apigee đặt ra khi chính sách này kích hoạt lỗi. Thông tin này đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.
Lỗi thời gian chạy
Những lỗi này có thể xảy ra khi thực thi chính sách.
Mã lỗi | Trạng thái HTTP | Xảy ra khi |
---|---|---|
steps.hmac.UnresolvedVariable |
401 | Lỗi này xảy ra nếu biến được chỉ định trong chính sách HMAC:
|
steps.hmac.HmacVerificationFailed |
401 | Xác minh HMAC không thành công; giá trị xác minh được cung cấp không khớp với giá trị được tính toán. |
steps.hmac.HmacCalculationFailed |
401 | Chính sách này không thể tính HMAC. |
steps.hmac.EmptySecretKey |
401 | Giá trị của biến khoá bí mật đang trống. |
steps.hmac.EmptyVerificationValue |
401 | Biến chứa giá trị xác minh đang trống. |
Lỗi triển khai
Những lỗi này có thể xảy ra khi bạn triển khai proxy chứa chính sách này.
Tên lỗi | Trạng thái HTTP | Xảy ra khi |
---|---|---|
steps.hmac.MissingConfigurationElement |
401 | Lỗi này xảy ra khi thiếu một phần tử hoặc thuộc tính bắt buộc. |
steps.hmac.InvalidValueForElement |
401 | Lỗi này xảy ra nếu giá trị được chỉ định trong phần tử Thuật toán không phải là một trong các giá trị sau: SHA-1 , SHA-224 , SHA-256 , SHA-512 hoặc MD-5 . |
steps.hmac.InvalidSecretInConfig |
401 | Lỗi này xảy ra nếu có một giá trị văn bản được cung cấp rõ ràng cho SecretKey . |
steps.hmac.InvalidVariableName |
401 | Lỗi này xảy ra nếu biến SecretKey không chứa
tiền tố private (private. ). |
Biến lỗi
Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách.
Biến | Trong đó | Ví dụ: |
---|---|---|
fault.name="fault_name" |
fault_name là tên của lỗi, như liệt kê trong bảng Lỗi thời gian chạy ở trên. Tên lỗi là phần cuối cùng của mã lỗi. | fault.name Matches "UnresolvedVariable" |
hmac.policy_name.failed |
Chính sách này sẽ đặt biến này trong trường hợp không thành công. | hmac.HMAC-Policy.failed = true |
Ví dụ về phản hồi lỗi
Để xử lý lỗi, phương pháp hay nhất là giữ phần errorcode
của phản hồi lỗi. Đừng dựa vào văn bản trong faultstring
vì văn bản này có thể thay đổi.
Ví dụ về quy tắc lỗi
<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>