=pod

=encoding utf-8

=head1 NAME

Net::BitTorrent::DHT::Security - BEP 42 Security Extensions

=head1 SYNOPSIS

    use Net::BitTorrent::DHT::Security;
    my $sec = Net::BitTorrent::DHT::Security->new;

    my $id = $sec->generate_node_id("127.0.0.1");
    if ($sec->validate_node_id($id, "127.0.0.1")) {
        say "Node ID is valid for this IP";
    }

=head1 DESCRIPTION

This module implements the security extensions defined in BEP 42. It provides methods for generating and validating
Node IDs based on the node's IP address to prevent Sybil attacks and routing table poisoning.

=head2 CRC32c Implementation

This module includes a pure-Perl implementation of the CRC32c (Castagnoli) polynomial (0x82F63B78), which is required
by BEP 42 for Node ID calculation.

=head1 METHODS

=head2 C<generate_node_id( $ip, [$seed] )>

Generates a secure, BEP 42 compliant Node ID.

    my $id = $sec->generate_node_id( '1.2.3.4' );

This method computes a node ID based on the provided IP address using the CRC32C algorithm as specified in BEP 42. This
hardens the ID against Sybil attacks by binding it to the IP address.

Expected parameters:

=over

=item C<$ip>

String. The external IP address string (e.g., '1.2.3.4').

=item C<$seed> - optional

A 1-byte integer seed (0-255). If omitted, a random one is used.

=back

=head2 C<validate_node_id( $id_bin, $ip )>

Validates a node ID against an IP address.

    my $ok = $sec->validate_node_id( $id, $ip );

This method checks if the provided Node ID is valid for the given IP address according to BEP 42 criteria (matching the
first 21 bits of the CRC32c hash).

Expected parameters:

=over

=item C<$id_bin>

String. The 20-byte binary node ID.

=item C<$ip>

String. The IP address string associated with the node.

=back

=head1 SEE ALSO

BEP 42: L<http://www.bittorrent.org/beps/bep_0042.html>

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 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.

=cut
