1.\" $OpenBSD: BN_new.3,v 1.9 2017/01/30 07:51:27 jmc Exp $ 2.\" OpenSSL doc/man3/BN_new.pod 2457c19d Mar 6 08:43:36 2004 +0000 3.\" OpenSSL doc/man7/bn.pod 05ea606a May 20 20:52:46 2016 -0400 4.\" 5.\" This file was written by Ulf Moeller <ulf@openssl.org>. 6.\" Copyright (c) 2000, 2004 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: January 30 2017 $ 53.Dt BN_NEW 3 54.Os 55.Sh NAME 56.Nm BN_new , 57.Nm BN_init , 58.Nm BN_clear , 59.Nm BN_free , 60.Nm BN_clear_free 61.Nd allocate and free BIGNUMs 62.Sh SYNOPSIS 63.In openssl/bn.h 64.Ft BIGNUM * 65.Fo BN_new 66.Fa void 67.Fc 68.Ft void 69.Fo BN_init 70.Fa "BIGNUM *" 71.Fc 72.Ft void 73.Fo BN_clear 74.Fa "BIGNUM *a" 75.Fc 76.Ft void 77.Fo BN_free 78.Fa "BIGNUM *a" 79.Fc 80.Ft void 81.Fo BN_clear_free 82.Fa "BIGNUM *a" 83.Fc 84.Sh DESCRIPTION 85The BN library performs arithmetic operations on integers of arbitrary 86size. 87It was written for use in public key cryptography, such as RSA and 88Diffie-Hellman. 89.Pp 90It uses dynamic memory allocation for storing its data structures. 91That means that there is no limit on the size of the numbers manipulated 92by these functions, but return values must always be checked in case a 93memory allocation error has occurred. 94.Pp 95The basic object in this library is a 96.Vt BIGNUM . 97It is used to hold a single large integer. 98This type should be considered opaque and fields should not be modified 99or accessed directly. 100.Pp 101.Fn BN_new 102allocates and initializes a 103.Vt BIGNUM 104structure. 105.Pp 106.Fn BN_init 107initializes an existing uninitialized 108.Vt BIGNUM . 109It is deprecated and dangerous: see 110.Sx CAVEATS . 111.Pp 112.Fn BN_clear 113is used to destroy sensitive data such as keys when they are no longer 114needed. 115It erases the memory used by 116.Fa a 117and sets it to the value 0. 118.Pp 119.Fn BN_free 120frees the components of the 121.Vt BIGNUM 122and, if it was created by 123.Fn BN_new , 124also the structure itself. 125.Fn BN_clear_free 126additionally overwrites the data before the memory is returned to the 127system. 128If 129.Fa a 130is a 131.Dv NULL 132pointer, no action occurs. 133.Sh RETURN VALUES 134.Fn BN_new 135returns a pointer to the 136.Vt BIGNUM . 137If the allocation fails, it returns 138.Dv NULL 139and sets an error code that can be obtained by 140.Xr ERR_get_error 3 . 141.Sh SEE ALSO 142.Xr BN_add 3 , 143.Xr BN_add_word 3 , 144.Xr BN_BLINDING_new 3 , 145.Xr BN_bn2bin 3 , 146.Xr BN_cmp 3 , 147.Xr BN_copy 3 , 148.Xr BN_CTX_new 3 , 149.Xr BN_CTX_start 3 , 150.Xr BN_generate_prime 3 , 151.Xr BN_get0_nist_prime_521 3 , 152.Xr BN_mod_inverse 3 , 153.Xr BN_mod_mul_montgomery 3 , 154.Xr BN_mod_mul_reciprocal 3 , 155.Xr BN_num_bytes 3 , 156.Xr BN_rand 3 , 157.Xr BN_set_bit 3 , 158.Xr BN_set_flags 3 , 159.Xr BN_set_negative 3 , 160.Xr BN_swap 3 , 161.Xr BN_zero 3 162.Sh HISTORY 163.Fn BN_new , 164.Fn BN_clear , 165.Fn BN_free , 166and 167.Fn BN_clear_free 168are available in all versions of SSLeay and OpenSSL. 169.Fn BN_init 170was added in SSLeay 0.9.1b. 171.Sh CAVEATS 172.Fn BN_init 173must not be called on a 174.Vt BIGNUM 175that was used and contains an actual number, or the memory 176used for storing the number is leaked immediately. 177Besides, it must not be called on a number allocated with 178.Fn BN_new , 179or the 180.Vt BIGNUM 181structure itself will likely be leaked later on. 182It can only be used on static 183.Vt BIGNUM 184structures, on 185.Vt BIGNUM 186structures on the stack, or on 187.Vt BIGNUM 188structures 189.Xr malloc 3 Ap ed 190manually, but all of these options are discouraged because they 191will no longer work once the 192.Vt BIGNUM 193data type is made opaque. 194