github.com/jasoet/gopki@v1.15.0/compatibility/README.md (about)

     1  # OpenSSL Compatibility Framework
     2  
     3  This directory contains comprehensive compatibility tests ensuring perfect interoperability between GoPKI and OpenSSL for all cryptographic operations.
     4  
     5  ## Overview
     6  
     7  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.
     8  
     9  ## Structure
    10  
    11  ```
    12  compatibility/
    13  ├── keypair/            # Keypair compatibility tests
    14  │   ├── keypair_test.go # RSA, ECDSA, Ed25519 key compatibility tests
    15  │   ├── ssh_test.go     # SSH/OpenSSH compatibility tests
    16  │   ├── doc.md         # Detailed keypair compatibility documentation
    17  │   └── ssh_doc.md     # SSH compatibility documentation
    18  ├── cert/               # Certificate compatibility tests
    19  │   ├── cert_test.go    # X.509 certificate compatibility tests
    20  │   ├── doc.md         # Certificate compatibility documentation
    21  │   └── testdata/       # Test certificates and reference data
    22  ├── signing/            # Digital signature compatibility tests
    23  │   ├── signing_test.go # PKCS#7/CMS signature compatibility tests
    24  │   ├── doc.md         # Comprehensive signing compatibility documentation
    25  │   └── README.md      # Quick signing compatibility reference
    26  ├── helpers.go          # OpenSSL integration utilities
    27  └── README.md          # This overview
    28  ```
    29  
    30  ## Quick Start
    31  
    32  ### Run All Compatibility Tests
    33  
    34  ```bash
    35  # Using Taskfile (recommended)
    36  task test:compatibility
    37  
    38  # Direct Go command
    39  go test -tags=compatibility ./compatibility/... -v
    40  ```
    41  
    42  ### Run Specific Module Tests
    43  
    44  ```bash
    45  # Keypair-specific tests only
    46  go test -tags=compatibility ./compatibility/keypair -v
    47  
    48  # Certificate-specific tests only
    49  go test -tags=compatibility ./compatibility/cert -v
    50  
    51  # Signing-specific tests only
    52  go test -tags=compatibility ./compatibility/signing -v
    53  ```
    54  
    55  ## Test Coverage
    56  
    57  ### ✅ **Keypair Compatibility** (`./keypair/`)
    58  - **RSA**: 2048, 3072, 4096-bit keys
    59  - **ECDSA**: P-256, P-384, P-521 curves
    60  - **Ed25519**: Modern high-performance curve
    61  - **Bidirectional testing**: GoPKI ↔ OpenSSL
    62  - **Format validation**: PEM, DER, SSH
    63  - **Signature interoperability**: Cross-platform verification
    64  
    65  ### ✅ **Certificate Compatibility** (`./cert/`)
    66  - **Self-Signed Certificates**: All algorithms with OpenSSL validation
    67  - **CA Certificates**: Path length constraints and CA extensions
    68  - **Certificate Signing**: CA-signed certificates with chain validation
    69  - **Subject Alternative Names**: DNS, IP, email address extensions
    70  - **Format Interoperability**: PEM ↔ DER conversion
    71  - **Certificate Chain Validation**: Multi-level certificate hierarchies
    72  - **Edge Cases**: Invalid certificates, expired certificates
    73  
    74  ### ✅ **Signing Compatibility** (`./signing/`)
    75  - **Raw Signatures**: RSA, ECDSA, Ed25519 signature generation and verification
    76  - **PKCS#7/CMS Formats**: Attached and detached signature containers
    77  - **Certificate Chain Integration**: Multi-level certificate inclusion
    78  - **Bidirectional Testing**: GoPKI ↔ OpenSSL signature validation
    79  - **Hash Algorithms**: SHA256, SHA384, SHA512 support
    80  - **Format Standards**: RFC 5652 CMS compliance validation
    81  - **Advanced Features**: Signature metadata extraction and validation
    82  
    83  ### 🔮 **Future Compatibility Tests**
    84  As GoPKI grows, additional compatibility tests will be organized here:
    85  - `./encryption/` - Encryption/decryption compatibility
    86  - `./pkcs12/` - PKCS#12 container compatibility
    87  
    88  ## Features
    89  
    90  - **Enhanced Logging**: Every OpenSSL command execution is logged with results
    91  - **Testify Assertions**: Clean, readable test assertions
    92  - **Automatic Cleanup**: Temporary files are properly managed
    93  - **Cross-Platform**: Works with OpenSSL 3.x, 1.1.1, LibreSSL
    94  - **Security Validation**: Ensures cryptographic correctness
    95  - **Build Tags**: Uses `//go:build compatibility` for conditional testing
    96  
    97  ## Build Tags
    98  
    99  The compatibility tests use build tags to allow conditional execution:
   100  
   101  ```bash
   102  # Include compatibility tests
   103  go test -tags=compatibility ./compatibility/... -v
   104  
   105  # Regular tests (excludes compatibility tests)
   106  go test ./compatibility/... -v  # Will find no test files
   107  ```
   108  
   109  This allows for:
   110  - **Conditional Testing**: Compatibility tests only run when explicitly tagged
   111  - **CI/CD Flexibility**: Can skip expensive OpenSSL tests in certain environments
   112  - **Development Workflow**: Developers can run regular tests without OpenSSL dependency
   113  
   114  ## Sample Output
   115  
   116  ```
   117  🔗 Running OpenSSL Compatibility Tests...
   118     This tests interoperability between GoPKI and OpenSSL
   119  
   120  === RUN   TestSelfSignedCertificateCompatibility/RSA_2048/GoPKI_Generate_OpenSSL_Validate
   121      → Validating certificate with OpenSSL...
   122      → Executing: openssl x509 -in /tmp/validate_cert.pem -text -noout
   123      ✓ Success: Certificate validation passed
   124      ✓ GoPKI RSA-2048 self-signed certificate validated by OpenSSL
   125  
   126  --- PASS: TestSelfSignedCertificateCompatibility/RSA_2048 (0.31s)
   127  ✅ OpenSSL compatibility tests completed
   128  ```
   129  
   130  ## Requirements
   131  
   132  ### Software Dependencies
   133  - **OpenSSL 3.0+** (compatible with older versions)
   134  - **Go 1.21+** with module support
   135  - **testify** assertion library
   136  
   137  ### OpenSSL Version Compatibility
   138  The tests are designed to work with:
   139  - **OpenSSL 3.x** (primary target)
   140  - **OpenSSL 1.1.1** (legacy support)
   141  - **LibreSSL** (partial compatibility)
   142  
   143  Version-specific behavior is handled automatically by the framework.
   144  
   145  ## Installation & Setup
   146  
   147  ### Install OpenSSL
   148  
   149  ```bash
   150  # macOS
   151  brew install openssl
   152  
   153  # Ubuntu/Debian
   154  sudo apt-get install openssl
   155  
   156  # RHEL/CentOS
   157  sudo yum install openssl
   158  ```
   159  
   160  ### Verify Installation
   161  
   162  ```bash
   163  # Check OpenSSL version
   164  openssl version
   165  
   166  # Test basic functionality
   167  task test:compatibility
   168  ```
   169  
   170  ## Documentation
   171  
   172  - **Keypair Compatibility**: See [`./keypair/doc.md`](./keypair/doc.md) for comprehensive keypair compatibility documentation
   173  - **SSH Compatibility**: See [`./keypair/ssh_doc.md`](./keypair/ssh_doc.md) for SSH/OpenSSH compatibility documentation
   174  - **Certificate Compatibility**: See [`./cert/doc.md`](./cert/doc.md) for certificate compatibility documentation
   175  - **Signing Compatibility**: See [`./signing/doc.md`](./signing/doc.md) for comprehensive digital signature compatibility documentation
   176  - **Implementation Details**: Architecture, usage examples, and troubleshooting
   177  - **Standards Compliance**: RFC references and OpenSSL command documentation
   178  
   179  ## Integration Examples
   180  
   181  ### CI/CD Integration
   182  
   183  ```yaml
   184  # GitHub Actions example
   185  - name: Run OpenSSL Compatibility Tests
   186    run: |
   187      task test:compatibility
   188  
   189  # Jenkins example
   190  pipeline {
   191      stages {
   192          stage('Compatibility Tests') {
   193              steps {
   194                  sh 'go test -tags=compatibility ./compatibility/... -v'
   195              }
   196          }
   197      }
   198  }
   199  ```
   200  
   201  ### Docker Integration
   202  
   203  ```dockerfile
   204  FROM golang:1.21-alpine
   205  RUN apk add --no-cache openssl
   206  COPY . /app
   207  WORKDIR /app
   208  RUN go test -tags=compatibility ./compatibility/... -v
   209  ```
   210  
   211  ## Troubleshooting
   212  
   213  ### Common Issues
   214  
   215  **OpenSSL Not Found**
   216  ```bash
   217  # Check if OpenSSL is in PATH
   218  which openssl
   219  
   220  # Check version
   221  openssl version
   222  ```
   223  
   224  **Permission Errors**
   225  ```bash
   226  # Ensure temporary directory is writable
   227  chmod 755 /tmp
   228  
   229  # Check Go module permissions
   230  go clean -modcache
   231  ```
   232  
   233  **Test Failures**
   234  - Check OpenSSL version compatibility
   235  - Verify temporary directory permissions
   236  - Enable verbose logging with `-v` flag
   237  - Check specific test documentation in module subdirectories
   238  
   239  ### Performance Considerations
   240  
   241  - RSA-4096 certificate generation can take 1-2 seconds
   242  - ECDSA tests are typically fastest
   243  - Ed25519 offers best performance/security ratio
   244  - Certificate chain validation is CPU-intensive
   245  - Parallel test execution is automatically handled
   246  
   247  ## Contributing
   248  
   249  ### Adding New Compatibility Tests
   250  
   251  1. Create new module directory under `compatibility/`
   252  2. Add algorithm-specific helper functions in `helpers.go`
   253  3. Create test cases following the existing pattern
   254  4. Update Taskfile with new test targets
   255  5. Add documentation for the new module
   256  
   257  ### Test Enhancement Guidelines
   258  
   259  - Always use bidirectional testing (GoPKI ↔ OpenSSL)
   260  - Include format conversion verification
   261  - Add comprehensive logging for debugging
   262  - Use descriptive test names and logging
   263  - Follow existing naming conventions
   264  - Ensure test independence (no shared state)
   265  - Clean up temporary resources
   266  - Use build tags for conditional testing
   267  
   268  ### Code Quality Standards
   269  
   270  - Use testify assertions for clean error handling
   271  - Add comprehensive logging for debugging
   272  - Follow existing naming conventions
   273  - Ensure test independence (no shared state)
   274  - Clean up temporary resources
   275  
   276  ## Security Considerations
   277  
   278  ### Validation Scope
   279  
   280  The compatibility tests verify:
   281  - **Cryptographic Correctness**: Operations generate valid cryptographic results
   282  - **Format Standards Compliance**: Output matches RFC specifications
   283  - **Cross-Platform Interoperability**: Works across different systems
   284  - **Algorithm Parameter Validation**: Correct curve parameters, key sizes
   285  - **Certificate Standards**: X.509 compliance and extension handling
   286  
   287  ### Security Boundaries
   288  
   289  The tests do NOT validate:
   290  - Side-channel attack resistance
   291  - Timing attack protection
   292  - Hardware security module integration
   293  - Key entropy quality (beyond basic validation)
   294  
   295  ### Key Material Handling
   296  
   297  - All test keys and certificates are generated in temporary directories
   298  - Private keys are automatically cleaned up after tests
   299  - No real cryptographic material is exposed
   300  - Test keys should never be used in production
   301  
   302  This framework ensures GoPKI maintains **100% compatibility** with OpenSSL operations across all supported algorithms and certificate types.