diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-04-26 15:06:49 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-05-02 01:24:19 +0200 |
| commit | dcde2f70372b49ec43efc5db864c9ff585d0a2dd (patch) | |
| tree | 78b9b7425130e4a5858e4c01a524d802423879ed /man/man3/bzero.3 | |
| parent | 12aca537ce78a41bbcdaf485209691e10f8002d7 (diff) | |
| download | man-pages-dcde2f70372b49ec43efc5db864c9ff585d0a2dd.tar.gz | |
man/, share/mk/: Move man*/ to man/
This is a scripted change:
$ mkdir man/;
$ mv man* man/;
$ ln -st . man/man*;
$ find share/mk/ -type f \
| xargs grep -l '^MANDIR *:=' \
| xargs sed -i '/^MANDIR *:=/s,$,/man,';
$ find share/mk/dist/ -type f \
| xargs grep -l man \
| xargs sed -i 's,man%,man/%,g';
Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/>
Cc: Petr Vorel <pvorel@suse.cz>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
Diffstat (limited to 'man/man3/bzero.3')
| -rw-r--r-- | man/man3/bzero.3 | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/man/man3/bzero.3 b/man/man3/bzero.3 new file mode 100644 index 0000000000..f6c0ca2f31 --- /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 (date) "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) |