Interface

Version : 1.0 / Update : 2025.10.14

1. Overview

This document defines the user interface of the JWT HTTP REST API Service. The JWT HTTP REST API Service provides an HTTP-based RESTful API.

For authentication, the JWT HTTP REST API Service supports two authentication methods

1. TLS Authentication (HTTPS): Depending on the configuration, it supports no authentication, server authentication, or mutual authentication.

2. API Authentication: Used to authenticate the client accessing the service.

2. Configuration File

2-1. Program Execution Options

The JWT REST API Service looks for the config.json file in the same directory where the program is executed. If you want to specify a different location for the config.json file, you can use the -config execution parameter when starting the program.

Program Execution Examples

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

To check the program version, run it with the -version option. This will display the current version of the program.

Example: Checking Program Version

% key4cJWTServer -version
key4cJWTServer Version 1.0.0

2-2. Configuration File

The configuration file used by the program follows the structure shown below.

depth1	depth2	depth3	Required	Description
server	ip		Required	IP addresses allowed to access the JWT service (set to "" to allow all)
	port		Required	Port used by the JWT service
	tlsOptions	tlsType	Required	HTTP Security Option for the JWT Service Valid Values: 0: No TLS 1: TLS (Server Only) 2: Mutual TLS (Client & Server) If this option is set to 1 or 2, the fields caCertFile, certFile, and keyFile in the same layer must be provided.
		caCertFile	Conditionally Required	Refer to the tlsType description.
		certFile	Conditionally Required	Refer to the tlsType description.
		keyFile	Conditionally Required	Refer to the tlsType description.
key4c	uuid		Required	UUID of the HSM token as shown in the Key4C web console
	pin		Required	PIN used to access the HSM
	apiKey		Required	apiKey for using the Key4C service
jwt	issuer		Required	Value to be used as the JWT issuer (e.g., iss)
appConfig	logFile		Optional	If empty, output is written to stdout only

Example Configuration File

{
  "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. Interface

3-1. Common HTTP Headers

Key	Value	Optional	Description
Content-Type	Application/json	Mandatory	All request and response data are formatted in JSON.

3-2. JWT Signing Request

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

Key	Data Type	Optional	Description
ckaId	string	Mandatory	CKA_ID value of the key used for JWT.
signAlg	string	Conditional	For RSA keys, the signAlg parameter must be specified. Available values: RSA, RSA-PSS For ECC keys, the signAlg value is fixed. Fixed value : ECC
hash	string	Conditional	For RSA keys, one of the following three hash algorithms must be selected and provided: sha256, sha384, sha512 For ECC keys, the hash algorithm follows the key configuration, and any input value is ignored. prime256v1 (P-256) → sha256
subject	string	Mandatory	The subject name that will use the JWT.
aliveHours	integer	Mandatory	JWT token validity period in hours. Default = 0.
aliveMinutes	integer	Mandatory	JWT token validity period in minutes. Default = 0.
alibeSeconds	integer	Mandatory	JWT token validity period in seconds. Default = 0.
claims	map	Optional	Key-value map containing JWT 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 Public Key Request

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 Structure

 A JWT consists of three strings separated by periods.
┌────────────┐    ┌───────────────┐    ┌────────────────────┐
│   Header   │ .  │    Payload    │ .  │     Signature      │
└────────────┘    └───────────────┘    └────────────────────┘

Component	Role	Included Information	Notes
Header	Algorithm, type	alg, typ
Payload	Data	exp, iss, iat, nbf, sub, claims	Do not include sensitive information
Signature	Tamper prevention	Signature value	Value obtained by signing base64(header) + '.' + base64(payload) with a private key

Decoded header Example

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

Name	Description
alg	Token signing algorithm (RS256: RSA + SHA256, PS256: RSA-PSS + SHA256, ES256: ECC + SHA256)
typ	Token type

Decoded payload Example

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

Name	Description
exp	Token expiration time
iat	Token issued-at time
nbf	Token not-before time
iss	Token issuer
sub	Token subject
Others	User-defined data