compatibility

OpenSSL Compatibility Framework

This directory contains comprehensive compatibility tests ensuring perfect interoperability between GoPKI and OpenSSL for all cryptographic operations.

Overview

The OpenSSL compatibility framework validates that cryptographic operations, certificates, signatures, and key operations generated by GoPKI are fully compatible with OpenSSL and vice versa. This ensures that GoPKI can be used as a drop-in replacement for OpenSSL operations in Go applications.

Structure

compatibility/
├── keypair/            # Keypair compatibility tests
│   ├── keypair_test.go # RSA, ECDSA, Ed25519 key compatibility tests
│   ├── ssh_test.go     # SSH/OpenSSH compatibility tests
│   ├── doc.md         # Detailed keypair compatibility documentation
│   └── ssh_doc.md     # SSH compatibility documentation
├── cert/               # Certificate compatibility tests
│   ├── cert_test.go    # X.509 certificate compatibility tests
│   ├── doc.md         # Certificate compatibility documentation
│   └── testdata/       # Test certificates and reference data
├── signing/            # Digital signature compatibility tests
│   ├── signing_test.go # PKCS#7/CMS signature compatibility tests
│   ├── doc.md         # Comprehensive signing compatibility documentation
│   └── README.md      # Quick signing compatibility reference
├── helpers.go          # OpenSSL integration utilities
└── README.md          # This overview

Quick Start

Run All Compatibility Tests

# Using Taskfile (recommended)
task test:compatibility

# Direct Go command
go test -tags=compatibility ./compatibility/... -v

Run Specific Module Tests

# Keypair-specific tests only
go test -tags=compatibility ./compatibility/keypair -v

# Certificate-specific tests only
go test -tags=compatibility ./compatibility/cert -v

# Signing-specific tests only
go test -tags=compatibility ./compatibility/signing -v

Test Coverage

✅ Keypair Compatibility (./keypair/)

• RSA: 2048, 3072, 4096-bit keys
• ECDSA: P-256, P-384, P-521 curves
• Ed25519: Modern high-performance curve
• Bidirectional testing: GoPKI ↔ OpenSSL
• Format validation: PEM, DER, SSH
• Signature interoperability: Cross-platform verification

✅ Certificate Compatibility (./cert/)

• Self-Signed Certificates: All algorithms with OpenSSL validation
• CA Certificates: Path length constraints and CA extensions
• Certificate Signing: CA-signed certificates with chain validation
• Subject Alternative Names: DNS, IP, email address extensions
• Format Interoperability: PEM ↔ DER conversion
• Certificate Chain Validation: Multi-level certificate hierarchies
• Edge Cases: Invalid certificates, expired certificates

✅ Signing Compatibility (./signing/)

• Raw Signatures: RSA, ECDSA, Ed25519 signature generation and verification
• PKCS#7/CMS Formats: Attached and detached signature containers
• Certificate Chain Integration: Multi-level certificate inclusion
• Bidirectional Testing: GoPKI ↔ OpenSSL signature validation
• Hash Algorithms: SHA256, SHA384, SHA512 support
• Format Standards: RFC 5652 CMS compliance validation
• Advanced Features: Signature metadata extraction and validation

🔮 Future Compatibility Tests

As GoPKI grows, additional compatibility tests will be organized here:

• ./encryption/ - Encryption/decryption compatibility
• ./pkcs12/ - PKCS#12 container compatibility

Features

• Enhanced Logging: Every OpenSSL command execution is logged with results
• Testify Assertions: Clean, readable test assertions
• Automatic Cleanup: Temporary files are properly managed
• Cross-Platform: Works with OpenSSL 3.x, 1.1.1, LibreSSL
• Security Validation: Ensures cryptographic correctness
• Build Tags: Uses //go:build compatibility for conditional testing

Build Tags

The compatibility tests use build tags to allow conditional execution:

# Include compatibility tests
go test -tags=compatibility ./compatibility/... -v

# Regular tests (excludes compatibility tests)
go test ./compatibility/... -v  # Will find no test files

This allows for:

• Conditional Testing: Compatibility tests only run when explicitly tagged
• CI/CD Flexibility: Can skip expensive OpenSSL tests in certain environments
• Development Workflow: Developers can run regular tests without OpenSSL dependency

Sample Output

🔗 Running OpenSSL Compatibility Tests...
   This tests interoperability between GoPKI and OpenSSL

=== RUN   TestSelfSignedCertificateCompatibility/RSA_2048/GoPKI_Generate_OpenSSL_Validate
    → Validating certificate with OpenSSL...
    → Executing: openssl x509 -in /tmp/validate_cert.pem -text -noout
    ✓ Success: Certificate validation passed
    ✓ GoPKI RSA-2048 self-signed certificate validated by OpenSSL

--- PASS: TestSelfSignedCertificateCompatibility/RSA_2048 (0.31s)
✅ OpenSSL compatibility tests completed

Requirements

Software Dependencies

• OpenSSL 3.0+ (compatible with older versions)
• Go 1.21+ with module support
• testify assertion library

OpenSSL Version Compatibility

The tests are designed to work with:

• OpenSSL 3.x (primary target)
• OpenSSL 1.1.1 (legacy support)
• LibreSSL (partial compatibility)

Version-specific behavior is handled automatically by the framework.

Installation & Setup

Install OpenSSL

# macOS
brew install openssl

# Ubuntu/Debian
sudo apt-get install openssl

# RHEL/CentOS
sudo yum install openssl

Verify Installation

# Check OpenSSL version
openssl version

# Test basic functionality
task test:compatibility

Documentation

• Keypair Compatibility: See ./keypair/doc.md for comprehensive keypair compatibility documentation
• SSH Compatibility: See ./keypair/ssh_doc.md for SSH/OpenSSH compatibility documentation
• Certificate Compatibility: See ./cert/doc.md for certificate compatibility documentation
• Signing Compatibility: See ./signing/doc.md for comprehensive digital signature compatibility documentation
• Implementation Details: Architecture, usage examples, and troubleshooting
• Standards Compliance: RFC references and OpenSSL command documentation

Integration Examples

CI/CD Integration

# GitHub Actions example
- name: Run OpenSSL Compatibility Tests
  run: |
    task test:compatibility

# Jenkins example
pipeline {
    stages {
        stage('Compatibility Tests') {
            steps {
                sh 'go test -tags=compatibility ./compatibility/... -v'
            }
        }
    }
}

Docker Integration

FROM golang:1.21-alpine
RUN apk add --no-cache openssl
COPY . /app
WORKDIR /app
RUN go test -tags=compatibility ./compatibility/... -v

Troubleshooting

Common Issues

OpenSSL Not Found

# Check if OpenSSL is in PATH
which openssl

# Check version
openssl version

Permission Errors

# Ensure temporary directory is writable
chmod 755 /tmp

# Check Go module permissions
go clean -modcache

Test Failures

• Check OpenSSL version compatibility
• Verify temporary directory permissions
• Enable verbose logging with -v flag
• Check specific test documentation in module subdirectories

Performance Considerations

• RSA-4096 certificate generation can take 1-2 seconds
• ECDSA tests are typically fastest
• Ed25519 offers best performance/security ratio
• Certificate chain validation is CPU-intensive
• Parallel test execution is automatically handled

Contributing

Adding New Compatibility Tests

1. Create new module directory under compatibility/
2. Add algorithm-specific helper functions in helpers.go
3. Create test cases following the existing pattern
4. Update Taskfile with new test targets
5. Add documentation for the new module

Test Enhancement Guidelines

• Always use bidirectional testing (GoPKI ↔ OpenSSL)
• Include format conversion verification
• Add comprehensive logging for debugging
• Use descriptive test names and logging
• Follow existing naming conventions
• Ensure test independence (no shared state)
• Clean up temporary resources
• Use build tags for conditional testing

Code Quality Standards

• Use testify assertions for clean error handling
• Add comprehensive logging for debugging
• Follow existing naming conventions
• Ensure test independence (no shared state)
• Clean up temporary resources

Security Considerations

Validation Scope

The compatibility tests verify:

• Cryptographic Correctness: Operations generate valid cryptographic results
• Format Standards Compliance: Output matches RFC specifications
• Cross-Platform Interoperability: Works across different systems
• Algorithm Parameter Validation: Correct curve parameters, key sizes
• Certificate Standards: X.509 compliance and extension handling

Security Boundaries

The tests do NOT validate:

• Side-channel attack resistance
• Timing attack protection
• Hardware security module integration
• Key entropy quality (beyond basic validation)

Key Material Handling

• All test keys and certificates are generated in temporary directories
• Private keys are automatically cleaned up after tests
• No real cryptographic material is exposed
• Test keys should never be used in production

This framework ensures GoPKI maintains 100% compatibility with OpenSSL operations across all supported algorithms and certificate types.