1.\" $OpenBSD: ASN1_INTEGER_get.3,v 1.3 2019/08/26 12:45:27 schwarze Exp $ 2.\" selective merge up to: 3.\" OpenSSL man3/ASN1_INTEGER_get_int64 df75c2bf Dec 9 01:02:36 2018 +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, 2019 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: August 26 2019 $ 70.Dt ASN1_INTEGER_GET 3 71.Os 72.Sh NAME 73.Nm ASN1_INTEGER_get , 74.Nm ASN1_INTEGER_set , 75.Nm BN_to_ASN1_INTEGER , 76.Nm ASN1_INTEGER_to_BN , 77.Nm i2a_ASN1_INTEGER , 78.Nm ASN1_ENUMERATED_get , 79.Nm ASN1_ENUMERATED_set , 80.Nm BN_to_ASN1_ENUMERATED , 81.Nm ASN1_ENUMERATED_to_BN 82.Nd ASN.1 INTEGER and ENUMERATED utilities 83.Sh SYNOPSIS 84.In openssl/asn1.h 85.Ft long 86.Fo ASN1_INTEGER_get 87.Fa "const ASN1_INTEGER *a" 88.Fc 89.Ft int 90.Fo ASN1_INTEGER_set 91.Fa "ASN1_INTEGER *a" 92.Fa "long v" 93.Fc 94.Ft ASN1_INTEGER * 95.Fo BN_to_ASN1_INTEGER 96.Fa "const BIGNUM *bn" 97.Fa "ASN1_INTEGER *ai" 98.Fc 99.Ft BIGNUM * 100.Fo ASN1_INTEGER_to_BN 101.Fa "const ASN1_INTEGER *ai" 102.Fa "BIGNUM *bn" 103.Fc 104.Ft int 105.Fo i2a_ASN1_INTEGER 106.Fa "BIO *out_bio" 107.Fa "const ASN1_INTEGER *a" 108.Fc 109.Ft long 110.Fo ASN1_ENUMERATED_get 111.Fa "const ASN1_ENUMERATED *a" 112.Fc 113.Ft int 114.Fo ASN1_ENUMERATED_set 115.Fa "ASN1_ENUMERATED *a" 116.Fa "long v" 117.Fc 118.Ft ASN1_ENUMERATED * 119.Fo BN_to_ASN1_ENUMERATED 120.Fa "const BIGNUM *bn" 121.Fa "ASN1_ENUMERATED *ai" 122.Fc 123.Ft BIGNUM * 124.Fo ASN1_ENUMERATED_to_BN 125.Fa "const ASN1_ENUMERATED *ai" 126.Fa "BIGNUM *bn" 127.Fc 128.Sh DESCRIPTION 129These functions convert to and from 130.Vt ASN1_INTEGER 131and 132.Vt ASN1_ENUMERATED 133objects. 134.Pp 135.Fn ASN1_INTEGER_get 136converts 137.Fa a 138to the 139.Vt long 140type. 141.Pp 142.Fn ASN1_INTEGER_set 143sets the value of 144.Fa a 145to 146.Fa v . 147.Pp 148.Fn BN_to_ASN1_INTEGER 149converts 150.Fa bn 151to an 152.Vt ASN1_INTEGER . 153If 154.Fa ai 155is 156.Dv NULL , 157a new 158.Vt ASN1_INTEGER 159object is returned. 160Otherwise, the existing object 161.Fa ai 162is used instead. 163.Pp 164.Fn ASN1_INTEGER_to_BN 165converts 166.Fa ai 167into a 168.Vt BIGNUM . 169If 170.Fa bn 171is 172.Dv NULL , 173a new 174.Vt BIGNUM 175object is returned. 176Otherwise, the existing object 177.Fa bn 178is used instead. 179.Pp 180.Fn i2a_ASN1_INTEGER 181writes a hexadecimal representation of 182.Fa a 183to 184.Fa out_bio . 185The output optionally starts with a minus sign, 186followed by an even number of upper case ASCII hexadecimal digits. 187After each group of 70 digits, a backslash and a linefeed 188are inserted before the next digit. 189.Pp 190.Fn ASN1_ENUMERATED_get , 191.Fn ASN1_ENUMERATED_set , 192.Fn BN_to_ASN1_ENUMERATED , 193and 194.Fn ASN1_ENUMERATED_to_BN 195behave like their 196.Vt ASN1_INTEGER 197counterparts except that they operate on an 198.Vt ASN1_ENUMERATED 199object. 200.Sh RETURN VALUES 201.Fn ASN1_INTEGER_get 202and 203.Fn ASN1_ENUMERATED_get 204return the converted value, 0 if 205.Fa a 206is 207.Dv NULL , 208or \-1 on error, which is ambiguous because \-1 is a legitimate 209value for an 210.Vt ASN1_INTEGER . 211.Pp 212.Fn ASN1_INTEGER_set 213and 214.Fn ASN1_ENUMERATED_set 215return 1 for success or 0 for failure. 216They only fail if a memory allocation error occurs. 217.Pp 218.Fn BN_to_ASN1_INTEGER 219and 220.Fn BN_to_ASN1_ENUMERATED 221return an 222.Vt ASN1_INTEGER 223or 224.Vt ASN1_ENUMERATED 225object, respectively, or 226.Dv NULL 227if an error occurs. 228They only fail due to memory allocation errors. 229.Pp 230.Fn ASN1_INTEGER_to_BN 231and 232.Fn ASN1_ENUMERATED_to_BN 233return a 234.Vt BIGNUM 235object of 236.Dv NULL 237if an error occurs. 238They can fail if the passed type is incorrect (due to a programming error) 239or due to memory allocation failures. 240.Pp 241In case of success, 242.Fn i2a_ASN1_INTEGER 243returns the total number of bytes written, which is at least 2. 244It returns 0 if 245.Fa a 246is 247.Dv NULL 248or -1 if 249.Xr BIO_write 3 250fails. 251.Sh SEE ALSO 252.Xr ASN1_INTEGER_new 3 253.Sh HISTORY 254.Fn ASN1_INTEGER_set 255first appeared in SSLeay 0.5.1. 256.Fn ASN1_INTEGER_get , 257.Fn BN_to_ASN1_INTEGER , 258.Fn ASN1_INTEGER_to_BN , 259and 260.Fn i2a_ASN1_INTEGER 261first appeared in SSLeay 0.6.0. 262These functions have been available since 263.Ox 2.3 . 264.Pp 265.Fn ASN1_ENUMERATED_get , 266.Fn ASN1_ENUMERATED_set , 267.Fn BN_to_ASN1_ENUMERATED , 268and 269.Fn ASN1_ENUMERATED_to_BN 270first appeared in OpenSSL 0.9.2b and have been available since 271.Ox 2.6 . 272.Sh CAVEATS 273In general an 274.Vt ASN1_INTEGER 275or 276.Vt ASN1_ENUMERATED 277type can contain an integer of almost arbitrary size 278and so cannot always be represented by a C 279.Vt long 280type. 281The ambiguous return values of 282.Fn ASN1_INTEGER_get 283and 284.Fn ASN1_ENUMERATED_get 285imply that these functions should be avoided if possible. 286