| yuezonghe | 824eb0c | 2024-06-27 02:32:26 -0700 | [diff] [blame^] | 1 | =pod |
| 2 | |
| 3 | =head1 NAME |
| 4 | |
| 5 | BN_copy, BN_dup, BN_with_flags - copy BIGNUMs |
| 6 | |
| 7 | =head1 SYNOPSIS |
| 8 | |
| 9 | #include <openssl/bn.h> |
| 10 | |
| 11 | BIGNUM *BN_copy(BIGNUM *to, const BIGNUM *from); |
| 12 | |
| 13 | BIGNUM *BN_dup(const BIGNUM *from); |
| 14 | |
| 15 | void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags); |
| 16 | |
| 17 | =head1 DESCRIPTION |
| 18 | |
| 19 | BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM> |
| 20 | containing the value B<from>. |
| 21 | |
| 22 | BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places |
| 23 | significant restrictions on the copied data. Applications that do no adhere to |
| 24 | these restrictions may encounter unexpected side effects or crashes. For that |
| 25 | reason use of this function is discouraged. Any flags provided in B<flags> will |
| 26 | be set in B<dest> in addition to any flags already set in B<b>. For example this |
| 27 | might commonly be used to create a temporary copy of a BIGNUM with the |
| 28 | B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in |
| 29 | B<dest> will share some internal state with B<b>. For this reason the following |
| 30 | restrictions apply to the use of B<dest>: |
| 31 | |
| 32 | =over 2 |
| 33 | |
| 34 | =item * |
| 35 | |
| 36 | B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It |
| 37 | should not have been used for other purposes or initialised in any way. |
| 38 | |
| 39 | =item * |
| 40 | |
| 41 | B<dest> must only be used in "read-only" operations, i.e. typically those |
| 42 | functions where the relevant parameter is declared "const". |
| 43 | |
| 44 | =item * |
| 45 | |
| 46 | B<dest> must be used and freed before any further subsequent use of B<b> |
| 47 | |
| 48 | =back |
| 49 | |
| 50 | =head1 RETURN VALUES |
| 51 | |
| 52 | BN_copy() returns B<to> on success, NULL on error. BN_dup() returns |
| 53 | the new B<BIGNUM>, and NULL on error. The error codes can be obtained |
| 54 | by L<ERR_get_error(3)>. |
| 55 | |
| 56 | =head1 SEE ALSO |
| 57 | |
| 58 | L<ERR_get_error(3)> |
| 59 | |
| 60 | =head1 COPYRIGHT |
| 61 | |
| 62 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
| 63 | |
| 64 | Licensed under the OpenSSL license (the "License"). You may not use |
| 65 | this file except in compliance with the License. You can obtain a copy |
| 66 | in the file LICENSE in the source distribution or at |
| 67 | L<https://www.openssl.org/source/license.html>. |
| 68 | |
| 69 | =cut |