1Authen::Passphrase::DESUCsreyrptC(o3n)tributed Perl DocuAmuetnhteant:i:oPnassphrase::DESCrypt(3)
2
3
4

NAME

6       Authen::Passphrase::DESCrypt - passphrases using the DES-based Unix
7       crypt()
8

SYNOPSIS

10               use Authen::Passphrase::DESCrypt;
11
12               $ppr = Authen::Passphrase::DESCrypt->new(
13                               salt_base64 => "my",
14                               hash_base64 => "TYK.j.88/9s");
15
16               $ppr = Authen::Passphrase::DESCrypt->new(
17                               salt_random => 12,
18                               passphrase => "passphrase");
19
20               $ppr = Authen::Passphrase::DESCrypt
21                       ->from_crypt('myTYK.j.88/9s');
22
23               $ppr = Authen::Passphrase::DESCrypt->new(
24                               fold => 1,
25                               initial => "xyzzy!!!",
26                               nrounds => 500,
27                               salt_base64 => "quux",
28                               hash_base64 => "QCKcHlgVsRY");
29
30               $fold = $ppr->fold;
31               $initial = $ppr->initial;
32               $initial_base64 = $ppr->initial_base64;
33               $nrounds = $ppr->nrounds;
34               $nrounds_base64 = $ppr->nrounds_base64_4;
35               $salt = $ppr->salt;
36               $salt_base64 = $ppr->salt_base64_2;
37               $salt_base64 = $ppr->salt_base64_4;
38               $hash = $ppr->hash;
39               $hash_base64 = $ppr->hash_base64;
40
41               if($ppr->match($passphrase)) { ...
42
43               $passwd = $ppr->as_crypt;
44               $userPassword = $ppr->as_rfc2307;
45

DESCRIPTION

47       An object of this class encapsulates a passphrase hashed using some
48       form of the DES-based Unix crypt() hash function.  This is a subclass
49       of Authen::Passphrase, and this document assumes that the reader is
50       familiar with the documentation for that class.
51
52       The crypt() function in a modern Unix actually supports several
53       different passphrase schemes.  That is not what this class is about.
54       This class is concerned only with one family of schemes, variants of
55       the DES-based scheme that crypt() originally implemented, which
56       confusingly is usually referred to merely as "crypt()".  To handle the
57       whole range of passphrase schemes supported by the modern crypt(), see
58       the from_crypt constructor and the as_crypt method in
59       Authen::Passphrase.
60
61       Warning: this password scheme is weak by modern standards, and in any
62       case does not support a large password space.  Cracking crypt()ed
63       passwords has been a routine activity since the early 1990s.  This
64       scheme is supported for compatibility reasons only, and should not be
65       used except when compatibility is required.  Do not use this in the
66       design of any new system or for new passwords in any system that
67       supports better passphrase schemes.
68
69   The traditional DES-based Unix crypt() password scheme
70       The traditional Unix crypt() password scheme is based on the DES block
71       encryption algorithm.  Using the password as a 56-bit key, it passes a
72       64-bit data block, initialised to zero, through the encryption function
73       25 times, and the hash is the 64-bit output of this process.  A 12-bit
74       salt is used to tweak the encryption algorithm.
75
76       The 56-bit key is extracted from the password in a very poor way.  Only
77       the first eight bytes of the password are used, and any remainder is
78       ignored.  This makes it impossible to use a passphrase, rather than a
79       password, hence the terminology in this section.  Of the eight bytes
80       used, the top bit is also ignored; this function hails from the days of
81       pure ASCII.
82
83       A password hash of this scheme is conventionally represented in ASCII
84       as a 13-character string using a base 64 encoding.  The base 64 digits
85       are ".", "/", "0" to "9", "A" to "Z", "a" to "z" (in ASCII order).  The
86       first two characters give the 12-bit salt.  The remaining eleven
87       characters give the 64-bit hash.  Because the base 64 encoding can
88       represent 66 bits in eleven digits, more than the 64 required, the last
89       character of the string can only take sixteen of the base 64 digit
90       values.
91
92   Variant DES-based Unix crypt() passphrase schemes
93       To make password cracking more difficult, historically some Unix sites
94       modified the crypt() function to be incompatible with the standard one.
95       This was easily achieved by initialising the data block to something
96       other than the standard all-bits-zero.  Another variation used was to
97       increase the number of encryption rounds, which makes cracking take
98       longer in addition to being non-standard.  Password hashes on such a
99       system looked normal but were not interoperable with standard crypt()
100       implementations.  To interpret them properly it is necessary to know
101       the modified parameters.
102
103       BSDi standardised an extended DES-based scheme.  The salt is extended
104       to 24 bits, and the number of encryption rounds is variable.
105       Passphrases longer than 8 characters are handled by an additional step
106       that folds (hashes) them down to 8 characters, rather than just
107       throwing away the characters after the eighth.  Passphrase hashes in
108       this scheme are conventionally represented in ASCII as a "_" followed
109       by 19 characters of base 64.  The first four base 64 digits give the
110       number of encryption rounds, the next four give the salt, and the
111       remaining eleven give the hash.
112

CONSTRUCTORS

114       Authen::Passphrase::DESCrypt->new(ATTR => VALUE, ...)
115           Generates a new passphrase recogniser object using the generalised
116           DES-based crypt() algorithm.  The following attributes may be
117           given:
118
119           fold
120               Truth value indicating whether the BSDi passphrase folding
121               scheme should be used for long passphrases.  Default false, for
122               compatibility with the original DES-based scheme.
123
124           initial
125               The initial data block to encrypt, as a string of exactly eight
126               bytes.  Default all bits zero, for compatibility with the
127               original DES-based scheme.
128
129           initial_base64
130               The initial data block to encrypt, as a string of eleven base
131               64 digits.
132
133           nrounds
134               The number of encryption rounds to use, as a Perl integer.
135               Default 25, for compatibility with the original DES-based
136               scheme.
137
138           nrounds_base64
139               The number of encryption rounds to use, as a string of four
140               base 64 digits.
141
142           salt
143               The salt, as an integer in the range [0, 16777216).
144
145           salt_base64
146               The salt, as a string of two or four base 64 digits.
147
148           salt_random
149               Causes salt to be generated randomly.  The value given for this
150               attribute must be either 12 or 24, giving the number of bits of
151               salt to generate.  The source of randomness may be controlled
152               by the facility described in Data::Entropy.
153
154           hash
155               The hash (output of encryption), as a string of exactly eight
156               bytes.
157
158           hash_base64
159               The hash, as a string of eleven base 64 digits.
160
161           passphrase
162               A passphrase that will be accepted.
163
164           The salt must be given, and either the hash or the passphrase.  The
165           other parameters default to those used in the original DES-based
166           crypt().
167
168       Authen::Passphrase::DESCrypt->from_crypt(PASSWD)
169           Generates a new passphrase recogniser object using the DES-based
170           crypt() algorithm, from a crypt string.  Two forms of crypt string
171           are supported.
172
173           The first form of crypt string must consist of 13 base 64 digits.
174           The first two give the salt, and the next eleven give the hash.
175           Long passphrases are not folded, the initial block is all bits
176           zero, and 25 encryption rounds are performed.
177
178           The second form of crypt string must consist of an "_" followed by
179           19 base 64 digits.  The first four give the number of encryption
180           rounds, the next four give the salt, and the next eleven give the
181           hash.  Long passphrases are folded, and the initial block is all
182           bits zero.
183
184       Authen::Passphrase::DESCrypt->from_rfc2307(USERPASSWORD)
185           Generates a new passphrase recogniser object using the DES-based
186           crypt() algorithm, from an RFC 2307 string.  The string must
187           consist of "{CRYPT}" (case insensitive) followed by an acceptable
188           crypt string.
189

METHODS

191       $ppr->fold
192           Returns a truth value indicating whether passphrase folding is
193           used.
194
195       $ppr->initial
196           Returns the initial block, as a string of eight bytes.
197
198       $ppr->initial_base64
199           Returns the initial block, as a string of eleven base 64 digits.
200
201       $ppr->nrounds
202           Returns the number of encryption rounds, as a Perl integer.
203
204       $ppr->nrounds_base64_4
205           Returns the number of encryption rounds, as a string of four base
206           64 digits.
207
208       $ppr->salt
209           Returns the salt, as a Perl integer.
210
211       $ppr->salt_base64_2
212           Returns the salt, as a string of two base 64 digits.  "die"s if it
213           doesn't fit into two digits.
214
215       $ppr->salt_base64_4
216           Returns the salt, as a string of four base 64 digits.
217
218       $ppr->hash
219           Returns the hash value, as a string of eight bytes.
220
221       $ppr->hash_base64
222           Returns the hash value, as a string of eleven base 64 digits.
223
224       $ppr->match(PASSPHRASE)
225       $ppr->as_crypt
226       $ppr->as_rfc2307
227           These methods are part of the standard Authen::Passphrase
228           interface.
229

SEE ALSO

231       Authen::Passphrase, Crypt::UnixCrypt_XS
232

AUTHOR

234       Andrew Main (Zefram) <zefram@fysh.org>
235
237       Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram)
238       <zefram@fysh.org>
239

LICENSE

241       This module is free software; you can redistribute it and/or modify it
242       under the same terms as Perl itself.
243
244
245
246perl v5.34.0                      2022-01-20   Authen::Passphrase::DESCrypt(3)
Impressum