1.\" $OpenBSD: BN_bn2bin.3,v 1.16 2023/07/09 06:45:03 tb Exp $ 2.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 3.\" 4.\" This file was written by Ulf Moeller <ulf@openssl.org> 5.\" and Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2000, 2002, 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: July 9 2023 $ 53.Dt BN_BN2BIN 3 54.Os 55.Sh NAME 56.Nm BN_bn2bin , 57.Nm BN_bn2binpad , 58.Nm BN_bin2bn , 59.Nm BN_bn2lebinpad , 60.Nm BN_lebin2bn , 61.Nm BN_bn2hex , 62.Nm BN_bn2dec , 63.Nm BN_hex2bn , 64.Nm BN_dec2bn , 65.Nm BN_asc2bn , 66.Nm BN_print , 67.Nm BN_print_fp , 68.Nm BN_bn2mpi , 69.Nm BN_mpi2bn 70.Nd format conversions 71.Sh SYNOPSIS 72.In openssl/bn.h 73.Ft int 74.Fo BN_bn2bin 75.Fa "const BIGNUM *a" 76.Fa "unsigned char *to" 77.Fc 78.Ft int 79.Fo BN_bn2binpad 80.Fa "const BIGNUM *a" 81.Fa "unsigned char *to" 82.Fa "int tolen" 83.Fc 84.Ft BIGNUM * 85.Fo BN_bin2bn 86.Fa "const unsigned char *s" 87.Fa "int len" 88.Fa "BIGNUM *ret" 89.Fc 90.Ft int 91.Fo BN_bn2lebinpad 92.Fa "const BIGNUM *a" 93.Fa "unsigned char *to" 94.Fa "int tolen" 95.Fc 96.Ft BIGNUM * 97.Fo BN_lebin2bn 98.Fa "const unsigned char *s" 99.Fa "int len" 100.Fa "BIGNUM *ret" 101.Fc 102.Ft char * 103.Fo BN_bn2hex 104.Fa "const BIGNUM *a" 105.Fc 106.Ft char * 107.Fo BN_bn2dec 108.Fa "const BIGNUM *a" 109.Fc 110.Ft int 111.Fo BN_hex2bn 112.Fa "BIGNUM **ap" 113.Fa "const char *str" 114.Fc 115.Ft int 116.Fo BN_dec2bn 117.Fa "BIGNUM **ap" 118.Fa "const char *str" 119.Fc 120.Ft int 121.Fo BN_asc2bn 122.Fa "BIGNUM **ap" 123.Fa "const char *str" 124.Fc 125.Ft int 126.Fo BN_print 127.Fa "BIO *fp" 128.Fa "const BIGNUM *a" 129.Fc 130.Ft int 131.Fo BN_print_fp 132.Fa "FILE *fp" 133.Fa "const BIGNUM *a" 134.Fc 135.Ft int 136.Fo BN_bn2mpi 137.Fa "const BIGNUM *a" 138.Fa "unsigned char *to" 139.Fc 140.Ft BIGNUM * 141.Fo BN_mpi2bn 142.Fa "unsigned char *s" 143.Fa "int len" 144.Fa "BIGNUM *ret" 145.Fc 146.Sh DESCRIPTION 147.Fn BN_bn2bin 148converts the absolute value of 149.Fa a 150into big-endian form and stores it at 151.Fa to . 152.Fa to 153must point to 154.Fn BN_num_bytes a 155bytes of memory. 156.Pp 157.Fn BN_bn2binpad 158also converts the absolute value of 159.Fa a 160into big-endian form and stores it at 161.Fa to . 162.Fa tolen 163indicates the length of the output buffer 164.Pf * Fa to . 165The result is padded with zeros if necessary. 166If 167.Fa tolen 168is less than 169.Fn BN_num_bytes a , 170an error is returned. 171.Pp 172.Fn BN_bin2bn 173converts the positive integer in big-endian form of length 174.Fa len 175at 176.Fa s 177into a 178.Vt BIGNUM 179and places it in 180.Fa ret . 181If 182.Fa ret 183is 184.Dv NULL , 185a new 186.Vt BIGNUM 187is created. 188.Pp 189.Fn BN_bn2lebinpad 190and 191.Fn BN_lebin2bn 192are identical to 193.Fn BN_bn2binpad 194and 195.Fn BN_bin2bn 196except the buffer 197.Pf * Fa to 198is in little-endian format. 199.Pp 200.Fn BN_bn2hex 201and 202.Fn BN_bn2dec 203return printable strings containing the hexadecimal and decimal encoding of 204.Fa a 205respectively. 206For negative numbers, the string is prefaced with a leading minus sign. 207The string must be freed later using 208.Xr free 3 . 209.Pp 210.Fn BN_hex2bn 211interprets 212.Fa str 213as a hexadecimal number. 214The string may start with a minus sign 215.Pq Sq - . 216Conversion stops at the first byte that is not a hexadecimal digit. 217The number is converted to a 218.Vt BIGNUM 219and stored in 220.Pf ** Fa ap . 221If 222.Pf * Fa ap 223is 224.Dv NULL , 225a new 226.Vt BIGNUM 227is created. 228If 229.Fa ap 230is 231.Dv NULL , 232it only computes the number's length in hexadecimal digits, 233also counting the leading minus sign if there is one. 234A "negative zero" is converted to zero. 235.Fn BN_dec2bn 236is the same using the decimal system. 237.Fn BN_asc2bn 238infers the number base from an optional prefix. 239If 240.Fa str 241starts with 242.Qq 0x 243or 244.Qq 0X , 245it calls 246.Fn BN_hex2bn , 247otherwise 248.Fn BN_dec2bn . 249If the number is negative, the minus sign can be given before or 250after the prefix. 251.Pp 252.Fn BN_print 253and 254.Fn BN_print_fp 255write the hexadecimal encoding of 256.Fa a , 257with a leading minus sign for negative numbers, to the 258.Vt BIO 259or 260.Vt FILE 261.Fa fp . 262.Pp 263.Fn BN_bn2mpi 264and 265.Fn BN_mpi2bn 266convert 267.Vt BIGNUM Ns s 268from and to a format that consists of the number's length in bytes 269represented as a 4-byte big-endian number, and the number itself in 270big-endian format, where the most significant bit signals a negative 271number (the representation of numbers with the MSB set is prefixed with 272a NUL byte). 273.Pp 274.Fn BN_bn2mpi 275stores the representation of 276.Fa a 277at 278.Fa to , 279where 280.Pf * Fa to 281must be large enough to hold the result. 282The size can be determined by calling 283.Fn BN_bn2mpi a NULL . 284.Pp 285.Fn BN_mpi2bn 286converts the 287.Fa len 288bytes long representation at 289.Fa s 290to a 291.Vt BIGNUM 292and stores it at 293.Fa ret , 294or in a newly allocated 295.Vt BIGNUM 296if 297.Fa ret 298is 299.Dv NULL . 300.Sh RETURN VALUES 301.Fn BN_bn2bin 302returns the length of the big-endian number placed at 303.Fa to . 304.Pp 305.Fn BN_bn2binpad 306and 307.Fn BN_bn2lebinpad 308return the number of bytes written 309or \-1 if the supplied buffer is too small. 310.Pp 311.Fn BN_bin2bn 312and 313.Fn BN_lebin2bn 314return the 315.Vt BIGNUM , 316or 317.Dv NULL 318on error. 319.Pp 320.Fn BN_bn2hex 321and 322.Fn BN_bn2dec 323return a NUL-terminated string, or 324.Dv NULL 325on error. 326.Fn BN_hex2bn 327and 328.Fn BN_dec2bn 329return the number's length in hexadecimal or decimal digits, 330also counting the leading minus sign if there is one, 331or 0 on error, in which case no new 332.Vt BIGNUM 333is created. 334.Fn BN_asc2bn 335returns 1 on success or 0 on error, in which case no new 336.Vt BIGNUM 337is created. 338.Pp 339.Fn BN_print_fp 340and 341.Fn BN_print 342return 1 on success, 0 on write errors. 343.Pp 344.Fn BN_bn2mpi 345returns the length of the representation. 346.Fn BN_mpi2bn 347returns the 348.Vt BIGNUM , 349or 350.Dv NULL 351on error. 352.Pp 353The error codes can be obtained by 354.Xr ERR_get_error 3 . 355.Sh SEE ALSO 356.Xr ASN1_INTEGER_to_BN 3 , 357.Xr BN_new 3 , 358.Xr BN_num_bytes 3 , 359.Xr BN_zero 3 360.Sh HISTORY 361.Fn BN_bn2bin , 362.Fn BN_bin2bn , 363and 364.Fn BN_print 365first appeared in SSLeay 0.5.1. 366.Fn BN_print_fp 367first appeared in SSLeay 0.6.0. 368.Fn BN_bn2hex , 369.Fn BN_bn2dec , 370.Fn BN_hex2bn , 371.Fn BN_dec2bn , 372.Fn BN_bn2mpi , 373and 374.Fn BN_mpi2bn 375first appeared in SSLeay 0.9.0. 376All these functions have been available since 377.Ox 2.4 . 378.Pp 379.Fn BN_asc2bin 380first appeared in OpenSSL 1.0.0 and has been available since 381.Ox 4.9 . 382.Pp 383.Fn BN_bn2binpad , 384.Fn BN_bn2lebinpad , 385and 386.Fn BN_lebin2bn 387first appeared in OpenSSL 1.1.0 and have been available since 388.Ox 7.0 . 389