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.30
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
34       an address belongs to a specific network or whether an address is
35       public 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_private_ipv6($ip)
172       This subroutine checks whether the address belongs to the IPv6 private
173       network - "FC00::/7" - as defined by RFC 4193
174       <http://tools.ietf.org/html/rfc4193>.
175
176   is_linklocal_ipv6($ip)
177       This subroutine checks whether the address belongs to the IPv6 link-
178       local unicast network - "FE80::/10" - as defined by RFC 4291
179       <http://tools.ietf.org/html/rfc4291>.
180
181   is_multicast_ipv6($ip)
182       This subroutine checks whether the address belongs to the IPv6
183       multicast network - "FF00::/8" - as defined by RFC 4291
184       <http://tools.ietf.org/html/rfc4291>.
185
186   is_public_ipv4($ip), is_public_ipv6($ip), is_public_ip($ip)
187       These subroutines check whether the given IP address belongs to any of
188       the special case networks defined previously. Note that this is not
189       simply the opposite of checking "is_private_ipv4()" or
190       "is_private_ipv6()". The private networks are a subset of all the
191       special case networks.
192
193   is_linklocal_ip($ip)
194       This subroutine checks whether the address belongs to the IPv4 or IPv6
195       link-local unicast network.
196
197   is_loopback_ip($ip)
198       This subroutine checks whether the address is the IPv4 or IPv6 loopback
199       address.
200
201   is_multicast_ip($ip)
202       This subroutine checks whether the address belongs to the IPv4 or IPv6
203       multicast network.
204
205   is_private_ip($ip)
206       This subroutine checks whether the address belongs to the IPv4 or IPv6
207       private network.
208

OBJECT-ORIENTED INTERFACE

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

SEE ALSO

217       IPv4
218
219       [RFC 5735] [RFC 1918]
220
221       IPv6
222
223       [RFC 2460] [RFC 4193] [RFC 4291] [RFC 6434]
224

ACKNOWLEDGEMENTS

226       Thanks to Richard Sonnen <sonnen@richardsonnen.com> for writing the
227       Data::Validate module.
228
229       Thanks to Matt Dainty <matt@bodgit-n-scarper.com> for adding the
230       "is_multicast_ipv4()" and "is_linklocal_ipv4()" code.
231

BUGS

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

SOURCE

242       The source code repository for Data-Validate-IP can be found at
243       <https://github.com/houseabsolute/Data-Validate-IP>.
244

AUTHORS

246       •   Neil Neely <neil@neely.cx>
247
248       •   Dave Rolsky <autarch@urth.org>
249

CONTRIBUTOR

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