Kebijakan HMAC

Anda sedang melihat dokumentasi Apigee Edge.
Lihat dokumentasi Apigee X.

Menghitung dan memverifikasi Kode Autentikasi Pesan Berbasis Hash (HMAC). Terkadang dikenal sebagai Kode Autentikasi Pesan Berkunci atau hash Berkunci, HMAC menggunakan fungsi hash kriptografi seperti SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, atau MD-5, yang diterapkan ke "pesan", bersama dengan kunci rahasia, untuk menghasilkan tanda tangan atau kode autentikasi pesan pada pesan tersebut. Istilah "pesan" di sini merujuk pada aliran byte apa pun. Pengirim pesan juga dapat mengirim HMAC ke penerima, dan penerima dapat menggunakan HMAC untuk mengautentikasi pesan.

Untuk mempelajari HMAC lebih lanjut, baca artikel HMAC: Keyed-Hashing for Message Authentication (RFC2104).

Sample

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

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 dihitung terhadap nilai yang diharapkan. Elemen VerificationValue opsional (jika ada) akan mengarahkan kebijakan untuk memeriksa nilai yang dihitung terhadap nilai yang diketahui atau yang diberikan.


Referensi elemen untuk HMAC

Referensi kebijakan menjelaskan elemen dan atribut kebijakan HMAC.

Atribut yang berlaku untuk elemen tingkat atas

<HMAC name="HMAC" continueOnError="false" enabled="true" async="false">

Atribut berikut sama 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 menerapkan batasan tambahan, seperti menghapus karakter yang bukan alfanumerik secara otomatis.

Jika ingin, gunakan elemen <displayname></displayname> untuk melabeli kebijakan di editor proxy UI Apigee dengan nama bahasa natural yang berbeda.

T/A Wajib diisi
ContinueOnError Tetapkan ke false untuk menampilkan error saat kebijakan gagal. Hal ini wajar untuk sebagian besar kebijakan.

Tetapkan ke true agar eksekusi flow dapat dilanjutkan bahkan setelah kebijakan gagal.

false Opsional
diaktifkan Tetapkan ke true untuk menerapkan kebijakan.

Tetapkan ke false untuk "menonaktifkan" kebijakan. Kebijakan ini tidak akan diberlakukan meskipun tetap disertakan ke alur.

true Opsional
asinkron Atribut ini tidak digunakan lagi. false Tidak digunakan lagi

<Algoritme>

<Algorithm>algorithm-name</Algorithm>

Menentukan algoritme hash untuk menghitung HMAC.

Default T/A
Kehadiran Wajib diisi
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, dengan atau tanpa tanda hubung di antara huruf dan angka . Misalnya, SHA256 dan SHA-256 serta sha256 setara.

<NamaTampilan>

<DisplayName>Policy Display Name</DisplayName>

Selain atribut nama untuk memberi label kebijakan pada editor proxy UI Apigee dengan nama bahasa alami yang berbeda.

Default Jika Anda menghilangkan elemen ini, nilai atribut nama kebijakan akan digunakan.
Kehadiran Opsional
Jenis String

<Pesan>

<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 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 variabel dan tetap, termasuk baris baru dan fungsi statis. Ruang kosong sangat penting.

Default T/A
Kehadiran Wajib diisi
Jenis String
Nilai yang valid Setiap string valid untuk nilai teks. Jika Anda memberikan atribut ref, atribut tersebut akan diprioritaskan 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 ditetapkan oleh kebijakan dengan nilai HMAC yang dihitung. Juga menentukan encoding yang akan digunakan untuk output.

Default

Variabel output default-nya adalah hmac.POLICYNAME.output.

Nilai default untuk atribut encoding adalah base64.

Kehadiran Opsional. Jika elemen ini tidak ada, kebijakan akan menetapkan variabel flow hmac.POLICYNAME.output, dengan nilai yang dienkode dengan base64.
Jenis String
Nilai yang valid

Untuk encoding, hex, base16, base64, base64url.

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

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

<Kunci Rahasia>

<SecretKey encoding='encoding_name' ref='private.secretkey'/>

Menentukan kunci rahasia yang digunakan untuk menghitung HMAC. Kunci diperoleh dari variabel yang direferensikan, yang didekode sesuai dengan encoding tertentu.

Default

Tidak ada nilai default untuk variabel yang direferensikan; atribut ref diperlukan.

Jika tidak ada atribut encoding, kebijakan secara default mendekode string kunci rahasia dengan UTF-8 untuk mendapatkan byte kunci.

Kehadiran Wajib diisi
Jenis String
Nilai yang valid

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

Penggunaan atribut encoding memungkinkan Anda menentukan kunci yang menyertakan byte di luar rentang karakter yang dapat dicetak UTF-8. Misalnya, konfigurasi kebijakan mencakup ini:

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

Dan misalkan private.encodedsecretkey menyimpan string 536563726574313233.

Dalam hal ini, byte kunci akan didekode sebagai: [53 65 63 72 65 74 31 32 33] (setiap byte yang direpresentasikan dalam heksadesimal). Sebagai contoh lainnya, jika encoding='base64', dan private.encodedsecretkey menyimpan string U2VjcmV0MTIz, string tersebut akan menghasilkan kumpulan byte yang sama untuk kunci. Tanpa atribut encoding, atau dengan atribut encoding UTF8, nilai string Secret123 akan menghasilkan kumpulan byte yang sama.

<VerifikasiNilai>

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

(Opsional) Menentukan nilai verifikasi, serta algoritme encoding yang digunakan untuk mengenkode nilai verifikasi. Kebijakan ini akan menggunakan algoritme ini untuk mendekode nilai.

Default Tidak ada nilai verifikasi default. Jika elemen tersebut ada, tetapi atribut encoding tidak ada, kebijakan akan menggunakan encoding default base64
Kehadiran Opsional
Jenis String
Nilai yang valid

Nilai yang valid untuk atribut encoding adalah: hex, base16, base64, base64url. Nilai ini tidak peka huruf besar/kecil; hex dan base16 adalah sinonimnya.

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

<AbaikanUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Tetapkan ke false jika Anda ingin kebijakan menampilkan error saat variabel yang direferensikan yang ditentukan dalam kebijakan tidak dapat diselesaikan. Tetapkan ke true untuk memperlakukan variabel yang tidak dapat diselesaikan sebagai string kosong (null).

Boolean UnUnresolvedVariables hanya memengaruhi variabel yang direferensikan oleh template pesan. Meskipun SecretKey dan VerificationValue dapat mereferensikan variabel, keduanya harus dapat di-resolve, sehingga setelan ignore tidak berlaku untuk variabel tersebut.

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 ini menetapkan variabel ini dengan pesan yang efektif, sebagai hasil dari 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

Referensi error

Bagian ini menjelaskan kode kesalahan dan pesan error yang dikembalikan, serta variabel kesalahan yang disetel oleh Apigee saat kebijakan ini memicu error. Informasi ini penting untuk diketahui jika Anda mengembangkan aturan fault untuk menangani fault. Untuk mempelajari lebih lanjut, lihat Yang perlu Anda ketahui tentang error kebijakan dan Menangani kesalahan.

Error runtime

Error ini dapat terjadi saat kebijakan dijalankan.

Kode kesalahan Status HTTP Terjadi saat
steps.hmac.UnresolvedVariable 401

Error ini terjadi jika variabel yang ditentukan dalam kebijakan HMAC adalah:

  • Di luar cakupan (tidak tersedia dalam alur tertentu tempat kebijakan 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 menyimpan nilai verifikasi adalah emtpy.

Error 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 Algoritme bukan salah satu 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 diberikan 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 mengetahui informasi selengkapnya, lihat Yang perlu Anda ketahui tentang error kebijakan.

Variabel Lokasi Contoh
fault.name="fault_name" fault_name adalah nama fault, seperti yang tercantum pada tabel Error runtime di atas. Nama fault adalah bagian terakhir dari kode fault. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed Kebijakan menetapkan variabel ini jika terjadi kegagalan. hmac.HMAC-Policy.failed = true

Contoh respons error

Untuk penanganan error, praktik terbaiknya adalah dengan menangkap 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>