github.com/jasoet/gopki@v1.15.0/internal/crypto/README.md (about) 1 # GoPKI Internal Crypto Package 2 3 This package contains complex cryptographic algorithms that are not available in Go's standard library or well-established third-party libraries. These implementations are isolated here for easy review and maintenance. 4 5 ## ⚠️ Security Notice 6 7 These implementations are provided for compatibility and educational purposes. They follow established RFCs and cryptographic standards, but should be thoroughly reviewed before production use. 8 9 ## Algorithms Implemented 10 11 ### 1. Ed25519 to X25519 Public Key Conversion (RFC 7748) 12 13 **File**: `curve25519.go` 14 15 **Purpose**: Converts Ed25519 public keys to X25519 public keys for ECDH operations. 16 17 **Mathematical Background**: 18 - Ed25519 uses Edwards25519 curve: `-x² + y² = 1 + d*x²*y²` 19 - X25519 uses Montgomery Curve25519: `B*v² = u³ + A*u² + u` 20 - Conversion formula: `u = (1 + y) / (1 - y) mod p` 21 - Prime field: `p = 2^255 - 19` 22 23 **References**: 24 - [RFC 7748 - Elliptic Curves for Security](https://tools.ietf.org/html/rfc7748) 25 - [RFC 8032 - Edwards-Curve Digital Signature Algorithm](https://tools.ietf.org/html/rfc8032) 26 27 **Usage**: 28 ```go 29 ed25519PubKey := []byte{...} // 32 bytes 30 x25519PubKey, err := crypto.Ed25519ToX25519PublicKey(ed25519PubKey) 31 ``` 32 33 ### 2. Field Arithmetic Operations 34 35 **File**: `bigint_ops.go` 36 37 **Purpose**: Provides modular arithmetic over the Curve25519 prime field. 38 39 **Operations**: 40 - Addition: `(a + b) mod p` 41 - Subtraction: `(a - b) mod p` 42 - Multiplication: `(a * b) mod p` 43 - Modular inverse: `a^(-1) mod p` 44 45 **Implementation**: Uses Go's `math/big` library for arbitrary precision arithmetic. 46 47 ## Testing 48 49 Run tests with: 50 ```bash 51 go test ./internal/crypto -v 52 ``` 53 54 Run benchmarks: 55 ```bash 56 go test ./internal/crypto -bench=. 57 ``` 58 59 ## Code Organization 60 61 ``` 62 internal/crypto/ 63 ├── curve25519.go # Main Ed25519->X25519 conversion 64 ├── bigint_ops.go # Complex mathematical operations 65 ├── curve25519_test.go # Comprehensive tests 66 └── README.md # This documentation 67 ``` 68 69 ## Design Principles 70 71 1. **Isolation**: Complex algorithms are separated from main codebase 72 2. **Documentation**: Each function includes mathematical background 73 3. **Testing**: Comprehensive test coverage including edge cases 74 4. **Standards Compliance**: Follows established RFCs 75 5. **Reviewability**: Code is structured for easy security review 76 77 ## Performance Notes 78 79 The Ed25519 to X25519 conversion involves: 80 - Big integer arithmetic operations 81 - Modular inverse calculation (most expensive operation) 82 - Field arithmetic over 255-bit prime 83 84 Expected performance: ~0.1-1ms per conversion on modern hardware. 85 86 ## Future Enhancements 87 88 Potential optimizations: 89 1. **Native Field Arithmetic**: Replace big.Int with optimized field operations 90 2. **Precomputed Tables**: Cache common modular inverse values 91 3. **Assembly Optimizations**: Use platform-specific optimizations 92 4. **Constant-Time Operations**: Ensure timing attack resistance 93 94 ## Security Considerations 95 96 1. **Side-Channel Resistance**: Current implementation may be vulnerable to timing attacks 97 2. **Input Validation**: All inputs are validated for correctness 98 3. **Error Handling**: Graceful handling of edge cases and invalid inputs 99 4. **Memory Safety**: No unsafe operations or manual memory management 100 101 ## Maintenance 102 103 When updating these algorithms: 104 1. Maintain RFC compliance 105 2. Add comprehensive tests for any changes 106 3. Document mathematical reasoning 107 4. Consider security implications 108 5. Benchmark performance impact 109 110 --- 111 112 **Note**: This package is internal to GoPKI and should not be used directly by external applications. Use the high-level encryption APIs instead.