ngx_http_secure_link_module 를 통한 링크 보안 및 유효 기간 관리

이 블로그 포스트는 NGINX의 ngx_http_secure_link_module 을 활용하여 링크 보안 및 유효 기간 관리를 구현하는 방법을 다룹니다. ngx_http_secure_link_module은 동적 콘텐츠 또는 파일 다운로드와 같은 요청에 대해 보안성을 제공하며, 링크 유효성을 검증하는 데 유용합니다.

이 글에서는 모듈의 기본 설정, 실사용 사례, 그리고 적합한 모범 사례를 설명합니다.

목차

1. ngx_http_secure_link_module 란 무엇인가?
 1-1. 모듈의 개요 및 역할
 1-2. ngx_http_secure_link_module 주요 기능과 특징
2. ngx_http_secure_link_module 설정 방법
 2-1. ngx_http_secure_link_module 기본 구성과 예제
 2-2. 보안 링크 생성 및 검증 과정
3. 링크 유효 기간 관리
 3-1. 유효 기간 설정 방법
 3-2. 만료된 링크 처리
4. ngx_http_secure_link_module 실사용 사례 및 활용 방법
 4-1. 파일 다운로드 보호
 4-2. 동적 콘텐츠 접근 제한
5. 결론
 5-1. ngx_http_secure_link_module의 이점 요약
 5-2. 추천 추가 설정 및 모범 사례

1. ngx_http_secure_link_module란 무엇인가?

1-1. 모듈의 개요 및 역할

ngx_http_secure_link_module은 URL에 포함된 보안 해시 값을 통해 요청의 무결성과 유효성을 검증하는 모듈입니다. 이를 통해 URL이 비인가 사용자에 의해 조작되거나 무단으로 공유되는 것을 방지합니다. 주로 동적 콘텐츠, 파일 다운로드, 또는 제한된 서비스에 대한 접근 제어를 구현하는 데 사용됩니다.

1-2. ngx_http_secure_link_module 주요 기능과 특징

ngx_http_secure_link_module은 요청의 유효성을 보장하는 데 필요한 다양한 기능을 제공합니다.

보안 토큰 기반 검증: 요청에 포함된 해시 값을 기반으로 요청의 정당성을 확인합니다.
유효 기간 관리: 링크에 만료 시간을 설정하여 한정된 기간 동안만 사용 가능하도록 제어합니다.
무결성 보장: 요청 URL이 의도적으로 변경되었을 경우 접근이 거부됩니다.
유연한 설정 지원: 커스텀 토큰 생성 및 검증 방식을 사용할 수 있습니다.

2. ngx_http_secure_link_module 설정 방법

2-1. ngx_http_secure_link_module 기본 구성과 예제

이 모듈은 간단한 설정으로 보안 링크를 구현할 수 있습니다. 기본적으로 secure_link와 secure_link_md5 지시어를 조합하여 동작합니다. 다음은 NGINX에서 ngx_http_secure_link_module을 설정하는 예제입니다.

NGINX STORE GitHub: secure_link.conf

location /download {
    secure_link $arg_md5,$arg_expires;  # 요청 URI에서 md5 ($arg_md5)와 만료 시간($arg_expires) 추출
    secure_link_md5 "$uri$secure_link_expires secret";  # 서버에서 생성된 MD5 값과 비교

    if ($secure_link = "") {
        return 403;  # MD5가 일치하지 않으면 접근 금지
    }

    if ($secure_link = "0") {
        return 410;  # 링크가 만료되었으면 접근 금지
    }

    internal_redirect @success;  # 검증 성공 시 내부 리다이렉트
}

• secure_link 디렉티브: 요청 URI에서 md5와 expires 값을 추출합니다.
• secure_link_md5 디렉티브: 서버에서 MD5 해시를 생성하기 위한 식을 정의합니다.
• 검증 로직:
  • 요청된 MD5 값이 일치하지 않으면 HTTP 403 반환.
  • 요청된 만료 시간이 현재 시간보다 과거라면 HTTP 410 반환.

2-2. 보안 링크 생성 및 검증 과정

보안 링크는 클라이언트가 생성한 MD5 해시와 서버에서 계산한 MD5 해시를 비교하여 검증하며, 링크 만료 시간도 함께 확인합니다. 이를 통해 비정상적인 요청이나 만료된 링크에 대한 접근을 방지할 수 있습니다.

보안 링크를 생성하려면 클라이언트는 요청 URI 경로와 만료 시간, 그리고 비밀 문자열(secret)을 조합하여 MD5 해시 값을 생성해야 합니다. 이를 위해 다음과 같은 Bash 스크립트를 사용할 수 있습니다.

NGINX STORE GitHub: generateSecureLink.sh

#!/bin/bash
echo -n '/download2147483647 secret' | \
    openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =

스크립트는 입력 데이터로 만료 시간, 요청 URI 경로, 그리고 서버와 클라이언트가 공유하는 비밀값을 조합하여 MD5 해시를 생성합니다. 예를 들어, '/download2147483647 secret'이라는 문자열에서 /download는 요청 URI 경로, secret은 서버와 클라이언트 간에 공유되는 비밀값, 2147483647은 링크의 만료 시간(UNIX Timestamp로 2038년 1월 19일)을 의미합니다.

이 데이터는 openssl md5 -binary 명령어를 사용해 다음과 같이 바이너리 형태의 MD5 해시로 변환됩니다.

doo5zp4ntI8hl0ecU83tmg

해당 MD5 해시와 링크 만료시간이 포함된 URI는 다음과 같습니다. 이는 secure_link 디렉티브에서 설정한 arg 순서와 일치해야 합니다.

{NGINX Server IP}/download?md5=doo5zp4ntI8hl0ecU83tmg&expires=2147483647

{NGINX Server IP}/download?$arg_md5,$arg_expires

생성된 md5의 값은 secure_link_md5 디렉티브를 통해 설정된 MD5 해시식과 일치해야 합니다.

doo5zp4ntI8hl0ecU83tmg (/download2147483647 secret)
secure_link_md5        ($uri$secure_link_expires secret)

3. ngx_http_secure_link_module 를 통한 링크 유효 기간 관리

3-1. 유효 기간 설정 방법

MD5 해시 생성 스크립트에서 UNIX Timestamp 기준 유효기간을 설정할 수 있습니다. 아래 예제는 현재 시각 기준 60초 뒤에 만료되는 UNIX Timestamp 만료기간을 출력하는 bash 스크립트 입니다.

NGINX STORE GitHub: generateSecureLinkAfter.sh

#!/bin/bash

# 현재 시간 기준 60초 뒤의 Unix Epoch 시간 계산
expires=$(date -d "+60 seconds" +%s)

# MD5 해시 생성
md5=$(echo -n "/download${expires} secret" | \
    openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =)

# 결과 출력 (MD5 해시와 만료 시간)
echo "MD5: $md5"
echo "Expires: $expires"

스크립트를 실행할 시 현재 시각의 60초 뒤 UNIX Timestamp와 해당 UNIX Timestamp가 포함되어 있는 md5 해시값이 생성됩니다.

./generateSecureLinkAfter.sh

MD5: 6GR_IHCjqfzoZlnwFk8qsg
Expires: 1732514754

생성된 md5 해시와 UNIX Timstamp를 통해 ngx_http_secure_link_module 모듈이 적용된 NGINX 서버로 요청을 전송합니다.

$ curl '{NGINX SERVER IP}/download?md5=6GR_IHCjqfzoZlnwFk8qsg&expires=1732514754'

welcome to success page

60초 뒤 동일한 링크로 다시 요청을 하면, NGINX 설정에 따라 410 Status Code가 반환되는 것을 확인할 수 있습니다.

$ curl '{NGINX SERVER IP}/download?md5=6GR_IHCjqfzoZlnwFk8qsg&expires=1732514754' -I

HTTP/1.1 410 Gone
Server: nginx/1.25.5

3-2. 만료된 링크 처리

만료된 링크, 혹은 유효하지 않은 md5 해시를 포함하고 있는 링크는 특정 Status Code를 Return 합니다.

NGINX의 error_page 지시문을 통해 이러한 Error Status Code를 Handling 할 수 있습니다.

    # 에러 페이지 설정
    error_page 403 /access-denied.html;
    error_page 410 /link-expired.html;

    # 403 에러 페이지
    location = /access-denied.html {
        default_type text/html;
        return 200 "<h1>접근이 거부되었습니다. 유효한 링크를 사용하세요.</h1>\n";
    }

    # 410 에러 페이지
    location = /link-expired.html {
        default_type text/html;
        return 200 "<h1>링크가 만료되었습니다. 링크 유효기간을 확인하세요.</h1>\n";
    }

error_page 지시문 설정 이후 만료된 링크와 유효하지 않은 링크를 NGINX에 요청합니다.

$ curl 'localhost/download?md5=6GR_IHCjqfzoZlnwFk8qsg&expires=1732514754' # 만료된 md5 해시를 포함한 링크
<h1>링크가 만료되었습니다. 링크 유효기간을 확인하세요.</h1>

$ curl 'localhost/download?md5=invalid-md5&expires=1732514754' 유효하지 않은 md5 해시를 포함한 링크
<h1>접근이 거부되었습니다. 유효한 링크를 사용하세요.</h1>

4. ngx_http_secure_link_module 실사용 사례 및 활용 방법

4-1. 파일 다운로드 보호

ngx_http_secure_link_module은 파일 다운로드 링크를 보호하는 데 적합합니다. 이를 통해 다운로드 링크의 무단 공유나 무결성 위반을 방지할 수 있습니다. MD5 해시와 만료 기간을 포함하여 링크를 생성하고, 요청이 조작되거나 만료된 경우 접근을 자동으로 차단합니다.

구성 예시:

location /download {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$uri$secure_link_expires secret";

    if ($secure_link = "") {
        return 403;  # 변조된 링크
    }

    if ($secure_link = "0") {
        return 410;  # 만료된 링크
    }

    root /var/www/files;  # 파일 경로
}

동작 과정:

1. 사용자는 /download 경로에 대한 요청을 생성하며, 링크는 다음과 같은 형식으로 제공됩니다.

/download?md5=<hash>&expires=<time>

2. NGINX는 제공된 MD5 해시를 검증하여 링크가 조작되지 않았는지 확인합니다.
3. 만료 시간이 유효한 경우에만 요청을 허용합니다.
4. 링크가 조작되었거나 만료되었다면 HTTP 403 또는 410 상태 코드를 반환합니다.

이러한 구성은 파일 다운로드 서버에서 대용량 파일에 대한 비인가 접근을 방지하거나, 다운로드 링크의 유효 기간을 제한하고자 할 때 유용합니다.

4-2. 동적 콘텐츠 접근 제한

동적 콘텐츠는 요청마다 실시간으로 생성되므로, 적절한 접근 제한이 필수적입니다. ngx_http_secure_link_module을 사용하면 요청 링크의 무결성을 검증하여, 승인된 사용자만 콘텐츠에 접근할 수 있도록 할 수 있습니다.

구성 예시:

location /dynamic {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

    if ($secure_link = "") {
        return 403;  # 변조된 링크
    }

    if ($secure_link = "0") {
        return 410;  # 만료된 링크
    }

    proxy_pass http://backend;  # 동적 콘텐츠 처리 백엔드
}

동작 과정:

1. 클라이언트 요청 시, 서버는 사용자별 정보를 포함하여 다음 형식으로 링크를 생성합니다.

/dynamic?md5=<hash>&expires=<time>

2. NGINX는 요청된 링크가 사용자 IP와 일치하는지, 만료되지 않았는지 검증합니다.
3. 검증 성공 시 요청을 백엔드로 전달하여 콘텐츠를 생성합니다.
4. 잘못된 IP로 접근하거나 만료된 경우 HTTP 403 또는 410 상태 코드를 반환합니다.

적용 예시:

• 사용자 맞춤형 데이터 제공
• 실시간 데이터 스트림
• API 요청 보호

5. 결론

ngx_http_secure_link_module은 파일 다운로드 및 동적 콘텐츠 보호와 같은 다양한 시나리오에서 활용 가능한 강력한 보안 도구입니다. 이를 활용하면 링크의 무결성을 보장하고, 유효 기간을 관리하여 서버 리소스 보호와 사용자 데이터 보안을 동시에 달성할 수 있습니다. 추천 설정과 모범 사례를 기반으로 구성하면 보안 수준을 더욱 강화할 수 있습니다. 이 모듈은 NGINX 기반 시스템의 보안을 위한 필수 구성 요소로 자리 잡을 수 있습니다.

5-1. ngx_http_secure_link_module의 이점 요약

ngx_http_secure_link_module은 간단한 설정으로 다음과 같은 강력한 보안 기능을 제공합니다:

• 무결성 검증: MD5 해시를 사용하여 요청 링크가 조작되지 않았음을 보장합니다.
• 만료 시간 관리: 링크의 유효 기간을 설정하여, 기간 초과 시 자동으로 요청을 차단합니다.
• 유연한 설정: URI, IP 주소, 만료 시간 등 다양한 조건을 활용하여 사용자 맞춤형 검증 로직을 구현할 수 있습니다.
• 적용 범위: 정적 파일 다운로드, 동적 콘텐츠 접근 제한 등 다양한 시나리오에서 활용 가능합니다.

5-2. 추천 추가 설정 및 모범 사례

ngx_http_secure_link_module을 효과적으로 활용하기 위해 다음의 설정과 모범 사례를 추천합니다.

• 비밀 키 관리: secure_link_md5에서 사용되는 비밀 키는 외부에 노출되지 않도록 관리하고, 주기적으로 갱신합니다.
• HTTPS 사용: 민감한 정보(예: MD5 해시와 만료 시간)가 포함된 링크는 HTTPS를 통해 전송하여 네트워크 도청을 방지합니다.
• 로그 분석: error.log에 기록된 검증 실패 요청을 분석하여, 잠재적인 보안 위협을 탐지하고 대응합니다.
• 시간 동기화: 만료 시간 설정이 정확히 작동하도록 서버 시간을 정기적으로 동기화합니다.

ngx_http_secure_link_module 사용 사례와 같이 다양한 모듈을 통해 NGINX의 기능을 확장하고 싶으신가요? NGINX STORE 블로그의 NGINX 카테고리를 참고하여 다양한 모듈 사용 사례에 대해 알아보세요.