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

     1  # OpenSSL Compatibility Testing Framework
     2  
     3  This directory contains comprehensive compatibility tests between GoPKI and OpenSSL, ensuring perfect interoperability between the two cryptographic implementations.
     4  
     5  ## Overview
     6  
     7  The OpenSSL compatibility framework validates that keys, signatures, and cryptographic 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  ## Test Coverage
    10  
    11  ### Supported Algorithms
    12  
    13  **RSA Keys**
    14  - RSA-2048 (minimum secure size)
    15  - RSA-3072 (enhanced security)
    16  - RSA-4096 (maximum security)
    17  
    18  **ECDSA Keys**
    19  - P-256 (prime256v1) - Most common curve
    20  - P-384 (secp384r1) - Enhanced security
    21  - P-521 (secp521r1) - Maximum security
    22  
    23  **Ed25519 Keys**
    24  - Ed25519 (modern curve) - High performance, excellent security
    25  
    26  ### Test Categories
    27  
    28  1. **Bidirectional Key Generation**
    29     - GoPKI generates → OpenSSL validates
    30     - OpenSSL generates → GoPKI validates
    31  
    32  2. **Format Compatibility**
    33     - PEM format verification
    34     - DER format verification
    35     - SSH format compatibility
    36  
    37  3. **Cryptographic Operations**
    38     - Digital signature generation and verification
    39     - Cross-platform signature validation
    40     - Key component mathematical verification
    41  
    42  4. **Edge Cases and Security**
    43     - Invalid key size handling
    44     - Corrupted data detection
    45     - Type safety validation
    46  
    47  ## Directory Structure
    48  
    49  ```
    50  compatibility/
    51  ├── keypair/            # Keypair-specific compatibility tests
    52  │   ├── keypair_test.go # Main keypair compatibility test suite
    53  │   └── doc.md         # This documentation
    54  ├── helpers.go          # OpenSSL integration utilities
    55  └── testdata/           # Test data directory
    56      ├── generated/      # Files generated during tests
    57      └── reference/      # Reference files for validation
    58  ```
    59  
    60  ## Running Tests
    61  
    62  ### Using Taskfile (Recommended)
    63  
    64  ```bash
    65  # Run all compatibility tests
    66  task test:compatibility
    67  
    68  # Show available tasks
    69  task help:quality
    70  ```
    71  
    72  ### Direct Go Testing
    73  
    74  ```bash
    75  # All compatibility tests
    76  go test -mod=mod ./compatibility/... -v
    77  
    78  # Keypair-specific tests
    79  go test -mod=mod ./compatibility/keypair -v
    80  
    81  # Specific algorithm tests
    82  go test -mod=mod ./compatibility/keypair -v -run TestRSAKeypairCompatibility
    83  go test -mod=mod ./compatibility/keypair -v -run TestECDSAKeypairCompatibility
    84  go test -mod=mod ./compatibility/keypair -v -run TestEd25519KeypairCompatibility
    85  
    86  # Specific test case
    87  go test -mod=mod ./compatibility/keypair -v -run TestRSAKeypairCompatibility/RSA_2048
    88  ```
    89  
    90  ## Test Output Interpretation
    91  
    92  ### Successful Test Output
    93  
    94  ```
    95  🔐 Running RSA OpenSSL Compatibility Tests...
    96     Testing RSA 2048/3072/4096 compatibility
    97  
    98  === RUN   TestRSAKeypairCompatibility/RSA_2048/GoPKI_Generate_OpenSSL_Validate
    99      → Validating RSA private key with OpenSSL...
   100      → Executing: openssl rsa -in /tmp/private_key.pem -check -noout
   101      ✓ Success: RSA key ok
   102      ✓ RSA private key validation passed
   103      ✓ GoPKI RSA-2048 key validated by OpenSSL
   104  
   105  --- PASS: TestRSAKeypairCompatibility/RSA_2048 (0.21s)
   106  ```
   107  
   108  ### Failed Test Indicators
   109  
   110  - `❌ Command failed:` - OpenSSL command execution failed
   111  - `❌ Output:` - Detailed error message from OpenSSL
   112  - Test failure with specific error description
   113  
   114  ## OpenSSL Commands Used
   115  
   116  The framework executes the following OpenSSL commands for validation:
   117  
   118  ### Key Generation
   119  ```bash
   120  # RSA key generation
   121  openssl genpkey -algorithm RSA -out private.pem -pkeyopt rsa_keygen_bits:2048
   122  
   123  # ECDSA key generation
   124  openssl genpkey -algorithm EC -out private.pem -pkeyopt ec_paramgen_curve:prime256v1
   125  
   126  # Ed25519 key generation
   127  openssl genpkey -algorithm Ed25519 -out private.pem
   128  
   129  # Public key extraction
   130  openssl pkey -in private.pem -pubout -out public.pem
   131  ```
   132  
   133  ### Key Validation
   134  ```bash
   135  # RSA key validation
   136  openssl rsa -in private.pem -check -noout
   137  
   138  # ECDSA key validation
   139  openssl ec -in private.pem -check -noout
   140  
   141  # Ed25519 key validation
   142  openssl pkey -in private.pem -check -noout
   143  
   144  # Public key validation
   145  openssl pkey -pubin -in public.pem -noout
   146  ```
   147  
   148  ### Signature Operations
   149  ```bash
   150  # Generate signature
   151  openssl dgst -sha256 -sign private.pem -out signature.bin data.txt
   152  
   153  # Verify signature
   154  openssl dgst -sha256 -verify public.pem -signature signature.bin data.txt
   155  
   156  # Ed25519 signature (different command)
   157  openssl pkeyutl -sign -inkey private.pem -in data.txt -out signature.bin
   158  openssl pkeyutl -verify -pubin -inkey public.pem -in data.txt -sigfile signature.bin
   159  ```
   160  
   161  ## Framework Architecture
   162  
   163  ### Helper Functions
   164  
   165  **OpenSSLHelper**
   166  - Manages temporary files and directories
   167  - Executes OpenSSL commands with detailed logging
   168  - Provides algorithm-specific key generation
   169  - Handles signature operations
   170  
   171  **Key Parsing Functions**
   172  - `ParsePrivateKeyPEM()` - Parse PEM-encoded private keys
   173  - `ParsePublicKeyPEM()` - Parse PEM-encoded public keys
   174  - Type-safe key validation
   175  
   176  **Comparison Functions**
   177  - `CompareRSAKeys()` - Mathematical comparison of RSA keys
   178  - `CompareECDSAKeys()` - ECDSA key component verification
   179  - `CompareEd25519Keys()` - Ed25519 key byte comparison
   180  
   181  ### Test Structure
   182  
   183  Each test follows the pattern:
   184  1. **Setup** - Create OpenSSL helper and temporary directories
   185  2. **Generate** - Create keys using either GoPKI or OpenSSL
   186  3. **Convert** - Transform keys to required formats
   187  4. **Validate** - Verify compatibility using the other tool
   188  5. **Compare** - Ensure mathematical equivalence
   189  6. **Cleanup** - Remove temporary files
   190  
   191  ### Error Handling
   192  
   193  The framework uses testify assertions for clean error handling:
   194  - `require.NoError()` - Fatal errors that stop test execution
   195  - `assert.NoError()` - Non-fatal errors that continue testing
   196  - `assert.Equal()` - Value comparison with detailed output
   197  - `assert.True()` - Boolean condition validation
   198  
   199  ## Dependencies
   200  
   201  ### Required Software
   202  - OpenSSL 3.0+ (compatible with older versions)
   203  - Go 1.21+ with module support
   204  - testify assertion library
   205  
   206  ### Go Dependencies
   207  ```go
   208  import (
   209      "github.com/stretchr/testify/assert"
   210      "github.com/stretchr/testify/require"
   211      "github.com/jasoet/gopki/keypair"
   212      "github.com/jasoet/gopki/keypair/algo"
   213  )
   214  ```
   215  
   216  ### OpenSSL Version Compatibility
   217  
   218  The tests are designed to work with:
   219  - **OpenSSL 3.x** (primary target)
   220  - **OpenSSL 1.1.1** (legacy support)
   221  - **LibreSSL** (partial compatibility)
   222  
   223  Version-specific behavior is handled automatically by the framework.
   224  
   225  ## Security Considerations
   226  
   227  ### Validation Scope
   228  
   229  The compatibility tests verify:
   230  - **Cryptographic Correctness** - Keys generate valid cryptographic operations
   231  - **Format Standards Compliance** - Output matches RFC specifications
   232  - **Cross-Platform Interoperability** - Works across different systems
   233  - **Algorithm Parameter Validation** - Correct curve parameters, key sizes
   234  
   235  ### Security Boundaries
   236  
   237  The tests do NOT validate:
   238  - Side-channel attack resistance
   239  - Timing attack protection
   240  - Hardware security module integration
   241  - Key entropy quality (beyond basic validation)
   242  
   243  ### Key Material Handling
   244  
   245  - All test keys are generated in temporary directories
   246  - Private keys are automatically cleaned up after tests
   247  - No real cryptographic material is exposed
   248  - Test keys should never be used in production
   249  
   250  ## Troubleshooting
   251  
   252  ### Common Issues
   253  
   254  **OpenSSL Not Found**
   255  ```bash
   256  # Install OpenSSL on macOS
   257  brew install openssl
   258  
   259  # Install OpenSSL on Ubuntu/Debian
   260  sudo apt-get install openssl
   261  
   262  # Install OpenSSL on RHEL/CentOS
   263  sudo yum install openssl
   264  ```
   265  
   266  **Permission Errors**
   267  ```bash
   268  # Ensure temporary directory is writable
   269  chmod 755 /tmp
   270  
   271  # Check Go module permissions
   272  go clean -modcache
   273  ```
   274  
   275  **Version Conflicts**
   276  ```bash
   277  # Check OpenSSL version
   278  openssl version
   279  
   280  # Use specific version (if needed)
   281  /usr/local/opt/openssl@3/bin/openssl version
   282  ```
   283  
   284  ### Debugging Tests
   285  
   286  Enable verbose logging:
   287  ```bash
   288  # Maximum verbosity
   289  go test -mod=mod ./compatibility -v -run TestName
   290  
   291  # Add custom debug logging
   292  OPENSSL_COMPAT_DEBUG=1 go test -mod=mod ./compatibility -v
   293  ```
   294  
   295  ### Performance Considerations
   296  
   297  - RSA-4096 key generation can take 1-2 seconds
   298  - ECDSA tests are typically fastest
   299  - Ed25519 offers best performance/security ratio
   300  - Parallel test execution is automatically handled
   301  
   302  ## Integration Examples
   303  
   304  ### CI/CD Integration
   305  
   306  ```yaml
   307  # GitHub Actions example
   308  - name: Run OpenSSL Compatibility Tests
   309    run: |
   310      task test:compatibility
   311  
   312  # Jenkins example
   313  pipeline {
   314      stages {
   315          stage('Compatibility Tests') {
   316              steps {
   317                  sh 'task test:compatibility'
   318              }
   319          }
   320      }
   321  }
   322  ```
   323  
   324  ### Docker Integration
   325  
   326  ```dockerfile
   327  FROM golang:1.21-alpine
   328  RUN apk add --no-cache openssl
   329  COPY . /app
   330  WORKDIR /app
   331  RUN go test -mod=mod ./compatibility -v
   332  ```
   333  
   334  ## Contributing
   335  
   336  ### Adding New Algorithm Tests
   337  
   338  1. Create algorithm-specific helper functions in `helpers.go`
   339  2. Add test cases following the existing pattern
   340  3. Update Taskfile with new test targets
   341  4. Add documentation for the new algorithm
   342  
   343  ### Test Enhancement Guidelines
   344  
   345  - Always use bidirectional testing (GoPKI ↔ OpenSSL)
   346  - Include format conversion verification
   347  - Add signature interoperability tests
   348  - Validate edge cases and error conditions
   349  - Use descriptive test names and logging
   350  
   351  ### Code Quality Standards
   352  
   353  - Use testify assertions for clean error handling
   354  - Add comprehensive logging for debugging
   355  - Follow existing naming conventions
   356  - Ensure test independence (no shared state)
   357  - Clean up temporary resources
   358  
   359  ## References
   360  
   361  ### Standards Compliance
   362  
   363  - **RFC 3447** - RSA PKCS #1 v2.1
   364  - **RFC 5480** - Elliptic Curve Cryptography Subject Public Key Info
   365  - **RFC 8032** - Edwards-Curve Digital Signature Algorithm (EdDSA)
   366  - **RFC 5652** - Cryptographic Message Syntax (CMS)
   367  
   368  ### OpenSSL Documentation
   369  
   370  - [OpenSSL Command Line Tools](https://www.openssl.org/docs/man3.0/man1/)
   371  - [OpenSSL Key Generation](https://www.openssl.org/docs/man3.0/man1/openssl-genpkey.html)
   372  - [OpenSSL Digital Signatures](https://www.openssl.org/docs/man3.0/man1/openssl-dgst.html)
   373  
   374  ### GoPKI Integration
   375  
   376  - [Keypair Module Documentation](../keypair/README.md)
   377  - [Algorithm-Specific Implementation](../keypair/algo/)
   378  - [Format Conversion Guide](../keypair/format/)