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)
|
.\" %%%LICENSE_START(VERBATIM)
|
||||||
.\" Permission is granted to make and distribute verbatim copies of this
|
.\" 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.
|
.\" the source, must acknowledge the copyright and authors of this work.
|
||||||
.\" %%%LICENSE_END
|
.\" %%%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"
|
.TH BZERO 3 2015-03-02 "Linux" "Linux Programmer's Manual"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
bzero \- write zero-valued bytes
|
bzero, explicit_bzero \- zero a byte string
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.nf
|
.nf
|
||||||
.B #include <strings.h>
|
.B #include <strings.h>
|
||||||
.sp
|
.sp
|
||||||
.BI "void bzero(void *" s ", size_t " n );
|
.BI "void bzero(void *" s ", size_t " n );
|
||||||
|
|
||||||
|
.BI "void explicit_bzero(void *" s ", size_t " n );
|
||||||
.fi
|
.fi
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
The
|
The
|
||||||
.BR bzero ()
|
.BR bzero ()
|
||||||
function sets the first
|
function erases the data in the
|
||||||
.I n
|
.I n
|
||||||
bytes of the area starting at
|
bytes of the memory starting at the location pointed to by
|
||||||
.I s
|
.IR s ,
|
||||||
to zero (bytes containing \(aq\\0\(aq).
|
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
|
.SH RETURN VALUE
|
||||||
None.
|
None.
|
||||||
|
.SH VERSIONS
|
||||||
|
.BR explicit_bzero ()
|
||||||
|
first appeared in glibc 2.25.
|
||||||
.SH ATTRIBUTES
|
.SH ATTRIBUTES
|
||||||
For an explanation of the terms used in this section, see
|
For an explanation of the terms used in this section, see
|
||||||
.BR attributes (7).
|
.BR attributes (7).
|
||||||
|
@ -56,16 +64,109 @@ lb lb lb
|
||||||
l l l.
|
l l l.
|
||||||
Interface Attribute Value
|
Interface Attribute Value
|
||||||
T{
|
T{
|
||||||
.BR bzero ()
|
.BR bzero (),
|
||||||
|
.br
|
||||||
|
.BR explicit_bzero ()
|
||||||
T} Thread safety MT-Safe
|
T} Thread safety MT-Safe
|
||||||
.TE
|
.TE
|
||||||
.SH CONFORMING TO
|
.SH CONFORMING TO
|
||||||
4.3BSD.
|
The
|
||||||
This function is deprecated (marked as LEGACY in POSIX.1-2001): use
|
.BR bzero ()
|
||||||
|
function is deprecated (marked as LEGACY in POSIX.1-2001); use
|
||||||
.BR memset (3)
|
.BR memset (3)
|
||||||
in new programs.
|
in new programs.
|
||||||
POSIX.1-2008 removes the specification of
|
POSIX.1-2008 removes the specification of
|
||||||
.BR bzero ().
|
.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
|
.SH SEE ALSO
|
||||||
.BR bstring (3),
|
.BR bstring (3),
|
||||||
.BR memset (3),
|
.BR memset (3),
|
||||||
|
|
Loading…
Reference in New Issue