Anda sedang melihat dokumentasi Apigee Edge.
Buka
Dokumentasi Apigee X. info
Menghitung dan memverifikasi Hash-based Message Authentication Code (HMAC). Kadang-kadang yang dikenal sebagai {i>Keyed Message Authentication Code<i} atau {i> Keyed hash<i}, HMAC menggunakan {i>hash<i} kriptografi fungsi seperti SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 atau MD-5, diterapkan ke sebuah "pesan," beserta sebuah kunci rahasia, untuk menghasilkan tanda tangan atau kode otentikasi pesan pada pesan itu. Istilah "pesan" di sini mengacu pada aliran byte. Pengirim pesan juga dapat mengirim HMAC ke penerima, dan penerima dapat menggunakan HMAC untuk mengotentikasi pesan.
Untuk mempelajari HMAC lebih lanjut, lihat HMAC: Keyed-Hashing untuk Message Authentication (rfc2104).
Contoh
Buat 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>
Memverifikasi 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>
Penghitungan tanda tangan dan verifikasi tanda tangan tersebut dilakukan dengan sama persis {i>checkout<i}. Kebijakan HMAC mengomputasi HMAC, dan dapat secara opsional memverifikasi tanda tangan terhadap nilai yang diharapkan. Elemen VerificationValue opsional (jika ada) mengarahkan kebijakan untuk memeriksa nilai komputasi terhadap nilai yang diketahui atau dengan sejumlah nilai.
Referensi elemen untuk HMAC
Referensi kebijakan menjelaskan elemen dan atribut kebijakan HMAC.
Atribut yang diterapkan pada elemen tingkat atas
<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">
Atribut berikut umum untuk semua elemen induk kebijakan.
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
nama |
Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % . Namun, UI Apigee memberlakukan
seperti menghapus karakter yang bukan alfanumerik secara otomatis.
Secara opsional, gunakan elemen |
T/A | Wajib |
continueOnError |
Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan
untuk sebagian besar kebijakan.
Setel ke |
salah | Opsional |
diaktifkan |
Setel ke true untuk menerapkan kebijakan.
Setel ke |
true | Opsional |
asinkron | Atribut ini tidak digunakan lagi. | salah | Tidak digunakan lagi |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
Menentukan algoritma hash untuk menghitung HMAC.
Default | T/A |
Kehadiran | Wajib |
Jenis | String |
Nilai yang valid | SHA-1 , SHA-224 , SHA-256 , SHA-384 ,
SHA-512 , dan MD-5
Konfigurasi kebijakan menerima nama algoritme tanpa membedakan huruf besar/kecil, dan
dengan atau tanpa tanda hubung di antara huruf dan angka . Misalnya, |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Gunakan selain atribut nama untuk memberi label kebijakan di editor proxy UI Apigee dengan nama natural language yang berbeda.
Default | Jika Anda menghapus elemen ini, nilai atribut nama kebijakan akan digunakan. |
Kehadiran | Opsional |
Jenis | String |
<Message>
<Message>message_template_here</Message> or <Message ref='variable_here'/>
Menentukan payload pesan yang akan ditandatangani. Input elemen ini mendukung template pesan (substitusi variabel) untuk memungkinkan item tambahan disertakan pada runtime, seperti stempel waktu, nonce, daftar {i>header<i}, atau informasi lainnya. Contoh:
<Message>Fixed Part {a_variable} {timeFormatUTCMs(timeFormatString1,system.timestamp)} {nonce} </Message>
Template pesan dapat menyertakan bagian tetap dan variabel, termasuk baris baru dan fungsi statis. Spasi kosong adalah signifikan.
Default | T/A |
Kehadiran | Wajib |
Jenis | String |
Nilai yang valid | String apa pun valid untuk nilai teks. Jika Anda memberikan atribut ref ,
parameter ini akan diprioritaskan daripada nilai teks. Kebijakan ini mengevaluasi teks
atau variabel yang direferensikan sebagai template pesan. |
<Output>
<Output encoding='encoding_name'>variable_name</Output>
Menentukan nama variabel yang harus ditetapkan kebijakan dengan nilai HMAC yang dikomputasi. Juga menentukan encoding yang akan digunakan untuk output.
Default |
Variabel output default adalah Nilai default untuk atribut |
Kehadiran | Opsional. Jika elemen ini tidak ada, kebijakan akan menyetel variabel alur
hmac.POLICYNAME.output , dengan nilai yang dienkode base64. |
Jenis | String |
Nilai yang valid | Untuk encoding, Nilainya tidak peka huruf besar/kecil; Nilai teks elemen |
<SecretKey>
<SecretKey encoding='encoding_name' ref='private.secretkey'/>
Menentukan kunci rahasia yang digunakan untuk menghitung HMAC. Kunci tersebut diperoleh dari variabel, didekode sesuai dengan encoding tertentu.
Default |
Tidak ada nilai default untuk variabel yang direferensikan;
Atribut Jika tidak ada atribut |
Kehadiran | Wajib |
Jenis | String |
Nilai yang valid | Untuk Dengan menggunakan atribut encoding memungkinkan Anda untuk menentukan kunci yang berisi byte di luar rentang karakter UTF-8 yang dapat dicetak. Misalnya, konfigurasi kebijakan menyertakan hal berikut: <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
Dan anggaplah
Dalam hal ini, byte kunci akan diterjemahkan sebagai: [53 65 63 72 65 74 31 32 33]
(setiap byte direpresentasikan dalam heksadesimal). Sebagai contoh lain, jika |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
(Opsional) Menentukan nilai verifikasi, serta algoritma encoding yang yang digunakan untuk mengenkode nilai verifikasi. Kebijakan tersebut akan menggunakan algoritma ini untuk mendekode nilainya.
Default | Tidak ada nilai verifikasi default. Jika elemen itu ada tetapi
Atribut encoding tidak ada, kebijakan menggunakan encoding default base64 |
Kehadiran | Opsional |
Jenis | String |
Nilai yang valid |
Nilai yang valid untuk atribut encoding adalah: Encoding |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Tetapkan ke false
jika Anda ingin kebijakan menampilkan error saat variabel yang direferensikan ditentukan
dalam kebijakan itu tidak
dapat diselesaikan. Tetapkan ke true
untuk memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong
(null).
Boolean IgnoreUnresolvedVariables hanya memengaruhi variabel yang direferensikan oleh
template pesan. Meskipun SecretKey
dan VerificationValue
dapat mereferensikan variabel, keduanya
dari masalah tersebut harus bisa diselesaikan, jadi setelan ignore
tidak berlaku untuk itu.
Default | Salah |
Kehadiran | Opsional |
Jenis | Boolean |
Nilai yang valid | benar atau salah |
Variabel flow
Kebijakan ini dapat menetapkan variabel ini selama eksekusi.
Variabel | Deskripsi | Contoh |
---|---|---|
hmac.policy_name.message |
Kebijakan menetapkan variabel
ini dengan pesan yang efektif,
hasil evaluasi template pesan yang ditentukan dalam Message
. |
hmac.HMAC-Policy.message = "Hello, World" |
hmac.policy_name.output |
Mendapatkan hasil dari
komputasi HMAC, ketika elemen Output bekerja
tidak menentukan nama variabel. |
hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4= |
hmac.policy_name.outputencoding |
Mendapatkan nama encoding output. | hmac.HMAC-Policy.outputencoding = base64 |
Referensi error
Bagian ini menjelaskan kode kesalahan dan pesan error yang ditampilkan dan variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui apakah Anda mengembangkan aturan kesalahan untuk menangani kesalahan. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.
Error runtime
Error ini dapat terjadi saat kebijakan dieksekusi.
Kode kesalahan | Status HTTP | Terjadi saat |
---|---|---|
steps.hmac.UnresolvedVariable |
401 | Error ini terjadi jika variabel yang ditentukan dalam kebijakan HMAC:
|
steps.hmac.HmacVerificationFailed |
401 | Verifikasi HMAC gagal; nilai verifikasi yang diberikan tidak cocok dengan nilai yang dihitung. |
steps.hmac.HmacCalculationFailed |
401 | Kebijakan ini tidak dapat menghitung HMAC. |
steps.hmac.EmptySecretKey |
401 | Nilai variabel kunci rahasia kosong. |
steps.hmac.EmptyVerificationValue |
401 | Variabel yang menyimpan nilai verifikasi kosong. |
Error saat deployment
Error ini dapat terjadi saat Anda men-deploy proxy yang berisi kebijakan ini.
Nama error | Status HTTP | Terjadi saat |
---|---|---|
steps.hmac.MissingConfigurationElement |
401 | Error ini terjadi jika elemen atau atribut yang diperlukan tidak ada. |
steps.hmac.InvalidValueForElement |
401 | Error ini terjadi jika nilai yang ditentukan dalam elemen Algoritma bukan
salah satu dari nilai berikut: SHA-1 , SHA-224 , SHA-256 ,
SHA-512 , atau MD-5 . |
steps.hmac.InvalidSecretInConfig |
401 | Error ini terjadi jika ada nilai teks yang secara eksplisit disediakan untuk SecretKey . |
steps.hmac.InvalidVariableName |
401 | Error ini terjadi jika variabel SecretKey tidak berisi awalan private (private. ). |
Variabel kesalahan
Variabel ini ditetapkan saat terjadi error runtime. Untuk informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.
Variabel | Di mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahan, seperti yang tercantum dalam Tabel Error runtime di atas. Nama {i>error <i}adalah yang bagian dari kode kesalahan. | fault.name Matches "UnresolvedVariable" |
hmac.policy_name.failed |
Kebijakan akan menetapkan variabel ini jika terjadi kegagalan. | hmac.HMAC-Policy.failed = true |
Contoh respons error
Untuk penanganan error, praktik terbaiknya adalah menangkap bagian errorcode
dari error
yang dihasilkan. Jangan mengandalkan teks di faultstring
, karena dapat berubah.
Contoh aturan kesalahan
<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>