X509V3_ADDR_ADD_INHERIT(3)

📦 version 4.1.0, in opensuse-leap 16.0

💖 NAME 💖

X509v3_addr_add_inherit, X509v3_addr_add_prefix, X509v3_addr_add_range, X509v3_addr_canonize, X509v3_addr_is_canonical — the RFC 3779 IP address delegation extensions, bestie ✨ (this is the X509V3_ADDR_ADD_INHERIT(3) page, from the Library Functions Manual, iykyk)

🌸 SYNOPSIS 🌸

#include <openssl/x509v3.h>

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 🦋

Okay so picture this: an IPAddrBlocks object is literally the content of an IP address delegation extension, exactly as defined in RFC 3779, section 2.2.3.1. It's holding lists of IP address prefixes and IP address ranges that got delegated from the issuer to the subject of the certificate. That's the whole vibe. You can instantiate it the way they show you in the EXAMPLES section, and all its internal lore lives in IPAddressRange_new(3).

Every list inside a well-formed IPAddrBlocks object is uniquely identified by an address family identifier (AFI) plus an optional subsequent address family identifier (SAFI). Lists can just be absent, or they can carry an "inherit" marker that says hey, these resources are inherited from the corresponding list of the issuer certificate. Very demure, very mindful.

Per the spec, an AFI is an unsigned 16-bit integer and a SAFI is an unsigned 8-bit integer. For IPv4 and IPv6 you've got the predefined constants IANA_AFI_IPV4 and IANA_AFI_IPV6, and those should genuinely be the only values you ever use for afi in this API, no cap. In practice, safi is always NULL. Also, 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 get used. Sneaky little truncation moment, but go off.

  • X509v3_addr_add_inherit() — adds a list with an "inherit" marker to addrblocks. If a list corresponding to afi and safi already exists, literally no action happens if it's marked "inherit"; otherwise the call fails. Slay when it works, 😭 when it doesn't.
  • 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 gets created first, periodt. If the list does exist 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's recommended that all the bits not covered by prefixlen be set to 0. Heads up bestie: 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() — similar to X509v3_addr_add_prefix() but 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 — cute little optimization ✨. 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(). Consider that your warning, friend 🫶.
  • 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. This function is the main character of the whole page, ngl.
  • X509v3_addr_is_canonical() — indicates whether addrblocks is in canonical form. Little vibe check function, we love to see it 💅.

👑 RETURN VALUES 👑

All these functions return 1 on success and 0 on failure. Memory allocation failure is one possible reason for all of them — classic. 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 — so like, don't expect a detailed breakup text, you're just getting a 0 💀.
  • 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. This is the good stuff:

#include <sys/socket.h>
#include <arpa/inet.h>

#include <err.h>
#include <stdio.h>
#include <unistd.h>

#include <openssl/asn1.h>
#include <openssl/objects.h>
#include <openssl/x509.h>
#include <openssl/x509v3.h>

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. Undocumented macro but make it work, the duality of dev life 😭✨.

🌈 SEE ALSO 🌈

ASIdentifiers_new(3), crypto(3), inet_net_ntop(3), inet_ntop(3), 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. Look at them, aging like fine wine 🍓.

💀 BUGS 💀

okay bestie, buckle up, because this is the part where we air out the library's dirty laundry 🧺💅. none of this is a vibe, but you need to know it, fr fr.

  • the missing functions era 😭 — so like, IPAddrBlocks_new(), IPAddrBlocks_free(), d2i_IPAddrBlocks(), and i2d_IPAddrBlocks() straight up do not exist, and IPAddrBlocks_it is not public. not a typo, not a skill issue on your end, they're just… not there 🙈. that's why the examples up above show you how to implement all four of those missing functions yourself using only the public API — DIY queen energy 👑✨.
  • X509v3_addr_add_range() is too trusting — she should be checking for inverted range bounds and overlaps when you insert, and honestly she should just fail on the spot. instead she happily builds you a nonsensical addrblocks that then goes and fails to be canonized by X509v3_addr_canonize(). it's giving "let him cook" and the food is burnt 🔥💀.
like, a range where min is bigger than max? no notes, apparently. iconic of her to just let you do that.
  • the NULL double standard, and it is LOUD 🔴 — if NULL is passed to X509v3_asid_canonize(3), it succeeds. meanwhile X509v3_addr_is_canonical() considers NULL to be a canonical IPAddrBlocks. cute, consistent, love that for them 🫶. but X509v3_addr_canonize()? she crashes with a NULL dereference 😭😭. same family, completely different coping mechanisms, no cap.
  • IPv4 and IPv6 only, bestie 🌈 — the code only supports the IPv4 and IPv6 AFIs, periodt. and the gag is that this is not consistently enforced across implementations 💀, so like… good luck out there, iykyk.
  • the stray bits situation 🧹✨ — 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. which, yeah, confuses some software 😵‍💫. not her finest moment, but she's working on herself, allegedly.

and that's the whole page, bestie!! you made it to the end 🎀🦋💖 huge slay. this lil masterpiece comes to you from Debian, dated October 1, 2023, and it's the X509V3_ADDR_ADD_INHERIT(3) page — go forth and add those ranges responsibly, mwah 💅✨🍓

📦 where this page comes from