1.\" $OpenBSD: BN_new.3,v 1.16 2019/06/10 09:49:48 schwarze Exp $ 2.\" full merge up to: OpenSSL man3/BN_new 2457c19d Mar 6 08:43:36 2004 +0000 3.\" selective merge up to: man3/BN_new 681acb31 Sep 29 13:10:34 2017 +0200 4.\" full merge up to: OpenSSL man7/bn 05ea606a May 20 20:52:46 2016 -0400 5.\" 6.\" This file was written by Ulf Moeller <ulf@openssl.org>. 7.\" Copyright (c) 2000, 2004 The OpenSSL Project. All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: June 10 2019 $ 54.Dt BN_NEW 3 55.Os 56.Sh NAME 57.Nm BN_new , 58.Nm BN_init , 59.Nm BN_clear , 60.Nm BN_free , 61.Nm BN_clear_free 62.Nd allocate and free BIGNUMs 63.Sh SYNOPSIS 64.In openssl/bn.h 65.Ft BIGNUM * 66.Fo BN_new 67.Fa void 68.Fc 69.Ft void 70.Fo BN_init 71.Fa "BIGNUM *" 72.Fc 73.Ft void 74.Fo BN_clear 75.Fa "BIGNUM *a" 76.Fc 77.Ft void 78.Fo BN_free 79.Fa "BIGNUM *a" 80.Fc 81.Ft void 82.Fo BN_clear_free 83.Fa "BIGNUM *a" 84.Fc 85.Sh DESCRIPTION 86The BN library performs arithmetic operations on integers of arbitrary 87size. 88It was written for use in public key cryptography, such as RSA and 89Diffie-Hellman. 90.Pp 91It uses dynamic memory allocation for storing its data structures. 92That means that there is no limit on the size of the numbers manipulated 93by these functions, but return values must always be checked in case a 94memory allocation error has occurred. 95.Pp 96The basic object in this library is a 97.Vt BIGNUM . 98It is used to hold a single large integer. 99This type should be considered opaque and fields should not be modified 100or accessed directly. 101.Pp 102.Fn BN_new 103allocates and initializes a 104.Vt BIGNUM 105structure, in particular setting the value to zero and the flags to 106.Dv BN_FLG_MALLOCED . 107The security-relevant flag 108.Dv BN_FLG_CONSTTIME 109is not set by default. 110.Pp 111.Fn BN_init 112initializes an existing uninitialized 113.Vt BIGNUM . 114It is deprecated and dangerous: see 115.Sx CAVEATS . 116.Pp 117.Fn BN_clear 118is used to destroy sensitive data such as keys when they are no longer 119needed. 120It erases the memory used by 121.Fa a 122and sets it to the value 0. 123.Pp 124.Fn BN_free 125frees the components of the 126.Vt BIGNUM 127and, if it was created by 128.Fn BN_new , 129also the structure itself. 130.Fn BN_clear_free 131additionally overwrites the data before the memory is returned to the 132system. 133If 134.Fa a 135is a 136.Dv NULL 137pointer, no action occurs. 138.Sh RETURN VALUES 139.Fn BN_new 140returns a pointer to the 141.Vt BIGNUM . 142If the allocation fails, it returns 143.Dv NULL 144and sets an error code that can be obtained by 145.Xr ERR_get_error 3 . 146.Sh SEE ALSO 147.Xr BN_add 3 , 148.Xr BN_add_word 3 , 149.Xr BN_BLINDING_new 3 , 150.Xr BN_bn2bin 3 , 151.Xr BN_cmp 3 , 152.Xr BN_copy 3 , 153.Xr BN_CTX_new 3 , 154.Xr BN_CTX_start 3 , 155.Xr BN_generate_prime 3 , 156.Xr BN_get0_nist_prime_521 3 , 157.Xr BN_mod_inverse 3 , 158.Xr BN_mod_mul_montgomery 3 , 159.Xr BN_mod_mul_reciprocal 3 , 160.Xr BN_num_bytes 3 , 161.Xr BN_rand 3 , 162.Xr BN_set_bit 3 , 163.Xr BN_set_flags 3 , 164.Xr BN_set_negative 3 , 165.Xr BN_swap 3 , 166.Xr BN_zero 3 , 167.Xr crypto 3 , 168.Xr get_rfc3526_prime_8192 3 169.Sh HISTORY 170.Fn BN_new , 171.Fn BN_clear , 172.Fn BN_free , 173and 174.Fn BN_clear_free 175first appeared in SSLeay 0.5.1 and have been available since 176.Ox 2.4 . 177.Pp 178.Fn BN_init 179first appeared in SSLeay 0.9.1 and has been available since 180.Ox 2.6 . 181.Sh CAVEATS 182.Fn BN_init 183must not be called on a 184.Vt BIGNUM 185that was used and contains an actual number, or the memory 186used for storing the number is leaked immediately. 187Besides, it must not be called on a number allocated with 188.Fn BN_new , 189or the 190.Vt BIGNUM 191structure itself will likely be leaked later on. 192It can only be used on static 193.Vt BIGNUM 194structures, on 195.Vt BIGNUM 196structures on the stack, or on 197.Vt BIGNUM 198structures 199.Xr malloc 3 Ap ed 200manually, but all of these options are discouraged because they 201will no longer work once the 202.Vt BIGNUM 203data type is made opaque. 204