lib/libcrypto/man/BN_new.3

   1 .\" $OpenBSD: BN_new.3,v 1.12 2018/03/21 09:03:49 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: March 21 2018 $
  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
  86 The BN library performs arithmetic operations on integers of arbitrary
  87 size.
  88 It was written for use in public key cryptography, such as RSA and
  89 Diffie-Hellman.
  90 .Pp
  91 It uses dynamic memory allocation for storing its data structures.
  92 That means that there is no limit on the size of the numbers manipulated
  93 by these functions, but return values must always be checked in case a
  94 memory allocation error has occurred.
  95 .Pp
  96 The basic object in this library is a
  97 .Vt BIGNUM .
  98 It is used to hold a single large integer.
  99 This type should be considered opaque and fields should not be modified
 100 or accessed directly.
 101 .Pp
 102 .Fn BN_new
 103 allocates and initializes a
 104 .Vt BIGNUM
 105 structure, in particular setting the value to zero.
 106 .Pp
 107 .Fn BN_init
 108 initializes an existing uninitialized
 109 .Vt BIGNUM .
 110 It is deprecated and dangerous: see
 111 .Sx CAVEATS .
 112 .Pp
 113 .Fn BN_clear
 114 is used to destroy sensitive data such as keys when they are no longer
 115 needed.
 116 It erases the memory used by
 117 .Fa a
 118 and sets it to the value 0.
 119 .Pp
 120 .Fn BN_free
 121 frees the components of the
 122 .Vt BIGNUM
 123 and, if it was created by
 124 .Fn BN_new ,
 125 also the structure itself.
 126 .Fn BN_clear_free
 127 additionally overwrites the data before the memory is returned to the
 128 system.
 129 If
 130 .Fa a
 131 is a
 132 .Dv NULL
 133 pointer, no action occurs.
 134 .Sh RETURN VALUES
 135 .Fn BN_new
 136 returns a pointer to the
 137 .Vt BIGNUM .
 138 If the allocation fails, it returns
 139 .Dv NULL
 140 and sets an error code that can be obtained by
 141 .Xr ERR_get_error 3 .
 142 .Sh SEE ALSO
 143 .Xr BN_add 3 ,
 144 .Xr BN_add_word 3 ,
 145 .Xr BN_BLINDING_new 3 ,
 146 .Xr BN_bn2bin 3 ,
 147 .Xr BN_cmp 3 ,
 148 .Xr BN_copy 3 ,
 149 .Xr BN_CTX_new 3 ,
 150 .Xr BN_CTX_start 3 ,
 151 .Xr BN_generate_prime 3 ,
 152 .Xr BN_get0_nist_prime_521 3 ,
 153 .Xr BN_mod_inverse 3 ,
 154 .Xr BN_mod_mul_montgomery 3 ,
 155 .Xr BN_mod_mul_reciprocal 3 ,
 156 .Xr BN_num_bytes 3 ,
 157 .Xr BN_rand 3 ,
 158 .Xr BN_set_bit 3 ,
 159 .Xr BN_set_flags 3 ,
 160 .Xr BN_set_negative 3 ,
 161 .Xr BN_swap 3 ,
 162 .Xr BN_zero 3
 163 .Sh HISTORY
 164 .Fn BN_new ,
 165 .Fn BN_clear ,
 166 .Fn BN_free ,
 167 and
 168 .Fn BN_clear_free
 169 appeared before SSLeay 0.8 and have been available since
 170 .Ox 2.4 .
 171 .Pp
 172 .Fn BN_init
 173 first appeared in SSLeay 0.9.1 and has been available since
 174 .Ox 2.6 .
 175 .Sh CAVEATS
 176 .Fn BN_init
 177 must not be called on a
 178 .Vt BIGNUM
 179 that was used and contains an actual number, or the memory
 180 used for storing the number is leaked immediately.
 181 Besides, it must not be called on a number allocated with
 182 .Fn BN_new ,
 183 or the
 184 .Vt BIGNUM
 185 structure itself will likely be leaked later on.
 186 It can only be used on static
 187 .Vt BIGNUM
 188 structures, on
 189 .Vt BIGNUM
 190 structures on the stack, or on
 191 .Vt BIGNUM
 192 structures
 193 .Xr malloc 3 Ap ed
 194 manually, but all of these options are discouraged because they
 195 will no longer work once the
 196 .Vt BIGNUM
 197 data type is made opaque.