워터마크 검출 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 입니다.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/url
- method : POST
- content type : application/json;charset=UTF-8
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로 파일 업로드 시 검출 요청이 진행 됩니다.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/token
- method : POST
- content type : application/json;charset=UTF-8
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입니다.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/list
- method : GET
- content type : application/json;charset=UTF-8
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 정보가 사용되었습니다. |