인터페이스

Version : 1.1 / Update : 2025.10.29

1. 개요

JWT HTTP REST API Service의 사용자 인터페이스에 대한 정의한다. JWT HTTP REST API Service는 HTTP 기반의 RESTful API를 제공한다.

JWT HTTP REST API Service는 인증을 위하여 다음의 두 가지 방법의 인증을 제공한다.

1. TLS 인증(HTTPS): 설정에 따라 인증 없음, 서버 인증, 상호 인증의 기능을 제공한다.

2. API 인증: 사용하는 클라이언트의 인증을 위해 사용한다.

---

2. 설정 파일

2-1. 프로그램 실행 옵션

JWT REST API Service 프로그램은 실행시 프로그램 실행의 동일 경로에서 config.json 파일을 찾는다. config.json 파일의 위치를 변경하여 지정하고 싶은 경우는 프로그램 실행 인자로 -config 옵션을 통해서 이를 변경 할 수 있다.

프로그램 실행 예시

% key4cJWTServer -config /opt/key4c/etc/config.json

프로그램의 버전을 확인하고 싶은 경우 -version 옵션을 실행하면, 프로그램의 버전 확인이 가능하다.

프로그램 버전 확인 실행 예시

% key4cJWTServer -version
key4cJWTServer Version 1.0.0

2-2. 설정 파일

프로그램에 사용되는 설정 파일은 다음과 같은 구조를 가지고 있다.

depth1	depth2	depth3	필수 여부	설명
server	ip		필수	JWT 서비스를 허용할 IP(""으로 설정하면 모두 허용)
	port		필수	JWT 서비스에서 사용할 port
	tlsOptions	tlsType	필수	JWT 서비스에 사용할 HTTP 보안 옵션 유효 값 범위 - 0: TLS 없음 - 1: TLS Server Only - 2: mTLS between Client and Server 해당 옵션이 1 또는 2인 경우, 같은 레이서의 caCertFile, certFile, keyFile 값은 필수 이다.
		caCertFile	조건부 필수	tlsType 설명 참조
		certFile	조건부 필수	tlsType 설명 참조
		keyFile	조건부 필수	tlsType 설명 참조
key4c	uuid		필수	key4c 웹 콘솔에서 표기된 HSM Token의 uuid
	pin		필수	HSM 사용을 위한 PIN 값
	apiKey		필수	key4c 서비스를 사용하기 위한 apiKey
jwt	issuer		필수	JWT 발급자 정보로 사용하기 위한 값
appConfig	logFile		선택	값이 없으면 stdout으로만 출력

설정 파일 예시

{
  "server": {
    "ip": "",
    "port": 8080,
    "tlsOptions": {
      "tlsType": 1,
      "caCertFile": "./certs/rootCa.crt",
      "certFile": "./certs/server.crt",
      "keyFile": "./certs/server.key"
    }
  },
  "key4c": {
    "uuid": "<<KEY4C_HSM_Token_UUID>>"",
    "pin": "<<KEY4C_HSM_PIN>>",
    "apiKey": "<<KEY4C_API_KEY>>"
  },
  "jwt": {
    "issuer": "Key4cJwtSigner"
  },
  "appConfig": {
    "logFile": "key4c.log"
  }
}

---

3. 인터페이스

3-1. HTTP Header 공통

Key	Value	Optional	Description
Content-Type	Application/json	Mandatory	데이터 송수신에 사용하는 데이터는 JSON 타입으로 지정한다.

3-2. JWT 서명 요청

Request

POST /jwt http1.1
Content-Type: Application/json

{
  "ckaId": string,
  "signAlg": string,
  "hash": string,
  "subject": string,
  "aliveHours": integer,
  "aliveMinutues": integer,
  "aliveSeconds": integer,
  "claims": map
}

Request Body

Key	Data Type	Optional	Description
ckaId	string	Mandatory	JWT를 사용하기 위한 키의 CKA_ID 값
signAlg	string	Conditional	RSA 키의 경우 signAlg을 지정해야 함. - 선택할 수 있는 값: RSA, RSA-PSS ECC 키의 경우 singAlg 값 고정. - 고정값 : ECC
hash	string	Conditional	RSA 키의 경우 아래 3가지 hash 중 1 선택 입력 필수. - sha256, sha384, sha512 ECC키의 경우 키 설정에 따라가며, 입력값은 무시. - prime256v1 (P-256) -> sha256
subject	string	Mandatory	JWT를 사용할 주체의 이름
aliveHours	integer	Mandatory	JWT 토큰 유효 시각, default=0
aliveMinutes	integer	Mandatory	JWT 토큰 유효 분, default=0
alibeSeconds	integer	Mandatory	JWT 토큰 유효 초, default=0
claims	map	Optional	Key-Value 형태의 map 데이터 Claims.

Request Body Example

{
    "ckaId": "7FD4CCE43D7B9CB431FDC11F3C0611A671B6F173",
    "hash": "sha512",
    "signAlg": "RSA-PSS",
    "subject": "subject",
    "aliveHours": 0,
    "aliveMinutes": 5,
    "aliveSeconds": 0,
    "claims": {
        "hello": "world",
        "values":{
            "key1":"value1",
            "key2":"value2"
        }
    }
}

Response Body

Key	Data Type	Optional	Description
time	date	Mandatory	GTM+9 date time string
code	integer	Mandatory	- 0: success - 1: invalid parameters - 2: server error
message	string	Mandatory	error message
token	string	Optional	when code is 0, token will returns JWT token

Response Body Example

{
    "time": "2025-08-18 10:42:08.169 +0900",
    "code": 0,
    "message": "OK",
    "token": "eyJhbGciOiJQUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NTU0OTU3MjgsImhlbGxvIjoid29ybGQiLCJpYXQiOjE3NTU0ODEzMjgsImlzcyI6IktleTRjSnd0U2lnbmVyIiwibmJmIjoxNzU1NDgxMzI4LCJzdWIiOiJzdWJqZWN0IiwidmFsdWVzIjp7ImtleTEiOiJ2YWx1ZTEiLCJrZXkyIjoidmFsdWUyIn19.B1wNRQc5Ex-Hnckfl7vrAXv46f8UWFMIBgCFFqoxa0Y5EV4mLONRPXOO49WqNdnP8vbAvHJjecpDsdmM4AlLb7WFaDgUGHbAEa-a9kiRrVemFYy1c5cT3q-1W9gqQdm8DzwROHLvN8b7FG_zxP6uFNeYoTgCi1RzHMPrbVDCr_kTXSaPFg37q0tgI5JBI6o49UO2o7YUGZr5tr9NXeU3Hj_LPpuLp3EaSBcRtDxXXgPfCaS_y9uQMXEHj7WQKhzwS7xU4He6gDsznB6Na7Fj9MqrYeLDgSkbjN1J_-iMAIcUWYxtljXFirAf5VFPE6yCpWOJ1h999bO8OwxIL6LqUw"
}

3-3. JWT 공개키 요청

Request

GET /publicKey/{ckaId} http1.1

Request Example

GET https://localhost:8080/publicKey/7FD4CCE43D7B9CB431FDC11F3C0611A671B6F173 http1.1

Response Body

Key	Data Type	Optional	Description
time	date	Mandatory	GTM+9 date time string
code	integer	Mandatory	- 0: success - 1: invalid parameters - 2: server error
message	string	Mandatory	error message
publicKey	string	Optional	when code is 0, publicKey will returns Public Key

Response Body Example

{
    "time": "2025-08-18 10:45:45.504 +0900",
    "code": 0,
    "message": "OK",
    "publicKey": "-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnZz9u6yFe2APOzVeBac+8+Cr4rKsd6r/eBrxE29Vy3WvUmSfRyh0bEOZMCJz+yGlLBCDyYAETEzk2f38dpAv9cIbLLxVpZgX+2kat5pG0xvaWoQLHTyj5Ddwt9/hirz8haRhTaxQnkJlmg3RB1Ns1j7122PVLoa1L7u6jFMqxtTvjXnMak5XLZpVD1FQ8KamE8idas2OGbWsYp8sSq0dgfWPaO3wwIs4BDxKMZ4qzOUO9jcZm27+HcjdTW/C5jBZX4V5WGto3s/pY1M1eEg2ckVeLgUTpy7b9IJx4ylVVSwT2fs/rFUMBLWBL5UKH/UbbtJ5hgfex7vgtwIccVzYAQIDAQAB-----END PUBLIC KEY-----"
}

4. JWT

4-1. JWT 구조

JWT는 . 으로 구분 된 세 개의 문자열로 구성.
┌────────────┐    ┌───────────────┐    ┌────────────────────┐
│   Header   │ .  │    Payload    │ .  │     Signature      │
└────────────┘    └───────────────┘    └────────────────────┘

구성요소	역할	포함정보	기타
Header	알고리즘, 타입	alg, typ
Payload	데이터	exp, iss, iat, nbf, sub, claims	민감 정보 금지
Signature	위조 방지	서명값	base64(header) + '.' + base64(payload)를 개인키로 서명한 값

Decoded header Example

{
  "alg": "PS512" ,
  "typ": "JWT"
}

Name	Description
alg	토근 서명 알고리즘 (RS256: RSA + SHA256, PS256: RSA-PSS + SHA256, ES256: ECC + SHA256)
type	토큰의 타입

Decoded payload Example

{
  "exp": 1755495728,
  "iat": 1755481328,
  "nbf": 1755481328,
  "iss": "Key4cJwtSigner",
  "sub": "subject",
  "hello": "world",
  "values": {
    "key1": "value1",
    "key2": "value2"
  }
}

Name	Description
exp	토큰 만료 시각
iat	토큰 발급 시각
nbf	토큰 유효 시작 시각
iss	토큰 발급자
sub	토큰의 주제
그 외	사용자 정의 데이터