1.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.9 2023/09/30 18:16:44 tb Exp $ 2.\" 3.\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 30 2023 $ 18.Dt X509V3_ASID_ADD_ID_OR_RANGE 3 19.Os 20.Sh NAME 21.Nm X509v3_asid_add_id_or_range , 22.Nm X509v3_asid_add_inherit , 23.Nm X509v3_asid_canonize , 24.Nm X509v3_asid_is_canonical 25.Nd RFC 3779 autonomous system identifier delegation extension 26.Sh SYNOPSIS 27.In openssl/x509v3.h 28.Ft int 29.Fo X509v3_asid_add_id_or_range 30.Fa "ASIdentifiers *asid" 31.Fa "int type" 32.Fa "ASN1_INTEGER *min" 33.Fa "ASN1_INTEGER *max" 34.Fc 35.Ft int 36.Fo X509v3_asid_add_inherit 37.Fa "ASIdentifiers *asid" 38.Fa "int type" 39.Fc 40.Ft int 41.Fo X509v3_asid_canonize 42.Fa "ASIdentifiers *asid" 43.Fc 44.Ft int 45.Fo X509v3_asid_is_canonical 46.Fa "ASIdentifiers *asid" 47.Fc 48.Sh DESCRIPTION 49An 50.Vt ASIdentifiers 51object represents the content of the certificate extension 52defined in RFC 3779, section 3.2.3.1. 53It can be instantiated with 54.Xr ASIdentifiers_new 3 55and its internals are documented in 56.Xr ASRange_new 3 . 57.Pp 58An autonomous system is identified by an unsigned 32-bit integer, 59called an AS identifier or AS number. 60An 61.Vt ASIdentifiers 62object can hold two lists: 63a list of 64.Fa type 65.Dv V3_ASID_ASNUM 66containing individual AS identifiers and ranges of AS identifiers, 67and an obsolete list of 68.Fa type 69.Dv V3_ASID_RDI 70containing routing domain identifiers (RDIs). 71Either of these lists may be absent, or it may contain nothing 72but a special 73.Dq inherit 74marker that indicates that the list is inherited from the issuer 75of the certificate. 76.Pp 77.Fn X509v3_asid_add_id_or_range 78adds an individual identifier or a range of identifiers to the list of 79.Fa type 80(either 81.Dv V3_ASID_ASNUM 82or 83.Dv V3_ASID_RDI ) 84in 85.Fa asid . 86If no such list exists, it is created first. 87If a list of 88.Fa type 89already exists and contains the 90.Dq inherit 91marker, the call fails. 92.Fa min 93must be a 94.Pf non- Dv NULL 95.Vt ASN1_INTEGER . 96If 97.Fa max 98is 99.Dv NULL , 100.Fa min 101is added as an individual identifier. 102Ownership of 103.Fa min 104and 105.Fa max 106is transferred to 107.Fa asid 108on success. 109It is the responsibility of the caller to ensure that 110the resulting 111.Fa asid 112does not contain lists with overlapping ranges and that 113.Fa min 114is strictly less than 115.Fa max 116if both are 117.Pf non- Dv NULL . 118The caller should also ensure that the AS identifiers are 11932-bit integers. 120Failure to do so may result in an 121.Fa asid 122that cannot be brought into canonical form by 123.Fn X509v3_asid_canonize . 124.Pp 125.Fn X509v3_asid_add_inherit 126adds the list of 127.Fa type 128(either 129.Dv V3_ASID_ASNUM 130or 131.Dv V3_ASID_RDI ) 132in 133.Fa asid 134if necessary and marks it 135.Dq inherit . 136This fails if 137.Fa asid 138already contains a list of 139.Fa type 140that is not marked 141.Dq inherit . 142.Pp 143.Fn X509v3_asid_canonize 144attempts to bring both lists in 145.Fa asid 146into canonical form. 147If 148.Fa asid 149is 150.Dv NULL 151the call succeeds and no action occurs. 152A list is in canonical form if it is either one of 153.Bl -dash -compact 154.It 155absent, 156.It 157marked 158.Dq inherit , 159.It 160non-empty and all identifiers and ranges are listed in increasing order. 161Ranges must not overlap, 162.\" the following is not currently specified and leads to ambiguity: 163.\" contain at least two elements, 164and adjacent ranges must be fully merged. 165.El 166.Pp 167.Fn X509v3_asid_canonize 168merges adjacent ranges 169but refuses to merge overlapping ranges or to discard duplicates. 170For example, the adjacent ranges [a,b] and [b+1,c] are merged 171into the single range [a,c], but if both [a,b] and [b,c] appear in a list, 172this results in an error since they are considered overlapping. 173Likewise, the identifier a is absorbed into the adjacent 174range [a+1,b] to yield [a,b]. 175.Fn X509v3_asid_canonize 176errors if the minimum of any range is larger than the maximum. 177In contrast, minimum and maximum of a range may be equal. 178.Pp 179.Fn X509v3_asid_is_canonical 180checks whether 181.Fa asid 182is in canonical form. 183Once 184.Fn X509v3_asid_canonize 185is called successfully on 186.Fa asid , 187all subsequent calls to 188.Fn X509v3_asid_is_canonical 189succeed on an unmodified 190.Fa asid 191unless memory allocation fails. 192.Sh RETURN VALUES 193All these functions return 1 on success and 0 on failure. 194.Pp 195.Fn X509v3_asid_add_id_or_range 196and 197.Fn X509v3_asid_add_inherit 198fail if 199.Fa asid 200is 201.Dv NULL 202or if 203.Fa type 204is distinct from 205.Dv V3_ASID_ASNUM 206and 207.Dv V3_ASID_RDI , 208or on memory allocation failure. 209In addition, 210.Fn X509v3_asid_add_id_or_range 211fails if 212.Fa asid 213contains a list of 214.Fa type 215that is marked 216.Dq inherit , 217and 218.Fn X509v3_asid_add_inherit 219fails if 220.Fa asid 221contains a list of 222.Fa type 223that is not marked 224.Dq inherit . 225.Pp 226.Fn X509v3_asid_canonize 227fails if either list is empty and not marked 228.Dq inherit , 229or if it is malformed, or if memory allocation fails. 230Malformed lists include lists containing duplicate, overlapping, 231or malformed elements, for example AS ranges where the minimum is 232larger than the maximum. 233Some of these failure modes result in an error being pushed onto the 234error stack. 235.Pp 236.Fn X509v3_asid_is_canonical 237returns 1 if 238.Fa asid 239is canonical and 0 if it is not canonical or on memory allocation 240failure. 241.Sh SEE ALSO 242.Xr ASIdentifiers_new 3 , 243.Xr crypto 3 , 244.Xr s2i_ASN1_INTEGER 3 , 245.Xr X509_new 3 , 246.Xr X509v3_addr_add_inherit 3 , 247.Xr X509v3_addr_validate_path 3 248.Sh STANDARDS 249RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers, 250.Bl -dash -compact 251.It 252section 3: Autonomous System Delegation Extension 253.El 254.Pp 255.Rs 256.%T Autonomous System (AS) Numbers 257.%U https://www.iana.org/assignments/as-numbers 258.Re 259.Sh HISTORY 260These functions first appeared in OpenSSL 0.9.8e 261and have been available since 262.Ox 7.1 . 263.Sh BUGS 264.Fn X509v3_asid_add_id_or_range 265does not check for inverted range bounds and overlaps 266on insertion. 267It is very easy to create an 268.Fa asid 269that fails to be canonized by 270.Fn X509v3_asid_canonize 271and it is very hard to diagnose why. 272.Pp 273Both 274.Fn X509v3_asid_add_id_or_range 275and 276.Fn X509v3_asid_add_inherit 277can leave 278.Fa asid 279in a corrupted state if memory allocation fails during their execution. 280In addition, 281.Fn X509v3_asid_add_id_or_range 282may already have freed the 283.Fa min 284and 285.Fa max 286arguments on failure. 287.Pp 288RFC 3779 does not explicitly disallow ranges where the minimum 289is equal to the maximum. 290The isolated AS identifier 291.Fa min 292and the AS range 293.Bq Fa min , Ns Fa min 294where the minimum and the maximum are equal to 295.Fa min 296have the same semantics. 297.Fn X509v3_asid_is_canonical 298accepts both representations as valid and 299.Fn X509v3_asid_canonize 300does not prefer either representation over the other. 301The encodings of the two representations produced by 302.Xr i2d_ASIdentifiers 3 303are distinct. 304.Pp 305.Fn X509v3_asid_is_canonical 306does not fully check inheriting lists to be well formed. 307It only checks the 308.Fa type 309to be 310.Dv ASIdentifierChoice_inherit 311and ignores the presence or absence of the 312.Fa inherit 313element. 314.Fn X509v3_asid_canonize 315does not fix that up. 316This can lead to incorrect or unexpected DER encoding of 317.Dq canonical 318.Vt ASIdentifiers 319objects. 320In particular, it is possible to construct an 321.Vt ASIdentifiers 322object for which both 323.Fn X509v3_asid_is_canonical 324and 325.Xr X509v3_asid_inherits 3 326return 1, and after a round trip through DER the latter 327returns 0. 328