콘텐츠로 이동

KMS API

클라우드 KMS(Key Management System)는 클라우드가 사용자를 대신해 암호화된 키들을 관리해주는 서비스입니다(Google Cloud Platform (GCP) KMS, Amazon Web Services (AWS) KMS).

블록체인 Open API - KMS API는, 이렇게 클라우드 KMS에 보관된 키를 블록체인 계정 지갑 키(Private Key, 지갑 개인키)로 사용할 수 있게 해주는 API입니다. KMS API를 사용하면 사용자가 블록체인 계정 지갑 키를 직접 관리하지 않아도 KMS에 보관된 키로 트랜잭션을 생성하고, 트랜잭션에 서명하고, 이를 블록체인에 전송할 수 있습니다. KMS API가 지원하는 클라우드 KMS 플랫폼은 GCP와 AWS 입니다.

예시로, 다음과 같이 KMS API를 사용할 수 있습니다.

클라우드 KMS에 이미 키가 있는 경우

  1. 클라우드 크리덴셜 준비
  2. Hive 콘솔 > 블록체인 > KMS 인증 정보 > 인증 정보 추가하기에서 클라우드 서비스 계정 정보(Credentials)를 등록하고 x-credential-id를 획득
  3. 클라우드 KMS 키 정보 준비
  4. 지갑 주소 등록 API 호출
  5. 지갑 주소 획득
  6. KMS 지갑 정보 조회
  7. KMS 지갑으로 트랜잭션을 생성: 토큰 전송, 스마트 컨트랙트 배포 등 새로운 트랜잭션을 생성하는 API를 호출
  8. 생성한 트랜잭션에 KMS 서명 API로 서명
  9. 서명한 트랜잭션을 블록체인 네트워크에 전송

클라우드 KMS를 사용하지 않거나, KMS에 키가 없는 경우

  1. 클라우드 KMS 서비스 계정 준비
  2. 지갑 키 생성: 지갑 키 생성 API로 생성
    1. 클라우드 크리덴셜 준비
    2. 블록체인 API 인증 키 준비
    3. Hive 콘솔 > 블록체인 > KMS 인증 정보 > 인증 정보 추가하기에서 클라우드 서비스 계정 정보(Credentials)를 등록하고 x-credential-id를 획득
    4. x-credential-id와 API 인증 키를 사용해 KMS 지갑 키 생성
    5. 지갑 키와 지갑 주소 획득
  3. KMS 지갑 정보 조회
  4. KMS 지갑으로 트랜잭션을 생성: 토큰 전송, 스마트 컨트랙트 배포 등 새로운 트랜잭션을 생성하는 API를 호출
  5. 생성한 트랜잭션에 KMS 서명 API로 서명
  6. 서명한 트랜잭션을 블록체인 네트워크에 전송

Note

KMS 서명 API로 서명할 수 있는 트랜잭션은 KMS 지갑 키로 생성한 트랜잭션뿐입니다.

사전 준비

클라우드 KMS Credentials를 Hive 콘솔 > 블록체인 > KMS 인증 정보 > 인증 정보 추가하기 에 등록합니다.

블록체인 계정 지갑 주소와 KMS 지갑 키 생성

클라우드 서비스 계정으로 KMS에 지갑 키를 생성하고, 이 지갑 키를 기반으로 블록체인 계정 지갑 주소를 생성합니다. 지갑 키는 KMS에 저장되고 확인할 수 없습니다. 키 생성 시 지연이 발생하면 지갑 주소가 응답값에 포함되지 않을 수 있습니다. 지갑 주소는 KMS 지갑 정보 조회 API에서 키 아이디(keyId)를 사용해 조회할 수 있습니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms
HTTP Method POST
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
x-network 블록체인 네트워크 string Y
x-credential-id Hive 콘솔에 Credentials 등록 시 얻는 고유한 값 string Y
Authorization API를 호출하기 위한 인증 토큰 string Y

Request parameters

필드명 설명 타입 필수 여부
keyName 생성할 키 이름으로 원하는 내용을 입력합니다. string Y
keyOptions KMS 지갑 키 옵션 정보 json Y
keyOptions.location 키를 저장할 위치입니다. 각 클라우드에서 사용하는 KMS 위치 정보입니다. string
  • GCP: Y (location, 예시: asia-northeast3)
  • AWS: Y (region, 예시: ap-northeast-2d)
keyOptions.project GCP 프로젝트 ID string
  • GCP: Y
  • AWS: N
keyOptions.keyRing GCP 키링 정보 string
  • GCP: Y
  • AWS: N

Responses

필드명 설명 타입
code API 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.keyId 생성한 키의 고유ID string
data.keyName 생성한 키의 별칭 string
data.address KMS 키로 생성한 블록체인 계정 지갑 주소 string
data.purpose 키 사용 용도 string
data.algorithm 키 생성 알고리즘 종류 string
data.cloudType 클라우드 플랫폼 종류 string
data.network 키를 사용할 블록체인 네트워크 string
data.options 키 옵션 정보 json
data.options.project GCP 프로젝트 ID string
data.options.location 키가 저장되는 위치 string
data.options.keyRing GCP 키링 정보 string
data.options.keyVersion GCP 키 버전 정보 string
data.regId 키 등록자 ID string
data.modId 키 수정자 ID string
data.createdAt 키 등록일 string
data.updatedAt 키 수정일 string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms' 
  -H 'accept: application/json' 
  -H 'x-credential-id: eb6cc005-b8d0-bc96-8b60-a531c2f15fd2' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiO... 
  -H 'Content-Type: application/json' 
  -d '{
  "keyName": "test-key",
  "keyOptions": {
    "project": "test-project",
    "location": "asia-northeast3",
    "keyRing": "test-keyring"
    },
    "requesterId": "system"
    }'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "test1-game-provider",
    "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test1-game-provider/cryptoKeyVersions/1",
    "address": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "project",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "test",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

블록체인 계정 지갑 주소 등록

KMS 지갑 키를 기반으로 블록체인 계정 지갑 주소를 생성하고 이를 Hive 서버에 등록합니다. GCP 사용 시 키 버전(keyVersion)을 명시해야 합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms/import
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms/import
HTTP Method POST
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
x-network 블록체인 네트워크 string Y
x-credential-id Hive 콘솔에 Credentials 등록 시 얻는 고유한 값 string Y
Authorization API를 호출하기 위한 인증 토큰 string Y

Request parameters

필드명 설명 타입 필수 여부
keys KMS 지갑 키 정보 array(json) Y
keys.keyId 생성한 키 고유 ID string Y
keys.keyVersion GCP 사용 시 키 버전 정보 string
  • GCP: Y
  • AWS: N
keyOptions 키 옵션 정보 json Y
keyOptions.location 키를 저장할 위치입니다. 각 클라우드에서 사용하는 KMS 위치 정보입니다. string
  • GCP: Y (location, 예시: asia-northeast3)
  • AWS: Y (region, 예시: ap-northeast-2d)
keyOptions.project GCP 프로젝트 ID string
  • GCP: Y
  • AWS: N
keyOptions.keyRing GCP 키링 정보 string
  • GCP: Y
  • AWS: N
requesterId 요청자 ID입니다. API 호출 주체를 구분하기 위한 임의의 값입니다. KMS 지갑 생성 시 Hive 콘솔에서 로그인한 계정 ID가 입력됩니다. string N

Responses

필드명 설명 타입
code API 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.keyId 생성한 키의 고유ID string
data.keyName 생성한 키의 별칭 string
data.address KMS 키로 생성한 블록체인 계정 지갑 주소 string
data.purpose 키 사용 용도 string
data.algorithm 키 생성 알고리즘 종류 string
data.cloudType 클라우드 플랫폼 종류 string
data.network 키를 사용할 블록체인 네트워크 string
data.options 키 옵션 정보 json
data.options.project GCP 프로젝트 ID string
data.options.location 키가 저장되는 위치 string
data.options.keyRing GCP 키링 정보 string
data.options.keyVersion GCP 키 버전 정보 string
data.regId 키 등록자 ID입니다. requesterId와 동일합니다. string
data.modId 키 수정자 ID string
data.createdAt 키 등록일 string
data.updatedAt 키 수정일 string

Request sample

curl -X 'POST' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms/import' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 9b3c0c1d-868c-71ea-a1a9-e615148b7f14' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJvb...' 
  -H 'Content-Type: application/json' 
  -d '{
  "keys": [
    {
      "keyId": "test1-game-provider",
      "keyVersion": "1"
    }
  ],
  "keyOptions": {
    "project": "kms-test",
    "location": "asia-northeast3",
    "keyRing": "key-ring"
  },
  "requesterId": "system"
}'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "kms-key-002",
    "keyName": "projects/quixotic-carver-412405/locations/asia-northeast3/keyRings/keyring/cryptoKeys/kms-key-002/cryptoKeyVersions/1",
    "address": "0x1e0481127b0ed12b6b6911bec32d414d76042860",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "quixotic-carver-412405",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "system",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

KMS 지갑 키 정보와 계정 지갑 주소 조회

KMS 지갑 키 고유 ID(keyId) 또는 키 이름(keyName)으로 KMS 지갑 키 정보와 계정 지갑 주소를 조회합니다. 키 생성 시 지갑 주소를 확인하지 못했다면 사용할 수 있습니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms/{key}
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms/{key}
HTTP Method GET
Content-Type application/json

Path parameters

필드명 설명 타입 필수 여부
key 키 고유 ID 또는 키 이름 string Y

Header parameters

필드명 설명 타입 필수 여부
x-credential-id Hive 콘솔에 Credentials 등록 시 얻는 고유한 값 string Y
Authorization API를 호출하기 위한 인증 토큰 string Y

Responses

필드명 설명 타입
code API 호출 결과 코드 , 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.keyId 생성한 키의 고유ID string
data.keyName 생성한 키의 별칭 string
data.purpose 키 사용 용도 string
data.algorithm 키 생성 알고리즘 종류 string
data.cloudType 클라우드 플랫폼 종류 string
data.network 키를 사용할 블록체인 네트워크 string
data.options 키 옵션 정보 json
data.options.project GCP 프로젝트 ID string
data.options.location 키가 저장되는 위치 string
data.options.keyRing GCP 키링 정보 string
data.options.keyVersion GCP 키 버전 정보 string
data.regId 키 등록자 ID string
data.modId 키 수정자 ID string
data.createdAt 키 등록일 string
data.updatedAt 키 수정일 string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms/kms-key-002' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 9b3c0c1d-868c-71ea-a1a9-e615148b7f14' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJvbGUiOiJhZG1pb...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "keyId": "test1-game-provider",
    "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test1-game-provider/cryptoKeyVersions/1",
    "address": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
    "purpose": "ASYMMETRIC_SIGN",
    "algorithm": "EC_SIGN_SECP256K1_SHA256",
    "cloudType": "gcp",
    "network": "polygon",
    "options": {
      "project": "project",
      "location": "asia-northeast3",
      "keyRing": "keyring",
      "keyVersion": "1"
    },
    "regId": "test",
    "modId": null,
    "createdAt": "2024-02-22T08:28:04.000Z",
    "updatedAt": null
  }
}

KMS 지갑 키 정보와 계정 지갑 주소 목록 조회

KMS 지갑 키 정보와 계정 지갑 주소 목록을 조회합니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms
HTTP Method GET
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
x-network 블록체인 네트워크 string Y
x-credential-id Hive 콘솔에 Credentials 등록 시 얻는 고유한 값 string Y
Authorization API를 호출하기 위한 인증 토큰 string Y

Query parameters

필드명 설명 타입 필수 여부
page 현재 페이지 번호 number N
limit 한 페이지에 노출할 KMS 지갑 키 정보와 계정 지갑 주소의 개수 number N

Responses

필드명 설명 타입
code API 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.kms KMS 지갑 키 정보와 지갑 주소 목록 array(json)
data.meta 페이지네이션 정보 json
data.meta.totalItems 조회 결과 총 개수(KMS 지갑 키와 지갑 주소 정보 개수) number
data.meta.itemsPerPage 한 페이지에 노출되는 KMS 지갑 키와 지갑 주소 정보 개수 number
data.meta.totalPages 총 페이지 수 number
data.meta.currentPage 현재 페이지 번호 number

data.kms 배열에 담기는 각 원소 정보: KMS 지갑 키 정보와 계정 지갑 주소

필드명 설명 타입
keyId 생성한 키의 고유ID string
keyName 생성한 키의 별칭 string
address KMS 키로 생성한 블록체인 계정 지갑 주소 string
purpose 키 사용 용도 string
algorithm 키 생성 알고리즘 종류 string
cloudType 클라우드 플랫폼 종류 string
network 키를 사용할 블록체인 네트워크 string
options 키 옵션 정보 json
options.project GCP 프로젝트 ID string
options.location 키가 저장되는 위치 string
options.keyRing GCP 키링 정보 string
options.keyVersion GCP 키 버전 정보 string
regId 키 등록자 ID string
modId 키 수정자 ID string
createdAt 키 등록일 string
updatedAt 키 수정일 string

Request sample

curl -X 'GET' 
  'https://sandbox-bc-api.qpyou.cn/core/v1/kms?page=1&limit=10' 
  -H 'accept: application/json' 
  -H 'x-credential-id: 41e26545-547e-7632-be1f-289f75c092d2' 
  -H 'x-network: polygon' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXlObyI6MSwiaWQiOiJwbGF0Zm9ybSIsImNvbXBhbnkiOm51bGwsInJv...'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "kms": [
      {
        "keyId": "test-polygon-001",
        "keyName": "projects/tribal-octane-403302/locations/asia-northeast3/keyRings/test-keyring-001/cryptoKeys/test-polygon-001/cryptoKeyVersions/1",
        "address": "0x599220fb6cd54553b9c2dfda3b0f711d7ebc21fb",
        "purpose": "ASYMMETRIC_SIGN",
        "algorithm": "EC_SIGN_SECP256K1_SHA256",
        "cloudType": "gcp",
        "network": "polygon",
        "options": {
          "project": "tribal-octane-403302",
          "location": "asia-northeast3",
          "keyRing": "test-keyring-001",
          "keyVersion": "1"
        },
        "regId": "system",
        "modId": null,
        "createdAt": "2024-02-22T08:27:58.000Z",
        "updatedAt": null
      },{
        "keyId": "kms-key-002",
        "keyName": "projects/quixotic-carver-412405/locations/asia-northeast3/keyRings/keyring/cryptoKeys/kms-key-002/cryptoKeyVersions/1",
        "address": "0x1e0481127b0ed12b6b6911bec32d414d76042860",
        "purpose": "ASYMMETRIC_SIGN",
        "algorithm": "EC_SIGN_SECP256K1_SHA256",
        "cloudType": "gcp",
        "network": "polygon",
        "options": {
          "project": "quixotic-carver-412405",
          "location": "asia-northeast3",
          "keyRing": "keyring",
          "keyVersion": "1"
        },
        "regId": "system",
        "modId": null,
        "createdAt": "2024-02-22T08:28:04.000Z",
        "updatedAt": null
      }
    ],
    "meta": {
      "totalItems": 2,
      "itemCount": 2,
      "itemsPerPage": 10,
      "totalPages": 1,
      "currentPage": 1
    }
  }
}

KMS 서명

KMS 지갑 키로 트랜잭션에 서명합니다. KMS 지갑 계정으로 생성한 트랜잭션만 KMS 지갑 키로 서명할 수 있습니다.

Request URL

Live URL https://bc-api.qpyou.cn/core/v1/kms/sign
Sandbox URL https://sandbox-bc-api.qpyou.cn/core/v1/kms/sign
HTTP Method POST
Content-Type application/json

Header parameters

필드명 설명 타입 필수 여부
x-credential-id Hive 콘솔에 Credentials 등록 시 얻는 고유한 값 string Y
Authorization API를 호출하기 위한 인증 토큰 string Y

Request parameters

필드명 설명 타입 필수 여부
from 서명을 진행할 KMS 지갑 주소입니다. 트랜잭션을 생성하는 API(예시) Request Body의 from과 동일해야 합니다. string Y
unsignedTx 서명되지 않은 트랜잭션 데이터입니다. 트랜잭션을 생성하면 응답값으로 받는 data.rawTx입니다. 아래 종류를 지원합니다.
1. 트랜잭션 데이터
2. 다중 서명 트랜잭션 데이터(x-network가 polygon일 때)		 string Y

Responses

필드명 설명 타입
code API 호출 결과 코드, 0:성공 number
message 결과 메시지 string
data API 응답 데이터 json
data.signedTx 서명된 트랜잭션 정보 string

Request sample

curl -X 'POST' 
  'http://sandbox-bc-api.qpyou.cn/core/v1/kms/sign' 
  -H 'accept: application/json' 
  -H 'x-credential-id: eb6cc005-b8d0-bc96-8b60-a531c2f15fd2' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImNvbS5jb20yd...' 
  -d '{
  "from": "0xc5AC98006fe612395b132742Fbe80a6Dc184670a",
  "unsignedTx": "0x5a0ca3a7eebbafa946da6ed0160930fc4f334887dbf11a9b38937ab8831fd125..."
}'

Response sample

{
  "code": 0,
  "message": "success",
  "data": {
    "signedData": "string"
  }
}