-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcrypt.3.html
336 lines (333 loc) · 18 KB
/
crypt.3.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file. Do not edit.
Written and revised by Solar Designer <solar at openwall.com> in 2000-2011.
Revised by Zack Weinberg <zackw at panix.com> in 2017.
Converted to mdoc format by Zack Weinberg in 2018.
No copyright is claimed, and this man page is hereby placed in the public
domain. In case this attempt to disclaim copyright and place the man page
in the public domain is deemed null and void, then the man page is
Copyright 2000-2011 Solar Designer, 2017, 2018 Zack Weinberg, and it is
hereby released to the general public under the following terms:
Redistribution and use in source and binary forms, with or without
modification, are permitted.
There's ABSOLUTELY NO WARRANTY, express or implied.
-->
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
<title>CRYPT(3)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">CRYPT(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">CRYPT(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">crypt</code>, <code class="Nm">crypt_r</code>,
<code class="Nm">crypt_rn</code>, <code class="Nm">crypt_ra</code> —
<span class="Nd">passphrase hashing</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1>
<p class="Pp"><span class="Lb">Crypt Library (libcrypt, -lcrypt)</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In" href="%N.%S.html">crypt.h</a>></code></p>
<p class="Pp"><var class="Ft">char *</var>
<br/>
<code class="Fn">crypt</code>(<var class="Fa">const char *phrase</var>,
<var class="Fa">const char *setting</var>);</p>
<p class="Pp"><var class="Ft">char *</var>
<br/>
<code class="Fn">crypt_r</code>(<var class="Fa">const char *phrase</var>,
<var class="Fa">const char *setting</var>, <var class="Fa">struct crypt_data
*data</var>);</p>
<p class="Pp"><var class="Ft">char *</var>
<br/>
<code class="Fn">crypt_rn</code>(<var class="Fa">const char *phrase</var>,
<var class="Fa">const char *setting</var>, <var class="Fa">struct crypt_data
*data</var>, <var class="Fa">int size</var>);</p>
<p class="Pp"><var class="Ft">char *</var>
<br/>
<code class="Fn">crypt_ra</code>(<var class="Fa">const char *phrase</var>,
<var class="Fa">const char *setting</var>, <var class="Fa">void
**data</var>, <var class="Fa">int *size</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">crypt</code>,
<code class="Nm">crypt_r</code>, <code class="Nm">crypt_rn</code>, and
<code class="Nm">crypt_ra</code> functions irreversibly “hash”
<var class="Fa">phrase</var> for storage in the system password database
(<a class="Xr" href="shadow.5.html">shadow(5)</a>) using a cryptographic
“hashing method.” The result of this operation is called a
“hashed passphrase” or just a “hash.” Hashing
methods are described in <a class="Xr" href="crypt.5.html">crypt(5)</a>.</p>
<p class="Pp"><var class="Fa">setting</var> controls which hashing method to
use, and also supplies various parameters to the chosen method, most
importantly a random “salt” which ensures that no two stored
hashes are the same, even if the <var class="Fa">phrase</var> strings are
the same.</p>
<p class="Pp">The <var class="Fa">data</var> argument to
<code class="Nm">crypt_r</code> is a structure of type
<var class="Vt">struct crypt_data</var>. It has at least these fields:</p>
<div class="Bd Pp Bd-indent Li">
<pre>struct crypt_data {
char output[CRYPT_OUTPUT_SIZE];
char setting[CRYPT_OUTPUT_SIZE];
char input[CRYPT_MAX_PASSPHRASE_SIZE];
char initialized;
};</pre>
</div>
<p class="Pp">Upon a successful return from <code class="Nm">crypt_r</code>, the
hashed passphrase will be stored in <var class="Fa">output</var>.
Applications are encouraged, but not required, to use the
<var class="Fa">input</var> and <var class="Fa">setting</var> fields to
store the strings that they will pass as <var class="Fa">input phrase</var>
and <var class="Fa">setting</var> to <code class="Nm">crypt_r</code>. This
will make it easier to erase all sensitive data after it is no longer
needed.</p>
<p class="Pp" id="crypt_r">The <var class="Fa">initialized</var> field must be
set to zero before the first time a <var class="Vt">struct crypt_data</var>
object is first used in a call to
<a class="permalink" href="#crypt_r"><code class="Fn">crypt_r</code></a>().
We recommend zeroing the entire object, not just
<var class="Fa">initialized</var> and not just the documented fields, before
the first use. (Of course, do this before storing anything in
<var class="Fa">setting</var> and <var class="Fa">input</var>.)</p>
<p class="Pp">The <var class="Fa">data</var> argument to
<code class="Nm">crypt_rn</code> should also point to a
<var class="Vt">struct crypt_data</var> object, and
<var class="Fa">size</var> should be the size of that object, cast to
<var class="Vt">int</var>. When used with <code class="Nm">crypt_rn</code>,
the entire <var class="Fa">data</var> object (except for the
<var class="Fa">input</var> and <var class="Fa">setting</var> fields) must
be zeroed before its first use; this is not just a recommendation, as it is
for <code class="Nm">crypt_r</code>. Otherwise, the fields of the object
have the same uses that they do for <code class="Nm">crypt_r</code>.</p>
<p class="Pp">On the first call to <code class="Nm">crypt_ra</code>,
<var class="Fa">data</var> should be the address of a <var class="Vt">void
*</var> variable set to NULL, and <var class="Fa">size</var> should be the
address of an <var class="Vt">int</var> variable set to zero.
<code class="Nm">crypt_ra</code> will allocate and initialize a
<var class="Vt">struct crypt_data</var> object, using
<a class="Xr" href="malloc.3.html">malloc(3)</a>, and write its address and
size into the variables pointed to by <var class="Fa">data</var> and
<var class="Fa">size</var>. These can be reused in subsequent calls. After
the application is done hashing passphrases, it should deallocate the
<var class="Vt">struct crypt_data</var> object using
<a class="Xr" href="free.3.html">free(3)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">Upon successful completion, <code class="Nm">crypt</code>,
<code class="Nm">crypt_r</code>, <code class="Nm">crypt_rn</code>, and
<code class="Nm">crypt_ra</code> return a pointer to a string which encodes
both the hashed passphrase, and the settings that were used to encode it.
This string is directly usable as <var class="Fa">setting</var> in other
calls to <code class="Nm">crypt</code>, <code class="Nm">crypt_r</code>,
<code class="Nm">crypt_rn</code>, and <code class="Nm">crypt_ra</code>, and
as <var class="Fa">prefix</var> in calls to
<code class="Nm">crypt_gensalt</code>,
<code class="Nm">crypt_gensalt_rn</code>, and
<code class="Nm">crypt_gensalt_ra</code>. It will be entirely printable
ASCII, and will not contain whitespace or the characters
‘<code class="Li">:</code>’,
‘<code class="Li">;</code>’,
‘<code class="Li">*</code>’,
‘<code class="Li">!</code>’, or
‘<code class="Li">\</code>’. See
<a class="Xr" href="crypt.5.html">crypt(5)</a> for more detail on the format
of hashed passphrases.</p>
<p class="Pp"><code class="Nm">crypt</code> places its result in a static
storage area, which will be overwritten by subsequent calls to
<code class="Nm">crypt</code>. It is not safe to call
<code class="Nm">crypt</code> from multiple threads simultaneously.</p>
<p class="Pp"><code class="Nm">crypt_r</code>, <code class="Nm">crypt_rn</code>,
and <code class="Nm">crypt_ra</code> place their result in the
<var class="Fa">output</var> field of their <var class="Fa">data</var>
argument. It is safe to call them from multiple threads simultaneously, as
long as a separate <var class="Fa">data</var> object is used for each
thread.</p>
<p class="Pp" id="invalid">Upon error, <code class="Nm">crypt_r</code>,
<code class="Nm">crypt_rn</code>, and <code class="Nm">crypt_ra</code> write
an <a class="permalink" href="#invalid"><i class="Em">invalid</i></a> hash
to the <var class="Fa">output</var> field of their
<var class="Fa">data</var> argument, and <code class="Nm">crypt</code>
writes an invalid hash to its static storage area. This string will be
shorter than 13 characters, will begin with a
‘<code class="Li">*</code>’, and will not compare equal to
<var class="Fa">setting</var>.</p>
<p class="Pp">Upon error, <code class="Nm">crypt_rn</code> and
<code class="Nm">crypt_ra</code> return a null pointer.
<code class="Nm">crypt_r</code> and <code class="Nm">crypt</code> may also
return a null pointer, or they may return a pointer to the invalid hash,
depending on how libcrypt was configured. (The option to return the invalid
hash is for compatibility with old applications that assume that
<code class="Nm">crypt</code> cannot return a null pointer. See
<a class="Sx" href="#PORTABILITY_NOTES">PORTABILITY NOTES</a> below.)</p>
<p class="Pp">All four functions set <var class="Va">errno</var> when they fail.
When the functions succeed, the value of <var class="Va">errno</var> is
unspecified and must not be relied upon.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1>
<dl class="Bl-tag">
<dt id="EINVAL"><a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a></dt>
<dd><var class="Fa">setting</var> is invalid, or requests a hashing method
that is not supported.</dd>
<dt id="ERANGE"><a class="permalink" href="#ERANGE"><code class="Er">ERANGE</code></a></dt>
<dd><var class="Fa">phrase</var> is too long (more than
<code class="Dv">CRYPT_MAX_PASSPHRASE_SIZE</code> characters; some hashing
methods may have lower limits).
<br/>
<code class="Nm">crypt_rn</code> only: <var class="Fa">size</var> is too
small for the hashing method requested by
<var class="Fa">setting</var>.</dd>
<dt id="ENOMEM"><a class="permalink" href="#ENOMEM"><code class="Er">ENOMEM</code></a></dt>
<dd>Failed to allocate internal scratch memory.
<br/>
<code class="Nm">crypt_ra</code> only: failed to allocate memory for
<var class="Fa">data</var>.</dd>
<dt id="ENOSYS"><a class="permalink" href="#ENOSYS"><code class="Er">ENOSYS</code></a>
<span class="No">or</span>
<a class="permalink" href="#EOPNOTSUPP"><code class="Er" id="EOPNOTSUPP">EOPNOTSUPP</code></a></dt>
<dd>Hashing passphrases is not supported at all on this installation, or the
hashing method requested by <var class="Fa">setting</var> is not
supported. These error codes are not used by this version of libcrypt, but
may be encountered on other systems.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="PORTABILITY_NOTES"><a class="permalink" href="#PORTABILITY_NOTES">PORTABILITY
NOTES</a></h1>
<p class="Pp"><code class="Nm">crypt</code> is included in POSIX, but
<code class="Nm">crypt_r</code>, <code class="Nm">crypt_rn</code>, and
<code class="Nm">crypt_ra</code> are not part of any standard.</p>
<p class="Pp">POSIX does not specify any hashing methods, and does not require
hashed passphrases to be portable between systems. In practice, hashed
passphrases are portable as long as both systems support the hashing method
that was used. However, the set of supported hashing methods varies
considerably from system to system.</p>
<p class="Pp">The behavior of <code class="Nm">crypt</code> on errors isn't well
standardized. Some implementations simply can't fail (except by crashing the
program), others return a null pointer or a fixed string. Most
implementations don't set <var class="Va">errno</var>, but some do. POSIX
specifies returning a null pointer and setting <var class="Va">errno</var>,
but it defines only one possible error, <code class="Er">ENOSYS</code>, in
the case where <code class="Nm">crypt</code> is not supported at all. Some
older applications are not prepared to handle null pointers returned by
<code class="Nm">crypt</code>. The behavior described above for this
implementation, setting <var class="Va">errno</var> and returning an invalid
hash different from <var class="Fa">setting</var>, is chosen to make these
applications fail closed when an error occurs.</p>
<p class="Pp">Due to historical restrictions on the export of cryptographic
software from the USA, <code class="Nm">crypt</code> is an optional POSIX
component. Applications should therefore be prepared for
<code class="Nm">crypt</code> not to be available, or to always fail
(setting <var class="Va">errno</var> to <code class="Er">ENOSYS</code>) at
runtime.</p>
<p class="Pp">POSIX specifies that <code class="Nm">crypt</code> is declared in
<code class="In"><<a class="In" href="%N.%S.html">unistd.h</a>></code>,
but only if the macro <code class="Dv">_XOPEN_CRYPT</code> is defined and
has a value greater than or equal to zero. Since libcrypt does not provide
<code class="In"><<a class="In" href="%N.%S.html">unistd.h</a>></code>,
it declares <code class="Nm">crypt</code>, <code class="Nm">crypt_r</code>,
<code class="Nm">crypt_rn</code>, and <code class="Nm">crypt_ra</code> in
<code class="In"><<a class="In" href="%N.%S.html">crypt.h</a>></code>
instead.</p>
<p class="Pp">On a minority of systems (notably recent versions of Solaris),
<code class="Nm">crypt</code> uses a thread-specific static storage buffer,
which makes it safe to call from multiple threads simultaneously, but does
not prevent each call within a thread from overwriting the results of the
previous one.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">Some implementations of <code class="Nm">crypt</code>, upon error,
return an invalid hash that is stored in a read-only location or only
initialized once, which means that it is only safe to erase the buffer
pointed to by the <code class="Nm">crypt</code> return value if an error did
not occur.</p>
<p class="Pp"><var class="Vt">struct crypt_data</var> may be quite large (32kB
in this implementation of libcrypt; over 128kB in some other
implementations). This is large enough that it may be unwise to allocate it
on the stack.</p>
<p class="Pp">Some recently designed hashing methods need even more scratch
memory, but the <code class="Nm">crypt_r</code> interface makes it
impossible to change the size of <var class="Vt">struct crypt_data</var>
without breaking binary compatibility. The <code class="Nm">crypt_rn</code>
interface could accommodate larger allocations for specific hashing methods,
but the caller of <code class="Nm">crypt_rn</code> has no way of knowing how
much memory to allocate. <code class="Nm">crypt_ra</code> does the
allocation itself, but can only make a single call to
<a class="Xr" href="malloc.3.html">malloc(3)</a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ATTRIBUTES"><a class="permalink" href="#ATTRIBUTES">ATTRIBUTES</a></h1>
<p class="Pp">For an explanation of the terms used in this section, see
<a class="Xr" href="attributes.7.html">attributes(7)</a>.</p>
<table class="tbl" border="1" style="border-style: solid;">
<tr>
<td><b>Interface</b></td>
<td><b>Attribute</b></td>
<td><b>Value</b></td>
</tr>
<tr>
<td>crypt</td>
<td>Thread safety</td>
<td>MT-Unsafe race:crypt</td>
</tr>
<tr>
<td>crypt_r , crypt_rn , crypt_ra</td>
<td>Thread safety</td>
<td>MT-Safe</td>
</tr>
</table>
<p class="Pp"></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">A rotor-based <code class="Nm">crypt</code> function appeared in
<span class="Ux">Version 6 AT&T UNIX</span>. The
“traditional” DES-based <code class="Nm">crypt</code> first
appeared in <span class="Ux">Version 7 AT&T UNIX</span>.</p>
<p class="Pp"><code class="Nm">crypt_r</code> originates with the GNU C Library.
There's also a <code class="Nm">crypt_r</code> function on HP-UX and MKS
Toolkit, but the prototypes and semantics differ.</p>
<p class="Pp"><code class="Nm">crypt_rn</code> and
<code class="Nm">crypt_ra</code> originate with the Openwall project.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr" href="crypt_gensalt.3.html">crypt_gensalt(3)</a>,
<a class="Xr" href="getpass.3.html">getpass(3)</a>,
<a class="Xr" href="getpwent.3.html">getpwent(3)</a>,
<a class="Xr" href="shadow.3.html">shadow(3)</a>,
<a class="Xr" href="login.1.html">login(1)</a>,
<a class="Xr" href="passwd.1.html">passwd(1)</a>,
<a class="Xr" href="crypt.5.html">crypt(5)</a>,
<a class="Xr" href="passwd.5.html">passwd(5)</a>,
<a class="Xr" href="shadow.5.html">shadow(5)</a>,
<a class="Xr" href="pam.8.html">pam(8)</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 11, 2017</td>
<td class="foot-os">Openwall Project</td>
</tr>
</table>
</body>
</html>