1. API 연동 공통사항

API를 사용할 때 공통으로 적용되는 사항입니다.

1.1. API Key 전달

API를 호출할 때 HTTP Header에 애플리케이션 등록 시 발급받은 API Key를 아래의 표를 참조하여 전송해 주세요.

Header Key	Header Value
X-TheCheat-ApiKey	발급 받은 API Key

1.2. 응답 복호화

정상적으로 API가 호출되면 응답은 다음과 같은 JSON 형태로 전송됩니다.

{
    "result_code": 1,
    "message": "success",
    "content": "암호화 된 데이터"
}

content 에는 응답 결과로 전달 될 데이터들이 들어있고, 애플리케이션 등록 시 발급받은 ENC Key를 이용하여 암호화가 되어 있습니다. 복호화 시 데이터는JSON 형태로 나타나게 됩니다.

info

content는 AES256-CBC 로 암호화 되어 있습니다.
데이터의 첫 16byte는 iv 값이며, 이후의 값은 실제 암호화 된 데이터 입니다.

복호화 구현은 1.3.1의 샘플코드를 참조해 주세요.

1.2.1. 응답 및 복호화 예시

• 예시에 사용한 암호화 키(ENC Key)
  • xsQ0G6*HkLBIRYrJXZiInmzPnFubT1YW
• 응답 예시

{
  "result_code": 1,
  "result_msg": "success (test)",
  "content": "LMCZljdon7VPY/pKuRH9s/qSoDlT+eS4v7hhhg+c7ZS9w4ZD4lrr3/TsPKP3hspN7n/pmepzT/Cc1KR5mLW5jij8XyD/MMyFxt0kmmxDnq1ihKSCnu64k6lWXjRJmToN9oZFLWr7gU8FykG3B80ov6k9zIlRDeueT9/LNBCcTJjXOIGNq2LgZmAAPBnj0YjcRyPN9g1HjFqW3p7/JcB9UETFPQRAGBuTCUbG7RTb8XBOJq6m5U93xYeRkdq1NQRc62H/dAORibaGQE0qQIezTtvKfJdWt7qjJW3ZygHVxlyJQ68njKuGp4yiGqvwy0Mfq9y98OHZMUV1r/2heET0yg2Pj5Cysn6cTN7+Xr7VmSv6ZFONeZ+6bRYahCvSEf5iSfWORCzXAH8xBBH5mlCuwkcUNyFg/Hl5/Pmk+iAuWlqcCc4eocqmpsTmsQm38gBhJU/jNB7INEeRAlKaxgYqzqHg+fph+P+rYtr1HmrCtNBlKEfJ5Jp3WOPTfoQM0Ig/bv4s+rcCH40iosNDV3RB2njOXBHO1rchETh7V7nnc5o04e8FJfftEr1ymh9C2Q8iKf8RKiR48cC8c4r44tPNRw=="
}

• 예시의 content 값 복호화 결과

{
  "keyword": "1001012341234",
  "keyword_type": "account",
  "bank_code": "",
  "caution": "N",
  "date_start": "20240301122324",
  "date_end": "20240530122324",
  "keyword_url": "https://api.thecheat.co.kr/web/redirect_test_result?keyword=74c19d18cd7f357745a0557f3696a73c81bfc9feb796a1c57731034148f9747a9c3114392b7aab7c53ea14a91828e30e96d83c169999f0b3da31755b5966c06af26405da1dd1b1afbbdc979cbbe4b899d63d98a2f10e495a&enc=1",
  "add_info": null
}

1.3. 응답 복호화 샘플 코드

1.3.1 Java

import org.apache.commons.codec.binary.Base64;

import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class AES256Cipher {
	private static final String ALG = "AES/CBC/PKCS5Padding";
	private static final String KEY_ALG = "AES";
	private final String key;
    
	public AES256Cipher(String key) {
		this.key = key;
	}
    
	public String decrypt(String str) throws Exception {
		byte[] byteStr = Base64.decodeBase64(str.getBytes());
		byte[] keyData = key.getBytes();
		SecretKey secureKey = new SecretKeySpec(keyData, KEY_ALG);
		Cipher c = Cipher.getInstance(ALG);
		int blockSize = c.getBlockSize();
		// iv 값 가져오기
		byte[] iv = new byte[blockSize];
		System.arraycopy(byteStr, 0, iv, 0, blockSize);
		IvParameterSpec ivSpec = new IvParameterSpec(iv, 0, blockSize);
		// 암호화 된 데이터 가져오기
		int encryptedSize = byteStr.length - blockSize;
		byte[] encryptedBytes = new byte[encryptedSize];
		System.arraycopy(byteStr, blockSize, encryptedBytes, 0, encryptedSize);
		byteStr = encryptedBytes;
		c.init(Cipher.DECRYPT_MODE, secureKey, ivSpec);
		return new String(c.doFinal(byteStr), StandardCharsets.UTF_8);
	}
}

1.3.2. PHP

<?php

class Aes256Cipher
{
    const CIPHER = 'AES-256-CBC';

    /**
     * @param string $text 암호화 된 값
     * @param string $key 암호화 키
     * @return string|false
     */
    public static function decrypt($text, $key)
    {
        $decode = base64_decode($text);
        if ($decode === false) {
            return false;
        }
        $ivSize = openssl_cipher_iv_length(Aes256Cipher::CIPHER);
        $iv = mb_substr($decode, 0, $ivSize, '8bit');
        $cipherText = mb_substr($decode, $ivSize, mb_strlen($decode, '8bit'), '8bit');

        $plainText = openssl_decrypt($cipherText, self::CIPHER, $key, OPENSSL_RAW_DATA, $iv);
        if ($plainText === false) {
            return false;
        }
        return trim($plainText);
    }
}

info

PHP 샘플코드 사용 시 php.ini에 mbstring, openssl 모듈을 추가해야 합니다.

1.3.3. Javascript (Node.js)

const crypto = require("crypto");

module.exports = {
  
     /**
     * AES256 복호화 함수
     * @param text 암호화 된 값
     * @param key 암호화 키
     * @returns
     */
    decrypt: function (text, key) {
        const buf = Buffer.from(text, "base64");
        const iv = buf.slice(0, 16);
        const data = buf.toString("base64", 16);

        const decipher = crypto.createDecipheriv("aes-256-cbc", key, iv);
        const decryptedText = Buffer.concat([
            decipher.update(data, "base64"),
            decipher.final(),
        ]).toString("utf-8");
    
        return decryptedText;
    },
};

1.3.4. Python

import base64

from Cryptodome.Cipher import AES


def decrypt(text, key):
    key = key.encode('utf-8')
    key = str_to_bytes(key)
    decode = base64.b64decode(text)
    iv = decode[:AES.block_size]
    crypto = AES.new(key, AES.MODE_CBC, iv)
    dec = crypto.decrypt(decode[AES.block_size:]).decode('utf-8')
    return _unpad(dec)


def str_to_bytes(data):
    u_type = type(b''.decode('utf8'))
    if isinstance(data, u_type):
        return data.encode('utf8')
    return data


def _unpad(s):
    return s[:-ord(s[len(s)-1:])]

info

python 샘플코드 사용 시 pycryptodomex 모듈을 추가해야 합니다.