From adfdcceb8aad478bc3c5692fb3aff045c0c8ef37 Mon Sep 17 00:00:00 2001 From: riastradh Date: Mon, 24 Jun 2013 04:21:19 +0000 Subject: Replace consttime_bcmp/explicit_bzero by consttime_memequal/explicit_memset. consttime_memequal is the same as the old consttime_bcmp. explicit_memset is to memset as explicit_bzero was to bcmp. Passes amd64 release and i386/ALL, but I'm sure I missed some spots, so please let me know. --- lib/libc/string/Makefile.inc | 8 ++-- lib/libc/string/consttime_bcmp.3 | 88 ------------------------------------ lib/libc/string/consttime_memequal.3 | 88 ++++++++++++++++++++++++++++++++++++ lib/libc/string/explicit_bzero.3 | 75 ------------------------------ lib/libc/string/explicit_memset.3 | 77 +++++++++++++++++++++++++++++++ lib/libc/string/memcmp.3 | 6 +-- lib/libc/string/memset.3 | 6 +-- 7 files changed, 175 insertions(+), 173 deletions(-) delete mode 100644 lib/libc/string/consttime_bcmp.3 create mode 100644 lib/libc/string/consttime_memequal.3 delete mode 100644 lib/libc/string/explicit_bzero.3 create mode 100644 lib/libc/string/explicit_memset.3 (limited to 'lib/libc/string') diff --git a/lib/libc/string/Makefile.inc b/lib/libc/string/Makefile.inc index eecb6520f60..e88301b0612 100644 --- a/lib/libc/string/Makefile.inc +++ b/lib/libc/string/Makefile.inc @@ -1,5 +1,5 @@ # from: @(#)Makefile.inc 8.1 (Berkeley) 6/4/93 -# $NetBSD: Makefile.inc,v 1.77 2013/06/24 01:12:08 riastradh Exp $ +# $NetBSD: Makefile.inc,v 1.78 2013/06/24 04:21:20 riastradh Exp $ # string sources .PATH: ${ARCHDIR}/string ${.CURDIR}/string @@ -19,7 +19,7 @@ SRCS+= bcmp.c bcopy.c bzero.c ffs.c memchr.c memcmp.c memset.c SRCS+= strcat.c strcmp.c strcpy.c strcspn.c strlen.c SRCS+= strncat.c strncmp.c strncpy.c strpbrk.c strsep.c SRCS+= strspn.c strstr.c swab.c -SRCS+= explicit_bzero.c consttime_bcmp.c +SRCS+= explicit_memset.c consttime_memequal.c SRCS+= memccpy.c memcpy.c memmem.c memmove.c SRCS+= strchr.c strrchr.c @@ -39,8 +39,8 @@ SRCS+= _strlcat.c _strlcpy.c _strerror_r.c .include "${ARCHDIR}/string/Makefile.inc" -MAN+= bm.3 bcmp.3 bcopy.3 bstring.3 bzero.3 consttime_bcmp.3 \ - explicit_bzero.3 ffs.3 index.3 \ +MAN+= bm.3 bcmp.3 bcopy.3 bstring.3 bzero.3 consttime_memequal.3 \ + explicit_memset.3 ffs.3 index.3 \ memccpy.3 memchr.3 memcmp.3 memcpy.3 memmem.3 memmove.3 memset.3 \ popcount.3 \ rindex.3 strcasecmp.3 strcat.3 strchr.3 strcmp.3 strcoll.3 \ diff --git a/lib/libc/string/consttime_bcmp.3 b/lib/libc/string/consttime_bcmp.3 deleted file mode 100644 index 1a4579dae45..00000000000 --- a/lib/libc/string/consttime_bcmp.3 +++ /dev/null @@ -1,88 +0,0 @@ -.\" $NetBSD: consttime_bcmp.3,v 1.1 2013/06/23 16:44:06 riastradh Exp $ -.\" -.\" Copyright (c) 2013 The NetBSD Foundation, Inc. -.\" All rights reserved. -.\" -.\" This documentation is derived from text contributed to The NetBSD -.\" Foundation by Taylor R. Campbell. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS -.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS -.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -.\" POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd June 23, 2013 -.Dt CONSTTIME_BCMP 3 -.Os -.Sh NAME -.Nm consttime_bcmp -.Nd compare byte strings for equality without timing leaks -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In string.h -.Ft int -.Fn consttime_bcmp "void *b1" "void *b2" "size_t len" -.Sh DESCRIPTION -The -.Fn consttime_bcmp -function compares -.Fa len -bytes of memory at -.Fa b1 -and -.Fa b2 -for equality, returning zero if they are identical and nonzero -otherwise. -.Pp -The time taken by -.Fn consttime_bcmp -depends on -.Fa len , -but not on the data at -.Fa b1 -or -.Fa b2 . -Thus, -.Fn consttime_bcmp -is appropriate for comparing cryptographic secrets, hashes, message -authentication codes, etc., without leaking information about them -through a timing side channel. -In crypto literature, -.Fn consttime_bcmp -is said to take -.Sq constant time , -meaning time that does not vary depending on the data it processes. -.Pp -Note that unlike -.Xr memcmp 3 , -.Fn consttime_bcmp -does not return a lexicographic ordering on the data at -.Fa b1 -and -.Fa b2 ; -it tells only whether they are equal. -.Sh SEE ALSO -.Xr explicit_bzero 3 , -.Xr memcmp 3 -.Sh HISTORY -The -.Fn consttime_bcmp -function appeared in -.Nx 7.0 . diff --git a/lib/libc/string/consttime_memequal.3 b/lib/libc/string/consttime_memequal.3 new file mode 100644 index 00000000000..2f71503b777 --- /dev/null +++ b/lib/libc/string/consttime_memequal.3 @@ -0,0 +1,88 @@ +.\" $NetBSD: consttime_memequal.3,v 1.1 2013/06/24 04:21:20 riastradh Exp $ +.\" +.\" Copyright (c) 2013 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD +.\" Foundation by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 23, 2013 +.Dt CONSTTIME_MEMEQUAL 3 +.Os +.Sh NAME +.Nm consttime_memequal +.Nd compare byte strings for equality without timing leaks +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft int +.Fn consttime_memequal "void *b1" "void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn consttime_memequal +function compares +.Fa len +bytes of memory at +.Fa b1 +and +.Fa b2 +for equality, returning zero if they are identical and nonzero +otherwise. +.Pp +The time taken by +.Fn consttime_memequal +depends on +.Fa len , +but not on the data at +.Fa b1 +or +.Fa b2 . +Thus, +.Fn consttime_memequal +is appropriate for comparing cryptographic secrets, hashes, message +authentication codes, etc., without leaking information about them +through a timing side channel. +In crypto literature, +.Fn consttime_memequal +is said to take +.Sq constant time , +meaning time that does not vary depending on the data it processes. +.Pp +Note that unlike +.Xr memcmp 3 , +.Fn consttime_memequal +does not return a lexicographic ordering on the data at +.Fa b1 +and +.Fa b2 ; +it tells only whether they are equal. +.Sh SEE ALSO +.Xr explicit_memset 3 , +.Xr memcmp 3 +.Sh HISTORY +The +.Fn consttime_memequal +function appeared in +.Nx 7.0 . diff --git a/lib/libc/string/explicit_bzero.3 b/lib/libc/string/explicit_bzero.3 deleted file mode 100644 index 12af1504a71..00000000000 --- a/lib/libc/string/explicit_bzero.3 +++ /dev/null @@ -1,75 +0,0 @@ -.\" $NetBSD: explicit_bzero.3,v 1.1 2013/06/23 16:44:06 riastradh Exp $ -.\" -.\" Copyright (c) 2013 The NetBSD Foundation, Inc. -.\" All rights reserved. -.\" -.\" This documentation is derived from text contributed to The NetBSD -.\" Foundation by Taylor R. Campbell. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS -.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED -.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS -.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -.\" POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd June 23, 2013 -.Dt EXPLICIT_BZERO 3 -.Os -.Sh NAME -.Nm explicit_bzero -.Nd guarantee zeroing a buffer in memory -.Sh LIBRARY -.Lb libc -.Sh SYNOPSIS -.In string.h -.Ft void -.Fn explicit_bzero "void *ptr" "size_t len" -.Sh DESCRIPTION -The -.Fn explicit_bzero -function writes -.Fa len -zero bytes to the memory pointed to by -.Fa ptr . -It is guaranteed not to be optimized away by the compiler even if -.Fa ptr -is no longer used and is about to be freed or go out of scope. -.Sh EXAMPLES -Create a buffer on the stack for a secret key, use it, and then zero it -in memory before throwing it away. -.Bd -literal -offset indent -void -f(void) -{ - uint8_t key[32]; - - crypto_random(key, sizeof(key)); - do_crypto_stuff(key, sizeof(key)); - \&... - - explicit_bzero(key, sizeof(key)); -} -.Ed -.Sh SEE ALSO -.Xr consttime_bcmp 3 , -.Xr memset 3 -.Sh HISTORY -The -.Fn explicit_bzero -function appeared in -.Nx 7.0 . diff --git a/lib/libc/string/explicit_memset.3 b/lib/libc/string/explicit_memset.3 new file mode 100644 index 00000000000..722c9475643 --- /dev/null +++ b/lib/libc/string/explicit_memset.3 @@ -0,0 +1,77 @@ +.\" $NetBSD: explicit_memset.3,v 1.1 2013/06/24 04:21:20 riastradh Exp $ +.\" +.\" Copyright (c) 2013 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed to The NetBSD +.\" Foundation by Taylor R. Campbell. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd June 23, 2013 +.Dt EXPLICIT_MEMSET 3 +.Os +.Sh NAME +.Nm explicit_memset +.Nd guarantee writing a byte to a byte string +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In string.h +.Ft void +.Fn explicit_memset "void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn explicit_memset +function writes +.Fa len +bytes of value +.Fa c +(converted to an unsigned char) to the string +.Fa b . +It is guaranteed not to be optimized away by the compiler even if +.Fa b +is no longer used and is about to be freed or go out of scope. +.Sh EXAMPLES +Create a buffer on the stack for a secret key, use it, and then zero it +in memory before throwing it away. +.Bd -literal -offset indent +void +f(void) +{ + uint8_t key[32]; + + crypto_random(key, sizeof(key)); + do_crypto_stuff(key, sizeof(key)); + \&... + + explicit_memset(key, 0, sizeof(key)); +} +.Ed +.Sh SEE ALSO +.Xr consttime_memequal 3 , +.Xr memset 3 +.Sh HISTORY +The +.Fn explicit_memset +function appeared in +.Nx 7.0 . diff --git a/lib/libc/string/memcmp.3 b/lib/libc/string/memcmp.3 index 78e92105e30..fec697f7224 100644 --- a/lib/libc/string/memcmp.3 +++ b/lib/libc/string/memcmp.3 @@ -30,7 +30,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)memcmp.3 8.1 (Berkeley) 6/4/93 -.\" $NetBSD: memcmp.3,v 1.10 2013/06/23 16:44:06 riastradh Exp $ +.\" $NetBSD: memcmp.3,v 1.11 2013/06/24 04:21:20 riastradh Exp $ .\" .Dd June 23, 2013 .Dt MEMCMP 3 @@ -74,11 +74,11 @@ to compare cryptographic secrets, because the time it takes varies depending on how many bytes are the same, and thus leaks information about the two strings by a timing side channel. To compare secrets, hashes, message authentication codes, etc., use -.Xr consttime_bcmp 3 +.Xr consttime_memequal 3 instead. .Sh SEE ALSO .Xr bcmp 3 , -.Xr consttime_bcmp 3 , +.Xr consttime_memequal 3 , .Xr strcasecmp 3 , .Xr strcmp 3 , .Xr strcoll 3 , diff --git a/lib/libc/string/memset.3 b/lib/libc/string/memset.3 index 777b167e804..bc51985b354 100644 --- a/lib/libc/string/memset.3 +++ b/lib/libc/string/memset.3 @@ -30,7 +30,7 @@ .\" SUCH DAMAGE. .\" .\" from: @(#)memset.3 8.1 (Berkeley) 6/4/93 -.\" $NetBSD: memset.3,v 1.10 2013/06/23 16:44:06 riastradh Exp $ +.\" $NetBSD: memset.3,v 1.11 2013/06/24 04:21:20 riastradh Exp $ .\" .Dd June 23, 2013 .Dt MEMSET 3 @@ -67,10 +67,10 @@ if it can prove that the string will not be used by the program again, for example if it is allocated on the stack and about to out of scope. If you want to guarantee that zeros are written to memory, for example to sanitize a buffer holding a cryptographic secret, use -.Xr explicit_bzero . +.Xr explicit_memset . .Sh SEE ALSO .Xr bzero 3 , -.Xr explicit_bzero 3 , +.Xr explicit_memset 3 , .Xr swab 3 .Sh STANDARDS The -- cgit