1 files changed, 158 insertions, 0 deletions
diff --git a/man/man3/bzero.3 b/man/man3/bzero.3
new file mode 100644
index 0000000..a50746f
--- /dev/null
+++ b/man/man3/bzero.3
@@ -0,0 +1,158 @@
+'\" t
+.\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH bzero 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+bzero, explicit_bzero \- zero a byte string
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <strings.h>
+.P
+.BI "void bzero(void " s [. n "], size_t " n );
+.P
+.B #include <string.h>
+.P
+.BI "void explicit_bzero(void " s [. n "], size_t " n );
+.fi
+.SH DESCRIPTION
+The
+.BR bzero ()
+function erases the data in the
+.I n
+bytes of the memory starting at the location pointed to by
+.IR s ,
+by writing zeros (bytes containing \[aq]\e0\[aq]) to that area.
+.P
+The
+.BR explicit_bzero ()
+function performs the same task as
+.BR bzero ().
+It differs from
+.BR bzero ()
+in that it guarantees that compiler optimizations will not remove the
+erase operation if the compiler deduces that the operation is "unnecessary".
+.SH RETURN VALUE
+None.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR bzero (),
+.BR explicit_bzero ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+None.
+.SH HISTORY
+.TP
+.BR explicit_bzero ()
+glibc 2.25.
+.IP
+The
+.BR explicit_bzero ()
+function is a nonstandard extension that is also present on some of the BSDs.
+Some other implementations have a similar function, such as
+.BR memset_explicit ()
+or
+.BR memset_s ().
+.TP
+.BR bzero ()
+4.3BSD.
+.IP
+Marked as LEGACY in POSIX.1-2001.
+Removed in POSIX.1-2008.
+.SH NOTES
+The
+.BR explicit_bzero ()
+function addresses a problem that security-conscious applications
+may run into when using
+.BR bzero ():
+if the compiler can deduce that the location to be zeroed will
+never again be touched by a
+.I correct
+program, then it may remove the
+.BR bzero ()
+call altogether.
+This is a problem if the intent of the
+.BR bzero ()
+call was to erase sensitive data (e.g., passwords)
+to prevent the possibility that the data was leaked
+by an incorrect or compromised program.
+Calls to
+.BR explicit_bzero ()
+are never optimized away by the compiler.
+.P
+The
+.BR explicit_bzero ()
+function does not solve all problems associated with erasing sensitive data:
+.IP \[bu] 3
+The
+.BR explicit_bzero ()
+function does
+.I not
+guarantee that sensitive data is completely erased from memory.
+(The same is true of
+.BR bzero ().)
+For example, there may be copies of the sensitive data in
+a register and in "scratch" stack areas.
+The
+.BR explicit_bzero ()
+function is not aware of these copies, and can't erase them.
+.IP \[bu]
+In some circumstances,
+.BR explicit_bzero ()
+can
+.I decrease
+security.
+If the compiler determined that the variable containing the
+sensitive data could be optimized to be stored in a register
+(because it is small enough to fit in a register,
+and no operation other than the
+.BR explicit_bzero ()
+call would need to take the address of the variable), then the
+.BR explicit_bzero ()
+call will force the data to be copied from the register
+to a location in RAM that is then immediately erased
+(while the copy in the register remains unaffected).
+The problem here is that data in RAM is more likely to be exposed
+by a bug than data in a register, and thus the
+.BR explicit_bzero ()
+call creates a brief time window where the sensitive data is more
+vulnerable than it would otherwise have been
+if no attempt had been made to erase the data.
+.P
+Note that declaring the sensitive variable with the
+.B volatile
+qualifier does
+.I not
+eliminate the above problems.
+Indeed, it will make them worse, since, for example,
+it may force a variable that would otherwise have been optimized
+into a register to instead be maintained in (more vulnerable)
+RAM for its entire lifetime.
+.P
+Notwithstanding the above details, for security-conscious applications, using
+.BR explicit_bzero ()
+is generally preferable to not using it.
+The developers of
+.BR explicit_bzero ()
+anticipate that future compilers will recognize calls to
+.BR explicit_bzero ()
+and take steps to ensure that all copies of the sensitive data are erased,
+including copies in registers or in "scratch" stack areas.
+.SH SEE ALSO
+.BR bstring (3),
+.BR memset (3),
+.BR swab (3)