src/ip/Address.h

   1 /*
   2  * Copyright (C) 1996-2020 The Squid Software Foundation and contributors
   3  *
   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.
   7  */
   8
   9 /* DEBUG: section 14    IP Storage and Handling */
  10
  11 #ifndef _SQUID_SRC_IP_ADDRESS_H
  12 #define _SQUID_SRC_IP_ADDRESS_H
  13
  14 #include "ip/forward.h"
  15
  16 #include <iosfwd>
  17 #include <ostream>
  18 #if HAVE_SYS_SOCKET_H
  19 #include <sys/socket.h>
  20 #endif
  21 #if HAVE_NETINET_IN_H
  22 #include <netinet/in.h>
  23 #endif
  24 #if HAVE_NETINET_IP_H
  25 #include <netinet/ip.h>
  26 #endif
  27 #if HAVE_WS2TCPIP_H
  28 #include <ws2tcpip.h>
  29 #endif
  30 #if HAVE_NETDB_H
  31 #include <netdb.h>
  32 #endif
  33
  34 namespace Ip
  35 {
  36
  37 /**
  38  * Holds and manipulates IPv4, IPv6, and Socket Addresses.
  39  */
  40 class Address
  41 {
  42
  43 public:
  44     /** @name Constructors and Destructor */
  45     /*@{*/
  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 &);
  53     Address(const char*);
  54     ~Address() {}
  55     /*@}*/
  56
  57     /** @name Assignment Operators */
  58     /*@{*/
  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);
  67     /*@}*/
  68
  69     /** @name Boolean Operators */
  70     /*@{*/
  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;
  77
  78 public:
  79     /* methods */
  80
  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.
  84      */
  85     bool isIPv4() const;
  86
  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.
  90      */
  91     bool isIPv6() const;
  92
  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)
  97      */
  98     bool isSockAddr() const;
  99
 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
 103      \retval true IPv6 ::
 104      \retval false anything else.
 105      */
 106     bool isAnyAddr() const;
 107
 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.
 112      */
 113     bool isNoAddr() const;
 114
 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.
 120      */
 121     bool isLocalhost() const;
 122
 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
 127      */
 128     bool isSiteLocal6() const;
 129
 130     /** Test whether content is an IPv6 address with SLAAC EUI-64 embeded.
 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
 134      */
 135     bool isSiteLocalAuto() const;
 136
 137     /*@}*/
 138
 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.
 142      */
 143     unsigned short port() const;
 144
 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.
 150      */
 151     unsigned short port(unsigned short port);
 152
 153     /// Set object to contain the specific IP case ANY_ADDR (format-neutral).
 154     /// see isAnyAddr() for more detail.
 155     void setAnyAddr();
 156
 157     /// Set object to contain the specific IP case NO_ADDR (format-neutral).
 158     /// see isNoAddr() for more detail.
 159     void setNoAddr();
 160
 161     /// Set object to contain the specific IP case LOCALHOST (format-neutral).
 162     /// see isLocalhost() for more detail.
 163     void setLocalhost();
 164
 165     /// Fast reset of the stored content to what would be after default constructor.
 166     void setEmpty();
 167
 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
 172      */
 173     bool setIPv4();
 174
 175     /**
 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.
 178      */
 179     int cidr() const;
 180
 181     /** Apply a mask to the stored address.
 182      \param mask Netmask format to be bit-mask-AND'd over the stored address.
 183      */
 184     int applyMask(const Address &mask);
 185
 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)
 190      */
 191     bool applyMask(const unsigned int cidr, int mtype);
 192
 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);
 197
 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.
 208      */
 209     char* toStr(char *buf, const unsigned int blen, int force = AF_UNSPEC) const;
 210
 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.
 218      */
 219     char* toUrl(char *buf, unsigned int len) const;
 220
 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.
 228      */
 229     unsigned int toHostStr(char *buf, const unsigned int len) const;
 230
 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);
 236
 237     /**
 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.
 245      */
 246     bool getReverseString(char buf[MAX_IPSTRLEN], int show_type = AF_UNSPEC) const;
 247
 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.
 252      */
 253     int matchIPAddr(const Address &rhs) const;
 254
 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.
 259     */
 260     int compareWhole(const Ip::Address &rhs) const;
 261
 262     /**
 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.
 271      \par
 272      *  Ip::Address allocated objects MUST be destructed by Ip::Address::FreeAddr
 273      *  System getaddrinfo() allocated objects MUST be freed with system freeaddrinfo()
 274      *
 275      \param ai structure to be filled out.
 276      \param force a specific sockaddr type is needed. default: don't care.
 277      */
 278     void getAddrInfo(struct addrinfo *&ai, int force = AF_UNSPEC) const;
 279
 280     /**
 281      *  Equivalent to the sysem call freeaddrinfo() but for Ip::Address allocated data
 282      */
 283     static void FreeAddr(struct addrinfo *&ai);
 284
 285     /**
 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
 290      */
 291     static void InitAddr(struct addrinfo *&ai);
 292
 293     /**
 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.
 298      */
 299     bool GetHostByName(const char *s);
 300
 301 public:
 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 functiosn WILL NOT be in the final public API after transition.
 310      */
 311
 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;
 317
 318 private:
 319     /* Conversion for dual-type internals */
 320
 321     bool getReverseString4(char buf[MAX_IPSTRLEN], const struct in_addr &dat) const;
 322
 323     bool getReverseString6(char buf[MAX_IPSTRLEN], const struct in6_addr &dat) const;
 324
 325     void map4to6(const struct in_addr &src, struct in6_addr &dest) const;
 326
 327     void map6to4(const struct in6_addr &src, struct in_addr &dest) const;
 328
 329     // Worker behind GetHostName and char* converters
 330     bool lookupHostIP(const char *s, bool nodns);
 331
 332     /* variables */
 333     struct sockaddr_in6 mSocketAddr_;
 334
 335 private:
 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;
 349 };
 350
 351 inline std::ostream &
 352 operator << (std::ostream &os, const Address &ipa)
 353 {
 354     char buf[MAX_IPSTRLEN];
 355     os << ipa.toUrl(buf,MAX_IPSTRLEN);
 356     return os;
 357 }
 358
 359 // WAS _sockaddr_in_list in an earlier incarnation
 360 class Address_list
 361 {
 362 public:
 363     Address_list() { next = NULL; };
 364     ~Address_list() { if (next) delete next; next = NULL; };
 365
 366     Address s;
 367     Address_list *next;
 368 };
 369
 370 } // namespace Ip
 371
 372 void parse_IpAddress_list_token(Ip::Address_list **, char *);
 373
 374 #endif /* _SQUID_SRC_IP_ADDRESS_H */
 375