1Data::Validate::IP(3) User Contributed Perl DocumentationData::Validate::IP(3)
2
3
4

NAME

6       Data::Validate::IP - IPv4 and IPv6 validation methods
7

VERSION

9       version 0.31
10

SYNOPSIS

12         use Data::Validate::IP qw(is_ipv4 is_ipv6);
13
14         my $suspect = '1.2.3.4';
15         if (is_ipv4($suspect)) {
16             print "Looks like an IPv4 address";
17         }
18         else {
19             print "Not an IPv4 address\n";
20         }
21
22         $suspect = '::1234';
23         if (is_ipv6($suspect)) {
24             print "Looks like an IPv6 address";
25         }
26         else {
27             print "Not an IPv6 address\n";
28         }
29

DESCRIPTION

31       This module provides a number IP address validation subs that both
32       validate and untaint their input. This includes both basic validation
33       (is_ipv4() and is_ipv6()) and special cases like checking whether an
34       address belongs to a specific network or whether an address is public
35       or private (reserved).
36

USAGE AND SECURITY RECOMMENDATIONS

38       It's important to understand that if is_ipv4($ip), is_ipv6($ip), or
39       is_ip($ip) return false, then all other validation functions for that
40       IP address family will also return false. So for example, if
41       is_ipv4($ip) returns false, then is_private_ipv4($ip) and
42       is_public_ipv4($ip) will both also return false.
43
44       This means that simply calling is_private_ipv4($ip) by itself is not
45       sufficient if you are dealing with untrusted input. You should always
46       check is_ipv4($ip) as well. This applies as well when using IPv6
47       functions or generic functions like is_private_ip($ip).
48
49       There are security implications to this around certain oddly formed
50       addresses.  Notably, an address like "010.0.0.1" is technically valid,
51       but the operating system will treat "010" as an octal number. That
52       means that "010.0.0.1" is equivalent to "8.0.0.1", not "10.0.0.1".
53
54       However, this module's is_ipv4($ip) and is_ip($ip) functions will
55       return false for addresses like "010.0.0.1" which have octal
56       components. And of course that means that it also returns false for
57       is_private_ipv4($ip) and is_public_ipv4($ip).
58

FUNCTIONS

60       All of the functions below are exported by default.
61
62       All functions return an untainted value if the test passes and undef if
63       it fails. In theory, this means that you should always check for a
64       defined status explicitly but in practice there are no valid IP
65       addresses where the string form evaluates to false in Perl.
66
67       Note that none of these functions actually attempt to test whether the
68       given IP address is routable from your device; they are purely semantic
69       checks.
70
71   is_ipv4($ip), is_ipv6($ip), is_ip($ip)
72       These functions simply check whether the address is a valid IPv4 or
73       IPv6 address.
74
75   is_innet_ipv4($ip, $network)
76       This subroutine checks whether the address belongs to the given IPv4
77       network.  The $network argument can either be a string in CIDR notation
78       like "15.0.15.0/24" or a NetAddr::IP object.
79
80       This subroutine used to accept many more forms of network
81       specifications (anything Net::Netmask accepts) but this has been
82       deprecated.
83
84   is_unroutable_ipv4($ip)
85       This subroutine checks whether the address belongs to any of several
86       special use IPv4 networks - "0.0.0.0/8", "100.64.0.0/10",
87       "192.0.0.0/29", "198.18.0.0/15", "240.0.0.0/4" - as defined by RFC 5735
88       <http://tools.ietf.org/html/rfc5735>, RFC 6333
89       <http://tools.ietf.org/html/rfc6333>, and RFC 6958
90       <http://tools.ietf.org/html/rfc6598>.
91
92       Arguably, these should be broken down further but this subroutine will
93       always exist for backwards compatibility.
94
95   is_private_ipv4($ip)
96       This subroutine checks whether the address belongs to any of the
97       private IPv4 networks - "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"
98       - as defined by RFC 5735 <http://tools.ietf.org/html/rfc5735>.
99
100   is_loopback_ipv4($ip)
101       This subroutine checks whether the address belongs to the IPv4 loopback
102       network - "127.0.0.0/8" - as defined by RFC 5735
103       <http://tools.ietf.org/html/rfc5735>.
104
105   is_linklocal_ipv4($ip)
106       This subroutine checks whether the address belongs to the IPv4 link
107       local network - "169.254.0.0/16" - as defined by RFC 5735
108       <http://tools.ietf.org/html/rfc5735>.
109
110   is_testnet_ipv4($ip)
111       This subroutine checks whether the address belongs to any of the IPv4
112       TEST-NET networks for use in documentation and example code -
113       "192.0.2.0/24", "198.51.100.0/24", and "203.0.113.0/24" - as defined by
114       RFC 5735 <http://tools.ietf.org/html/rfc5735>.
115
116   is_anycast_ipv4($ip)
117       This subroutine checks whether the address belongs to the 6to4 relay
118       anycast network - "192.88.99.0/24" - as defined by RFC 5735
119       <http://tools.ietf.org/html/rfc5735>.
120
121   is_multicast_ipv4($ip)
122       This subroutine checks whether the address belongs to the IPv4
123       multicast network - "224.0.0.0/4" - as defined by RFC 5735
124       <http://tools.ietf.org/html/rfc5735>.
125
126   is_loopback_ipv6($ip)
127       This subroutine checks whether the address is the IPv6 loopback address
128       - "::1/128" - as defined by RFC 4291
129       <http://tools.ietf.org/html/rfc4291>.
130
131   is_ipv4_mapped_ipv6($ip)
132       This subroutine checks whether the address belongs to the IPv6
133       IPv4-mapped address network - "::ffff:0:0/96" - as defined by RFC 4291
134       <http://tools.ietf.org/html/rfc4291>.
135
136   is_discard_ipv6($ip)
137       This subroutine checks whether the address belongs to the IPv6 discard
138       prefix network - "100::/64" - as defined by RFC 6666
139       <http://tools.ietf.org/html/rfc6666>.
140
141   is_special_ipv6($ip)
142       This subroutine checks whether the address belongs to the IPv6 special
143       network - "2001::/23" - as defined by RFC 2928
144       <http://tools.ietf.org/html/rfc2928>.
145
146   is_teredo_ipv6($ip)
147       This subroutine checks whether the address belongs to the IPv6 TEREDO
148       network - "2001::/32" - as defined by RFC 4380
149       <http://tools.ietf.org/html/rfc4380>.
150
151       Note that this network is a subnet of the larger special network at
152       "2001::/23".
153
154   is_orchid_ipv6($ip)
155       This subroutine checks whether the address belongs to the IPv6 ORCHID
156       network - "2001::/32" - as defined by RFC 4380
157       <http://tools.ietf.org/html/rfc4380>.
158
159       Note that this network is a subnet of the larger special network at
160       "2001::/23".
161
162       This network is currently scheduled to be returned to the special pool
163       in March of 2014 unless the IETF extends its use. If that happens this
164       subroutine will continue to exist but will always return false.
165
166   is_documentation_ipv6($ip)
167       This subroutine checks whether the address belongs to the IPv6
168       documentation network - "2001:DB8::/32" - as defined by RFC 3849
169       <http://tools.ietf.org/html/rfc3849>.
170
171   is_unspecified_ipv6($ip)
172       This subroutine checks whether the address belongs to the IPv6
173       unspecified network - "::0/128" - as defined by RFC 4291
174       <http://tools.ietf.org/html/rfc4291>.. Note that the address in this
175       subnet is neither private nor public.
176
177   is_private_ipv6($ip)
178       This subroutine checks whether the address belongs to the IPv6 private
179       network - "FC00::/7" - as defined by RFC 4193
180       <http://tools.ietf.org/html/rfc4193>.
181
182   is_linklocal_ipv6($ip)
183       This subroutine checks whether the address belongs to the IPv6 link-
184       local unicast network - "FE80::/10" - as defined by RFC 4291
185       <http://tools.ietf.org/html/rfc4291>.
186
187   is_multicast_ipv6($ip)
188       This subroutine checks whether the address belongs to the IPv6
189       multicast network - "FF00::/8" - as defined by RFC 4291
190       <http://tools.ietf.org/html/rfc4291>.
191
192   is_public_ipv4($ip), is_public_ipv6($ip), is_public_ip($ip)
193       These subroutines check whether the given IP address belongs to any of
194       the special case networks defined previously. Note that this is not
195       simply the opposite of checking is_private_ipv4() or is_private_ipv6().
196       The private networks are a subset of all the special case networks.
197
198   is_linklocal_ip($ip)
199       This subroutine checks whether the address belongs to the IPv4 or IPv6
200       link-local unicast network.
201
202   is_loopback_ip($ip)
203       This subroutine checks whether the address is the IPv4 or IPv6 loopback
204       address.
205
206   is_multicast_ip($ip)
207       This subroutine checks whether the address belongs to the IPv4 or IPv6
208       multicast network.
209
210   is_private_ip($ip)
211       This subroutine checks whether the address belongs to the IPv4 or IPv6
212       private network.
213

OBJECT-ORIENTED INTERFACE

215       This module can also be used as a class. You can call
216       "Data::Validate::IP->new()" to get an object and then call any of the
217       validation subroutines as methods on that object. This is somewhat
218       pointless since the object will never contain any state but this
219       interface is kept for backwards compatibility.
220

SEE ALSO

222       IPv4
223
224       [RFC 5735] [RFC 1918]
225
226       IPv6
227
228       [RFC 2460] [RFC 4193] [RFC 4291] [RFC 6434]
229

ACKNOWLEDGEMENTS

231       Thanks to Richard Sonnen <sonnen@richardsonnen.com> for writing the
232       Data::Validate module.
233
234       Thanks to Matt Dainty <matt@bodgit-n-scarper.com> for adding the
235       is_multicast_ipv4() and is_linklocal_ipv4() code.
236

BUGS

238       Please report any bugs or feature requests to
239       "bug-data-validate-ip@rt.cpan.org", or through the web interface at
240       <http://rt.cpan.org>. I will be notified, and then you'll automatically
241       be notified of progress on your bug as I make changes.
242
243       Bugs may be submitted at
244       <https://github.com/houseabsolute/Data-Validate-IP/issues>.
245

SOURCE

247       The source code repository for Data-Validate-IP can be found at
248       <https://github.com/houseabsolute/Data-Validate-IP>.
249

AUTHORS

251       •   Neil Neely <neil@neely.cx>
252
253       •   Dave Rolsky <autarch@urth.org>
254

CONTRIBUTOR

256       Gregory Oschwald <goschwald@maxmind.com>
257
259       This software is copyright (c) 2022 by Neil Neely.
260
261       This is free software; you can redistribute it and/or modify it under
262       the same terms as the Perl 5 programming language system itself.
263
264       The full text of the license can be found in the LICENSE file included
265       with this distribution.
266
267
268
269perl v5.36.0                      2023-01-31             Data::Validate::IP(3)
Impressum