<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는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다.
선택적으로 |
해당 사항 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 false 로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.
정책이 실패해도 흐름 실행이 계속되도록 하려면 |
거짓 | 선택사항 |
사용 설정됨 | 정책을 시행하려면 true 로 설정합니다.
|
true | 선택사항 |
비동기 | 이 속성은 지원이 중단되었습니다. | 거짓 | 지원 중단됨 |
<Algorithm>
<Algorithm>algorithm-name</Algorithm>
HMAC를 계산하기 위한 해시 알고리즘을 지정합니다.
기본값 | 해당 사항 없음 |
Presence | 필수 |
유형 | 문자열 |
유효한 값 | SHA-1 , SHA-224 , SHA-256 , SHA-384 ,
SHA-512 , MD-5
정책 구성은 대소문자를 구분하지 않고 문자와 숫자 사이에 대시를 포함하거나 포함하지 않는 알고리즘 이름을 허용합니다. 예를 들어 |
<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 값으로 정책을 설정해야 하는 변수의 이름을 지정합니다. 또한 출력에 사용할 인코딩을 지정합니다.
기본값 |
기본 출력 변수는 |
Presence | 선택사항. 이 요소가 없으면 정책은 base64로 인코딩된 값을 사용하여 흐름 변수 hmac.POLICYNAME.output 을 설정합니다. |
유형 | 문자열 |
유효한 값 | 인코딩의 경우 값은 대소문자를 구분하지 않고,
|
<SecretKey>
<SecretKey encoding='encoding_name' ref='private.secretkey'/>
HMAC를 계산하는 데 사용되는 보안 비밀번호 키를 지정합니다. 키는 구체적인 인코딩에서 디코딩된 참조된 변수에서 가져옵니다.
기본값 |
참조된 변수에는 기본값이 없으며
|
Presence | 필수 |
유형 | 문자열 |
유효한 값 |
인코딩 속성을 사용하면 UTF-8 인쇄 가능 문자 범위를 벗어난 바이트가 포함된 키를 지정할 수 있습니다. 예를 들어 정책 구성에 다음이 포함되어 있다고 가정해 보겠습니다. <SecretKey encoding='hex' ref='private.encodedsecretkey'/>
그리고
이 경우 키 바이트는 [53 65 63 72 65 74 31 32 33]으로 디코딩됩니다(각 바이트는 16진수로 표시됨). 또 다른 예시로 |
<VerificationValue>
<VerificationValue encoding='encoding_name' ref='variable_name'/> or <VerificationValue encoding='encoding_name'>string_value</VerificationValue>
(선택사항) 확인 값과 확인 값을 인코딩하는 데 사용된 인코딩 알고리즘을 지정합니다. 정책에서 이 알고리즘을 사용하여 값을 디코딩합니다.
기본값 | 기본 확인 값이 없습니다. 요소가 있지만 encoding 속성이 없으면 정책은 base64 의 기본 인코딩을 사용합니다. |
Presence | 선택사항 |
유형 | 문자열 |
유효한 값 |
인코딩 속성의 유효한 값은
|
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
정책에 지정된 참조 변수를 해결할 수 없는 경우 정책에서 오류가 발생하게 하려면 false
로 설정합니다. 해결할 수 없는 변수를 빈 문자열(null)로 취급하려면 true
로 설정합니다.
IgnoreUnresolvedVariables 부울은 메시지 템플릿이 참조하는 변수에만 영향을 줍니다. SecretKey
및 VerificationValue
는 변수를 참조할 수 있지만 둘 다 확인할 수 있어야 하므로 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>