/ 
Net-BitTorrent-v2.0.0
River stage zero No dependents
⭐ Starred 13 GitHub stars
/ Net::BitTorrent::Protocol::MSE

NAME

Net::BitTorrent::Protocol::MSE - Message Stream Encryption (PE/MSE)

SYNOPSIS

use Net::BitTorrent::Protocol::MSE;

my $mse = Net::BitTorrent::Protocol::MSE->new(
    infohash     => $bin_ih,
    is_initiator => 1
);

# Step 1: Send initial Public Key
my $out = $mse->write_buffer( );

# Step 2: Feed data from socket until state is 'PAYLOAD'
while ($mse->state ne 'PAYLOAD') {
    $mse->receive_data($raw_incoming);
    my $reply = $mse->write_buffer( );
    # send $reply to peer
}

# Step 3: Transparently encrypt/decrypt PWP messages
my $encrypted = $mse->encrypt_data( $pwp_payload );
my $plain     = $mse->decrypt_data( $raw_from_socket );

DESCRIPTION

This module implements the Message Stream Encryption protocol used by BitTorrent to avoid traffic shaping and improve privacy. It provides a layer of obfuscation for BitTorrent traffic, helping to prevent passive traffic analysis and "throttling" by ISPs.

Security Disclaimer

MSE is not designed to provide strong cryptographic security or authentication. It is purely an obfuscation layer designed to make the BitTorrent protocol difficult to identify via simple pattern matching.

METHODS

new( %params )

Creates a new MSE handler object.

Expected parameters:

infohash

The 20-byte binary infohash of the torrent. Can be undef for initiators if using on_infohash_probe.

is_initiator

Boolean. True if we are starting the connection.

on_infohash_probe - optional

A code reference used by the responder to identify the infohash in incoming connections.

allow_plaintext - optional

Boolean. Whether to allow falling back to plaintext. Defaults to true.

receive_data( $data )

Handles incoming handshake or payload data.

my $decrypted = $mse->receive_data( $raw_chunk );

This method processes the MSE handshake phases. Once the handshake is complete (state is 'PAYLOAD'), it returns decrypted data.

Expected parameters:

$data

The raw data received from the transport.

encrypt_data( $data )

Encrypts outgoing data.

my $encrypted = $mse->encrypt_data( $pwp_message );

This method encrypts data using the negotiated RC4 key if the handshake is complete.

Expected parameters:

$data

The plaintext data to encrypt.

decrypt_data( $data )

Decrypts incoming data.

my $decrypted = $mse->decrypt_data( $raw_chunk );

Alias for receive_data.

Expected parameters:

$data

The encrypted data.

write_buffer( )

Returns pending bytes that must be sent to the remote peer to advance the handshake or provide encryption responses.

my $out = $mse->write_buffer();

supported( )

Returns true if MSE is supported by the system.

say "MSE enabled" if $mse->supported();

state( )

Returns the current MSE handshake state:

  • A_WAIT_PUBKEY, B_WAIT_PUBKEY: Waiting for Diffie-Hellman exchange.

  • A_WAIT_SELECT, B_WAIT_REQS: Synchronizing on the infohash.

  • PAYLOAD: Handshake complete; stream is now obfuscated.

buffer_in( )

Returns the internal input buffer.

buffer_out( )

Returns the internal output buffer.

ARCHITECTURE

MSE uses a 768-bit Diffie-Hellman key exchange to derive a shared secret, which is then used to seed two RC4 stream ciphers (one for each direction).

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

Copyright (C) 2008-2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.