From e113c9c59dcb419dd00525cec431edb854a6c897 Mon Sep 17 00:00:00 2001 From: Matt Caswell Date: Tue, 24 Nov 2015 16:08:34 +0000 Subject: Add documentation for BN_with_flags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Following on from the previous commit this adds some documentation for the BN_with_flags function which is easy to misuse. Reviewed-by: Emilia Käsper --- doc/crypto/BN_copy.pod | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/crypto/BN_copy.pod b/doc/crypto/BN_copy.pod index 4de9c1ad17..0a00884ff0 100644 --- a/doc/crypto/BN_copy.pod +++ b/doc/crypto/BN_copy.pod @@ -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 to B. BN_dup() creates a new B containing the value B. +BN_with_flags creates a B shallow copy of B in B. 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 will +be set in B in addition to any flags already set in B. For example this +might commonly be used to create a temporary copy of a BIGNUM with the +B flag set for constant time operations. The temporary copy in +B will share some internal state with B. For this reason the following +restrictions apply to the use of B: + +=over 4 + +=item * + +B 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 must only be used in "read-only" operations, i.e. typically those +functions where the relevant parameter is declared "const". + +=item * + +B must be used and freed before any further subsequent use of B + +=back + =head1 RETURN VALUES BN_copy() returns B on success, NULL on error. BN_dup() returns -- cgit v1.2.3