|
Packit |
7cfc04 |
.\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH BZERO 3 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
bzero, explicit_bzero \- zero a byte string
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <strings.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "void bzero(void *" s ", size_t " n );
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.B #include <string.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "void explicit_bzero(void *" s ", size_t " n );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR bzero ()
|
|
Packit |
7cfc04 |
function erases the data in the
|
|
Packit |
7cfc04 |
.I n
|
|
Packit |
7cfc04 |
bytes of the memory starting at the location pointed to by
|
|
Packit |
7cfc04 |
.IR s ,
|
|
Packit |
7cfc04 |
by writing zeroes (bytes containing \(aq\\0\(aq) to that area.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
function performs the same task as
|
|
Packit |
7cfc04 |
.BR bzero ().
|
|
Packit |
7cfc04 |
It differs from
|
|
Packit |
7cfc04 |
.BR bzero ()
|
|
Packit |
7cfc04 |
in that it guarantees that compiler optimizations will not remove the
|
|
Packit |
7cfc04 |
erase operation if the compiler deduces that the operation is "unnecessary".
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
first appeared in glibc 2.25.
|
|
Packit |
7cfc04 |
.SH ATTRIBUTES
|
|
Packit |
7cfc04 |
For an explanation of the terms used in this section, see
|
|
Packit |
7cfc04 |
.BR attributes (7).
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
allbox;
|
|
Packit |
7cfc04 |
lb lb lb
|
|
Packit |
7cfc04 |
l l l.
|
|
Packit |
7cfc04 |
Interface Attribute Value
|
|
Packit |
7cfc04 |
T{
|
|
Packit |
7cfc04 |
.BR bzero (),
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
T} Thread safety MT-Safe
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR bzero ()
|
|
Packit |
7cfc04 |
function is deprecated (marked as LEGACY in POSIX.1-2001); use
|
|
Packit |
7cfc04 |
.BR memset (3)
|
|
Packit |
7cfc04 |
in new programs.
|
|
Packit |
7cfc04 |
POSIX.1-2008 removes the specification of
|
|
Packit |
7cfc04 |
.BR bzero ().
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR bzero ()
|
|
Packit |
7cfc04 |
function first appeared in 4.3BSD.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
function is a nonstandard extension that is also present on some of the BSDs.
|
|
Packit |
7cfc04 |
Some other implementations have a similar function, such as
|
|
Packit |
7cfc04 |
.BR memset_explicit ()
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR memset_s ().
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
function addresses a problem that security-conscious applications
|
|
Packit |
7cfc04 |
may run into when using
|
|
Packit |
7cfc04 |
.BR bzero ():
|
|
Packit |
7cfc04 |
if the compiler can deduce that the location to zeroed will
|
|
Packit |
7cfc04 |
never again be touched by a
|
|
Packit |
7cfc04 |
.I correct
|
|
Packit |
7cfc04 |
program, then it may remove the
|
|
Packit |
7cfc04 |
.BR bzero ()
|
|
Packit |
7cfc04 |
call altogether.
|
|
Packit |
7cfc04 |
This is a problem if the intent of the
|
|
Packit |
7cfc04 |
.BR bzero ()
|
|
Packit |
7cfc04 |
call was to erase sensitive data (e.g., passwords)
|
|
Packit |
7cfc04 |
to prevent the possibility that the data was leaked
|
|
Packit |
7cfc04 |
by an incorrect or compromised program.
|
|
Packit |
7cfc04 |
Calls to
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
are never optimized away by the compiler.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
function does not solve all problems associated with erasing sensitive data:
|
|
Packit |
7cfc04 |
.IP 1. 3
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
function does
|
|
Packit |
7cfc04 |
.I not
|
|
Packit |
7cfc04 |
guarantee that sensitive data is completely erased from memory.
|
|
Packit |
7cfc04 |
(The same is true of
|
|
Packit |
7cfc04 |
.BR bzero ().)
|
|
Packit |
7cfc04 |
For example, there may be copies of the sensitive data in
|
|
Packit |
7cfc04 |
a register and in "scratch" stack areas.
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
function is not aware of these copies, and can't erase them.
|
|
Packit |
7cfc04 |
.IP 2.
|
|
Packit |
7cfc04 |
In some circumstances,
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
can
|
|
Packit |
7cfc04 |
.I decrease
|
|
Packit |
7cfc04 |
security.
|
|
Packit |
7cfc04 |
If the compiler determined that the variable containing the
|
|
Packit |
7cfc04 |
sensitive data could be optimized to be stored in a register
|
|
Packit |
7cfc04 |
(because it is small enough to fit in a register,
|
|
Packit |
7cfc04 |
and no operation other than the
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
call would need to take the address of the variable), then the
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
call will force the data to be copied from the register
|
|
Packit |
7cfc04 |
to a location in RAM that is then immediately erased
|
|
Packit |
7cfc04 |
(while the copy in the register remains unaffected).
|
|
Packit |
7cfc04 |
The problem here is that data in RAM is more likely to be exposed
|
|
Packit |
7cfc04 |
by a bug than data in a register, and thus the
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
call creates a brief time window where the sensitive data is more
|
|
Packit |
7cfc04 |
vulnerable than it would otherwise have been
|
|
Packit |
7cfc04 |
if no attempt had been made to erase the data.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Note that declaring the sensitive variable with the
|
|
Packit |
7cfc04 |
.B volatile
|
|
Packit |
7cfc04 |
qualifier does
|
|
Packit |
7cfc04 |
.I not
|
|
Packit |
7cfc04 |
eliminate the above problems.
|
|
Packit |
7cfc04 |
Indeed, it will make them worse, since, for example,
|
|
Packit |
7cfc04 |
it may force a variable that would otherwise have been optimized
|
|
Packit |
7cfc04 |
into a register to instead be maintained in (more vulnerable)
|
|
Packit |
7cfc04 |
RAM for its entire lifetime.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Notwithstanding the above details, for security-conscious applications, using
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
is generally preferable to not using it.
|
|
Packit |
7cfc04 |
The developers of
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
anticipate that future compilers will recognize calls to
|
|
Packit |
7cfc04 |
.BR explicit_bzero ()
|
|
Packit |
7cfc04 |
and take steps to ensure that all copies of the sensitive data are erased,
|
|
Packit |
7cfc04 |
including copies in registers or in "scratch" stack areas.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR bstring (3),
|
|
Packit |
7cfc04 |
.BR memset (3),
|
|
Packit |
7cfc04 |
.BR swab (3)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|