Skip to content

REST API 서명인증

Jump to bottom
alphaex-api edited this page Nov 22, 2018 · 2 revisions

REST API 서명인증

현재 API Key 신청 및 수정은 ‘계정-API관리’ 페이지에서 작업이 가능합니다. 그 중 ①Access Key는 API 접속을 위한 Secret Key이며, ②Secret Key는 사용자가 서명할 때 요구되는 Secret Key입니다(신청할 때만 볼 수 있습니다). Huobi Global(Huobi Pro)와 HADAX의 API Key는 같은 Key로 사용 가능합니다.

중요 안내: 상기 두가지 SecretKey는 계정 보안과 밀접한 관계가 있으므로 어떠한 경우에도 타인에게 노출하는 것을 금지합니다.

안전한 요청 구조

보안 문제를 고려하여, 시세 API를 제외한 모든 API 요청은 서명 연산이 반드시 필요합니다. 1개의 보안성을 갖춘 요청은 다음과 같은 부분으로 구성됩니다.

  • 방법 요청 주소, 서버 방문 주소: api-cloud.huobi.co.kr 뒤쪽에 방법 명칭을 기재해 주시기 바랍니다. 예) api-cloud.huobi.co.kr/v1/order/orders
  • API AccessKeyId: 고객님이 신청하신 API Key 중 AccessKey를 말합니다.
  • 서명 방법(SignatureMethod): 서명 계산의 기초로 활용되는 Hash Protocol이며, HmacSHA256이 활용됩니다.
  • 서명 버전(SignatureVersion): 서명 protocol 버전이며, 2가 활용됩니다.
  • 타임 스탬프(Timestamp): 고객님이 요청을 발송한 시간 (UTC Time Zone)이며, 요청 조회 과정에서 본 값을 포함하는 이유는 제3자가 고객님의 요청에 개입하는 것을 방지하기 위함입니다. 예: 2017--05-11T16:22:06. 다시한번 Timestamp는 UTC Time Zone임을 숙지하시기 바랍니다.
  • 필수 선택과 선택가능 Parameter: 각 방법은 모두 API 정의 조정에 사용되는 필수 Parameter와 선택가능 Parameter가 있습니다. 각 방법의 설명에서 상기 Parameter들과 이들의 함축적 의미를 확인할 수 있습니다. 주의할 점은 GET 요청에 대해 각 방법이 자체적으로 보유하고 있는 Parameter는 모두 서명 인증 후 작업이 가능합니다. POST 요청의 경우, 매번 요청하는 방법이 자체적으로 보유한 Parameter는 서명 인증이 필요 없으므로, 즉 POST 요청에서 서명 인증이 필요한 부분은 AccessKeyId, SignatureMethod, SignatureVersion, Timestamp 총 4가지 parameter입니다. 나머지 Parameter는 Body에 놓고 사용하시면 됩니다.
  • 서명: 서명 계산으로 얻은 값은 서명의 유효성과 왜곡되지 않았다는 것을 보증하는데 사용됩니다.

예:


https://api-cloud.huobi.co.kr/v1/order/orders?
AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T15%3A19%3A30
&order-id=1234567890
&Signature=calculated value

서명 연산

API 요청은 Internet을 통해 발송하는 과정에서 왜곡될 가능성이 있습니다. 요청 사항이 변경되지 않았음을 보증하기 위해 매 요청 시 서명을 필수로 요청하고 있으며(시세 API 제외), Parameter 검수 또는 Parameter 값이 전송되는 과정에서 변경되지 않았음을 확인하는데 활용됩니다.

서명 계산 프로세스:

  1. 서명 계산 요구사항의 규범: HMAC로 서명 계산을 진행할 경우, 상이한 내용의 계산으로 얻는 결과값은 완전히 다를 수 있습니다. 따라서, 서명 계산을 진행하기 전에 해당 요청에 대해 먼저 일종의 규칙화를 해 주시기 바랍니다. 다음과 같이 어떠한 주문서 상세 정보 조회 요청을 예시로 하여 설명 드리겠습니다.

https://api-cloud.huobi.co.kr/v1/order/orders?
AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2017-05-11T15:19:30
&order-id=1234567890
  1. 요청 방법(GET 또는 POST) 뒤쪽에 행 추가를 의미하는 \n를 추가합니다.

GET\n
  1. 소문자로 접속 주소를 추가한 후, 뒤쪽에 행 추가를 의미하는 \n를 추가합니다.

api-cloud.huobi.co.kr\n
  1. 접속 방법 경로를 추가한 후, 뒤쪽에 행 추가를 의미하는 \n를 추가합니다.

/v1/order/orders\n
  1. ASCII코드 순서에 따라 parameter를 정렬합니다(UTF-8를 사용하여 코딩하고 URI 코딩을 진행합니다. 16진법 부호는 반드시 대문자로 기입해야 합니다. 예: ‘코딩 가능’은 ‘%3A’, 빈칸 코딩은 ‘%20’). 예를 들어, 다음은 요청 parameter의 raw 순서이며, 코딩을 거치면 다음과 같이 표시됩니다.

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx
order-id=1234567890
SignatureMethod=HmacSHA256
SignatureVersion=2
Timestamp=2017-05-11T15%3A19%3A30

이러한 Parameter는 다음과 같이 정렬됩니다.


AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx
SignatureMethod=HmacSHA256
SignatureVersion=2
Timestamp=2017-05-11T15%3A19%3A30
order-id=1234567890

상기 순서에 따라 각 parameter를 기호’&’로 연결합니다.


AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&order-id=1234567890

최종적으로 서명 계산을 진행해야 하는 문자열의 구성은 다음과 같습니다.


GET\n
api-cloud.huobi.co.kr\n
/v1/order/orders\n
AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&order-id=1234567890

SecretKey 서명을 진행합니다.


b0xxxxxx-c6xxxxxx-94xxxxxx-dxxxx

도출된 서명 계산 결과값으로 Base64 코딩을 진행합니다.


4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=

상기 값을 Parameter Signature의 결과값으로 하여 API 요청에 추가합니다. 본 Parameter를 요청에 추가할 때, 반드시 해당 값 URI 코딩을 진행해야 합니다.

최종적으로 서버에 발송하게 되는 API 요청은 다음과 같아야 합니다.


https://api-cloud.huobi.co.kr/v1/order/orders?AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&order-id=1234567890&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&Signature=4F65x5A2bLyMWVQj3Aqp%2BB4w%2BivaA7n5Oi2SuYtCJ9o%3D
Clone this wiki locally