mirror of https://github.com/mkerrisk/man-pages
180 lines
5.2 KiB
Groff
180 lines
5.2 KiB
Groff
.\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH BZERO 3 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
bzero, explicit_bzero \- zero a byte string
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <strings.h>
|
|
.PP
|
|
.BI "void bzero(void *" s ", size_t " n );
|
|
.PP
|
|
.B #include <string.h>
|
|
.PP
|
|
.BI "void explicit_bzero(void *" s ", 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.
|
|
.PP
|
|
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 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).
|
|
.ad l
|
|
.nh
|
|
.TS
|
|
allbox;
|
|
lbx lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR bzero (),
|
|
.BR explicit_bzero ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.hy
|
|
.ad
|
|
.sp 1
|
|
.SH CONFORMING TO
|
|
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.
|
|
.PP
|
|
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 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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)
|