licensingpy 1.0.0

🔐 Secure offline licensing system with beautiful CLI, ECDSA signatures, and hardware fingerprinting

🔐 LicensingPy - Professional Offline Licensing System

A professional, secure offline licensing solution with beautiful CLI, ECDSA signatures, and hardware fingerprinting.

✨ Features

• 🔒 ECDSA P-256 Signatures - Cryptographically secure license verification
• 🖥️ Hardware Fingerprinting - Bind licenses to specific machines (MAC, disk, CPU, system, composite)
• 🧩 Component-Based Licensing - Separate licenses for different modules/components
• 🌱 Secure Preseed System - File-based secret management with SHA-256 hashing
• 🎨 Beautiful Rich CLI - Colorful, interactive command-line interface with progress bars
• 🐧 Cross-Platform - Windows, Linux, macOS with native fallbacks
• 🌐 Offline Operation - No internet connection required for license operations
• 🛡️ Tamper Resistant - Licenses cannot be modified, copied, or forged
• ⚡ Auto-Verification - Automatic license discovery and batch validation
• 📦 Zero Dependencies - Optional hardware detection libraries with native fallbacks
• 🧪 Comprehensive Tests - 111+ test cases with high coverage
• 📚 Complete Documentation - Detailed guides and API documentation

📦 Installation

Using pip (Recommended)

pip install licensingpy

Using Poetry

poetry add licensingpy

With Optional Hardware Detection

For enhanced hardware detection capabilities:

pip install "licensingpy[hardware]"
# or
poetry add licensingpy -E hardware

Development Installation

git clone https://github.com/licensingpy/licensingpy.git
cd licensingpy
poetry install --with dev,test

🚀 Quick Start Guide

Step 1: Generate Preseed File

The preseed file contains secret content that secures your licenses:

licensingpy generate-preseed --project-name "MyAwesomeApp" --description "Production preseed for MyApp" --output my_app_preseed.json

Output:

✓ Preseed file generated: my_app_preseed.json
✓ Secret length: 64 characters
✓ File size: 285 bytes

🔐 SECURITY NOTES:
   • Keep my_app_preseed.json secure and confidential
   • Do NOT commit my_app_preseed.json to version control
   • Back up my_app_preseed.json safely

Step 2: Generate Cryptographic Keys

licensingpy generate-keys --format json --output my_app_keys.json

Output:

✓ Key pair generated successfully
✓ Keys saved to my_app_keys.json

🔐 SECURITY NOTES:
- Keep the private key secure and confidential
- The public key can be distributed with your application

Step 3: Generate a License

licensingpy generate-license --private-key my_app_keys.json --preseed-file my_app_preseed.json --app-name "MyAwesomeApp" --version "2.1.0" --component-name "CoreEngine" --customer "Acme Corporation" --expires "2025-12-31" --output customer_license.txt

Output:

✓ Loaded preseed from: my_app_preseed.json
Generating license (expires: 2025-12-31)...
Hardware fingerprint (composite): 4e120bb4a65e...

License generated successfully!
License Details:
   Fingerprint Type: composite
   Expiry Date: 2025-12-31
   Component Name: CoreEngine
   App Name: MyAwesomeApp
   App Version: 2.1.0
   Customer: Acme Corporation

✓ License saved to: customer_license.txt

Step 4: Verify the License

licensingpy verify-license --public-key my_app_keys.json --preseed-file my_app_preseed.json --license customer_license.txt --verbose

Output:

✓ Loaded preseed from: my_app_preseed.json
✓ Loaded license from: customer_license.txt

LICENSE IS VALID AND ACTIVE
✓ Signature verification: PASSED
✓ Hardware fingerprint: MATCHED
✓ License expiry: NOT EXPIRED
✓ Component verification: PASSED

💻 Using in Your Python Code

Basic License Verification

from licensing import LicenseManager, PreseedGenerator

# Load your keys and preseed
def load_app_credentials():
    """Load your app's licensing credentials."""
    import json
    
    # Load public key
    with open('my_app_keys.json', 'r') as f:
        keys = json.load(f)
        public_key = keys['public_key']
    
    # Load and hash preseed
    preseed_hash = PreseedGenerator.load_preseed_from_file('my_app_preseed.json')
    
    return public_key, preseed_hash

# Verify a single license
def verify_license(license_string):
    """Verify a license string."""
    try:
        public_key, preseed_hash = load_app_credentials()
        manager = LicenseManager(public_key, preseed_hash)
        
        # Verify the license
        license_data = manager.verify_license(license_string)
        
        print("✅ License is valid!")
        print(f"App: {license_data.get('app_name')}")
        print(f"Component: {license_data.get('component_name')}")
        print(f"Customer: {license_data.get('customer')}")
        print(f"Expires: {license_data.get('expiry')}")
        
        return True
        
    except Exception as e:
        print(f"❌ License verification failed: {e}")
        return False

# Example usage
if __name__ == "__main__":
    # Load license from file
    with open('customer_license.txt', 'r') as f:
        license_string = f.read().strip()
    
    if verify_license(license_string):
        print("🎉 Application can start!")
    else:
        print("🚫 Application access denied!")

Auto-Discovery License Verification

from licensing import auto_verify_licenses

def check_all_licenses():
    """Automatically find and verify all licenses in current directory."""
    
    # Auto-discover and verify licenses
    results = auto_verify_licenses()
    
    if "error" in results:
        print(f"❌ Error: {results['error']}")
        return False
    
    summary = results['summary']
    print(f"📊 License Summary:")
    print(f"   Total found: {summary['total_licenses']}")
    print(f"   ✅ Valid: {summary['valid_count']}")
    print(f"   ❌ Invalid: {summary['invalid_count']}")
    print(f"   ⏰ Expired: {summary['expired_count']}")
    
    # Show valid licenses
    for license_data in results['valid_licenses']:
        print(f"\n📄 Valid License:")
        print(f"   App: {license_data.get('app_name', 'N/A')}")
        print(f"   Component: {license_data.get('component_name', 'N/A')}")
        print(f"   Customer: {license_data.get('customer', 'N/A')}")
        print(f"   Expires: {license_data.get('expiry', 'N/A')}")
    
    return summary['valid_count'] > 0

# Example usage
if __name__ == "__main__":
    if check_all_licenses():
        print("🎉 Valid licenses found - application authorized!")
    else:
        print("🚫 No valid licenses found - access denied!")

Component-Specific License Checking

from licensing import LicenseManager, PreseedGenerator

class ComponentLicenseManager:
    """Manage licenses for different application components."""
    
    def __init__(self, public_key_file, preseed_file):
        # Load credentials
        import json
        with open(public_key_file, 'r') as f:
            keys = json.load(f)
            self.public_key = keys['public_key']
        
        self.preseed_hash = PreseedGenerator.load_preseed_from_file(preseed_file)
        self.manager = LicenseManager(self.public_key, self.preseed_hash)
        
        # Cache for verified licenses
        self.verified_components = {}
    
    def verify_component_license(self, license_file, required_component):
        """Verify license for a specific component."""
        
        # Check cache first
        if required_component in self.verified_components:
            return self.verified_components[required_component]
        
        try:
            # Load license
            with open(license_file, 'r') as f:
                license_string = f.read().strip()
            
            # Verify license
            license_data = self.manager.verify_license(license_string)
            
            # Check component match
            license_component = license_data.get('component_name', '')
            if license_component != required_component:
                print(f"❌ Component mismatch: need '{required_component}', got '{license_component}'")
                return False
            
            # Cache successful verification
            self.verified_components[required_component] = license_data
            
            print(f"✅ Component '{required_component}' licensed to: {license_data.get('customer')}")
            return True
            
        except Exception as e:
            print(f"❌ Component '{required_component}' license verification failed: {e}")
            return False
    
    def require_license(self, component_name):
        """Decorator to require license for a component."""
        def decorator(func):
            def wrapper(*args, **kwargs):
                if not self.verify_component_license('license.txt', component_name):
                    raise PermissionError(f"No valid license for component '{component_name}'")
                return func(*args, **kwargs)
            return wrapper
        return decorator

# Example usage
license_manager = ComponentLicenseManager('my_app_keys.json', 'my_app_preseed.json')

@license_manager.require_license('DatabaseEngine')
def access_database():
    """This function requires a valid DatabaseEngine license."""
    print("🗄️ Accessing database with licensed engine...")
    # Your database code here

@license_manager.require_license('ReportGenerator')  
def generate_reports():
    """This function requires a valid ReportGenerator license."""
    print("📊 Generating reports with licensed engine...")
    # Your reporting code here

# Use the licensed functions
try:
    access_database()      # Requires DatabaseEngine license
    generate_reports()     # Requires ReportGenerator license
except PermissionError as e:
    print(f"🚫 Access denied: {e}")

Advanced License Validation

from licensing import LicenseManager, PreseedGenerator
from datetime import datetime, timedelta

def advanced_license_check(license_file, preseed_file, public_key_file):
    """Advanced license validation with detailed reporting."""
    
    try:
        # Load credentials
        import json
        with open(public_key_file, 'r') as f:
            keys = json.load(f)
            public_key = keys['public_key']
        
        preseed_hash = PreseedGenerator.load_preseed_from_file(preseed_file)
        manager = LicenseManager(public_key, preseed_hash)
        
        # Load license
        with open(license_file, 'r') as f:
            license_string = f.read().strip()
        
        # Get license info without full validation
        license_info = manager.get_license_info(license_string)
        
        print("📋 License Information:")
        print(f"   App: {license_info.get('app_name', 'N/A')}")
        print(f"   Version: {license_info.get('app_version', 'N/A')}")
        print(f"   Component: {license_info.get('component_name', 'N/A')}")
        print(f"   Customer: {license_info.get('customer', 'N/A')}")
        print(f"   Issued: {license_info.get('issued', 'N/A')}")
        print(f"   Expires: {license_info.get('expiry', 'N/A')}")
        
        # Check expiry details
        days_left = manager.get_days_until_expiry(license_string)
        if days_left is not None:
            if days_left > 0:
                print(f"   ⏰ Days remaining: {days_left}")
                if days_left <= 30:
                    print("   ⚠️  License expiring soon!")
            else:
                print(f"   💀 License expired {abs(days_left)} days ago")
        
        # Show status details
        status = license_info.get('status', {})
        print(f"\n🔍 Verification Status:")
        print(f"   Signature: {'✅ VALID' if not status.get('signature_invalid') else '❌ INVALID'}")
        print(f"   Hardware: {'✅ MATCH' if status.get('hardware_matches') else '❌ MISMATCH'}")
        print(f"   Expiry: {'✅ ACTIVE' if not status.get('is_expired') else '❌ EXPIRED'}")
        print(f"   Preseed: {'✅ VALID' if status.get('preseed_valid') else '❌ INVALID'}")
        
        # Attempt full verification
        print(f"\n🛡️ Full Verification:")
        try:
            verified_license = manager.verify_license(license_string)
            print("✅ LICENSE IS FULLY VALID AND ACTIVE")
            return True
        except Exception as e:
            print(f"❌ Full verification failed: {e}")
            return False
            
    except Exception as e:
        print(f"❌ License check failed: {e}")
        return False

# Example usage
if __name__ == "__main__":
    is_valid = advanced_license_check(
        license_file='customer_license.txt',
        preseed_file='my_app_preseed.json', 
        public_key_file='my_app_keys.json'
    )
    
    if is_valid:
        print("\n🎉 Application startup authorized!")
    else:
        print("\n🚫 Application startup denied!")

🛠️ CLI Reference

Generate Preseed File

licensingpy generate-preseed [OPTIONS]

Options:
  -o, --output PATH     Output file (default: preseed.json)
  -l, --length INTEGER  Secret length in characters (default: 64)
  --project-name TEXT   Project name for metadata
  --description TEXT    Description for metadata

Generate Keys

licensingpy generate-keys [OPTIONS]

Options:
  -o, --output PATH           Output file for keys
  --format [json|text]        Output format (default: text)

Generate License

licensingpy generate-license [OPTIONS]

Required:
  -k, --private-key PATH      Private key file
  -p, --preseed-file PATH     Preseed file

Options:
  -e, --expires TEXT          Expiry date (YYYY-MM-DD) or days (30d)
  -f, --fingerprint-type      Hardware fingerprint type
  -t, --target-hardware PATH  Generate for specific hardware
  --app-name TEXT             Application name
  --version TEXT              Application version  
  --customer TEXT             Customer name
  -c, --component-name TEXT   Component/module name
  -o, --output PATH           Output license file

Verify License

licensingpy verify-license [OPTIONS]

Required:
  -k, --public-key PATH       Public key file
  -p, --preseed-file PATH     Preseed file
  -l, --license PATH          License file or string

Options:
  --skip-hardware             Skip hardware verification
  --skip-expiry               Skip expiry verification
  -v, --verbose               Show detailed information

Demo Workflow

licensingpy demo

📁 File Structure

After following the quick start guide, you'll have:

your_project/
├── my_app_preseed.json     # Secret preseed file (keep secure!)
├── my_app_keys.json        # Public/private keys
├── customer_license.txt    # Generated license
└── your_application.py     # Your app with license verification

🔒 Security Best Practices

1. Preseed File Security

• ✅ Keep preseed files secure - treat like passwords
• ✅ Never commit to version control - add to .gitignore
• ✅ Back up safely - store in secure location
• ✅ Use different preseeds for different products/versions

2. Key Management

• ✅ Private keys - Keep secret, use for license generation only
• ✅ Public keys - Can be distributed with your application
• ✅ Separate environments - Different keys for dev/staging/prod

3. License Distribution

• ✅ Unique licenses - Generate separate license for each customer
• ✅ Component isolation - Use different component names for modules
• ✅ Expiry dates - Set appropriate expiration dates
• ✅ Hardware binding - Bind to customer's specific hardware

4. Application Integration

• ✅ Fail securely - Deny access if license verification fails
• ✅ Cache verification - Avoid re-verifying same license repeatedly
• ✅ Component separation - Check licenses for specific features
• ✅ User feedback - Provide clear messages for license issues

🆘 Troubleshooting

License Verification Fails

Hardware Mismatch:

# Skip hardware check for testing
licensingpy verify-license --skip-hardware ...

License Expired:

# Check expiry date
licensingpy verify-license --verbose ...

Invalid Signature:

• Ensure you're using the correct preseed file
• Verify the public key matches the private key used for generation

Auto-Discovery Issues

No licenses found:

• Ensure license files are in current directory
• Check file naming: license.txt, *.license, etc.

No keys found:

• Ensure key files are present: keys.json, public_key.txt, etc.

📞 Support

For issues and questions:

1. Check this README for common solutions
2. Review the example code above
3. Test with the demo command: licensingpy demo
4. Verify your file structure and permissions

🎯 Example Project Structure

# main.py - Your application entry point
from licensing import LicenseManager, PreseedGenerator

def startup_license_check():
    """Check license before starting application."""
    try:
        # Load credentials
        import json
        with open('app_keys.json', 'r') as f:
            public_key = json.load(f)['public_key']
        
        preseed_hash = PreseedGenerator.load_preseed_from_file('app_preseed.json')
        manager = LicenseManager(public_key, preseed_hash)
        
        # Verify license
        with open('license.txt', 'r') as f:
            license_string = f.read().strip()
        
        license_data = manager.verify_license(license_string)
        
        print(f"✅ Licensed to: {license_data.get('customer')}")
        print(f"📱 App: {license_data.get('app_name')} v{license_data.get('app_version')}")
        print(f"🧩 Component: {license_data.get('component_name')}")
        
        return True
        
    except Exception as e:
        print(f"❌ License verification failed: {e}")
        return False

if __name__ == "__main__":
    if startup_license_check():
        print("🚀 Starting application...")
        # Your application code here
    else:
        print("🚫 Application startup denied - invalid license")
        exit(1)

---

🎉 You're now ready to integrate secure offline licensing into your Python applications!