틸코블렛 API 데모 페이지

API 프로세스

https://tilko.net/Docs/Step1

개발 가이드 문서

틸코 API 개발 가이드.v1.1(20211119.1030-서성원).pdf

틸코블렛.간편인증API사용가이드(20220117.0859-서성원).pdf

틸코블렛.틸코사인 제품소개서.v1.2(20210429.1436-손정민).pdf

틸코사인.공인인증서 활용 가이드.v2.7(20250925.1612-한인수).pdf

샘플 코드

개발 언어

▽Request

HEADER

Method: POST
Content-Type: application/json
API-KEY: API KEY (내정보 > API KEY)
ENC-KEY: API Key 생성 시 제공받은 '공개키'로 RSA 암호화 시킨 AES Secret key 값이며, AES Secret key는 고객님이 생성한 값입니다.

BODY

Json 형식으로 보기

▽Response

Result	Boolean
ApiTxKey	String
StatusSeq	Int32
ErrorCode	Int32
Message	String
ErrorLog	String
TargetCode	String
TargetMessage	String
PointBalance	String

▽Demo

using Microsoft.VisualStudio.TestTools.UnitTesting;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Org.BouncyCastle.Crypto;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.OpenSsl;
using Org.BouncyCastle.Security;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;

namespace UnitTest
{
	[TestClass]
	public class TestCase
	{
		string apiHost   = "https://dev.tilko.net";
		string apiKey    = "__API_KEY__";

// AES 암호화 함수
		public string aesEncrypt(byte[] key, byte[] iv, byte[] plainText)
		{
			byte[] ret = new byte[0];

using (RijndaelManaged aes = new RijndaelManaged())
			{
				aes.Key = key;
				aes.IV = iv;
				aes.Mode = CipherMode.CBC;
				aes.Padding = PaddingMode.PKCS7;

using (ICryptoTransform enc = aes.CreateEncryptor(aes.Key, aes.IV))
				{
					using (MemoryStream ms = new MemoryStream())
					{
						using (CryptoStream cs = new CryptoStream(ms, enc, CryptoStreamMode.Write))
						{
							cs.Write(plainText, 0, plainText.Length);
							cs.FlushFinalBlock();
							ret = ms.ToArray();
						}
					}
				}
				aes.Clear();
			}

return Convert.ToBase64String(ret);
		}

// AES 암호화 함수
		public string aesEncrypt(byte[] key, byte[] iv, string plainText)
		{
			byte[] ret		= new byte[0];

using (RijndaelManaged aes = new RijndaelManaged())
			{
				aes.Key				= key;
				aes.IV				= iv;
				aes.Mode			= CipherMode.CBC;
				aes.Padding			= PaddingMode.PKCS7;

using (ICryptoTransform enc = aes.CreateEncryptor(aes.Key, aes.IV))
				{
					using (MemoryStream ms = new MemoryStream())
					{
						using (CryptoStream cs = new CryptoStream(ms, enc, CryptoStreamMode.Write))
						{
							cs.Write(Encoding.UTF8.GetBytes(plainText), 0, Encoding.UTF8.GetBytes(plainText).Length);
							cs.FlushFinalBlock();
							ret	= ms.ToArray();
						}
					}
				}
				aes.Clear();
			}

return Convert.ToBase64String(ret);
		}

// RSA 암호화 함수
		public string rsaEncrypt(string publicKey, byte[] aesKey)
		{
			string encryptedData = "";

using (RSACryptoServiceProvider rsaCSP = importPublicKey(publicKey))
			{
				byte[] byteEncryptedData = rsaCSP.Encrypt(aesKey, false);
				encryptedData = Convert.ToBase64String(byteEncryptedData);
				rsaCSP.Dispose();
			}

return encryptedData;
		}

public static RSACryptoServiceProvider importPublicKey(string pem)
		{
			string PUBLIC_HEADER	= "-----BEGIN PUBLIC KEY-----";
			string PUBLIC_FOOTER	= "-----END PUBLIC KEY-----";

if (!pem.Contains(PUBLIC_HEADER))
			{
				pem = PUBLIC_HEADER + Environment.NewLine +
					  pem + Environment.NewLine +
					  PUBLIC_FOOTER;
			}

PemReader pr						= new PemReader(new StringReader(pem));
			AsymmetricKeyParameter publicKey	= (AsymmetricKeyParameter)pr.ReadObject();
			RSAParameters rsaParams				= DotNetUtilities.ToRSAParameters((RsaKeyParameters)publicKey);

RSACryptoServiceProvider csp		= new RSACryptoServiceProvider();
			csp.ImportParameters(rsaParams);

return csp;
		}

// RSA 공개키(Public Key) 조회 함수
		public string getPublicKey()
        {
			string rsaPublicKey	= "";

using (HttpClient httpClient = new HttpClient())
			{
				httpClient.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

// 틸코 인증 서버에 RSA 공개키 요청
				string url	= string.Format("{0}/api/Auth/GetPublicKey?APIkey={1}", apiHost, apiKey);
				using (var response = httpClient.GetAsync(url).Result)
				{
					var resContent	= response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
					JObject resJson	= JObject.Parse(resContent);

rsaPublicKey	= (string)resJson["PublicKey"].ToString();
				}
			}

return rsaPublicKey;
		}

public class Auth
		{
			public string UserId { get; set; }
		
			public string UserPassword { get; set; }
		}

[TestMethod]
		public void main()
		{
			// RSA Public Key 조회
			string rsaPublicKey		= getPublicKey();
			Debug.WriteLine("rsaPublicKey: " + rsaPublicKey);

// AES Secret Key 및 IV 생성
			byte[] aesKey			= new byte[16];
			new Random().NextBytes(aesKey);
			byte[] aesIv			= new byte[16] { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };

// AES Key를 RSA Public Key로 암호화
			string aesCipherKey		= rsaEncrypt(rsaPublicKey, aesKey);
			Debug.WriteLine("aesCipherKey: " + aesCipherKey);

// API URL 설정
			string url				= apiHost + "/api/v2.0/nhis/register";

// API 요청 파라미터 설정
			var paramObj	= {{REQ_JSON}};

string bodies	= JsonConvert.SerializeObject(paramObj);

// API 호출
			using (HttpClient httpClient = new HttpClient())
			{
				httpClient.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));
				httpClient.DefaultRequestHeaders.Add("API-KEY", apiKey);
				httpClient.DefaultRequestHeaders.Add("ENC-KEY", aesCipherKey);

// 틸코 데이터 서버에 데이터 요청
				var reqContent = new StringContent(bodies, Encoding.UTF8, "application/json");
				using (var response = httpClient.PostAsync(url, reqContent).Result)
				{
					var resContent	= response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
					Debug.WriteLine("resContent: " + resContent);

// 바이너리 파일 저장(해당되는 경우에만)
					/*
					JObject resJson	= JObject.Parse(resContent);
					File.WriteAllBytes("D:\\result.bin", Convert.FromBase64String((string)resJson["Result"]["BinaryData"]));
					*/
				}
			}
		}
	}
}

package UnitTest;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.io.UnsupportedEncodingException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.PublicKey;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import java.util.Random;
import java.util.concurrent.TimeUnit;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;

import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;
import org.json.simple.parser.ParseException;

import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class TestCase {

String apiHost	= "https://dev.tilko.net";
	String apiKey	= "__API_KEY__";

// AES 암호화 함수
	public String aesEncrypt(byte[] key, byte[] iv, byte[] plainText) throws NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException, InvalidAlgorithmParameterException, IllegalBlockSizeException, BadPaddingException {
		Cipher cipher						= Cipher.getInstance("AES/CBC/PKCS5Padding");	// JAVA의 PKCS5Padding은 PKCS7Padding과 호환
		SecretKeySpec keySpec				= new SecretKeySpec(key, "AES");
		IvParameterSpec ivSpec				= new IvParameterSpec(iv);

cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec);
		byte[] byteEncryptedData			= cipher.doFinal(plainText);
		
		// Base64로 인코딩
		String encryptedData				= new String(Base64.getEncoder().encodeToString(byteEncryptedData));
		
		return encryptedData;
	}

// AES 암호화 함수
	public String aesEncrypt(byte[] key, byte[] iv, String plainText) throws NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException, InvalidAlgorithmParameterException, IllegalBlockSizeException, BadPaddingException, UnsupportedEncodingException {
		Cipher cipher						= Cipher.getInstance("AES/CBC/PKCS5Padding");	// JAVA의 PKCS5Padding은 PKCS7Padding과 호환
		SecretKeySpec keySpec				= new SecretKeySpec(key, "AES");
		IvParameterSpec ivSpec				= new IvParameterSpec(iv);

cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec);
		byte[] byteEncryptedData			= cipher.doFinal(plainText.getBytes("UTF-8"));
		
		// Base64로 인코딩
		String encryptedData				= new String(Base64.getEncoder().encodeToString(byteEncryptedData));
		
		return encryptedData;
	}

// RSA 암호화 함수
	public static String rsaEncrypt(String rsaPublicKey, byte[] aesKey) throws NoSuchAlgorithmException, UnsupportedEncodingException, InvalidKeySpecException, NoSuchPaddingException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException {
		String encryptedData				= null;
		
        KeyFactory keyFactory				= KeyFactory.getInstance("RSA");
        byte[] keyBytes						= Base64.getDecoder().decode(rsaPublicKey.getBytes("UTF-8"));
        X509EncodedKeySpec spec				= new X509EncodedKeySpec(keyBytes);
        PublicKey fileGeneratedPublicKey	= keyFactory.generatePublic(spec);
        RSAPublicKey key					= (RSAPublicKey)(fileGeneratedPublicKey);

// 만들어진 공개키객체를 기반으로 암호화모드로 설정하는 과정
		Cipher cipher						= Cipher.getInstance("RSA");
		cipher.init(Cipher.ENCRYPT_MODE, key);

// 평문을 암호화하는 과정
		byte[] byteEncryptedData			= cipher.doFinal(aesKey);
		
		// Base64로 인코딩
		encryptedData						= new String(Base64.getEncoder().encodeToString(byteEncryptedData));

return encryptedData;
	}

// RSA 공개키(Public Key) 조회 함수
	public String getPublicKey() throws IOException, ParseException {
		OkHttpClient client		= new OkHttpClient();
		
		Request request			= new Request.Builder()
									.url(apiHost + "/api/Auth/GetPublicKey?APIkey=" + apiKey)
									.header("Content-Type", "application/json").build();

Response response		= client.newCall(request).execute();
		String responseStr		= response.body().string();

JSONParser jsonParser	= new JSONParser();
		JSONObject jsonObject	= (JSONObject) jsonParser.parse(responseStr);
		
		String rsaPublicKey		= (String) jsonObject.get("PublicKey");

return rsaPublicKey;
	}

public static void main(String[] args) throws IOException, ParseException, NoSuchAlgorithmException, InvalidKeySpecException, NoSuchPaddingException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException, InvalidAlgorithmParameterException {
		TestCase tc				= new TestCase();

// RSA Public Key 조회
		String rsaPublicKey		= tc.getPublicKey();
		System.out.println("rsaPublicKey: " + rsaPublicKey);
		
		
		// AES Secret Key 및 IV 생성
		byte[] aesKey			= new byte[16];
		new Random().nextBytes(aesKey);
		
		byte[] aesIv			= new byte[] { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };

// AES Key를 RSA Public Key로 암호화
		String aesCipherKey		= rsaEncrypt(rsaPublicKey, aesKey);
		System.out.println("aesCipherKey: " + aesCipherKey);

// API URL 설정
		String url				= tc.apiHost + "/api/v2.0/nhis/register";
		
		
		// API 요청 파라미터 설정
		JSONObject json			= new JSONObject();

// API 호출
		OkHttpClient client		= new OkHttpClient.Builder()
									.connectTimeout(60, TimeUnit.SECONDS)
									.readTimeout(60, TimeUnit.SECONDS)
									.writeTimeout(60, TimeUnit.SECONDS)
									.build();
		
		Request request			= new Request.Builder()
									.url(url)
									.addHeader("API-KEY"			, tc.apiKey)
									.addHeader("ENC-KEY"			, aesCipherKey)
									.post(RequestBody.create(MediaType.get("application/json; charset=utf-8"), json.toJSONString())).build();

Response response		= client.newCall(request).execute();
		String responseStr		= response.body().string();
		System.out.println("responseStr: " + responseStr);
		
		
		// 바이너리 파일 저장(해당되는 경우에만)
		/*
		JSONParser parser		= new JSONParser();
		JSONObject responseJson	= (JSONObject) parser.parse(responseStr);
		
		JSONObject result		= (JSONObject) responseJson.get("Result");
		String binaryDataStr	= (String) result.get("BinaryData");
		
		byte[] binaryData = Base64.getDecoder().decode(binaryDataStr);
		try (OutputStream stream = new FileOutputStream("D:\\result.bin")) {
			stream.write(binaryData);
		}
		*/
	}

}

const Request   = require("sync-request");
const Crypto    = require("crypto");
const NodeRSA   = require("node-rsa");
const FS        = require("fs");

const apiHost   = "https://dev.tilko.net";
const apiKey    = "__API_KEY__";

// AES 암호화 함수
function aesEncrypt(key, iv, plainText) {
    const cipher    = Crypto.createCipheriv("aes-128-cbc", key, iv);
    
    let ret         = cipher.update(plainText, "utf8", "base64");
    ret             += cipher.final("base64");

return ret;
}

// RSA 암호화 함수
function rsaEncrypt(publicKey, aesKey, padding) {
    const key   = new NodeRSA("-----BEGIN PUBLIC KEY-----\n" + publicKey + "\n-----END PUBLIC KEY-----", {"encryptionScheme": padding});
    return key.encrypt(aesKey, "base64", "utf8");
}

// RSA 공개키(Public Key) 조회 함수
function getPublicKey() {
    const uri       = apiHost + "/api/Auth/GetPublicKey?APIkey=" + apiKey;
    const options   = {
        json: true,
    };
    
    const response      = Request("GET", uri, options);
    const rsaPublicKey  = JSON.parse(response.getBody("utf8")).PublicKey;
    return rsaPublicKey;
}

// RSA Public Key 조회
const rsaPublicKey  = getPublicKey(apiKey);
console.log("rsaPublicKey:", rsaPublicKey);

// AES Secret Key 및 IV 생성
const aesKey        = Crypto.randomBytes(16);
const aesIv         = Buffer.from([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);

// AES Key를 RSA Public Key로 암호화
let aesCipherKey    = Buffer.alloc(0);
aesCipherKey        = rsaEncrypt(rsaPublicKey, aesKey, "pkcs1");
console.log("aesCipherKey:", aesCipherKey);

// API URL 설정
const url       = apiHost + "/api/v2.0/nhis/register";

// API 요청 파라미터 설정
const options   = {
    headers: {
        "Content-Type"          : "application/json",
        "API-KEY"               : apiKey,
        "ENC-KEY"               : aesCipherKey
    },
    
    json: {{REQ_JSON}}
};

// API 호출
const res  = Request("POST", url, options);
console.log("res:", res.getBody("utf8"));

// 바이너리 파일 저장(해당되는 경우에만)
// FS.writeFileSync("D:\\result.bin", Buffer.from(JSON.parse(res.getBody("utf-8")).Result.BinaryData, "base64"));

<?php

set_include_path(get_include_path() . PATH_SEPARATOR . '../phpseclib1.0.19');
require_once('Crypt/RSA.php');

$apiHost   = "https://dev.tilko.net";
$apiKey    = "__API_KEY__";

// AES 암호화 함수
function aesEncrypt($aesKey, $aesIv, $plainText) {
    $ret = openssl_encrypt($plainText, 'AES-128-CBC', $aesKey, OPENSSL_RAW_DATA, $aesIv);	//default padding은 PKCS7 padding
    return base64_encode($ret);
}

// RSA 공개키(Public Key) 조회 함수
function getPublicKey($apiKey) {
    global $apiHost;

$url        = $apiHost . "api/Auth/GetPublicKey?APIkey=" . $apiKey;

$curl       = curl_init();

curl_setopt_array($curl, array(
        CURLOPT_URL             => $url,
        CURLOPT_RETURNTRANSFER  => true,
        CURLOPT_CUSTOMREQUEST   => "GET",
        CURLOPT_SSL_VERIFYHOST  => 0,
        CURLOPT_SSL_VERIFYPEER  => 0
    ));

$response   = curl_exec($curl);

curl_close($curl);

return json_decode($response, true)["PublicKey"];
}

// RSA Public Key 조회
$rsaPublicKey   = getPublicKey($apiKey);
print("rsaPublicKey:" . $rsaPublicKey);

// AES Secret Key 및 IV 생성
$aesKey     = random_bytes(16);
$aesIv      = str_repeat(chr(0), 16);

// AES Key를 RSA Public Key로 암호화
$rsa            = new Crypt_RSA();
$rsa->loadKey($rsaPublicKey);
$rsa->setEncryptionMode(CRYPT_RSA_ENCRYPTION_PKCS1);

$aesCipheredKey = $rsa->encrypt($aesKey);

// API URL 설정
$url        = $apiHost . "/api/v2.0/nhis/register";

// API 요청 파라미터 설정
$headers    = array(
    "Content-Type:"             . "application/json",
    "API-Key:"                  . $apiKey,
    "ENC-Key:"                  . base64_encode($aesCipheredKey),
);

$json			= array();

// API 호출
$curl   = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL             => $url,
    CURLOPT_RETURNTRANSFER  => true,
    CURLOPT_CUSTOMREQUEST   => "POST",
    CURLOPT_POSTFIELDS      => json_encode($json),
    CURLOPT_HTTPHEADER      => $headers,
    CURLOPT_VERBOSE         => false,
    CURLOPT_SSL_VERIFYHOST  => 0,
    CURLOPT_SSL_VERIFYPEER  => 0
));

$response   = curl_exec($curl);

curl_close($curl);

print($response);

// 바이너리 파일 저장(해당되는 경우에만)
// file_put_contents("D:\\result.bin", base64_decode(json_decode($response)->Result->BinaryData));

import os, json, base64
import requests
from Crypto import PublicKey
from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_v1_5, AES

apiHost = 'https://dev.tilko.net'
apiKey  = '__API_KEY__'

# AES 암호화 함수
def aesEncrypt(key, iv, plainText):
    def pad(text):
        text_length     = len(text)
        amount_to_pad   = AES.block_size - (text_length % AES.block_size)

if amount_to_pad == 0:
            amount_to_pad = AES.block_size
            
        pad     = chr(amount_to_pad)

result  = None
        try:
            result  = text + str(pad * amount_to_pad).encode('utf-8')
        except Exception as e:
            result  = text + str(pad * amount_to_pad)

return result
    
    if type(plainText) == str:
        plainText = plainText.encode('utf-8')
    
    plainText   = pad(plainText)
    cipher      = AES.new(key, AES.MODE_CBC, iv)
    
    if(type(plainText) == bytes):
        return base64.b64encode(cipher.encrypt(plainText)).decode('utf-8')
    else:
        return base64.b64encode(cipher.encrypt(plainText.encode('utf-8'))).decode('utf-8')

# RSA 암호화 함수(RSA 공개키로 AES키 암호화)
def rsaEncrypt(publicKey, aesKey):
    rsa             = RSA.importKey(base64.b64decode(publicKey))
    cipher          = PKCS1_v1_5.new(rsa.publickey())
    aesCipherKey    = cipher.encrypt(aesKey)
    return aesCipherKey

# RSA 공개키(Public Key) 조회 함수
def getPublicKey():
    headers = {'Content-Type': 'application/json'}
    response = requests.get(apiHost + "/api/Auth/GetPublicKey?APIkey=" + apiKey, headers=headers)
    return response.json()['PublicKey']

# RSA Public Key 조회
rsaPublicKey    = getPublicKey()
print(f"rsaPublicKey: {rsaPublicKey}")

# AES Secret Key 및 IV 생성
aesKey          = os.urandom(16)
aesIv           = ('\x00' * 16).encode('utf-8')

# AES Key를 RSA Public Key로 암호화
aesCipherKey    = base64.b64encode(rsaEncrypt(rsaPublicKey, aesKey))
print(f"aesCipherKey: {aesCipherKey}")

# API URL 설정
url         = apiHost + "/api/v2.0/nhis/register";

# API 요청 파라미터 설정
options     = {
    "headers": {
        "Content-Type"          : "application/json",
        "API-KEY"               : apiKey,
        "ENC-KEY"               : aesCipherKey
    },
    "json": {{REQ_JSON}},
}

# API 호출
res         = requests.post(url, headers=options['headers'], json=options['json'])
print(f"res: {res.json()}")

# 결과 저장
with open(f"D:\\Temp\\result.txt", "w", encoding='utf-8') as f:
    f.write(res.text)

# 바이너리 파일 저장(해당되는 경우에만)
'''
with open("D:\\result.bin", "wb") as f:
    f.write(base64.b64decode(res.json()["Result"]["BinaryData"]))
'''

[공동인증용] 인증서 등록

공동인증서를 통해 국민건강보험공단에 인증서 등록을 할 수 있습니다.

API 호출 주소

▽API 기본 가이드