Struct AuthService

pub struct AuthService {
    pub jwt_config: JwtConfig,
}

Authentication service that handles ECDSA challenge-based authentication

This service provides stateless authentication operations:

• Challenge generation for clients to sign
• Signature verification against challenges
• JWT token creation for authenticated sessions
• JWT token validation

The service does not store any state - developers must handle challenge storage and session management in their own systems.

Example

use ecdsa_jwt::{AuthService, JwtConfig};
use secrecy::Secret;
use base64::prelude::*;

let config = JwtConfig {
    secret: Secret::new(BASE64_STANDARD.encode("your-secret")),
    ttl: 3600, // 1 hour
};
let auth_service = AuthService::new(config);

Fields

jwt_config: JwtConfig

Implementations

impl AuthService

pub fn new(jwt_config: JwtConfig) -> Self

Create a new authentication service with the given JWT configuration

Arguments

• jwt_config - Configuration containing JWT secret and token lifetime

Example

use ecdsa_jwt::{auth::{AuthService},config::JwtConfig};
use secrecy::Secret;
use base64::prelude::*;

let config = JwtConfig {  
    secret: Secret::new(BASE64_STANDARD.encode("your-secret")),
    ttl: 3600, // 1 hour
};
let auth_service = AuthService::new(config);

Examples found in repository

examples/basic_workflow.rs (line 19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("ECDSA-JWT Basic Usage Example");

    // 1. Setup authentication service
    let jwt_config = JwtConfig {
        secret: Secret::new(BASE64_STANDARD.encode("example-secret-key")),
        ttl: 3600, // 1 hour
    };
    let auth_service = AuthService::new(jwt_config);

    // 2. Simulate challenge storage (in real app, use Redis/DB)
    let mut challenges: HashMap<String, String> = HashMap::new();

    // 3. Generate challenge
    let challenge = auth_service.generate_challenge();
    let session_id = "example-session-123";
    challenges.insert(session_id.to_string(), challenge.clone());

    println!("Generated challenge: {challenge}");
    println!("Stored with session ID: {session_id}");

    // 4. Simulate client authentication (this would normally fail without real signature)
    println!("\n Authentication attempt...");

    let auth_request = AuthRequest {
        challenge,
        signature: "dummy-signature-for-example".to_string(),
        public_key: "-----BEGIN PUBLIC KEY-----\nDummyKeyForExample\n-----END PUBLIC KEY-----"
            .to_string(),
    };

    // This will fail, but demonstrates the API structure
    match auth_service.authenticate(auth_request, false) {
        Ok(response) => {
            println!("Authentication successful!");
            println!("   JWT Token: {}", response.session_token);
            println!("   Session ID: {}", response.session_id);
            println!("   Expires at: {}", response.expires_at);
        }
        Err(e) => {
            println!(" Authentication failed (expected with dummy data): {e}");
            println!("   In real usage, provide valid signature and public key.");
        }
    }

    // 5. Demonstrate JWT validation with a real token
    println!("\nJWT Token Operations...");

    let session_id = uuid::Uuid::new_v4();
    let jwt_token = ecdsa_jwt::crypto::jwt::create_jwt(session_id, None, &auth_service.jwt_config)?;

    println!("Created JWT: {}...", &jwt_token[..50]);

    match auth_service.validate_session(&jwt_token) {
        Ok(claims) => {
            println!("Token validation successful!");
            println!("User/Session ID: {}", claims.sub);
            println!("Issued at: {}", claims.iat);
            println!("Expires at: {}", claims.exp);
        }
        Err(e) => {
            println!("Token validation failed: {e}");
        }
    }

    println!("\nExample completed! Check the documentation for real implementation details.");
    Ok(())
}

pub fn generate_challenge(&self) -> String

Generate a cryptographically secure random challenge

Creates a 32-byte random challenge encoded as base64. This challenge should be:

1. Sent to the client
2. Stored temporarily by the server (with expiration)
3. Signed by the client using their private key
4. Submitted back with the signature for verification

Returns

Base64-encoded 32-byte random challenge

Example

use ecdsa_jwt::{auth::{AuthService},config::JwtConfig};
use secrecy::Secret;
use base64::prelude::*;

let config = JwtConfig {  
    secret: Secret::new(BASE64_STANDARD.encode("your-secret")),
    ttl: 3600, // 1 hour
};
let auth_service = AuthService::new(config);
let challenge = auth_service.generate_challenge();
// Store this challenge with a session ID and expiration time
// Send challenge to client for signing

Examples found in repository

examples/basic_workflow.rs (line 25)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("ECDSA-JWT Basic Usage Example");

    // 1. Setup authentication service
    let jwt_config = JwtConfig {
        secret: Secret::new(BASE64_STANDARD.encode("example-secret-key")),
        ttl: 3600, // 1 hour
    };
    let auth_service = AuthService::new(jwt_config);

    // 2. Simulate challenge storage (in real app, use Redis/DB)
    let mut challenges: HashMap<String, String> = HashMap::new();

    // 3. Generate challenge
    let challenge = auth_service.generate_challenge();
    let session_id = "example-session-123";
    challenges.insert(session_id.to_string(), challenge.clone());

    println!("Generated challenge: {challenge}");
    println!("Stored with session ID: {session_id}");

    // 4. Simulate client authentication (this would normally fail without real signature)
    println!("\n Authentication attempt...");

    let auth_request = AuthRequest {
        challenge,
        signature: "dummy-signature-for-example".to_string(),
        public_key: "-----BEGIN PUBLIC KEY-----\nDummyKeyForExample\n-----END PUBLIC KEY-----"
            .to_string(),
    };

    // This will fail, but demonstrates the API structure
    match auth_service.authenticate(auth_request, false) {
        Ok(response) => {
            println!("Authentication successful!");
            println!("   JWT Token: {}", response.session_token);
            println!("   Session ID: {}", response.session_id);
            println!("   Expires at: {}", response.expires_at);
        }
        Err(e) => {
            println!(" Authentication failed (expected with dummy data): {e}");
            println!("   In real usage, provide valid signature and public key.");
        }
    }

    // 5. Demonstrate JWT validation with a real token
    println!("\nJWT Token Operations...");

    let session_id = uuid::Uuid::new_v4();
    let jwt_token = ecdsa_jwt::crypto::jwt::create_jwt(session_id, None, &auth_service.jwt_config)?;

    println!("Created JWT: {}...", &jwt_token[..50]);

    match auth_service.validate_session(&jwt_token) {
        Ok(claims) => {
            println!("Token validation successful!");
            println!("User/Session ID: {}", claims.sub);
            println!("Issued at: {}", claims.iat);
            println!("Expires at: {}", claims.exp);
        }
        Err(e) => {
            println!("Token validation failed: {e}");
        }
    }

    println!("\nExample completed! Check the documentation for real implementation details.");
    Ok(())
}

pub fn authenticate( &self, auth_request: AuthRequest, include_public_key: bool, ) -> Result<AuthResponse>

Authenticate a client by verifying their signed challenge

This is the core authentication method that:

1. Validates all input parameters
2. Decodes base64-encoded challenge and signature
3. Verifies the ECDSA signature using the provided public key
4. Creates and returns a JWT token on successful verification

Arguments

• auth_request - Contains challenge, signature, and public key

Returns

• Ok(AuthResponse) - Authentication successful, contains JWT token
• Err(AuthError) - Authentication failed with specific error details

Errors

• InvalidPublicKey - Public key is empty or malformed
• InvalidChallenge - Challenge is empty or invalid
• InvalidSignature - Signature is empty, malformed, or verification failed
• Base64Error - Challenge or signature has invalid base64 encoding
• CryptoError - Unexpected cryptographic operation failure

Example

use ecdsa_jwt::{auth::{AuthService, AuthRequest},config::JwtConfig};
use secrecy::Secret;
use base64::prelude::*;

let config = JwtConfig {  
    secret: Secret::new(BASE64_STANDARD.encode("your-secret")),
    ttl: 3600, // 1 hour
};

let auth_request = AuthRequest {
    challenge: "stored_challenge".to_string(),
    signature: "client_signature".to_string(),
    public_key: "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----".to_string(),
};
let auth_service = AuthService::new(config);
match auth_service.authenticate(auth_request, true) { // true = include public key in JWT
    Ok(response) => {
        println!("Authentication successful!");
        println!("JWT: {}", response.session_token);
    }
    Err(e) => println!("Authentication failed: {}", e),
}

Examples found in repository

examples/basic_workflow.rs (line 43)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("ECDSA-JWT Basic Usage Example");

    // 1. Setup authentication service
    let jwt_config = JwtConfig {
        secret: Secret::new(BASE64_STANDARD.encode("example-secret-key")),
        ttl: 3600, // 1 hour
    };
    let auth_service = AuthService::new(jwt_config);

    // 2. Simulate challenge storage (in real app, use Redis/DB)
    let mut challenges: HashMap<String, String> = HashMap::new();

    // 3. Generate challenge
    let challenge = auth_service.generate_challenge();
    let session_id = "example-session-123";
    challenges.insert(session_id.to_string(), challenge.clone());

    println!("Generated challenge: {challenge}");
    println!("Stored with session ID: {session_id}");

    // 4. Simulate client authentication (this would normally fail without real signature)
    println!("\n Authentication attempt...");

    let auth_request = AuthRequest {
        challenge,
        signature: "dummy-signature-for-example".to_string(),
        public_key: "-----BEGIN PUBLIC KEY-----\nDummyKeyForExample\n-----END PUBLIC KEY-----"
            .to_string(),
    };

    // This will fail, but demonstrates the API structure
    match auth_service.authenticate(auth_request, false) {
        Ok(response) => {
            println!("Authentication successful!");
            println!("   JWT Token: {}", response.session_token);
            println!("   Session ID: {}", response.session_id);
            println!("   Expires at: {}", response.expires_at);
        }
        Err(e) => {
            println!(" Authentication failed (expected with dummy data): {e}");
            println!("   In real usage, provide valid signature and public key.");
        }
    }

    // 5. Demonstrate JWT validation with a real token
    println!("\nJWT Token Operations...");

    let session_id = uuid::Uuid::new_v4();
    let jwt_token = ecdsa_jwt::crypto::jwt::create_jwt(session_id, None, &auth_service.jwt_config)?;

    println!("Created JWT: {}...", &jwt_token[..50]);

    match auth_service.validate_session(&jwt_token) {
        Ok(claims) => {
            println!("Token validation successful!");
            println!("User/Session ID: {}", claims.sub);
            println!("Issued at: {}", claims.iat);
            println!("Expires at: {}", claims.exp);
        }
        Err(e) => {
            println!("Token validation failed: {e}");
        }
    }

    println!("\nExample completed! Check the documentation for real implementation details.");
    Ok(())
}

pub fn validate_session(&self, token: &str) -> Result<Claims>

Validate a JWT session token

Verifies that a JWT token is:

• Properly formatted
• Signed with the correct secret
• Not expired
• Contains valid claims

Arguments

• token - JWT token string to validate

Returns

• Ok(Claims) - Token is valid, returns parsed claims
• Err(AuthError) - Token is invalid, expired, or malformed

Example

use ecdsa_jwt::{auth::{AuthService, AuthRequest},config::JwtConfig};
use secrecy::Secret;
use base64::prelude::*;

let config = JwtConfig {  
    secret: Secret::new(BASE64_STANDARD.encode("your-secret")),
    ttl: 3600, // 1 hour
};

let auth_service = AuthService::new(config);
let jwt_token = "token";
match auth_service.validate_session(&jwt_token) {
    Ok(claims) => {
        println!("Valid session for user: {}", claims.sub);
        // Allow access to protected resource
    }
    Err(_) => {
        println!("Invalid token - access denied");
        // Return 401 Unauthorized
    }
}

Examples found in repository

examples/basic_workflow.rs (line 64)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("ECDSA-JWT Basic Usage Example");

    // 1. Setup authentication service
    let jwt_config = JwtConfig {
        secret: Secret::new(BASE64_STANDARD.encode("example-secret-key")),
        ttl: 3600, // 1 hour
    };
    let auth_service = AuthService::new(jwt_config);

    // 2. Simulate challenge storage (in real app, use Redis/DB)
    let mut challenges: HashMap<String, String> = HashMap::new();

    // 3. Generate challenge
    let challenge = auth_service.generate_challenge();
    let session_id = "example-session-123";
    challenges.insert(session_id.to_string(), challenge.clone());

    println!("Generated challenge: {challenge}");
    println!("Stored with session ID: {session_id}");

    // 4. Simulate client authentication (this would normally fail without real signature)
    println!("\n Authentication attempt...");

    let auth_request = AuthRequest {
        challenge,
        signature: "dummy-signature-for-example".to_string(),
        public_key: "-----BEGIN PUBLIC KEY-----\nDummyKeyForExample\n-----END PUBLIC KEY-----"
            .to_string(),
    };

    // This will fail, but demonstrates the API structure
    match auth_service.authenticate(auth_request, false) {
        Ok(response) => {
            println!("Authentication successful!");
            println!("   JWT Token: {}", response.session_token);
            println!("   Session ID: {}", response.session_id);
            println!("   Expires at: {}", response.expires_at);
        }
        Err(e) => {
            println!(" Authentication failed (expected with dummy data): {e}");
            println!("   In real usage, provide valid signature and public key.");
        }
    }

    // 5. Demonstrate JWT validation with a real token
    println!("\nJWT Token Operations...");

    let session_id = uuid::Uuid::new_v4();
    let jwt_token = ecdsa_jwt::crypto::jwt::create_jwt(session_id, None, &auth_service.jwt_config)?;

    println!("Created JWT: {}...", &jwt_token[..50]);

    match auth_service.validate_session(&jwt_token) {
        Ok(claims) => {
            println!("Token validation successful!");
            println!("User/Session ID: {}", claims.sub);
            println!("Issued at: {}", claims.iat);
            println!("Expires at: {}", claims.exp);
        }
        Err(e) => {
            println!("Token validation failed: {e}");
        }
    }

    println!("\nExample completed! Check the documentation for real implementation details.");
    Ok(())
}

pub fn verify_signature_from_jwt( &self, jwt_token: &str, challenge: &[u8], signature: &[u8], ) -> Result<()>

Verify a signature using the public key from JWT claims

This method extracts the public key from the JWT and uses it to verify a signature, eliminating the need to pass the public key separately.

Arguments

• jwt_token - JWT token containing public key information
• challenge - Challenge bytes that were signed
• signature - Signature bytes to verify

Returns

• Ok(()) if signature is valid
• Err(AuthError) if verification fails

Example

use ecdsa_jwt::auth::AuthService;
use ecdsa_jwt::config::JwtConfig;
use secrecy::Secret;
use base64::prelude::*;

let jwt_config = JwtConfig {
    secret: Secret::new(BASE64_STANDARD.encode("test-secret")),
    ttl: 3600,
};
let auth_service = AuthService::new(jwt_config);

// This would normally be a real JWT token with embedded public key
let jwt_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...";
let challenge = b"challenge bytes";
let signature = &[0x30, 0x44, 0x02, 0x20]; // Example DER signature

// Note: This will fail with a real JWT that doesn't contain a public key
// This is just demonstrating the API usage
let _result = auth_service.verify_signature_from_jwt(jwt_token, challenge, signature);