1.\" $OpenBSD: ASN1_TYPE_get.3,v 1.19 2023/10/09 16:06:01 tb Exp $ 2.\" selective merge up to: OpenSSL 6328d367 Jul 4 21:58:30 2020 +0200 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2017, 2021 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2015, 2016 The OpenSSL Project. All rights reserved. 23.\" 24.\" Redistribution and use in source and binary forms, with or without 25.\" modification, are permitted provided that the following conditions 26.\" are met: 27.\" 28.\" 1. Redistributions of source code must retain the above copyright 29.\" notice, this list of conditions and the following disclaimer. 30.\" 31.\" 2. Redistributions in binary form must reproduce the above copyright 32.\" notice, this list of conditions and the following disclaimer in 33.\" the documentation and/or other materials provided with the 34.\" distribution. 35.\" 36.\" 3. All advertising materials mentioning features or use of this 37.\" software must display the following acknowledgment: 38.\" "This product includes software developed by the OpenSSL Project 39.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 40.\" 41.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 42.\" endorse or promote products derived from this software without 43.\" prior written permission. For written permission, please contact 44.\" openssl-core@openssl.org. 45.\" 46.\" 5. Products derived from this software may not be called "OpenSSL" 47.\" nor may "OpenSSL" appear in their names without prior written 48.\" permission of the OpenSSL Project. 49.\" 50.\" 6. Redistributions of any form whatsoever must retain the following 51.\" acknowledgment: 52.\" "This product includes software developed by the OpenSSL Project 53.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 54.\" 55.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 56.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 57.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 58.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 59.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 60.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 61.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 62.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 63.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 64.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 66.\" OF THE POSSIBILITY OF SUCH DAMAGE. 67.\" 68.Dd $Mdocdate: October 9 2023 $ 69.Dt ASN1_TYPE_GET 3 70.Os 71.Sh NAME 72.Nm ASN1_TYPE_new , 73.Nm ASN1_TYPE_free , 74.Nm ASN1_TYPE_get , 75.Nm ASN1_TYPE_set , 76.Nm ASN1_TYPE_set1 , 77.Nm ASN1_TYPE_set_octetstring , 78.Nm ASN1_TYPE_get_octetstring , 79.Nm ASN1_TYPE_set_int_octetstring , 80.Nm ASN1_TYPE_get_int_octetstring , 81.Nm ASN1_TYPE_cmp 82.Nd ASN.1 objects of arbitrary type 83.Sh SYNOPSIS 84.In openssl/asn1.h 85.Ft ASN1_TYPE * 86.Fn ASN1_TYPE_new void 87.Ft void 88.Fn ASN1_TYPE_free "ASN1_TYPE *a" 89.Ft int 90.Fo ASN1_TYPE_get 91.Fa "const ASN1_TYPE *a" 92.Fc 93.Ft void 94.Fo ASN1_TYPE_set 95.Fa "ASN1_TYPE *a" 96.Fa "int type" 97.Fa "void *value" 98.Fc 99.Ft int 100.Fo ASN1_TYPE_set1 101.Fa "ASN1_TYPE *a" 102.Fa "int type" 103.Fa "const void *value" 104.Fc 105.Ft int 106.Fo ASN1_TYPE_set_octetstring 107.Fa "ASN1_TYPE *a" 108.Fa "const unsigned char *data" 109.Fa "int len" 110.Fc 111.Ft int 112.Fo ASN1_TYPE_get_octetstring 113.Fa "const ASN1_TYPE *a" 114.Fa "unsigned char *buffer" 115.Fa "int buflen" 116.Fc 117.Ft int 118.Fo ASN1_TYPE_set_int_octetstring 119.Fa "ASN1_TYPE *a" 120.Fa "long num" 121.Fa "const unsigned char *data" 122.Fa "int len" 123.Fc 124.Ft int 125.Fo ASN1_TYPE_get_int_octetstring 126.Fa "const ASN1_TYPE *a", 127.Fa "long *num" 128.Fa "unsigned char *buffer", 129.Fa "int buflen" 130.Fc 131.Ft int 132.Fo ASN1_TYPE_cmp 133.Fa "const ASN1_TYPE *a" 134.Fa "const ASN1_TYPE *b" 135.Fc 136.Sh DESCRIPTION 137The 138.Vt ASN1_TYPE 139data type and the 140.Dv V_ASN1_ANY 141type identifier constant represent the ASN.1 ANY type. 142An 143.Vt ASN1_TYPE 144object can store an ASN.1 value of arbitrary type, 145including constructed types such as a SEQUENCE. 146It also remembers internally which type it currently holds. 147.Pp 148.Fn ASN1_TYPE_new 149allocates and initializes an empty 150.Vt ASN1_TYPE 151object of type 152.Dv V_ASN1_UNDEF . 153.Pp 154.Fn ASN1_TYPE_free 155frees 156.Fa a 157including the value stored in it, if any. 158If 159.Fa a 160is a 161.Dv NULL 162pointer, no action occurs. 163.Pp 164.Fn ASN1_TYPE_get 165returns the type currently held by 166.Fa a , 167represented by one of the 168.Dv V_ASN1_* 169constants defined in 170.In openssl/asn1.h . 171.Pp 172.Fn ASN1_TYPE_set 173frees the value contained in 174.Fa a , 175if any, and sets the 176.Fa value 177and 178.Fa type 179now held in 180.Fa a . 181This function uses the pointer 182.Fa value 183internally so it must 184.Sy not 185be freed up after the call. 186.Pp 187.Fn ASN1_TYPE_set1 188sets the type held by 189.Fa a 190to 191.Fa type 192and its value to a copy of 193.Fa value . 194If copying succeeds, the previous value that was contained in 195.Fa a 196is freed. 197If copying fails, 198.Fa a 199remains unchanged. 200.Pp 201The type and meaning of the 202.Fa value 203argument of 204.Fn ASN1_TYPE_set 205and 206.Fn ASN1_TYPE_set1 207is determined by the 208.Fa type 209argument. 210If 211.Fa type 212is 213.Dv V_ASN1_NULL , 214.Fa value 215is ignored. 216If 217.Fa type 218is 219.Dv V_ASN1_BOOLEAN , 220then the boolean is set to TRUE if 221.Fa value 222is not 223.Dv NULL . 224If 225.Fa type 226is 227.Dv V_ASN1_OBJECT , 228then 229.Fa value 230is an 231.Vt ASN1_OBJECT 232structure. 233Otherwise 234.Fa type 235is an 236.Vt ASN1_STRING 237structure. 238If 239.Fa type 240corresponds to a primitive type or a string type, then the contents 241of the 242.Vt ASN1_STRING 243contains the content octets of the type. 244If 245.Fa type 246corresponds to a constructed type or a tagged type 247.Pq Dv V_ASN1_SEQUENCE , V_ASN1_SET , No or Dv V_ASN1_OTHER , 248then the 249.Vt ASN1_STRING 250contains the entire ASN.1 encoding verbatim, including tag and 251length octets. 252.Pp 253.Fn ASN1_TYPE_set_octetstring 254allocates a new 255.Vt ASN1_OCTET_STRING 256object, copies 257.Fa len 258bytes of 259.Fa data 260into it using 261.Xr ASN1_STRING_set 3 , 262and replaces the value of 263.Fa a 264with it by calling 265.Fn ASN1_TYPE_set 266with a type of 267.Dv V_ASN1_OCTET_STRING . 268.Pp 269.Fn ASN1_TYPE_get_octetstring 270copies the contents of the 271.Vt ASN1_OCTET_STRING 272object contained in 273.Fa a , 274but not more than 275.Fa buflen 276bytes, into the 277.Fa buffer 278provided by the caller. 279.Pp 280.Fn ASN1_TYPE_set_int_octetstring 281frees the value contained in 282.Fa a , 283if any, sets its type to 284.Dv V_ASN1_SEQUENCE , 285and sets its value to a two-element ASN.1 sequence consisting of 286an ASN.1 INTEGER object with the value 287.Fa num 288and an ASN.1 OCTET STRING object 289containing a copy of the 290.Fa len 291bytes pointed to by 292.Fa data . 293.Pp 294.Fn ASN1_TYPE_get_int_octetstring 295copies the integer value from the first element of the ASN.1 sequence 296.Fa a 297to 298.Pf * Fa num 299unless 300.Fa num 301is a 302.Dv NULL 303pointer and copies the octet string value from the second element, 304but not more than 305.Fa buflen 306bytes, into the 307.Fa buffer 308provided by the caller unless 309.Fa buffer 310is a 311.Dv NULL 312pointer. 313.Pp 314.Fn ASN1_TYPE_cmp 315checks that 316.Fa a 317and 318.Fa b 319hold the same type, the same value, and are encoded in the same way. 320.Pp 321If the types agree and the values have the same meaning but are 322encoded differently, they are considered different. 323For example, a boolean value is represented 324using a single content octet. 325Under BER, any non-zero octet represents the TRUE value, but 326.Fn ASN1_TYPE_cmp 327will only report a match if the content octet is the same. 328.Pp 329If either or both of the arguments passed to 330.Fn ASN1_TYPE_cmp 331is 332.Dv NULL , 333the result is a mismatch. 334Technically, if both arguments are 335.Dv NULL , 336the two types could be absent OPTIONAL fields and so should match, 337however passing 338.Dv NULL 339values could also indicate a programming error (for example an 340unparsable type which returns 341.Dv NULL ) 342for types which do 343.Sy not 344match. 345So applications should handle the case of two absent values separately. 346.Sh RETURN VALUES 347.Fn ASN1_TYPE_new 348returns the new 349.Vt ASN1_TYPE 350object or 351.Dv NULL 352if an error occurs. 353.Pp 354.Fn ASN1_TYPE_get 355returns the type currently held by 356.Fa a 357or 0 if an error occurs. 358The latter can happen if 359.Fa a 360does not contain a value even though its type is not 361.Dv V_ASN1_NULL . 362For example, it will always happen for empty objects 363newly constructed with 364.Fn ASN1_TYPE_new . 365.Pp 366.Fn ASN1_TYPE_set1 , 367.Fn ASN1_TYPE_set_octetstring , 368and 369.Fn ASN1_TYPE_set_int_octetstring 370return 1 on success or 0 on failure. 371.Pp 372.Fn ASN1_TYPE_get_octetstring 373returns the number of data bytes contained in the 374.Vt ASN1_OCTET_STRING 375object contained in 376.Fa a 377or \-1 if 378.Fa a 379is not of the type 380.Dv V_ASN1_OCTET_STRING 381or does not contain any object. 382If the return value is greater than the 383.Fa buflen 384argument, the content was truncated when copied to the 385.Fa buffer . 386.Pp 387.Fn ASN1_TYPE_get_int_octetstring 388returns the number of data bytes contained in the 389.Vt ASN1_OCTET_STRING 390object that is the second element of the ASN.1 sequence 391.Fa a 392or \-1 if 393.Fa a 394is not of the type 395.Dv V_ASN1_SEQUENCE 396or if decoding fails. 397If the return value is greater than the 398.Fa buflen 399argument, the content was truncated when copied to the 400.Fa buffer . 401.Pp 402.Fn ASN1_TYPE_cmp 403returns 0 for a match or non-zero for a mismatch. 404.Sh SEE ALSO 405.Xr ASN1_generate_nconf 3 , 406.Xr ASN1_get_object 3 , 407.Xr ASN1_item_free 3 , 408.Xr ASN1_OBJECT_new 3 , 409.Xr ASN1_parse_dump 3 , 410.Xr ASN1_put_object 3 , 411.Xr ASN1_STRING_dup 3 , 412.Xr ASN1_STRING_new 3 , 413.Xr crypto 3 , 414.Xr d2i_ASN1_NULL 3 , 415.Xr d2i_ASN1_SEQUENCE_ANY 3 , 416.Xr d2i_ASN1_TYPE 3 , 417.Xr OBJ_dup 3 418.Sh HISTORY 419.Fn ASN1_TYPE_new 420and 421.Fn ASN1_TYPE_free 422first appeared in SSLeay 0.5.1, 423.Fn ASN1_TYPE_get 424and 425.Fn ASN1_TYPE_set 426in SSLeay 0.8.0, and 427.Fn ASN1_TYPE_set_octetstring , 428.Fn ASN1_TYPE_get_octetstring , 429.Fn ASN1_TYPE_set_int_octetstring , 430and 431.Fn ASN1_TYPE_get_int_octetstring 432in SSLeay 0.9.0. 433These functions have been available since 434.Ox 2.4 . 435.Pp 436.Fn ASN1_TYPE_set1 437first appeared in OpenSSL 0.9.8h and has been available since 438.Ox 4.5 . 439.Pp 440.Fn ASN1_TYPE_cmp 441first appeared in OpenSSL 0.9.8zd, 1.0.0p, and 1.0.1k 442and has been available since 443.Ox 4.9 . 444