マニュアル - NAVER CLOUD PLATFORM

NAVERクラウドプラットフォームAPI利用開始ガイドの概要

詳しい内容はNAVERクラウドプラットフォームFile Safer API referenceをご参考ください。

API利用開始ガイドは簡単なシナリオを利用してファイルの悪意の有無を検知する内容を含めており、該当のシナリオに従ってやっていけば、NAVERクラウドプラットフォームFile Safer APIの使用方法を習うことができます。

File Safer API(Published API)の利用

利用開始の前に、File SaferのAPIはAPI Gateway経由で提供されるので、API Gateway利用の申込みおよびAPI Keyが必要です。

次のガイドを参照し、API Gateway利用の申込みを行います。

API Gateway

API GatewayのAPI Keysメニューに移動し、API Keyを作成します。

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はNAVERクラウドプラットフォームで使用する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

④ 認証値を作成

NAVERクラウドプラットフォームAPIで必要なIAM認証値を作成します。

NAVERクラウドプラットフォームポータル > マイページ > 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はNAVERクラウドプラットフォームで使用する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の容量制限があります。

② 認証値を作成

NAVERクラウドプラットフォームAPIで必要なIAM認証値を作成します。

詳しい内容は次をご参考ください。

作成された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をサポートします。)

② 認証値を作成

NAVERクラウドプラットフォーム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’を確認した後、運用中のシステムで削除または安全に隔離します。

ご参考

本商品はグローバルリージョンサービスとしても提供されます。

ポータルのショートカット  NAVERクラウドプラットフォームのマニュアル

NAVERクラウドプラットフォームAPI利用開始ガイドの概要

File Safer API(Published API)の利用

怪しいファイルのHash値を確認して遮断

シナリオ

シナリオ実行

怪しいファイルを転送して悪意の有無を確認

シナリオ

ファイルの検査をリクエスト

検査結果を確認

シナリオの実行

ファイルの検査をリクエスト

検査結果を確認

ご参考

関連情報のご確認

に対する検索結果は～件です。 ""

に対する検索結果がありません。 ""

処理中...

サイト情報