2 * Copyright (C) 1996-2020 The Squid Software Foundation and contributors
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
9 /* DEBUG: section 14 IP Storage and Handling */
11 #ifndef _SQUID_SRC_IP_ADDRESS_H
12 #define _SQUID_SRC_IP_ADDRESS_H
14 #include "ip/forward.h"
19 #include <sys/socket.h>
22 #include <netinet/in.h>
25 #include <netinet/ip.h>
38 * Holds and manipulates IPv4, IPv6, and Socket Addresses.
44 /** @name Constructors and Destructor */
46 Address() { setEmpty(); }
47 Address(const struct in_addr
&);
48 Address(const struct sockaddr_in
&);
49 Address(const struct in6_addr
&);
50 Address(const struct sockaddr_in6
&);
51 Address(const struct hostent
&);
52 Address(const struct addrinfo
&);
57 /** @name Assignment Operators */
59 Address
& operator =(struct sockaddr_in
const &s
);
60 Address
& operator =(struct sockaddr_storage
const &s
);
61 Address
& operator =(struct in_addr
const &s
);
62 Address
& operator =(struct in6_addr
const &s
);
63 Address
& operator =(struct sockaddr_in6
const &s
);
64 bool operator =(const struct hostent
&s
);
65 bool operator =(const struct addrinfo
&s
);
66 bool operator =(const char *s
);
69 /** @name Boolean Operators */
71 bool operator ==(Address
const &s
) const;
72 bool operator !=(Address
const &s
) const;
73 bool operator >=(Address
const &rhs
) const;
74 bool operator <=(Address
const &rhs
) const;
75 bool operator >(Address
const &rhs
) const;
76 bool operator <(Address
const &rhs
) const;
81 /** Test whether content can be used as an IPv4 address
82 \retval true if content was received as an IPv4-Mapped address
83 \retval false if content was received as a non-mapped IPv6 native address.
87 /** Test whether content can be used as an IPv6 address.
88 \retval true if content is a non IPv4-mapped address.
89 \retval false if content is IPv4-mapped.
93 /** Test whether content can be used as a Socket address.
94 \retval true if address AND port are both set
95 \retval true if content was received as a Socket address with port
96 \retval false if port in unset (zero)
98 bool isSockAddr() const;
100 /** Content-neutral test for whether the specific IP case ANY_ADDR is stored.
101 * This is the default content of a new undefined Ip::Address object.
102 \retval true IPv4 0.0.0.0
104 \retval false anything else.
106 bool isAnyAddr() const;
108 /** Content-neutral test for whether the specific IP case NO_ADDR is stored.
109 \retval true IPv4 255.255.255.255
110 \retval true IPv6 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
111 \retval false anything else.
113 bool isNoAddr() const;
115 /** Content-neutral test for whether the specific IP case LOCALHOST is stored.
116 * This is the default content of a new undefined Ip::Address object.
117 \retval true IPv4 127.0.0.1
118 \retval true IPv6 ::1
119 \retval false anything else.
121 bool isLocalhost() const;
123 /** Test whether content is an IPv6 Site-Local address.
124 \retval true if address begins with fd00::/8.
125 \retval false if --disable-ipv6 has been compiled.
126 \retval false if address does not match fd00::/8
128 bool isSiteLocal6() const;
130 /** Test whether content is an IPv6 address with SLAAC EUI-64 embedded.
131 \retval true if address matches ::ff:fe00:0
132 \retval false if --disable-ipv6 has been compiled.
133 \retval false if address does not match ::ff:fe00:0
135 bool isSiteLocalAuto() const;
139 /** Retrieve the Port if stored.
140 \retval 0 Port is unset or an error occurred.
141 \retval n Port associated with this address in host native -endian.
143 unsigned short port() const;
145 /** Set the Port value for an address.
146 * Replaces any previously existing Port value.
147 \param port Port being assigned in host native -endian.
148 \retval 0 Port is unset or an error occurred.
149 \retval n Port associated with this address in host native -endian.
151 unsigned short port(unsigned short port
);
153 /// Set object to contain the specific IP case ANY_ADDR (format-neutral).
154 /// see isAnyAddr() for more detail.
157 /// Set object to contain the specific IP case NO_ADDR (format-neutral).
158 /// see isNoAddr() for more detail.
161 /// Set object to contain the specific IP case LOCALHOST (format-neutral).
162 /// see isLocalhost() for more detail.
165 /// Fast reset of the stored content to what would be after default constructor.
168 /** Require an IPv4-only address for this usage.
169 * Converts the object to prefer only IPv4 output.
170 \retval true Content can be IPv4
171 \retval false Content CANNOT be IPv4
176 * Valid results IF and only IF the stored IP address is actually a network bitmask
177 \retval N number of bits which are set in the bitmask stored.
181 /** Apply a mask to the stored address.
182 \param mask Netmask format to be bit-mask-AND'd over the stored address.
184 int applyMask(const Address
&mask
);
186 /** Apply a mask to the stored address.
187 * CIDR will be converted appropriate to map the stored content.
188 \param cidr CIDR Mask being applied. As an integer in host format.
189 \param mtype Type of CIDR mask being applied (AF_INET or AF_INET6)
191 bool applyMask(const unsigned int cidr
, int mtype
);
193 /// Apply so-called 'privacy masking' to IPv4 addresses,
194 /// except localhost IP.
195 /// IPv6 clients use 'privacy addressing' instead.
196 void applyClientMask(const Address
&mask
);
198 /** Return the ASCII equivalent of the address
199 * Semantically equivalent to the IPv4 inet_ntoa()
200 * eg. 127.0.0.1 (IPv4) or ::1 (IPv6)
201 * But for memory safety it requires a buffer as input
202 * instead of producing one magically.
203 * If buffer is not large enough the data is truncated silently.
204 \param buf Allocated buffer to write address to
205 \param len byte length of buffer available for writing.
206 \param force (optional) require the IPA in a specific format.
207 \return pointer to buffer received.
209 char* toStr(char *buf
, const unsigned int blen
, int force
= AF_UNSPEC
) const;
211 /** Return the ASCII equivalent of the address:port combination
212 * Provides a URL formatted version of the content.
213 * If buffer is not large enough the data is truncated silently.
214 * eg. 127.0.0.1:80 (IPv4) or [::1]:80 (IPv6)
215 \param buf Allocated buffer to write address:port to
216 \param len byte length of buffer available for writing.
217 \return pointer to buffer received.
219 char* toUrl(char *buf
, unsigned int len
) const;
221 /** Return a properly hostname formatted copy of the address
222 * Provides a URL formatted version of the content.
223 * If buffer is not large enough the data is truncated silently.
224 * eg. 127.0.0.1 (IPv4) or [::1] (IPv6)
225 \param buf Allocated buffer to write address to
226 \param len byte length of buffer available for writing.
227 \return amount of buffer filled.
229 unsigned int toHostStr(char *buf
, const unsigned int len
) const;
231 /// Empties the address and then slowly imports the IP from a possibly
232 /// [bracketed] portless host. For the semi-reverse operation, see
233 /// toHostStr() which does export the port.
234 /// \returns whether the conversion was successful
235 bool fromHost(const char *hostWithoutPort
);
238 * Convert the content into a Reverse-DNS string.
239 * The buffer sent MUST be allocated large enough to hold the resulting string.
240 * Name truncation will occur if buf does not have enough space.
241 * The constant MAX_IPSTRLEN is defined to provide for sizing arrays correctly.
242 \param show_type may be one of: AF_INET, AF_INET6 for the format of rDNS string wanted.
243 * AF_UNSPEC the default displays the IP in its most advanced native form.
244 \param buf buffer to receive the text string output.
246 bool getReverseString(char buf
[MAX_IPSTRLEN
], int show_type
= AF_UNSPEC
) const;
248 /** Test how two IP relate to each other.
249 \retval 0 IP are equal
250 \retval 1 IP rhs is greater (numerically) than that stored.
251 \retval -1 IP rhs is less (numerically) than that stored.
253 int matchIPAddr(const Address
&rhs
) const;
255 /** Compare taking IP, port, protocol, etc. into account. Returns an
256 integer less than, equal to, or greater than zero if the object
257 is found, respectively, to be less than, to match, or to be greater
258 than rhs. The exact ordering algorithm is not specified and may change.
260 int compareWhole(const Ip::Address
&rhs
) const;
263 * Get RFC 3493 addrinfo structure from the Ip::Address data
264 * for protocol-neutral socket operations.
265 * Should be passed a NULL pointer of type struct addrinfo* it will
266 * allocate memory for the structures involved. (see FreeAddr() to clear).
267 * Defaults to a TCP streaming socket, if other values (such as UDP) are needed
268 * the caller MUST override these default settings.
269 * Some situations may also require an actual call to the system getaddrinfo()
270 * to pull relevant OS details for the socket.
272 * Ip::Address allocated objects MUST be destructed by Ip::Address::FreeAddr
273 * System getaddrinfo() allocated objects MUST be freed with system freeaddrinfo()
275 \param ai structure to be filled out.
276 \param force a specific sockaddr type is needed. default: don't care.
278 void getAddrInfo(struct addrinfo
*&ai
, int force
= AF_UNSPEC
) const;
281 * Equivalent to the sysem call freeaddrinfo() but for Ip::Address allocated data
283 static void FreeAddr(struct addrinfo
*&ai
);
286 * Initializes an empty addrinfo properly for use.
287 * It is intended for use in cases such as getsockopt() where the addrinfo is
288 * about to be changed and the stored details may not match the new ones coming.
289 \param ai addrinfo struct to be initialized as AF_UNSPEC with large address buffer
291 static void InitAddr(struct addrinfo
*&ai
);
294 * Lookup a Host by Name. Equivalent to system call gethostbyname(char*)
295 \param s The textual FQDN of the host being located.
296 \retval true lookup was successful and an IPA was located.
297 \retval false lookup failed or FQDN has no IP associated.
299 bool GetHostByName(const char *s
);
302 /* FIXME: When C => C++ conversion is done will be fully private.
303 * Legacy Transition Methods.
304 * These are here solely to simplify the transition
305 * when moving from converted code to unconverted
306 * these functions can be used to convert this object
307 * and pull out the data needed by the unconverted code
308 * they are intentionaly hard to use, use getAddrInfo() instead.
309 * these functions WILL NOT be in the final public API after transition.
312 void getSockAddr(struct sockaddr_storage
&addr
, const int family
) const;
313 void getSockAddr(struct sockaddr_in
&) const;
314 bool getInAddr(struct in_addr
&) const; /* false if could not convert IPv6 down to IPv4 */
315 void getSockAddr(struct sockaddr_in6
&) const;
316 void getInAddr(struct in6_addr
&) const;
319 /* Conversion for dual-type internals */
321 bool getReverseString4(char buf
[MAX_IPSTRLEN
], const struct in_addr
&dat
) const;
323 bool getReverseString6(char buf
[MAX_IPSTRLEN
], const struct in6_addr
&dat
) const;
325 void map4to6(const struct in_addr
&src
, struct in6_addr
&dest
) const;
327 void map6to4(const struct in6_addr
&src
, struct in_addr
&dest
) const;
329 // Worker behind GetHostName and char* converters
330 bool lookupHostIP(const char *s
, bool nodns
);
333 struct sockaddr_in6 mSocketAddr_
;
336 /* Internally used constants */
337 static const unsigned int STRLEN_IP4A
= 16; // aaa.bbb.ccc.ddd\0
338 static const unsigned int STRLEN_IP4R
= 28; // ddd.ccc.bbb.aaa.in-addr.arpa.\0
339 static const unsigned int STRLEN_IP4S
= 21; // ddd.ccc.bbb.aaa:ppppp\0
340 static const unsigned int MAX_IP4_STRLEN
= STRLEN_IP4R
;
341 static const unsigned int STRLEN_IP6A
= 42; // [ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff]/0
342 static const unsigned int STRLEN_IP6R
= 75; // f.f.f.f f.f.f.f f.f.f.f f.f.f.f f.f.f.f f.f.f.f f.f.f.f f.f.f.f ipv6.arpa./0
343 static const unsigned int STRLEN_IP6S
= 48; // [ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff]:00000/0
344 static const unsigned int MAX_IP6_STRLEN
= STRLEN_IP6R
;
345 static const struct in6_addr v4_localhost
;
346 static const struct in6_addr v4_anyaddr
;
347 static const struct in6_addr v4_noaddr
;
348 static const struct in6_addr v6_noaddr
;
351 inline std::ostream
&
352 operator << (std::ostream
&os
, const Address
&ipa
)
354 char buf
[MAX_IPSTRLEN
];
355 os
<< ipa
.toUrl(buf
,MAX_IPSTRLEN
);
359 // WAS _sockaddr_in_list in an earlier incarnation
363 Address_list() { next
= NULL
; };
364 ~Address_list() { if (next
) delete next
; next
= NULL
; };
372 void parse_IpAddress_list_token(Ip::Address_list
**, char *);
374 #endif /* _SQUID_SRC_IP_ADDRESS_H */