Kebijakan HMAC

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Dokumentasi Apigee Edge.

ikon kebijakan

Kebijakan ini menghitung dan secara opsional memverifikasi Kode Autentikasi Pesan Berbasis Hash (HMAC). Terkadang dikenal sebagai {i>Keyed Message Authentication Code<i} atau {i>Keyed hash<i}, HMAC menggunakan fungsi hash kriptografis seperti SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 atau MD-5, diterapkan ke "pesan", bersama dengan kunci rahasia, untuk menghasilkan tanda tangan atau pesan kode otentikasi pada pesan tersebut. Istilah "pesan" di sini mengacu pada aliran {i>byte.<i} Pada penggunaan umum HMAC, pengirim pesan mengirim pesan dan HMAC-nya ke penerima, dan penerima dapat menggunakan HMAC bersama dengan kunci rahasia bersama untuk melakukan otentikasi pesan.

Kebijakan ini merupakan Kebijakan standar dan dapat di-deploy ke jenis lingkungan apa pun. Tidak semua perlu diketahui pengguna tentang jenis kebijakan dan lingkungan. Sebagai informasi tentang jenis kebijakan dan ketersediaan untuk setiap jenis lingkungan, lihat Jenis kebijakan.

Untuk mempelajari HMAC lebih lanjut, lihat HMAC: Keyed-Hashing untuk Message Authentication (rfc2104).

Sampel

Buat 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>

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 tertentu, seperti menghapus karakter yang bukan alfanumerik secara otomatis.

Secara opsional, gunakan elemen <DisplayName> untuk Beri label kebijakan di editor proxy UI Apigee dengan bahasa alami yang berbeda nama.

 T/A Wajib
continueOnError Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Diharapkan untuk sebagian besar kebijakan.

Setel ke true agar eksekusi alur dapat dilanjutkan bahkan setelah kebijakan gagal. Lihat juga:

 salah Opsional
diaktifkan Setel ke true untuk menerapkan kebijakan.

Setel ke false untuk "matikan" kebijakan tersebut. Kebijakan ini tidak akan diterapkan bahkan jika data itu tetap terlampir pada aliran.

 benar Opsional
asinkron Atribut ini tidak digunakan lagi. salah Tidak digunakan lagi

&lt;Algorithm&gt;

<Algorithm>algorithm-name</Algorithm>

Menentukan algoritma hash yang akan digunakan saat 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, SHA256 dan SHA-256 dan sha256 setara.

&lt;DisplayName&gt;

<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

&lt;Message&gt;

<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, seperti baris baru dan karakter spasi, bersifat 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.

&lt;Output&gt;

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

Menentukan nama variabel yang harus ditetapkan oleh kebijakan dengan nilai HMAC yang dikomputasi. Juga menentukan encoding yang akan digunakan untuk output.

Default

Variabel output default adalah hmac.POLICYNAME.output.

Nilai default untuk atribut encoding adalah base64.
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, hex, base16, base64, base64url.

Nilainya tidak peka huruf besar/kecil; hex dan base16 adalah sinonim.

Nilai teks elemen Output dapat berupa nama variabel flow yang valid.

&lt;SecretKey&gt;

<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 ref wajib diisi.

Jika tidak ada atribut encoding, kebijakan ini akan secara default mendekode string kunci rahasia dengan UTF-8 untuk mendapatkan byte kunci.
Kehadiran Wajib
Jenis String
Nilai yang valid

Untuk encoding, nilai yang valid adalah hex, base16, base64, utf8. Defaultnya adalah UTF8. Nilai tidak peka huruf besar/kecil, dan tanda hubung tidak signifikan. Base16 sama dengan base-16 dan bAse16. Base16 dan Hex adalah sinonim.

Dengan menggunakan atribut encoding memungkinkan Anda untuk menentukan kunci yang mencakup byte di luar rentang karakter UTF-8 yang dapat dicetak. Misalnya, konfigurasi kebijakan menyertakan hal berikut: 

 <SecretKey encoding='hex' ref='private.encodedsecretkey'/>

Dan anggaplah private.encodedsecretkey menyimpan string 536563726574313233.

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 menggunakan encoding='base64', dan jika private.encodedsecretkey menyimpan string U2VjcmV0MTIz, itu akan menghasilkan set byte yang sama untuk kunci. Tanpa atribut encoding, atau dengan atribut encoding UTF8, nilai string Secret123 akan menghasilkan set byte yang sama. Hal ini menunjukkan tiga cara berbeda untuk merepresentasikan tombol yang sama.

&lt;VerificationValue&gt;

<VerificationValue encoding='encoding_name' ref='variable_name'/>
or
<VerificationValue encoding='encoding_name'>string_value</VerificationValue>

(Opsional) Menentukan nilai verifikasi, serta encoding yang yang digunakan untuk mengenkode nilai verifikasi. Kebijakan tersebut akan menggunakan encoding 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: hex, base16, base64, base64url. Nilai-nilai tidak peka huruf besar/kecil; hex dan base16 adalah sinonim.

Encoding VerificationValue tidak harus sama dengan encoding digunakan untuk elemen Output.

&lt;IgnoreUnresolvedVariables&gt;

<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

Masalah Umum

Pada satu tingkat, kebijakan HMAC tampaknya mudah: memberikan kunci dan pesan, dan HMAC yang telah dikomputasi. Anda akan merasa frustrasi saat menggunakan kebijakan ini jika Anda mendapatkan hasil Nilai HMAC untuk pesan dan kombinasi kunci 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 dalam pesan, dan perbedaan dalam encoding dan decoding. Yang kedua berlaku untuk elemen SecretKey dan juga elemen Output.

Perbedaan Spasi Kosong

Perbedaan yang mungkin tampak tidak penting bagi manusia, dapat memengaruhi nilai HMAC output. Misalnya, misalkan kunci rahasia yang bisa direpresentasikan sebagai "Secret123". Dengan decoding UTF-8, byte kunci akan menjadi: [53 65 63 72 65 74 31 32 33]. Menggunakan kunci itu untuk menghitung HMAC-SHA256 pada pesan abc menghasilkan a7938720fe5749d31076e6961360364c0cd271443f1b580779932c244293bc94. Menambahkan satu spasi ke pesan sehingga menjadi abc<SPACE>, dengan <SPACE> menyiratkan ASCII 32, menghasilkan HMAC-SHA256 dari 274669b2a85d2532da48e2ce3d8e52ee17346d1bcd1a606d87db1934b5ab294b.

Demikian pula, jika pesannya adalah abc<NEWLINE>, dengan <NEWLINE> menyiratkan ASCII 10, HMACnya adalah 0780370844ca07f896066837e8230d3b6a775f678a4ae03e6b5e864c674831f5. Perubahan kecil pada pesan akan menghasilkan nilai HMAC yang sangat berbeda. Hal ini sesuai dengan desain. Ini adalah perilaku HMAC yang diinginkan 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 {i>payload<i} pesan dengan cara apa pun, dengan menambahkan spasi kosong atau memformat ulang teks, HMAC yang telah dihitung akan berubah.

Hati-hati 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 <Message> akan menyertakan baris baru dan ruang di sekeliling isi pesan. Ini adalah mungkin tidak seperti 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 materi kunci yang sama akan menghasilkan kunci yang berbeda. Misalkan kunci rahasia yang dapat direpresentasikan sebagai "U2VjcmV0S2V5MTIz". Dengan decoding UTF-8, byte kunci sebagaimana yang direpresentasikan dalam base16 adalah: [55 32 56 6a 63 6d 56 30 53 32 56 35 4d 54 49 7a]. Dengan decoding base64, byte kunci akan menjadi [53 65 63 72 65 74 4b 65 79 31 32 33]. Mendekode materi sumber secara berbeda menghasilkan kunci yang berbeda, dan itu akan menghasilkan nilai HMAC yang berbeda.

Kesimpulan: Penting untuk memastikan bahwa materi utama yang digunakan untuk menghitung HMAC asli dan kunci yang digunakan untuk memverifikasi HMAC sama persis. Ini mungkin berarti memastikan bahwa pengkodean 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 diekspresikan dalam base16 atau encoding hex karena 27f17e11c8ece93844c5eb5e55161d993368628a214f9a51c25d0185e8ea06e2 adalah sama seperti HMAC-SHA256 yang diekspresikan dalam bentuk berenkode base64 sebagai J/F+Ecjs6ThExeteVRYdmTNoYoohT5pRwl0BhejqBuI=. Keduanya terlihat berbeda, tetapi kedua string ini mewakili nilai yang sama. Pastikan bahwa hal yang sama digunakan untuk mengenkode HMAC yang awalnya dihitung, dan HMAC yang memverifikasi. Dalam kebijakan HMAC, Anda dapat menggunakan atribut encoding di elemen Output untuk menentukan encoding output yang diinginkan, dan atribut yang sama pada VerificationValueelemen 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:

  • Di luar cakupan (tidak tersedia di alur spesifik tempat kebijakan sedang dijalankan)

    atau

  • Tidak dapat diselesaikan (tidak ditentukan)
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>