1.\" $OpenBSD: BN_new.3,v 1.31 2023/07/26 20:08:59 tb 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: July 26 2023 $ 54.Dt BN_NEW 3 55.Os 56.Sh NAME 57.Nm BN_new , 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_clear 70.Fa "BIGNUM *a" 71.Fc 72.Ft void 73.Fo BN_free 74.Fa "BIGNUM *a" 75.Fc 76.Ft void 77.Fo BN_clear_free 78.Fa "BIGNUM *a" 79.Fc 80.Sh DESCRIPTION 81The BN library performs arithmetic operations on integers of arbitrary 82size. 83It was written for use in public key cryptography, such as RSA and 84Diffie-Hellman. 85.Pp 86It uses dynamic memory allocation for storing its data structures. 87That means that there is no limit on the size of the numbers manipulated 88by these functions, but return values must always be checked in case a 89memory allocation error has occurred. 90.Pp 91The basic object in this library is a 92.Vt BIGNUM . 93It is used to hold a single large integer. 94This type should be considered opaque and fields should not be modified 95or accessed directly. 96.Pp 97.Fn BN_new 98allocates and initializes a 99.Vt BIGNUM 100structure, in particular setting the value to zero and the flags to 101.Dv BN_FLG_MALLOCED . 102The security-relevant flag 103.Dv BN_FLG_CONSTTIME 104is not set by default. 105.Pp 106.Fn BN_clear 107is used to destroy sensitive data such as keys when they are no longer 108needed. 109It erases the memory used by 110.Fa a 111and sets it to the value 0. 112.Pp 113.Fn BN_free 114frees the components of the 115.Vt BIGNUM 116and, if it was created by 117.Fn BN_new , 118also the structure itself. 119.Fn BN_clear_free 120additionally overwrites the data before the memory is returned to the 121system. 122If 123.Fa a 124is a 125.Dv NULL 126pointer, no action occurs. 127.Sh RETURN VALUES 128.Fn BN_new 129returns a pointer to the 130.Vt BIGNUM . 131If the allocation fails, it returns 132.Dv NULL 133and sets an error code that can be obtained by 134.Xr ERR_get_error 3 . 135.Sh SEE ALSO 136.Xr BN_add 3 , 137.Xr BN_add_word 3 , 138.Xr BN_bn2bin 3 , 139.Xr BN_cmp 3 , 140.Xr BN_copy 3 , 141.Xr BN_CTX_new 3 , 142.Xr BN_CTX_start 3 , 143.Xr BN_generate_prime 3 , 144.Xr BN_get_rfc3526_prime_8192 3 , 145.Xr BN_kronecker 3 , 146.Xr BN_mod_inverse 3 , 147.Xr BN_mod_mul_montgomery 3 , 148.Xr BN_mod_sqrt 3 , 149.Xr BN_num_bytes 3 , 150.Xr BN_rand 3 , 151.Xr BN_security_bits 3 , 152.Xr BN_set_bit 3 , 153.Xr BN_set_flags 3 , 154.Xr BN_set_negative 3 , 155.Xr BN_swap 3 , 156.Xr BN_zero 3 , 157.Xr crypto 3 158.Sh HISTORY 159.Fn BN_new , 160.Fn BN_clear , 161.Fn BN_free , 162and 163.Fn BN_clear_free 164first appeared in SSLeay 0.5.1 and have been available since 165.Ox 2.4 . 166