1.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.7 2023/05/22 19:38:04 tb Exp $ 2.\" selective merge up to: 3.\" OpenSSL man3/ASN1_INTEGER_get_int64 24a535ea Sep 22 13:14:20 2020 +0100 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2018, 2021, 2022 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2015 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: May 22 2023 $ 70.Dt ASN1_INTEGER_GET 3 71.Os 72.Sh NAME 73.Nm ASN1_INTEGER_get_uint64 , 74.Nm ASN1_INTEGER_get_int64 , 75.Nm ASN1_INTEGER_get , 76.Nm ASN1_INTEGER_set_uint64 , 77.Nm ASN1_INTEGER_set_int64 , 78.Nm ASN1_INTEGER_set , 79.Nm ASN1_INTEGER_cmp , 80.Nm ASN1_INTEGER_dup , 81.Nm BN_to_ASN1_INTEGER , 82.Nm ASN1_INTEGER_to_BN , 83.Nm ASN1_ENUMERATED_get_int64 , 84.Nm ASN1_ENUMERATED_get , 85.Nm ASN1_ENUMERATED_set_int64 , 86.Nm ASN1_ENUMERATED_set , 87.Nm BN_to_ASN1_ENUMERATED , 88.Nm ASN1_ENUMERATED_to_BN 89.Nd ASN.1 INTEGER and ENUMERATED utilities 90.Sh SYNOPSIS 91.In openssl/asn1.h 92.Ft int 93.Fo ASN1_INTEGER_get_uint64 94.Fa "uint64_t *out_val" 95.Fa "const ASN1_INTEGER *a" 96.Fc 97.Ft int 98.Fo ASN1_INTEGER_get_int64 99.Fa "int64_t *out_val" 100.Fa "const ASN1_INTEGER *a" 101.Fc 102.Ft long 103.Fo ASN1_INTEGER_get 104.Fa "const ASN1_INTEGER *a" 105.Fc 106.Ft int 107.Fo ASN1_INTEGER_set_uint64 108.Fa "ASN1_INTEGER *a" 109.Fa "uint64_t v" 110.Fc 111.Ft int 112.Fo ASN1_INTEGER_set_int64 113.Fa "ASN1_INTEGER *a" 114.Fa "int64_t v" 115.Fc 116.Ft int 117.Fo ASN1_INTEGER_set 118.Fa "ASN1_INTEGER *a" 119.Fa "long v" 120.Fc 121.Ft int 122.Fo ASN1_INTEGER_cmp 123.Fa "const ASN1_INTEGER *a1" 124.Fa "const ASN1_INTEGER *a2" 125.Fc 126.Ft ASN1_INTEGER * 127.Fo ASN1_INTEGER_dup 128.Fa "const ASN1_INTEGER *a" 129.Fc 130.Ft ASN1_INTEGER * 131.Fo BN_to_ASN1_INTEGER 132.Fa "const BIGNUM *bn" 133.Fa "ASN1_INTEGER *ai" 134.Fc 135.Ft BIGNUM * 136.Fo ASN1_INTEGER_to_BN 137.Fa "const ASN1_INTEGER *ai" 138.Fa "BIGNUM *bn" 139.Fc 140.Ft int 141.Fo ASN1_ENUMERATED_get_int64 142.Fa "int64_t *out_val" 143.Fa "const ASN1_ENUMERATED *a" 144.Fc 145.Ft long 146.Fo ASN1_ENUMERATED_get 147.Fa "const ASN1_ENUMERATED *a" 148.Fc 149.Ft int 150.Fo ASN1_ENUMERATED_set_int64 151.Fa "ASN1_ENUMERATED *a" 152.Fa "int64_t v" 153.Fc 154.Ft int 155.Fo ASN1_ENUMERATED_set 156.Fa "ASN1_ENUMERATED *a" 157.Fa "long v" 158.Fc 159.Ft ASN1_ENUMERATED * 160.Fo BN_to_ASN1_ENUMERATED 161.Fa "const BIGNUM *bn" 162.Fa "ASN1_ENUMERATED *ai" 163.Fc 164.Ft BIGNUM * 165.Fo ASN1_ENUMERATED_to_BN 166.Fa "const ASN1_ENUMERATED *ai" 167.Fa "BIGNUM *bn" 168.Fc 169.Sh DESCRIPTION 170These functions convert to and from 171.Vt ASN1_INTEGER 172and 173.Vt ASN1_ENUMERATED 174objects. 175.Pp 176.Fn ASN1_INTEGER_get_uint64 177and 178.Fn ASN1_INTEGER_get_int64 179store the value of 180.Fa a 181in 182.Pf * Fa out_val 183if successful. 184.Pp 185The deprecated function 186.Fn ASN1_INTEGER_get 187converts 188.Fa a 189to the 190.Vt long 191type. 192.Pp 193.Fn ASN1_INTEGER_set_uint64 , 194.Fn ASN1_INTEGER_set_int64 , 195and 196.Fn ASN1_INTEGER_set 197set the type of 198.Fa a 199to 200.Dv V_ASN1_INTEGER 201or 202.Dv V_ASN1_NEG_INTEGER 203depending on the sign of 204.Fa v 205and set the value of 206.Fa a 207to 208.Fa v . 209.Pp 210.Fn ASN1_INTEGER_cmp 211compares the signed integer numbers represented by 212.Fa a1 213and 214.Fa a2 . 215.Pp 216.Fn ASN1_INTEGER_dup 217does exactly the same as 218.Xr ASN1_STRING_dup 3 219without providing any type safety, 220except that it fails if the 221.Xr ASN1_STRING_length 3 222of 223.Fa a 224is 0. 225.Pp 226.Fn BN_to_ASN1_INTEGER 227converts 228.Fa bn 229to an 230.Vt ASN1_INTEGER . 231If 232.Fa ai 233is 234.Dv NULL , 235a new 236.Vt ASN1_INTEGER 237object is returned. 238Otherwise, the existing object 239.Fa ai 240is used instead. 241.Pp 242.Fn ASN1_INTEGER_to_BN 243converts 244.Fa ai 245into a 246.Vt BIGNUM . 247If 248.Fa bn 249is 250.Dv NULL , 251a new 252.Vt BIGNUM 253object is returned. 254Otherwise, the existing object 255.Fa bn 256is used instead. 257.Pp 258.Fn ASN1_ENUMERATED_get_int64 , 259.Fn ASN1_ENUMERATED_get , 260.Fn ASN1_ENUMERATED_set_int64 , 261.Fn ASN1_ENUMERATED_set , 262.Fn BN_to_ASN1_ENUMERATED , 263and 264.Fn ASN1_ENUMERATED_to_BN 265behave like their 266.Vt ASN1_INTEGER 267counterparts except that they operate on an 268.Vt ASN1_ENUMERATED 269object. 270.Sh RETURN VALUES 271.Fn ASN1_INTEGER_get_uint64 272returns 1 in case of success or 0 if 273.Fa a 274is not of the type 275.Dv V_ASN1_INTEGER 276or greater than 277.Dv UINT64_MAX . 278.Pp 279.Fn ASN1_INTEGER_get_int64 280returns 1 in case of success or 0 if 281.Fa a 282is not of the type 283.Dv V_ASN1_INTEGER 284or 285.Dv V_ASN1_NEG_INTEGER , 286less than 287.Dv INT64_MIN , 288or greater than 289.Dv INT64_MAX . 290.Pp 291.Fn ASN1_INTEGER_get 292and 293.Fn ASN1_ENUMERATED_get 294return the converted value, 0 if 295.Fa a 296is 297.Dv NULL , 298or \-1 on error, which is ambiguous because \-1 is a legitimate 299value for an 300.Vt ASN1_INTEGER . 301.Pp 302.Fn ASN1_INTEGER_set_uint64 , 303.Fn ASN1_INTEGER_set_int64 , 304.Fn ASN1_INTEGER_set , 305.Fn ASN1_ENUMERATED_set_int64 , 306and 307.Fn ASN1_ENUMERATED_set 308return 1 for success or 0 for failure. 309They only fail if a memory allocation error occurs. 310.Pp 311.Fn ASN1_INTEGER_cmp 312returns a value greater than, equal to, or less than 0 313if the signed integer number represented by 314.Fa a1 315is greater than, equal to, or less than 316the signed integer number represented by 317.Fa a2 , 318respectively. 319.Pp 320.Fn ASN1_INTEGER_dup 321returns a pointer to a newly allocated 322.Vt ASN1_STRING 323structure or 324.Dv NULL 325if 326.Fa a 327is a 328.Dv NULL 329pointer, if the length of 330.Fa a 331is 0, or if memory allocation fails. 332.Pp 333.Fn BN_to_ASN1_INTEGER 334and 335.Fn BN_to_ASN1_ENUMERATED 336return an 337.Vt ASN1_INTEGER 338or 339.Vt ASN1_ENUMERATED 340object, respectively, or 341.Dv NULL 342if an error occurs. 343They only fail due to memory allocation errors. 344.Pp 345.Fn ASN1_INTEGER_to_BN 346and 347.Fn ASN1_ENUMERATED_to_BN 348return a 349.Vt BIGNUM 350object of 351.Dv NULL 352if an error occurs. 353They can fail if the passed type is incorrect (due to a programming error) 354or due to memory allocation failures. 355.Sh SEE ALSO 356.Xr ASN1_INTEGER_new 3 , 357.Xr ASN1_STRING_length 3 358.Sh HISTORY 359.Fn ASN1_INTEGER_set 360first appeared in SSLeay 0.5.1. 361.Fn ASN1_INTEGER_get , 362.Fn BN_to_ASN1_INTEGER , 363and 364.Fn ASN1_INTEGER_to_BN 365first appeared in SSLeay 0.6.0. 366.Fn ASN1_INTEGER_cmp 367and 368.Fn ASN1_INTEGER_dup 369first appeared in SSLeay 0.6.5. 370These functions have been available since 371.Ox 2.3 . 372.Pp 373.Fn ASN1_ENUMERATED_get , 374.Fn ASN1_ENUMERATED_set , 375.Fn BN_to_ASN1_ENUMERATED , 376and 377.Fn ASN1_ENUMERATED_to_BN 378first appeared in OpenSSL 0.9.2b and have been available since 379.Ox 2.6 . 380.Pp 381.Fn ASN1_INTEGER_get_uint64 , 382.Fn ASN1_INTEGER_get_int64 , 383.Fn ASN1_INTEGER_set_uint64 , 384.Fn ASN1_INTEGER_set_int64 , 385.Fn ASN1_ENUMERATED_get_int64 , 386and 387.Fn ASN1_ENUMERATED_set_int64 388first appeared in OpenSSL 1.1.0 and have been available since 389.Ox 7.2 . 390.Sh CAVEATS 391In general an 392.Vt ASN1_INTEGER 393or 394.Vt ASN1_ENUMERATED 395type can contain an integer of almost arbitrary size 396and so cannot always be represented by a C 397.Vt long 398type. 399The ambiguous return values of 400.Fn ASN1_INTEGER_get 401and 402.Fn ASN1_ENUMERATED_get 403imply that these functions should be avoided if possible. 404.Sh BUGS 405.Fn ASN1_INTEGER_cmp , 406.Fn ASN1_INTEGER_dup , 407and 408.Fn ASN1_INTEGER_to_BN 409do not check whether their arguments are really of the type 410.Dv V_ASN1_INTEGER 411or 412.Dv V_ASN1_NEG_INTEGER . 413They may report success even if their arguments are of a wrong type. 414Consequently, even in case of success, the return value of 415.Fn ASN1_INTEGER_dup 416is not guaranteed to be of the type 417.Dv V_ASN1_INTEGER 418or 419.Dv V_ASN1_NEG_INTEGER 420either. 421.Pp 422Similarly, 423.Fn ASN1_ENUMERATED_to_BN 424does not check whether its argument is really of the type 425.Dv V_ASN1_ENUMERATED 426or 427.Dv V_ASN1_NEG_ENUMERATED 428and may report success even if the argument is of a wrong type. 429