Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Baca dokumentasi Apigee Edge.
Kebijakan ini menghitung dan memverifikasi Hash-based Message Authentication Code (HMAC) secara opsional. Terkadang dikenal sebagai Keyed Message Authentication Code atau Keyed hash, HMAC menggunakan fungsi hash kriptografis seperti SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, atau MD-5, yang diterapkan pada "pesan", bersama dengan kunci rahasia, untuk menghasilkan tanda tangan atau kode autentikasi pesan pada pesan tersebut. Istilah "message" di sini mengacu pada stream byte. Dalam penggunaan HMAC secara umum, pengirim pesan mengirimkan pesan dan HMAC-nya ke penerima, dan penerima dapat menggunakan HMAC bersama dengan kunci rahasia bersama untuk mengautentikasi pesan.
Kebijakan ini adalah Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua pengguna perlu mengetahui tentang kebijakan dan jenis lingkungan. Untuk mengetahui informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.
Untuk mempelajari HMAC lebih lanjut, lihat HMAC: Keyed-Hashing for Message Authentication (rfc2104).
Sampel
Membuat HMAC
<HMAC name='HMAC-1'> <Algorithm>SHA256</Algorithm> <!-- the default encoding of the SecretKey is UTF-8 --> <SecretKey encoding='base64' ref='private.secretkey'/> <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional --> <!-- The Message element accepts a template, which means the "message" the policy operates on can include fixed and multiple variable parts, including newlines and static functions. Whitespace, such as newlines and space characters, 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> <!-- the default encoding of the SecretKey is UTF-8 --> <SecretKey encoding='base16' ref='private.secretkey'/> <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <!-- optional --> <!-- The Message element accepts a template. This policy verifies an HMAC on the request content. --> <Message>{request.content}</Message> <!-- VerificationValue is optional. Include it to perform an HMAC check. --> <VerificationValue encoding='base16' ref='expected_hmac_value'/> <!-- default encoding of the output is base64 --> <Output encoding='base16'>name_of_variable</Output> </HMAC>
Komputasi tanda tangan dan verifikasi tanda tangan tersebut mengikuti proses
yang sama persis. Kebijakan HMAC menghitung HMAC, dan secara opsional dapat memverifikasi tanda tangan yang dikomputasi terhadap nilai yang diharapkan. Elemen VerificationValue
opsional (jika ada) mengarahkan kebijakan untuk memeriksa nilai yang dihitung terhadap nilai yang diketahui atau diberikan.
Referensi elemen untuk HMAC
Referensi kebijakan menjelaskan elemen dan atribut kebijakan HMAC.
Atribut yang berlaku untuk elemen level atas
<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">
Atribut berikut bersifat umum untuk semua elemen induk kebijakan.
Atribut | Deskripsi | Default | Kehadiran |
---|---|---|---|
name |
Nama internal kebijakan. Karakter yang dapat Anda gunakan dalam nama dibatasi untuk:
A-Z0-9._\-$ % . Namun, UI Apigee menerapkan pembatasan tambahan, misalnya penghapusan otomatis karakter yang bukan alfanumerik.
Atau, gunakan elemen |
T/A | Diperlukan |
continueOnError |
Setel ke false untuk menampilkan error jika kebijakan gagal. Ini adalah perilaku yang wajar untuk sebagian besar kebijakan.
Setel ke |
false | Opsional |
diaktifkan |
Setel ke true untuk menerapkan kebijakan.
Setel ke |
true | Opsional |
async | Atribut ini tidak digunakan lagi. | false | Tidak digunakan lagi |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
Menentukan algoritma hash yang akan digunakan saat menghitung HMAC.
Default | T/A |
Kehadiran | Diperlukan |
Type | 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 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 |
Type | String |
<Message>
<Message>message_template_here</Message> or <Message ref='variable_here'/>
Menentukan payload pesan yang akan ditandatangani. Input elemen ini mendukung template pesan (pergantian variabel) agar item tambahan dapat disertakan saat runtime, seperti stempel waktu, nonce, daftar header, 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, seperti baris baru dan karakter spasi, bersifat signifikan.
Default | T/A |
Kehadiran | Diperlukan |
Type | String |
Nilai yang valid | String apa pun valid untuk nilai teks. Jika Anda memberikan atribut ref , atribut tersebut akan lebih diutamakan daripada nilai teks. Kebijakan ini mengevaluasi nilai teks
atau variabel yang direferensikan sebagai template pesan. |
<Output>
<Output encoding='encoding_name'>variable_name</Output>
Menentukan nama variabel yang harus disetel oleh kebijakan dengan nilai HMAC yang dikomputasi. Juga menentukan encoding yang akan digunakan untuk output.
Default |
Variabel output default-nya adalah Nilai default untuk atribut |
Kehadiran | Opsional. Jika elemen ini tidak ada, kebijakan akan menyetel variabel flow
hmac.POLICYNAME.output , dengan nilai berenkode base64. |
Type | 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 yang direferensikan, yang didekode sesuai dengan encoding tertentu.
Default |
Tidak ada nilai default untuk variabel yang direferensikan;
atribut Jika tidak ada atribut |
Kehadiran | Diperlukan |
Type | String |
Nilai yang valid | Untuk Dengan menggunakan atribut encoding, Anda dapat menentukan kunci yang mencakup byte di luar rentang karakter UTF-8 yang dapat dicetak. Misalnya, anggaplah konfigurasi kebijakan menyertakan hal ini: <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
Dan anggaplah
Dalam hal ini, byte utama akan didekode sebagai: [53 65 63 72 65 74 31 32 33]
(setiap byte yang direpresentasikan dalam heksadesimal). Sebagai contoh lainnya, jika menggunakan |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
(Opsional) Menentukan nilai verifikasi, serta encoding yang digunakan untuk mengenkode nilai verifikasi. Kebijakan tersebut akan menggunakan encoding ini untuk mendekode nilai tersebut.
Default | Tidak ada nilai verifikasi default. Jika elemen tersebut ada, tetapi
atribut encoding tidak ada, kebijakan akan menggunakan encoding default base64 |
Kehadiran | Opsional |
Type | 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 referensi apa pun yang ditentukan
dalam kebijakan tidak dapat diselesaikan. Tetapkan ke true
untuk memperlakukan variabel yang tidak dapat di-resolve sebagai string kosong (null).
Boolean IgnoreUnresolvedVariables hanya memengaruhi variabel yang direferensikan oleh template pesan. Meskipun SecretKey
dan VerificationValue
dapat mereferensikan variabel, keduanya harus dapat diselesaikan, sehingga setelan ignore
tidak berlaku untuk variabel tersebut.
Default | Salah |
Kehadiran | Opsional |
Type | Boolean |
Nilai yang valid | benar atau salah |
Variabel alur
Kebijakan ini dapat menetapkan variabel ini selama eksekusi.
Variabel | Deskripsi | Contoh |
---|---|---|
hmac.policy_name.message |
Kebijakan ini menetapkan variabel ini dengan pesan yang efektif,
yaitu hasil evaluasi template pesan yang ditentukan dalam elemen
Message . |
hmac.HMAC-Policy.message = "Hello, World" |
hmac.policy_name.output |
Mendapatkan hasil
komputasi HMAC, saat elemen Output tidak menentukan nama variabel. |
hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4= |
hmac.policy_name.outputencoding |
Mendapatkan nama encoding output. | hmac.HMAC-Policy.outputencoding = base64 |
Masalah Umum
Di satu tingkat, kebijakan HMAC tampak langsung: menyediakan kunci dan pesan, serta mendapatkan HMAC yang dikomputasi sebagai respons. Anda akan merasa kesal saat menggunakan kebijakan ini jika mendapatkan nilai HMAC yang tidak terduga untuk kombinasi kunci dan pesan yang diketahui. Bagian ini akan menjelaskan beberapa catatan penggunaan untuk mengatasi masalah tersebut.
Ada dua kesalahan umum yang mengakibatkan HMAC tidak cocok selama verifikasi: perbedaan spasi kosong pada pesan, serta perbedaan dalam encoding dan decoding.
Hal yang kedua berlaku untuk elemen SecretKey
serta
elemen Output
.
Perbedaan Spasi Kosong
Perbedaan yang mungkin tampak tidak penting bagi manusia, memengaruhi nilai HMAC output. Misalnya, kunci rahasia yang dapat direpresentasikan sebagai "Secret123". Dengan decoding UTF-8, byte utama
akan menjadi: [53 65 63 72 65 74 31 32 33]
. Menggunakan kunci tersebut untuk menghitung
HMAC-SHA256 pada pesan abc
akan menghasilkan a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94
.
Menambahkan satu spasi ke pesan, sehingga abc<SPACE>
, dengan
<SPACE>
menyiratkan ASCII 32, menghasilkan
HMAC-SHA256 dari 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b
.
Demikian pula, jika pesannya adalah abc<NEWLINE>
, dengan
<NEWLINE>
menyiratkan ASCII 10,
HMAC adalah 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5
.
Sedikit perubahan pada pesan akan menghasilkan nilai HMAC yang sangat berbeda. Hal ini sesuai dengan desain.
Ini adalah perilaku HMAC yang
dimaksudkan dan diinginkan.
Kesimpulan: Penting untuk memastikan bahwa isi pesan yang digunakan untuk menghitung HMAC asli dan isi pesan yang digunakan untuk memverifikasi HMAC sama persis. Jika pemverifikasi HMAC mengubah payload pesan dengan cara apa pun, dengan menambahkan spasi kosong atau memformat ulang teks, HMAC yang dihitung akan berubah.
Berhati-hatilah saat menggunakan template pesan dalam konfigurasi kebijakan. Misalnya, fragmen konfigurasi kebijakan ini menunjukkan potensi masalah:
<HMAC name='HMAC-1'> ... <!-- the result of this message template will include surrounding whitespace --> <Message> {request.content} </Message> ... </HMAC>
Hasil evaluasi template pesan dalam elemen <Message>
akan menyertakan baris baru dan spasi yang mengelilingi konten pesan. Ini mungkin bukan yang dimaksudkan. Konfigurasi yang lebih baik akan terlihat seperti ini:
<HMAC name='HMAC-1'> ... <Message>{request.content}</Message> ... </HMAC>
Perbedaan Encoding
Dekode yang berbeda dari material kunci yang sama akan menghasilkan kunci yang berbeda. Misalnya kunci rahasia yang dapat direpresentasikan sebagai "U2VjcmV0S2V5MTIz". Dengan decoding UTF-8, byte kunci
sebagaimana dinyatakan dalam base16 adalah: [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a]
.
Dengan decoding base64, byte utama akan menjadi [53 65 63 72 65 74 4b 65 79 31 32 33]
.
Mendecode bahan sumber akan menghasilkan kunci yang berbeda pula, dan hal tersebut akan menghasilkan nilai HMAC yang berbeda.
Kesimpulan: Penting untuk memastikan bahwa bahan kunci yang digunakan untuk menghitung HMAC asli dan kunci yang digunakan untuk memverifikasi HMAC sama persis. Hal ini mungkin berarti memastikan bahwa encoding kunci yang sama digunakan di kedua ujungnya. Dalam kebijakan HMAC,
Anda dapat menggunakan atribut encoding
di elemen SecretKey
untuk menentukan encoding kunci.
Pertimbangkan juga encoding pada output. HMAC-SHA256 yang dinyatakan dalam encoding base16 atau hex
sebagai 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2
sama
dengan HMAC-SHA256 yang dinyatakan dalam bentuk yang dienkode base64 sebagai J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI=
.
Keduanya terlihat berbeda, tetapi kedua string ini mewakili nilai yang sama. Pastikan encoding
yang sama digunakan untuk mengenkode HMAC yang dihitung secara awal, dan HMAC yang memverifikasi. Dalam kebijakan HMAC,
Anda dapat menggunakan atribut encoding
pada Output
elemen
untuk menentukan encoding output yang diinginkan, dan atribut yang sama pada
VerificationValue
elemen
untuk menentukan cara mendekode pemverifikasi.
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 berisi 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 | Dari mana | Contoh |
---|---|---|
fault.name="fault_name" |
fault_name adalah nama kesalahannya, seperti yang tercantum dalam tabel Error runtime di atas. Nama kesalahan adalah bagian terakhir 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 menjebak bagian errorcode
dari respons
error. 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>