1Authen::Passphrase::SalUtseedrDiCgoensttr(i3b)uted PerlADuotchuemne:n:tPaatsisopnhrase::SaltedDigest(3)
2
3
4

NAME

6       Authen::Passphrase::SaltedDigest - passphrases using the generic salted
7       digest algorithm
8

SYNOPSIS

10               use Authen::Passphrase::SaltedDigest;
11
12               $ppr = Authen::Passphrase::SaltedDigest->new(
13                       algorithm => "SHA-1",
14                       salt_hex => "a9f524b1e819e96d8cc7".
15                                   "a04d5471e8b10c84e596",
16                       hash_hex => "8270d9d1a345d3806ab2".
17                                   "3b0385702e10f1acc943");
18
19               $ppr = Authen::Passphrase::SaltedDigest->new(
20                       algorithm => "SHA-1", salt_random => 20,
21                       passphrase => "passphrase");
22
23               $ppr = Authen::Passphrase::SaltedDigest->from_rfc2307(
24                       "{SSHA}gnDZ0aNF04BqsjsDhXAuEPGsy".
25                       "UOp9SSx6BnpbYzHoE1UceixDITllg==");
26
27               $algorithm = $ppr->algorithm;
28               $salt = $ppr->salt;
29               $salt_hex = $ppr->salt_hex;
30               $hash = $ppr->hash;
31               $hash_hex = $ppr->hash_hex;
32
33               if($ppr->match($passphrase)) { ...
34
35               $userPassword = $ppr->as_rfc2307;
36

DESCRIPTION

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
43       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
48       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
57       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
63       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

CONSTRUCTORS

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
74           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
79               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
92               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
96               Any other type of algorithm specifier has undefined behaviour.
97
98               The digest context objects must support at least the standard
99               "add" and "digest" methods.
100
101           salt
102               The salt, as a raw string of bytes.  Defaults to the empty
103               string, yielding an unsalted scheme.
104
105           salt_hex
106               The salt, as a string of hexadecimal digits.  Defaults to the
107               empty string, yielding an unsalted scheme.
108
109           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
116           hash
117               The hash, as a string of bytes.
118
119           hash_hex
120               The hash, as a string of hexadecimal digits.
121
122           passphrase
123               A passphrase that will be accepted.
124
125           The digest algorithm must be given, and either the hash or the
126           passphrase.
127
128       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
135           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

METHODS

141       $ppr->algorithm
142           Returns the digest algorithm, in the same form as supplied to the
143           constructor.
144
145       $ppr->salt
146           Returns the salt, in raw form.
147
148       $ppr->salt_hex
149           Returns the salt, as a string of hexadecimal digits.
150
151       $ppr->hash
152           Returns the hash value, in raw form.
153
154       $ppr->hash_hex
155           Returns the hash value, as a string of hexadecimal digits.
156
157       $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

SEE ALSO

164       Authen::Passphrase, Crypt::SaltedHash
165

AUTHOR

167       Andrew Main (Zefram) <zefram@fysh.org>
168
170       Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram)
171       <zefram@fysh.org>
172

LICENSE

174       This module is free software; you can redistribute it and/or modify it
175       under the same terms as Perl itself.
176
177
178
179perl v5.32.1                      2021-01-26Authen::Passphrase::SaltedDigest(3)
Impressum