Commit e113c9c5 authored by Matt Caswell's avatar Matt Caswell
Browse files

Add documentation for BN_with_flags 



Following on from the previous commit this adds some documentation for the
BN_with_flags function which is easy to misuse.

Reviewed-by: default avatarEmilia Käsper <emilia@openssl.org>
parent fd7d2520

doc/crypto/BN_copy.pod

+31 −1
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 


=head1 NAME



BN_copy, BN_dup - copy BIGNUMs

BN_copy, BN_dup, BN_with_flags - copy BIGNUMs



=head1 SYNOPSIS
@@ -12,11 +12,41 @@ BN_copy, BN_dup - copy BIGNUMs 


 BIGNUM *BN_dup(const BIGNUM *from);



 void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);



=head1 DESCRIPTION



BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>

containing the value B<from>.



BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places

significant restrictions on the copied data. Applications that do no adhere to

these restrictions may encounter unexpected side effects or crashes. For that

reason use of this function is discouraged. Any flags provided in B<flags> will

be set in B<dest> in addition to any flags already set in B<b>. For example this

might commonly be used to create a temporary copy of a BIGNUM with the

B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in

B<dest> will share some internal state with B<b>. For this reason the following

restrictions apply to the use of B<dest>:



=over 4



=item *



B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It

should not have been used for other purposes or initialised in any way.



=item *



B<dest> must only be used in "read-only" operations, i.e. typically those

functions where the relevant parameter is declared "const".



=item *



B<dest> must be used and freed before any further subsequent use of B<b>



=back



=head1 RETURN VALUES



BN_copy() returns B<to> on success, NULL on error. BN_dup() returns

include/openssl/bn.h

+4 −2
Original line number Diff line number Diff line
@@ -285,9 +285,11 @@ int BN_get_flags(const BIGNUM *b, int n); 


/*

 * get a clone of a BIGNUM with changed flags, for *temporary* use only (the

 * two BIGNUMs cannot not be used in parallel!)

 * two BIGNUMs cannot be used in parallel!). Also only for *read only* use. The

 * value |dest| should be a newly allocated BIGNUM obtained via BN_new() that

 * has not been otherwise initialised or used.

 */

void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int n);

void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);



/* Wrapper function to make using BN_GENCB easier,  */

int BN_GENCB_call(BN_GENCB *cb, int a, int b);