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.