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

     1  # OpenSSL Certificate Compatibility Testing Framework
     2  
     3  This directory contains comprehensive compatibility tests between GoPKI and OpenSSL for certificate operations, ensuring perfect interoperability between the two cryptographic implementations for X.509 certificate management.
     4  
     5  ## Overview
     6  
     7  The OpenSSL certificate compatibility framework validates that certificates, certificate chains, 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 certificate operations in Go applications.
     8  
     9  ## Test Coverage
    10  
    11  ### Supported Algorithms
    12  
    13  **RSA Certificates**
    14  - RSA-2048 (minimum secure size for certificates)
    15  - RSA-4096 (maximum security for CA certificates)
    16  
    17  **ECDSA Certificates**
    18  - P-256 (prime256v1) - Most common curve for certificates
    19  - P-384 (secp384r1) - Enhanced security for CA certificates
    20  
    21  **Ed25519 Certificates**
    22  - Ed25519 (modern curve) - High performance, excellent security
    23  
    24  ### Test Categories
    25  
    26  1. **Self-Signed Certificate Compatibility**
    27     - GoPKI generates → OpenSSL validates
    28     - OpenSSL generates → GoPKI validates
    29     - Format conversion and validation
    30  
    31  2. **CA Certificate Compatibility**
    32     - CA certificate generation and validation
    33     - Path length constraint verification
    34     - CA extension validation (BasicConstraints, KeyUsage)
    35  
    36  3. **Certificate Signing Compatibility**
    37     - CA signs certificates using both tools
    38     - Cross-validation of signed certificates
    39     - Certificate chain verification
    40  
    41  4. **Certificate Chain Validation**
    42     - Multi-level certificate chains (Root → Intermediate → End Entity)
    43     - Cross-tool chain validation
    44     - Path length constraint enforcement
    45  
    46  5. **Format Interoperability**
    47     - PEM ↔ DER format conversion
    48     - Certificate content preservation
    49     - Cross-parsing validation
    50  
    51  6. **Subject Alternative Names (SAN)**
    52     - DNS names, IP addresses, email addresses
    53     - Multi-SAN certificate validation
    54     - Wildcard certificate support
    55  
    56  7. **Advanced Certificate Features**
    57     - Certificate extension validation
    58     - Key usage and extended key usage verification
    59     - Certificate validity period handling
    60  
    61  8. **Edge Cases and Error Handling**
    62     - Invalid certificate handling
    63     - Expired certificate detection
    64     - Malformed certificate rejection
    65  
    66  ## Directory Structure
    67  
    68  ```
    69  compatibility/cert/
    70  ├── cert_test.go           # Main certificate compatibility test suite
    71  ├── doc.md                 # This documentation
    72  └── testdata/              # Test data directory
    73      ├── generated/         # Files generated during tests
    74      └── reference/         # Reference files for validation
    75  ```
    76  
    77  ## Running Tests
    78  
    79  ### Using Taskfile (Recommended)
    80  
    81  ```bash
    82  # Run all compatibility tests (includes certificate tests)
    83  task test:compatibility
    84  
    85  # Show available tasks
    86  task help:quality
    87  ```
    88  
    89  ### Direct Go Testing
    90  
    91  ```bash
    92  # All compatibility tests
    93  go test -tags=compatibility ./compatibility/... -v
    94  
    95  # Certificate-specific tests only
    96  go test -tags=compatibility ./compatibility/cert -v
    97  
    98  # Specific test categories
    99  go test -tags=compatibility ./compatibility/cert -v -run TestSelfSignedCertificateCompatibility
   100  go test -tags=compatibility ./compatibility/cert -v -run TestCACertificateCompatibility
   101  go test -tags=compatibility ./compatibility/cert -v -run TestCertificateSigningCompatibility
   102  go test -tags=compatibility ./compatibility/cert -v -run TestCertificateChainValidation
   103  
   104  # Specific algorithm tests
   105  go test -tags=compatibility ./compatibility/cert -v -run TestSelfSignedCertificateCompatibility/RSA_2048
   106  go test -tags=compatibility ./compatibility/cert -v -run TestSelfSignedCertificateCompatibility/ECDSA_P256
   107  go test -tags=compatibility ./compatibility/cert -v -run TestSelfSignedCertificateCompatibility/Ed25519
   108  ```
   109  
   110  ## Test Output Interpretation
   111  
   112  ### Successful Test Output
   113  
   114  ```
   115  🔐 Running Self-Signed Certificate OpenSSL Compatibility Tests...
   116     Testing self-signed certificate generation and validation
   117  
   118  === RUN   TestSelfSignedCertificateCompatibility/RSA_2048/GoPKI_Generate_OpenSSL_Validate
   119      → Validating certificate with OpenSSL...
   120      → Executing: openssl x509 -in /tmp/validate_cert.pem -text -noout
   121      ✓ Success: Certificate:
   122          Data:
   123              Version: 3 (0x2)
   124              Serial Number:
   125                  12:34:56:78:9a:bc:de:f0
   126      ✓ Certificate validation passed
   127      ✓ GoPKI RSA-2048 self-signed certificate validated by OpenSSL
   128  
   129  --- PASS: TestSelfSignedCertificateCompatibility/RSA_2048 (0.31s)
   130  ```
   131  
   132  ### Failed Test Indicators
   133  
   134  - `❌ Command failed:` - OpenSSL command execution failed
   135  - `❌ Output:` - Detailed error message from OpenSSL
   136  - Test failure with specific error description
   137  
   138  ## OpenSSL Commands Used
   139  
   140  The framework executes the following OpenSSL commands for validation:
   141  
   142  ### Certificate Generation
   143  
   144  ```bash
   145  # Self-signed certificate generation
   146  openssl req -new -x509 -key private.pem -out cert.pem -days 365 -config cert.conf -batch
   147  
   148  # CA certificate generation
   149  openssl req -new -x509 -key ca_private.pem -out ca_cert.pem -days 3650 -config ca.conf -batch -extensions v3_ca
   150  
   151  # Certificate signing request
   152  openssl req -new -key private.pem -out cert.csr -config csr.conf -batch
   153  
   154  # Certificate signing
   155  openssl x509 -req -in cert.csr -CA ca_cert.pem -CAkey ca_private.pem -CAcreateserial -out cert.pem -days 365 -extensions v3_req -extfile signing.conf
   156  ```
   157  
   158  ### Certificate Validation
   159  
   160  ```bash
   161  # Certificate validation
   162  openssl x509 -in cert.pem -text -noout
   163  
   164  # Certificate chain verification
   165  openssl verify -CAfile ca_cert.pem cert.pem
   166  
   167  # Multi-level chain verification
   168  openssl verify -CAfile root_ca.pem -untrusted intermediate_ca.pem cert.pem
   169  ```
   170  
   171  ### Format Conversion
   172  
   173  ```bash
   174  # PEM to DER conversion
   175  openssl x509 -in cert.pem -outform DER -out cert.der
   176  
   177  # DER to PEM conversion
   178  openssl x509 -in cert.der -inform DER -outform PEM -out cert.pem
   179  ```
   180  
   181  ## Framework Architecture
   182  
   183  ### Helper Functions
   184  
   185  **OpenSSLHelper Extensions for Certificates**
   186  - `GenerateSelfSignedCertWithOpenSSL()` - Self-signed certificate generation
   187  - `GenerateCACertWithOpenSSL()` - CA certificate generation
   188  - `SignCertificateWithOpenSSL()` - Certificate signing operations
   189  - `GenerateCSRWithOpenSSL()` - Certificate signing request generation
   190  - `ValidateCertificateWithOpenSSL()` - Certificate validation
   191  - `VerifyCertificateChainWithOpenSSL()` - Chain verification
   192  - `ConvertCertPEMToDERWithOpenSSL()` - Format conversion utilities
   193  - `ConvertCertDERToPEMWithOpenSSL()` - Format conversion utilities
   194  
   195  **Configuration File Generation**
   196  - `createOpenSSLConfig()` - Self-signed certificate configuration
   197  - `createCAConfig()` - CA certificate configuration
   198  - `createCSRConfig()` - CSR generation configuration
   199  - `createSigningConfig()` - Certificate signing configuration
   200  
   201  **Certificate Parsing Functions**
   202  - Uses GoPKI `cert.ParseCertificateFromPEM()` for validation
   203  - Uses GoPKI `cert.VerifyCertificate()` for chain validation
   204  - Cross-validation with OpenSSL commands
   205  
   206  ### Test Structure
   207  
   208  Each test follows the pattern:
   209  1. **Setup** - Create OpenSSL helper and generate test key pairs
   210  2. **Generate** - Create certificates using either GoPKI or OpenSSL
   211  3. **Cross-Validate** - Verify compatibility using the other tool
   212  4. **Format Test** - Ensure format conversion compatibility
   213  5. **Chain Test** - Verify certificate chain operations
   214  6. **Cleanup** - Remove temporary files
   215  
   216  ### Error Handling
   217  
   218  The framework uses testify assertions for clean error handling:
   219  - `require.NoError()` - Fatal errors that stop test execution
   220  - `assert.NoError()` - Non-fatal errors that continue testing
   221  - `assert.Equal()` - Value comparison with detailed output
   222  - `assert.True()` - Boolean condition validation
   223  
   224  ## Configuration Files
   225  
   226  The framework generates OpenSSL configuration files for consistent certificate generation:
   227  
   228  ### Self-Signed Certificate Configuration
   229  
   230  ```ini
   231  [req]
   232  distinguished_name = req_distinguished_name
   233  req_extensions = v3_req
   234  prompt = no
   235  
   236  [req_distinguished_name]
   237  CN=Test Certificate,O=GoPKI,C=US
   238  
   239  [v3_req]
   240  basicConstraints = CA:FALSE
   241  keyUsage = nonRepudiation, digitalSignature, keyEncipherment
   242  subjectAltName = DNS:localhost,DNS:example.com,IP:127.0.0.1
   243  ```
   244  
   245  ### CA Certificate Configuration
   246  
   247  ```ini
   248  [req]
   249  distinguished_name = req_distinguished_name
   250  x509_extensions = v3_ca
   251  prompt = no
   252  
   253  [req_distinguished_name]
   254  CN=Test CA,O=GoPKI,C=US
   255  
   256  [v3_ca]
   257  basicConstraints = critical,CA:true
   258  keyUsage = critical, digitalSignature, cRLSign, keyCertSign
   259  subjectKeyIdentifier = hash
   260  authorityKeyIdentifier = keyid:always,issuer
   261  ```
   262  
   263  ## Dependencies
   264  
   265  ### Required Software
   266  - OpenSSL 3.0+ (compatible with older versions)
   267  - Go 1.21+ with module support
   268  - testify assertion library
   269  
   270  ### Go Dependencies
   271  ```go
   272  import (
   273      "github.com/stretchr/testify/assert"
   274      "github.com/stretchr/testify/require"
   275      "github.com/jasoet/gopki/cert"
   276      "github.com/jasoet/gopki/keypair"
   277      "github.com/jasoet/gopki/keypair/algo"
   278      "github.com/jasoet/gopki/compatibility"
   279  )
   280  ```
   281  
   282  ### OpenSSL Version Compatibility
   283  
   284  The tests are designed to work with:
   285  - **OpenSSL 3.x** (primary target)
   286  - **OpenSSL 1.1.1** (legacy support)
   287  - **LibreSSL** (partial compatibility)
   288  
   289  Version-specific behavior is handled automatically by the framework.
   290  
   291  ## Security Considerations
   292  
   293  ### Validation Scope
   294  
   295  The compatibility tests verify:
   296  - **Certificate Generation Correctness** - Certificates follow X.509 standards
   297  - **Format Standards Compliance** - Output matches RFC 5280 specifications
   298  - **Cross-Platform Interoperability** - Works across different systems
   299  - **Extension Handling** - Proper certificate extension support
   300  - **Chain Validation** - Certificate chain verification works correctly
   301  
   302  ### Security Boundaries
   303  
   304  The tests do NOT validate:
   305  - Certificate revocation mechanisms (CRL/OCSP)
   306  - Hardware security module integration
   307  - Certificate transparency log operations
   308  - Advanced certificate policies
   309  
   310  ### Certificate Material Handling
   311  
   312  - All test certificates are generated in temporary directories
   313  - Private keys are automatically cleaned up after tests
   314  - No real cryptographic material is exposed
   315  - Test certificates should never be used in production
   316  
   317  ## Troubleshooting
   318  
   319  ### Common Issues
   320  
   321  **OpenSSL Not Found**
   322  ```bash
   323  # Install OpenSSL on macOS
   324  brew install openssl
   325  
   326  # Install OpenSSL on Ubuntu/Debian
   327  sudo apt-get install openssl
   328  
   329  # Install OpenSSL on RHEL/CentOS
   330  sudo yum install openssl
   331  ```
   332  
   333  **Permission Errors**
   334  ```bash
   335  # Ensure temporary directory is writable
   336  chmod 755 /tmp
   337  
   338  # Check Go module permissions
   339  go clean -modcache
   340  ```
   341  
   342  **Version Conflicts**
   343  ```bash
   344  # Check OpenSSL version
   345  openssl version
   346  
   347  # Use specific version (if needed)
   348  /usr/local/opt/openssl@3/bin/openssl version
   349  ```
   350  
   351  ### Debugging Tests
   352  
   353  Enable verbose logging:
   354  ```bash
   355  # Maximum verbosity
   356  go test -tags=compatibility ./compatibility/cert -v -run TestName
   357  
   358  # Add custom debug logging
   359  OPENSSL_COMPAT_DEBUG=1 go test -tags=compatibility ./compatibility/cert -v
   360  ```
   361  
   362  ### Performance Considerations
   363  
   364  - RSA-4096 certificate generation can take 1-2 seconds
   365  - ECDSA certificate tests are typically fastest
   366  - Ed25519 offers best performance/security ratio for certificates
   367  - Certificate chain validation is CPU-intensive
   368  - Parallel test execution is automatically handled
   369  
   370  ## Integration Examples
   371  
   372  ### CI/CD Integration
   373  
   374  ```yaml
   375  # GitHub Actions example
   376  - name: Run Certificate Compatibility Tests
   377    run: |
   378      task test:compatibility
   379  
   380  # Jenkins example
   381  pipeline {
   382      stages {
   383          stage('Certificate Compatibility Tests') {
   384              steps {
   385                  sh 'go test -tags=compatibility ./compatibility/cert -v'
   386              }
   387          }
   388      }
   389  }
   390  ```
   391  
   392  ### Docker Integration
   393  
   394  ```dockerfile
   395  FROM golang:1.21-alpine
   396  RUN apk add --no-cache openssl
   397  COPY . /app
   398  WORKDIR /app
   399  RUN go test -tags=compatibility ./compatibility/cert -v
   400  ```
   401  
   402  ## Contributing
   403  
   404  ### Adding New Certificate Tests
   405  
   406  1. Add new test functions following the existing pattern
   407  2. Use the provided OpenSSL helper functions
   408  3. Include both GoPKI → OpenSSL and OpenSSL → GoPKI validation
   409  4. Add format conversion verification
   410  5. Update documentation for new test categories
   411  
   412  ### Test Enhancement Guidelines
   413  
   414  - Always use bidirectional testing (GoPKI ↔ OpenSSL)
   415  - Include certificate chain verification
   416  - Add Subject Alternative Name validation
   417  - Validate certificate extensions and constraints
   418  - Use descriptive test names and logging
   419  - Test edge cases and error conditions
   420  
   421  ### Code Quality Standards
   422  
   423  - Use testify assertions for clean error handling
   424  - Add comprehensive logging for debugging
   425  - Follow existing naming conventions
   426  - Ensure test independence (no shared state)
   427  - Clean up temporary resources
   428  - Use build tags for conditional testing
   429  
   430  ## References
   431  
   432  ### Standards Compliance
   433  
   434  - **RFC 5280** - Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
   435  - **RFC 3647** - Internet X.509 Public Key Infrastructure Certificate Policy and Certification Practices Framework
   436  - **RFC 6818** - Updates to the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
   437  
   438  ### OpenSSL Documentation
   439  
   440  - [OpenSSL Certificate Commands](https://www.openssl.org/docs/man3.0/man1/openssl-x509.html)
   441  - [OpenSSL Certificate Generation](https://www.openssl.org/docs/man3.0/man1/openssl-req.html)
   442  - [OpenSSL Certificate Verification](https://www.openssl.org/docs/man3.0/man1/openssl-verify.html)
   443  
   444  ### GoPKI Integration
   445  
   446  - [Certificate Module Documentation](../cert/README.md)
   447  - [Keypair Module Integration](../keypair/)
   448  - [Certificate Examples](../examples/certificates/)
   449  
   450  This framework ensures GoPKI maintains **100% compatibility** with OpenSSL certificate operations across all supported algorithms and certificate types.