Botan::IPv6Address Class Reference

#include <ipv6_address.h>

Public Member Functions
std::array< uint8_t, 16 >	address () const
std::optional< IPv4Address >	as_ipv4 () const
	IPv6Address (std::array< uint8_t, 16 > ip)
	IPv6Address (std::span< const uint8_t, 16 > ip)
IPv6Address	operator& (const IPv6Address &other) const
auto	operator<=> (const IPv6Address &) const =default
std::optional< size_t >	prefix_length () const
std::string	to_string () const

Static Public Member Functions
static std::optional< IPv6Address >	from_string (std::string_view str)
static IPv6Address	host_mask ()
static IPv6Address	netmask (size_t bits)

Detailed Description

IPv6 Address

Definition at line 25 of file ipv6_address.h.

Constructor & Destructor Documentation

IPv6Address() [1/2]

Botan::IPv6Address::IPv6Address ( std::span< const uint8_t, 16 > ip )

explicit

Create an address from its 16 byte big-endian encoding

Parameters

ip	the bytes of the address

Definition at line 17 of file ipv6_address.cpp.

                                                      : m_ip{} {
   for(size_t i = 0; i != 16; ++i) {
      m_ip[i] = ip[i];
   }
}

Referenced by host_mask(), netmask(), operator&(), and operator<=>().

IPv6Address() [2/2]

Botan::IPv6Address::IPv6Address ( std::array< uint8_t, 16 > ip )

inlineexplicit

Create an address from its 16 byte big-endian encoding

Parameters

ip	the bytes of the address

Definition at line 37 of file ipv6_address.h.

: m_ip(ip) {}

Member Function Documentation

address()

std::array< uint8_t, 16 > Botan::IPv6Address::address ( ) const

inline

Access the raw bytes of the address

Returns

the 16 byte big-endian encoding of the address

Definition at line 79 of file ipv6_address.h.

{ return m_ip; }

Referenced by Botan::IPv6Subnet::serialize().

as_ipv4()

std::optional< IPv4Address > Botan::IPv6Address::as_ipv4

(

)

const

If this IPv6 address is an IPv4-compatible IPv6 address (RFC 4291 2.5.5.1) or an IPv4-mapped IPv6 address (RFC 4291 2.5.5.2), return the embedded IPv4 address.

Definition at line 283 of file ipv6_address.cpp.

                                                    {
   const uint32_t ip0 = load_be<uint32_t>(m_ip.data(), 0);
   const uint32_t ip1 = load_be<uint32_t>(m_ip.data(), 1);
   const uint32_t ip2 = load_be<uint32_t>(m_ip.data(), 2);
   const uint32_t ip3 = load_be<uint32_t>(m_ip.data(), 3);
 
   if(ip0 == 0x00000000 && ip1 == 0x00000000 && (ip2 == 0x00000000 || ip2 == 0x0000FFFF)) {
      return IPv4Address(ip3);
   } else {
      return {};
   }
}

References as_ipv4(), and Botan::load_be().

Referenced by as_ipv4().

from_string()

std::optional< IPv6Address > Botan::IPv6Address::from_string ( std::string_view str )

static

Convert a string representation of an IPv6 address to IPv6Address.

Accepts the full form (eight colon-separated hex groups), the "::"-compressed form (exactly one run of zero groups elided), and combinations such as "2001:db8::1". The final 32 bits may be given in IPv4 dotted-decimal form (e.g. "::ffff:192.0.2.1"). Surrounding brackets and zone identifiers are not accepted.

Definition at line 24 of file ipv6_address.cpp.

                                                                    {
   if(str.empty()) {
      return {};
   }
 
   // Parsed hex groups, split by whether they appeared before or after a "::".
   // If no "::" appears, only `pre` is populated and must reach exactly 8 groups.
   std::array<uint16_t, 8> pre{};
   std::array<uint16_t, 8> post{};
   size_t pre_count = 0;
   size_t post_count = 0;
   bool seen_double_colon = false;
 
   auto hex_value = [](char c) -> std::optional<uint8_t> {
      if(c >= '0' && c <= '9') {
         return c - '0';
      } else if(c >= 'a' && c <= 'f') {
         return 10 + (c - 'a');
      } else if(c >= 'A' && c <= 'F') {
         return 10 + (c - 'A');
      } else {
         return {};
      }
   };
 
   size_t idx = 0;
   bool expect_group = true;  // set after any separator, cleared after a group
 
   while(idx < str.size()) {
      if(str[idx] == ':') {
         if(idx + 1 < str.size() && str[idx + 1] == ':') {
            if(seen_double_colon) {
               return {};  // at most one "::"
            }
            seen_double_colon = true;
            idx += 2;
            expect_group = (idx < str.size());
            continue;
         }
         // single ':' separator between groups, only valid after a group
         if(expect_group) {
            return {};
         }
         expect_group = true;
         idx += 1;
         continue;
      }
 
      // Parse a hex group of 1..4 digits
      const size_t group_start = idx;
      uint32_t group = 0;
      size_t hex_chars = 0;
      while(idx < str.size() && hex_chars < 4) {
         const auto digit = hex_value(str[idx]);
         if(digit.has_value() == false) {
            break;
         }
         group = (group << 4) | static_cast<uint32_t>(digit.value());
         idx += 1;
         hex_chars += 1;
      }
      if(hex_chars == 0) {
         return {};
      }
      // If a 5th hex digit follows, the group is oversized.
      if(hex_chars == 4 && idx < str.size() && hex_value(str[idx]).has_value()) {
         return {};
      }
 
      /*
      RFC 4291 2.2 allows the final 32 bits in dotted decimal, eg
      "::ffff:1.2.3.4". The dotted quad must consume the remainder of the
      input, and accounts for two 16-bit groups.
      */
      if(idx < str.size() && str[idx] == '.') {
         const auto ipv4 = IPv4Address::from_string(str.substr(group_start));
         if(!ipv4.has_value()) {
            return {};
         }
         const uint32_t v4 = ipv4->address();
         const std::array<uint16_t, 2> v4_groups{static_cast<uint16_t>(v4 >> 16), static_cast<uint16_t>(v4 & 0xFFFF)};
         for(const auto g : v4_groups) {
            if(seen_double_colon) {
               if(post_count >= 8) {
                  return {};
               }
               post[post_count++] = g;
            } else {
               if(pre_count >= 8) {
                  return {};
               }
               pre[pre_count++] = g;
            }
         }
         idx = str.size();
         expect_group = false;
         continue;
      }
 
      if(seen_double_colon) {
         if(post_count >= 8) {
            return {};
         }
         post[post_count++] = static_cast<uint16_t>(group);
      } else {
         if(pre_count >= 8) {
            return {};
         }
         pre[pre_count++] = static_cast<uint16_t>(group);
      }
      expect_group = false;
   }
 
   // Trailing single ':' is invalid
   if(expect_group) {
      return {};
   }
 
   const size_t total_groups = pre_count + post_count;
   if(seen_double_colon) {
      // "::" has to cover at least one zero group
      if(total_groups > 7) {
         return {};
      }
   } else {
      if(total_groups != 8) {
         return {};
      }
   }
 
   std::array<uint8_t, 16> out{};
   for(size_t i = 0; i != pre_count; ++i) {
      out[2 * i] = get_byte<0>(pre[i]);
      out[2 * i + 1] = get_byte<1>(pre[i]);
   }
   const size_t gap = 8 - total_groups;
   for(size_t i = 0; i != post_count; ++i) {
      const size_t target = pre_count + gap + i;
      out[2 * target] = get_byte<0>(post[i]);
      out[2 * target + 1] = get_byte<1>(post[i]);
   }
   return IPv6Address(out);
}

Referenced by Botan::IPv6Subnet::from_string(), Botan::URI::Authority::from_string(), Botan::TLS::Server_Name_Indicator::hostname_acceptable_for_sni(), and Botan::X509_Certificate::matches_dns_name().

host_mask()

IPv6Address Botan::IPv6Address::host_mask ( )

inlinestatic

Return the netmask matching a single host

Returns

an address with all 128 bits set

Definition at line 60 of file ipv6_address.h.

{ return netmask(128); }

References IPv6Address(), and netmask().

netmask()

IPv6Address Botan::IPv6Address::netmask ( size_t bits )

static

Return an address with the leading bits set to one and the remainder zero. Throws Invalid_Argument if bits > 128.

Definition at line 169 of file ipv6_address.cpp.

                                            {
   BOTAN_ARG_CHECK(bits <= 128, "IPv6 netmask prefix length must be at most 128");
 
   const size_t full_bytes = bits / 8;
   const size_t leftover = bits % 8;
 
   std::array<uint8_t, 16> m{};
   for(size_t i = 0; i != full_bytes; ++i) {
      m[i] = 0xFF;
   }
 
   if(leftover > 0) {
      m[full_bytes] = static_cast<uint8_t>(0xFF << (8 - leftover));
   }
 
   return IPv6Address(m);
}

References BOTAN_ARG_CHECK, IPv6Address(), and netmask().

Referenced by Botan::IPv6Subnet::contains(), Botan::GeneralName::encode_into(), host_mask(), netmask(), prefix_length(), and Botan::IPv6Subnet::serialize().

operator&()

IPv6Address Botan::IPv6Address::operator&

(

const IPv6Address &

other

)

const

Bitwise AND of two addresses, typically used to apply a netmask

Parameters

other

the address to AND with

Returns

the bitwise AND of the two addresses

Definition at line 257 of file ipv6_address.cpp.

                                                                 {
   std::array<uint8_t, 16> masked{};
   for(size_t i = 0; i != 16; ++i) {
      masked[i] = m_ip[i] & other.m_ip[i];
   }
   return IPv6Address(masked);
}

References IPv6Address(), and operator&().

Referenced by operator&().

operator<=>()

auto Botan::IPv6Address::operator<=> ( const IPv6Address & ) const

default

Order two addresses numerically

Returns

the ordering of this address relative to the other

References IPv6Address().

prefix_length()

std::optional< size_t > Botan::IPv6Address::prefix_length

(

)

const

If this value is a netmask consisting of a run of one bits followed by a run of zero bits, return the number of one bits.

Otherwise return nullopt.

Definition at line 265 of file ipv6_address.cpp.

                                                     {
   // Count leading one bits, stopping at the first byte that isn't fully set.
   size_t leading = 0;
   for(size_t i = 0; i != 16; ++i) {
      const size_t hw = (m_ip[i] == 0xFF) ? 8 : std::countl_one(m_ip[i]);
      leading += hw;
      if(hw != 8) {
         break;
      }
   }
 
   // Verify this is exactly equal to a netmask of that size
   if(*this != netmask(leading)) {
      return std::nullopt;
   }
   return leading;
}

References netmask(), and prefix_length().

Referenced by prefix_length().

to_string()

std::string Botan::IPv6Address::to_string

(

)

const

Convert an IPv6 address to the RFC 5952 canonical text form: lowercase hex, leading zeros within a group suppressed, and the longest run of two or more zero groups compressed to "::". The mixed hex/dotted notation is never produced, even for IPv4-mapped addresses.

Definition at line 187 of file ipv6_address.cpp.

                                       {
   static const char* hex = "0123456789abcdef";
 
   std::array<uint16_t, 8> groups{};
   for(size_t i = 0; i != 8; ++i) {
      groups[i] = make_uint16(m_ip[2 * i], m_ip[2 * i + 1]);
   }
 
   /*
   Find the run of zero groups to elide with "::", per RFC 5952 4.2:
   "The use of the symbol '::' MUST be used to its maximum capability",
   "The symbol '::' MUST NOT be used to shorten just one 16-bit 0 field",
   and on ties "the first sequence of zero bits MUST be shortened".
   */
   size_t best_start = 0;
   size_t best_len = 0;
   size_t run_len = 0;
   for(size_t i = 0; i != 8; ++i) {
      if(groups[i] == 0) {
         run_len += 1;
         if(run_len > best_len) {
            best_len = run_len;
            best_start = i + 1 - run_len;
         }
      } else {
         run_len = 0;
      }
   }
 
   std::string out;
   out.reserve(39);
 
   auto append_group = [&](uint16_t group) {
      bool started = false;
      // Write each nibble omitting leading 0s
      for(int s = 12; s >= 0; s -= 4) {
         const auto nibble = (group >> s) & 0xF;
         if(nibble != 0 || started || s == 0) {
            out.push_back(hex[nibble]);
            started = true;
         }
      }
   };
 
   if(best_len < 2) {
      // No run of two or more zero groups; write the full form
      for(size_t i = 0; i != 8; ++i) {
         if(i > 0) {
            out.push_back(':');
         }
         append_group(groups[i]);
      }
   } else {
      for(size_t i = 0; i != best_start; ++i) {
         if(i > 0) {
            out.push_back(':');
         }
         append_group(groups[i]);
      }
      out += "::";
      for(size_t i = best_start + best_len; i != 8; ++i) {
         if(i > best_start + best_len) {
            out.push_back(':');
         }
         append_group(groups[i]);
      }
   }
   return out;
}

References Botan::make_uint16(), and to_string().

Referenced by to_string().

---

The documentation for this class was generated from the following files:

• src/lib/utils/ip_address/ipv6_address.h
• src/lib/utils/ip_address/ipv6_address.cpp