From 441c99b87b2c1b279a582436aafe0a064d1bc709 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 19 Dec 2021 22:06:35 +0000 Subject: document BN_consttime_swap(3); this will probably require more work, but what i have so far is already better than nothing --- src/lib/libcrypto/man/BN_swap.3 | 87 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 80 insertions(+), 7 deletions(-) diff --git a/src/lib/libcrypto/man/BN_swap.3 b/src/lib/libcrypto/man/BN_swap.3 index db9082d7ef..218ca1cf02 100644 --- a/src/lib/libcrypto/man/BN_swap.3 +++ b/src/lib/libcrypto/man/BN_swap.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: BN_swap.3,v 1.5 2018/03/22 21:08:22 schwarze Exp $ -.\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 +.\" $OpenBSD: BN_swap.3,v 1.6 2021/12/19 22:06:35 schwarze Exp $ +.\" full merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800 .\" -.\" This file was written by Bodo Moeller <bodo@openssl.org>. +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> +.\" +.\" 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. +.\" +.\" The original file was written by Bodo Moeller <bodo@openssl.org>. .\" Copyright (c) 2000 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,11 +65,12 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 22 2018 $ +.Dd $Mdocdate: December 19 2021 $ .Dt BN_SWAP 3 .Os .Sh NAME -.Nm BN_swap +.Nm BN_swap , +.Nm BN_consttime_swap .Nd exchange BIGNUMs .Sh SYNOPSIS .In openssl/bn.h @@ -61,15 +79,70 @@ .Fa "BIGNUM *a" .Fa "BIGNUM *b" .Fc +.Ft void +.Fo BN_consttime_swap +.Fa "BN_ULONG condition" +.Fa "BIGNUM *a" +.Fa "BIGNUM *b" +.Fa "int nwords" +.Fc .Sh DESCRIPTION .Fn BN_swap -exchanges the values of +and +.Fn BN_consttime_swap +exchange the values of .Fa a and .Fa b . +.Pp +.Fn BN_swap +implements this by exchanging the pointers to the data buffers of +.Fa a +and +.Fa b +and also exchanging the values of the +.Dv BN_FLG_STATIC_DATA +bits. +Consequently, the operation is fast and execution time does not depend +on any properties of the two numbers. +However, execution time obviously differs between swapping (by calling +this function) and not swapping (by not calling this function). +.Pp +.Fn BN_consttime_swap +only performs the exchange if the +.Fa condition +is non-zero; otherwise, it has no effect. +It implements the exchange by exchanging the contents of the data +buffers rather than the pointers to the data buffers. +This is slower, but implemented in such a way that the execution time +is not only independent of the properties of the two numbers, but also +independent of the +.Fa condition +argument, i.e. the same for swapping or not swapping. +Execution time does however grow in an approximately linear manner with the +.Fa nwords +argument. +.Pp +.Fn BN_consttime_swap +calls +.Xr abort 3 +if at least one of +.Fa a +or +.Fa b +has fewer than +.Fa nwords +data words allocated or more than +.Fa nwords +data words are currently in use in at least one of them. .Sh SEE ALSO -.Xr BN_new 3 +.Xr BN_new 3 , +.Xr BN_set_flags 3 .Sh HISTORY .Fn BN_swap first appeared in OpenSSL 0.9.7 and has been available since .Ox 3.2 . +.Pp +.Fn BN_consttime_swap +first appeared in OpenSSL 1.0.1g and has been available since +.Ox 5.6 . -- cgit v1.2.3-55-g6feb