HMAC 정책

<ph type="x-smartling-placeholder"></ph> 현재 Apigee Edge 문서를 보고 있습니다.
Apigee X 문서.
정보

해시 기반 메시지 인증 코드(HMAC)를 계산하고 확인합니다. 간혹 키 메시지 인증 코드 또는 키 해시라고도 하는 HMAC는 보안 비밀 키와 함께 사용하여 '메시지'에 적용된 SHA-1, SHA-224, SHA-256, SHA-384, SHA-512 또는 MD-5와 같은 암호화 해시 함수를 사용하여 해당 메시지에 서명 또는 메시지 인증 코드를 생성합니다. 여기서 '메시지'라는 용어는 모든 바이트 스트림을 의미합니다. 메시지 발신자도 수신자에게 HMAC를 보낼 수 있으며 수신자는 HMAC를 사용하여 메시지를 인증할 수 있습니다.

HMAC에 대한 자세한 내용은 HMAC: Keyed-Hashing for Message Authentication (rfc2104)을 참조하세요.

샘플

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>

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>

서명 계산과 서명 확인은 완전히 같은 프로세스를 따릅니다. HMAC 정책은 HMAC를 계산하고, 계산된 서명을 예상 값에 대해 선택적으로 확인할 수 있습니다. 선택사항인 VerificationValue 요소(있는 경우)는 계산된 값을 알려진 값 또는 지정된 값과 비교하여 확인하도록 정책에 지시합니다.


HMAC의 요소 참조

정책 참조는 HMAC 정책의 요소 및 속성을 설명합니다.

최상위 요소에 적용되는 속성

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

다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.

속성 설명 기본 Presence
이름 정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$ %로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다.

선택적으로 <displayname></displayname> 요소를 사용하여 Apigee UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

해당 사항 없음 필수
continueOnError 정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다.

거짓 선택사항
사용 설정됨 정책을 시행하려면 true로 설정합니다.

false로 설정하여 정책을 '사용 중지'합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

true 선택사항
비동기 이 속성은 지원이 중단되었습니다. 거짓 지원 중단됨

<Algorithm>

<Algorithm>algorithm-name</Algorithm>

HMAC를 계산하기 위한 해시 알고리즘을 지정합니다.

기본값 해당 사항 없음
Presence 필수
유형 문자열
유효한 값 SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, MD-5

정책 구성은 대소문자를 구분하지 않고 문자와 숫자 사이에 대시를 포함하거나 포함하지 않는 알고리즘 이름을 허용합니다. 예를 들어 SHA256, SHA-256, sha256은 동일합니다.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

이름 속성 외에도 이 요소를 사용하여 Apigee UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

기본값 이 요소를 생략하면 정책 이름 속성 값이 사용됩니다.
Presence 선택사항
유형 문자열

<Message>

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

서명할 메시지 페이로드를 지정합니다. 이 요소의 입력은 메시지 템플릿(변수 대체)을 지원하므로 타임스탬프, nonce, 헤더 목록 또는 기타 정보와 같은 추가 항목을 런타임에 포함할 수 있습니다. 예를 들면 다음과 같습니다.

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

메시지 템플릿은 줄바꿈 및 정적 함수를 포함하여 고정 및 가변 부분을 포함할 수 있습니다. 공백은 중요합니다.

기본값 해당 사항 없음
Presence 필수
유형 문자열
유효한 값 텍스트 값에 모든 문자열은 유효합니다. ref 속성을 제공하면 텍스트 값보다 우선합니다. 정책은 텍스트 값 또는 참조된 변수를 메시지 템플릿으로 평가합니다.

<Output>

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

계산된 HMAC 값으로 정책을 설정해야 하는 변수의 이름을 지정합니다. 또한 출력에 사용할 인코딩을 지정합니다.

기본값

기본 출력 변수는 hmac.POLICYNAME.output입니다.

encoding 속성의 기본값은 base64입니다.

Presence 선택사항. 이 요소가 없으면 정책은 base64로 인코딩된 값을 사용하여 흐름 변수 hmac.POLICYNAME.output을 설정합니다.
유형 문자열
유효한 값

인코딩의 경우 hex, base16, base64, base64url입니다.

값은 대소문자를 구분하지 않고, hexbase16는 동의어입니다.

Output 요소의 텍스트 값은 모든 유효한 흐름 변수 이름이 될 수 있습니다.

<SecretKey>

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

HMAC를 계산하는 데 사용되는 보안 비밀번호 키를 지정합니다. 키는 구체적인 인코딩에서 디코딩된 참조된 변수에서 가져옵니다.

기본값

참조된 변수에는 기본값이 없으며 ref 속성이 필요합니다.

encoding 속성이 없으면 기본적으로 정책은 보안 키 문자열을 UTF-8로 디코딩하여 키 바이트를 가져옵니다.

Presence 필수
유형 문자열
유효한 값

encoding의 유효한 값은 hex, base16, base64, utf8입니다. 기본값은 UTF8입니다. 값은 대소문자를 구분하지 않으며 대시는 중요하지 않습니다. Base16base-16bAse16과 동일합니다. Base16Hex는 동의어입니다.

인코딩 속성을 사용하면 UTF-8 인쇄 가능 문자 범위를 벗어난 바이트가 포함된 키를 지정할 수 있습니다. 예를 들어 정책 구성에 다음이 포함되어 있다고 가정해 보겠습니다.

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

그리고 private.encodedsecretkey536563726574313233 문자열이 있다고 가정해 보겠습니다.

이 경우 키 바이트는 [53 65 63 72 65 74 31 32 33]으로 디코딩됩니다(각 바이트는 16진수로 표시됨). 또 다른 예시로 encoding='base64'이고 private.encodedsecretkey에 문자열 U2VjcmV0MTIz가 있으면 키의 동일한 바이트 집합이 생성됩니다. 인코딩 속성이 없거나 UTF8 인코딩 속성을 사용하면 문자열 값 Secret123이 동일한 바이트 집합을 생성합니다.

<VerificationValue>

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

(선택사항) 확인 값과 확인 값을 인코딩하는 데 사용된 인코딩 알고리즘을 지정합니다. 정책에서 이 알고리즘을 사용하여 값을 디코딩합니다.

기본값 기본 확인 값이 없습니다. 요소가 있지만 encoding 속성이 없으면 정책은 base64의 기본 인코딩을 사용합니다.
Presence 선택사항
유형 문자열
유효한 값

인코딩 속성의 유효한 값은 hex, base16, base64, base64url입니다. 값은 대소문자를 구분하지 않고 hexbase16은 동의어입니다.

VerificationValue 인코딩은 Output 요소에 사용된 인코딩과 동일할 필요가 없습니다.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

정책에 지정된 참조 변수를 해결할 수 없는 경우 정책에서 오류가 발생하게 하려면 false로 설정합니다. 해결할 수 없는 변수를 빈 문자열(null)로 취급하려면 true로 설정합니다.

IgnoreUnresolvedVariables 부울은 메시지 템플릿이 참조하는 변수에만 영향을 줍니다. SecretKeyVerificationValue는 변수를 참조할 수 있지만 둘 다 확인할 수 있어야 하므로 ignore 설정이 적용되지 않습니다.

기본값 거짓
Presence 선택사항
유형 부울
유효한 값 true 또는 false

흐름 변수

정책은 실행 중에 이러한 변수를 설정할 수 있습니다.

변수 설명
hmac.policy_name.message 정책은 Message 요소에 지정된 메시지 템플릿을 평가한 결과인 유효 메시지를 사용하여 이 변수를 설정합니다. hmac.HMAC-Policy.message = "Hello, World"
hmac.policy_name.output Output 요소가 변수 이름을 지정하지 않으면 HMAC 계산 결과를 가져옵니다. hmac.HMAC-Policy.output = /yyRjydfP+fBHTwXFgc5AZhLAg2kwCri+e35girrGw4=
hmac.policy_name.outputencoding 출력 인코딩의 이름을 가져옵니다. hmac.HMAC-Policy.outputencoding = base64

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드 HTTP 상태 발생 상황
steps.hmac.UnresolvedVariable 401

이 오류는 HMAC 정책에 지정된 변수가 다음 중 하나에 해당하는 경우 발생합니다.

  • 범위를 벗어난 경우(정책이 실행 중인 특정 흐름에서 사용할 수 없음)

    또는

  • 확인할 수 없는 경우(정의되지 않음)
steps.hmac.HmacVerificationFailed 401 HMAC 인증에 실패했습니다. 제공된 확인 값이 계산된 값과 일치하지 않습니다.
steps.hmac.HmacCalculationFailed 401 정책에서 HMAC를 계산할 수 없습니다.
steps.hmac.EmptySecretKey 401 보안 비밀 키 변수의 값이 비어 있습니다.
steps.hmac.EmptyVerificationValue 401 확인 값을 포함하는 변수가 비어 있습니다.

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 HTTP 상태 발생 상황
steps.hmac.MissingConfigurationElement 401 이 오류는 필수 요소 또는 속성이 누락된 경우에 발생합니다.
steps.hmac.InvalidValueForElement 401 이 오류는 알고리즘 요소에 지정된 값이 SHA-1, SHA-224, SHA-256, SHA-512, MD-5 값 중 하나가 아닌 경우 발생합니다.
steps.hmac.InvalidSecretInConfig 401 이 오류는 SecretKey에 명시적으로 제공된 텍스트 값이 있을 때 발생합니다.
steps.hmac.InvalidVariableName 401 이 오류는 SecretKey 변수에 private 프리픽스(private.)가 포함되지 않은 경우 발생합니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수 위치
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "UnresolvedVariable"
hmac.policy_name.failed 이 정책은 실패한 경우 이 변수를 설정합니다. hmac.HMAC-Policy.failed = true

오류 응답 예시

오류 처리에서 오류 응답의 errorcode 부분을 트래핑하는 것이 가장 좋습니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

오류 규칙 예시

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