diff options
-rw-r--r-- | doc/crypto/BN_copy.pod | 32 | ||||
-rw-r--r-- | include/openssl/bn.h | 6 |
2 files changed, 35 insertions, 3 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 diff --git a/include/openssl/bn.h b/include/openssl/bn.h index 0fcf843314..b052c41991 100644 --- a/include/openssl/bn.h +++ b/include/openssl/bn.h @@ -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); |