1.\" $OpenBSD: BN_bn2bin.3,v 1.13 2019/06/10 14:58:48 schwarze Exp $ 2.\" full merge up to: OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400 3.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100 4.\" 5.\" This file was written by Ulf Moeller <ulf@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: June 10 2019 $ 53.Dt BN_BN2BIN 3 54.Os 55.Sh NAME 56.Nm BN_bn2bin , 57.Nm BN_bin2bn , 58.Nm BN_bn2hex , 59.Nm BN_bn2dec , 60.Nm BN_hex2bn , 61.Nm BN_dec2bn , 62.Nm BN_asc2bn , 63.Nm BN_print , 64.Nm BN_print_fp , 65.Nm BN_bn2mpi , 66.Nm BN_mpi2bn 67.Nd format conversions 68.Sh SYNOPSIS 69.In openssl/bn.h 70.Ft int 71.Fo BN_bn2bin 72.Fa "const BIGNUM *a" 73.Fa "unsigned char *to" 74.Fc 75.Ft BIGNUM * 76.Fo BN_bin2bn 77.Fa "const unsigned char *s" 78.Fa "int len" 79.Fa "BIGNUM *ret" 80.Fc 81.Ft char * 82.Fo BN_bn2hex 83.Fa "const BIGNUM *a" 84.Fc 85.Ft char * 86.Fo BN_bn2dec 87.Fa "const BIGNUM *a" 88.Fc 89.Ft int 90.Fo BN_hex2bn 91.Fa "BIGNUM **a" 92.Fa "const char *str" 93.Fc 94.Ft int 95.Fo BN_dec2bn 96.Fa "BIGNUM **a" 97.Fa "const char *str" 98.Fc 99.Ft int 100.Fo BN_asc2bn 101.Fa "BIGNUM **a" 102.Fa "const char *str" 103.Fc 104.Ft int 105.Fo BN_print 106.Fa "BIO *fp" 107.Fa "const BIGNUM *a" 108.Fc 109.Ft int 110.Fo BN_print_fp 111.Fa "FILE *fp" 112.Fa "const BIGNUM *a" 113.Fc 114.Ft int 115.Fo BN_bn2mpi 116.Fa "const BIGNUM *a" 117.Fa "unsigned char *to" 118.Fc 119.Ft BIGNUM * 120.Fo BN_mpi2bn 121.Fa "unsigned char *s" 122.Fa "int len" 123.Fa "BIGNUM *ret" 124.Fc 125.Sh DESCRIPTION 126.Fn BN_bn2bin 127converts the absolute value of 128.Fa a 129into big-endian form and stores it at 130.Fa to . 131.Fa to 132must point to 133.Fn BN_num_bytes a 134bytes of memory. 135.Pp 136.Fn BN_bin2bn 137converts the positive integer in big-endian form of length 138.Fa len 139at 140.Fa s 141into a 142.Vt BIGNUM 143and places it in 144.Fa ret . 145If 146.Fa ret 147is 148.Dv NULL , 149a new 150.Vt BIGNUM 151is created. 152.Pp 153.Fn BN_bn2hex 154and 155.Fn BN_bn2dec 156return printable strings containing the hexadecimal and decimal encoding of 157.Fa a 158respectively. 159For negative numbers, the string is prefaced with a leading minus sign. 160The string must be freed later using 161.Xr free 3 . 162.Pp 163.Fn BN_hex2bn 164interprets 165.Fa str 166as a hexadecimal number. 167The string may start with a minus sign 168.Pq Sq - . 169Conversion stops at the first byte that is not a hexadecimal digit. 170The number is converted to a 171.Vt BIGNUM 172and stored in 173.Pf * Fa a . 174If 175.Pf * Fa a 176is 177.Dv NULL , 178a new 179.Vt BIGNUM 180is created. 181If 182.Fa a 183is 184.Dv NULL , 185it only computes the number's length in hexadecimal digits, 186also counting the leading minus sign if there is one. 187A "negative zero" is converted to zero. 188.Fn BN_dec2bn 189is the same using the decimal system. 190.Fn BN_asc2bn 191infers the number base from an optional prefix. 192If 193.Fa str 194starts with 195.Qq 0x 196or 197.Qq 0X , 198it calls 199.Fn BN_hex2bn , 200otherwise 201.Fn BN_dec2bn . 202If the number is negative, the minus sign can be given before or 203after the prefix. 204.Pp 205.Fn BN_print 206and 207.Fn BN_print_fp 208write the hexadecimal encoding of 209.Fa a , 210with a leading minus sign for negative numbers, to the 211.Vt BIO 212or 213.Vt FILE 214.Fa fp . 215.Pp 216.Fn BN_bn2mpi 217and 218.Fn BN_mpi2bn 219convert 220.Vt BIGNUM Ns s 221from and to a format that consists of the number's length in bytes 222represented as a 4-byte big-endian number, and the number itself in 223big-endian format, where the most significant bit signals a negative 224number (the representation of numbers with the MSB set is prefixed with 225a NUL byte). 226.Pp 227.Fn BN_bn2mpi 228stores the representation of 229.Fa a 230at 231.Fa to , 232where 233.Fa to 234must be large enough to hold the result. 235The size can be determined by calling 236.Fn BN_bn2mpi a NULL . 237.Pp 238.Fn BN_mpi2bn 239converts the 240.Fa len 241bytes long representation at 242.Fa s 243to a 244.Vt BIGNUM 245and stores it at 246.Fa ret , 247or in a newly allocated 248.Vt BIGNUM 249if 250.Fa ret 251is 252.Dv NULL . 253.Sh RETURN VALUES 254.Fn BN_bn2bin 255returns the length of the big-endian number placed at 256.Fa to . 257.Fn BN_bin2bn 258returns the 259.Vt BIGNUM , 260or 261.Dv NULL 262on error. 263.Pp 264.Fn BN_bn2hex 265and 266.Fn BN_bn2dec 267return a NUL-terminated string, or 268.Dv NULL 269on error. 270.Fn BN_hex2bn 271and 272.Fn BN_dec2bn 273return the number's length in hexadecimal or decimal digits, 274also counting the leading minus sign if there is one, 275or 0 on error, in which case no new 276.Vt BIGNUM 277is created. 278.Fn BN_asc2bn 279returns 1 on success or 0 on error, in which case no new 280.Vt BIGNUM 281is created. 282.Pp 283.Fn BN_print_fp 284and 285.Fn BN_print 286return 1 on success, 0 on write errors. 287.Pp 288.Fn BN_bn2mpi 289returns the length of the representation. 290.Fn BN_mpi2bn 291returns the 292.Vt BIGNUM , 293or 294.Dv NULL 295on error. 296.Pp 297The error codes can be obtained by 298.Xr ERR_get_error 3 . 299.Sh SEE ALSO 300.Xr BN_new 3 , 301.Xr BN_num_bytes 3 , 302.Xr BN_zero 3 303.Sh HISTORY 304.Fn BN_bn2bin , 305.Fn BN_bin2bn , 306and 307.Fn BN_print 308first appeared in SSLeay 0.5.1. 309.Fn BN_print_fp 310first appeared in SSLeay 0.6.0. 311.Fn BN_bn2hex , 312.Fn BN_bn2dec , 313.Fn BN_hex2bn , 314.Fn BN_dec2bn , 315.Fn BN_bn2mpi , 316and 317.Fn BN_mpi2bn 318first appeared in SSLeay 0.9.0. 319All these functions have been available since 320.Ox 2.4 . 321.Pp 322.Fn BN_asc2bin 323first appeared in OpenSSL 1.0.0 and has been available since 324.Ox 4.9 . 325