Annotation of src/lib/libcrypt/crypt.3, Revision 1.32
1.32 ! wiz 1: .\" $NetBSD: crypt.3,v 1.31 2021/10/12 17:27:26 nia Exp $
1.2 cgd 2: .\"
3: .\" Copyright (c) 1989, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
1.17 agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 15: .\" may be used to endorse or promote products derived from this software
16: .\" without specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
1.8 thorpej 30: .\" @(#)crypt.3 8.2 (Berkeley) 12/11/93
1.1 cgd 31: .\"
1.31 nia 32: .Dd October 12, 2021
1.1 cgd 33: .Dt CRYPT 3
34: .Os
35: .Sh NAME
36: .Nm crypt ,
37: .Nm setkey ,
38: .Nm encrypt ,
39: .Nm des_setkey ,
40: .Nm des_cipher
1.13 wiz 41: .Nd password encryption
1.5 perry 42: .Sh LIBRARY
43: .Lb libcrypt
1.1 cgd 44: .Sh SYNOPSIS
1.16 wiz 45: .In unistd.h
1.21 christos 46: .Ft "char *"
47: .Fn crypt "const char *key" "const char *setting"
1.1 cgd 48: .Ft int
49: .Fn encrypt "char *block" "int flag"
50: .Ft int
51: .Fn des_setkey "const char *key"
52: .Ft int
53: .Fn des_cipher "const char *in" "char *out" "long salt" "int count"
1.16 wiz 54: .In stdlib.h
1.6 kleink 55: .Ft int
56: .Fn setkey "const char *key"
1.1 cgd 57: .Sh DESCRIPTION
58: The
1.4 mikel 59: .Fn crypt
1.1 cgd 60: function
1.15 wiz 61: performs password encryption.
62: The encryption scheme used by
1.9 ad 63: .Fn crypt
64: is dependent upon the contents of the
65: .Dv NUL Ns -terminated
66: string
67: .Ar setting .
1.14 itojun 68: If it begins
69: with a string character
70: .Pq Ql $
71: and a number then a different algorithm is used depending on the number.
72: At the moment a
73: .Ql $1
74: chooses MD5 hashing and a
75: .Ql $2
76: chooses Blowfish hashing; see below for more information.
1.9 ad 77: If
78: .Ar setting
79: begins with the ``_'' character, DES encryption with a user specified number
1.15 wiz 80: of perturbations is selected.
81: If
1.9 ad 82: .Ar setting
83: begins with any other character, DES encryption with a fixed number
84: of perturbations is selected.
1.12 wiz 85: .Ss DES encryption
1.9 ad 86: The DES encryption scheme is derived from the
1.1 cgd 87: .Tn NBS
88: Data Encryption Standard.
1.9 ad 89: Additional code has been added to deter key search attempts and to use
1.15 wiz 90: stronger hashing algorithms.
1.19 drochner 91: In the DES case, the second argument to
1.9 ad 92: .Fn crypt
93: is a character array, 9 bytes in length, consisting of an underscore (``_'')
94: followed by 4 bytes of iteration count and 4 bytes of salt.
1.1 cgd 95: Both the iteration
96: .Fa count
1.10 wiz 97: and the
1.1 cgd 98: .Fa salt
99: are encoded with 6 bits per character, least significant bits first.
100: The values 0 to 63 are encoded by the characters ``./0-9A-Za-z'',
101: respectively.
102: .Pp
103: The
104: .Fa salt
105: is used to induce disorder in to the
106: .Tn DES
107: algorithm
108: in one of 16777216
109: possible ways
110: (specifically, if bit
111: .Em i
112: of the
113: .Ar salt
114: is set then bits
115: .Em i
116: and
117: .Em i+24
118: are swapped in the
119: .Tn DES
120: ``E'' box output).
121: The
122: .Ar key
123: is divided into groups of 8 characters (a short final group is null-padded)
1.2 cgd 124: and the low-order 7 bits of each character (56 bits per group) are
1.1 cgd 125: used to form the DES key as follows: the first group of 56 bits becomes the
126: initial DES key.
127: For each additional group, the XOR of the group bits and the encryption of
128: the DES key with itself becomes the next DES key.
129: Then the final DES key is used to perform
130: .Ar count
131: cumulative encryptions of a 64-bit constant.
132: The value returned is a
133: .Dv NUL Ns -terminated
134: string, 20 bytes in length, consisting
135: of the
136: .Ar setting
137: followed by the encoded 64-bit encryption.
138: .Pp
139: For compatibility with historical versions of
1.22 wiz 140: .Fn crypt ,
1.1 cgd 141: the
142: .Ar setting
143: may consist of 2 bytes of salt, encoded as above, in which case an
144: iteration
145: .Ar count
146: of 25 is used, fewer perturbations of
147: .Tn DES
148: are available, at most 8
149: characters of
150: .Ar key
151: are used, and the returned value is a
152: .Dv NUL Ns -terminated
153: string 13 bytes in length.
154: .Pp
155: The
1.4 mikel 156: functions
1.1 cgd 157: .Fn encrypt ,
158: .Fn setkey ,
159: .Fn des_setkey
160: and
161: .Fn des_cipher
162: allow limited access to the
163: .Tn DES
164: algorithm itself.
165: The
166: .Ar key
167: argument to
168: .Fn setkey
169: is a 64 character array of
170: binary values (numeric 0 or 1).
171: A 56-bit key is derived from this array by dividing the array
172: into groups of 8 and ignoring the last bit in each group.
173: .Pp
174: The
175: .Fn encrypt
176: argument
177: .Fa block
178: is also a 64 character array of
179: binary values.
180: If the value of
181: .Fa flag
182: is 0,
183: the argument
184: .Fa block
1.8 thorpej 185: is encrypted, otherwise it
186: is decrypted.
187: The encryption or decryption is returned in the original
1.1 cgd 188: array
189: .Fa block
190: after using the
191: key specified
192: by
193: .Fn setkey
194: to process it.
195: .Pp
196: The
197: .Fn des_setkey
198: and
199: .Fn des_cipher
200: functions are faster but less portable than
201: .Fn setkey
202: and
203: .Fn encrypt .
204: The argument to
205: .Fn des_setkey
206: is a character array of length 8.
207: The
208: .Em least
209: significant bit in each character is ignored and the next 7 bits of each
210: character are concatenated to yield a 56-bit key.
211: The function
212: .Fn des_cipher
1.8 thorpej 213: encrypts (or decrypts if
214: .Fa count
215: is negative) the 64-bits stored in the 8 characters at
1.1 cgd 216: .Fa in
217: using
218: .Xr abs 3
219: of
220: .Fa count
221: iterations of
222: .Tn DES
223: and stores the 64-bit result in the 8 characters at
224: .Fa out .
225: The
226: .Fa salt
227: specifies perturbations to
228: .Tn DES
229: as described above.
1.12 wiz 230: .Ss MD5 encryption
1.9 ad 231: For the
1.10 wiz 232: .Tn MD5
1.9 ad 233: encryption scheme, the version number (in this case ``1''),
234: .Fa salt
235: and the hashed password are separated
1.15 wiz 236: by the ``$'' character.
237: A valid password looks like this:
1.9 ad 238: .Pp
239: ``$1$2qGr5PPQ$eT08WBFev3RPLNChixg0H.''.
1.1 cgd 240: .Pp
1.10 wiz 241: The entire password string is passed as
1.14 itojun 242: .Fa setting
243: for interpretation.
1.28 jhigh 244: .Ss Argon2 encryption
1.29 wiz 245: Argon2 is a memory-hard hashing algorithm.
246: .Fn crypt
247: provides all three variants: argon2i, argon2d, and argon2id.
248: It is recommended to use argon2id, which provides a hybrid combination
249: using argon2i on the first pass, and argon2d on the remaining
250: passes.
251: We parameterize on three variables.
252: First, m_cost (m), specifies the memory usage in KB.
1.30 andvar 253: Second, t_cost (t), specifies the number of iterations.
1.29 wiz 254: Third, parallelism (p) specifies the number of threads.
1.32 ! wiz 255: This is currently ignored and one thread will always be used.
1.29 wiz 256: A valid Argon2 encoded password looks similar to
257: .Bd -literal
1.28 jhigh 258: $argon2id$v=19$m=4096,t=6,p=1$qCatF9a1s/6TgcYB$ \
259: yeYYrU/rh7E+LI2CAeHTSHVB3iO+OXiNIUHu6NPeTfo
1.29 wiz 260: .Ed
261: containing five fields delimited by '$'.
262: The fields, in order, are variant name, version, parameter set,
263: 128-bit salt, and encoded password.
264: The complete password string is required to be processed correctly.
1.14 itojun 265: .Ss "Blowfish" crypt
266: The
267: .Tn Blowfish
1.25 wiz 268: version of
1.24 christos 269: .Fn crypt
270: has 128 bits of
1.14 itojun 271: .Fa salt
272: in order to make building dictionaries of common passwords space consuming.
273: The initial state of the
274: .Tn Blowfish
275: cipher is expanded using the
276: .Fa salt
277: and the
278: .Fa password
279: repeating the process a variable number of rounds, which is encoded in
280: the password string.
281: The maximum password length is 72.
282: The final Blowfish password entry is created by encrypting the string
283: .Pp
284: .Dq OrpheanBeholderScryDoubt
285: .Pp
286: with the
287: .Tn Blowfish
288: state 64 times.
289: .Pp
290: The version number, the logarithm of the number of rounds and
291: the concatenation of salt and hashed password are separated by the
292: .Ql $
293: character.
294: An encoded
295: .Sq 8
296: would specify 256 rounds.
297: A valid Blowfish password looks like this:
298: .Pp
299: .Dq $2a$12$eIAq8PR8sIUnJ1HaohxX2O9x9Qlm2vK97LJ5dsXdmB.eXF42qjchC .
300: .Pp
301: The whole Blowfish password string is passed as
1.9 ad 302: .Fa setting
303: for interpretation.
304: .Sh RETURN VALUES
1.1 cgd 305: The function
306: .Fn crypt
1.23 christos 307: returns a pointer to the encrypted value on success.
308: .Pp
309: The behavior of
310: .Fn crypt
311: on errors isn't well standardized.
312: Some implementations simply can't fail (unless the process dies, in which
313: case they obviously can't return), others return
314: .Dv NULL
315: or a fixed string.
316: Most implementations don't set
317: .Va errno ,
318: but some do.
319: .St -susv2
320: specifies
321: only returning
322: .Dv NULL
323: and setting
324: .Va errno
325: as a valid behavior, and defines
326: only one possible error
327: .Er ( ENOSYS ,
328: .Dq "The functionality is not supported on this implementation." )
329: Unfortunately, most existing applications aren't prepared to handle
330: .Dv NULL
331: returns from
332: .Fn crypt .
1.24 christos 333: The description below corresponds to this implementation of
334: .Fn crypt
335: only.
1.23 christos 336: The behavior may change to match standards, other implementations or existing
337: applications.
338: .Pp
339: .Fn crypt
340: may only fail (and return) when passed an invalid or unsupported
341: .Fa setting ,
342: in which case it returns a pointer to a magic string that is shorter than 13
1.24 christos 343: characters and is guaranteed to differ from
1.23 christos 344: .Fa setting .
1.24 christos 345: This behavior is safe for older applications which assume that
346: .Fn crypt
347: can't fail, when both setting new passwords and authenticating against
348: existing password hashes.
1.23 christos 349: .Pp
1.1 cgd 350: The functions
351: .Fn setkey ,
352: .Fn encrypt ,
353: .Fn des_setkey ,
354: and
355: .Fn des_cipher
356: return 0 on success and 1 on failure.
357: Historically, the functions
358: .Fn setkey
359: and
360: .Fn encrypt
361: did not return any value.
1.29 wiz 362: They have been provided return values primarily to distinguish
1.1 cgd 363: implementations where hardware support is provided but not
364: available or where the DES encryption is not available due to the
365: usual political silliness.
366: .Sh SEE ALSO
367: .Xr login 1 ,
368: .Xr passwd 1 ,
1.29 wiz 369: .Xr pwhash 1 ,
370: .Xr getpass 3 ,
371: .Xr md5 3 ,
372: .Xr passwd 5 ,
373: .Xr passwd.conf 5
374: .Rs
375: .%T "Mathematical Cryptology for Computer Scientists and Mathematicians"
1.1 cgd 376: .%A Wayne Patterson
377: .%D 1987
378: .%N ISBN 0-8476-7438-X
379: .Re
380: .Rs
381: .%T "Password Security: A Case History"
382: .%A R. Morris
383: .%A Ken Thompson
384: .%J "Communications of the ACM"
385: .%V vol. 22
386: .%P pp. 594-597
1.29 wiz 387: .%D Nov. 1979
388: .Re
389: .Rs
390: .%T "DES will be Totally Insecure within Ten Years"
391: .%A M.E. Hellman
392: .%J "IEEE Spectrum"
393: .%V vol. 16
394: .%P pp. 32-39
1.1 cgd 395: .%D July 1979
396: .Re
397: .Sh HISTORY
398: A rotor-based
399: .Fn crypt
400: function appeared in
401: .At v6 .
402: The current style
403: .Fn crypt
404: first appeared in
405: .At v7 .
406: .Sh BUGS
407: Dropping the
408: .Em least
409: significant bit in each character of the argument to
410: .Fn des_setkey
1.29 wiz 411: is ridiculous.
1.1 cgd 412: .Pp
413: The
414: .Fn crypt
415: function leaves its result in an internal static object and returns
416: a pointer to that object.
417: Subsequent calls to
418: .Fn crypt
419: will modify the same object.
1.21 christos 420: .Pp
421: Before
1.27 njoly 422: .Nx 6.0
1.21 christos 423: .Fn crypt
424: returned either
425: .Dv NULL
426: or
1.26 wiz 427: .Dv \&:
1.21 christos 428: on error.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to crypt.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libcrypt