CSRF

Fiber용 CSRF 미들웨어는 Cross-Site Request Forgery (CSRF) 공격에 대한 보호 기능을 제공합니다. RFC9110#section-9.2.1에서 'safe'로 정의된 메서드(GET, HEAD, OPTIONS, TRACE) 이외의 메서드를 사용하는 요청은 토큰을 사용하여 검증됩니다. 잠재적인 공격이 감지되면 미들웨어는 기본적으로 403 Forbidden 오류를 반환합니다.

이 미들웨어는 두 가지 Token Validation Patterns을 제공합니다: Double Submit Cookie Pattern (default)과 Synchronizer Token Pattern (with Session).

Defense In Depth 조치로, 이 미들웨어는 HTTPS 요청에 대해 Referer Checking을 수행합니다.

Token Generation

CSRF 토큰은 'safe' 요청에서 생성되며, 기존 토큰이 만료되었거나 아직 설정되지 않은 경우에도 생성됩니다. SingleUseToken이 true이면 토큰을 사용할 때마다 새 토큰이 생성됩니다. c.Locals(contextKey)를 사용하여 CSRF 토큰을 가져올 수 있습니다. 여기서 contextKey는 구성 내에서 정의됩니다.

Security Considerations

이 미들웨어는 CSRF 공격을 방지하도록 설계되었지만 XSS와 같은 다른 공격 벡터는 보호하지 않습니다. 다른 보안 조치와 함께 사용해야 합니다.

절대로 'safe' 메서드를 사용하여 데이터를 변경하지 마세요. 예를 들어 GET 요청을 사용하여 리소스를 수정하지 마세요. 이 미들웨어는 'safe' 메서드에 대한 CSRF 공격을 보호하지 않습니다.

Token Validation Patterns

Double Submit Cookie Pattern (Default)

기본적으로 미들웨어는 fiber.Storage 인터페이스를 사용하여 토큰을 생성하고 저장합니다. 이러한 토큰은 특정 사용자 세션에 연결되어 있지 않으며 Double Submit Cookie 패턴을 사용하여 검증됩니다. 토큰은 쿠키에 저장된 다음 요청의 헤더로 전송됩니다. 미들웨어는 쿠키 값과 헤더 값을 비교하여 토큰의 유효성을 검사합니다. 이는 사용자 세션을 필요로 하지 않는 안전한 패턴입니다.

권한 상태가 변경되면 이전에 발급된 토큰을 반드시 삭제하고 새 토큰을 생성해야 합니다. 자세한 내용은 Token Lifecycle Deleting Tokens을 참조하세요.

이 패턴을 사용할 때는 CookieSameSite 옵션을 Lax 또는 Strict로 설정하고 Extractor가 CsrfFromCookie가 아니며 KeyLookup이 cookie:<name>이 아닌지 확인하는 것이 중요합니다.

이 패턴을 사용할 때 이 미들웨어는 Storage 패키지를 사용하여 단일 인터페이스를 통해 다양한 데이터베이스를 지원합니다. Storage의 기본 구성은 데이터를 메모리에 저장합니다. 스토리지를 사용자 정의하려면 Custom Storage/Database를 참조하세요.

Synchronizer Token Pattern (with Session)

이 미들웨어를 사용자 세션과 함께 사용할 때는 세션 내에 토큰을 저장하도록 미들웨어를 구성할 수 있습니다. 사용자 세션을 사용할 때는 일반적으로 Double Submit Cookie 패턴보다 안전하므로 이 방법을 권장합니다.

이 패턴을 사용할 때는 권한 상태가 변경되면 세션을 다시 생성하는 것이 중요합니다. 이렇게 하면 토큰도 삭제됩니다. 자세한 내용은 Token Lifecycle을 참조하세요.

사전 세션이 필요하며 없으면 자동으로 생성됩니다. 세션의 존재 여부에 의존하지 않고 인증을 나타내는 세션 값을 사용하세요.

Defense In Depth

이 미들웨어를 사용할 때는 페이지를 HTTPS를 통해 제공하고 CookieSecure 옵션을 true로 설정하며 CookieSameSite 옵션을 Lax 또는 Strict로 설정하는 것이 좋습니다. 이렇게 하면 쿠키가 HTTPS를 통해서만 전송되고 외부 사이트의 요청에서는 전송되지 않습니다.

쿠키 접두사 __Host- 및 __Secure-를 사용하여 쿠키를 더욱 안전하게 보호할 수 있습니다. 이러한 접두사는 모든 브라우저에서 지원되는 것은 아니며 다른 제한 사항이 있습니다. 자세한 내용은 MDN#Set-Cookie#cookie_prefixes를 참조하세요.

이러한 접두사를 사용하려면 CookieName 옵션을 __Host-csrf_ 또는 __Secure-csrf_로 설정하세요.

Referer Checking

HTTPS 요청의 경우 이 미들웨어는 엄격한 레퍼러 검사를 수행합니다. 하위 도메인이 도메인에서 쿠키를 설정하거나 수정할 수 있더라도 해당 요청이 정확히 동일한 도메인에서 오지 않으므로 사용자가 애플리케이션에 게시하도록 강제할 수 없습니다.

CSRF로 보호되는 HTTPS 요청의 경우 항상 레퍼러 확인이 수행됩니다.

Referer 헤더는 JS Fetch API를 사용하여 요청을 포함하여 모든 최신 브라우저에서 자동으로 요청에 포함됩니다. 그러나 사용자 지정 클라이언트와 함께 이 미들웨어를 사용하는 경우 클라이언트가 유효한 Referer 헤더를 전송하는지 확인하는 것이 중요합니다.

Token Lifecycle

토큰은 만료되거나 삭제될 때까지 유효합니다. 기본적으로 토큰은 1시간 동안 유효하며 이후의 각 요청은 만료 시간을 1시간씩 연장합니다. 사용자가 만료 시간 동안 요청을 하지 않으면 토큰이 만료됩니다.

Token Reuse

기본적으로 토큰은 여러 번 사용될 수 있습니다. 토큰을 사용한 후 삭제하려면 SingleUseToken 옵션을 true로 설정하면 됩니다. 이렇게 하면 토큰이 사용된 후 삭제되고 다음 요청 시 새 토큰이 생성됩니다.

SingleUseToken을 사용하면 사용성 측면에서 타협이 필요하므로 기본적으로 활성화되어 있지 않습니다. 예를 들어 사용자가 여러 탭을 열어 두거나 뒤로 가기 버튼을 사용하는 경우 사용자 경험에 방해가 될 수 있습니다.

Deleting Tokens

권한 상태가 변경되면 CSRF 토큰을 반드시 삭제하고 새 토큰을 생성해야 합니다. 이는 handler.DeleteToken(c)을 호출하여 수행할 수 있습니다.

if handler, ok := app.AcquireCtx(ctx).Locals(csrf.ConfigDefault.HandlerContextKey).(*CSRFHandler); ok {
    if err := handler.DeleteToken(app.AcquireCtx(ctx)); err != nil {
        // handle error
    }
}

fiber 세션 미들웨어와 함께 이 미들웨어를 사용하는 경우 단순히 session.Destroy(), session.Regenerate() 또는 session.Reset()을 호출하여 세션 및 세션에 저장된 토큰을 삭제할 수 있습니다.

BREACH

토큰이 모든 요청의 헤더로 전송된다는 점에 유의해야 합니다. BREACH에 취약한 페이지에 토큰을 포함하면 공격자가 토큰을 추출할 수 있습니다. 이를 완화하려면 페이지가 HTTPS를 통해 제공되고 HTTP 압축이 비활성화되며 요청에 대한 속도 제한이 구현되어 있는지 확인하세요.

Signatures

func New(config ...Config) fiber.Handler

Examples

Fiber 웹 프레임워크의 일부인 미들웨어 패키지를 가져옵니다:

import (
    "github.com/gofiber/fiber/v2"
    "github.com/gofiber/fiber/v2/middleware/csrf"
)

Fiber 앱을 초기화한 후 다음 코드를 사용하여 미들웨어를 초기화할 수 있습니다:

// Initialize default config
app.Use(csrf.New())

// Or extend your config for customization
app.Use(csrf.New(csrf.Config{
    KeyLookup:      "header:X-Csrf-Token",
    CookieName:     "csrf_",
    CookieSameSite: "Lax",
    Expiration:     1 * time.Hour,
    KeyGenerator:   utils.UUIDv4,
}))

Config

속성

타입

설명

기본값

func(*fiber.Ctx) bool

Next는 true를 반환할 때 이 미들웨어를 건너뛰는 함수를 정의합니다.

nil

KeyLookup

string

KeyLookup은 요청에서 토큰을 추출하는 Extractor를 만드는 데 사용되는 "<source>:<key>" 형식의 문자열입니다. 가능한 값: "header:<name>", "query:<name>", "param:<name>", "form:<name>", "cookie:<name>". Extractor가 명시적으로 설정된 경우 무시됩니다.

"header:X-Csrf-Token"

CookieName

string

CSRF 쿠키의 이름입니다. 이 쿠키는 CSRF 키를 저장합니다.

"csrf_"

CookieDomain

string

CSRF 쿠키의 도메인입니다.

CookiePath

string

CSRF 쿠키의 경로입니다.

CookieSecure

bool

CSRF 쿠키가 보안 설정인지 여부를 나타냅니다.

false

CookieHTTPOnly

bool

CSRF 쿠키가 HTTP 전용인지 여부를 나타냅니다.

false

CookieSameSite

string

SameSite 쿠키의 값입니다.

"Lax"

CookieSessionOnly

bool

쿠키가 브라우저 세션에만 유지되어야 하는지 여부를 결정합니다. true로 설정하면 Expiration을 무시합니다.

false

Expiration

time.Duration

Expiration은 CSRF 토큰이 만료되기 전까지의 기간입니다.

1 * time.Hour

SingleUseToken

bool

SingleUseToken은 CSRF 토큰을 사용할 때마다 파기하고 새로운 토큰을 생성할지 여부를 나타냅니다. (TokenLifecycle 참조)

false

Storage

fiber.Storage

Store는 미들웨어의 상태를 저장하는 데 사용됩니다.

nil

Session

*session.Store

Session은 미들웨어의 상태를 저장하는 데 사용됩니다. 설정되면 Storage를 무시합니다.

nil

SessionKey

string

SessionKey는 세션 내에 토큰을 저장하는 데 사용되는 키입니다.

"fiber.csrf.token"

ContextKey

inteface{}

생성된 CSRF 토큰을 컨텍스트에 저장하는 컨텍스트 키입니다. 비어 있으면 토큰이 컨텍스트에 저장되지 않습니다.

KeyGenerator

func() string

KeyGenerator는 새 CSRF 토큰을 생성합니다.

utils.UUID

CookieExpires

time.Duration (Deprecated)

Deprecated: Expiration을 사용하세요.

*fiber.Cookie (Deprecated)

Deprecated: Cookie* 관련 필드를 사용하세요.

nil

TokenLookup

string (Deprecated)

Deprecated: KeyLookup을 사용하세요.

ErrorHandler

fiber.ErrorHandler

ErrorHandler는 fiber.Handler에서 오류가 반환될 때 실행됩니다.

DefaultErrorHandler

Extractor

func(*fiber.Ctx) (string, error)

Extractor는 CSRF 토큰을 반환합니다. 설정되면 KeyLookup 기반 Extractor 대신 사용됩니다.

Extractor based on KeyLookup

HandlerContextKey

interface{}

HandlerContextKey는 CSRF 핸들러를 컨텍스트에 저장하는 데 사용됩니다.

"fiber.csrf.handler"

Default Config

var ConfigDefault = Config{
    KeyLookup:         "header:" + HeaderName,
    CookieName:        "csrf_",
    CookieSameSite:    "Lax",
    Expiration:        1 * time.Hour,
    KeyGenerator:      utils.UUIDv4,
    ErrorHandler:      defaultErrorHandler,
    Extractor:         CsrfFromHeader(HeaderName),
    SessionKey:        "fiber.csrf.token",
    HandlerContextKey: "fiber.csrf.handler",
}

Recommended Config (with session)

fiber/middleware/session과 함께 이 미들웨어를 사용하여 세션 내에 CSRF 토큰을 저장하는 것이 좋습니다. 이는 일반적으로 기본 구성보다 더 안전합니다.

var ConfigDefault = Config{
    KeyLookup:         "header:" + HeaderName,
    CookieName:        "__Host-csrf_",
    CookieSameSite:    "Lax",
    CookieSecure:      true,
    CookieSessionOnly: true,
    CookieHTTPOnly:    true,
    Expiration:        1 * time.Hour,
    KeyGenerator:      utils.UUIDv4,
    ErrorHandler:      defaultErrorHandler,
    Extractor:         CsrfFromHeader(HeaderName),
    Session:           session.Store,
    SessionKey:        "fiber.csrf.token",
    HandlerContextKey: "fiber.csrf.handler",
}

Constants

const (
    HeaderName = "X-Csrf-Token"
)

Sentinel Errors

CSRF 미들웨어는 다양한 시나리오를 처리하고 오류를 효과적으로 전달하기 위해 sentinel 오류 집합을 활용합니다. 이러한 오류는 custom error handler 내에서 미들웨어에 의해 반환된 오류를 처리하는 데 사용할 수 있습니다.

Errors Returned to Error Handler

ErrTokenNotFound: CSRF 토큰을 찾을 수 없음을 나타냅니다.
ErrTokenInvalid: CSRF 토큰이 유효하지 않음을 나타냅니다.
ErrNoReferer: 레퍼러가 제공되지 않았음을 나타냅니다.
ErrBadReferer: 레퍼러가 유효하지 않음을 나타냅니다.

기본 오류 핸들러를 사용하면 클라이언트는 추가 정보 없이 403 Forbidden 오류를 수신합니다.

Custom Error Handler

CSRF 미들웨어에서 반환된 오류를 처리하기 위해 사용자 정의 오류 핸들러를 사용할 수 있습니다. 오류 핸들러는 미들웨어에서 오류가 반환될 때 실행됩니다. 오류 핸들러에는 미들웨어에서 반환된 오류와 fiber.Ctx가 전달됩니다.

예를 들어 API 요청에 대해 JSON 응답을 반환하고 다른 요청에 대해 오류 페이지를 렌더링하는 경우:

app.Use(csrf.New(csrf.Config{
    ErrorHandler: func(c *fiber.Ctx, err error) error {
        accepts := c.Accepts("html", "json")
        path := c.Path()
        if accepts == "json" || strings.HasPrefix(path, "/api/") {
            return c.Status(fiber.StatusForbidden).JSON(fiber.Map{
                "error": "Forbidden",
            })
        }
        return c.Status(fiber.StatusForbidden).Render("error", fiber.Map{
            "Title": "Forbidden",
            "Status": fiber.StatusForbidden,
        }, "layouts/main")
    },
}))

Custom Storage/Database

storage 패키지에서 제공하는 모든 스토리지를 사용할 수 있습니다.

storage := sqlite3.New() // From github.com/gofiber/storage/sqlite3
app.Use(csrf.New(csrf.Config{
    Storage: storage,
}))

PreviousCORS NextEarlyData

Last updated 9 months ago