--- name: "libressl-X509v3_addr_add_inherit" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-X509v3_addr_add_inherit" --- # libressl-X509v3\_addr\_add\_inherit(3) RFC 3779 IP address delegation extensions ## NAME **X509v3\_addr\_add\_inherit**, **X509v3\_addr\_add\_prefix**, **X509v3\_addr\_add\_range**, **X509v3\_addr\_canonize**, **X509v3\_addr\_is\_canonical** – RFC 3779 IP address delegation extensions ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *int*\ **X509v3\_addr\_add\_inherit**(*IPAddrBlocks \*addrblocks*, *const unsigned afi*, *const unsigned \*safi*); *int*\ **X509v3\_addr\_add\_prefix**(*IPAddrBlocks \*addrblocks*, *const unsigned afi*, *const unsigned \*safi*, *unsigned char \*prefix*, *const int prefixlen*); *int*\ **X509v3\_addr\_add\_range**(*IPAddrBlocks \*addrblocks*, *const unsigned afi*, *const unsigned \*safi*, *unsigned char \*min*, *unsigned char \*max*); *int*\ **X509v3\_addr\_canonize**(*IPAddrBlocks \*addrblocks*); *int*\ **X509v3\_addr\_is\_canonical**(*IPAddrBlocks \*addrblocks*); ## DESCRIPTION An *IPAddrBlocks* object represents the content of an IP address delegation extension as defined in RFC 3779, section 2.2.3.1. It holds lists of IP address prefixes and IP address ranges delegated from the issuer to the subject of the certificate. It can be instantiated as explained in the EXAMPLES section and its internals are documented in IPAddressRange\_new(3). Each list in a well-formed *IPAddrBlocks* object is uniquely identified by an address family identifier (AFI) and an optional subsequent address family identifier (SAFI). Lists can be absent or can contain an “inherit” marker to indicate that the resources are to be inherited from the corresponding list of the issuer certificate. Per specification, an AFI is an unsigned 16-bit integer and a SAFI is an unsigned 8-bit integer. For IPv4 and IPv6 there are the predefined constants IANA\_AFI\_IPV4 and IANA\_AFI\_IPV6, which should be the only values used for *afi* in this API. In practice, *safi* is always NULL. *afi* is generally silently truncated to its lowest 16 bits and, if *safi* is non-NULL, only the lowest 8 bits of the value pointed at are used. **X509v3\_addr\_add\_inherit**() adds a list with an “inherit” marker to *addrblocks*. If a list corresponding to *afi* and *safi* already exists, no action occurs if it is marked “inherit”, otherwise the call fails. **X509v3\_addr\_add\_prefix**() adds a newly allocated internal representation of the *prefix* of length *prefixlen* to the list corresponding to *afi* and the optional *safi* in *addrblocks*. If no such list exists, it is created first. If the list exists and is marked “inherit”, the call fails. *prefix* is expected to be a byte array in network byte order. It should point at enough memory to accommodate *prefixlen* bits and it is recommended that all the bits not covered by the *prefixlen* be set to 0. It is the caller's responsibility to ensure that the *prefix* has no address in common with any of the prefixes or ranges already in the list. If *afi* is IANA\_AFI\_IPV4, *prefixlen* should be between 0 and 32 (inclusive) and if *afi* is IANA\_AFI\_IPV6, *prefixlen* should be between 0 and 128 (inclusive). **X509v3\_addr\_add\_range**() is similar to **X509v3\_addr\_add\_prefix**() for the closed interval of IP addresses between *min* and *max* in network presentation. If *afi* is IANA\_AFI\_IPV4, *min* and *max* should point at 4 bytes of memory and if *afi* is IANA\_AFI\_IPV6, *min* and *max* should point at 16 bytes of memory. In case the range of IP addresses between *min* and *max* is a prefix, a prefix will be added instead of a range. It is the caller's responsibility to ensure that *min* is less than or equal to *max* and that it does not contain any address already present in the list. Failure to do so will result in a subsequent failure of **X509v3\_addr\_canonize**(). **X509v3\_addr\_canonize**() attempts to bring the non-NULL *addrblocks* into canonical form. An *IPAddrBlocks* object is said to be in canonical form if it conforms to the ordering specified in RFC 3779: section 2.2.3.3 requires that the list of lists be sorted first by increasing *afi* and then by increasing *safi*, where NULL is the minimal SAFI; section 2.2.3.6 requires that each list be in minimal form and sorted. The minimality requirement is that all adjacent prefixes and ranges must be merged into a single range and that each range must be expressed as a prefix, if possible. In particular, any given address can be in at most one list entry. The order is by increasing minimal IP address in network byte order. **X509v3\_addr\_is\_canonical**() indicates whether *addrblocks* is in canonical form. ## RETURN VALUES All these functions return 1 on success and 0 on failure. Memory allocation failure is one possible reason for all of them. Sometimes an error code can be obtained by ERR\_get\_error(3). **X509v3\_addr\_add\_inherit**() fails if the list corresponding to *afi* and the optional *safi* already exists and is not marked “inherit”. **X509v3\_addr\_add\_prefix**() and **X509v3\_addr\_add\_range**() fail if a list corresponding to *afi* and the optional *safi* already exists and is marked “inherit”, or if *prefixlen* is outside the interval \[0,32\] for IPv4 addresses or \[0,128\] for IPv6 addresses. **X509v3\_addr\_canonize**() fails if one of the lists in *addrblocks* is malformed, in particular if it contains corrupt, overlapping, or duplicate entries. Corruption includes ranges where *max* is strictly smaller than *min*. The error conditions are generally indistinguishable. **X509v3\_addr\_is\_canonical**() returns 1 if *addrblocks* is in canonical form. A return value of 0 can indicate non-canonical form or a corrupted list. ## EXAMPLES Construct the first extension from RFC 3779, Appendix B. ``` #include #include #include #include #include #include #include #include #include const char *prefixes[] = { "10.0.32/20", "10.0.64/24", "10.1/16", "10.2.48/20", "10.2.64/24", "10.3/16", }; #define N_PREFIXES (sizeof(prefixes) / sizeof(prefixes[0])) static void hexdump(const unsigned char *buf, size_t len) { size_t i; for (i = 1; i <= len; i++) printf(" 0x%02x,%s", buf[i - 1], i % 8 ? "" : "\n"); if (len % 8) printf("\n"); } int main(void) { IPAddrBlocks *addrblocks; X509_EXTENSION *ext; unsigned char *der; int der_len; size_t i; if (pledge("stdio", NULL) == -1) err(1, "pledge"); /* * Somebody forgot to implement IPAddrBlocks_new(). IPAddrBlocks * is the same as STACK_OF(IPAddressFamily). As such, it should * have IPAddressFamily_cmp() as its comparison function. It is * not possible to call sk_new(3) because IPAddressFamily_cmp() * is not part of the public API. The correct comparison function * can be installed as a side-effect of X509v3_addr_canonize(3). */ if ((addrblocks = sk_IPAddressFamily_new_null()) == NULL) err(1, "sk_IPAddressFamily_new_null"); if (!X509v3_addr_canonize(addrblocks)) errx(1, "X509v3_addr_canonize"); /* Add the prefixes as IPv4 unicast. */ for (i = 0; i < N_PREFIXES; i++) { unsigned char addr[16] = {0}; int len; int unicast = 1; /* SAFI for unicast forwarding. */ len = inet_net_pton(AF_INET, prefixes[i], addr, sizeof(addr)); if (len == -1) errx(1, "inet_net_pton(%s)", prefixes[i]); if (!X509v3_addr_add_prefix(addrblocks, IANA_AFI_IPV4, &unicast, addr, len)) errx(1, "X509v3_addr_add_prefix(%s)", prefixes[i]); } if (!X509v3_addr_add_inherit(addrblocks, IANA_AFI_IPV6, NULL)) errx(1, "X509v3_addr_add_inherit"); /* * Ensure the extension is in canonical form. Otherwise the two * adjacent prefixes 10.2.48/20 and 10.2.64/24 are not merged into * the range 10.2.48.0--10.2.64.255. This results in invalid DER * encoding from X509V3_EXT_i2d(3) and i2d_X509_EXTENSION(3). */ if (!X509v3_addr_canonize(addrblocks)) errx(1, "X509v3_addr_canonize"); /* Create the extension with the correct OID; mark it critical. */ ext = X509V3_EXT_i2d(NID_sbgp_ipAddrBlock, 1, addrblocks); if (ext == NULL) errx(1, "X509V3_EXT_i2d"); der = NULL; if ((der_len = i2d_X509_EXTENSION(ext, &der)) <= 0) errx(1, "i2d_X509_EXTENSION"); hexdump(der, der_len); /* One way of implementing IPAddrBlocks_free(). */ sk_IPAddressFamily_pop_free(addrblocks, IPAddressFamily_free); X509_EXTENSION_free(ext); free(der); return 0; } ``` Implement the missing public API **d2i\_IPAddrBlocks**() and **i2d\_IPAddrBlocks**() using ASN1\_item\_d2i(3): ``` IPAddrBlocks * d2i_IPAddrBlocks(IPAddrBlocks **addrblocks, const unsigned char **in, long len) { const X509V3_EXT_METHOD *v3_addr; if ((v3_addr = X509V3_EXT_get_nid(NID_sbgp_ipAddrBlock)) == NULL) return NULL; return (IPAddrBlocks *)ASN1_item_d2i((ASN1_VALUE **)addrblocks, in, len, ASN1_ITEM_ptr(v3_addr->it)); } int i2d_IPAddrBlocks(IPAddrBlocks *addrblocks, unsigned char **out) { const X509V3_EXT_METHOD *v3_addr; if ((v3_addr = X509V3_EXT_get_nid(NID_sbgp_ipAddrBlock)) == NULL) return -1; return ASN1_item_i2d((ASN1_VALUE *)addrblocks, out, ASN1_ITEM_ptr(v3_addr->it)); } ``` The use of the undocumented macro ASN1\_ITEM\_ptr() is necessary if compatibility with modern versions of other implementations is desired. ## SEE ALSO ASIdentifiers\_new(3), [crypto(3)](/crypto/3.md), [inet\_net\_ntop(3)](/inet_net_ntop/3.md), [inet\_ntop(3)](/inet_ntop/3.md), IPAddressRange\_new(3), X509\_new(3), X509v3\_addr\_get\_range(3), X509v3\_addr\_validate\_path(3), X509v3\_asid\_add\_id\_or\_range(3) ## STANDARDS RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: - section 2: IP Address delegation extension RFC 7020: The Internet Numbers Registry System RFC 7249: Internet Number Registries *Address Family Numbers*, https://www.iana.org/assignments/address-family-numbers. *Subsequent Address Family Identifiers (SAFI) Parameters*, https://www.iana.org/assignments/safi-namespace. ## HISTORY These functions first appeared in OpenSSL 0.9.8e and have been available since OpenBSD 7.1. ## BUGS **IPAddrBlocks\_new**(), **IPAddrBlocks\_free**(), **d2i\_IPAddrBlocks**(), and **i2d\_IPAddrBlocks**() do not exist and *IPAddrBlocks\_it* is not public. The above examples show how to implement the four missing functions with public API. **X509v3\_addr\_add\_range**() should check for inverted range bounds and overlaps on insertion and fail instead of creating a nonsensical *addrblocks* that fails to be canonized by **X509v3\_addr\_canonize**(). If NULL is passed to X509v3\_asid\_canonize(3), it succeeds. **X509v3\_addr\_is\_canonical**() considers NULL to be a canonical *IPAddrBlocks*. In contrast, **X509v3\_addr\_canonize**() crashes with a NULL dereference. The code only supports the IPv4 and IPv6 AFIs. This is not consistently enforced across implementations. In some implementations **X509v3\_addr\_add\_range**() fails to clear the unused bits set to 1 in the last octet of the *ASN1\_BIT\_STRING* representation of *max*. This confuses some software.