3. 피해사례 검색 (암호화)

더치트에 등록된 금융사기 피해 정보 중 최근 3개월 내 1건 이상 등록된 연락처, 계좌번호를 조회할 수 있습니다.

보안 강화를 위해 검색 키워드를 ENC Key로 암호화하여 전송합니다.

3.1. API 기본 정보

메서드	요청 URL	출력 포맷
POST	https://api.thecheat.co.kr/api/v2/fraud/search/encrypted	JSON

3.2. 요청 변수

변수명	타입	내용	필수	비고
keyword	string	암호화된 검색 키워드 (연락처 또는 계좌번호)	O	ENC Key로 암호화 암호화 전 keyword는 숫자만 포함하도록 전달해 주세요. (하이픈(-), 공백 등은 제거 후 암호화)
keyword_type	string	검색 키워드 유형. - 연락처 검색 시: phone - 계좌번호 검색 시: account	O	소문자
bank_code	string	금융기관 공동코드, 계좌번호 검색 시 보조 정보로 사용	X	세자리 숫자
add_info	string	게시물의 URL 등 상호협의된 정보	X

# 요청 json 샘플

{
  "keyword_type": "account",
  "keyword": "암호화된 검색 키워드",
  "add_info": ""
}

• keyword 값은 AES-256-CBC 방식으로 암호화된 문자열(Base64)입니다.
• keyword_type, add_info는 평문으로 전달합니다.

info

• keyword 암호화 방법
  • 암호화 전 키워드는 숫자만 포함해야 합니다. (예: "11020123456")
  • 애플리케이션 등록 시 발급받은 ENC Key를 사용하여 AES256-CBC로 암호화합니다.
  • 암호화는 데이터의 첫 16byte에 iv 값을 포함하여 전송해야 합니다.
  • 암호화 구현은 아래의 3.3. 암호화 샘플 코드를 참조해 주세요.
• bank_code 에 사용되는 금융기관 공동코드는 아래의 페이지에서 확인 가능 합니다. (금융회사 공동코드 hwp, pdf 문서)
  • https://www.kftc.or.kr/archive/bankListByCode (대표코드 및 기관코드)
  • 반드시 대표코드를 이용하여 연동해 주세요.
• bank_code 를 전달하면 계좌번호 검색 시 계좌번호와 AND 조건으로 검색이 됩니다.
• 유효하지 않은 bank_code 전달 시 (세 자리 숫자가 아닐 시) 해당 값은 무시 됩니다.

3.3. 암호화 샘플 코드

3.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;
import java.security.SecureRandom;

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 encrypt(String str) throws Exception {
        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];
        SecureRandom random = new SecureRandom();
        random.nextBytes(iv);
        IvParameterSpec ivSpec = new IvParameterSpec(iv);
        
        // 암호화
        c.init(Cipher.ENCRYPT_MODE, secureKey, ivSpec);
        byte[] encrypted = c.doFinal(str.getBytes(StandardCharsets.UTF_8));
        
        // iv + 암호화된 데이터 결합
        byte[] combined = new byte[blockSize + encrypted.length];
        System.arraycopy(iv, 0, combined, 0, blockSize);
        System.arraycopy(encrypted, 0, combined, blockSize, encrypted.length);
        
        return new String(Base64.encodeBase64(combined));
    }
}

3.3.2. PHP

<?php

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

    /**
     * @param string $text 암호화 할 평문
     * @param string $key 암호화 키
     * @return string|false
     */
    public static function encrypt($text, $key)
    {
        $ivSize = openssl_cipher_iv_length(self::CIPHER);
        $iv = openssl_random_pseudo_bytes($ivSize);
        
        $cipherText = openssl_encrypt($text, self::CIPHER, $key, OPENSSL_RAW_DATA, $iv);
        if ($cipherText === false) {
            return false;
        }
        
        // iv + 암호화된 데이터 결합 후 base64 인코딩
        return base64_encode($iv . $cipherText);
    }
}

info

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

3.3.3. Javascript (Node.js)

const crypto = require("crypto");

module.exports = {
  
    /**
     * AES256 암호화 함수
     * @param text 암호화 할 평문
     * @param key 암호화 키
     * @returns
     */
    encrypt: function (text, key) {
        const iv = crypto.randomBytes(16);
        const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
        
        let encrypted = cipher.update(text, "utf-8", "base64");
        encrypted += cipher.final("base64");
        
        // iv와 암호화된 데이터를 결합
        const combined = Buffer.concat([
            iv,
            Buffer.from(encrypted, "base64")
        ]);
        
        return combined.toString("base64");
    },
};

3.3.4. Python

from Cryptodome.Random import get_random_bytes
from Cryptodome.Cipher import AES
import base64

def encrypt(text, key):
    key = key.encode("utf-8")
    text = _pad(text)

    iv = get_random_bytes(AES.block_size)
    cipher = AES.new(key, AES.MODE_CBC, iv)
    encrypted = cipher.encrypt(text.encode("utf-8"))

    return base64.b64encode(iv + encrypted).decode("utf-8")



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


def _pad(s):
    block_size = AES.block_size
    padding = block_size - len(s) % block_size
    return s + chr(padding) * padding

info

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

3.4. 출력 결과

필드	타입	설명
result_code	int	결과 코드 (1: 성공, 그 외: 실패)
result_msg	string	결과 메시지
content	string	content는 암호화 되어 있습니다. 복호화 시 아래의 필드 들을 가진 JSON 문자열이 나타납니다.
keyword	string	검색한 키워드 (복호화된 값)
keyword_type	string	검색한 키워드 타입 (phone 또는 account)
bank_code	string	검색한 금융기관 공동 코드
caution	string	피해사례 등록 여부 (Y, N)
add_info	string	부가 정보, 검색 시 제공된 값 (게시물의 URL 등 상호 협의된 정보)
date_start	string	검색기간의 시작일시 (yyyyMMddHHmmss)
date_end	string	검색기간의 종료일시 (yyyyMMddHHmmss)
keyword_url	string	피해사례 열람용 URL

# 응답 json 샘플
{
    "result_code": 1,
    "result_msg": "success",
    "content": "암호화된 데이터"
}

# content 복호화 값 샘플
{
    "keyword": "11020123456",
    "keyword_type": "account",
    "bank_code": "",
    "caution": "N",
    "date_start": "20211026154116",
    "date_end": "20220126154116",
    "keyword_url": "https://api.thecheat.co.kr/web/redirect.php?keyword=efb70607704f12aeeda8c9eb535f77051329fc07c0c7b8d9b83297f7c44e880ff0709011f83ea9e42fd463a3f241f9784d326e8ae5c15534fbe87a40f5c275f8d2ee391edced04d64e2aa38d49ef586e&enc=1",
    "add_info": null
}

3.5. 에러코드

HTTP 코드	에러 코드	에러 메시지	조치 방안
500	-1	Sorry. An internal error has occurred (시스템 에러)	서버 내부 에러가 발생하였습니다. 연락 주시면 신속히 조치하겠습니다.
401	-2	Invalid API Key.	API Key 값이 전달되지 않았거나, API Key값이 유효하지 않습니다.
400	-3	Invalid attempt. (잘못된 요청, 요청 변수의 종류에 따라 메시지가 바뀔 수 있음.) Failed to decrypt keyword.	필수 요청 변수가 정확한지 확인하거나, keyword 복호화 실패 시 암호화가 올바르게 되었는지 확인 바랍니다.
403	-4	Access is not allowed. IP DENY. (허용되지 않은 IP 접근)	더치트 API센터에서 허용 IP 목록을 확인 해 주세요.

3.6. 테스트

제휴 계약이 되지 않은 애플리케이션에서 요청 시 더치트 피해사례 데이터베이스가 아닌 테스트 데이터베이스에서 조회된 값이 반환 됩니다.

제휴가 되지 않은 상태에서는 아래와 같이 result_msg 값이 success (test) 로 반환 됩니다.

# 테스트 응답 json 샘플
{
    "result_code": 1,
    "result_msg": "success (test)",
    "content": "암호화된 데이터"
}

또한 테스트 데이터베이스는 아래의 휴대폰 번호, 계좌번호가 등록되어 있습니다. 해당 번호를 암호화하여 검색하시면 등록여부 "Y" 결과 값을 받아 볼 수 있습니다.

• 휴대폰번호: 01044440000
• 계좌번호: 12010123456

info

API 센터를 통해 고객이 직접 테스트 데이터베이스에 값을 삽입할 수 있도록 기능 개발 중입니다.

고객이 등록하는 테스트 값은 다른 고객사와 공유되지 않습니다.