mirror of https://github.com/mkerrisk/man-pages
bzero.3: Document explicit_bzero() (new in glibc 2.25)
Also, reword the description of bzero somewhat. By now, over time, I've completely rewritten the page, so change the copyright as well. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
879091c911
commit
55e04d2370
131
man3/bzero.3
131
man3/bzero.3
|
@ -1,4 +1,4 @@
|
|||
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
||||
.\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
|
||||
.\"
|
||||
.\" %%%LICENSE_START(VERBATIM)
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
|
@ -22,31 +22,39 @@
|
|||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\" %%%LICENSE_END
|
||||
.\"
|
||||
.\" References consulted:
|
||||
.\" Linux libc source code
|
||||
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
||||
.\" 386BSD man pages
|
||||
.\" Modified Sat Jul 24 21:28:17 1993 by Rik Faith <faith@cs.unc.edu>
|
||||
.\" Modified Tue Oct 22 23:49:37 1996 by Eric S. Raymond <esr@thyrsus.com>
|
||||
.TH BZERO 3 2015-03-02 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
bzero \- write zero-valued bytes
|
||||
bzero, explicit_bzero \- zero a byte string
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B #include <strings.h>
|
||||
.sp
|
||||
.BI "void bzero(void *" s ", size_t " n );
|
||||
|
||||
.BI "void explicit_bzero(void *" s ", size_t " n );
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.BR bzero ()
|
||||
function sets the first
|
||||
function erases the data in the
|
||||
.I n
|
||||
bytes of the area starting at
|
||||
.I s
|
||||
to zero (bytes containing \(aq\\0\(aq).
|
||||
bytes of the memory starting at the location pointed to by
|
||||
.IR s ,
|
||||
by writing zeroes (bytes containing \(aq\\0\(aq) to that area.
|
||||
|
||||
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 option if the compiler deduces that the operation is "unnecessary".
|
||||
.SH RETURN VALUE
|
||||
None.
|
||||
.SH VERSIONS
|
||||
.BR explicit_bzero ()
|
||||
first appeared in glibc 2.25.
|
||||
.SH ATTRIBUTES
|
||||
For an explanation of the terms used in this section, see
|
||||
.BR attributes (7).
|
||||
|
@ -56,16 +64,109 @@ lb lb lb
|
|||
l l l.
|
||||
Interface Attribute Value
|
||||
T{
|
||||
.BR bzero ()
|
||||
.BR bzero (),
|
||||
.br
|
||||
.BR explicit_bzero ()
|
||||
T} Thread safety MT-Safe
|
||||
.TE
|
||||
.SH CONFORMING TO
|
||||
4.3BSD.
|
||||
This function is deprecated (marked as LEGACY in POSIX.1-2001): use
|
||||
The
|
||||
.BR bzero ()
|
||||
function is deprecated (marked as LEGACY in POSIX.1-2001); use
|
||||
.BR memset (3)
|
||||
in new programs.
|
||||
POSIX.1-2008 removes the specification of
|
||||
.BR bzero ().
|
||||
The
|
||||
.BR bzero ()
|
||||
function first appeared in 4.3BSD.
|
||||
|
||||
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 ().
|
||||
.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 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.
|
||||
|
||||
The
|
||||
.BR explicit_bzero ()
|
||||
function does not solve all problems associated with erasing sensitive data:
|
||||
.IP 1. 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 2.
|
||||
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.
|
||||
.PP
|
||||
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.
|
||||
|
||||
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),
|
||||
|
|
Loading…
Reference in New Issue