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/)