Safe Haskell	None
Language	GHC2021

Network.LibP2P.Security.Noise.Handshake

Contents

Handshake types
Payload encoding
Static key signing
Handshake lifecycle
Remote static key extraction
Convenience
Re-exports for payload decoding

Description

Noise XX handshake for libp2p secure channels.

Implements the Noise_XX_25519_ChaChaPoly_SHA256 handshake pattern with libp2p-specific payload injection (identity key + signature).

Uses cacophony for the core Noise protocol state machine.

Synopsis

data HandshakeResult = HandshakeResult {
- hrRemotePeerId :: !PeerId
- hrRemotePublicKey :: !PublicKey
}
data NoisePayload = NoisePayload {
- npIdentityKey :: !ByteString
- npIdentitySig :: !ByteString
}
newtype HandshakeState = HandshakeState {
- hsNoiseState :: CacophonyState
}
encodeNoisePayload :: NoisePayload -> ByteString
decodeNoisePayload :: ByteString -> Either String NoisePayload
buildHandshakePayload :: KeyPair -> ByteString -> NoisePayload
validateHandshakePayload :: NoisePayload -> Either String PublicKey
signStaticKey :: PrivateKey -> ByteString -> Either String ByteString
verifyStaticKey :: PublicKey -> ByteString -> ByteString -> Bool
initHandshakeInitiator :: KeyPair -> IO (HandshakeState, ByteString)
initHandshakeResponder :: KeyPair -> IO (HandshakeState, ByteString)
writeHandshakeMsg :: HandshakeState -> ByteString -> Either String (ByteString, HandshakeState)
readHandshakeMsg :: HandshakeState -> ByteString -> Either String (ByteString, HandshakeState)
sessionComplete :: HandshakeState -> Bool
getRemoteNoiseStaticKey :: HandshakeState -> Maybe ByteString
performFullHandshake :: KeyPair -> KeyPair -> IO (Either String (PeerId, PeerId))
performFullHandshakeWithSessions :: KeyPair -> KeyPair -> IO (Either String (NoiseSession, NoiseSession))
decodePublicKey :: ByteString -> Either String PublicKey

Handshake types

data HandshakeResult Source #

Result of a successful Noise handshake.

Constructors

HandshakeResult
Fields hrRemotePeerId :: !PeerId hrRemotePublicKey :: !PublicKey

Instances

Instances details

Show HandshakeResult Source #
Instance details Defined in Network.LibP2P.Security.Noise.Handshake Methods showsPrec :: Int -> HandshakeResult -> ShowS # show :: HandshakeResult -> String # showList :: [HandshakeResult] -> ShowS #
Eq HandshakeResult Source #
Instance details Defined in Network.LibP2P.Security.Noise.Handshake Methods (==) :: HandshakeResult -> HandshakeResult -> Bool # (/=) :: HandshakeResult -> HandshakeResult -> Bool #

data NoisePayload Source #

Noise handshake payload (protobuf-encoded in messages 2 and 3).

Constructors

NoisePayload
Fields npIdentityKey :: !ByteString Serialized PublicKey protobuf npIdentitySig :: !ByteString Signature over "noise-libp2p-static-key:" \|\| static_pubkey

Instances

Instances details

Show NoisePayload Source #
Instance details Defined in Network.LibP2P.Security.Noise.Handshake Methods showsPrec :: Int -> NoisePayload -> ShowS # show :: NoisePayload -> String # showList :: [NoisePayload] -> ShowS #
Eq NoisePayload Source #
Instance details Defined in Network.LibP2P.Security.Noise.Handshake Methods (==) :: NoisePayload -> NoisePayload -> Bool # (/=) :: NoisePayload -> NoisePayload -> Bool #

newtype HandshakeState Source #

Opaque handshake state wrapping cacophony's NoiseState.

Constructors

HandshakeState
Fields hsNoiseState :: CacophonyState

Payload encoding

encodeNoisePayload :: NoisePayload -> ByteString Source #

Encode a NoisePayload as a minimal protobuf message.

decodeNoisePayload :: ByteString -> Either String NoisePayload Source #

Decode a NoisePayload from protobuf bytes.

buildHandshakePayload :: KeyPair -> ByteString -> NoisePayload Source #

Build a handshake payload from an identity key pair and Noise static pubkey.

validateHandshakePayload :: NoisePayload -> Either String PublicKey Source #

Validate a handshake payload (decode identity key and check structure). Does NOT verify the signature (caller must provide the remote Noise static key).

Static key signing

signStaticKey :: PrivateKey -> ByteString -> Either String ByteString Source #

Sign the Noise static public key with the identity private key.

verifyStaticKey :: PublicKey -> ByteString -> ByteString -> Bool Source #

Verify a signature over the Noise static public key.

Handshake lifecycle

initHandshakeInitiator :: KeyPair -> IO (HandshakeState, ByteString) Source #

Initialize a handshake state for the initiator role. Returns (HandshakeState, noiseStaticPublicKey).

initHandshakeResponder :: KeyPair -> IO (HandshakeState, ByteString) Source #

Initialize a handshake state for the responder role. Returns (HandshakeState, noiseStaticPublicKey).

writeHandshakeMsg :: HandshakeState -> ByteString -> Either String (ByteString, HandshakeState) Source #

Write a handshake message with the given payload. Returns (ciphertext, updatedState).

readHandshakeMsg :: HandshakeState -> ByteString -> Either String (ByteString, HandshakeState) Source #

Read a handshake message and extract the decrypted payload. Returns (plaintext, updatedState).

sessionComplete :: HandshakeState -> Bool Source #

Check whether the handshake is complete.

Remote static key extraction

getRemoteNoiseStaticKey :: HandshakeState -> Maybe ByteString Source #

Extract the remote party's Noise static public key from the handshake state. Returns Just after the remote static key has been transmitted (msg2 for initiator, msg3 for responder in XX pattern).

Convenience

performFullHandshake :: KeyPair -> KeyPair -> IO (Either String (PeerId, PeerId)) Source #

Perform a full 3-message XX handshake between two peers. Returns the remote PeerId as seen by each side.

performFullHandshakeWithSessions :: KeyPair -> KeyPair -> IO (Either String (NoiseSession, NoiseSession)) Source #

Perform a full handshake and return transport sessions for both sides.

Re-exports for payload decoding

decodePublicKey :: ByteString -> Either String PublicKey Source #

Decode a protobuf-encoded PublicKey message.