io.vertx.ext.web.handler

## Interface CSRFHandler

- All Superinterfaces:
    Handler<RoutingContext>, InputTrustHandler

      public interface CSRFHandler
      extends InputTrustHandler

  This handler adds a CSRF token to requests which mutate state. In order change the state a (XSRF-TOKEN) cookie is set with a unique token, that is expected to be sent back in a (X-XSRF-TOKEN) header. The behavior is to check the request body header and cookie for validity. This Handler requires session support, thus should be added somewhere below Session and Body handlers.
  Author:
    Paulo Lopes

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `DEFAULT_COOKIE_NAME`
    `static String` | `DEFAULT_COOKIE_PATH`
    `static String` | `DEFAULT_HEADER_NAME`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static CSRFHandler` | `create(Vertx vertx, String secret)` Instantiate a new CSRFHandlerImpl with a secret
    `CSRFHandler` | `setCookieHttpOnly(boolean httpOnly)` Set the cookie `httpOnly` attribute.
    `CSRFHandler` | `setCookieName(String name)` Set the cookie name.
    `CSRFHandler` | `setCookiePath(String path)` Set the cookie path.
    `CSRFHandler` | `setCookieSecure(boolean secure)` Sets the cookie `secure` flag.
    `CSRFHandler` | `setHeaderName(String name)` Set the header name.
    `CSRFHandler` | `setNagHttps(boolean nag)` Should the handler give warning messages if this handler is used in other than https protocols?
    `CSRFHandler` | `setOrigin(String origin)` Set the origin for this server.
    `CSRFHandler` | `setTimeout(long timeout)` Set the timeout for tokens generated by the handler, by default it uses the default from the session handler.

    - ### Methods inherited from interface io.vertx.core.Handler

      `handle`

- - ### Field Detail

    - #### DEFAULT_COOKIE_NAME

          static final String DEFAULT_COOKIE_NAME

      See Also:
        Constant Field Values

    - #### DEFAULT_COOKIE_PATH

          static final String DEFAULT_COOKIE_PATH

      See Also:
        Constant Field Values

    - #### DEFAULT_HEADER_NAME

          static final String DEFAULT_HEADER_NAME

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### create

          static CSRFHandler create(Vertx vertx,
                                    String secret)

      Instantiate a new CSRFHandlerImpl with a secret

           CSRFHandler.create("s3cr37")

      Parameters:
        `secret` - server secret to sign the token.

    - #### setOrigin

          CSRFHandler setOrigin(String origin)

      Set the origin for this server. When this value is set, extra validation will occur. The request must match the origin server, port and protocol.
      Parameters:
        `origin` - the origin for this server e.g.: `https://www.foo.com`.
      Returns:
        fluent

    - #### setCookieName

          CSRFHandler setCookieName(String name)

      Set the cookie name. By default XSRF-TOKEN is used as it is the expected name by AngularJS however other frameworks might use other names.
      Parameters:
        `name` - a new name for the cookie.
      Returns:
        fluent

    - #### setCookiePath

          CSRFHandler setCookiePath(String path)

      Set the cookie path. By default / is used.
      Parameters:
        `path` - a new path for the cookie.
      Returns:
        fluent

    - #### setCookieHttpOnly

          CSRFHandler setCookieHttpOnly(boolean httpOnly)

      Set the cookie `httpOnly` attribute. When setting to `false` the CSRF handler will behave in Double Submit Cookie mode. When set to `true` then it will operate in Cookie-to-header mode. For more information https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie
      Parameters:
        `httpOnly` - a new name for the header.
      Returns:
        fluent

    - #### setCookieSecure

          CSRFHandler setCookieSecure(boolean secure)

      Sets the cookie `secure` flag. When set this flag instructs browsers to only send the cookie over HTTPS.
      Parameters:
        `secure` - true to set the secure flag on the cookie
      Returns:
        a reference to this, so the API can be used fluently

    - #### setHeaderName

          CSRFHandler setHeaderName(String name)

      Set the header name. By default X-XSRF-TOKEN is used as it is the expected name by AngularJS however other frameworks might use other names.
      Parameters:
        `name` - a new name for the header.
      Returns:
        fluent

    - #### setNagHttps

          CSRFHandler setNagHttps(boolean nag)

      Should the handler give warning messages if this handler is used in other than https protocols?
      Parameters:
        `nag` - true to nag
      Returns:
        fluent

    - #### setTimeout

          CSRFHandler setTimeout(long timeout)

      Set the timeout for tokens generated by the handler, by default it uses the default from the session handler.
      Parameters:
        `timeout` - token timeout
      Returns:
        fluent

Copyright © 2023 Eclipse. All rights reserved.