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.