libp2p.security.noise package

Subpackages

Submodules

libp2p.security.noise.exceptions module

exception libp2p.security.noise.exceptions.HandshakeHasNotFinished

Bases: NoiseFailure

exception libp2p.security.noise.exceptions.InvalidSignature

Bases: NoiseFailure

exception libp2p.security.noise.exceptions.NoiseFailure

Bases: HandshakeFailure

exception libp2p.security.noise.exceptions.NoiseStateError

Bases: NoiseFailure

Raised when anything goes wrong in the noise state in noiseprotocol package.

exception libp2p.security.noise.exceptions.PeerIDMismatchesPubkey

Bases: NoiseFailure

libp2p.security.noise.io module

class libp2p.security.noise.io.BaseNoiseMsgReadWriter(conn: IRawConnection, noise_state: NoiseConnection)

Bases: EncryptedMsgReadWriter

The base implementation of noise message reader/writer.

encrypt and decrypt are not implemented here, which should be implemented by the subclasses.

async close() → None
get_remote_address() → tuple[str, int] | None

Get remote address if supported by the underlying connection.

noise_state: NoiseConnection
prefix: bytes = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
async read_msg(prefix_encoded: bool = False) → bytes
read_writer: NoisePacketReadWriter
async write_msg(msg: bytes, prefix_encoded: bool = False) → None
class libp2p.security.noise.io.NoiseHandshakeReadWriter(conn: IRawConnection, noise_state: NoiseConnection)

Bases: BaseNoiseMsgReadWriter

decrypt(data: bytes) → bytes
encrypt(data: bytes) → bytes
class libp2p.security.noise.io.NoisePacketReadWriter(read_write_closer: ReadWriteCloser)

Bases: FixedSizeLenMsgReadWriter

size_len_bytes: int = 2
class libp2p.security.noise.io.NoiseTransportReadWriter(conn: IRawConnection, noise_state: NoiseConnection)

Bases: BaseNoiseMsgReadWriter

decrypt(data: bytes) → bytes
encrypt(data: bytes) → bytes

libp2p.security.noise.messages module

class libp2p.security.noise.messages.NoiseExtensions(webtransport_certhashes: list[bytes] = <factory>, stream_muxers: list[str] = <factory>, early_data: bytes | None = None)

Bases: object

Noise protocol extensions for advanced features like WebTransport and early data.

This class provides support for: - WebTransport certificate hashes for WebTransport support - Stream multiplexers supported by this peer (spec compliant) - Early data payload for 0-RTT support (Python extension)

early_data: bytes | None = None
classmethod from_protobuf(pb_ext: NoiseExtensions) → NoiseExtensions

Create from protobuf message.

Args:

pb_ext: The protobuf message to convert

Returns:

NoiseExtensions: The Python dataclass representation

has_early_data() → bool

Check if early data is present.

Returns:

bool: True if early data is present

has_stream_muxers() → bool

Check if stream multiplexers are present.

Returns:

bool: True if stream multiplexers are present

has_webtransport_certhashes() → bool

Check if WebTransport certificate hashes are present.

Returns:

bool: True if WebTransport certificate hashes are present

is_empty() → bool

Check if extensions are empty (no data).

Returns:

bool: True if no extensions data is present

stream_muxers: list[str]
to_protobuf() → NoiseExtensions

Convert to protobuf message.

Returns:

noise_pb.NoiseExtensions: The protobuf message representation

webtransport_certhashes: list[bytes]
class libp2p.security.noise.messages.NoiseHandshakePayload(id_pubkey: PublicKey, id_sig: bytes, extensions: NoiseExtensions | None = None)

Bases: object

Noise handshake payload containing peer identity and optional extensions.

This class represents the payload sent during Noise handshake and provides: - Peer identity verification through public key and signature - Optional extensions for advanced features like WebTransport and stream muxers

classmethod deserialize(protobuf_bytes: bytes) → NoiseHandshakePayload

Deserialize protobuf bytes to handshake payload.

Args:

protobuf_bytes: The serialized protobuf message

Returns:

NoiseHandshakePayload: The deserialized handshake payload

Raises:

ValueError: If the protobuf data is invalid

extensions: NoiseExtensions | None = None
get_early_data() → bytes | None

Get early data from extensions.

Returns:

bytes | None: The early data if present

has_early_data() → bool

Check if early data is present in extensions.

Returns:

bool: True if early data is present

has_extensions() → bool

Check if extensions are present.

Returns:

bool: True if extensions are present

id_pubkey: PublicKey
id_sig: bytes
serialize() → bytes

Serialize the handshake payload to protobuf bytes.

Returns:

bytes: The serialized protobuf message

Raises:

ValueError: If the payload is invalid

libp2p.security.noise.messages.make_data_to_be_signed(noise_static_pubkey: PublicKey) → bytes
libp2p.security.noise.messages.make_handshake_payload_sig(id_privkey: PrivateKey, noise_static_pubkey: PublicKey) → bytes
libp2p.security.noise.messages.verify_handshake_payload_sig(payload: NoiseHandshakePayload, noise_static_pubkey: PublicKey) → bool
Verify if the signature

  1. is composed of the data SIGNED_DATA_PREFIX`++`noise_static_pubkey and

  2. signed by the private key corresponding to id_pubkey

libp2p.security.noise.patterns module

Noise protocol handshake patterns implementation.

This module provides the core handshake patterns for the Noise protocol, including the abstract interface and concrete implementations like the XX pattern. The XX pattern is the standard for libp2p Noise connections, providing mutual authentication and forward secrecy through a three-message handshake.

class libp2p.security.noise.patterns.BasePattern

Bases: IPattern

Base implementation for Noise protocol handshake patterns.

Provides common functionality for Noise handshake patterns including: - Noise state creation and management - Handshake payload generation with early data support - Protocol-specific configuration

create_noise_state() → NoiseConnection
early_data: bytes | None
libp2p_privkey: PrivateKey
local_peer: ID
make_handshake_payload(extensions: NoiseExtensions | None = None) → NoiseHandshakePayload
noise_static_key: PrivateKey
protocol_name: bytes
class libp2p.security.noise.patterns.IPattern

Bases: ABC

Abstract interface for Noise protocol handshake patterns.

Defines the contract that all Noise handshake implementations must follow, ensuring consistent behavior across different protocol patterns.

abstract async handshake_inbound(conn: IRawConnection) → ISecureConn

Perform inbound handshake as responder.

Args:

conn: Raw connection to perform handshake on

Returns:

ISecureConn: Established secure connection

Raises:

NoiseStateError: If handshake state is invalid InvalidSignature: If signature verification fails HandshakeHasNotFinished: If handshake doesn’t complete properly

abstract async handshake_outbound(conn: IRawConnection, remote_peer: ID) → ISecureConn

Perform outbound handshake as initiator.

Args:

conn: Raw connection to perform handshake on remote_peer: Expected remote peer ID for verification

Returns:

ISecureConn: Established secure connection

Raises:

NoiseStateError: If handshake state is invalid InvalidSignature: If signature verification fails PeerIDMismatchesPubkey: If peer ID doesn’t match public key HandshakeHasNotFinished: If handshake doesn’t complete properly

class libp2p.security.noise.patterns.PatternXX(local_peer: ID, libp2p_privkey: PrivateKey, noise_static_key: PrivateKey, early_data: bytes | None = None)

Bases: BasePattern

Noise XX handshake pattern implementation.

The XX pattern provides mutual authentication and forward secrecy through a three-message handshake: 1. Initiator sends empty message 2. Responder sends static public key + handshake payload 3. Initiator sends static public key + handshake payload

This pattern is the standard for libp2p Noise connections.

async handshake_inbound(conn: IRawConnection) → ISecureConn

Perform inbound handshake as responder.

Args:

conn: Raw connection to perform handshake on

Returns:

ISecureConn: Established secure connection

Raises:

NoiseStateError: If handshake state is invalid InvalidSignature: If signature verification fails HandshakeHasNotFinished: If handshake doesn’t complete properly

async handshake_outbound(conn: IRawConnection, remote_peer: ID) → ISecureConn

Perform outbound handshake as initiator.

Args:

conn: Raw connection to perform handshake on remote_peer: Expected remote peer ID for verification

Returns:

ISecureConn: Established secure connection

Raises:

NoiseStateError: If handshake state is invalid InvalidSignature: If signature verification fails PeerIDMismatchesPubkey: If peer ID doesn’t match public key HandshakeHasNotFinished: If handshake doesn’t complete properly

libp2p.security.noise.transport module

Enhanced Noise transport implementation.

This module provides an enhanced Noise transport with support for advanced features including early data, WebTransport integration, and rekey management. The transport uses the XX handshake pattern for mutual authentication and forward secrecy.

class libp2p.security.noise.transport.Transport(libp2p_keypair: KeyPair, noise_privkey: PrivateKey, early_data: bytes | None = None, early_data_handler: EarlyDataHandler | None = None, rekey_policy: RekeyPolicy | None = None)

Bases: ISecureTransport

Enhanced Noise transport with advanced features support.

cache_static_key(peer_id: ID, static_key: bytes) → None

Cache a static key for a peer.

Args:

peer_id: The peer ID static_key: The static key to cache

clear_static_key_cache() → None

Clear the static key cache.

early_data: bytes | None
early_data_manager: EarlyDataManager
get_cached_static_key(peer_id: ID) → bytes | None

Get cached static key for a peer.

Args:

peer_id: The peer ID

Returns:

The cached static key or None if not found

get_pattern() → IPattern

Get the handshake pattern for the connection.

Returns:

IPattern: The XX handshake pattern

libp2p_privkey: PrivateKey
local_peer: ID
noise_privkey: PrivateKey
rekey_manager: RekeyManager
async secure_inbound(conn: IRawConnection) → ISecureConn

Perform inbound secure connection.

Args:

conn: Raw connection

Returns:

ISecureConn: Secure connection

async secure_outbound(conn: IRawConnection, peer_id: ID) → ISecureConn

Perform outbound secure connection.

Args:

conn: Raw connection peer_id: Remote peer ID

Returns:

ISecureConn: Secure connection

webtransport_support: WebTransportSupport

Module contents