Botan 3.14.1
Crypto and TLS for C&
ipv6_address.h
Go to the documentation of this file.
1/*
2* (C) 2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_IPV6_ADDRESS_H_
8#define BOTAN_IPV6_ADDRESS_H_
9
10#include <botan/types.h>
11#include <array>
12#include <optional>
13#include <span>
14#include <string>
15#include <string_view>
16#include <vector>
17
18namespace Botan {
19
20class IPv4Address;
21
22/**
23* IPv6 Address
24*/
25class BOTAN_PUBLIC_API(3, 12) IPv6Address final {
26 public:
27 /**
28 * Create an address from its 16 byte big-endian encoding
29 * @param ip the bytes of the address
30 */
31 explicit IPv6Address(std::span<const uint8_t, 16> ip);
32
33 /**
34 * Create an address from its 16 byte big-endian encoding
35 * @param ip the bytes of the address
36 */
37 explicit IPv6Address(std::array<uint8_t, 16> ip) : m_ip(ip) {}
38
39 /**
40 * Convert a string representation of an IPv6 address to IPv6Address.
41 *
42 * Accepts the full form (eight colon-separated hex groups), the
43 * "::"-compressed form (exactly one run of zero groups elided), and
44 * combinations such as "2001:db8::1". The final 32 bits may be given
45 * in IPv4 dotted-decimal form (e.g. "::ffff:192.0.2.1"). Surrounding
46 * brackets and zone identifiers are not accepted.
47 */
48 static std::optional<IPv6Address> from_string(std::string_view str);
49
50 /**
51 * Return an address with the leading @p bits set to one and the remainder
52 * zero. Throws Invalid_Argument if @p bits > 128.
53 */
54 static IPv6Address netmask(size_t bits);
55
56 /**
57 * Return the netmask matching a single host
58 * @return an address with all 128 bits set
59 */
60 static IPv6Address host_mask() { return netmask(128); }
61
62 /**
63 * Bitwise AND of two addresses, typically used to apply a netmask
64 * @param other the address to AND with
65 * @return the bitwise AND of the two addresses
66 */
67 IPv6Address operator&(const IPv6Address& other) const;
68
69 /**
70 * Order two addresses numerically
71 * @return the ordering of this address relative to the other
72 */
73 auto operator<=>(const IPv6Address&) const = default;
74
75 /**
76 * Access the raw bytes of the address
77 * @return the 16 byte big-endian encoding of the address
78 */
79 std::array<uint8_t, 16> address() const { return m_ip; }
80
81 /// The address as sixteen bytes, network-byte-order.
82 std::array<uint8_t, 16> to_bytes() const { return m_ip; }
83
84 /**
85 * Convert an IPv6 address to the RFC 5952 canonical text form:
86 * lowercase hex, leading zeros within a group suppressed, and the
87 * longest run of two or more zero groups compressed to "::". The
88 * mixed hex/dotted notation is never produced, even for IPv4-mapped
89 * addresses.
90 */
91 std::string to_string() const;
92
93 /**
94 * If this value is a netmask consisting of a run of one bits followed by
95 * a run of zero bits, return the number of one bits.
96 *
97 * Otherwise return nullopt.
98 */
99 std::optional<size_t> prefix_length() const;
100
101 /**
102 * If this IPv6 address is an IPv4-compatible IPv6 address (RFC 4291 2.5.5.1)
103 * or an IPv4-mapped IPv6 address (RFC 4291 2.5.5.2), return the embedded
104 * IPv4 address.
105 */
106 std::optional<IPv4Address> as_ipv4() const;
107
108 private:
109 std::array<uint8_t, 16> m_ip;
110};
111
112/**
113* An IPv6 subnet in CIDR form: a network address paired with a prefix length
114*/
115class BOTAN_PUBLIC_API(3, 12) IPv6Subnet final {
116 public:
117 /**
118 * Construct from a network address and a prefix length in [0, 128].
119 * Host bits of @p address are cleared.
120 *
121 * Throws Invalid_Argument if @p prefix_length > 128.
122 */
124
125 /**
126 * Construct from a network address and a 16-byte CIDR netmask.
127 * Returns nullopt if netmask is not a valid contiguous CIDR prefix.
128 */
129 static std::optional<IPv6Subnet> from_address_and_mask(std::span<const uint8_t, 32> addr_and_mask);
130
131 /**
132 * Parse the CIDR-style form "2001:db8::/32".
133 *
134 * The "/N" suffix is required: bare addresses should be parsed via
135 * IPv6Address::from_string and wrapped with IPv6Subnet::host if needed.
136 * The input must already be canonical, such that from_string and
137 * to_string are exact inverses: the address is RFC 5952 form with host
138 * bits clear ("2001:db8::/32") and the prefix length is canonical
139 * decimal ("/32", not "/032"). In particular the IPv4-mapped dotted form
140 * ("::ffff:1.2.3.4/120") is rejected even though IPv6Address::from_string
141 * would accept the address.
142 *
143 * Returns nullopt on parse failure or out-of-range prefix length.
144 */
145 static std::optional<IPv6Subnet> from_string(std::string_view str);
146
147 /**
148 * A single-host subnet (prefix length 128) covering exactly @p address.
149 */
151
152 /// The network address (host bits already zeroed).
153 const IPv6Address& address() const { return m_address; }
154
155 /// Prefix length in [0, 128].
156 size_t prefix_length() const { return m_prefix_length; }
157
158 /// True iff prefix_length() == 128.
159 bool is_host() const { return m_prefix_length == 128; }
160
161 /// True iff @p ip falls within this subnet.
162 bool contains(const IPv6Address& ip) const;
163
164 /// The last address in this subnet (all host bits set)
165 IPv6Address last_address() const;
166
167 /// CIDR-style "2001:db8::/32".
168 std::string to_string() const;
169
170 /**
171 * Bytes for use in a DER-encoded GeneralName iPAddress field:
172 * - 16 bytes (the address) if is_host(); the SAN form per RFC 5280 4.2.1.6.
173 * - 32 bytes (address || netmask) otherwise; the name constraint form
174 * per RFC 5280 4.2.1.10.
175 */
176 std::vector<uint8_t> serialize() const;
177
178 friend bool operator==(const IPv6Subnet&, const IPv6Subnet&) = default;
179
180 private:
181 IPv6Address m_address;
182 uint8_t m_prefix_length;
183};
184
185} // namespace Botan
186
187#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
std::array< uint8_t, 16 > address() const
static IPv6Address host_mask()
auto operator<=>(const IPv6Address &) const =default
IPv6Address(std::span< const uint8_t, 16 > ip)
std::array< uint8_t, 16 > to_bytes() const
The address as sixteen bytes, network-byte-order.
static IPv6Address netmask(size_t bits)
IPv6Address(std::array< uint8_t, 16 > ip)
friend bool operator==(const IPv6Subnet &, const IPv6Subnet &)=default
size_t prefix_length() const
Prefix length in [0, 128].
static std::optional< IPv6Subnet > from_address_and_mask(std::span< const uint8_t, 32 > addr_and_mask)
const IPv6Address & address() const
The network address (host bits already zeroed).
static std::optional< IPv6Subnet > from_string(std::string_view str)
IPv6Subnet(IPv6Address address, size_t prefix_length)
bool is_host() const
True iff prefix_length() == 128.
static IPv6Subnet host(IPv6Address address)
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition exceptn.cpp:13
ECIES_Flags operator&(ECIES_Flags a, ECIES_Flags b)
Definition ecies.h:70