Module auth

dmsc::c

Module auth 

Source
Expand description

Copyright © 2025-2026 Wenze Wei. All Rights Reserved.

This file is part of DMSC. The DMSC project belongs to the Dunimd Team.

Licensed under the Apache License, Version 2.0 (the “License”); You may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

§Auth Module C API

This module provides C language bindings for DMSC’s authentication and authorization subsystem. The authentication module is responsible for handling user authentication, session management, permission verification, and OAuth authentication flows. This C API enables C/C++ applications to integrate with DMSC’s security features without requiring Rust runtime dependencies.

§Module Architecture

The authentication module consists of five primary components:

  • DMSCAuthConfig: Centralized configuration container for authentication parameters. Manages JWT secret keys, session timeouts, token expiration settings, and OAuth provider configurations. This configuration object is required for initializing authentication managers and controls security policy enforcement across the system.

  • DMSCJWTManager: JSON Web Token (JWT) generation and validation handler. Provides token creation with custom claims, signature verification using HMAC-SHA256, expiration checking, and audience validation. The JWT manager supports both access tokens and refresh tokens with configurable expiration periods. It implements RFC 7519 specification for secure stateless authentication in distributed systems.

  • DMSCSessionManager: Server-side session state management for stateful authentication. Maintains active user sessions in memory with configurable timeout policies. Supports session creation, validation, renewal, and invalidation. The session manager uses DashMap for thread-safe concurrent access in multi-threaded server environments.

  • DMSCPermissionManager: Role-based access control (RBAC) permission evaluator. Manages user roles, permissions, and resource access policies. Supports hierarchical role definitions with permission inheritance. The permission manager provides efficient permission checking for high-throughput authorization decisions.

  • DMSCOAuthManager: OAuth 2.0 authentication flow handler for third-party integrations. Implements authorization code flow for web applications, implicit flow for single-page applications, and client credentials flow for machine-to-machine communication. Supports multiple OAuth providers with configurable redirect URIs and scope requirements.

§Memory Management

All C API objects use opaque pointers with manual memory management. The caller is responsible for freeing allocated objects using the provided destructor functions. Objects must not be used after being freed to prevent use-after-free vulnerabilities. Null pointer checks must be performed before accessing any object methods or fields.

§Thread Safety

All underlying Rust implementations use synchronization primitives appropriate for concurrent access. The C API itself is not thread-safe; callers must implement their own synchronization when accessing objects from multiple threads simultaneously.

§Error Handling

Functions return null pointers or error codes (-1) to indicate failure conditions. Callers should check return values and handle errors appropriately. Memory allocation failures and invalid arguments are the primary error conditions.

§Usage Example

// Create authentication configuration
CDMSCAuthConfig* config = dmsc_auth_config_new();

// Create JWT manager with secret and expiration
CDMSCJWTManager* jwt = dmsc_jwt_manager_new("your-secret-key", 3600);

// Generate token for authenticated user
const char* token = dmsc_jwt_manager_generate(jwt, "user-id", "admin");

// Validate token on subsequent requests
bool valid = dmsc_jwt_manager_validate(jwt, token);

// Cleanup resources
dmsc_jwt_manager_free(jwt);
dmsc_auth_config_free(config);

§Dependencies

This module depends on the following core DMSC modules:

  • crate::auth: Rust implementation of authentication logic
  • crate::prelude: Common types and traits

§Feature Flags

The authentication module is enabled by default with the “auth” feature flag. Disable this feature to reduce binary size in deployments that do not require authentication capabilities.

Structs§

CDMSCAuthConfig
CDMSCJWTManager
CDMSCOAuthManager
CDMSCPermissionManager
CDMSCSessionManager

Functions§

dmsc_auth_config_free
dmsc_auth_config_new
dmsc_jwt_manager_free
dmsc_jwt_manager_new
Creates a new CDMSCJWTManager instance with specified secret and expiration.
dmsc_permission_manager_free
dmsc_permission_manager_new
Creates a new CDMSCPermissionManager instance.
dmsc_session_manager_free
dmsc_session_manager_new
Creates a new CDMSCSessionManager instance with specified session timeout.