1.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.5 2021/11/23 13:52:27 schwarze 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 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: November 23 2021 $ 70.Dt ASN1_INTEGER_GET 3 71.Os 72.Sh NAME 73.Nm ASN1_INTEGER_get , 74.Nm ASN1_INTEGER_set , 75.Nm ASN1_INTEGER_cmp , 76.Nm ASN1_INTEGER_dup , 77.Nm BN_to_ASN1_INTEGER , 78.Nm ASN1_INTEGER_to_BN , 79.Nm ASN1_ENUMERATED_get , 80.Nm ASN1_ENUMERATED_set , 81.Nm BN_to_ASN1_ENUMERATED , 82.Nm ASN1_ENUMERATED_to_BN 83.Nd ASN.1 INTEGER and ENUMERATED utilities 84.Sh SYNOPSIS 85.In openssl/asn1.h 86.Ft long 87.Fo ASN1_INTEGER_get 88.Fa "const ASN1_INTEGER *a" 89.Fc 90.Ft int 91.Fo ASN1_INTEGER_set 92.Fa "ASN1_INTEGER *a" 93.Fa "long v" 94.Fc 95.Ft int 96.Fo ASN1_INTEGER_cmp 97.Fa "const ASN1_INTEGER *a1" 98.Fa "const ASN1_INTEGER *a2" 99.Fc 100.Ft ASN1_INTEGER * 101.Fo ASN1_INTEGER_dup 102.Fa "const ASN1_INTEGER *a" 103.Fc 104.Ft ASN1_INTEGER * 105.Fo BN_to_ASN1_INTEGER 106.Fa "const BIGNUM *bn" 107.Fa "ASN1_INTEGER *ai" 108.Fc 109.Ft BIGNUM * 110.Fo ASN1_INTEGER_to_BN 111.Fa "const ASN1_INTEGER *ai" 112.Fa "BIGNUM *bn" 113.Fc 114.Ft long 115.Fo ASN1_ENUMERATED_get 116.Fa "const ASN1_ENUMERATED *a" 117.Fc 118.Ft int 119.Fo ASN1_ENUMERATED_set 120.Fa "ASN1_ENUMERATED *a" 121.Fa "long v" 122.Fc 123.Ft ASN1_ENUMERATED * 124.Fo BN_to_ASN1_ENUMERATED 125.Fa "const BIGNUM *bn" 126.Fa "ASN1_ENUMERATED *ai" 127.Fc 128.Ft BIGNUM * 129.Fo ASN1_ENUMERATED_to_BN 130.Fa "const ASN1_ENUMERATED *ai" 131.Fa "BIGNUM *bn" 132.Fc 133.Sh DESCRIPTION 134These functions convert to and from 135.Vt ASN1_INTEGER 136and 137.Vt ASN1_ENUMERATED 138objects. 139.Pp 140.Fn ASN1_INTEGER_get 141converts 142.Fa a 143to the 144.Vt long 145type. 146.Pp 147.Fn ASN1_INTEGER_set 148sets the type of 149.Fa a 150to 151.Dv V_ASN1_INTEGER 152or 153.Dv V_ASN1_NEG_INTEGER 154depending on the sign of 155.Fa v 156and sets the value of 157.Fa a 158to 159.Fa v . 160.Pp 161.Fn ASN1_INTEGER_cmp 162compares the signed integer numbers represented by 163.Fa a1 164and 165.Fa a2 . 166.Pp 167.Fn ASN1_INTEGER_dup 168does exactly the same as 169.Xr ASN1_STRING_dup 3 170without providing any type safety, 171except that it fails if the 172.Xr ASN1_STRING_length 3 173of 174.Fa a 175is 0. 176.Pp 177.Fn BN_to_ASN1_INTEGER 178converts 179.Fa bn 180to an 181.Vt ASN1_INTEGER . 182If 183.Fa ai 184is 185.Dv NULL , 186a new 187.Vt ASN1_INTEGER 188object is returned. 189Otherwise, the existing object 190.Fa ai 191is used instead. 192.Pp 193.Fn ASN1_INTEGER_to_BN 194converts 195.Fa ai 196into a 197.Vt BIGNUM . 198If 199.Fa bn 200is 201.Dv NULL , 202a new 203.Vt BIGNUM 204object is returned. 205Otherwise, the existing object 206.Fa bn 207is used instead. 208.Pp 209.Fn ASN1_ENUMERATED_get , 210.Fn ASN1_ENUMERATED_set , 211.Fn BN_to_ASN1_ENUMERATED , 212and 213.Fn ASN1_ENUMERATED_to_BN 214behave like their 215.Vt ASN1_INTEGER 216counterparts except that they operate on an 217.Vt ASN1_ENUMERATED 218object. 219.Sh RETURN VALUES 220.Fn ASN1_INTEGER_get 221and 222.Fn ASN1_ENUMERATED_get 223return the converted value, 0 if 224.Fa a 225is 226.Dv NULL , 227or \-1 on error, which is ambiguous because \-1 is a legitimate 228value for an 229.Vt ASN1_INTEGER . 230.Pp 231.Fn ASN1_INTEGER_set 232and 233.Fn ASN1_ENUMERATED_set 234return 1 for success or 0 for failure. 235They only fail if a memory allocation error occurs. 236.Pp 237.Fn ASN1_INTEGER_cmp 238returns a value greater than, equal to, or less than 0 239if the signed integer number represented by 240.Fa a1 241is greater than, equal to, or less than 242the signed integer number represented by 243.Fa a2 , 244respectively. 245.Pp 246.Fn ASN1_INTEGER_dup 247returns a pointer to a newly allocated 248.Vt ASN1_STRING 249structure or 250.Dv NULL 251if 252.Fa a 253is a 254.Dv NULL 255pointer, if the length of 256.Fa a 257is 0, or if memory allocation fails. 258.Pp 259.Fn BN_to_ASN1_INTEGER 260and 261.Fn BN_to_ASN1_ENUMERATED 262return an 263.Vt ASN1_INTEGER 264or 265.Vt ASN1_ENUMERATED 266object, respectively, or 267.Dv NULL 268if an error occurs. 269They only fail due to memory allocation errors. 270.Pp 271.Fn ASN1_INTEGER_to_BN 272and 273.Fn ASN1_ENUMERATED_to_BN 274return a 275.Vt BIGNUM 276object of 277.Dv NULL 278if an error occurs. 279They can fail if the passed type is incorrect (due to a programming error) 280or due to memory allocation failures. 281.Sh SEE ALSO 282.Xr ASN1_INTEGER_new 3 , 283.Xr ASN1_STRING_length 3 284.Sh HISTORY 285.Fn ASN1_INTEGER_set 286first appeared in SSLeay 0.5.1. 287.Fn ASN1_INTEGER_get , 288.Fn BN_to_ASN1_INTEGER , 289and 290.Fn ASN1_INTEGER_to_BN 291first appeared in SSLeay 0.6.0. 292.Fn ASN1_INTEGER_cmp 293and 294.Fn ASN1_INTEGER_dup 295first appeared in SSLeay 0.6.5. 296These functions have been available since 297.Ox 2.3 . 298.Pp 299.Fn ASN1_ENUMERATED_get , 300.Fn ASN1_ENUMERATED_set , 301.Fn BN_to_ASN1_ENUMERATED , 302and 303.Fn ASN1_ENUMERATED_to_BN 304first appeared in OpenSSL 0.9.2b and have been available since 305.Ox 2.6 . 306.Sh CAVEATS 307In general an 308.Vt ASN1_INTEGER 309or 310.Vt ASN1_ENUMERATED 311type can contain an integer of almost arbitrary size 312and so cannot always be represented by a C 313.Vt long 314type. 315The ambiguous return values of 316.Fn ASN1_INTEGER_get 317and 318.Fn ASN1_ENUMERATED_get 319imply that these functions should be avoided if possible. 320.Sh BUGS 321.Fn ASN1_INTEGER_cmp , 322.Fn ASN1_INTEGER_dup , 323and 324.Fn ASN1_INTEGER_to_BN 325do not check whether their arguments are really of the type 326.Dv V_ASN1_INTEGER 327or 328.Dv V_ASN1_NEG_INTEGER . 329They may report success even if their arguments are of a wrong type. 330Consequently, even in case of success, the return value of 331.Fn ASN1_INTEGER_dup 332is not guaranteed to be of the type 333.Dv V_ASN1_INTEGER 334or 335.Dv V_ASN1_NEG_INTEGER 336either. 337.Pp 338Similarly, 339.Fn ASN1_ENUMERATED_to_BN 340does not check whether its argument is really of the type 341.Dv V_ASN1_ENUMERATED 342or 343.Dv V_ASN1_NEG_ENUMERATED 344and may report success even if the argument is of a wrong type. 345