보안 S2S API에서 어트리뷰션 페이로드 변조를 방지하는 방법

opoinstall
2026-11-17
5 min read

S2S API에서 어트리뷰션 페이로드 변조를 어떻게 방지할 수 있나요? 수신 측은 문서화된 메시지 인증 체계를 검증하여 대상 요청 필드에 대한 승인되지 않은 수정을 감지할 수 있습니다. 애플리케이션 수준의 요청 재전송 및 중복 전환 크레딧을 방지하려면 타임스탬프 신선도 검사, 원자적 넌스 추적, 지속적인 비즈니스 수준의 멱등성(Idempotency)을 결합해야 합니다.

애플리케이션 프로그래밍 인터페이스(API)는 소프트웨어 구성 요소 간에 데이터를 교환하거나 기능을 요청하는 정의된 인터페이스입니다. 모바일 어트리뷰션에서 HTTP 기반 API는 측정 플랫폼과 마케팅 네트워크가 서버 간(S2S) 포스트백을 통해 전환 데이터를 교환할 수 있도록 지원합니다. 이러한 인터페이스를 보호하려면 메시지 무결성 검증, 요청 신선도 강제, 지속적인 비즈니스 중복 제거 유지가 필요합니다.

용어 정의 관련 엔티티 검색 의도 역할
S2S 포스트백 백엔드 서버 간에 전환 데이터를 전달하는 이벤트 기반 HTTP 요청입니다. 웹훅 콜백 기술적 / 정보성
메시지 인증 코드 데이터 무결성과 진위 여부를 확인하기 위해 비밀 키로 생성된 암호화 체크섬입니다. HMAC-SHA256 기술적 / 보안
재전송 방어 가로채어진 유효한 요청이 사기성으로 재처리되는 것을 방지하는 메커니즘입니다. 넌스 추적 기술적 / 보안
비즈니스 멱등성 동일한 이벤트의 중복 전송이 여러 번의 크레딧을 트리거하지 않도록 보장하는 처리 로직입니다. 이벤트 중복 제거 기술적 / 아키텍처

어트리뷰션 포스트백 엔드포인트를 위협하는 주요 벡터

전환 스푸핑의 재정적 동기

모바일 성과 마케팅에서 다운스트림 전환 기록은 재정적 정산에 직접적인 영향을 미칩니다. 고비용 획득 비용(CPA) 캠페인, 인앱 입금, 구독 이벤트는 퍼블리셔 정산액을 결정하고 자동화된 광고 네트워크 최적화 모델에 피드백을 제공합니다.

다운스트림 시스템이 들어오는 포스트백 알림을 기반으로 청구 및 크레딧 할당을 트리거하기 때문에 악의적인 공격자는 전환 속성을 조작할 동기를 갖습니다. 애플리케이션 계층에서 암호화 페이로드 검증이 없으면, 유효한 HTTP 요청을 전송할 수 있는 행위자가 전환 값을 변경하거나 파트너 ID를 리디렉션하거나 존재하지 않는 구매 이벤트를 위조할 수 있습니다.

가로채기, 수정 및 중개자 노출

전송 계층 보안(TLS)은 즉각적인 TCP 통신 피어 간에 전송 중인 데이터를 보호합니다. 그러나 최신 클라우드 아키텍처에서는 요청이 백엔드 서비스에 도달하기 전에 에지 로드 밸런서, API 게이트웨이, 리버스 프록시 또는 콘텐츠 전송 네트워크(CDN)에서 TLS가 자주 종료됩니다.

중간 프록시가 손상되거나 송신자와 수신자 사이에 검증되지 않은 라우팅 서비스가 있는 경우 수신 요청 구성 요소가 검사되거나 수정될 수 있습니다.

  • 어트리뷰션 재라우팅: click_id 또는 publisher_id와 같은 매개변수를 변경하여 오가닉 전환을 승인되지 않은 계정에 귀속시킵니다.
  • 금전적 인플레이션: 요청 본문 내의 트랜잭션 번호나 통화 코드를 변경하여 부풀려진 제휴 수수료를 청구합니다.
  • 이벤트 승격: 퍼널 상단 상호작용에서 고가치 구매 마일스톤으로 이벤트 카테고리 식별자를 수정합니다.

재전송 공격 대 중복 네트워크 전달

재전송 공격(Replay exploit)은 악의적인 공격자가 정당한 포스트백 전송을 가로채어 해당 페이로드를 수신자에게 그대로 다시 제출할 때 발생합니다. 원래 메시지 내의 매개변수와 암호화 토큰이 생성 시점에 유효했기 때문에, 메시지 서명만 검증하는 단순한 수신자는 재제출된 요청을 유효한 것으로 평가하게 됩니다.

이 위협은 일반적인 전송 계층 재시도와 구분되어야 합니다. 수신자가 이미 레코드를 수신했더라도 HTTP 확인 응답을 받지 못한 경우 일시적인 네트워크 타임아웃으로 인해 송신자가 포스트백을 재전송하는 경우가 종종 발생합니다. 강력한 아키텍처는 사기성 재전송과 정상적인 재전송을 구분해야 합니다.

자격 증명 탈취와 정적 토큰의 한계

공유 API 키나 HTTP 요청 헤더에 배치된 베어러 토큰과 같은 정적 자격 증명에만 의존하는 것은 비밀이 기밀로 유지된다는 가정 하에 호출자의 신원을 인증합니다.

그러나 정적 베어러 토큰은 요청 본문에 대한 암호화 바인딩을 전혀 제공하지 않습니다. 서버 로그, 리포지토리 구성 오류, 네트워크 모니터링 툴을 통해 정적 키가 유출되면 해당 토큰을 보유한 공격자가 임의의 페이로드를 위조할 수 있습니다. 정적 토큰은 누가 호출하고 있다고 주장하는지를 검증하지만, 전송된 데이터가 수정되었는지 여부는 증명하지 못합니다.

암호화 메시지 인증 및 보호 범위

HMAC의 수학적 메커니즘 (IETF RFC 2104)

IETF RFC 2104에 표준화된 키 해시 메시지 인증 코드(HMAC)는 데이터 무결성과 진위 여부를 확인하기 위해 사전 공유된 비밀 키와 결합된 암호화 해시 함수(SHA-256 등)를 사용합니다.

HMAC 알고리즘은 비밀 키 K와 입력 메시지 M을 기반으로 작동합니다.

\text{HMAC}(K, M) = H\Big((K' \oplus \text{opad}) \parallel H\big((K' \oplus \text{ipad}) \parallel M\big)\Big)

여기서:

  • H는 기본 암호화 해시 함수(SHA-256)입니다.
  • B는 해시 함수의 블록 크기입니다(SHA-256의 경우 64바이트).
  • K'는 비밀 키 K에서 파생됩니다. K가 B보다 길면 H를 사용하여 길이 L(32바이트)로 사전 해시되고 0으로 B까지 패딩됩니다. K가 B보다 짧으면 0으로 채워 B까지 확장됩니다.
  • \text{opad}는 외부 패딩 문자열입니다(0x5c가 B번 반복됨).
  • \text{ipad}는 내부 패딩 문자열입니다(0x36이 B번 반복됨).
  • \parallel은 바이트 연결을 나타내고, \oplus는 비트 단위 배타적 논리합(XOR)을 나타냅니다.

업계 문서에서는 이 메커니즘을 종종 "요청 서명"이라고 부르지만, HMAC은 대칭 메시지 인증 코드(MAC)입니다. 송신자와 수신자가 모두 동일한 비밀 키 K에 대한 액세스 권한을 공유하기 때문에 비대칭 디지털 서명이나 암호화 부인 방지를 제공하지 않습니다.

메시지 인증의 범위와 경계

암호화 검증 주위에 명확한 경계를 설정하면 보안 결과를 과장하는 것을 방지할 수 있습니다.

검증 경계 실제 운영 기능
유효한 MAC이 증명하는 것 1. 포함된 메시지 요소가 송신자에 의해 해시된 정확한 바이트와 일치함.
2. MAC을 생성한 주체가 활성 공유 비밀 키를 보유하고 있음.
유효한 MAC이 증명하지 않는 것 1. 인앱 구매나 설치가 실제 기기에서 실제로 발생했는지 여부.
2. 송신자가 사기성 비즈니스 이벤트를 조작하지 않았는지 여부.
3. 공유 비밀이 노출되거나 내부적으로 공유되지 않았는지 여부.
4. 요청이 가로채어져 재전송(재전송 공격)되지 않았는지 여부.

유효한 MAC은 구성된 키에 따라 포함된 요청 데이터를 인증합니다. 보고된 전환이 발생했음을 증명하지는 않습니다. 권위 있는 비즈니스 기록, 권한 부여, 조정 및 이벤트 멱등성은 별도의 제어 요소로 유지됩니다.

전송 보안 대 애플리케이션 보안

TLS는 포스트백 전송을 보호하고 HMAC은 인증된 요청 필드의 변조를 감지합니다.

애플리케이션 계층 메시지 인증은 전송 계층 보안(TLS)을 대체하지 않습니다. 즉각적인 TCP 피어 간에 작동하는 TLS는 오픈 인터넷상의 수동적인 도청으로부터 자격 증명, 헤더, 페이로드를 보호합니다. 차례로 애플리케이션 계층 메시지 인증은 중간 리버스 프록시나 에지 게이트웨이에서 TLS가 종료되더라도 포함된 필드에 대한 무단 수정이 애플리케이션 실행 로직에 도달하기 전에 감지되고 거부되도록 보장합니다.

서명된 정규화된 데이터 모델 구축

포함되지 않은 요청 필드의 위험성

암호화 MAC은 해시 함수에 입력된 특정 바이트 시퀀스만 보호합니다. IETF RFC 9421(HTTP 메시지 서명)에 명시된 바와 같이 서명 베이스에서 누락된 요청 구성 요소는 인증 태그를 무효화하지 않고 전송 중에 수정되거나 주입될 수 있습니다.

HTTP S2S 어트리뷰션 포스트백에서 URI 경로, 키 식별자 또는 쿼리 매개변수를 생략하면 요청 본문 단독에 대해 유효한 서명을 유지하면서 매개변수 조작이 허용됩니다.

  • 쿼리 문자열 조작: HTTP GET 포스트백 또는 URL 쿼리 매개변수를 전달하는 POST 요청에서 정규화된 문자열에서 쿼리 매개변수를 제외하면 공격자가 해당 쿼리 매개변수를 자유롭게 수정할 수 있습니다.
  • 경로 탐색 및 엔드포인트 리타겟팅: 대상 경로를 생략하면 공격자가 테스트 엔드포인트(/v1/test/conversion)용으로 의도된 페이로드를 가져와 프로덕션 청구 엔드포인트(/v1/live/conversion)로 전달할 수 있습니다.
  • 키 식별자 대체: 키 조회 및 테넌트 신원이 안전하게 바인딩되지 않거나 동일한 비밀 자재가 테넌트 범위에 부적절하게 공유되는 경우 키 ID를 생략하면 공격자가 요청을 재라우팅할 수 있습니다.

예시 S2S 요청 스키마 정의

검증을 표준화하기 위해 시스템은 명확한 정규화된 문자열 형식을 구축해야 합니다. 다음 스키마는 전용 트랜잭션 식별자와 선택적 통화 추적 매개변수가 포함된 JSON POST 전환 페이로드를 보여줍니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "IllustrativeConversionPostbackPayload",
  "type": "object",
  "required": [
    "event_id",
    "event_name",
    "event_timestamp"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "minLength": 1,
      "description": "비즈니스 수준의 중복 제거를 위해 수신 시스템에서 사용하는 고유 트랜잭션 이벤트 식별자입니다."
    },
    "click_id": {
      "type": ["string", "null"],
      "description": "광고 클릭 기록과 일치하는 상태 비저장 어트리뷰션 식별자입니다. 오가닉 또는 집계 이벤트의 경우 null일 수 있습니다."
    },
    "campaign_id": {
      "type": ["string", "null"],
      "description": "초기 클릭 수집 중에 제공되는 캠페인 추적 식별자입니다."
    },
    "event_name": {
      "type": "string",
      "minLength": 1,
      "description": "표준화된 이벤트 식별자(예: 설치, 구매, 가입)."
    },
    "event_timestamp": {
      "type": "integer",
      "minimum": 0,
      "description": "비즈니스 이벤트가 발생한 시점을 나타내는 전체 초 단위의 에포크 타임스탬프입니다."
    },
    "conversion_value": {
      "type": "number",
      "description": "이벤트와 관련된 선택적 금전적 수익입니다."
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "3글자 통화 형식 문자열입니다. ISO 4217에 대한 의미론적 검증은 애플리케이션 로직에 의해 강제되어야 합니다."
    }
  },
  "dependentRequired": {
    "conversion_value": ["currency"]
  }
}

정규화된 프로토콜 정규화

시스템 간의 형식 지정 차이로 인한 검증 실패를 방지하기 위해 송신자와 수신자 모두 정규화되고 구분된 UTF-8 문자열을 조립해야 합니다.

프로토콜 경계 참고: 다음 구성은 정확한 경로를 타겟팅하는 JSON POST 요청을 위해 예시적인 애플리케이션 정의 MAC 프로파일을 정의합니다. 이는 공식 IETF RFC 9421 HTTP 메시지 서명 와이어 사양이나 공식 OpoInstall 프로토콜이 아닙니다. 연동 개발자는 자체 정규화 규칙을 문서화하고 적용해야 합니다.

CanonicalString = HTTP_METHOD + "\n" +
                  REQUEST_PATH + "\n" +
                  KEY_ID + "\n" +
                  TIMESTAMP_SECONDS + "\n" +
                  NONCE + "\n" +
                  HEX_SHA256(RAW_BODY_BYTES)

이 프로파일에서 각 정규화된 컴포넌트를 조립하기 위한 규칙:

  • HTTP_METHOD: 반드시 대문자 POST여야 합니다.
  • REQUEST_PATH: 정확한 대상 URI 경로(예: /v1/conversions/postback). 쿼리 정규화 모호성을 제거하기 위해 이 엔드포인트에서는 URL 쿼리 매개변수가 허용되지 않습니다.
  • KEY_ID: 사전 공유 키의 식별자(예: key_demo_2026). 키 대체 공격을 방지하기 위해 정규화된 문자열에 직접 바인딩됩니다.
  • TIMESTAMP_SECONDS: 에포크 초를 나타내는 10진수 정수로 형식화된 요청 디스패치 타임스탬프.
  • NONCE: 이 HTTP 요청 디스패치에 고유한 암호화 무작위 1네이티브 16진수 문자열(CSPRNG를 통해 생성된 최소 32개의 소문자 16진수 문자).
  • RAW_BODY_BYTES: 요청 본문의 정확한 바이트 스트림. SHA-256 다이제스트는 이 바이트에 대해 직접 계산됩니다.

정규화된 요청 필드와 공유 비밀은 HMAC 인증 태그를 생성합니다.

다중 레이어 재전송 방어 및 멱등성

요청 검증 파이프라인 전반의 책임

처리 단계 방어 제어 운영 책임
1. 요청 전송 및 구문 메서드, 경로 및 본문 크기 제한 요청이 허용된 HTTP 메서드, 경로와 일치하고 메모리 경계를 초과하지 않는지 검증합니다.
2. 신선도 검증 제한된 타임스탬프 창 (\Delta t \le W) 수신자 시간 전후 W초 이내의 타임스탬프만 허용합니다.
3. 신원 및 키 바인딩 신뢰할 수 있는 키 레지스트리 조회 X-Key-Id를 사용하여 신뢰할 수 있는 백엔드 저장소에서 공유 비밀 키를 해결합니다. 암호화 평가 전에 알 수 없는 키를 거부합니다.
4. 메시지 인증 상수 시간 HMAC-SHA256 검증 정규화된 문자열에 대해 MAC을 계산하고 compare_digest를 사용하여 X-Signature와 비교합니다.
5. 원자적 재전송 보호 범위가 지정된 넌스 캐시 (SET key NX EX) 보유 기간 동안 인증된 테넌트 키 범위 내에서 캐시의 넌스를 원자적으로 예약합니다.
6. 비즈니스 중복 제거 트랜잭션 데이터베이스 고유 제약 조건 이벤트 중복 제거 및 크레딧 업데이트가 테넌트 경계 내에서 원자적으로 커밋될 때 중복 크레딧을 방지합니다.

타임스탬프 오차 허용 오차 및 넌스 보존 구성

재전송 공격을 완화하려면 제한된 타임스탬프 창과 원자적 넌스 캐시라는 상호 의존적인 두 가지 검사를 조정해야 합니다.

서버가 다음 조건 내의 요청을 수락하는 대칭 클럭 오차 허용 오차 W = 300\text{ seconds}와의 연동을 고려해 보세요.

t_{\text{recv}} - W \le t_{\text{req}} \le t_{\text{recv}} + W

수신자 시계가 t_{\text{recv}} = 700을 가리킬 때 t_{\text{req}} = 1000으로 타임스탬프가 찍힌 요청이 도착하고(1000 - 700 \le 300이므로 허용됨), 넌스가 300초 TTL로 저장되는 경우 캐시 키는 t = 1000에 만료됩니다. 공격자가 t = 1001에 동일한 요청을 재전송하면 요청은 이제 1초 경과된 것이며(1001 - 1000 = 1 \le 300), 이는 신선도 검사를 통과합니다. t = 1000에 캐시에서 넌스가 만료되었기 때문에 재전송된 요청은 성공하게 됩니다.

대칭 창에서 이 공격을 방지하기 위해 이 예시 프로토콜은 보수적인 보존 구성을 채택합니다.

\text{TTL}_{\text{nonce}} = 2 \times W + \text{ClockSkewMargin}

허용 오차 창 W = 300\text{s} 및 클럭 스큐 여유 60\text{s}의 경우 넌스 TTL은 660\text{ seconds}로 구성됩니다. 또는 수신자는 비대칭 오차 정책(예: 5초를 초과하는 미래 타임스탬프 거부)을 적용하고 넌스 TTL을 W + \text{FutureMargin}으로 설정할 수 있습니다.

타임스탬프 검사 및 원자적 넌스 추적은 서명된 요청의 반복 수락을 방지합니다.

원자적 넌스 추적 및 실패 모드 정책

넌스 검사와 넌스 예약은 원자적 연산으로 실행되어야 합니다. 별도의 읽기 쿼리 뒤에 쓰기 쿼리를 수행하면 동시 재전송 공격을 허용하는 경쟁 상태(Time-of-check to time-of-use)가 발생합니다.

분산 아키텍처에서 원자적 예약은 Redis SET key value EX ttl NX와 같은 메모리 데이터 저장소 프리미티브를 사용하여 구현됩니다. 테넌트 간 충돌이나 키 간 오염을 방지하려면 캐시 키가 인증된 키 또는 테넌트 식별자(예: s2s_nonce:{key_id}:{nonce})에 의해 범위가 지정되어야 합니다.

시스템 관리자는 분산 캐시에 연결할 수 없는 경우에 대한 명시적인 실패 정책을 정의해야 합니다.

  • 폐쇄형 정책(Fail-Closed): 넌스 캐시가 오프라인 상태인 경우 HTTP 503 상태로 들어오는 포스트백을 거부합니다. 이는 인프라 파티션 중 재전송 공격을 방지하지만 전환 수집이 중단됩니다.
  • 감사 기능이 있는 개방형 정책(Fail-Open): 알림을 기록하는 동안 검증된 서명이 통과되도록 일시적으로 허용합니다. 이는 수집 가용성을 유지하지만 운영자는 캐시가 복구될 때까지 전송 재전송 보호 기능이 저하된다는 점을 감수해야 합니다.

전송 재전송 대 비즈니스 멱등성

애플리케이션 보안은 전송 계층 재시도 처리와 비즈니스 계층 이벤트 처리를 분리해야 합니다.

  • 전송 계층 (넌스 및 타임스탬프): 단일 HTTP 디스패치를 보호합니다. 네트워크 타임아웃이 발생하고 송신자가 포스트백을 재시도하는 경우 송신자는 새로운 타임스탬프, 새로운 넌스를 생성하고 업데이트된 정규화된 문자열에 대해 HMAC를 다시 계산해야 합니다.
  • 비즈니스 계층 (이벤트 ID): 전환 기록을 보호합니다. 페이로드 본문은 원본의 변경 불가능한 event_id를 유지합니다. 수신 광고 네트워크가 요청을 수집할 때 테넌트에 범위가 지정된 고유 제약 조건(예: INSERT ... ON CONFLICT DO NOTHING을 통해)을 통해 event_id가 이미 크레딧 처리되었는지 확인합니다. 이미 처리된 경우 중복 청구 없이 확인 응답을 반환합니다.

고유한 요청 넌스는 합법적인 재시도를 보존하는 동시에 데이터베이스 멱등성은 중복 전환 크레딧을 방지합니다.

참조 구현: 암호화 헤더 스키마 및 검증

와이어 수준 헤더 및 페이로드 표현

다음의 자체 일관성 있는 HTTP 교환은 분리된 암호화 헤더를 활용하는 인증된 전환 포스트백 요청을 보여줍니다.

요청은 테스트 비밀 키 b"k_demo_secret_key_32_bytes_len!", X-Key-Id key_demo_2026, 타임스탬프 1794815760(2026-11-16T07:56:00Z에 해당), 넌스 4e9a2c1b74e64f8e9b2a1c74e6f8a9b2를 사용합니다.

원시 UTF-8 본문 바이트(압축된 JSON, 정확히 207바이트): {"event_id":"evt_9876543210_abc","click_id":"click_123456789_xyz","campaign_id":"cmp_spring_acquisition","event_name":"in_app_purchase","event_timestamp":1794815758,"conversion_value":49.99,"currency":"USD"}

SHA-256(raw_body_bytes) 계산 결과: eda92f236690851c47e5662feb02a6d3aa144e6d7061bf41c4b41a4f43a0a9ba

정규화된 문자열 조립:

POST
/v1/conversions/postback
key_demo_2026
1794815760
4e9a2c1b74e64f8e9b2a1c74e6f8a9b2
eda92f236690851c47e5662feb02a6d3aa144e6d7061bf41c4b41a4f43a0a9ba

HMAC-SHA256(key, canonical_string) 계산 결과 정확한 1네이티브 서명 생성: a0c399934b8bde268d5deedb879b2f06ff8d9df0b51dd5957fd1014a8e1429fc

와이어 전송 및 즉각적인 확인 응답:

POST /v1/conversions/postback HTTP/1.1
Host: api.adnetwork-receiver.example.com
Content-Type: application/json
X-Key-Id: key_demo_2026
X-Signature-Version: v1
X-Timestamp: 1794815760
X-Nonce: 4e9a2c1b74e64f8e9b2a1c74e6f8a9b2
X-Signature: a0c399934b8bde268d5deedb879b2f06ff8d9df0b51dd5957fd1014a8e1429fc

{"event_id":"evt_9876543210_abc","click_id":"click_123456789_xyz","campaign_id":"cmp_spring_acquisition","event_name":"in_app_purchase","event_timestamp":1794815758,"conversion_value":49.99,"currency":"USD"}
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 16 Nov 2026 07:56:01 GMT

{
  "status": "acknowledged",
  "event_id": "evt_9876543210_abc"
}

Python에서의 방어적 검증 로직

다음 구현은 인증 계층 참조 구성 요소를 나타냅니다. request_target은 승인되지 않은 쿼리 문자열이 거부되도록 모든 경로와 쿼리 요소를 유지하면서 원시 HTTP 요청 라인에서 직접 추출해야 합니다. 트랜잭션이 커밋되기 전에 Content-Type 유효성 검사, 테넌트 권한 부여, 스키마 역직렬화와 같은 애플리케이션 계층 문제들이 다운스트림 미들웨어에 의해 평가되어야 합니다.

import hmac
import hashlib
import time
import re
from typing import Optional, Dict

# Configuration Constants
ALLOWED_SIGNATURE_VERSIONS = {"v1"}
HEX_64_PATTERN = re.compile(r"^[0-9a-f]{64}$")
TIMESTAMP_PATTERN = re.compile(r"^\d{1,10}$")
HEX_NONCE_PATTERN = re.compile(r"^[0-9a-f]{32,64}$")

DRIFT_WINDOW_SECONDS = 300
SKEW_MARGIN_SECONDS = 60
NONCE_TTL_SECONDS = (DRIFT_WINDOW_SECONDS * 2) + SKEW_MARGIN_SECONDS
MAX_BODY_SIZE_BYTES = 1024 * 64  # 64 KB limit
EXPECTED_REQUEST_PATH = "/v1/conversions/postback"

# Mock Trusted Key Registry (In production, load securely from Vault / KMS)
TRUSTED_KEY_REGISTRY: Dict[str, bytes] = {
    "key_demo_2026": b"k_demo_secret_key_32_bytes_len!"
}

class VerificationResult:
    def __init__(self, valid: bool, status_code: int, error_code: str):
        self.valid = valid
        self.status_code = status_code
        self.error_code = error_code

def verify_s2s_postback_authentication(
    headers: dict,
    http_method: str,
    request_target: str,
    raw_body_bytes: bytes,
    redis_client
) -> VerificationResult:
    """
    Reference authentication-layer verifier for S2S postback requests.
    Enforces strict method/path rules, validates headers, checks freshness,
    verifies HMAC-SHA256, and atomically reserves the scoped nonce in Redis.
    """
    # 1. Payload Size Guard
    if len(raw_body_bytes) > MAX_BODY_SIZE_BYTES:
        return VerificationResult(False, 413, "PAYLOAD_TOO_LARGE")

    # 2. Strict Method and Target Path Enforcement (No query strings allowed)
    if http_method.upper().strip() != "POST":
        return VerificationResult(False, 405, "METHOD_NOT_ALLOWED")

    normalized_target = request_target.strip()
    if normalized_target != EXPECTED_REQUEST_PATH:
        return VerificationResult(False, 404, "INVALID_REQUEST_PATH")

    # 3. Header Extraction and Syntax Validation
    sig_version = headers.get("X-Signature-Version", "")
    if sig_version not in ALLOWED_SIGNATURE_VERSIONS:
        return VerificationResult(False, 400, "UNSUPPORTED_SIGNATURE_VERSION")

    key_id = headers.get("X-Key-Id", "").strip()
    if not key_id or len(key_id) > 64 or not key_id.isascii():
        return VerificationResult(False, 400, "INVALID_KEY_ID_FORMAT")

    # 4. Resolve Trusted Secret Key from Authenticated Registry
    secret_key = TRUSTED_KEY_REGISTRY.get(key_id)
    if not secret_key:
        return VerificationResult(False, 401, "UNKNOWN_OR_INACTIVE_KEY")

    received_sig = headers.get("X-Signature", "").strip().lower()
    if not received_sig.isascii() or not HEX_64_PATTERN.match(received_sig):
        return VerificationResult(False, 400, "MALFORMED_SIGNATURE_HEADER")

    timestamp_str = headers.get("X-Timestamp", "").strip()
    if not timestamp_str.isascii() or not TIMESTAMP_PATTERN.match(timestamp_str):
        return VerificationResult(False, 400, "MALFORMED_TIMESTAMP_HEADER")

    nonce = headers.get(
        "X-Nonce", ""
    ).strip().lower()
    if not nonce.isascii() or not HEX_NONCE_PATTERN.match(nonce):
        return VerificationResult(False, 400, "INVALID_NONCE_FORMAT")

    # 5. Time-Drift Freshness Check
    req_timestamp = int(timestamp_str)
    current_time = int(time.time())
    if abs(current_time - req_timestamp) > DRIFT_WINDOW_SECONDS:
        return VerificationResult(False, 401, "EXPIRED_OR_PREDATED_TIMESTAMP")

    # 6. Canonical String Construction (Explicitly binding Method, Path, Key ID, Timestamp, Nonce, Body)
    body_digest = hashlib.sha256(raw_body_bytes).hexdigest()
    canonical_string = (
        f"POST\n"
        f"{EXPECTED_REQUEST_PATH}\n"
        f"{key_id}\n"
        f"{timestamp_str}\n"
        f"{nonce}\n"
        f"{body_digest}"
    )

    # 7. Cryptographic MAC Calculation (RFC 2104 / SHA-256)
    computed_mac = hmac.new(
        secret_key,
        canonical_string.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison to mitigate timing attacks
    if not hmac.compare_digest(received_sig, computed_mac):
        return VerificationResult(False, 401, "SIGNATURE_VERIFICATION_FAILED")

    # 8. Scoped Atomic Nonce Registration (Bound to Key ID; executed AFTER signature check)
    scoped_nonce_key = f"s2s_nonce:{key_id}:{nonce}"
    try:
        is_unique = redis_client.set(
            scoped_nonce_key,
            "1",
            ex=NONCE_TTL_SECONDS,
            nx=True
        )
        if not is_unique:
            return VerificationResult(False, 401, "REPLAYED_TRANSACTION_NONCE")
    except Exception:
        # Fail-closed policy: reject request when nonce storage is unavailable
        return VerificationResult(False, 503, "NONCE_STORAGE_UNAVAILABLE")

    return VerificationResult(True, 200, "SUCCESS")

보안 검증 실패에 대한 HTTP 상태 코드 의미

HTTP 상태 응답을 표준화하면 프로토콜 표준을 준수하면서 진단 감사가 가능해집니다.

  • 400 Bad Request: 요청 전송 시 구문적 또는 구조적 결함이 있음을 나타냅니다. 필수 보안 헤더가 누락되었거나, 문자열 인코딩이 ASCII 규칙을 위반했거나, 1네이티브 값이 형식 패턴을 위반할 때 반환됩니다.
  • 401 Unauthorized: 인증 또는 암호화 실패를 나타냅니다. 키 ID를 인식할 수 없거나, HMAC 계산이 수신된 서명과 일치하지 않거나, 타임스탬프가 오차 범위를 위반했거나, 넌스가 중복으로 식별된 경우 반환됩니다. 401 응답을 생성할 때 HTTP 어댑터 레이어는 IETF RFC 9110을 준수하는 해당 WWW-Authenticate 챌린지 헤더를 포함해야 합니다.
  • 403 Forbidden: 암호화 서명 및 타임스탬프가 키 아래에서 성공적으로 확인되었음에도 불구하고 인증된 테넌트가 본문에 식별된 특정 캠페인 또는 퍼블리셔 리소스에 대한 권한이 부족함을 나타냅니다.
  • 405 Method Not Allowed: 요청이 지원되지 않는 HTTP 동사(예: 서명된 POST 요청 전용으로 구성된 엔드포인트에서 GET 또는 PUT)를 사용할 때 반환됩니다. HTTP 어댑터 레이어는 응답에 Allow: POST 헤더를 포함해야 합니다.
  • 413 Payload Too Large: 요청 본문이 구성된 최대 바이트 제한(예: 64 KB)을 초과할 때 반환됩니다.
  • 422 Unprocessable Content: 암호화 헤더가 성공적으로 검증되었음에도 불구하고 JSON 페이로드 본문이 의미론적 규칙을 위반함(예: 이벤트 수익 값이 전달될 때 필수 ISO 통화 코드가 누락된 경우)을 나타냅니다.

S2S 보안 제어 비교 평가

적절한 보안 메커니즘을 선택하려면 특정 운영 경계에 대해 방어 레이어를 평가해야 합니다.

제어 TLS 연결 보안 애플리케이션 페이로드 무결성 애플리케이션 요청 재전송 방어 비즈니스 이벤트 중복 제거
HTTPS를 통한 정적 베어러 토큰 직접 피어 간 TLS에 의해 제공됨 없음; 중간 프록시 전반에서 페이로드 보호되지 않음 없음; 유효 기간 내에 베어러 토큰 재전송 가능 별도의 데이터베이스 고유 제약 조건 필요
IP 화이트리스트 없음; 네트워크 라우팅 제어만 해당 없음; 애플리케이션 계층에서 패킷 인증되지 않음 없음; 승인된 IP에서 요청 재전송 가능 별도의 데이터베이스 고유 제약 조건 필요
애플리케이션 HMAC-SHA256 없음; 애플리케이션 계층에서 작동함 키 아래에서 포함된 정규화된 요소 인증 외부 타임스탬프 및 넌스 메커니즘에 의존함 별도의 데이터베이스 고유 제약 조건 필요
상호 TLS (mTLS) 암호화 피어 및 전송 인증 터널 수준; 애플리케이션 수준의 재전송으로부터 보호하지 않음 없음; 애플리케이션 계층에서 요청 재전송 가능 별도의 데이터베이스 고유 제약 조건 필요
계층화된 아키텍처 (mTLS + HMAC + 넌스 + DB 고유 키) 네트워크 전반의 암호화 피어 인증 중개자 전반의 엔드투엔드 페이로드 무결성 타임스탬프 범위 및 원자적 넌스 캐시를 통해 강제됨 트랜잭션 데이터베이스 제약 조건을 통해 강제됨

자주 묻는 질문 (FAQ)

S2S 보안에서 API 키와 HMAC 서명 간의 차이점은 무엇인가요?
정적 API 키는 호출자의 신원을 인증하지만 메시지 무결성에 대한 검증을 전혀 제공하지 않는 HTTP 헤더로 전송되는 지속적인 베어러 자격 증명입니다. HMAC 서명은 사전 공유된 비밀 키, 타임스탬프, 고유한 넌스 및 원시 페이로드 본문을 사용하여 요청당 계산되는 동적 암호화 해시입니다. 페이로드의 매개변수가 전송 중에 변경되면 계산된 HMAC가 변경되어 수신자가 변조된 요청을 즉시 거부하게 됩니다.
수신 시스템은 포스트백 검증 중에 합법적인 클럭 오차를 어떻게 처리하나요?
이 예시 프로토콜에서 수신 시스템은 분산 클라우드 인스턴스 간의 미세한 시계 불일치를 고려하기 위해 대칭 시간 오차 허용 오차 창($\pm 300\text{ seconds}$)을 구성합니다. 포스트백 타임스탬프가 이 창 내에 속하면 수신자는 서명을 평가합니다. 타임스탬프가 구성된 임계값을 벗어나면 요청은 HTTP 401 Unauthorized 상태와 함께 즉시 거부되어 만료되었거나 사전 날짜가 지정된 요청이 처리 파이프라인에 진입하는 것을 방지합니다.
어트리뷰션 API에 대한 독립형 보안 제어로서 IP 화이트리스트가 불충분한 이유는 무엇인가요?
IP 화이트리스트는 승인된 서버 서브넷으로 네트워크 액세스를 제한하지만, 공유 프록시 뒤의 특정 애플리케이션 테넌트를 인증하지 못하고 페이로드 데이터 무결성을 검증하지 않으며 동적 클라우드 IP 풀 전반에서 운영상 취약합니다. 최신 클라우드 환경은 동적 아웃바운드 IP 범위를 자주 활용하므로 애플리케이션 계층 암호화 검증이 없을 때는 정적 IP 화이트리스트가 불충분합니다.

요약 및 결정 프레임워크

서버 간 API에서 어트리뷰션 페이로드 변조를 방지하려면 정적 자격 증명과 인증되지 않은 웹훅을 넘어설 필요가 있습니다. 정규화된 문자열 표준화, HMAC-SHA256 해싱, 제한된 타임스탬프 검사, 원자적 넌스 예약을 결합한 애플리케이션 계층 암호화 아키텍처를 구현함으로써 측정 시스템은 검증 가능한 데이터 무결성을 구축하고 재전송 공격을 완화합니다.

암호화 검증은 들어오는 전환 데이터가 사전 공유된 비밀을 보유한 송신자에 의해 구성된 정확한 페이로드와 일치함을 확인합니다. 그러나 메시지 인증은 기본 실제 전환 정당성을 검증하지 않습니다. 엔터프라이즈 어트리뷰션 아키텍처는 탄력적인 어트리뷰션 시스템을 유지하기 위해 요청 서명을 비즈니스 수준의 멱등성, 전환 값 감사, 서버 측 조정과 페어링해야 합니다.

캠페인 추적 연동을 구성하고 API 사양을 검토하는 팀은 OpoInstall 문서 센터를 참조하거나 OpoInstall 개발자 콘솔에서 애플리케이션 식별자를 관리하거나, 아키텍처 지침을 위해 광범위한 모바일 어트리뷰션 구현 참조를 검토할 수 있습니다.

관련 자료

Share this article