libressl-X509v3_asid_add_id_or_range3

Usage

Overview

An ASIdentifiers object represents the content of the certificate extension defined in RFC 3779, section 3.2.3.1. It can be instantiated with ASIdentifiers_new(3) and its internals are documented in ASRange_new(3).

An autonomous system is identified by an unsigned 32-bit integer, called an AS identifier or AS number. An ASIdentifiers object can hold two lists: a list of type V3_ASID_ASNUM containing individual AS identifiers and ranges of AS identifiers, and an obsolete list of type V3_ASID_RDI containing routing domain identifiers (RDIs). Either of these lists may be absent, or it may contain nothing but a special “inherit” marker that indicates that the list is inherited from the issuer of the certificate.

X509v3_asid_add_id_or_range() adds an individual identifier or a range of identifiers to the list of type (either V3_ASID_ASNUM or V3_ASID_RDI) in asid. If no such list exists, it is created first. If a list of type already exists and contains the “inherit” marker, the call fails. min must be a non-NULL ASN1_INTEGER. If max is NULL, min is added as an individual identifier. Ownership of min and max is transferred to asid on success. It is the responsibility of the caller to ensure that the resulting asid does not contain lists with overlapping ranges and that min is strictly less than max if both are non-NULL. The caller should also ensure that the AS identifiers are 32-bit integers. Failure to do so may result in an asid that cannot be brought into canonical form by X509v3_asid_canonize().

X509v3_asid_add_inherit() adds the list of type (either V3_ASID_ASNUM or V3_ASID_RDI) in asid if necessary and marks it “inherit”. This fails if asid already contains a list of type that is not marked “inherit”.

X509v3_asid_canonize() attempts to bring both lists in asid into canonical form. If asid is NULL the call succeeds and no action occurs. A list is in canonical form if it is either one of

• absent,

• marked “inherit”,

• non-empty and all identifiers and ranges are listed in increasing order. Ranges must not overlap, and adjacent ranges must be fully merged.

X509v3_asid_canonize() merges adjacent ranges but refuses to merge overlapping ranges or to discard duplicates. For example, the adjacent ranges [a,b] and [b+1,c] are merged into the single range [a,c], but if both [a,b] and [b,c] appear in a list, this results in an error since they are considered overlapping. Likewise, the identifier a is absorbed into the adjacent range [a+1,b] to yield [a,b]. X509v3_asid_canonize() errors if the minimum of any range is larger than the maximum. In contrast, minimum and maximum of a range may be equal.

X509v3_asid_is_canonical() checks whether asid is in canonical form. Once X509v3_asid_canonize() is called successfully on asid, all subsequent calls to X509v3_asid_is_canonical() succeed on an unmodified asid unless memory allocation fails.

Return values

All these functions return 1 on success and 0 on failure.

X509v3_asid_add_id_or_range() and X509v3_asid_add_inherit() fail if asid is NULL or if type is distinct from V3_ASID_ASNUM and V3_ASID_RDI, or on memory allocation failure. In addition, X509v3_asid_add_id_or_range() fails if asid contains a list of type that is marked “inherit”, and X509v3_asid_add_inherit() fails if asid contains a list of type that is not marked “inherit”.

X509v3_asid_canonize() fails if either list is empty and not marked “inherit”, or if it is malformed, or if memory allocation fails. Malformed lists include lists containing duplicate, overlapping, or malformed elements, for example AS ranges where the minimum is larger than the maximum. Some of these failure modes result in an error being pushed onto the error stack.

X509v3_asid_is_canonical() returns 1 if asid is canonical and 0 if it is not canonical or on memory allocation failure.