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.