/ 
Net-BitTorrent-0.039_002
⭐ Starred 13 / Net::BitTorrent::Torrent
Security Advisories (4)
CVE-2026-57079 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl write files outside the download directory via path traversal in peer-supplied metadata. Net::BitTorrent validates file path components only on the .torrent-file ingest path. The peer and magnet metadata path (_on_metadata_received, reached from the BEP09 ut_metadata extension) passes attacker-supplied file names straight to Storage::add_file and Storage::_parse_file_tree, where Path::Tiny's child() does not collapse "..". A v2 file tree key, a v1 files[].path element, or a single-file name containing ".." segments therefore resolves outside the download directory. Because the peer also controls the piece hashes and the served bytes, content verification passes, so a malicious magnet or peer writes attacker-chosen content to an attacker-chosen path on the downloading host.

CVE-2026-57080 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl allow remote memory exhaustion via an uncapped peer-wire message-length prefix. The peer-wire framing in _process_messages trusts the 4-byte length prefix sent by a connected peer with no upper bound, while receive_data appends every inbound byte to the input buffer. A peer announces a length prefix of up to about 4 GiB and then streams bytes; the decoder waits until the buffer holds the full message before processing it, so the buffer grows without limit. Peer connections are unauthenticated, so any peer in the swarm exhausts the downloading process's memory. The largest legitimate message is a 16 KiB piece block, so any announced length far above that is anomalous.

CVE-2026-57082 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl generate the MSE Diffie-Hellman private key with a non-cryptographic PRNG. The MSE (Message Stream Encryption) handshake derives its 160-bit Diffie-Hellman private key from Perl's rand(), a non-cryptographic drand48-class generator seeded once per process, in KeyExchange.pm. The shared secret and the RC4 keys derived from it (the SHA-1 of "keyA" or "keyB", the shared secret, and the infohash) therefore depend entirely on a predictable PRNG. The same handshake sends, in cleartext, random padding drawn from the same rand() sequence in _random_pad, immediately after the public key and the private-key draw. A passive observer of the handshake recovers the PRNG state from the cleartext padding, reconstructs the private key, computes the shared secret from the peer's public key on the wire, derives the RC4 keys, and decrypts the connection, defeating the passive-observation obfuscation MSE provides.

CVE-2026-57081 (2026-06-30)

Net::BitTorrent versions through 2.0.1 for Perl allow remote memory exhaustion via deeply nested bencoded input. bdecode recurses once per nested list or dictionary level with no depth cap, and each recursive call receives the remaining buffer by value while the list and dictionary branches capture the whole remainder, so every live recursion frame keeps its own copy of the shrinking buffer (O(N^2) bytes for an N-deep input). The decoder runs on every untrusted bencode source: .torrent files, BEP09 metadata fetched from peers, DHT messages, and tracker responses. A bencoded input of roughly 150,000 nested lists (about 150 KB on the wire) drives multi-gigabyte peak memory, so one short message from any peer, or one crafted .torrent file or magnet link, terminates the client.

NAME

Net::BitTorrent::Torrent - Class Representing a Single .torrent File

Synopsis

use Net::BitTorrent::Torrent;

my $torrent = Net::BitTorrent::Torrent->new({Path => q[a.legal.torrent]})
    or die q[Cannot load .torrent];

$torrent->on_event(
    q[piece_hash_pass],
    sub {
        printf qq[%s is % 3.2f%% complete\r], $torrent->name,
            (scalar grep {$_} split q[], unpack q[b*], $torrent->bitfield)
            / $torrent->piece_count * 100;
    }
);

$torrent->hashcheck;    # Verify any existing data

Description

Net::BitTorrent::Torrent objects are typically created by the Net::BitTorrent class.

Standalone Net::BitTorrent::Torrent objects can be made for informational use. See new ( ) and queue ( ).

Constructor

new ( { [ARGS] } )

Creates a Net::BitTorrent::Torrent object. This constructor is called by Net::BitTorrent::add_torrent( ).

new( ) accepts arguments as a hash, using key-value pairs:

BaseDir

The root directory used to store the files related to this torrent. This directory is created if not preexisting.

This is an optional parameter.

Default: ./ (Current working directory)

Client

The Net::BitTorrent object this torrent will eventually be served from.

This is an optional parameter.

No default. Without a defined parent client, his object is very limited in capability. Basic information and hash checking only. Orphan objects are obviously not queued automatically and must be added to a client manually.

Path

Filename of the .torrent file to load.

This is the only required parameter.

Status

Initial status of the torrent. This parameter is ORed with the loaded and queued (if applicable) values.

For example, you could set the torrent to automatically start after hashcheck with { [...] Status => 4, [...] }.

This is an optional parameter.

Default: 1 (started)

See also: status ( )

Note: This is alpha code and may not work correctly.

Methods

bitfield ( )

Returns a bitfield representing the pieces that have been successfully downloaded.

comment ( )

Returns the (optional) comment the original creator included in the .torrent metadata.

created_by ( )

Returns the (optional) "created by" string included in the .torrent metadata. This is usually a software version.

creation_date ( )

Returns the (optional) creation time of the torrent, in standard UNIX epoch format.

downloaded ( )

Returns the total amount downloaded from remote peers since the client started transferring data related to this .torrent.

See also: uploaded ( )

error ( )

Returns the most recent error that caused the software to set the error status. Torrents with active errors are automatically stopped and must be started.

See also: status ( ), start ( )

files ( )

Returns a list of Net::BitTorrent::Torrent::File objects representing all files contained in the related .torrent file.

hashcheck ( )

Verifies the integrity of all files associated with this torrent.

This is a blocking method; all processing will stop until this function returns.

See also: bitfield ( ), status ( )

infohash ( )

Returns the 20 byte SHA1 hash used to identify this torrent internally, with trackers, and with remote peers.

is_complete ( )

Returns a bool value based on download progress. Returns true when we have completed every file with a priority above 0. Otherwise, returns false.

See also: Net::BitTorrent::Torrent::File->priority()

name ( )

Returns the advisory name used when creating the related files on disk.

In a single file torrent, this is used as the filename by default. In a multiple file torrent, this is used as the containing directory for related files.

on_event ( TYPE, CODEREF )

Net::BitTorrent::Torrent provides per-torrent callbacks. For example, to catch all attempts to read from a file, use $torrent->on_event( 'file_read', \&on_read ). These per- torrent callbacks are especially useful for standalone torrents.

See the Events section for more.

path ( )

Returns the filename of the torrent this object represents.

piece_count ( )

The number of pieces this torrent's data is broken into.

private ( )

Returns bool value dependent on whether the private flag is set in the .torrent metadata. Private torrents disallow information sharing via DHT and PEX.

queue ( CLIENT )

Adds a standalone (or orphan) torrent object to the particular CLIENT object's queue.

See also: remove_torrent ( )

raw_data ( )

Returns the bdecoded metadata. found in the .torrent file.

size ( )

Returns the total size of all files listed in the .torrent file.

status ( )

Returns the internal status of this Net::BitTorrent::Torrent object. States are bitwise AND values of...

Value Type Notes
1 STARTED Client is (making an attempt to be) active in the swarm
2 CHECKING Currently hashchecking (possibly in another thread)
4 START_AFTER_CHECK (Unused in this version)
8 CHECKED Files of this torrent have been checked
16 ERROR Activity is halted and may require user intervention (Unused in this version)
32 PAUSED Sockets are kept open but no piece data is sent or requested
64 LOADED Torrent has been parsed without error
128 QUEUED Has an associated Net::BitTorrent parent

For example, a status of 201 implies the torrent is QUEUED | LOADED | CHECKED | STARTED.

When torrents have the a status that indicates an error, they must be restarted (if possible). The reason for the error may be returned by error ( ).

Import the :status tag and you'll get the various status keywords in your namespace.

Note: This is alpha and may not work as advertised. Yet.

start ( )

Starts a paused or stopped torrent.

See also: status ( ), stop ( ), pause ( )

stop ( )

Stops an active or paused torrent. All related sockets (peers) are disconnected and all files are closed.

See also: status ( ), start ( ), pause ( )

pause ( )

Pauses an active torrent without closing related sockets.

See also: status ( ), stop ( ), start ( )

trackers

Returns a list of all Net::BitTorrent::Torrent::Tracker objects related to the torrent.

uploaded ( )

Returns the total amount uploaded to remote peers since the client started transferring data related to this .torrent.

See also: downloaded ( )

Events

When triggered, per-torrent callbacks receive two arguments: the Net::BitTorrent::Torrent object and a hashref containing pertinent information. Per-torrent callbacks also trigger client-wide callbacks when the current torrent is queued.

Currently, per-torrent callbacks are limited to tracker-, piece-, and file-related events. See Net::BitTorrent for client-wide callbacks.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

Copyright (C) 2008 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.

When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.

Neither this module nor the Author is affiliated with BitTorrent, Inc.