| Copyright | (c) 2025 Jared Tobin |
|---|---|
| License | MIT |
| Maintainer | Jared Tobin <jared@ppad.tech> |
| Safe Haskell | None |
| Language | Haskell2010 |
Lightning.Protocol.BOLT4.Prim
Description
Low-level cryptographic primitives for BOLT4 onion routing.
Synopsis
- newtype SharedSecret = SharedSecret ByteString
- newtype DerivedKey = DerivedKey ByteString
- newtype BlindingFactor = BlindingFactor ByteString
- deriveRho :: SharedSecret -> DerivedKey
- deriveMu :: SharedSecret -> DerivedKey
- deriveUm :: SharedSecret -> DerivedKey
- derivePad :: SharedSecret -> DerivedKey
- deriveAmmag :: SharedSecret -> DerivedKey
- computeSharedSecret :: ByteString -> Projective -> Maybe SharedSecret
- computeBlindingFactor :: Projective -> SharedSecret -> BlindingFactor
- blindPubKey :: Projective -> BlindingFactor -> Maybe Projective
- blindSecKey :: ByteString -> BlindingFactor -> Maybe ByteString
- generateStream :: DerivedKey -> Int -> ByteString
- computeHmac :: DerivedKey -> ByteString -> ByteString -> ByteString
- verifyHmac :: ByteString -> ByteString -> Bool
Types
newtype SharedSecret Source #
32-byte shared secret derived from ECDH.
Constructors
| SharedSecret ByteString |
Instances
newtype DerivedKey Source #
32-byte derived key (rho, mu, um, pad, ammag).
Constructors
| DerivedKey ByteString |
Instances
| Show DerivedKey Source # | |
Defined in Lightning.Protocol.BOLT4.Prim Methods showsPrec :: Int -> DerivedKey -> ShowS # show :: DerivedKey -> String # showList :: [DerivedKey] -> ShowS # | |
| Eq DerivedKey Source # | |
Defined in Lightning.Protocol.BOLT4.Prim | |
newtype BlindingFactor Source #
32-byte blinding factor for ephemeral key updates.
Constructors
| BlindingFactor ByteString |
Instances
| Show BlindingFactor Source # | |
Defined in Lightning.Protocol.BOLT4.Prim Methods showsPrec :: Int -> BlindingFactor -> ShowS # show :: BlindingFactor -> String # showList :: [BlindingFactor] -> ShowS # | |
| Eq BlindingFactor Source # | |
Defined in Lightning.Protocol.BOLT4.Prim Methods (==) :: BlindingFactor -> BlindingFactor -> Bool # (/=) :: BlindingFactor -> BlindingFactor -> Bool # | |
Key derivation
deriveRho :: SharedSecret -> DerivedKey Source #
Derive rho key for obfuscation stream generation.
rho = HMAC-SHA256(key="rho", data=shared_secret)
deriveMu :: SharedSecret -> DerivedKey Source #
Derive mu key for HMAC computation.
mu = HMAC-SHA256(key="mu", data=shared_secret)
deriveUm :: SharedSecret -> DerivedKey Source #
Derive um key for return error HMAC.
um = HMAC-SHA256(key="um", data=shared_secret)
derivePad :: SharedSecret -> DerivedKey Source #
Derive pad key for filler generation.
pad = HMAC-SHA256(key="pad", data=shared_secret)
deriveAmmag :: SharedSecret -> DerivedKey Source #
Derive ammag key for error obfuscation.
ammag = HMAC-SHA256(key="ammag", data=shared_secret)
Shared secret computation
Arguments
| :: ByteString | 32-byte secret key |
| -> Projective | public key |
| -> Maybe SharedSecret |
Compute shared secret from ECDH.
Takes a 32-byte secret key and a public key. Returns SHA256 of the compressed ECDH point (33 bytes).
Blinding factor computation
computeBlindingFactor Source #
Arguments
| :: Projective | ephemeral public key |
| -> SharedSecret | shared secret |
| -> BlindingFactor |
Compute blinding factor for ephemeral key updates.
blinding_factor = SHA256(ephemeral_pubkey || shared_secret)
Key blinding
blindPubKey :: Projective -> BlindingFactor -> Maybe Projective Source #
Blind a public key by multiplying with blinding factor.
new_pubkey = pubkey * blinding_factor
Arguments
| :: ByteString | 32-byte secret key |
| -> BlindingFactor | blinding factor |
| -> Maybe ByteString | 32-byte blinded secret key |
Blind a secret key by multiplying with blinding factor (mod curve order).
new_seckey = seckey * blinding_factor (mod q)
Uses Montgomery multiplication from ppad-fixed for efficiency. Takes a 32-byte secret key and returns a 32-byte blinded secret key.
Stream generation
Arguments
| :: DerivedKey | rho or ammag key |
| -> Int | desired length |
| -> ByteString |
Generate pseudo-random byte stream using ChaCha20.
Uses derived key as ChaCha20 key, 96-bit zero nonce, counter=0. Encrypts zeros to produce keystream.
HMAC operations
Arguments
| :: DerivedKey | mu key |
| -> ByteString | hop_payloads |
| -> ByteString | associated_data |
| -> ByteString | 32-byte HMAC |
Compute HMAC-SHA256 for packet integrity.
Arguments
| :: ByteString | expected |
| -> ByteString | computed |
| -> Bool |
Constant-time HMAC comparison.