---
name: "libressl-IPAddressRange_new"
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-IPAddressRange_new"
---

# libressl-IPAddressRange\_new(3)

RFC 3779 IP address prefixes and ranges

## NAME

**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

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#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*);

## DESCRIPTION

*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.

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

**IPAddressRange\_free**() 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.

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

**IPAddressOrRange\_free**() 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 **v4IPAddressOrRange\_cmp**() and **v6IPAddressOrRange\_cmp**() 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.

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

**IPAddressChoice\_free**() 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.

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

**IPAddressFamily\_free**() 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 **sk\_IPAddressFamily\_new\_null**() 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.

**d2i\_IPAddressRange**(), **i2d\_IPAddressRange**(), **d2i\_IPAddressOrRange**(), **i2d\_IPAddressOrRange**(), **d2i\_IPAddressChoice**(), **i2d\_IPAddressChoice**(), **d2i\_IPAddressFamily**(), and **i2d\_IPAddressFamily**() 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).

## RETURN VALUES

**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.

## SEE ALSO

ASIdentifiers\_new(3), ASN1\_BIT\_STRING\_new(3), ASN1\_OCTET\_STRING\_new(3), ASN1\_OCTET\_STRING\_set(3), [crypto(3)](/crypto/3.md), X509\_new(3), X509v3\_addr\_add\_inherit(3), X509v3\_addr\_inherits(3), X509v3\_addr\_subset(3)

## STANDARDS

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

## HISTORY

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

## BUGS

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*.