1. 소개

Dataspace 에서 제공하는 파라미터 수집 기능 사용 시 HMAC 서명 사용에 대한 가이드 입니다.

파라미터에 대한 일반적인 설명은 파라미터 사용 가이드를 참고해주시기 바랍니다.

1.1 제공 기능

파라미터를 포함한 응답 링크의 위변조를 방지하기 위해 HMAC 을 제공하고 있습니다.

2. 개발 가이드

2.1 응답 링크 형태

응답 링크의 기본 URI 는 아래와 같습니다.
- https://{설정한 응답 URL 도메인}.fdback.me/r/{serial 값}
- {설정한 응답 URL 도메인} 은 “설정" 메뉴에서 데이터스페이스 별로 하나씩 설정이 가능합니다.
  - 기본값은 ds 입니다. (ds.fdback.me)
- serial 값 은 수집그룹 마다 생성되는 값입니다. 수집그룹 serial 값 조회 API 를 통해 확인 가능합니다.
Query Parameter 로 파라미터 값을 같이 제공할 수 있습니다.
- https://{설정한 응답 URL 도메인}.fdback.me/r/{serial}?uid={uid}&store={store}

파라미터 value 에 들어가는 값은 URL Encode 된 값이여야만 합니다.

잘못된 링크

https://test.fdback.me/r/aLBNYVAk1Ku?store=강남점&uid=TEST_UID&hmac=jx4sAKGP

올바른 링크

https://test.fdback.me/r/aLBNYVAk1Ku?store=%EA%B0%95%EB%82%A8%EC%A0%90&uid=TEST_UID&hmac=Fm0zzi5O

2.2 링크 위변조 방지용 HMAC

링크를 받은 응답자가 파라미터 등의 구성 요소를 위변조하는 것을 막기 위해 HMAC 값을 추가할 수 있습니다.
- HMAC 설정을 원하지 않는 경우, 수집그룹 상세 페이지에서 설정이 가능합니다.
- Query Parameter 로 hmac 값을 같이 제공하면 됩니다. Query Parameter 이름은 “hmac” 입니다.
- https://{설정한 응답 URL 도메인}.fdback.me/r/{serial}?uid={uid}&store={store}&hmac={hmac}
HMAC_KEY는 데이터스페이스 ‘API’ 메뉴에서 확인이 가능합니다.

HMAC 생성규약은 아래와 같습니다.
- “HMAC 적용할 문자열” = “{serial}?{key 값 기준 사전순으로 나열된 파라미터 key-value 쌍, key값은 알파벳 소문자로 변환}“
- SUBSTRING(Base64Url(HmacSHA256(HMAC_KEY, “HMAC 적용할 문자열”), 0, 8))
- 미리 주어진 HMAC_KEY와 함께 HmacSHA256 방법으로 digest한 결과를 base64url encoding 후 앞 8글자만 따서 이를 {hmac} 형태로 생성합니다.
HMAC 생성규약에 따른 예제는 아래와 같습니다.
- 전제조건
  - 설정한 응답 URL 도메인 = “test” (https://test.fdback.me)
  - HMAC_SECRET = “SECRET_FROM_DATASPACE”
  - serial = “aLBNYVAk1Ku”
  - UID = “TEST_UID”
  - store = “gangnam-store”
- 생성과정/결과
  - hmac 적용할 문자열 = “aLBNYVAk1Ku?store=gangnam-store&uid=TEST_UID”
    파라미터 key 값 기준으로 사전순 정렬 수행하면 store 가 uid 보다 먼저 와야 하며, key 값인 UID 를 알파벳 소문자로 변환합니다.
  - SUBSTRING(Base64Url(HmacSHA256(“SECRET_FROM_DATASPACE”, “aLBNYVAk1Ku?store=gangnam-store&uid=TEST_UID”), 0, 8)
    = “XUVJFZA_”
    Base64 가 아닌 Base64Url 을 사용하므로, “XUVJFZA/” 가 아닙니다.
  - 응답 링크는 아래와 같습니다.
    https://test.fdback.me/r/aLBNYVAk1Ku?UID=TEST_UID&store=gangnam_store&hmac=XUVJFZA_
    파라미터 key 값은 대소문자 구분없이 사용 가능합니다.
  - 응답 URL은 그대로 응답자에게 전달 되어야 하며, 임의 변경시 응답자에게 인가 실패가 표시됩니다.
구체적인 구현 코드 예제는 3. Sample Code 를 참조해주세요.

3. Sample Code

아래 샘플 코드 링크를 참조 바랍니다.