Plexius-TSIG

Version: 0.6.0

Copyright (c) 2025 Fastcomcorp Licensed under the Apache License, Version 2.0

A Rust library for implementing TSIG (Transaction SIGnature) in DNS operations, providing secure message signing and verification capabilities.

Overview

Plexius-TSIG is a robust implementation of the TSIG protocol as defined in RFC 2845. It provides secure message signing and verification for DNS operations, ensuring message integrity and authenticity.

This library was specifically created to support Security Technical Implementation Guide (STIG) compliance for PlexiusDNS, addressing the critical need for secure zone transfers (AXFR/IXFR) between signed and authorized peers. By implementing TSIG, PlexiusDNS can now ensure that zone transfers are only performed between authenticated and authorized DNS servers, meeting strict security requirements for NIST compliance and other types of secure environments, while remaining lightweight and broadly useful for general-purpose DNS security.

The library also supports FIPS-compatible cryptography when configured to use HMAC-SHA256 exclusively. Legacy algorithms are provided for compatibility with existing systems, but should be disabled in FIPS environments.

Key security features that support STIG compliance:

• Secure zone transfer authentication
• Message integrity verification
• Replay attack prevention
• Timestamp validation
• Key rotation and management
• Audit logging capabilities

The library enables PlexiusDNS to meet the following STIG requirements:

• DNS zone transfer security
• Authentication of DNS transactions
• Protection against DNS cache poisoning
• Secure key management
• Audit trail for DNS operations

Features

• Support for HMAC algorithms with different security levels:
  • HMAC-SHA256 (256-bit security, recommended for most use cases including FIPS environments)
  • HMAC-SHA384 (384-bit security, for high-security requirements)
  • HMAC-SHA512 (512-bit security, maximum security level)
  • HMAC-SHA1 (legacy support, not recommended for new deployments)
  • HMAC-MD5 (legacy support, not recommended for new deployments)
• Thread-safe key management with improved security
• Comprehensive error handling with detailed error types
• Property-based and fuzz testing
• Async support (optional)
• Configurable security parameters
• Enhanced key rotation support
• GSS (Generic Security Services) integration
• TKEY (Transaction Key) support
• Zero-copy message handling
• Secure memory handling with zeroize
• Performance optimizations with rayon and parking_lot

Algorithm Selection and Security Levels

Plexius-TSIG supports multiple HMAC algorithms to accommodate different security requirements:

Recommended Algorithms

1. HMAC-SHA256 (Recommended Default)

   • 256-bit security level
   • FIPS 140-2/3 compliant
   • Optimal balance of security and performance
   • Recommended for most production environments
   • Suitable for FIPS environments

2. HMAC-SHA384 (High Security)

   • 384-bit security level
   • Recommended for high-security requirements
   • Suitable for environments requiring enhanced security
   • FIPS 140-2/3 compliant

3. HMAC-SHA512 (Maximum Security)

   • 512-bit security level
   • Maximum security level available
   • Recommended for environments with strict security requirements
   • FIPS 140-2/3 compliant

Legacy Algorithms (Not Recommended)

1. HMAC-SHA1

   • Legacy support only
   • Not recommended for new deployments
   • Maintained for backward compatibility

2. HMAC-MD5

   • Legacy support only
   • Not recommended for new deployments
   • Maintained for backward compatibility

Algorithm Selection Guidelines

• For new deployments, use HMAC-SHA256 as the default choice
• For FIPS environments, HMAC-SHA256 is the recommended algorithm
• For high-security requirements, consider HMAC-SHA384 or HMAC-SHA512
• Avoid using legacy algorithms (HMAC-SHA1, HMAC-MD5) in new deployments
• Consider performance impact when selecting stronger algorithms

Standards Compliance

RFC Compliance

• RFC 2845 - TSIG Protocol
  • HMAC-MD5 support
  • Message signing and verification
  • Time validation with fudge factor
  • Error response codes (BADSIG, BADKEY, BADTIME)
• RFC 4635 - HMAC-SHA TSIG Algorithm Identifiers
  • HMAC-SHA256 support
  • HMAC-SHA1 support
  • Algorithm validation
  • Key size requirements

Security Standards

• NIST SP 800-107 (HMAC)
  • Key size requirements
  • Algorithm validation
  • Security strength
• NIST SP 800-131A (Transitioning)
  • Algorithm recommendations
  • Key size requirements
  • Security parameters
• NIST SP 800-57 (Key Management)
  • Key rotation policies
  • Key storage requirements
  • Key lifecycle management

Trust-DNS Integration

• Full compatibility with Trust-DNS
• Wire format compliance
• Message handling compatibility
• Integration tests

Security Features

• Replay attack prevention
• Message integrity verification
• Timestamp validation
• Secure memory handling
• Key zeroization
• Thread-safe operations

STIG Compliance

Plexius-TSIG is designed to meet the security requirements specified in the Defense Information Systems Agency (DISA) Security Technical Implementation Guide (STIG) for DNS servers. This compliance is crucial for organizations operating in military, defense, and federal environments.

STIG Requirements Addressed

1. DNS Zone Transfer Security (SRG-APP-000516-DNS-000010)

   • Secure AXFR/IXFR operations
   • Authentication of zone transfer requests
   • Protection against unauthorized zone transfers

2. DNS Transaction Security (SRG-APP-000516-DNS-000020)

   • Message authentication
   • Transaction integrity
   • Replay attack prevention

3. Key Management (SRG-APP-000516-DNS-000030)

   • Secure key generation
   • Key rotation policies
   • Key storage security
   • Key distribution controls

4. Audit and Logging (SRG-APP-000516-DNS-000040)

   • Transaction logging
   • Security event tracking
   • Audit trail maintenance

Implementation Details

The library implements these requirements through:

1. Zone Transfer Protection

   // Example of secure zone transfer
   let config = SecurityConfig::new()
       .with_key_rotation(true)
       .with_rotation_period(90)
       .with_audit_logging(true);

2. Transaction Security

   // Example of secure transaction
   let message = TsigMessage::new()
       .with_type(MessageType::ZoneTransfer)
       .with_key(&key)?
       .with_timestamp(SystemTime::now())
       .with_fudge(300)?;

3. Audit Trail

   // Example of audit logging
   let audit_log = AuditLog::new()
       .with_event_type("zone_transfer")
       .with_source_ip("192.168.1.1")
       .with_key_name("zone-transfer-key")
       .with_timestamp(SystemTime::now());

Compliance Documentation

For detailed compliance information:

• STIG Requirements Matrix
• Security Controls Implementation Guide
• Audit Configuration Guide
• Compliance Checklist

Components

1. Key Management (TsigKey)

The TsigKey struct handles the creation and management of TSIG keys:

// Create a key
let mut key = TsigKey::new("key-name", "HMAC-SHA256", "base64-encoded-secret")?;

// Enable test mode for testing
key.enable_test_mode();

Key features:

• Key validation and expiration
• Algorithm selection
• Secure secret key management with zeroize
• Message signing and verification
• Test mode for development and testing
• Key rotation support

2. Message Handling (TsigMessage)

The TsigMessage struct manages DNS messages and their TSIG records:

let message = TsigMessage::new();
message.set_content(b"message content");

Features:

• Zero-copy message serialization/deserialization
• TSIG record management
• Message validation
• Wire format conversion
• Performance optimizations

3. Manager (TsigManager)

The TsigManager provides a thread-safe interface for key and message operations:

// Create manager with key rotation
let config = SecurityConfig::new()
    .with_key_rotation(true)
    .with_rotation_period(90);  // days

let manager = TsigManager::with_config(config);

// Add key with test mode
let mut key = TsigKey::new("key-name", "HMAC-SHA256", "secret")?;
key.enable_test_mode();
manager.add_key(key)?;

let signature = manager.sign_message(message, "key-name")?;

Features:

• Thread-safe key storage with parking_lot
• Enhanced key rotation support
• Message signing/verification
• Security configuration
• Performance optimizations with rayon
• GSS and TKEY integration

Security Features

1. Key Management

   • Configurable key size limits
   • Algorithm restrictions
   • Key expiration
   • Secure key storage with zeroize
   • Enhanced key rotation
   • GSS integration for enterprise environments

2. Message Security

   • HMAC-based message signing
   • Replay attack prevention
   • Message integrity verification
   • Timestamp validation
   • Test mode for security testing
   • TKEY support for dynamic key management

3. Performance & Memory Security

   • Zero-copy message handling
   • Secure memory management
   • Thread-safe operations
   • Performance optimizations
   • Memory leak prevention

Memory Protection

Plexius-TSIG implements multiple layers of memory protection to ensure sensitive data is handled securely:

1. Secure Memory Handling

• Automatic zeroization of sensitive data using the zeroize crate
• Secure wiping of cryptographic keys and secrets when no longer needed
• Protected memory regions for key storage
• Prevention of memory leaks for sensitive information

2. Zero-Copy Operations

• Zero-copy message serialization/deserialization
• Reduced memory allocations and copies
• Minimized attack surface for memory-related vulnerabilities
• Efficient byte buffer handling with the bytes crate

3. Thread-Safe Memory Operations

• Thread-safe memory access using parking_lot
• Protected concurrent memory operations
• Safe memory sharing between threads
• Prevention of race conditions

4. Memory Safety Testing

• Comprehensive fuzz testing for memory safety
• Property-based tests for memory management
• Memory leak detection in test suite
• Concurrent operation testing for memory safety

5. Key Management Memory Security

• Secure key storage with automatic zeroization
• Protected memory regions for key operations
• Secure key lifecycle management
• Memory-safe key rotation procedures

Memory Protection Use Cases

• FIPS-compliant environments
• Military and defense systems
• Financial institutions
• Healthcare systems
• High-security environments

Protected Against

• Memory leaks
• Buffer overflows
• Use-after-free vulnerabilities
• Data exposure in memory dumps
• Race conditions in memory access

Testing Strategy

The library includes several types of tests:

1. Unit Tests

• Basic functionality testing
• Error case handling
• Edge case validation
• Test mode verification
• GSS and TKEY integration tests

2. Property-Based Tests

• Random input generation
• Algorithm verification
• Key management properties
• Message signing properties
• Test mode scenarios
• Performance benchmarks

3. Fuzz Tests

• Random message generation
• Concurrent operation testing
• Error case exploration
• Edge case handling
• Key rotation testing
• Memory safety testing

4. Integration Tests

• End-to-end message flow
• Key rotation scenarios
• Network edge cases
• Performance testing
• Test mode integration
• GSS and TKEY scenarios

Usage Examples

Basic Usage

use plexius_tsig::{TsigKey, TsigManager, TsigMessage};

// Create a key with test mode
let mut key = TsigKey::new("test-key", "HMAC-SHA256", "base64-secret")?;
key.enable_test_mode();

// Create a manager
let manager = TsigManager::new();
manager.add_key(key)?;

// Create and sign a message
let message = TsigMessage::new();
let signature = manager.sign_message(&message.to_wire(), "test-key")?;

// Verify the message
let is_valid = manager.verify_message(&message.to_wire(), &signature, "test-key")?;

Key Rotation with GSS

use plexius_tsig::{TsigKey, TsigManager, SecurityConfig};

// Create manager with key rotation and GSS
let config = SecurityConfig::new()
    .with_key_rotation(true)
    .with_rotation_period(90)  // days
    .with_gss_enabled(true);

let manager = TsigManager::with_config(config);

// Add keys with GSS
let mut key1 = TsigKey::new("key1", "HMAC-SHA256", "secret1")?;
let mut key2 = TsigKey::new("key2", "HMAC-SHA256", "secret2")?;

key1.enable_gss();
key2.enable_gss();

manager.add_key(key1);
manager.add_key(key2);

Async Usage with TKEY

#[cfg(feature = "async")]
async fn async_example() -> Result<()> {
    let manager = TsigManager::new();
    let mut key = TsigKey::new("test-key", "HMAC-SHA256", "base64-secret")?;
    key.enable_tkey();
    
    manager.add_key_async(key).await?;
    let message = TsigMessage::new();
    let signature = manager.sign_message_async(&message.to_wire(), "test-key").await?;
    
    Ok(())
}

Configuration

The library can be configured through the SecurityConfig struct:

use plexius_tsig::config::SecurityConfig;

let config = SecurityConfig::new()
    .with_key_size_limits(16, 64)
    .with_allowed_algorithms(vec!["HMAC-SHA256".to_string()])
    .with_key_rotation(true)
    .with_rotation_period(90)
    .with_gss_enabled(true)
    .with_tkey_enabled(true)
    .with_test_mode(true);  // Enable test mode globally

let manager = TsigManager::with_config(config);

Error Handling

The library uses a custom error type TsigError for comprehensive error handling:

pub enum TsigError {
    InvalidKey(String),
    InvalidAlgorithm(String),
    InvalidMessage(String),
    KeyNotFound(String),
    KeyExists(String),
    TestModeRequired,
    GssError(String),
    TkeyError(String),
    // ... other error variants
}

Performance Considerations

• Zero-copy message handling for reduced memory usage
• Thread-safe operations with parking_lot
• Parallel processing with rayon
• Secure memory management with zeroize
• Optimized cryptographic operations
• Efficient key rotation

Contributing

Contributions are welcome! Please read our contributing guidelines and ensure all tests pass before submitting a pull request.

License

Copyright (c) 2025 Fastcomcorp

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.

Open Source Dependencies

This project uses several open source libraries. We would like to acknowledge and thank their authors:

Core Dependencies

• sha2 (MIT/Apache-2.0) - SHA-2 family of hash functions
• hmac (MIT/Apache-2.0) - HMAC implementation
• rand (MIT/Apache-2.0) - Random number generation
• base64 (MIT/Apache-2.0) - Base64 encoding/decoding
• zeroize (Apache-2.0) - Secure memory zeroing
• hkdf (MIT/Apache-2.0) - HMAC-based Key Derivation Function

DNS Protocol

• trust-dns-proto (MIT/Apache-2.0) - DNS protocol implementation
• trust-dns-resolver (MIT/Apache-2.0) - DNS resolver implementation

Performance & Concurrency

• bytes (MIT) - Efficient byte buffer handling
• parking_lot (Apache-2.0/MIT) - Efficient synchronization primitives
• crossbeam-channel (MIT/Apache-2.0) - Multi-producer, multi-consumer channels
• rayon (Apache-2.0/MIT) - Parallel iterator library

Async Runtime

• tokio (MIT) - Async runtime for Rust

Error Handling & Serialization

• thiserror (MIT/Apache-2.0) - Error handling utilities
• anyhow (MIT/Apache-2.0) - Error handling utilities
• serde (MIT/Apache-2.0) - Serialization framework
• serde_json (MIT/Apache-2.0) - JSON serialization

Logging

• tracing (MIT) - Application-level tracing
• tracing-subscriber (MIT) - Tracing subscriber implementation

Testing

• proptest (MIT/Apache-2.0) - Property testing framework
• criterion (Apache-2.0/MIT) - Statistics-driven benchmarking
• mockall (MIT/Apache-2.0) - Mocking library
• tempfile (MIT/Apache-2.0) - Temporary file utilities

For more details about each dependency's license and usage, please refer to their respective repositories and documentation.