diff options
author | Matt Caswell <matt@openssl.org> | 2015-11-24 16:08:34 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2015-11-26 10:20:36 +0000 |
commit | e113c9c59dcb419dd00525cec431edb854a6c897 (patch) | |
tree | f1101f29267b7911ef97d5bb82b9753ec9f34a57 /doc | |
parent | fd7d252060c427b2e567295845a61d824539443b (diff) |
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: Emilia Käsper <emilia@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/BN_copy.pod | 32 |
1 files changed, 31 insertions, 1 deletions
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<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 |