| blob | d43abe5bbe4abd3ea87fdbe459bcf32276f5917a |
1 .\" Copyright (C) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\"
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
7 .\"
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
12 .\"
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
19 .\" professionally.
20 .\"
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" %%%LICENSE_END
24 .\"
25 .TH BZERO 3 2021-03-22 "Linux" "Linux Programmer's Manual"
26 .SH NAME
27 bzero, explicit_bzero \- zero a byte string
28 .SH SYNOPSIS
29 .nf
30 .B #include <strings.h>
31 .PP
32 .BI "void bzero(void *" s ", size_t " n );
33 .PP
34 .B #include <string.h>
35 .PP
36 .BI "void explicit_bzero(void *" s ", size_t " n );
37 .fi
38 .SH DESCRIPTION
39 The
40 .BR bzero ()
41 function erases the data in the
42 .I n
43 bytes of the memory starting at the location pointed to by
44 .IR s ,
45 by writing zeros (bytes containing \(aq\e0\(aq) to that area.
46 .PP
47 The
48 .BR explicit_bzero ()
49 function performs the same task as
50 .BR bzero ().
51 It differs from
52 .BR bzero ()
53 in that it guarantees that compiler optimizations will not remove the
54 erase operation if the compiler deduces that the operation is "unnecessary".
55 .SH RETURN VALUE
56 None.
57 .SH VERSIONS
58 .BR explicit_bzero ()
59 first appeared in glibc 2.25.
60 .SH ATTRIBUTES
61 For an explanation of the terms used in this section, see
62 .BR attributes (7).
63 .ad l
64 .nh
65 .TS
66 allbox;
67 lbx lb lb
68 l l l.
69 Interface Attribute Value
70 T{
71 .BR bzero (),
72 .BR explicit_bzero ()
73 T} Thread safety MT-Safe
74 .TE
75 .hy
76 .ad
77 .sp 1
78 .SH CONFORMING TO
79 The
80 .BR bzero ()
81 function is deprecated (marked as LEGACY in POSIX.1-2001); use
82 .BR memset (3)
83 in new programs.
84 POSIX.1-2008 removes the specification of
85 .BR bzero ().
86 The
87 .BR bzero ()
88 function first appeared in 4.3BSD.
89 .PP
90 The
91 .BR explicit_bzero ()
92 function is a nonstandard extension that is also present on some of the BSDs.
93 Some other implementations have a similar function, such as
94 .BR memset_explicit ()
95 or
96 .BR memset_s ().
97 .SH NOTES
98 The
99 .BR explicit_bzero ()
100 function addresses a problem that security-conscious applications
101 may run into when using
102 .BR bzero ():
103 if the compiler can deduce that the location to be zeroed will
104 never again be touched by a
105 .I correct
106 program, then it may remove the
107 .BR bzero ()
108 call altogether.
109 This is a problem if the intent of the
110 .BR bzero ()
111 call was to erase sensitive data (e.g., passwords)
112 to prevent the possibility that the data was leaked
113 by an incorrect or compromised program.
114 Calls to
115 .BR explicit_bzero ()
116 are never optimized away by the compiler.
117 .PP
118 The
119 .BR explicit_bzero ()
120 function does not solve all problems associated with erasing sensitive data:
121 .IP 1. 3
122 The
123 .BR explicit_bzero ()
124 function does
125 .I not
126 guarantee that sensitive data is completely erased from memory.
127 (The same is true of
128 .BR bzero ().)
129 For example, there may be copies of the sensitive data in
130 a register and in "scratch" stack areas.
131 The
132 .BR explicit_bzero ()
133 function is not aware of these copies, and can't erase them.
134 .IP 2.
135 In some circumstances,
136 .BR explicit_bzero ()
137 can
138 .I decrease
139 security.
140 If the compiler determined that the variable containing the
141 sensitive data could be optimized to be stored in a register
142 (because it is small enough to fit in a register,
143 and no operation other than the
144 .BR explicit_bzero ()
145 call would need to take the address of the variable), then the
146 .BR explicit_bzero ()
147 call will force the data to be copied from the register
148 to a location in RAM that is then immediately erased
149 (while the copy in the register remains unaffected).
150 The problem here is that data in RAM is more likely to be exposed
151 by a bug than data in a register, and thus the
152 .BR explicit_bzero ()
153 call creates a brief time window where the sensitive data is more
154 vulnerable than it would otherwise have been
155 if no attempt had been made to erase the data.
156 .PP
157 Note that declaring the sensitive variable with the
158 .B volatile
159 qualifier does
160 .I not
161 eliminate the above problems.
162 Indeed, it will make them worse, since, for example,
163 it may force a variable that would otherwise have been optimized
164 into a register to instead be maintained in (more vulnerable)
165 RAM for its entire lifetime.
166 .PP
167 Notwithstanding the above details, for security-conscious applications, using
168 .BR explicit_bzero ()
169 is generally preferable to not using it.
170 The developers of
171 .BR explicit_bzero ()
172 anticipate that future compilers will recognize calls to
173 .BR explicit_bzero ()
174 and take steps to ensure that all copies of the sensitive data are erased,
175 including copies in registers or in "scratch" stack areas.
176 .SH SEE ALSO
177 .BR bstring (3),
178 .BR memset (3),
179 .BR swab (3)