|
1 .\" Portions Copyright © 2005-2006 Nokia. All rights reserved. |
|
2 .\" FreeSec: libcrypt for NetBSD |
|
3 .\" |
|
4 .\" Copyright (c) 1994 David Burren |
|
5 .\" All rights reserved. |
|
6 .\" |
|
7 .\" Redistribution and use in source and binary forms, with or without |
|
8 .\" modification, are permitted provided that the following conditions |
|
9 .\" are met: |
|
10 .\" 1. Redistributions of source code must retain the above copyright |
|
11 .\" notice, this list of conditions and the following disclaimer. |
|
12 .\" 2. Redistributions in binary form must reproduce the above copyright |
|
13 .\" notice, this list of conditions and the following disclaimer in the |
|
14 .\" documentation and/or other materials provided with the distribution. |
|
15 .\" 4. Neither the name of the author nor the names of other contributors |
|
16 .\" may be used to endorse or promote products derived from this software |
|
17 .\" without specific prior written permission. |
|
18 .\" |
|
19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
|
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
|
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
|
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
|
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
|
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
|
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
|
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
|
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
|
29 .\" SUCH DAMAGE. |
|
30 .\" |
|
31 .\" $FreeBSD: src/lib/libcrypt/crypt.3,v 1.31 2005/02/09 18:03:14 ru Exp $ |
|
32 .\" |
|
33 .Dd January 19, 1997 |
|
34 .Dt CRYPT 3 |
|
35 .Os |
|
36 .Sh NAME |
|
37 .Nm crypt |
|
38 .Nd password and data encryption |
|
39 .Sh LIBRARY |
|
40 .Lb libcrypt |
|
41 .Sh SYNOPSIS |
|
42 .In unistd.h |
|
43 .Ft char * |
|
44 .Fn crypt "const char *key" "const char *salt" |
|
45 .Sh RETURN VALUES |
|
46 The |
|
47 .Fn crypt |
|
48 function returns a pointer to the encrypted value on success, and NULL on |
|
49 failure. |
|
50 .Pp |
|
51 .Sh DESCRIPTION |
|
52 The |
|
53 .Fn crypt |
|
54 function performs password hashing with additional code added to |
|
55 thwart dictionary attack. |
|
56 Different algorithms can be used in the hash. |
|
57 .\" |
|
58 .\" NOTICE: |
|
59 .\" If you add more algorithms, make sure to update this list |
|
60 .\" and the default used for the Traditional format, below. |
|
61 .\" |
|
62 Currently the implementation supports |
|
63 .Tn Data Encryption Standard (DES) |
|
64 and |
|
65 .Tn MD5 |
|
66 hash algorithms. However, the actual algorithm used during the call to |
|
67 .Fn crypt |
|
68 depends on the |
|
69 .Fn salt |
|
70 parameter. |
|
71 .Pp |
|
72 The first argument to |
|
73 .Fn crypt |
|
74 is the data to hash (usually a password), in a |
|
75 .Dv NULL Ns -terminated |
|
76 string. |
|
77 The second is the salt, in one of two forms: |
|
78 .Pp |
|
79 .Bl -tag -width Traditional -compact -offset indent |
|
80 .It Modular |
|
81 If |
|
82 .Fn salt |
|
83 begins with the string |
|
84 .Dq $digit$ |
|
85 then the Modular Crypt Format is used. |
|
86 .It Traditional |
|
87 .Fn salt |
|
88 parameter is a two-character string chosen from the set [a-zA-Z0-9./]. |
|
89 .El |
|
90 .Pp |
|
91 .Ss "Modular" crypt: |
|
92 .Pp |
|
93 If |
|
94 .Fn salt |
|
95 begins with the string |
|
96 .Fa $digit$ |
|
97 then Modular Crypt Format is used. |
|
98 The |
|
99 .Fa digit |
|
100 identifies the algorithm used for encryption. Currently MD5 hash is implemented. So |
|
101 .Fa digit |
|
102 will be 1 and hence the second argument to this function will be a string beginning with |
|
103 .Dq $1$ |
|
104 followed by at most 8 characters (actual salt to be used in the encryption), and optionally |
|
105 terminated by |
|
106 .Dq $ |
|
107 . |
|
108 If the optional |
|
109 .Dq $ |
|
110 is included then the characters following the dollar sign are ignored. |
|
111 The output of this operation will be a string |
|
112 containing 34 characters in the format |
|
113 .Dq $1$<string>$ |
|
114 .Pp |
|
115 .Dq <string> |
|
116 consists of the actual salt (the at most 8 characters string following |
|
117 .Dq $1$ |
|
118 in the |
|
119 .Fn salt), |
|
120 followed by 22 bytes of data from the set [a-zA-Z0-9./]. |
|
121 .El |
|
122 .Pp |
|
123 Other crypt formats may be easily added. |
|
124 An example salt would be: |
|
125 .Bl -tag -offset indent |
|
126 .It Cm "$4$thesalt$rest" |
|
127 .El |
|
128 .Pp |
|
129 .Ss "Traditional" crypt: |
|
130 .Pp |
|
131 It is based on Data Encryption Standard algorithm (DES). |
|
132 .Fn salt |
|
133 is a two-character string chosen from the set [a-zA-Z0-9./]. In order to thwart the |
|
134 Dictionary Attack, the two-character |
|
135 .Fn salt |
|
136 is used to perturb the algorithm in 4096 ways. |
|
137 .Pp |
|
138 The 56-bit key for the DES algorithm is obtained by taking the lowest 7 bits of each |
|
139 of the first eight characters of the |
|
140 .Fn key. |
|
141 The key thus obtained is used to encrypt a constant string (a string containing all zeroes). |
|
142 .Pp |
|
143 The return value of this function is a pointer to a static buffer. So the function |
|
144 is not reentrant. |
|
145 |
|
146 .Sh Example |
|
147 .Bd -literal -offset indent |
|
148 #include <stdlib.h> |
|
149 #include <unistd.h> |
|
150 |
|
151 void crypt_user() |
|
152 { |
|
153 char *p = NULL, |
|
154 *q = NULL; |
|
155 |
|
156 /* Invoke crypt() to perform password hashing */ |
|
157 p = crypt("password", "S1"); /* p contains the hash of "password" |
|
158 * when "S1" is used as the key. DES |
|
159 * encryption algoritm is used in this |
|
160 * scenario |
|
161 */ |
|
162 |
|
163 q = crypt("password", "$1$Salt1"); |
|
164 /* q contains the hash of "password" |
|
165 * as computed by the MD5 hash algorithm |
|
166 */ |
|
167 } |
|
168 .Ed |
|
169 .Sh SEE ALSO |
|
170 .Sh BUGS |
|
171 Output of |
|
172 .Fn crypt |
|
173 differs from that of Linux's when NULL passed as |
|
174 .Fn salt . |