blib/lib/Authen/Challenge/Basic.pm

filter: Statementstmt 33.3% 1 / 3 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 1 / 1 Podpod n/a totaltotal 50.0% 2 / 4 CC 1 SCAR 2.6
CC
1
Cov
33%
BEGIN
1.3
CRAP 1.3
↑ Summary
1 #
2 # Authen::Challenge::Basic: Provides a trivial challenge/response protocol
3 # to assist in authentication tasks. It provides for time-window
4 # challenge/response sessions.
5 #
6 # Using this module, it's possible to autenticate both endpoints of
7 # a transaction provided that a shared-secret was exchanged prior to
8 # the session among the endpoints. As timestamps are part of the
9 # protocol, some restrictions can be applied to the timing, to help
10 # prevent hijacked connections.
11 #
12 # This is free software. You can use at will provided that proper
13 # credit is given to the author(s). This module requires MD5.
14 #
15 # lem@cantv.net, 19980713 - Initial release
16 #
17 #############
18  
19 package Authen::Challenge::Basic;
20 $VERSION='0.1';
21 require 5.000;
22  
23 =head1 NAME
24  
25 Authen::Challenge::Basic - A Basic challenge/response authentication scheme.
26  
27 =head1 SYNOPSIS
28  
29 use Authen::Challenge::Basic;
30  
31 $server = Authen::Challenge->new ('Secret' => 'known2us',
32 'Timeout' => 30,
33 'Sync' => 10);
34  
35 $client = Authen::Challenge->new ('Secret' => 'known2us',
36 'Timeout' => 30,
37 'Sync' => 10);
38  
39 $challenge = $server->Challenge;
40 $response = $client->Response($challenge);
41  
42 if ($server->Validate($challenge, $response)) {
43 print "Hi master\n";
44 }
45 else {
46 print "Impostor!\n";
47 }
48  
49 =head1 DESCRIPTION
50  
51 Authen::Challenge::Basic provides a simple MD5-based challenge/response
52 protocol allowing for mutual peer authentication in a session. The
53 protocol includes timing information, so it is possible to introduce
54 time constraints in the session to help prevent attacks that rely on
55 adjusting the clock in one of the peers.
56  
57 This protocol requires a shared secret to be known only to the peers.
58 The compromise of this secret also compromises this protocol, so
59 it should be treated as a trusted password for that matter.
60  
61 Challenge/response sessions are not 'replayable' provided that the
62 attacker ignores the shared secret. The sessions are also associated
63 to the instance that produced the challenge. This means that it can
64 only be Validate()'d by the instance that produced the challenge in
65 the first place.
66  
67 The built-in random number generator from perl is used in this module.
68 Hooks for better random number generators are planned soon to increase
69 the relative strength of this protocol. In any case, the main security
70 dependencies for this module are MD5 itself and the secrecy of the shared
71 secret.
72  
73 The following functions are provided by this class.
74  
75 new()
76  
77 Creates a new instance of a challenge/response endpoint. It has three
78 parameters that influence its behavior. Those can be seen next
79  
80 $server = Authen::Challenge::Basic->new ('Secret' => 'known2us',
81 'Timeout' => 30,
82 'Sync' => 10);
83  
84 'Secret' is used to indicate the shared secret to use in this session.
85  
86 'Timeout' specifies the lifespan, in seconds, for this transaction.
87 This means that a succesful Validate() must occur within this many
88 seconds to have a chance to be acknowledged. Reducing this value
89 too much can cause problems as a slight ammount of load can make the
90 session fail. 30 seconds is a reasonable default for many uses. If
91 left unspecified, no timeout is enforced.
92  
93 'Sync' indicates how strict are we with regard to the clock in our
94 peer. The parameter contains the maximum offset in seconds between the
95 clocks of the peers. The more strict we are (ie, the smaller the number),
96 the less tolerant we are. If left unspecified, we'll allow any ammount
97 of drift. It's specified in seconds.
98  
99 Challenge()
100  
101 Issues a new challenge. The object creating this challenge stores
102 information about it that allows for later recognition and validation.
103 The Challenge() is a typical function of the server, though a double
104 Challenge/Response scenario allows mutual authentication such as
105 in the following scheme:
106  
107 Client Server
108 (1) C1 ---------------------->
109 (2) <---------------------- R(C1), C2
110 (3) R(C2) ---------------------->
111  
112 On stage (2), the Client is authenticated to the server. On stage (3),
113 both are mutually authenticated.
114  
115 This method is usually invoked like
116  
117 $challenge = $server->Challenge;
118  
119 $challenge will contain a printable string that must be passed to the
120 peer in order for a response to be received.
121  
122 Response()
123  
124 This method takes a challenge and generates the required response. This
125 is usually invoked as
126  
127 $response = $client->Response($challenge);
128  
129 Where $challenge contains a Challenge generated by a call to Challenge().
130 $response will contain a printable string that must be returned to the
131 peer in order for it to be validated.
132  
133 Validate()
134  
135 This method verifies the correctness of the Challenge/Response session by
136 insuring that:
137  
138 (a) The challenge was indeed generated from this instance
139 and is pending validation
140 (b) The time interval for the validation is acceptable
141 (c) The shared secret was used by the peer to create the
142 response
143  
144 Usually this method is invoked like this
145  
146 $r = $server->Validate($challenge, $response);
147  
148 It returns a true value to indicate a correct session where (a), (b) and
149 (c) hold true or false otherwise.
150  
151 =head1 CAVEATS
152  
153 Note that this module helps insure that the peers were who they said they
154 where provided that the shared secret is not known to any third parties.
155 If this is not true, then anything could happen.
156  
157 Also, after the initial authentication, a network connection can be
158 stolen or hijacked, rendering all of the tests useless.
159  
160 =head1 AUTHOR
161  
162 Luis E. Munoz <lem@cantv.net>
163  
164 =cut
165  
166 0 ▶use MD5;
Subroutine BEGIN: called CC=1 SCAR=2.6
167  
168 sub new {
169 my ($class, @opt) = @_;
170 my ($r_param) = canon_params(@opt);
171 $self = {'p' => $r_param,
172 'Error' => undef,
173 'Stamp' => '',
174 'Count' => 0,
175 'Alive' => {}
176 };
177 bless $self, $class;
178 return $self;
179 }
180  
181 sub Error {
182 my ($self) = @_;
183 $self->{'Error'};
184 }
185  
186 sub Challenge {
187 my ($self) = @_;
188 my ($ctx) = new MD5;
189 my ($Count) = sprintf("%05d", $self->{'Count'}++);
190 my ($Stamp) = time;
191 # Add the shared secret...
192 $ctx->add($self->{'p'}->{'secret'});
193 # ... and a transaction counter...
194 $ctx->add($Count);
195 # ... and a perturbed timestamp, keeping it safe.
196 $ctx->add($self->{'Stamp'} = $Stamp + rand(16384));
197 my ($result) = $ctx->hexdigest;
198 $self->{'Alive'}->{$result} = $Stamp;
199 $self->{'Error'} = undef;
200 $result;
201 }
202  
203 sub Response {
204 my ($self, $challenge) = @_;
205 my ($ctx) = new MD5;
206 my ($Stamp) = time;
207 $self->{'Error'} = undef;
208 $ctx->add($challenge);
209 $ctx->add($self->{'p'}->{'secret'});
210 $ctx->add($Stamp);
211 $ctx->hexdigest . "/" . sprintf("%012d", $Stamp);
212 }
213  
214 sub Validate {
215 my ($self, $c, $r) = @_;
216 my ($Stamp) = time;
217 my ($mysignature, $this);
218  
219 # Insure the response is in a valid format...
220 my ($signature, $tstamp) = split(/\//, $r, 2);
221  
222 if (!$tstamp or !$signature) {
223 $self->{'Error'} = "Wrong response format";
224 return undef;
225 }
226  
227 # Insure this challenge was issued by this instance...
228 if (!($this = $self->{'Alive'}->{$c})) {
229 $self->{'Error'} = "This challenge doesn't belong to this instance";
230 return undef;
231 }
232  
233 undef($self->{'Alive'}->{$c});
234  
235 # Insure that this response has come on time...
236 if ($self->{'p'}->{'timeout'}
237 && $self->{'p'}->{'timeout'} + $this < $Stamp)
238 {
239 $self->{'Error'} = "Response came too late";
240 return undef;
241 }
242  
243 # Insure time sync between client and server...
244 if ($self->{'p'}->{'sync'}
245 && $self->{'p'}->{'sync'} + $this < $tstamp)
246 {
247 $self->{'Error'} = "Endpoints out of time-sync";
248 return undef;
249 }
250  
251 # Insure a correct signature...
252 $mysignature = new MD5;
253 $mysignature->add($c);
254 $mysignature->add($self->{'p'}->{'secret'});
255 $mysignature->add(int($tstamp));
256 if ($mysignature->hexdigest ne $signature) {
257 $self->{'Error'} = "Wrong signature for this response";
258 return undef;
259 }
260 $c;
261 }
262  
263 sub canon_params {
264 my(@param) = @_;
265 my(%param) = @param;
266 my ($k, $n);
267  
268 foreach $k (keys %param) {
269 $n = $k;
270 $n =~ tr/A-Z/a-z/;
271 $param{$n} = $param{$k};
272 undef($param{$k}) unless $n eq $k;
273 }
274  
275 \%param;
276  
277 }
278  
279 1;
280  
281  
282  
283  
↑ Summary