| .\" 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 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) |