Botan 3.14.1
Crypto and TLS for C&
ipv4_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_IPV4_ADDRESS_H_
8#define BOTAN_IPV4_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
20/**
21* IPv4 Address
22*/
23class BOTAN_PUBLIC_API(3, 12) IPv4Address final {
24 public:
25 /**
26 * Create an address from its integer value
27 * @param ip the address as a 32-bit big-endian integer
28 */
29 explicit IPv4Address(uint32_t ip) : m_ip(ip) {}
30
31 /**
32 * Create an address from its 4 byte big-endian encoding
33 * @param ip the bytes of the address
34 */
35 explicit IPv4Address(std::span<const uint8_t, 4> ip);
36
37 /**
38 * Create an address from its 4 byte big-endian encoding
39 * @param ip the bytes of the address
40 */
41 explicit IPv4Address(std::array<uint8_t, 4> ip) : IPv4Address(std::span<const uint8_t, 4>(ip)) {}
42
43 /**
44 * Convert a dotted-decimal string to an IPv4Address
45 * @param str the address to parse
46 * @return the parsed address, or nullopt if str is not a valid IPv4 address
47 */
48 static std::optional<IPv4Address> 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 > 32.
53 */
54 static IPv4Address netmask(size_t bits);
55
56 /**
57 * Return the netmask matching a single host
58 * @return an address with all 32 bits set
59 */
60 static IPv4Address host_mask() { return netmask(32); }
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 IPv4Address operator&(const IPv4Address& other) const { return IPv4Address(m_ip & other.m_ip); }
68
69 /**
70 * Order two addresses numerically
71 * @return the ordering of this address relative to the other
72 */
73 auto operator<=>(const IPv4Address&) const = default;
74
75 /// The address as a 32-bit big-endian integer
76 BOTAN_DEPRECATED("Use IPv4Address::address") uint32_t value() const { return m_ip; }
77
78 /// The address as a 32-bit big-endian integer
79 uint32_t address() const { return m_ip; }
80
81 /// The address as four bytes, network-byte-order.
82 std::array<uint8_t, 4> to_bytes() const;
83
84 /// Dotted-decimal form, e.g. "10.0.0.1".
85 std::string to_string() const;
86
87 /**
88 * If this value is a netmask consisting of a run of one bits followed by
89 * a run of zero bits, return the number of one bits.
90 *
91 * Otherwise return nullopt.
92 */
93 std::optional<size_t> prefix_length() const;
94
95 private:
96 uint32_t m_ip;
97};
98
99/**
100* An IPv4 subnet in CIDR form: a network address paired with a prefix length
101*/
102class BOTAN_PUBLIC_API(3, 12) IPv4Subnet final {
103 public:
104 /**
105 * Construct from a network address and a prefix length in [0, 32].
106 * Host bits of @p address are cleared.
107 *
108 * Throws Invalid_Argument if @p prefix_length > 32.
109 */
111
112 /**
113 * Construct from a network address and a netmask (4 bytes each)
114 * Returns nullopt if netmask is not a valid contiguous CIDR prefix.
115 */
116 static std::optional<IPv4Subnet> from_address_and_mask(std::span<const uint8_t, 8> addr_and_mask);
117
118 /**
119 * Construct from a network address and a netmask (4 bytes each)
120 * Returns nullopt if netmask is not a valid contiguous CIDR prefix.
121 */
122 static std::optional<IPv4Subnet> from_address_and_mask(uint32_t addr, uint32_t mask);
123
124 /**
125 * Parse CIDR-style form "10.0.0.0/8".
126 *
127 * The "/N" suffix is required: bare addresses should be parsed via
128 * IPv4Address::from_string and wrapped with IPv4Subnet::host if needed.
129 * The input must already be canonical, such that from_string and
130 * to_string are exact inverses: the prefix length is canonical decimal
131 * ("/8", not "/08") and the host bits are clear ("10.0.0.0/8", not
132 * "10.1.2.3/8").
133 *
134 * Returns nullopt on parse failure or out-of-range prefix length.
135 */
136 static std::optional<IPv4Subnet> from_string(std::string_view str);
137
138 /**
139 * A single-host subnet (prefix length 32) covering exactly @p address.
140 */
142
143 /// The network address (host bits already zeroed).
144 const IPv4Address& address() const { return m_address; }
145
146 /// Prefix length in [0, 32].
147 size_t prefix_length() const { return m_prefix_length; }
148
149 /// True iff prefix_length() == 32.
150 bool is_host() const { return m_prefix_length == 32; }
151
152 /// True iff @p ip falls within this subnet.
153 bool contains(const IPv4Address& ip) const;
154
155 /// The last address in this subnet (all host bits set)
156 IPv4Address last_address() const;
157
158 /// CIDR-style "10.0.0.0/8".
159 std::string to_string() const;
160
161 /**
162 * Bytes for use in a DER-encoded GeneralName iPAddress field.
163 *
164 * If this is an address (is_host returns true) the output is 4 bytes (the address in network order)
165 * Otherwise it is a subnet and the output is 8 bytes (address || netmask)
166 */
167 std::vector<uint8_t> serialize() const;
168
169 friend bool operator==(const IPv4Subnet&, const IPv4Subnet&) = default;
170
171 private:
172 IPv4Address m_address;
173 uint8_t m_prefix_length;
174};
175
176} // namespace Botan
177
178#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
IPv4Address operator&(const IPv4Address &other) const
auto operator<=>(const IPv4Address &) const =default
IPv4Address(std::array< uint8_t, 4 > ip)
uint32_t address() const
The address as a 32-bit big-endian integer.
uint32_t value() const
The address as a 32-bit big-endian integer.
static IPv4Address host_mask()
IPv4Address(uint32_t ip)
static IPv4Address netmask(size_t bits)
static std::optional< IPv4Subnet > from_address_and_mask(std::span< const uint8_t, 8 > addr_and_mask)
bool is_host() const
True iff prefix_length() == 32.
friend bool operator==(const IPv4Subnet &, const IPv4Subnet &)=default
IPv4Subnet(IPv4Address address, size_t prefix_length)
size_t prefix_length() const
Prefix length in [0, 32].
static IPv4Subnet host(IPv4Address address)
static std::optional< IPv4Subnet > from_string(std::string_view str)
const IPv4Address & address() const
The network address (host bits already zeroed).
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition exceptn.cpp:13