1.\" $OpenBSD: ASRange_new.3,v 1.8 2023/10/11 12:06:11 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: October 11 2023 $ 18.Dt ASRANGE_NEW 3 19.Os 20.Sh NAME 21.Nm ASRange_new , 22.Nm ASRange_free , 23.Nm d2i_ASRange , 24.Nm i2d_ASRange , 25.Nm ASIdOrRange_new , 26.Nm ASIdOrRange_free , 27.Nm d2i_ASIdOrRange , 28.Nm i2d_ASIdOrRange , 29.Nm ASIdentifierChoice_new , 30.Nm ASIdentifierChoice_free , 31.Nm d2i_ASIdentifierChoice , 32.Nm i2d_ASIdentifierChoice 33.Nd RFC 3779 autonomous system identifiers and ranges 34.Sh SYNOPSIS 35.In openssl/x509v3.h 36.Ft "ASRange *" 37.Fn ASRange_new void 38.Ft void 39.Fn ASRange_free "ASRange *asrange" 40.Ft ASRange * 41.Fo d2i_ASRange 42.Fa "ASRange **asrange" 43.Fa "const unsigned char **der_in" 44.Fa "long length" 45.Fc 46.Ft int 47.Fo i2d_ASRange 48.Fa "ASRange *asrange" 49.Fa "unsigned char **der_out" 50.Fc 51.Ft "ASIdOrRange *" 52.Fn ASIdOrRange_new void 53.Ft void 54.Fn ASIdOrRange_free "ASIdOrRange *aor" 55.Ft ASIdOrRange * 56.Fo d2i_ASIdOrRange 57.Fa "ASIdOrRange **aor" 58.Fa "const unsigned char **der_in" 59.Fa "long length" 60.Fc 61.Ft int 62.Fo i2d_ASIdOrRange 63.Fa "ASIdOrRange *aor" 64.Fa "unsigned char **der_out" 65.Fc 66.Ft "ASIdentifierChoice *" 67.Fn ASIdentifierChoice_new void 68.Ft void 69.Fn ASIdentifierChoice_free "ASIdentifierChoice *aic" 70.Ft ASIdentifierChoice * 71.Fo d2i_ASIdentifierChoice 72.Fa "ASIdentifierChoice **aic" 73.Fa "const unsigned char **der_in" 74.Fa "long length" 75.Fc 76.Ft int 77.Fo i2d_ASIdentifierChoice 78.Fa "ASIdentifierChoice *aic" 79.Fa "unsigned char **der_out" 80.Fc 81.Sh DESCRIPTION 82.Vt ASRange , 83.Vt ASIdOrRange , 84and 85.Vt ASIdentifierChoice 86are building blocks of the 87.Vt ASIdentifiers 88type representing the RFC 3779 89autonomous system identifier delegation extension. 90.Pp 91All 92.Vt ASN1_INTEGER Ns s 93in this manual must be representable as unsigned 32-bit integers. 94The API performs no corresponding checks. 95An 96.Vt ASN1_INTEGER 97can be set using 98.Xr ASN1_INTEGER_set_uint64 3 . 99.Pp 100The 101.Vt ASRange 102type defined in RFC 3779 section 3.2.3.8 is implemented as 103.Bd -literal -offset indent 104typedef struct ASRange_st { 105 ASN1_INTEGER *min; 106 ASN1_INTEGER *max; 107} ASRange; 108.Ed 109.Pp 110It represents the closed range [min,max] of AS identifiers between 111.Fa min 112and 113.Fa max , 114where 115.Fa min 116should be strictly smaller than 117.Fa max . 118.Pp 119.Fn ASRange_new 120allocates a new 121.Vt ASRange 122object with allocated, empty 123.Fa min 124and 125.Fa max , 126thus representing the invalid range [0,0]. 127.Pp 128.Fn ASRange_free 129frees 130.Fa asrange 131including any data contained in it. 132If 133.Fa asrange 134is 135.Dv NULL , 136no action occurs. 137.Pp 138The 139.Vt ASIdOrRange 140type defined in RFC 3779 section 3.2.3.5 is implemented as 141.Bd -literal -offset indent 142typedef struct ASIdOrRange_st { 143 int type; 144 union { 145 ASN1_INTEGER *id; 146 ASRange *range; 147 } u; 148} ASIdOrRange; 149.Ed 150.Pp 151representing an individual AS identifier or a range. 152When populating an 153.Vt ASIdOrRange 154object by hand, its 155.Fa type 156should be set to 157.Dv ASIdOrRange_id 158or 159.Dv ASIdOrRange_range 160to indicate which member of the union 161.Fa u 162is valid. 163.Pp 164.Fn ASIdOrRange_new 165returns a new 166.Vt ASIdOrRange 167object with invalid type and 168.Dv NULL 169members of the union 170.Fa u . 171.Pp 172.Fn ASIdOrRange_free 173frees 174.Fa aor 175including any data contained in it, 176provided 177.Fa type 178is set correctly. 179If 180.Fa asrange 181is 182.Dv NULL , 183no action occurs. 184.Pp 185In order to express a list of AS identifiers and ranges, 186RFC 3779 section 3.2.3.4 187uses an ASN.1 SEQUENCE, 188which is implemented via a 189.Xr STACK_OF 3 190construction over 191.Vt ASIdOrRange : 192.Bd -literal -offset indent 193typedef STACK_OF(ASIdOrRange) ASIdOrRanges; 194.Ed 195.Pp 196Since an 197.Vt ASIdOrRanges 198object should be sorted in a specific way (see 199.Xr X509v3_asid_canonize 3 Ns ), 200a comparison function is needed for a correct instantiation 201with 202.Xr sk_new 3 . 203The 204.Fn ASIdOrRange_cmp 205function is not directly exposed and not easily accessible 206from outside the library, 207and it is non-trivial to implement. 208It is therefore discouraged to use 209.Vt ASIdOrRanges 210objects that are not part of an 211.Vt ASIdentifiers 212object. 213.Pp 214The 215.Dq inherit 216marker from RFC 3779 section 3.2.3.3 is implemented as 217.Vt ASN1_NULL . 218It has no dedicated type or API and can be instantiated with 219.Xr ASN1_NULL_new 3 . 220.Pp 221The 222.Vt ASIdentifierChoice 223type defined in RFC 3779 section 3.2.3.2 is implemented as 224.Bd -literal -offset indent 225typedef struct ASIdentifierChoice_st { 226 int type; 227 union { 228 ASN1_NULL *inherit; 229 ASIdOrRanges *asIdsOrRanges; 230 } u; 231} ASIdentifierChoice; 232.Ed 233.Pp 234where the 235.Fa type 236member should be set to 237.Dv ASIdentifierChoice_inherit 238or 239.Dv ASIdentifierChoice_asIdsOrRanges 240to indicate whether a given 241.Vt ASIdentifierChoice 242object represents an inherited list or an explicit list. 243.Pp 244.Fn ASIdentifierChoice_new 245returns a new 246.Vt ASIdentifierChoice 247object with invalid type and 248.Dv NULL 249members of the union 250.Fa u . 251.Pp 252.Fn ASIdentifierChoice_free 253frees 254.Fa aic 255including any data contained in it, 256provided 257.Fa type 258is set correctly. 259.Pp 260The 261.Vt ASIdentifiers 262type defined in RFC 3779 section 3.2.3.1 is implemented as 263.Bd -literal -offset indent 264typedef struct ASIdentifiers_st { 265 ASIdentifierChoice *asnum; 266 ASIdentifierChoice *rdi; 267} ASIdentifiers; 268.Ed 269.Pp 270It should be instantiated with 271.Xr ASIdentifiers_new 3 272and populated with 273.Xr X509v3_asid_add_id_or_range 3 . 274.Pp 275.Fn d2i_ASRange , 276.Fn i2d_ASRange , 277.Fn d2i_ASIdOrRange , 278.Fn i2d_ASIdOrRange , 279.Fn d2i_ASIdentifierChoice , 280and 281.Fn i2d_ASIdentifierChoice 282decode and encode ASN.1 283.Vt ASRange , 284.Vt ASIdOrRange , 285and 286.Vt ASIdentifierChoice 287objects. 288For details about the semantics, examples, caveats, and bugs, see 289.Xr ASN1_item_d2i 3 . 290In order for the encoding produced by 291.Fn i2d_ASRange 292to be correct, 293.Fa min 294must be strictly less than 295.Fa max . 296Similarly for 297.Fn i2d_ASIdOrRange 298and an 299.Fa ASIdOrRange 300object of 301.Fa type 302.Dv ASIdOrRange_range . 303.Sh RETURN VALUES 304.Fn ASRange_new 305returns a new 306.Vt ASRange 307object with allocated, empty members, or 308.Dv NULL 309if an error occurs. 310.Pp 311.Fn ASIdOrRange_new 312returns a new, empty 313.Vt ASIdOrRange 314object or 315.Dv NULL 316if an error occurs. 317.Pp 318.Fn ASIdentifierChoice_new 319returns a new, empty 320.Vt ASIdentifierChoice 321object or 322.Dv NULL 323if an error occurs. 324.Pp 325The decoding functions 326.Fn d2i_ASRange , 327.Fn d2i_ASIdOrRange , 328and 329.Fn d2i_ASIdentifierChoice 330return an 331.Vt ASRange , 332an 333.Vt ASIdOrRange , 334or an 335.Vt ASIdentifierChoice , 336object, respectively, 337or 338.Dv NULL 339if an error occurs. 340.Pp 341The encoding functions 342.Fn i2d_ASRange , 343.Fn i2d_ASIdOrRange , 344and 345.Fn i2d_ASIdentifierChoice 346return the number of bytes successfully encoded 347or a value <= 0 if an error occurs. 348.Sh SEE ALSO 349.Xr ASIdentifiers_new 3 , 350.Xr ASN1_INTEGER_set_uint64 3 , 351.Xr crypto 3 , 352.Xr IPAddressRange_new 3 , 353.Xr s2i_ASN1_INTEGER 3 , 354.Xr STACK_OF 3 , 355.Xr X509_new 3 , 356.Xr X509v3_asid_add_id_or_range 3 357.Sh STANDARDS 358RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: 359.Bl -dash -compact 360.It 361section 3.2.3: Syntax 362.It 363section 3.2.3.1: Type ASIdentifiers 364.It 365section 3.2.3.2: Elements asnum, rdi, and Type ASIdentifierChoice 366.It 367section 3.2.3.3: Element inherit 368.It 369section 3.2.3.4: Element asIdsOrRanges 370.It 371section 3.2.3.5: Type ASIdOrRange 372.It 373section 3.2.3.6: Element id 374.It 375section 3.2.3.7: Element range 376.It 377section 3.2.3.8: Type ASRange 378.It 379section 3.2.3.9: Elements min and max 380.El 381.Sh HISTORY 382These functions first appeared in OpenSSL 0.9.8e 383and have been available since 384.Ox 7.1 . 385.Sh BUGS 386An 387.Fn ASIdOrRanges_new 388function that installs the correct comparison function 389on the stack of 390.Vt ASIdOrRange 391should have been part of the API to make it usable. 392.Pp 393.Fn ASIdentifierChoice_new 394is of very limited use because 395.Fn ASIdOrRanges_new 396is missing. 397.Pp 398There is no way of ensuring that an 399.Vt ASIdOrRanges 400object is in canonical form unless it is part of an 401.Vt ASIdentifiers 402object. 403It is therefore difficult to guarantee that the output of 404.Fn i2d_ASIdentifierChoice 405is conformant. 406.Pp 407RFC 3779 3.2.3.4 has 408.Dq Fa asIdsOrRanges 409while its type in this implementation is 410.Vt ASIdOrRanges . 411