네이버 클라우드 플랫폼 API 시작 가이드 개요

자세한 내용은 네이버 클라우드 플랫폼 File Safer API reference를 참고하시기 바랍니다.

API 시작 가이드에서는 간단한 시나리오를 통해 파일의 악성여부를 탐지하는 내용을 포함하고 있으며, 해당 시나리오를 따라 해 봄으로써 네이버 클라우드 플랫폼 File Safer API 사용법을 익힐 수 있습니다.

File Safer API(Published API) 이용하기

시작하기에 앞서, File Safer의 API는 API Gateway를 통해 제공되므로 API Gateway의 이용 신청 및 API Key가 필요합니다.

아래의 가이드를 참조하여 API Gateway의 이용을 신청합니다.

API Gateway의 API Keys 메뉴로 이동하여 API Key를 생성합니다.

생성된 API Key를 이용하여 File Safer의 API를 이용하게 되며, API에 대한 설명은 문서 하단의 연관정보인 File Safer API 사용 가이드 및 API reference 내용을 참고하시기 바랍니다.

File Safer의 API의 Subscription Type은 공개-자율구독(Public)이므로 별도의 구독과정없이 생성하신 API Key를 이용하여 사용 가능합니다.

의심파일 Hash 값 확인하여 차단하기

사용자로부터 업로드/다운로드되는 파일의 Hash 값을 추출하여 악성여부를 확인하고 이를 차단하는 과정을 시나리오로 알아 보겠습니다.

Hash 값을 이용하여 악성여부를 확인하는 기능은 File Safer의 Hash Filter에서 제공하는 API를 이용하며, 해당 API는 네이버 클라우드 플랫폼에서 사용하는 IAM인증 및 API Gateway를 통해 사용하실 수 있습니다.

아래의 시나리오에 따라 인증 값을 생성하고 필요한 액션 파라미터를 추가하여 API를 호출 합니다.

시나리오

시나리오는 아래의 순서로 진행됩니다.

① 악성코드로 의심되는 파일을 구분

② 구분된 파일의 Hash 값 추출

③ Hash 값을 포함하여 액션 파라미터 값 추가

④ 인증 값 생성

⑤ API 요청

⑥ 응답 값 확인 및 차단 여부 판단

시나리오 수행

시나리오 순서에 따라 아래와 같이 수행합니다.

① 악성코드로 의심되는 파일을 구분

새로이 업로드되거나 사용자가 다운로드하려는 파일 등 악성 부의 확인이 필요한 파일을 구분 합니다.

② 구분된 파일의 Hash 값 추출

악성여부를 확인하려는 파일의 Hash 값을 추출 합니다.

아래는 Hash 값을 추출하는 java sample code이며, 추출된 Hash 값은 아래와 같이 표기 합니다. (현재는 SHA-1과 MD5를 지원하며, SHA-1의 사용을 권고 드립니다.)

  • SHA-1: 16진수 40bytes String으로 표기 합니다. (ex 3ec625cb2277d7334406ab712b69c4ceaf38bd82)
  • MD5: 16진수 32bytes String으로 표기 합니다. (ex. 8072fd6da170738c905cf362f787442b)
public static String getHash(String filename, String algorithm) throws Exception
{
    MessageDigest md = MessageDigest.getInstance(algorithm);

    // file hashing with DigestInputStream
    DigestInputStream dis = new DigestInputStream(new FileInputStream(new File(filename)), md);

    // empty loop to clear the data
    while(dis.read() != -1);
    dis.close();

    // Get the hash's bytes
    byte[] hashBytes = md.digest();

    // bytes to hex
    StringBuffer sb = new StringBuffer();
    for(byte h : hashBytes) {
        sb.append(String.format("%02x", h));
    }

    return sb.toString();
}

public static void main(String[] args)
{
    try {
        // Get hash value of a file with SHA-1 Algorithm
        String sha1 = getHash("./test.exe", "sha-1");
        // Get hash value of a file MD5 Algorithm
        String md5 = getHash("./test.exe", "md5");
    } catch (Exception e) {
        e.printStackTrace();
    }
}

③ Hash 값을 포함하여 액션 파라미터 값 추가

추출된 Hash 값을 포함하여 API에 필요한 액션 파라미터 값들을 추가합니다.

  • hashCode: 확인하려는 Hash 값을 스트링으로 추가합니다.
  • hashType: 추가한 Hash 값의 알고리즘을 표기 합니다. (MD5 또는 SHA1)

생성된 요청 파라미터는 다음과 같습니다.

Ex. hashCode=00010efc49b7174d18400710eed1642a7d4b12db&hashType=sha1

④ 인증 값 생성

네이버 클라우드 플랫폼 API에서 필요한 IAM 인증 값을 생성합니다.

세부 내용은 아래의 내용을 참조합니다.

네이버 클라우드 플랫폼 포털 > 마이페이지 > API 인증키 관리 화면에서 Access Key, Secret Key를 발급받고 진행한 후 Signature를 생성합니다. (개행문자는 \n을 사용합니다.)

생성된 Signature 값은 API 호출 시 x-ncp-apigw-signature-v2로 사용됩니다.

⑤ API 요청

Hash Filter에서 제공하는 URI로 생성한 인증 + 액션 파라미터를 이용하여 요청 합니다.

private static void main(String[] args) throws Exception
{
    String apiKey = "AAAAAAAAAA"; // api key (from api gateway portal)
    String accessKey = "AAAAAAAAAAAAAAAAAAAA"; // access key (from portal or sub account)
    String apiDomain = "https://filesafer.apigw.ntruss.com";
    String method = "GET";
    long timestamp = System.currentTimeMillis();

    // step 2, 3: Extract hash vlaue of a identified file then add parameter value including hash value and hash type
    String param = "hashCode=" + getHash("./test.exe") + "&hashType=sha1";
    // The apiURL is the value obtained by appending parameter to the end of URI string provided by Hash Filter.
    String apiURL = "/hashfilter/v1/checkHash?" + param;

    // step 4: Create authentication value
    String signature = makeSignature(method, apiURL, timestamp);

    // step 5: Request API
    URL url = new URL(apiDomain + apiURL);
    HttpURLConnection con = (HttpURLConnection)url.openConnection();
    con.setRequestMethod(method);
    con.setRequestProperty("x-ncp-apigw-timestamp", Long.toString(timestamp));
    con.setRequestProperty("x-ncp-apigw-api-key", apiKey);
    con.setRequestProperty("x-ncp-iam-access-key", accessKey);
    con.setRequestProperty("x-ncp-apigw-signature-v2", signature);
    con.setRequestProperty("accept", "application/json");

    // step 6: Check the response value and determine whether to block
    int httpResponseCode = con.getResponseCode();
    BufferedReader br = null;
    if (httpResponseCode == 200) {
        br = new BufferedReader(new InputStreamReader(con.getInputStream()));

        String readLine;
        StringBuffer httpResponse = new StringBuffer();

        while((readLine = br.readLine())! = null) {
            httpResponse.append(readLine);
        }

        // Do next step (ex, determine whether to block)
        ...

        br.close();
    }
}

⑥ 응답 값 확인 및 차단 여부 판단

API 호출 응답 값의 hashCheckResultList의 object 값을 통해 악성 유무를 판단하여 파일을 처리합니다.

의심 파일 전송하여 악성 여부 확인하기

악성코드로 의심되는 파일을 전송하여 검사를 요청 하고, 전송한 파일의 검사 결과를 확인하여 악성여부를 구분하는 과정을 시나리오로 알아 보겠습니다.

파일을 전송하여 악성여부를 확인하는 기능은 File Safer의 File Fiter에서 제공하는 API를 이용하며, 해당 API는 네이버 클라우드 플랫폼에서 사용하는 IAM인증 및 API Gateway를 통해 사용하실 수 있습니다.

File Filter에서는 2개의 API를 제공하며 각각의 용도는 아래와 같습니다.

① 파일 검사 요청 (inputFile)

Multipart 형태로 파일을 전송하여 검사를 요청 합니다.

② 검사 결과 확인 (getInputFileLog)

검사를 요청한 파일의 Hash 값을 이용하여 검사 결과를 확인합니다.

File Filter는 악성코드로 확인되는 경우 Hash Filter로 Hash 값을 업데이트하므로, 확인이 필요한 Hash를 Hash Filter에서 조회하여도 동일한 결과를 얻을 수 있습니다.

File Filter로는 파일을 전송(inputFile)하고 확인은 Hash Filter(checkhash)로 하도록 구성하는 것이 File Safer의 특징에 좀 더 맞는 방법입니다.

시나리오

시나리오는 아래의 순서로 진행됩니다.

파일 검사 요청

① 악성코드로 의심되는 파일을 구분

② 인증 값 생성

③ 구분된 파일을 추가한 요청 생성

④ 필요한 파라미터 추가

⑤ API 요청

검사 결과 확인

① 검사 결과를 확인해야 하는 Hash 값 구분

② 인증 값 생성

③ 필요한 파라미터 추가

④ API 요청

⑤ 응답 값 확인 및 차단 여부 판단

시나리오 수행

시나리오 순서에 따라 아래와 같이 수행합니다.

파일 검사 요청

① 악성코드로 의심되는 파일을 구분

Hash Filter로 확인이 안되거나 악성여부 확인이 필요한 파일을 구분 하며, 아래의 제약이 따릅니다.

  • 파일 개수 제한: 1번의 전송에는 1개의 파일만 처리되며, 2개 이상의 파일이 전송되는 경우 전송된 파일 중 1개의 파일이 임의선택되어 처리됩니다.

  • 파일 크기 제한: 1번의 전송 시 스트림 기준으로 10MB의 용량 제한이 적용됩니다.

② 인증 값 생성

네이버 클라우드 플랫폼 API에서 필요한 IAM 인증 값을 생성합니다.

세부 내용은 아래의 내용을 참조합니다.

네이버 클라우드 플랫폼 포털 > 마이페이지 > API 인증키 관리 화면에서 Access Key, Secret Key를 발급받고 진행한 후 Signature를 생성합니다. (개행문자는 \n을 사용합니다.) 생성된 Signature 값은 API 호출 시 x-ncp-apigw-signature-v2로 사용됩니다.

③ 구분된 파일을 추가한 요청 생성

Multipart로 Body에 파일을 포함한 요청을 생성합니다.

  • Key: file
  • Value: binary

④ 필요한 파라미터 추가

전송하려는 파일이 패스워드가 설정된 압축 파일인 경우 아래의 파라미터를 요청에 추가합니다.

  • Key: archivePassword
  • Value: 압축파일 패스워드 String

파라미터가 모두 추가된 POST 요청의 Body는 아래의 형태를 가집니다.

Content-Type: multipart/form-data; boundary=----AAAAAAAAAAAAAAAAAAAAAAAAAAAAA

------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Disposition: form-data; name="file"; filename="suspicious-file.zip"
Content-Type: application/x-zip-compressed

... contents of 'suspicious-file.zip'
------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Content-Disposition: form-data; name="archivePassword"

password
------AAAAAAAAAAAAAAAAAAAAAAAAAAAAA--

⑤ API 요청

File Filter에서 제공하는 URI로 생성한 요청을 전송합니다.

public static void callInputFileAPI(String fileName, String password)
{
    String APIKEY = "AAAAAAAAAA"; // api key (from api gateway portal)
    String ACCESSKEY = "AAAAAAAAAAAAAAAAAAAA"; // access key (from portal or sub account)

    String apiDomain = "https://filesafer.apigw.ntruss.com";
    String apiURL = "/filefilter/v1/inputFile";
    String method = "POST";
    String boundary = "----AAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
    String crlf = "\r\n";
    String twoHyphens = "--";

    long timestamp = System.currentTimeMillis();

    // step 2: Create Authentication Value
    String signature = makeSignature(method, apiURL, timestamp);

    // step 5: Request API
    URL url = new URL(apiDomain + apiURL);
    HttpURLConnection con = (HttpURLConnection)url.openConnection();
    con.setDoOutput(true);
    con.setRequestMethod(method);
    con.setRequestProperty("x-ncp-apigw-timestamp", Long.toString(timestamp));
    con.setRequestProperty("x-ncp-apigw-api-key", APIKEY);
    con.setRequestProperty("x-ncp-iam-access-key", ACCESSKEY);
    con.setRequestProperty("x-ncp-apigw-signature-v2", signature);
    con.setRequestProperty("accept", "application/json");
    con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);

    try {
            // step 3: Create request with the identified file added
        DataOutputStream dos = new DataOutputStream(con.getOutputStream());

        // start of request body
        dos.writeBytes(twoHyphens + boundary + crlf);
        dos.writeBytes("Content-Disposition: form-data; name=\"file\"; filename=\"" + fileName + "\"" + crlf);
        dos.writeBytes("Content-Type: "+ URLConnection.guessContentTypeFromName(fileName) + crlf);
        dos.writeBytes(crlf);

        FileInputStream inputStream = new FileInputStream(fileName);
        byte[] buffer = new byte[4096];
        int bytesRead = -1;
        while ((bytesRead = inputStream.read(buffer)) != -1) {
            dos.write(buffer, 0, bytesRead-1);
        }
        dos.writeBytes(crlf);
        inputStream.close();

        // step 4: If the file you want to transfer is a zip file with a password, add the following parameters to the request
        if(password != null && !password.isEmpty()) {
            dos.writeBytes(twoHyphens + boundary + crlf);
            dos.writeBytes("Content-Disposition: form-data; name=\"archivePassword\"" + crlf);
            dos.writeBytes(crlf);
            dos.writeBytes(password + crlf);
        }

        // end of request body
        dos.writeBytes(crlf);
        dos.writeBytes(twoHyphens + boundary + twoHyphens + crlf);
        dos.flush();

        // Check the response value
        int responseCode = con.getResponseCode();
        BufferedReader br = null;
        if(responseCode == 200) {
            br = new BufferedReader(new InputStreamReader(con.getInputStream()));

            String inputLine;
            StringBuffer response = new StringBuffer();

            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }

            // do next step (ex, check to transfer succeeded)
            ...

            br.close();
        }

    } catch (Exception e) {
        e.printStackTrace();
    }
}

public static void main(String[] args)
{
    callInputFileAPI("/test.zip", "test1234"); // If a zip file has a password
    callInputFileAPI("/test.zip", null); // If a zip file hasn't a password
    callInputFileAPI("/text.exe", null);
}

검사 결과 확인

① 검사 결과를 확인해야 하는 Hash 값 구분

File Filter에 검사를 요청했던 파일의 Hash 값을 구분 합니다. (MD5, SHA-1을 지원 합니다.)

② 인증 값 생성

네이버 클라우드 플랫폼 API에서 필요한 IAM 인증 값을 생성합니다.

인증 값 생성 설명은 “파일 검사 요청”의 내용을 참조합니다.

③ 필요한 파라미터 추가

결과 확인에 필요한 조건을 json 포맷으로 생성하여 추가하며, 필수 파라미터는 아래와 같습니다.

  • hash: 확인하려는 Hash 값을 스트링으로 추가합니다.

  • hashType: 추가한 Hash 값의 알고리즘을 표기 합니다. (MD5, SHA1)

파라미터가 추가된 POST 요청의 Body의 예제는 아래와 같습니다.

{
    "hash":"a7bbc4b4f781e04214ecebe69a766c76681aa7eb",
    "hashType":"sha1"
}

④ API 요청

File Filter에서 제공하는 URI로 생성한 요청을 전송합니다.

public static void main(String[] args)
{
    String apiKey = "AAAAAAAAAA"; // api key (from api gateway portal)
    String accessKey = "AAAAAAAAAAAAAAAAAAAA"; // access key (from portal or sub account)
    String apiDomain = "https://filesafer.apigw.ntruss.com";
    String method = "POST";
    String apiURL = "/filefilter/v1/getInputFileLog";

    long timestamp = System.currentTimeMillis();

    // step 2: Create Authentication Value
    String signature = makeSignature(method, apiURL, timestamp);

        // step 4: Request API
    URL url = new URL(apiDomain + apiURL);
    HttpURLConnection con = (HttpURLConnection)url.openConnection();
    con.setDoOutput(true);
    con.setRequestMethod(method);
    con.setRequestProperty("x-ncp-apigw-timestamp", Long.toString(timestamp));
    con.setRequestProperty("x-ncp-apigw-api-key", APIKEY);
    con.setRequestProperty("x-ncp-iam-access-key", ACCESSKEY);
    con.setRequestProperty("x-ncp-apigw-signature-v2", signature);
    con.setRequestProperty("Content-Type", "application/json");
    con.setRequestProperty("accept", "application/json");

    // step3: Add required parameters with json format
    DataOutputStream dos = new DataOutputStream(con.getOutputStream());

    dos.writeBytes("{\r\n");
    dos.writeBytes("    \"hash\": \"f093e7767bb63ac973b697d3fd1d40a78b87b8bf\",\r\n");
    dos.writeBytes("    \"hashType\": \"sha1\"\r\n");
    dos.writeBytes("}");

    // step5: Check the response value and determine whether to block
    int responseCode = con.getResponseCode();
    BufferedReader br = null;
    if(responseCode == 200) {
        br = new BufferedReader(new InputStreamReader(con.getInputStream()));

        String inputLine;
        StringBuffer response = new StringBuffer();
        while ((inputLine = br.readLine()) != null) {
            response.append(inputLine);
        }

        // do next step (ex, determine whether to block)
        ...

        br.close();
    }
}

⑤ 응답 값 확인 및 차단 여부 판단

File Filter의 결과 값에 따라서, 차단 또는 허용여부를 판단하고 진행합니다.

응답 값은 json 포맷이며, inputFileLogList의 리스트의 개수가 0일 경우는 확인한 Hash의 파일의 결과가 없는 경우입니다. 반면, 리스트의 개수가 2개 이상일 경우 2번 이상 분석이 된 경우이며 ‘analysisResultCode’를 확인 후 운영 하시는 시스템에서 삭제 또는 안전하게 격리를 수행합니다.

참고 사항

본 상품은 글로벌 리전 서비스로도 제공됩니다.

연관 정보 바로가기

아래 가이드에서 연관 정보를 확인할 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...