1Authen::Passphrase::SalUtseedrDiCgoensttr(i3bpumt)ed PerAlutDhoecnu:m:ePnatsastpihornase::SaltedDigest(3pm)
2
6 Authen::Passphrase::SaltedDigest - passphrases using the generic salted
7 digest algorithm
8
10 use Authen::Passphrase::SaltedDigest;
11 $ppr = Authen::Passphrase::SaltedDigest->new(
13 algorithm => "SHA-1",
14 salt_hex => "a9f524b1e819e96d8cc7".
15 "a04d5471e8b10c84e596",
16 hash_hex => "8270d9d1a345d3806ab2".
17 "3b0385702e10f1acc943");
18 $ppr = Authen::Passphrase::SaltedDigest->new(
20 algorithm => "SHA-1", salt_random => 20,
21 passphrase => "passphrase");
22 $ppr = Authen::Passphrase::SaltedDigest->from_rfc2307(
24 "{SSHA}gnDZ0aNF04BqsjsDhXAuEPGsy".
25 "UOp9SSx6BnpbYzHoE1UceixDITllg==");
26 $algorithm = $ppr->algorithm;
28 $salt = $ppr->salt;
29 $salt_hex = $ppr->salt_hex;
30 $hash = $ppr->hash;
31 $hash_hex = $ppr->hash_hex;
32 if($ppr->match($passphrase)) { ...
34 $userPassword = $ppr->as_rfc2307;
36
38 An object of this class encapsulates a passphrase hashed using a
39 generic digest-algorithm-based scheme. This is a subclass of
40 Authen::Passphrase, and this document assumes that the reader is
41 familiar with the documentation for that class.
42 The salt is an arbitrary string of bytes. It is appended to
44 passphrase, and the combined string is passed through a specified
45 message digest algorithm. The output of the message digest algorithm
46 is the passphrase hash.
47 The strength depends entirely on the choice of digest algorithm, so
49 choose according to the level of security required. SHA-1 is suitable
50 for most applications, but recent work has revealed weaknesses in the
51 basic structure of MD5, SHA-1, SHA-256, and all similar digest
52 algorithms. A new generation of digest algorithms emerged in 2008,
53 centred around NIST's competition to design SHA-3. Once these
54 algorithms have been subjected to sufficient cryptanalysis, the
55 survivors will be preferred over SHA-1 and its generation.
56 Digest algorithms are generally designed to be as efficient to compute
58 as possible for their level of cryptographic strength. An unbroken
59 digest algorithm makes brute force the most efficient way to attack it,
60 but makes no effort to resist a brute force attack. This is a concern
61 in some passphrase-using applications.
62 The use of this kind of passphrase scheme is generally recommended for
64 new systems. Choice of digest algorithm is important: SHA-1 is
65 suitable for most applications. If efficiency of brute force attack is
66 a concern, see Authen::Passphrase::BlowfishCrypt for an algorithm
67 designed to be expensive to compute.
68
70 Authen::Passphrase::SaltedDigest->new(ATTR => VALUE, ...)
71 Generates a new passphrase recogniser object using the generic
72 salted digest algorithm. The following attributes may be given:
73 algorithm
75 Specifies the algorithm to use. If it is a reference to a
76 blessed object, it must be possible to call the "new" method on
77 that object to generate a digest context object.
78 If it is a string containing the subsequence "::" then it
80 specifies a module to use. A plain package name in bareword
81 syntax, optionally preceded by "::" (so that top-level packages
82 can be recognised as such), is taken as a class name, on which
83 the "new" method will be called to generate a digest context
84 object. The package name may optionally be followed by "-" to
85 cause automatic loading of the module, and the "-" (if present)
86 may optionally be followed by a version number that will be
87 checked against. For example, "Digest::MD5-1.99_53" would load
88 the Digest::MD5 module and check that it is at least version
89 1.99_53 (which is the first version that can be used by this
90 module).
91 A string not containing "::" and which is understood by
93 Digest->new will be passed to that function to generate a
94 digest context object.
95 Any other type of algorithm specifier has undefined behaviour.
97 The digest context objects must support at least the standard
99 "add" and "digest" methods.
100 salt
102 The salt, as a raw string of bytes. Defaults to the empty
103 string, yielding an unsalted scheme.
104 salt_hex
106 The salt, as a string of hexadecimal digits. Defaults to the
107 empty string, yielding an unsalted scheme.
108 salt_random
110 Causes salt to be generated randomly. The value given for this
111 attribute must be a non-negative integer, giving the number of
112 bytes of salt to generate. (The same length as the hash is
113 recommended.) The source of randomness may be controlled by
114 the facility described in Data::Entropy.
115 hash
117 The hash, as a string of bytes.
118 hash_hex
120 The hash, as a string of hexadecimal digits.
121 passphrase
123 A passphrase that will be accepted.
124 The digest algorithm must be given, and either the hash or the
126 passphrase.
127 Authen::Passphrase::SaltedDigest->from_rfc2307(USERPASSWORD)
129 Generates a salted-digest passphrase recogniser from the supplied
130 RFC2307 encoding. The scheme identifier gives the digest algorithm
131 and controls whether salt is permitted. It is followed by a base
132 64 string, using standard MIME base 64, which encodes the
133 concatenation of the hash and salt.
134 The scheme identifiers accepted are "{MD4}" (unsalted MD4), "{MD5}"
136 (unsalted MD5), "{RMD160}" (unsalted RIPEMD-160), "{SHA}" (unsalted
137 SHA-1), "{SMD5}" (salted MD5), and "{SSHA}" (salted SHA-1). All
138 scheme identifiers are recognised case-insensitively.
139
141 $ppr->algorithm
142 Returns the digest algorithm, in the same form as supplied to the
143 constructor.
144 $ppr->salt
146 Returns the salt, in raw form.
147 $ppr->salt_hex
149 Returns the salt, as a string of hexadecimal digits.
150 $ppr->hash
152 Returns the hash value, in raw form.
153 $ppr->hash_hex
155 Returns the hash value, as a string of hexadecimal digits.
156 $ppr->match(PASSPHRASE)
158 $ppr->as_rfc2307
159 These methods are part of the standard Authen::Passphrase
160 interface. Only passphrase recognisers using certain well-known
161 digest algorithms can be represented in RFC 2307 form.
162
164 Authen::Passphrase, Crypt::SaltedHash
165
167 Andrew Main (Zefram) <zefram@fysh.org>
168
170 Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram)
171 <zefram@fysh.org>
172
174 This module is free software; you can redistribute it and/or modify it
175 under the same terms as Perl itself.
176perl v5.38.0 2023-07-A2u0then::Passphrase::SaltedDigest(3pm)