From 77fac97f447a495db8dde0a769d98807430544b9 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 30 Jan 2017 01:29:31 +0000 Subject: Document BN_set_flags(3) and BN_get_flags(3). jsing@ confirmed that these macros are public and worth documenting. --- src/lib/libcrypto/man/BN_add.3 | 8 +- src/lib/libcrypto/man/BN_copy.3 | 6 +- src/lib/libcrypto/man/BN_mod_inverse.3 | 6 +- src/lib/libcrypto/man/BN_new.3 | 5 +- src/lib/libcrypto/man/BN_set_flags.3 | 144 +++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/Makefile | 3 +- 6 files changed, 159 insertions(+), 13 deletions(-) create mode 100644 src/lib/libcrypto/man/BN_set_flags.3 diff --git a/src/lib/libcrypto/man/BN_add.3 b/src/lib/libcrypto/man/BN_add.3 index 77afec7de3..a275dbfe95 100644 --- a/src/lib/libcrypto/man/BN_add.3 +++ b/src/lib/libcrypto/man/BN_add.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BN_add.3,v 1.6 2017/01/07 05:06:22 schwarze Exp $ +.\" $OpenBSD: BN_add.3,v 1.7 2017/01/30 01:29:31 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Ulf Moeller @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: January 7 2017 $ +.Dd $Mdocdate: January 30 2017 $ .Dt BN_ADD 3 .Os .Sh NAME @@ -384,8 +384,8 @@ The error codes can be obtained by .Xr BN_CTX_new 3 , .Xr BN_new 3 , .Xr BN_set_bit 3 , -.Xr BN_set_negative 3 , -.Xr ERR_get_error 3 +.Xr BN_set_flags 3 , +.Xr BN_set_negative 3 .Sh HISTORY .Fn BN_add , .Fn BN_sub , diff --git a/src/lib/libcrypto/man/BN_copy.3 b/src/lib/libcrypto/man/BN_copy.3 index 34653be7e3..398cf1f8ec 100644 --- a/src/lib/libcrypto/man/BN_copy.3 +++ b/src/lib/libcrypto/man/BN_copy.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BN_copy.3,v 1.5 2017/01/07 05:06:22 schwarze Exp $ +.\" $OpenBSD: BN_copy.3,v 1.6 2017/01/30 01:29:31 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Ulf Moeller @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: January 7 2017 $ +.Dd $Mdocdate: January 30 2017 $ .Dt BN_COPY 3 .Os .Sh NAME @@ -151,7 +151,7 @@ The error codes can be obtained by .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr BN_new 3 , -.Xr ERR_get_error 3 +.Xr BN_set_flags 3 .Sh HISTORY .Fn BN_copy and diff --git a/src/lib/libcrypto/man/BN_mod_inverse.3 b/src/lib/libcrypto/man/BN_mod_inverse.3 index 6817fc2a3f..f407fa71e8 100644 --- a/src/lib/libcrypto/man/BN_mod_inverse.3 +++ b/src/lib/libcrypto/man/BN_mod_inverse.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BN_mod_inverse.3,v 1.5 2016/12/10 21:13:25 schwarze Exp $ +.\" $OpenBSD: BN_mod_inverse.3,v 1.6 2017/01/30 01:29:31 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Ulf Moeller . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 10 2016 $ +.Dd $Mdocdate: January 30 2017 $ .Dt BN_MOD_INVERSE 3 .Os .Sh NAME @@ -103,7 +103,7 @@ The error codes can be obtained by .Sh SEE ALSO .Xr BN_add 3 , .Xr BN_new 3 , -.Xr ERR_get_error 3 +.Xr BN_set_flags 3 .Sh HISTORY .Fn BN_mod_inverse is available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/BN_new.3 b/src/lib/libcrypto/man/BN_new.3 index 8294a4f4d1..ce3734938d 100644 --- a/src/lib/libcrypto/man/BN_new.3 +++ b/src/lib/libcrypto/man/BN_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: BN_new.3,v 1.7 2017/01/29 23:41:49 schwarze Exp $ +.\" $OpenBSD: BN_new.3,v 1.8 2017/01/30 01:29:31 schwarze Exp $ .\" OpenSSL doc/man3/BN_new.pod 2457c19d Mar 6 08:43:36 2004 +0000 .\" OpenSSL doc/man7/bn.pod 05ea606a May 20 20:52:46 2016 -0400 .\" @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: January 29 2017 $ +.Dd $Mdocdate: January 30 2017 $ .Dt BN_NEW 3 .Os .Sh NAME @@ -155,6 +155,7 @@ and sets an error code that can be obtained by .Xr BN_num_bytes 3 , .Xr BN_rand 3 , .Xr BN_set_bit 3 , +.Xr BN_set_flags 3 , .Xr BN_set_negative 3 , .Xr BN_swap 3 , .Xr BN_zero 3 diff --git a/src/lib/libcrypto/man/BN_set_flags.3 b/src/lib/libcrypto/man/BN_set_flags.3 new file mode 100644 index 0000000000..27649fd074 --- /dev/null +++ b/src/lib/libcrypto/man/BN_set_flags.3 @@ -0,0 +1,144 @@ +.\" $OpenBSD: BN_set_flags.3,v 1.1 2017/01/30 01:29:31 schwarze Exp $ +.\" +.\" Copyright (c) 2017 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: January 30 2017 $ +.Dt BN_SET_FLAGS 3 +.Os +.Sh NAME +.Nm BN_set_flags , +.Nm BN_get_flags +.Nd enable and inspect flags on BIGNUM objects +.Sh SYNOPSIS +.In openssl/bn.h +.Ft void +.Fo BN_set_flags +.Fa "BIGNUM *b" +.Fa "int flags" +.Fc +.Ft int +.Fo BN_get_flags +.Fa "const BIGNUM *b" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn BN_set_flags +enables the given +.Fa flags +on +.Fa b . +The +.Fa flags +argument can contain zero or more of the following constants OR'ed +together: +.Bl -tag -width Ds +.It Dv BN_FLG_CONSTTIME +If this flag is set on the divident +.Fa a +in +.Xr BN_div 3 , +on the exponent +.Fa p +in +.Xr BN_mod_exp 3 , +or on the divisor +.Fa a +or the modulus +.Fa n +in +.Xr BN_mod_inverse 3 , +these functions prefer algorithms with an execution time independent +of the respective numbers, to avoid exposing sensitive information +to timing attacks. +.Pp +If this flag is set on the exponent +.Fa p +in +.Xr BN_exp 3 +or if the modulus +.Fa m +is even for +.Xr BN_mod_exp 3 , +an error occurs. +.Pp +Various functions automatically set this flag on sensitive data. +For example, the default implementations of +.Xr DH_generate_key 3 , +.Xr DSA_generate_key 3 , +and +.Xr RSA_generate_key_ex 3 +set it on the generated private key. +.It Dv BN_FLG_MALLOCED +If this flag is set, +.Xr BN_free 3 +and +.Xr BN_clear_free 3 +will not only clear and free the components of +.Fa b , +but also +.Fa b +itself. +This flag is set internally by +.Xr BN_new 3 . +Setting it manually on an existing +.Vt BIGNUM +object is usually a bad idea and can cause calls to +.Xr free 3 +with bogus arguments. +.It Dv BN_FLG_STATIC_DATA +If this flag is set, +.Xr BN_clear_free 3 +will neither clear nor free the memory used for storing the number. +Consequently, setting it manually on an existing +.Vt BIGNUM +object is usually a terrible idea that can cause both disclosure +of secret data and memory leaks. +This flag is automatically set on the constant +.Vt BIGNUM +objects returned by +.Xr BN_value_one 3 +and by the functions documented in +.Xr BN_get0_nist_prime_521 3 . +.El +.Pp +.Fn BN_get_flags +interpretes +.Fa flags +as a bitmask and returns those of the given flags that are set in +.Fa b , +OR'ed together, or 0 if none of the given +.Fa flags +is set. +The +.Fa flags +argument has the same syntax as for +.Fn BN_set_flags . +.Pp +These functions are currently implemented as macros, but they are +likely to become real functions in the future when the +.Vt BIGNUM +data type will be made opaque. +.Sh RETURN VALUES +.Fn BN_get_flags +returns zero or more of the above constants, OR'ed together. +.Sh SEE ALSO +.Xr BN_mod_exp 3 , +.Xr BN_mod_inverse 3 , +.Xr BN_new 3 , +.Xr BN_with_flags 3 +.Sh CAVEATS +No public interface exists to clear a flag once it is set. +So think twice before using +.Fn BN_set_flags . diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 46e8ba5739..d991508cff 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.112 2017/01/07 00:45:04 schwarze Exp $ +# $OpenBSD: Makefile,v 1.113 2017/01/30 01:29:31 schwarze Exp $ .include @@ -55,6 +55,7 @@ MAN= \ BN_num_bytes.3 \ BN_rand.3 \ BN_set_bit.3 \ + BN_set_flags.3 \ BN_set_negative.3 \ BN_swap.3 \ BN_zero.3 \ -- cgit v1.2.3-55-g6feb