IPADDRESSRANGE_NEW(3) Library Functions Manual IPADDRESSRANGE_NEW(3)

IPAddressRange_new, IPAddressRange_free, d2i_IPAddressRange, i2d_IPAddressRange, IPAddressOrRange_new, IPAddressOrRange_free, d2i_IPAddressOrRange, i2d_IPAddressOrRange, IPAddressChoice_new, IPAddressChoice_free, d2i_IPAddressChoice, i2d_IPAddressChoice, IPAddressFamily_new, IPAddressFamily_free, d2i_IPAddressFamily, i2d_IPAddressFamily — RFC 3779 IP address prefixes and ranges

#include <openssl/x509v3.h>

IPAddressRange *
IPAddressRange_new(void);

void
IPAddressRange_free(IPAddressRange *range);

IPAddressRange *
d2i_IPAddressRange(IPAddressRange **range, const unsigned char **der_in, long length);

int
i2d_IPAddressRange(IPAddressRange *range, unsigned char **der_out);

IPAddressOrRange *
IPAddressOrRange_new(void);

void
IPAddressOrRange_free(IPAddressOrRange *aor);

IPAddressOrRange *
d2i_IPAddressOrRange(IPAddressOrRange **aor, const unsigned char **der_in, long length);

int
i2d_IPAddressOrRange(IPAddressOrRange *aor, unsigned char **der_out);

IPAddressChoice *
IPAddressChoice_new(void);

void
IPAddressChoice_free(IPAddressChoice *ac);

IPAddressChoice *
d2i_IPAddressChoice(IPAddressChoice **ac, const unsigned char **der_in, long length);

int
i2d_IPAddressChoice(IPAddressChoice *ac, unsigned char **der_out);

IPAddressFamily *
IPAddressFamily_new(void);

void
IPAddressFamily_free(IPAddressFamily *af);

IPAddressFamily *
d2i_IPAddressFamily(IPAddressFamily **af, const unsigned char **der_in, long length);

int
i2d_IPAddressFamily(IPAddressFamily *af, unsigned char **der_out);

IPAddressRange, IPAddressOrRange, IPAddressChoice, and IPAddressFamily are building blocks of the IPAddrBlocks type representing the RFC 3779 IP address delegation extension.

Per RFC 3779, section 2.1.1, an IPv4 or an IPv6 address is encoded in network byte order in an ASN.1 BIT STRING of bit size 32 or 128 bits, respectively. The bit size of a prefix is its prefix length; all insignificant zero bits are omitted from the encoding. Per section 2.1.2, an address range is expressed as a pair of BIT STRINGs where all the least significant zero bits of the lower bound and all the least significant one bits of the upper bound are omitted.

The library provides no API for directly converting an IP address or prefix (in any form) to and from an ASN1_BIT_STRING. It also provides no API for directly handling ranges. The ASN1_BIT_STRING internals are subtle and directly manipulating them in the context of the RFC 3779 API is discouraged. The bit size of an ASN1_BIT_STRING representing an IP address prefix or range is eight times its length member minus the lowest three bits of its flags, provided the ASN1_STRING_FLAG_BITS_LEFT flag is set.

The IPAddressRange type defined in RFC 3779 section 2.2.3.9 is implemented as

typedef struct IPAddressRange_st {
	ASN1_BIT_STRING *min;
	ASN1_BIT_STRING *max;
} IPAddressRange;

It represents the closed range [min,max] of IP addresses between min and max, where min should be strictly smaller than max and the range should not be expressible as a prefix.

() allocates a new IPAddressRange object with allocated, empty min and max, thus representing the entire address space invalidly as a non-prefix.

() frees range including any data contained in it. If range is NULL, no action occurs.

There is no dedicated type representing the IPAddress type defined in RFC 3779 section 2.2.3.8. The API uses ASN1_BIT_STRING for this.

The IPAddressOrRange type defined in RFC 3779 section 2.2.3.7 is implemented as

typedef struct IPAddressOrRange_st {
	int type;
	union {
		ASN1_BIT_STRING *addressPrefix;
		IPAddressRange *addressRange;
	} u;
} IPAddressOrRange;

representing an individual address prefix or an address range. The type member should be set to IPAddressOrRange_addressPrefix or IPAddressOrRange_addressRange to indicate which member of the union u is valid.

() returns a new IPAddressOrRange object with invalid type and NULL members of the union u.

() frees aor including any data contained in it, provided type is set correctly. If aor is NULL, no action occurs.

In order to express a list of address prefixes and address ranges, RFC 3779 section 2.2.3.6 uses an ASN.1 SEQUENCE, which is implemented via a STACK_OF(3) construction over IPAddressOrRange:

typedef STACK_OF(IPAddressOrRange) IPAddressOrRanges;

Since an IPAddressOrRanges object should be sorted in a specific way (see X509v3_addr_canonize(3)), a comparison function is needed for a correct instantiation with sk_new(3). The () and () functions are not directly exposed and not easily accessible from outside the library, and they are non-trivial to implement. It is therefore discouraged to use IPAddressOrRanges objects that are not part of an IPAddrBlocks object.

The “inherit” marker from RFC 3779 section 2.2.3.5 is implemented as ASN1_NULL. It has no dedicated type or API and can be instantiated with ASN1_NULL_new(3).

The IPAddressChoice type defined in RFC 3779 section 2.2.3.4 is implemented as

typedef struct IPAddressChoice_st {
	int type;
	union {
		ASN1_NULL *inherit;
		IPAddressOrRanges *addressesOrRanges;
	} u;
} IPAddressChoice;

where the type member should be set to IPAddressChoice_inherit or IPAddressChoice_addressesOrRanges to indicate whether a given IPAddressChoice object represents an inherited list or an explicit list.

() returns a new IPAddressChoice object with invalid type and NULL members of the union u.

() frees ac including any data contained in it, provided type is set correctly.

The addressFamily element defined in RFC 3779 section 2.2.3.3 is implemented as an ASN1_OCTET_STRING and it contains two or three octets. The first two octets are always present and represent the address family identifier (AFI) in network byte order. The optional subsequent address family identifier (SAFI) occupies the third octet. For IPv4 and IPv6, IANA_AFI_IPV4 and IANA_AFI_IPV6 are predefined. Other AFIs are not supported by this implementation.

The IPAddressFamily type defined in RFC 3779 section 2.2.3.2 is implemented as

typedef struct IPAddressFamily_st {
	ASN1_OCTET_STRING *addressFamily;
	IPAddressChoice *ipAddressChoice;
} IPAddressFamily;

The addressFamily member indicates the address family the ipAddressChoice represents.

() returns a new IPAddressFamily object with empty addressFamily and invalid ipAddressChoice members.

() frees af including any data contained in it. If af is NULL, no action occurs.

The IPAddrBlocks type defined in RFC 3779 section 2.2.3.1 uses an ASN.1 SEQUENCE, which is implemented via a STACK_OF(3) construction over IPAddressFamily:

typedef STACK_OF(IPAddressFamily) IPAddrBlocks;

It can be instantiated with () and the correct sorting function can be installed with X509v3_addr_canonize(3). To populate it, use X509v3_addr_add_prefix(3) and related functions.

(), (), (), (), (), (), (), and () decode and encode ASN.1 IPAddressRange, IPAddressOrRange, IPAddressChoice, and IPAddressFamily objects. For details about the semantics, examples, caveats, and bugs, see ASN1_item_d2i(3). There is no easy way of ensuring that the encodings generated by these functions are correct, unless they are applied to objects that are part of a canonical IPAddrBlocks structure, see X509v3_addr_is_canonical(3).

IPAddressRange_new() returns a new IPAddressRange object with allocated, empty members, or NULL if an error occurs.

IPAddressOrRange_new() returns a new, empty IPAddressOrRange object or NULL if an error occurs.

IPAddressChoice_new() returns a new, empty IPAddressChoice object or NULL if an error occurs.

IPAddressFamily_new() returns a new IPAddressFamily object with allocated, empty members, or NULL if an error occurs.

The decoding functions d2i_IPAddressRange(), d2i_IPAddressOrRange(), d2i_IPAddressChoice(), and d2i_IPAddressFamily() return an IPAddressRange, an IPAddressOrRange, an IPAddressChoice, or an IPAddressFamily object, respectively, or NULL if an error occurs.

The encoding functions i2d_IPAddressRange(), i2d_IPAddressOrRange(), i2d_IPAddressChoice(), and i2d_IPAddressFamily() return the number of bytes successfully encoded or a value <= 0 if an error occurs.

ASIdentifiers_new(3), ASN1_BIT_STRING_new(3), ASN1_OCTET_STRING_new(3), ASN1_OCTET_STRING_set(3), crypto(3), X509_new(3), X509v3_addr_add_inherit(3), X509v3_addr_inherits(3), X509v3_addr_subset(3)

RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:

  • section 2.1.1: Encoding of an IP Address or Prefix
  • section 2.1.2: Encoding of a Range of IP Addresses
  • section 2.2.3: Syntax
  • section 2.2.3.1: Type IPAddrBlocks
  • section 2.2.3.2: Type IPAddressFamily
  • section 2.2.3.3: Element addressFamily
  • section 2.2.3.4: Element ipAddressChoice and Type IPAddressChoice
  • section 2.2.3.5: Element inherit
  • section 2.2.3.6: Element addressesOrRanges
  • section 2.2.3.7: Type IPAddressOrRange
  • section 2.2.3.8: Element addressPrefix and Type IPAddress
  • section 2.2.3.9: Element addressRange and Type IPAddressRange

ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER), section 8.6: Encoding of a bitstring value

These functions first appeared in OpenSSL 0.9.8e and have been available since OpenBSD 7.1.

As it stands, the API is barely usable due to missing convenience accessors, constructors and destructors and due to the complete absence of API that checks that the individual building blocks are correct. Extracting information from a given object can be done relatively safely. However, constructing objects is very error prone, be it by hand or using the bug-ridden X509v3_addr_add_inherit(3) API.

RFC 3779 has element “addressesOrRanges”. Its type in this API is IPAddressOrRanges.

October 3, 2023 Linux 6.8.2-arch2-1