lib/libcrypto/man/BN_copy.3

   1 .\"     $OpenBSD: BN_copy.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org>
   5 .\" and Matt Caswell <matt@openssl.org>.
   6 .\" Copyright (c) 2000, 2015 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: March 27 2018 $
  53 .Dt BN_COPY 3
  54 .Os
  55 .Sh NAME
  56 .Nm BN_copy ,
  57 .Nm BN_dup ,
  58 .Nm BN_with_flags
  59 .Nd copy BIGNUMs
  60 .Sh SYNOPSIS
  61 .In openssl/bn.h
  62 .Ft BIGNUM *
  63 .Fo BN_copy
  64 .Fa "BIGNUM *to"
  65 .Fa "const BIGNUM *from"
  66 .Fc
  67 .Ft BIGNUM *
  68 .Fo BN_dup
  69 .Fa "const BIGNUM *from"
  70 .Fc
  71 .Ft void
  72 .Fo BN_with_flags
  73 .Fa "BIGNUM *dest"
  74 .Fa "const BIGNUM *b"
  75 .Fa "int flags"
  76 .Fc
  77 .Sh DESCRIPTION
  78 .Fn BN_copy
  79 copies
  80 .Fa from
  81 to
  82 .Fa to .
  83 .Pp
  84 .Fn BN_dup
  85 creates a new
  86 .Vt BIGNUM
  87 containing the value
  88 .Fa from .
  89 .Pp
  90 .Fn BN_with_flags
  91 creates a
  92 .Em temporary
  93 shallow copy of
  94 .Fa b
  95 in
  96 .Fa dest .
  97 It places significant restrictions on the copied data.
  98 Applications that do not adhere to these restrictions
  99 may encounter unexpected side effects or crashes.
 100 For that reason, use of this macro is discouraged.
 101 .Pp
 102 Any flags provided in
 103 .Fa flags
 104 will be set in
 105 .Fa dest
 106 in addition to any flags already set in
 107 .Fa b .
 108 For example, this can be used to create a temporary copy of a
 109 .Vt BIGNUM
 110 with the
 111 .Dv BN_FLG_CONSTTIME
 112 flag set for constant time operations.
 113 .Pp
 114 The temporary copy in
 115 .Fa dest
 116 will share some internal state with
 117 .Fa b .
 118 For this reason, the following restrictions apply to the use of
 119 .Fa dest :
 120 .Bl -bullet
 121 .It
 122 .Fa dest
 123 should be a newly allocated
 124 .Vt BIGNUM
 125 obtained via a call to
 126 .Xr BN_new 3 .
 127 It should not have been used for other purposes or initialised in any way.
 128 .It
 129 .Fa dest
 130 must only be used in "read-only" operations, i.e. typically those
 131 functions where the relevant parameter is declared "const".
 132 .It
 133 .Fa dest
 134 must be used and freed before any further subsequent use of
 135 .Fa b .
 136 .El
 137 .Sh RETURN VALUES
 138 .Fn BN_copy
 139 returns
 140 .Fa to
 141 on success or
 142 .Dv NULL
 143 on error.
 144 .Fn BN_dup
 145 returns the new
 146 .Vt BIGNUM
 147 or
 148 .Dv NULL
 149 on error.
 150 The error codes can be obtained by
 151 .Xr ERR_get_error 3 .
 152 .Sh SEE ALSO
 153 .Xr BN_new 3 ,
 154 .Xr BN_set_flags 3
 155 .Sh HISTORY
 156 .Fn BN_copy
 157 and
 158 .Fn BN_dup
 159 first appeared in SSLeay 0.5.1 and have been available since
 160 .Ox 2.4 .
 161 .Pp
 162 .Fn BN_with_flags
 163 first appeared in OpenSSL 0.9.7h and 0.9.8a
 164 and has been available since
 165 .Ox 4.0 .