HMAC politikası

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin.
bilgi

Karma Tabanlı Mesaj Kimlik Doğrulama Kodu (HMAC) hesaplayıp doğrular. Bazen Anahtarlı Mesaj Kimlik Doğrulama Kodu veya Anahtarlı karma olarak bilinen HMAC, bir "iletiye" gizli anahtarla birlikte uygulanan SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 veya MD-5 gibi şifreleme karması işlevi kullanarak söz konusu mesajda bir imza veya ileti kimlik doğrulama kodu oluşturur. Buradaki "mesaj" terimi, herhangi bir bayt akışını ifade eder. Bir mesajın göndereni, alıcıya HMAC de gönderebilir. Alıcı da mesajın kimliğini doğrulamak için HMAC'yi kullanabilir.

HMAC hakkında daha fazla bilgi edinmek için HMAC: Mesaj Kimlik Doğrulaması için Anahtarlı Karma Oluşturma (rfc2104) bölümüne bakın.

Sana Özel

HMAC oluştur

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

HMAC'yi doğrulayın

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

İmzanın hesaplanması ve bu imzanın doğrulanması tamamen aynı süreci takip eder. HMAC politikası bir HMAC hesaplar ve isteğe bağlı olarak hesaplanan imzayı beklenen bir değere göre doğrulayabilir. İsteğe bağlı VerificationValue öğesi (varsa), hesaplanan değeri bilinen veya verilen bir değere göre kontrol etmesi için politikayı yönlendirir.


HMAC için öğe referansı

Politika referansı, HMAC politikasının öğelerini ve özelliklerini açıklar.

Üst düzey öğe için geçerli olan özellikler

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

Aşağıdaki özellikler, tüm politika üst öğelerinde ortaktır.

Özellik Açıklama Varsayılan Bulunma
ad Politikanın dahili adı. Adda kullanabileceğiniz karakterler şunlarla sınırlıdır: A-Z0-9._\-$ %. Bununla birlikte Apigee kullanıcı arayüzü, alfanümerik olmayan karakterlerin otomatik olarak kaldırılması gibi ek kısıtlamalar uygular.

İsteğe bağlı olarak, politikayı Apigee kullanıcı arayüzü proxy düzenleyicisinde farklı bir doğal dil adıyla etiketlemek için <displayname></displayname> öğesini kullanın.

Yok Gerekli
continueOnError Bir politika başarısız olduğunda hata döndürülmesi için false olarak ayarlayın. Bu, çoğu politika için beklenen davranıştır.

Bir politika başarısız olduktan sonra bile akış yürütülmesinin devam etmesi için true değerine ayarlayın.

false İsteğe bağlı
etkin Politikayı uygulamak için true değerine ayarlayın.

Politikayı "devre dışı bırakmak" için false olarak ayarlayın. Politika bir akışa bağlı kalsa bile uygulanmaz.

true İsteğe bağlı
async Bu özellik kullanımdan kaldırıldı. false Kullanımdan kaldırıldı

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

HMAC'yi hesaplamak için karma algoritmasını belirtir.

Varsayılan Yok
Bulunma Gerekli
Tür Dize
Geçerli değerler SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 ve MD-5

Politika yapılandırması, büyük/küçük harf ayrımı olmadan ve harfler ile sayılar arasında kısa çizgi bulunan veya içermeyen algoritma adlarını kabul eder . Örneğin, SHA256 ve SHA-256 ile sha256 eşdeğerdir.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Apigee kullanıcı arayüzü proxy düzenleyicisinde politikayı farklı bir doğal dil adıyla etiketlemek için name özelliğine ek olarak kullanın.

Varsayılan Bu öğeyi çıkarırsanız politikanın ad özelliğinin değeri kullanılır.
Bulunma İsteğe bağlı
Tür Dize

<Message>

<Message>message_template_here</Message>
or
<Message ref='variable_here'/>

İmzalanacak mesaj yükünü belirtir. Bu öğenin girişi; zaman damgaları, nonce'lar, üstbilgi listeleri veya diğer bilgiler gibi ek öğelerin çalışma zamanında eklenmesine olanak tanımak için mesaj şablonlarını (değişken değiştirme) destekler. Örneğin:

<Message>Fixed Part
    {a_variable}
    {timeFormatUTCMs(timeFormatString1,system.timestamp)}
    {nonce}
</Message>

Mesaj şablonu, yeni satırlar ve statik işlevler dahil olmak üzere sabit ve değişken parçalar içerebilir. Boşluk önemli.

Varsayılan Yok
Bulunma Gerekli
Tür Dize
Geçerli değerler Metin değeri için herhangi bir dize geçerlidir. Bir ref özelliği sağlarsanız bu özellik, metin değerine göre öncelikli olur. Politika, metin değerini veya referans verilen değişkeni bir mesaj şablonu olarak değerlendirir.

<Çıkış>

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

Politikanın, hesaplanan HMAC değeriyle ayarlanması gereken değişkenin adını belirtir. Ayrıca, çıkış için kullanılacak kodlamayı da belirtir.

Varsayılan

Varsayılan çıkış değişkeni hmac.POLICYNAME.output.

encoding özelliği için varsayılan değer base64 değeridir.

Bulunma İsteğe bağlı. Bu öğe yoksa politika, hmac.POLICYNAME.output akış değişkenini base64 olarak kodlanmış bir değerle ayarlar.
Tür Dize
Geçerli değerler

Kodlama için hex, base16, base64, base64url.

Değerler büyük/küçük harfe duyarlı değildir; hex ve base16 eş anlamlıdır.

Output öğesinin metin değeri, geçerli herhangi bir akış değişkeni adı olabilir.

<SecretKey>

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

HMAC'yi hesaplamak için kullanılan gizli anahtarı belirtir. Anahtar, başvurulan değişkenden elde edilir ve spesifik kodlamaya göre kodu çözülür.

Varsayılan

Başvurulan değişken için varsayılan bir değer yoktur; ref özelliği zorunludur.

encoding özelliği yoksa politika varsayılan olarak anahtar baytları elde etmek için gizli anahtar dizesinin kodunu UTF-8 ile çözer.

Bulunma Gerekli
Tür Dize
Geçerli değerler

encoding için geçerli değerler hex, base16, base64, utf8 şeklindedir. Varsayılan değer UTF8'dir. Değerler büyük/küçük harfe duyarlı değildir ve kısa çizgiler önemsizdir. Base16, base-16 ve bAse16 ile aynıdır. Base16 ve Hex kelimeleri eş anlamlıdır.

Kodlama özelliği kullanmak, UTF-8 yazdırılabilir karakter aralığının dışındaki baytları içeren bir anahtar belirtmenize olanak tanır. Örneğin, politika yapılandırmasının aşağıdakileri içerdiğini varsayalım:

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

Ayrıca, 536563726574313233 dizesinin private.encodedsecretkey içinde olduğunu varsayalım.

Bu durumda, anahtar baytlarının kodu şu şekilde çözülür: [53 65 63 72 65 74 31 32 33] (her baytlık onaltılık olarak gösterilir). Başka bir örnek olarak, encoding='base64' ve private.encodedsecretkey içinde U2VjcmV0MTIz dizesi varsa anahtar için aynı bayt grubu elde edilir. Kodlama özelliği olmadığında veya kodlama özelliği UTF8 olduğunda, Secret123 dize değeri aynı bayt grubuyla sonuçlanır.

<VerificationValue>

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

(İsteğe bağlı) Doğrulama değerini ve doğrulama değerini kodlamak için kullanılan kodlama algoritmasını belirtir. Politika, değerin kodunu çözmek için bu algoritmayı kullanır.

Varsayılan Varsayılan doğrulama değeri yoktur. Öğe mevcutsa ancak encoding özelliği yoksa politika, varsayılan olarak base64 kodlamasını kullanır.
Bulunma İsteğe bağlı
Tür Dize
Geçerli değerler

Kodlama özelliği için geçerli değerler şunlardır: hex, base16, base64, base64url. Değerler büyük/küçük harfe duyarlı değildir; hex ve base16 eş anlamlıdır.

VerificationValue öğesinin kodlamasının, Output öğesi için kullanılan kodlamayla aynı olması gerekmez.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Politikada belirtilen referans verilen herhangi bir değişken çözümlenemez durumda olduğunda politikanın hata vermesini istiyorsanız false değerine ayarlayın. Çözümlenemeyen değişkenleri boş dize (null) olarak işlemek için true değerine ayarlayın.

ignoreUnresolvedVariables boole'si, yalnızca mesaj şablonu tarafından başvurulan değişkenleri etkiler. SecretKey ve VerificationValue bir değişkene başvurabilir ancak ikisinin de çözümlenebilir olması gerekir. Bu nedenle, ignore ayarı bunlar için geçerli değildir.

Varsayılan Yanlış
Bulunma İsteğe bağlı
Tür Boole
Geçerli değerler doğru veya yanlış

Akış değişkenleri

Politika, yürütme sırasında bu değişkenleri ayarlayabilir.

Değişken Açıklama Örnek
hmac.policy_name.message Politika, Message öğesinde belirtilen mesaj şablonunun değerlendirilmesinin sonucu olarak bu değişkeni etkili mesaj ile ayarlar. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Output öğesi bir değişken adı belirtmediğinde HMAC hesaplamasının sonucunu alır. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding Çıkış kodlamasının adını alır. hmac.HMAC-Policy.outputencoding = base64

Hata referansı

Bu bölümde, bu politika bir hata tetiklediğinde gönderilen hata kodları ve hata mesajları ile Apigee tarafından ayarlanan hata değişkenleri açıklanmaktadır. Bu bilgiyi, hataları ele almak için hata kuralları geliştirip geliştirmediğinizi bilmeniz önemlidir. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler ve Hataları işleme bölümlerine bakın.

Çalışma zamanı hataları

Politika yürütüldüğünde bu hatalar ortaya çıkabilir.

Hata kodu HTTP durumu Gerçekleşme zamanı:
steps.hmac.UnresolvedVariable 401

Bu hata, HMAC politikasında belirtilen bir değişken aşağıdakilerden biriyse ortaya çıkar:

  • Kapsam dışında (politikanın yürütüldüğü belirli akışta kullanılamaz)

    veya

  • Çözümlenemiyor (tanımlanmadı)
steps.hmac.HmacVerificationFailed 401 HMAC doğrulaması başarısız oldu. Sağlanan doğrulama değeri, hesaplanan değerle eşleşmiyor.
steps.hmac.HmacCalculationFailed 401 Politika HMAC hesaplanamadı.
steps.hmac.EmptySecretKey 401 Gizli anahtar değişkeninin değeri boş.
steps.hmac.EmptyVerificationValue 401 Doğrulama değerini tutan değişken boş.

Dağıtım hataları

Bu hatalar, bu politikayı içeren bir proxy dağıttığınızda ortaya çıkabilir.

Hata adı HTTP durumu Gerçekleşme zamanı:
steps.hmac.MissingConfigurationElement 401 Bu hata, gerekli bir öğe veya özellik eksik olduğunda ortaya çıkar.
steps.hmac.InvalidValueForElement 401 Bu hata, Algoritma öğesinde belirtilen değer şu değerlerden biri değilse ortaya çıkar: SHA-1, SHA-224, SHA-256, SHA-512 veya MD-5.
steps.hmac.InvalidSecretInConfig 401 Bu hata, SecretKey için açıkça sağlanan bir metin değeri varsa ortaya çıkar.
steps.hmac.InvalidVariableName 401 Bu hata, SecretKey değişkeni private önekini (private.) içermiyorsa ortaya çıkar.

Hata değişkenleri

Bu değişkenler, bir çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Politika hataları hakkında bilmeniz gerekenler bölümüne bakın.

Değişkenler Konum Örnek
fault.name="fault_name" fault_name, yukarıdaki Çalışma zamanı hataları tablosunda listelenen hatanın adıdır. Hata adı, hata kodunun son kısmıdır. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed Politika, bir hata durumunda bu değişkeni ayarlar. hmac.HMAC-Policy.failed = true

Örnek hata yanıtı

Hata işleme için en iyi uygulama, hata yanıtının errorcode bölümünü yakalamaktır. Değişebileceği için faultstring içindeki metne güvenmeyin.

Hata kuralı örneğ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>