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.