Crate rocket_csrf_token

rocket_csrf_token

The rocket_csrf_token crate is a powerful library that provides Cross-Site Request Forgery (CSRF) protection for Rocket web applications. With this library, you can seamlessly integrate CSRF protection into your Rust applications, securing them against CSRF attacks efficiently.

Quick Start

Get started with the rocket_csrf_token crate quickly by following these simple steps:

1. Add the rocket_csrf_token crate to your project’s Cargo.toml file:

[dependencies]
rocket_csrf_token = "0.3.2"

2. Import the library into your Rocket application code:

use rocket_csrf_token::{CsrfConfig, Fairing};

3. Initialize the CSRF protection with your custom configuration:

use rocket_csrf_token::{CsrfConfig, Fairing};
use rocket::{Rocket, Build, launch};

#[launch]
fn rocket() -> Rocket<Build> {
    rocket::build()
        .attach(Fairing::new(CsrfConfig::default()))
        // ...
}

4. Start securing your routes with CSRF protection using the provided functionality.

Key Features

The rocket_csrf_token crate offers a range of features to protect your Rocket web application from CSRF attacks:

• Customizable Configuration: Configure the CSRF token lifespan, cookie name, and token length according to your needs.
• Automatic CSRF Token Generation: Automatically generate and manage CSRF tokens for each request.
• Request Verification: Verify incoming requests for valid CSRF tokens to ensure their authenticity.

Usage

Configuration

You can customize the CSRF protection by configuring the CsrfConfig structure. The following code shows how to create a custom configuration:

use rocket_csrf_token::CsrfConfig;
use rocket::time::Duration;

fn main() {
    let csrf_config = CsrfConfig::default()
        .with_lifetime(Some(Duration::hours(2)))
        .with_cookie_name("my_csrf_token")
        .with_cookie_len(64);
    // ...
}

Rocket Fairing

The Fairing struct integrates CSRF protection into your Rocket application. You can attach the fairing during Rocket’s setup to enable CSRF protection:

use rocket_csrf_token::{CsrfConfig, Fairing};
use rocket::launch;

#[launch]
fn rocket() -> _ {
    rocket::build()
        .attach(Fairing::new(CsrfConfig::default()))
        // ...
}

Request Handling

Use the provided request guards and functionality to handle CSRF tokens within your routes:

use rocket_csrf_token::{CsrfToken, Fairing};
use rocket::{post, http::Status, form::Form, FromForm};

#[derive(FromForm)]
struct PostData {
    authenticity_token: String,
    data: String,
}

#[post("/secure-endpoint", data = "<form>")]
async fn secure_endpoint(token: CsrfToken, form: Form<PostData>) -> Result<(), Status> {
    // Verify the CSRF token and process the request
    if token.verify(&form.authenticity_token).is_ok() {
        // Request is valid, continue processing
        // ...
        Ok(())
    } else {
        // Handle the CSRF token verification failure
        Err(Status::Forbidden)
    }
}

GitHub Repository

You can access the source code for this library on GitHub.

Contributing

We actively welcome contributions and bug reports from the community. If you’d like to contribute, report a bug, or suggest an enhancement, please feel free to engage with the project on GitHub. Your contributions are invaluable in making this library better for everyone.

Structs

• CsrfConfig
  Configuration for Cross-Site Request Forgery (CSRF) protection. It allows you to customize settings related to CSRF token management, including token lifespan, cookie name, and token length.
• CsrfToken
  Structure to hold a CSRF token. This token can be used for generating authenticity tokens and verifying the authenticity of incoming requests.
• Fairing
  Rocket fairing for CSRF protection. This fairing is responsible for handling and managing CSRF tokens during Rocket application runtime.
• VerificationFailure
  Custom error type for CSRF token verification failure. It is returned when CSRF token verification fails during request processing.