워터마크 검출 API 가이드

워터마크 검출은 영상의 각 프레임을 분석하여 원본 워터마크 패턴을 감지하고 삽입 시 사용한 비밀 키로 데이터를 해독합니다. 검출 과정을 통해 워터마크 페이로드를 찾아내면, 세션 데이터베이스에서 해당 페이로드를 키 값으로 하는 세션 정보를 찾아 검출 결과로 리포트합니다.

sequenceDiagram
    participant A as 서비스 사이트
    participant B as PallyCon 서비스
    A ->> B: 유출 의심 영상
    Note right of B: 워터마크(페이로드) 검출
    B -->> B: 영상 프레임 분석
    opt 워터마크 검출 시
    Note right of B: 워터마크 세션 데이터베이스
    B -->> B: 해당 세션 정보 검색
    end
    B ->> A: 검출 결과 리포트

워터마크 검출 요구사항

워터마크 검출을 위해서는 최소 5분 이상의 연속된 녹화 영상이 필요합니다. PallyCon 포렌식 워터마크 제품은 리사이징을 비롯한 각종 공격에 대한 강인성을 가지고 있지만, 실제 워터마크의 검출율은 검출에 사용되는 영상의 화질(해상도, 비트레이트, 흔들림 등)에 따라 달라질 수 있습니다. 검출에 필요한 최소 사양은 480p 1Mbps 이상이며, 일반적으로 720p 이상의 영상에 대해서는 대부분 검출이 가능합니다.

워터마크 검출에 필요한 상세 요구 사항은 다음과 같습니다.

항목 내용
최소 영상 길이 워터마크 검출을 위해서는 최소 5분 이상 길이의 구간 반복 없이 연속된 녹화 영상이 필요
검출 영상 화질 검출을 위해서는 최소 480p 1Mbps 이상 화질 필요. 720p 이상의 화질 권장
영상 안정성 흔들림 없이 고정된 녹화 영상 필요. 핸드헬드 카메라 또는 스마트폰으로 촬영되어 화면이 흔들리는 경우 검출 불가
버퍼링 또는 화면 멈춤 최소 5분 이상 버퍼링이나 화면 멈춤 현상 없이 정상 재생된 구간이 있어야 함

PallyCon HTTP API 규격

PallyCon 서비스에서 사용하는 각종 HTTP API 요청시 아래 규격을 따릅니다.

API 요청 규격에 대한 샘플 코드는 샘플 다운로드 페이지에서 확인하시기 바랍니다.

요청 규격

Name Value
pallycon-apidata base64 Encoding ( JSON string )

요청 데이터 JSON 형식

{
    "data":"{각 API 별 `API data` JSON 값을 aes256 cbc 암호화한 base64 문자열}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{아래 'SHA256 입력 형식'의 문자열 값을 sha256 해시 처리한 base64 문자열}"
}

요청 데이터 명세

Name
Value
Required
Description
data String Y 각 API마다 정의된 규격으로 생성한 JSON 문자열을 AES 암호화하고, 결과값을 base64 문자열로 입력
timestamp String Y GMT 시간대 기준으로 요청 시점의 시간을 “yyyy-mm-ddThh:mm:ssZ” 형식으로 입력
hash String Y 아래 규격에 따라 생성한 해시값을 입력

AES256 암호화

AES256 암호화는 PallyCon Cloud 서비스 사이트 생성 시 발급 되는 Site 키 값을 이용하여 아래와 같이 처리 합니다. ( PallyCon 콘솔 사이트에서 확인 )

  • Mode : CBC
  • AES key : 32 byte (PallyCon 콘솔 사이트에서 발급 되는 site key)
  • AES IV : fixed 16 byte (0123456789abcdef)
  • Padding : pkcs7

SHA256 입력 형식

SHA256 해시의 입력값은 다음과 같은 문자열을 조합해 입력합니다.

[site access key] + [site_id] + [json.data] + [json.timestamp]
  • site access key: PallyCon Cloud 서비스 사이트 생성 시 발급 되는 access key 값이며 PallyCon 콘솔 사이트에서 확인 가능합니다.
  • sha256 해시 함수의 결과 값은 문자열로 변환하지 않고 바이너리 데이터 형태 그대로 base64 함수에 입력되어야 합니다.

검출 요청 등록 API

유출이 의심되는 영상에 대해 워터마크 검출을 요청하는 API 입니다.

API 데이터 JSON 형식

{
    "title": "title"
    "file_path": "aaa.mp4"
}

API 데이터 규격

Key type required description
title String Y 콘텐츠 타이틀
file_path String Y 검출 대상 파일의 다운로드 링크

응답 데이터 JSON 형식

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "detection_id": "detection id",
}

응답 데이터 규격

Key type description
error_code String 0000 : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
detection_id Number 해당 검출 요청에 대해 서버에서 자동 생성한 일련번호

검출 결과 조회

등록된 검출 요청 항목들과 각각의 진행 상황, 검출 결과를 조회하는 API입니다.

API 데이터 JSON 형식

{
    "search_keyword": "{search keyword}",
    "search_condition": "{search condition}",
    "detect_status": "FD001",
    "service_code": "PD002",
    "from": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "to": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "page_unit": "{long value}",
    "page_index": "{long value}",
    "time_zone": "{hh:mm}"
}

API 데이터 규격

Key type required description
search_keyword String N 검색어
search_condition String N 검색타입(콘텐츠 제목, 검출 ID). 기본값: 제목
detect_status String N 검출 상태값(FD001 ~ FD005)
service_code String N 서비스코드(PD001~)
from String N 등록 날짜 검색 조건
to String N 등록 날짜 검색 조건
page_unit Int N 검색 갯수. 기본값 : 25
page_index Int N 검색 페이지. 기본값 : 1
time_zone String N 검색 기준 시간대

응답 데이터 JSON 형식

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "total_count": "total count",
    "time_zone": "{hh:mm}",
    "data": [{
        "detection_id" : {detection id},
        "vendor_id" : "{site id}",
        "title": "{title}",
        "detect_status" : "{detect status}",
        "file_id" : "{file_id}",
        "service_code": "{service code}",
        "fwm_key": "{fwm key}",
        "fwm_data": "{fwm data}",
        "reg_date" : "{register date}",
     }]
}

응답 데이터 규격

Key type description
error_code String 0000 : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
data.detection_id Number 검출 ID
data.vendor_id String 고객사 Site ID
data.title String 콘텐츠 제목
data.detect_status String 검출 상태값(FD001 ~ FD005)
data.file_id Number Anti Piracy 에서 검출 요청 시 테이크다운 ID, 포렌식 워터마킹에서 요청한 경우에는 파일 ID
data.service_code String 제품 코드
data.fwm_key String 해당 사이트의 FWM 인증키
data.fwm_data String 세션 매니저를 통해 설정한 워터마크 정보
data.reg_date String 등록 날짜
이전