[PATCH] explicit_bzero: new module

[Paul Eggert]

The explicit_bzero function has been added to glibc.
This module is intended to supports its use in GNU programs.
* doc/glibc-functions/explicit_bzero.texi, lib/explicit_bzero.c:
* m4/explicit_bzero.m4, modules/explicit_bzero:
New files.
* doc/gnulib.texi (Glibc string.h): Link to new doc.
* lib/string.in.h (explicit_bzero): Declare.
* m4/string_h.m4 (gl_HEADER_STRING_H_DEFAULTS): Add defaults for it.
* modules/string (string.h): Substitute its vars.
---
 ChangeLog                               | 13 +++++++++
 doc/glibc-functions/explicit_bzero.texi | 29 ++++++++++++++++++++
 doc/gnulib.texi                         |  2 ++
 lib/explicit_bzero.c                    | 48 +++++++++++++++++++++++++++++++++
 lib/string.in.h                         | 17 ++++++++++++
 m4/explicit_bzero.m4                    | 22 +++++++++++++++
 m4/string_h.m4                          |  2 ++
 modules/explicit_bzero                  | 29 ++++++++++++++++++++
 modules/string                          |  4 ++-
 9 files changed, 165 insertions(+), 1 deletion(-)
 create mode 100644 doc/glibc-functions/explicit_bzero.texi
 create mode 100644 lib/explicit_bzero.c
 create mode 100644 m4/explicit_bzero.m4
 create mode 100644 modules/explicit_bzero

diff --git a/ChangeLog b/ChangeLog
index 7865c05..c2e140f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2017-07-16  Paul Eggert  <address@hidden>
+
+       explicit_bzero: new module
+       The explicit_bzero function has been added to glibc.
+       This module is intended to supports its use in GNU programs.
+       * doc/glibc-functions/explicit_bzero.texi, lib/explicit_bzero.c:
+       * m4/explicit_bzero.m4, modules/explicit_bzero:
+       New files.
+       * doc/gnulib.texi (Glibc string.h): Link to new doc.
+       * lib/string.in.h (explicit_bzero): Declare.
+       * m4/string_h.m4 (gl_HEADER_STRING_H_DEFAULTS): Add defaults for it.
+       * modules/string (string.h): Substitute its vars.
+
 2017-07-16  Bruno Haible  <address@hidden>
 
        threadlib: Support static linking.
diff --git a/doc/glibc-functions/explicit_bzero.texi 
b/doc/glibc-functions/explicit_bzero.texi
new file mode 100644
index 0000000..b5e127b
--- /dev/null
+++ b/doc/glibc-functions/explicit_bzero.texi
@@ -0,0 +1,29 @@
address@hidden explicit_bzero
address@hidden @code{explicit_bzero}
address@hidden explicit_bzero
+
+Gnulib module: explicit_bzero
+
+The @code{explicit_bzero} function is an approximation to what is
+needed, and does not suffice in general to erase information.
+Although calling @code{explicit_bzero} should clear the memory in
+question, the information that was in memory may still be available
+elsewhere on the machine.  Proper implementation of information
+erasure requires support from levels below C code.
+
+Portability problems fixed by Gnulib:
address@hidden
address@hidden
+This function is missing on some platforms:
+glibc 2.24, FreeBSD 10, NetBSD 7.1, OpenBSD 5.4, macOS 10.12, Solaris 11.3,
+and many other systems.
address@hidden itemize
+
+Portability problems not fixed by Gnulib:
address@hidden
address@hidden
+Although the module's implementation should clear the memory on
+platforms compatible with GCC and on platforms using traditional
+linkers, it may not clear the memory on non-GCC platforms that use
+whole-program optimization.
address@hidden itemize
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index f4bbfcf..188ece6 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -5568,6 +5568,7 @@ This list of functions is sorted according to the header 
that declares them.
 @section Glibc Extensions to @code{<string.h>}
 
 @menu
+* explicit_bzero::
 * ffsl::
 * ffsll::
 * memfrob::
@@ -5582,6 +5583,7 @@ This list of functions is sorted according to the header 
that declares them.
 * strverscmp::
 @end menu
 
address@hidden glibc-functions/explicit_bzero.texi
 @include glibc-functions/ffsl.texi
 @include glibc-functions/ffsll.texi
 @include glibc-functions/memfrob.texi
diff --git a/lib/explicit_bzero.c b/lib/explicit_bzero.c
new file mode 100644
index 0000000..2cd391b
--- /dev/null
+++ b/lib/explicit_bzero.c
@@ -0,0 +1,48 @@
+/* Erasure of sensitive data, generic implementation.
+   Copyright (C) 2016-2017 Free Software Foundation, Inc.
+   This file is part of the GNU C Library.
+
+   The GNU C Library is free software; you can redistribute it and/or
+   modify it under the terms of the GNU Lesser General Public
+   License as published by the Free Software Foundation; either
+   version 2.1 of the License, or (at your option) any later version.
+
+   The GNU C Library is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   Lesser General Public License for more details.
+
+   You should have received a copy of the GNU Lesser General Public
+   License along with the GNU C Library; if not, see
+   <http://www.gnu.org/licenses/>.  */
+
+/* An assembler implementation of explicit_bzero can be created as an
+   assembler alias of an optimized bzero implementation.
+   Architecture-specific implementations also need to define
+   __explicit_bzero_chk.  */
+
+#if !_LIBC
+# include <config.h>
+#endif
+
+#include <string.h>
+
+/* glibc-internal users use __explicit_bzero_chk, and explicit_bzero
+   redirects to that.  */
+#undef explicit_bzero
+
+/* Set LEN bytes of S to 0.  The compiler will not delete a call to
+   this function, even if S is dead after the call.  */
+void
+explicit_bzero (void *s, size_t len)
+{
+#ifdef HAVE_EXPLICIT_MEMSET
+  explicit_memset (s, 0, len);
+#else
+  memset (s, '\0', len);
+# ifdef __GNUC__
+  /* Compiler barrier.  */
+  asm volatile ("" ::: "memory");
+# endif
+#endif
+}
diff --git a/lib/string.in.h b/lib/string.in.h
index bcc00cc..fa9518e 100644
--- a/lib/string.in.h
+++ b/lib/string.in.h
@@ -74,6 +74,23 @@
 /* The definition of _GL_WARN_ON_USE is copied here.  */
 
 
+/* Clear a block of memory.  The compiler will not delete a call to
+   this function, even if the block is dead after the call.  */
+#if @GNULIB_EXPLICIT_BZERO@
+# if ! @HAVE_EXPLICIT_BZERO@
+_GL_FUNCDECL_SYS (explicit_bzero, void,
+                  (void *__dest, size_t __n) _GL_ARG_NONNULL ((1)));
+# endif
+_GL_CXXALIAS_SYS (explicit_bzero, void, (void *__dest, size_t __n));
+_GL_CXXALIASWARN (explicit_bzero);
+#elif defined GNULIB_POSIXCHECK
+# undef explicit_bzero
+# if HAVE_RAW_DECL_EXPLICIT_BZERO
+_GL_WARN_ON_USE (explicit_bzero, "explicit_bzero is unportable - "
+                 "use gnulib module explicit_bzero for portability");
+# endif
+#endif
+
 /* Find the index of the least-significant set bit.  */
 #if @GNULIB_FFSL@
 # if address@hidden@
diff --git a/m4/explicit_bzero.m4 b/m4/explicit_bzero.m4
new file mode 100644
index 0000000..f9dc678
--- /dev/null
+++ b/m4/explicit_bzero.m4
@@ -0,0 +1,22 @@
+dnl Copyright 2017 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
+AC_DEFUN([gl_FUNC_EXPLICIT_BZERO],
+[
+  AC_REQUIRE([gl_HEADER_STRING_H_DEFAULTS])
+
+  dnl Persuade glibc <string.h> to declare explicit_bzero.
+  AC_REQUIRE([AC_USE_SYSTEM_EXTENSIONS])
+
+  AC_CHECK_FUNCS_ONCE([explicit_bzero])
+  if test $ac_cv_func_explicit_bzero = no; then
+    HAVE_EXPLICIT_BZERO=0
+  fi
+])
+
+AC_DEFUN([gl_PREREQ_EXPLICIT_BZERO],
+[
+  AC_CHECK_FUNCS([explicit_memset])
+])
diff --git a/m4/string_h.m4 b/m4/string_h.m4
index 3d2ad22..ac6311f 100644
--- a/m4/string_h.m4
+++ b/m4/string_h.m4
@@ -43,6 +43,7 @@ AC_DEFUN([gl_STRING_MODULE_INDICATOR],
 
 AC_DEFUN([gl_HEADER_STRING_H_DEFAULTS],
 [
+  GNULIB_EXPLICIT_BZERO=0; AC_SUBST([GNULIB_EXPLICIT_BZERO])
   GNULIB_FFSL=0;        AC_SUBST([GNULIB_FFSL])
   GNULIB_FFSLL=0;       AC_SUBST([GNULIB_FFSLL])
   GNULIB_MEMCHR=0;      AC_SUBST([GNULIB_MEMCHR])
@@ -82,6 +83,7 @@ AC_DEFUN([gl_HEADER_STRING_H_DEFAULTS],
   GNULIB_STRVERSCMP=0;  AC_SUBST([GNULIB_STRVERSCMP])
   HAVE_MBSLEN=0;        AC_SUBST([HAVE_MBSLEN])
   dnl Assume proper GNU behavior unless another module says otherwise.
+  HAVE_EXPLICIT_BZERO=1;        AC_SUBST([HAVE_EXPLICIT_BZERO])
   HAVE_FFSL=1;                  AC_SUBST([HAVE_FFSL])
   HAVE_FFSLL=1;                 AC_SUBST([HAVE_FFSLL])
   HAVE_MEMCHR=1;                AC_SUBST([HAVE_MEMCHR])
diff --git a/modules/explicit_bzero b/modules/explicit_bzero
new file mode 100644
index 0000000..81d41d1
--- /dev/null
+++ b/modules/explicit_bzero
@@ -0,0 +1,29 @@
+Description:
+Erase sensitive data from a buffer.
+
+Files:
+lib/explicit_bzero.c
+m4/explicit_bzero.m4
+
+Depends-on:
+extensions
+string
+
+configure.ac:
+gl_FUNC_EXPLICIT_BZERO
+if test $HAVE_EXPLICIT_BZERO = 0; then
+  AC_LIBOBJ([explicit_bzero])
+  gl_PREREQ_EXPLICIT_BZERO
+fi
+gl_STRING_MODULE_INDICATOR([explicit_bzero])
+
+Makefile.am:
+
+Include:
+<string.h>
+
+License:
+LGPLv3+
+
+Maintainer:
+all
diff --git a/modules/string b/modules/string
index c7b942a..8a07da5 100644
--- a/modules/string
+++ b/modules/string
@@ -30,6 +30,7 @@ string.h: string.in.h $(top_builddir)/config.status 
$(CXXDEFS_H) $(ARG_NONNULL_H
              -e 's|@''PRAGMA_SYSTEM_HEADER''@|@PRAGMA_SYSTEM_HEADER@|g' \
              -e 's|@''PRAGMA_COLUMNS''@|@PRAGMA_COLUMNS@|g' \
              -e 's|@''NEXT_STRING_H''@|$(NEXT_STRING_H)|g' \
+             -e 's/@''GNULIB_EXPLICIT_BZERO''@/$(GNULIB_EXPLICIT_BZERO)/g' \
              -e 's/@''GNULIB_FFSL''@/$(GNULIB_FFSL)/g' \
              -e 's/@''GNULIB_FFSLL''@/$(GNULIB_FFSLL)/g' \
              -e 's/@''GNULIB_MBSLEN''@/$(GNULIB_MBSLEN)/g' \
@@ -68,7 +69,8 @@ string.h: string.in.h $(top_builddir)/config.status 
$(CXXDEFS_H) $(ARG_NONNULL_H
              -e 's/@''GNULIB_STRSIGNAL''@/$(GNULIB_STRSIGNAL)/g' \
              -e 's/@''GNULIB_STRVERSCMP''@/$(GNULIB_STRVERSCMP)/g' \
              < $(srcdir)/string.in.h | \
-         sed -e 's|@''HAVE_FFSL''@|$(HAVE_FFSL)|g' \
+         sed -e 's|@''HAVE_EXPLICIT_BZERO''@|$(HAVE_EXPLICIT_BZERO)|g' \
+             -e 's|@''HAVE_FFSL''@|$(HAVE_FFSL)|g' \
              -e 's|@''HAVE_FFSLL''@|$(HAVE_FFSLL)|g' \
              -e 's|@''HAVE_MBSLEN''@|$(HAVE_MBSLEN)|g' \
              -e 's|@''HAVE_MEMCHR''@|$(HAVE_MEMCHR)|g' \
-- 
2.7.4