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

     1  # OpenSSL Signing Compatibility Testing Framework
     2  
     3  This document provides comprehensive documentation for digital signature compatibility testing between GoPKI and OpenSSL, ensuring perfect interoperability for all signing operations and formats.
     4  
     5  ## Overview
     6  
     7  The OpenSSL signing compatibility framework validates that digital signatures, PKCS#7/CMS formats, 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 signing operations in Go applications.
     8  
     9  ## Test Coverage
    10  
    11  ### Supported Algorithms
    12  
    13  **RSA Signatures**
    14  - RSA-2048 (minimum secure size for signatures)
    15  - RSA-3072 (enhanced security)
    16  - RSA-4096 (maximum security for high-value signatures)
    17  
    18  **ECDSA Signatures**
    19  - P-256 (prime256v1) - Most common curve for signatures
    20  - P-384 (secp384r1) - Enhanced security for enterprise use
    21  - P-521 (secp521r1) - Maximum security for critical signatures
    22  
    23  **Ed25519 Signatures**
    24  - Ed25519 (modern curve) - High performance, excellent security
    25  
    26  ### Test Categories
    27  
    28  #### 1. **Raw Signature Compatibility**
    29  - GoPKI generates signatures → OpenSSL verifies
    30  - OpenSSL generates signatures → GoPKI verifies
    31  - Cross-platform signature validation for all algorithms
    32  - Hash algorithm consistency (SHA256, SHA384, SHA512)
    33  
    34  #### 2. **PKCS#7/CMS Format Compatibility**
    35  - PKCS#7 attached signature format validation
    36  - PKCS#7 detached signature format validation
    37  - Certificate inclusion in signature containers
    38  - Cross-tool PKCS#7 format parsing and verification
    39  
    40  #### 3. **Detached Signature Workflows**
    41  - Detached vs attached signature handling
    42  - Separate data and signature file workflows
    43  - Certificate chain preservation in detached signatures
    44  - Multi-file signature verification scenarios
    45  
    46  #### 4. **Certificate Chain Integration**
    47  - Certificate chain inclusion in signatures
    48  - Multi-level certificate hierarchy validation
    49  - CA certificate chain verification
    50  - Trust anchor and intermediate certificate handling
    51  
    52  #### 5. **Advanced Signature Features**
    53  - Signature metadata extraction and validation
    54  - Multiple hash algorithm support
    55  - Signature format detection and validation
    56  - Cross-algorithm signature verification
    57  
    58  ## Directory Structure
    59  
    60  ```
    61  compatibility/signing/
    62  ├── signing_test.go          # Main compatibility tests with build tags
    63  ├── doc.md                  # This comprehensive documentation
    64  └── README.md              # Quick reference guide
    65  ```
    66  
    67  ## Test Implementation
    68  
    69  ### Build Tags
    70  
    71  All signing compatibility tests use build tags for conditional execution:
    72  
    73  ```go
    74  //go:build compatibility
    75  
    76  package signing
    77  ```
    78  
    79  **Execution:**
    80  ```bash
    81  # Run signing compatibility tests only
    82  go test -tags=compatibility ./compatibility/signing -v
    83  
    84  # Run all compatibility tests
    85  go test -tags=compatibility ./compatibility/... -v
    86  
    87  # Using Taskfile
    88  task test:compatibility:signing
    89  ```
    90  
    91  ### Test Structure
    92  
    93  **Algorithm-Specific Testing:**
    94  ```go
    95  func TestSigningCompatibility(t *testing.T) {
    96      t.Run("RSA", func(t *testing.T) {
    97          testRSASigningCompatibility(t)
    98      })
    99      t.Run("ECDSA", func(t *testing.T) {
   100          testECDSASigningCompatibility(t)
   101      })
   102      t.Run("Ed25519", func(t *testing.T) {
   103          testEd25519SigningCompatibility(t)
   104      })
   105  }
   106  ```
   107  
   108  **Bidirectional Testing Pattern:**
   109  For each algorithm, comprehensive bidirectional testing ensures full compatibility:
   110  - `GoPKI_Sign_OpenSSL_Verify` - GoPKI creates signatures, OpenSSL validates
   111  - `OpenSSL_Sign_GoPKI_Verify` - OpenSSL creates signatures, GoPKI validates
   112  - `PKCS7_Format_Compatibility` - PKCS#7 format cross-validation
   113  - `Detached_Signature_Compatibility` - Detached signature workflows
   114  
   115  ## OpenSSL Helper Functions
   116  
   117  The framework includes specialized helper functions for signing operations:
   118  
   119  ### Core Signing Functions
   120  
   121  **`CreatePKCS7SignatureWithOpenSSL()`**
   122  - Creates PKCS#7 signatures using OpenSSL `cms` command
   123  - Supports both attached and detached signature modes
   124  - Handles certificate inclusion automatically
   125  
   126  **`VerifyPKCS7SignatureWithOpenSSL()`**
   127  - Verifies PKCS#7 signatures using OpenSSL
   128  - Validates signature format and cryptographic correctness
   129  - Supports certificate chain verification
   130  
   131  **`CreateRawSignatureWithOpenSSL()`**
   132  - Creates raw signatures using OpenSSL `dgst` command
   133  - Algorithm-specific signature generation (RSA, ECDSA, Ed25519)
   134  - Hash algorithm selection and validation
   135  
   136  **`VerifyRawSignatureWithOpenSSL()`**
   137  - Verifies raw signatures using OpenSSL
   138  - Cross-algorithm signature verification
   139  - Hash algorithm consistency validation
   140  
   141  ### Advanced Functions
   142  
   143  **`VerifyPKCS7SignatureWithCertificateChainWithOpenSSL()`**
   144  - Verifies signatures with complete certificate chain validation
   145  - CA certificate trust anchor verification
   146  - Multi-level certificate hierarchy support
   147  
   148  **`ExtractSignatureInfoWithOpenSSL()`**
   149  - Extracts signature metadata using OpenSSL
   150  - Parses signature algorithm, hash algorithm, certificates
   151  - Validates signature container structure
   152  
   153  **`ValidateSignatureFormatWithOpenSSL()`**
   154  - Validates signature format compliance
   155  - ASN.1 structure verification
   156  - PKCS#7/CMS container validation
   157  
   158  ## Validation Scope
   159  
   160  ### Cryptographic Validation
   161  
   162  **Signature Verification:**
   163  - ✅ Cross-platform signature validation (GoPKI ↔ OpenSSL)
   164  - ✅ Algorithm-specific parameter validation
   165  - ✅ Hash algorithm consistency verification
   166  - ✅ Signature format standards compliance
   167  
   168  **Certificate Integration:**
   169  - ✅ Certificate inclusion in signature containers
   170  - ✅ Certificate chain preservation and validation
   171  - ✅ CA certificate trust anchor verification
   172  - ✅ Certificate validity period checks
   173  
   174  ### Format Standards Compliance
   175  
   176  **PKCS#7/CMS Compliance:**
   177  - ✅ RFC 5652 Cryptographic Message Syntax compliance
   178  - ✅ ASN.1 structure validation
   179  - ✅ Certificate and signature container format
   180  - ✅ Detached vs attached signature handling
   181  
   182  **Cross-Tool Interoperability:**
   183  - ✅ Format parsing consistency between tools
   184  - ✅ Metadata preservation across formats
   185  - ✅ Certificate chain encoding compatibility
   186  - ✅ Signature algorithm parameter consistency
   187  
   188  ## Practical Usage Examples
   189  
   190  ### Basic Signature Compatibility Test
   191  
   192  ```go
   193  func testBasicSignatureCompatibility(t *testing.T) {
   194      // Generate key pair and certificate
   195      manager, _ := keypair.Generate[algo.KeySize, *algo.RSAKeyPair, *rsa.PrivateKey, *rsa.PublicKey](algo.KeySize2048)
   196      certificate, _ := cert.CreateSelfSignedCertificate(manager.KeyPair(), certRequest)
   197  
   198      // Sign with GoPKI
   199      signature, _ := signing.SignDocument(testData, manager.KeyPair(), certificate, opts)
   200  
   201      // Verify with OpenSSL
   202      privatePEM, publicPEM, _ := manager.ToPEM()
   203      err := helper.VerifyRawSignatureWithOpenSSL(testData, signature.Data, publicPEM, "RSA", "sha256")
   204      assert.NoError(t, err)
   205  }
   206  ```
   207  
   208  ### PKCS#7 Format Compatibility Test
   209  
   210  ```go
   211  func testPKCS7FormatCompatibility(t *testing.T) {
   212      // Create PKCS#7 signature with GoPKI
   213      opts := signing.DefaultSignOptions()
   214      opts.Format = signing.FormatPKCS7
   215      opts.IncludeCertificate = true
   216  
   217      signature, _ := signing.SignDocument(testData, manager.KeyPair(), certificate, opts)
   218  
   219      // Verify PKCS#7 format with OpenSSL
   220      err := helper.VerifyPKCS7SignatureWithOpenSSL(testData, signature.Data)
   221      assert.NoError(t, err)
   222  }
   223  ```
   224  
   225  ## Performance Considerations
   226  
   227  ### Algorithm Performance
   228  
   229  **RSA Signatures:**
   230  - RSA-2048: ~10ms signing, ~1ms verification
   231  - RSA-4096: ~50ms signing, ~2ms verification
   232  - Larger keys provide more security but impact performance
   233  
   234  **ECDSA Signatures:**
   235  - P-256: ~2ms signing, ~3ms verification
   236  - P-384: ~4ms signing, ~6ms verification
   237  - P-521: ~8ms signing, ~12ms verification
   238  - Best performance/security ratio for most applications
   239  
   240  **Ed25519 Signatures:**
   241  - ~0.5ms signing, ~1ms verification
   242  - Excellent performance with high security
   243  - Recommended for high-throughput applications
   244  
   245  ### Test Execution Performance
   246  
   247  **Parallel Execution:**
   248  - Tests run in parallel per algorithm
   249  - Independent temporary directory per test
   250  - Automatic cleanup of temporary files
   251  - Optimized for CI/CD environments
   252  
   253  **Resource Usage:**
   254  - Temporary file creation and cleanup
   255  - OpenSSL process spawning overhead
   256  - Certificate generation can be CPU-intensive
   257  - Memory usage scales with key size and test count
   258  
   259  ## Troubleshooting
   260  
   261  ### Common Issues
   262  
   263  **OpenSSL Version Compatibility:**
   264  ```bash
   265  # Check OpenSSL version
   266  openssl version
   267  
   268  # Verify CMS command availability
   269  openssl cms -help
   270  ```
   271  
   272  **Certificate Chain Issues:**
   273  - Ensure certificate chain order is correct (leaf → intermediate → root)
   274  - Verify certificate validity periods
   275  - Check certificate key usage extensions
   276  
   277  **Signature Format Problems:**
   278  - Validate ASN.1 structure with `openssl asn1parse`
   279  - Check PKCS#7 container with `openssl cms -print`
   280  - Verify signature algorithm compatibility
   281  
   282  ### Debug Commands
   283  
   284  **Signature Analysis:**
   285  ```bash
   286  # Analyze PKCS#7 signature structure
   287  openssl cms -in signature.p7s -inform DER -print -noout
   288  
   289  # Extract certificates from signature
   290  openssl cms -in signature.p7s -inform DER -print_certs -noout
   291  
   292  # Verify signature manually
   293  openssl cms -verify -in signature.p7s -inform DER -content data.bin -noverify
   294  ```
   295  
   296  **Certificate Chain Analysis:**
   297  ```bash
   298  # Display certificate chain
   299  openssl x509 -in cert.pem -text -noout
   300  
   301  # Verify certificate chain
   302  openssl verify -CAfile ca.pem cert.pem
   303  
   304  # Check certificate purpose
   305  openssl x509 -in cert.pem -purpose -noout
   306  ```
   307  
   308  ## Integration with CI/CD
   309  
   310  ### GitHub Actions Example
   311  
   312  ```yaml
   313  name: Signing Compatibility Tests
   314  on: [push, pull_request]
   315  
   316  jobs:
   317    signing-compatibility:
   318      runs-on: ubuntu-latest
   319      steps:
   320      - uses: actions/checkout@v3
   321      - uses: actions/setup-go@v3
   322        with:
   323          go-version: '1.21'
   324  
   325      - name: Install OpenSSL
   326        run: |
   327          sudo apt-get update
   328          sudo apt-get install openssl
   329          openssl version
   330  
   331      - name: Run Signing Compatibility Tests
   332        run: |
   333          go test -tags=compatibility ./compatibility/signing -v
   334  
   335      - name: Run All Compatibility Tests
   336        run: |
   337          go test -tags=compatibility ./compatibility/... -v
   338  ```
   339  
   340  ### Docker Integration
   341  
   342  ```dockerfile
   343  FROM golang:1.21-alpine
   344  RUN apk add --no-cache openssl
   345  WORKDIR /app
   346  COPY . .
   347  RUN go test -tags=compatibility ./compatibility/signing -v
   348  ```
   349  
   350  ## Security Considerations
   351  
   352  ### Validation Boundaries
   353  
   354  **What the Tests Validate:**
   355  - ✅ Cryptographic signature correctness
   356  - ✅ Format standards compliance (RFC 5652)
   357  - ✅ Cross-platform interoperability
   358  - ✅ Certificate chain validation
   359  - ✅ Algorithm parameter consistency
   360  
   361  **What the Tests Do NOT Validate:**
   362  - ❌ Side-channel attack resistance
   363  - ❌ Timing attack protection
   364  - ❌ Hardware security module integration
   365  - ❌ Key entropy quality beyond basic validation
   366  - ❌ Production certificate authority policies
   367  
   368  ### Test Key Material
   369  
   370  **Security Notes:**
   371  - All test keys and certificates are generated in temporary directories
   372  - Private keys are automatically cleaned up after tests
   373  - No real cryptographic material is exposed or reused
   374  - Test keys should NEVER be used in production environments
   375  
   376  **File Permissions:**
   377  - Private keys created with 0600 permissions (owner read/write only)
   378  - Temporary directories created with 0700 permissions
   379  - Automatic cleanup prevents key material exposure
   380  
   381  ## Contributing
   382  
   383  ### Adding New Signature Tests
   384  
   385  1. **Extend Test Coverage:**
   386     - Add new algorithm support in test functions
   387     - Include additional signature formats
   388     - Add edge case validation
   389  
   390  2. **Helper Function Development:**
   391     - Add new OpenSSL command integrations
   392     - Extend format validation capabilities
   393     - Improve error handling and logging
   394  
   395  3. **Documentation Updates:**
   396     - Update this documentation for new features
   397     - Add usage examples for new functionality
   398     - Update troubleshooting guides
   399  
   400  ### Code Quality Standards
   401  
   402  **Testing Requirements:**
   403  - Comprehensive bidirectional testing (GoPKI ↔ OpenSSL)
   404  - Proper error handling and validation
   405  - Extensive logging for debugging
   406  - Temporary resource cleanup
   407  - Build tag conditional execution
   408  
   409  **Performance Optimization:**
   410  - Parallel test execution where possible
   411  - Efficient temporary file management
   412  - Minimal OpenSSL process spawning
   413  - Resource usage monitoring
   414  
   415  This comprehensive signing compatibility framework ensures GoPKI maintains **100% compatibility** with OpenSSL for all digital signature operations, formats, and certificate integration scenarios.