워터마크 검출 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 함수에 입력되어야 합니다.

Url을 이용한 검출 요청 등록 API

유출이 의심되는 영상에 대해 url을 이용하여 워터마크 검출을 요청하는 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 해당 검출 요청에 대해 서버에서 자동 생성한 일련번호

파일 업로드로 검출 요청을 하기 위한 signed url 발급 API

검출 요청은 직접 파일을 업로드하여 요청할 수도 있습니다. 파일 업로드하기 위한 AWS S3 signed url을 발급하는 api 입니다. 발급받은 url로 파일 업로드 시 검출 요청이 진행 됩니다.

API 데이터 JSON 형식

{
    "title": "title"
    "file_extension": "mp4",
    "service_code": "PD002",
    "demo_contents": false
}

API 데이터 규격

Key type required description
title String Y 컨텐츠 title
file_extension String Y 파일 확장자 (mp4, mkv, mov)
service_code String N 제품 코드. default: PD002
demo_contents Boolean N PallyCon demo contents 검출 요청 여부. default: false

응답 데이터 JSON 형식

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "upload_url": "upload url",
}

응답 데이터 규격

Key type description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
upload_url String 1분동안 업로드 가능한 signed url

파일 업로드 샘플 (curl)

curl -v --upload-file {filename.mp4} {signed upload url}

검출 결과 조회

등록된 검출 요청 항목들과 각각의 진행 상황, 검출 결과를 조회하는 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 등록 날짜

상태 및 에러 코드

워터마크 검출 상태 코드

상태 코드 상태
FD001 검출 작업 준비
FD002 다운로드 중
FD210 다운로드 시작됨
FD220 다운로드 완료
FD003 검출 중
FD311 자동 검출 시작됨
FD312 자동 검출 완료
FD321 수동 검출 시작됨
FD322 수동 검출 완료
FD004 작업 완료
FD400 작업 완료 (진행)
FD005 검출 취소
FD510 취소 요청 접수
FD520 검출 취소 완료
FD006 에러
FD600 에러 (진행)
FD700 검출 실패 (진행)

워터마크 검출 에러 코드

에러 코드 에러 메시지 원인 해결 방안
A4001 워터마크 정보 검색 실패  워터마크 페이로드에 해당하는 세션 정보를 데이터베이스에서 찾지 못했습니다. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4002 검출 요청 등록 실패 요청 데이터가 잘못되어 내부 서버 에러가 발생했습니다. 1. 요청 데이터의 파라미터를 확인 후 재시도합니다.
2. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4003 검출 키 정보 등록 실패 기술 지원 담당자의 수동 검출 결과 등록 과정에서 내부 에러가 발생했습니다. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4004 키 정보 검색 실패 A4001 에러와 동일한 원인 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4005 파일 경로 정보가 잘못 입력되었습니다. 검출 요청 데이터의 파일 경로가 Null이거나 빈 문자열입니다. 요청 데이터 확인 후 재시도합니다.
A4006 검출 상태 업데이트 실패 내부 서버 에러로 인해 발생합니다. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4007 워터마크 키 정보를 등록하지 못했습니다. 기술 지원 담당자의 수동 검출 결과 등록 과정에서 내부 에러가 발생했습니다. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4008 진행 상태 알림 전송 실패 사용자/관리자에게 검출 결과 메일을 보내거나, PallyCon 내부 슬랙 채널에 알림을 전송하는 과정에서 에러가 발생하였습니다. 헬프데스크 티켓으로 검출 진행 상황 정보를 요청합니다.
A4009 검출 정보 검색 실패  내부 에러로 인해 데이터베이스에서 검출 결과를 조회하지 못했습니다. 요청 데이터를 다시 확인한 후 재시도합니다. 동일 에러 발생 시 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4011 슬랙 알림 메시지 전송 실패  PallyCon 내부 슬랙 채널에 메시지를 전송하지 못했습니다. 고객사에서는 해당 에러에 대해 별도 처리가 필요 없습니다.
A4012 검출 정보 업데이트 실패 검출 과정에서 내부 서버 오류가 발생했습니다. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4013 대기열 메시지 전송 실패 내부 오류로 인해 자동 검출 과정을 시작하지 못했습니다. 헬프데스크 티켓으로 기술 지원을 요청합니다.
A4014 검출 작업 중단 실패 내부 오류로 인해 검출 작업을 중단하지 못했습니다. 요청 데이터 확인 후 다시 시도합니다. 동일 에러 발생 시 헬프데스크 티켓으로 기술 지원을 요청합니다.
WM900### FWM 패키징 작업 에러 코드와 동일
WM900901, WM900902 FWM 패키징 작업 에러 코드의 WM900903 에러와 동일

검출 실패에 대한 에러 코드

에러 코드 설명
D000 기타 에러 (검출 실패 관련 정의되지 않은 에러)
D001 파일 다운로드 실패 
D002 영상 길이가 5분 미만입니다.
D003 지원되는 코덱이 아닙니다.(H.264 또는 H.265 코덱 지원)
D004 영상 해상도가 480P 미만입니다.  
D005 영상 비트레이트가 1 Mbps 미만입니다. 
D006 과도한 저화질 영상입니다.
D007 녹화된 화면이 흔들려 워터마크 검출이 실패하였습니다. 
D008 재생 중 과도한 버퍼링이 발생합니다. 
D009 영상에 반복 재생된 구간이 있습니다.
D010 지원되는 확장자가 아닙니다. (.mp4, .mkv, .mov 지원)
D011 영상의 미디어 스펙을 추출하지 못했습니다. 
D012 잘못된 키 목록 정보가 사용되었습니다.
D013 잘못된 fwmKey 정보가 사용되었습니다. 
이전