File Coverage

blib/lib/Net/SNMP/MessageProcessing.pm
Criterion Covered Total %
statement 43 170 25.2
branch 19 122 15.5
condition 5 17 29.4
subroutine 13 18 72.2
pod 0 8 0.0
total 80 335 23.8


line stmt bran cond sub pod time code
1             # -*- mode: perl -*-
2             # ============================================================================
3              
4             package Net::SNMP::MessageProcessing;
5              
6             # $Id: MessageProcessing.pm,v 3.1 2010/09/10 00:01:22 dtown Rel $
7              
8             # Object that implements the Message Processing module.
9              
10             # Copyright (c) 2001-2010 David M. Town
11             # All rights reserved.
12              
13             # This program is free software; you may redistribute it and/or modify it
14             # under the same terms as the Perl 5 programming language system itself.
15              
16             # ============================================================================
17              
18 2     2   7087 use strict;
  2         5  
  2         81  
19              
20 2         15 use Net::SNMP::PDU qw(
21             :types :msgFlags :securityLevels asn1_itoa SNMP_VERSION_3 TRUE FALSE
22 2     2   1326 );
  2         7  
23              
24             srand( time() ^ ($$ + ($$ <<15)) );
25              
26             ## Version of the Net::SNMP::MessageProcessing module
27              
28             our $VERSION = v3.0.1;
29              
30             ## Package variables
31              
32             our $INSTANCE; # Reference to the Singleton object
33              
34             our $DEBUG = FALSE; # Debug flag
35              
36             ## Object array indexes
37              
38 6     6   17 sub _ERROR { 0 } # Error message
39 1     1   6 sub _HANDLES { 1 } # Cached request messages
40              
41             BEGIN
42             {
43             # See if there is a better pseudorandom number generator (PRNG) available.
44 2 50   2   175 if (eval 'require Math::Random::MT::Auto') {
45 0         0 Math::Random::MT::Auto->import('rand');
46             }
47             }
48              
49             # [public methods] -----------------------------------------------------------
50              
51             sub instance
52             {
53 2   33 2 0 33 return $INSTANCE ||= Net::SNMP::MessageProcessing->_new();
54             }
55              
56             sub prepare_outgoing_msg
57             {
58 1     1 0 213 my ($this, $pdu) = @_;
59              
60             # Clear any previous errors
61 1         5 $this->_error_clear();
62              
63 1 50 33     10 if ((@_ != 2) || (!ref $pdu)) {
64 0         0 return $this->_error('The PDU object is missing or invalid');
65             }
66              
67             # We must have a Security Model in order to prepare the message.
68 1 50       14 if (!defined $pdu->security()) {
69 0         0 return $this->_error('The Security Model object is not defined');
70             }
71              
72             # Create a new Message
73 1         21 my ($msg, $error) = Net::SNMP::Message->new(
74             -callback => $pdu->callback(),
75             -leadingdot => $pdu->leading_dot(),
76             -requestid => $pdu->request_id(),
77             -security => $pdu->security(),
78             -translate => $pdu->translate(),
79             -transport => $pdu->transport(),
80             -version => $pdu->version()
81             );
82 1 50       5 return $this->_error($error) if !defined $msg;
83              
84 1 50       5 if ($pdu->version() == SNMP_VERSION_3) {
85              
86             # ScopedPDU::=SEQUENCE
87              
88 0 0       0 if (!defined $pdu->prepare_pdu_scope()) {
89 0         0 return $this->_error($pdu->error());
90             }
91              
92             # We need to copy the contextEngineID and contextName to the
93             # request message so that they are available for comparison
94             # with the response message.
95              
96 0         0 $msg->context_engine_id($pdu->context_engine_id());
97 0         0 $msg->context_name($pdu->context_name());
98              
99             # Set a new msgID for each message unless the PDU type is a
100             # GetResponse-PDU or a Report-PDU.
101              
102 0 0 0     0 if (($pdu->pdu_type() != GET_RESPONSE) && ($pdu->pdu_type() != REPORT)) {
103 0         0 $pdu->msg_id($this->msg_handle_alloc());
104             }
105              
106             # msgGlobalData::=SEQUENCE
107              
108 0 0       0 if (!defined $this->_prepare_global_data($pdu, $msg)) {
109 0         0 return $this->_error();
110             }
111              
112             }
113              
114             # Pass off to the Security Model
115 1 50       24 if (!defined $pdu->security()->generate_request_msg($pdu, $msg)) {
116 0         0 return $this->_error($pdu->security()->error());
117             }
118              
119             # If a response to the message is expected, add the message to the
120             # cache using the msgId (request-id) has the lookup "handle".
121              
122 1 50       4 if ($pdu->expect_response()) {
123 1         3 $this->[_HANDLES]->{$msg->msg_id()} = $msg;
124             }
125              
126             # Return the new message.
127 1         3 return $msg;
128             }
129              
130             sub prepare_data_elements
131             {
132 1     1 0 188 my ($this, $msg) = @_;
133              
134             # Clear any previous errors
135 1         4 $this->_error_clear();
136              
137 1 50 33     9 if ((@_ != 2) || (!ref $msg)) {
138 0         0 return $this->_error('The Message object is missing or invalid');
139             }
140              
141             # message::=SEQUENCE
142 1 50       4 return $this->_error($msg->error()) if !defined $msg->process(SEQUENCE);
143              
144             # version::=INTEGER
145 1 50       4 if (!defined $msg->version($msg->process(INTEGER))) {
146 0         0 return $this->_error($msg->error());
147             }
148              
149             # Find the request message in the cache. We are assuming this
150             # message is a response to an outstanding request.
151              
152 1         2 my $request;
153              
154 1 50       4 if ($msg->version() == SNMP_VERSION_3) {
155              
156             # msgGlobalData::=SEQUENCE
157 0 0       0 if (!defined $this->_process_global_data($msg)) {
158 0         0 return $this->_error();
159             }
160              
161 0         0 $request = $this->msg_handle_delete($msg->msg_id());
162              
163             } else {
164              
165             # community::=OCTET STRING
166 1 50       3 if (!defined $msg->security_name($msg->process(OCTET_STRING))) {
167 0         0 return $this->_error($msg->error());
168             }
169              
170             # Cast the Message to a PDU
171 1 50       4 if (!defined($msg = Net::SNMP::PDU->new($msg))) {
172 0         0 return $this->_error('Failed to allocate a new PDU object');
173             }
174              
175             # PDU::=SEQUENCE
176 1 50       4 if (!defined $msg->process_pdu_sequence()) {
177 0         0 return $this->_error($msg->error());
178             }
179              
180 1 50       4 if ($msg->pdu_type() != GET_RESPONSE) {
181 1         4 return $this->_error(
182             'A %s was expected, but %s was found',
183             asn1_itoa(GET_RESPONSE), asn1_itoa($msg->pdu_type())
184             );
185             }
186              
187 0         0 $request = $this->msg_handle_delete($msg->request_id());
188              
189             }
190              
191             # Was a matching request found?
192 0 0       0 if (!defined $request) {
193 0         0 return $this->_error('No matching request message was found');
194             }
195              
196             # Update the received message with the relevant request data.
197 0         0 $msg->callback($request->callback());
198 0         0 $msg->timeout_id($request->timeout_id());
199 0         0 $msg->transport($request->transport());
200              
201             # Now that we have found the matching request for this response
202             # we return a FALSE error instead of undefined so that the error
203             # gets propagated back to the user.
204              
205             # Compare the Security Models
206 0 0       0 if ($msg->msg_security_model() != $request->msg_security_model()) {
207 0         0 $this->_error(
208             'The msgSecurityModel %d was expected, but %d was found',
209             $request->msg_security_model(), $msg->msg_security_model()
210             );
211 0         0 return FALSE;
212             }
213            
214 0         0 $msg->security($request->security());
215              
216             # Pass off to the Security Model
217 0 0       0 if (!defined $request->security()->process_incoming_msg($msg)) {
218 0         0 $this->_error($request->security()->error());
219 0         0 return FALSE;
220             }
221              
222 0 0       0 if ($msg->version() == SNMP_VERSION_3) {
223              
224             # Adjust our maxMsgSize if necessary
225 0 0       0 if ($msg->msg_max_size() < $request->max_msg_size()) {
226 0         0 DEBUG_INFO('new maxMsgSize = %d', $msg->msg_max_size());
227 0 0       0 if (!defined $request->max_msg_size($msg->msg_max_size())) {
228 0         0 $this->_error($request->error());
229 0         0 return FALSE;
230             }
231             }
232              
233             # Cast the Message to a PDU
234 0 0       0 if (!defined($msg = Net::SNMP::PDU->new($msg))) {
235 0         0 $this->_error('Failed to allocate new PDU object');
236 0         0 return FALSE;
237             }
238              
239             # ScopedPDU::=SEQUENCE
240 0 0       0 if (!defined $msg->process_pdu_scope()) {
241 0         0 $this->_error($msg->error());
242 0         0 return FALSE;
243             }
244              
245             # PDU::=SEQUENCE
246 0 0       0 if (!defined $msg->process_pdu_sequence()) {
247 0         0 $this->_error($msg->error());
248 0         0 return FALSE;
249             }
250              
251 0 0       0 if ($msg->pdu_type() != REPORT) {
252              
253 0 0       0 if ($msg->pdu_type() != GET_RESPONSE) {
254 0         0 $this->_error(
255             'A %s was expected, but %s was found',
256             asn1_itoa(GET_RESPONSE), asn1_itoa($msg->pdu_type())
257             );
258 0         0 return FALSE;
259             }
260              
261             # Compare the contextEngineID
262 0 0       0 if ($msg->context_engine_id() ne $request->context_engine_id()) {
263 0         0 $this->_error(
264             'The contextEngineID "%s" was expected, but "%s" was found',
265             unpack('H*', $request->context_engine_id()),
266             unpack('H*', $msg->context_engine_id()),
267             );
268 0         0 return FALSE;
269             }
270              
271             # Compare the contextName
272 0 0       0 if ($msg->context_name() ne $request->context_name()) {
273 0         0 $this->_error(
274             'The contextName "%s" was expected, but "%s" was found',
275             $request->context_name(), $msg->context_name()
276             );
277 0         0 return FALSE;
278             }
279              
280             # Check the request-id
281 0 0       0 if ($msg->request_id() != $request->request_id()) {
282 0         0 $this->_error(
283             'The request-id %d was expected, but %d was found',
284             $request->request_id(), $msg->request_id()
285             );
286 0         0 return FALSE;
287             }
288             }
289              
290             }
291              
292             # Now update the message with format parameters.
293 0         0 $msg->leading_dot($request->leading_dot());
294 0         0 $msg->translate($request->translate());
295              
296             # VarBindList::=SEQUENCE OF VarBind
297              
298 0 0       0 if (!defined $msg->process_var_bind_list()) {
299 0         0 $this->_error($msg->error());
300 0         0 return FALSE;
301             }
302              
303             # Return the PDU
304 0         0 return $msg;
305             }
306              
307             sub msg_handle_alloc
308             {
309 0     0 0 0 my ($this) = @_;
310              
311             # Limit message handles by RFC 3412 - msgID::=INTEGER (0..2147483647)
312              
313 0         0 my $handle = int rand(2147483648);
314              
315 0   0     0 while (exists $this->[_HANDLES]->{$handle} &&
  0         0  
316             keys %{$this->[_HANDLES]->{$handle}} < 2147483648)
317             {
318 0         0 $handle = int rand(2147483648);
319             }
320              
321 0         0 return $handle;
322             }
323              
324             sub msg_handle_delete
325             {
326 0     0 0 0 my ($this, $handle) = @_;
327              
328             # Clear any previous errors
329 0         0 $this->_error_clear();
330              
331 0 0       0 return $this->_error('No msgHandle was specified') if (@_ < 2);
332              
333 0 0       0 if (!exists $this->[_HANDLES]->{$handle}) {
334 0         0 return $this->_error('The msgHandle %d was not found', $handle);
335             }
336              
337 0         0 return delete $this->[_HANDLES]->{$handle};
338             }
339              
340             sub error
341             {
342 2   100 2 0 25 return $_[0]->[_ERROR] || q{};
343             }
344              
345             sub debug
346             {
347 1 0   1 0 6 return (@_ == 2) ? $DEBUG = ($_[1]) ? TRUE : FALSE : $DEBUG;
    50          
348             }
349              
350             # [private methods] ----------------------------------------------------------
351              
352             sub _new
353             {
354 2     2   5 my ($class) = @_;
355              
356             # The constructor is private since we only want one MessageProcessing
357             # object. We also reserve message handle (request-id/msgID) 0 so that
358             # it is not used for valid messages.
359              
360 2         3609 return bless [ undef, { 0, undef } ], $class;
361             }
362              
363             sub _prepare_global_data
364             {
365 0     0   0 my ($this, $pdu, $msg) = @_;
366              
367             # msgSecurityModel::=INTEGER
368              
369 0 0       0 if (!defined
370             $msg->prepare(
371             INTEGER, $msg->msg_security_model($pdu->msg_security_model())
372             )
373             )
374             {
375 0         0 return $this->_error($msg->error());
376             }
377              
378             # msgFlags::=OCTET STRING
379              
380 0         0 my $security_level = $pdu->security_level();
381 0         0 my $msg_flags = MSG_FLAGS_NOAUTHNOPRIV | MSG_FLAGS_REPORTABLE;
382              
383 0 0       0 if ($security_level > SECURITY_LEVEL_NOAUTHNOPRIV) {
384 0         0 $msg_flags |= MSG_FLAGS_AUTH;
385 0 0       0 if ($security_level > SECURITY_LEVEL_AUTHNOPRIV) {
386 0         0 $msg_flags |= MSG_FLAGS_PRIV;
387             }
388             }
389              
390 0 0       0 if (!$pdu->expect_response()) {
391 0         0 $msg_flags &= ~MSG_FLAGS_REPORTABLE;
392             }
393              
394 0 0       0 if (!defined $msg->prepare(OCTET_STRING, pack 'C', $msg_flags)) {
395 0         0 $this->_error($msg->error());
396             }
397              
398 0         0 $msg->msg_flags($msg_flags);
399              
400             # msgMaxSize::=INTEGER
401              
402 0 0       0 if (!defined
403             $msg->prepare(INTEGER, $msg->msg_max_size($pdu->max_msg_size()))
404             )
405             {
406 0         0 return $this->_error($msg->error());
407             }
408              
409             # msgID::=INTEGER
410 0 0       0 if (!defined $msg->prepare(INTEGER, $msg->msg_id($pdu->msg_id()))) {
411 0         0 return $this->_error($msg->error());
412             }
413              
414             # msgGlobalData::=SEQUENCE
415 0 0       0 if (!defined $msg->prepare(SEQUENCE)) {
416 0         0 return $this->_error($msg->error());
417             }
418              
419 0         0 return TRUE;
420             }
421              
422             sub _process_global_data
423             {
424 0     0   0 my ($this, $msg) = @_;
425              
426             # msgGlobalData::=SEQUENCE
427 0 0       0 return $this->_error($msg->error()) if !defined $msg->process(SEQUENCE);
428              
429             # msgID::=INTEGER
430 0 0       0 if (!defined $msg->msg_id($msg->process(INTEGER))) {
431 0         0 return $this->_error($msg->error());
432             }
433              
434             # msgMaxSize::=INTEGER
435 0 0       0 if (!defined $msg->msg_max_size($msg->process(INTEGER))) {
436 0         0 return $this->_error($msg->error());
437             }
438              
439             # msgFlags::=OCTET STRING
440              
441 0         0 my $msg_flags = $msg->process(OCTET_STRING);
442              
443 0 0       0 if (!defined $msg_flags) {
444 0         0 return $this->_error($msg->error());
445             }
446              
447 0 0       0 if (CORE::length($msg_flags) != 1) {
448 0         0 return $this->_error(
449             'The msgFlags length of %d is invalid', CORE::length($msg_flags)
450             );
451             }
452              
453 0         0 $msg->msg_flags($msg_flags = unpack 'C', $msg_flags);
454              
455             # Validate the msgFlags and derive the securityLevel.
456              
457 0         0 my $security_level = SECURITY_LEVEL_NOAUTHNOPRIV;
458              
459 0 0       0 if ($msg_flags & MSG_FLAGS_AUTH) {
    0          
460 0         0 $security_level = SECURITY_LEVEL_AUTHNOPRIV;
461 0 0       0 if ($msg_flags & MSG_FLAGS_PRIV) {
462 0         0 $security_level = SECURITY_LEVEL_AUTHPRIV;
463             }
464             } elsif ($msg_flags & MSG_FLAGS_PRIV) {
465              
466             # RFC 3412 - Section 7.2 1d: "If the authFlag is not set
467             # and privFlag is set... ...the message is discarded..."
468              
469 0         0 return $this->_error('The msgFlags value 0x%02x is invalid', $msg_flags);
470             }
471              
472             # RFC 3412 - Section 7.2 1e: "Any other bits... ...are ignored."
473 0 0       0 if ($msg_flags & ~MSG_FLAGS_MASK) {
474 0         0 DEBUG_INFO('questionable msgFlags value 0x%02x', $msg_flags);
475             }
476              
477 0         0 $msg->security_level($security_level);
478              
479             # msgSecurityModel::=INTEGER
480 0 0       0 if (!defined $msg->msg_security_model($msg->process(INTEGER))) {
481 0         0 return $this->_error($msg->error());
482             }
483              
484 0         0 return TRUE;
485             }
486              
487             sub _error
488             {
489 1     1   2 my $this = shift;
490              
491 1 50       3 if (!defined $this->[_ERROR]) {
492 1 50       9 $this->[_ERROR] = (@_ > 1) ? sprintf(shift(@_), @_) : $_[0];
493 1 50       4 if ($this->debug()) {
494 0         0 printf "error: [%d] %s(): %s\n",
495             (caller 0)[2], (caller 1)[3], $this->[_ERROR];
496             }
497             }
498              
499 1         2 return;
500             }
501              
502             sub _error_clear
503             {
504 2     2   9 return $_[0]->[_ERROR] = undef;
505             }
506              
507             sub DEBUG_INFO
508             {
509 0 0   0 0   return $DEBUG if (!$DEBUG);
510              
511 0 0         return printf
512             sprintf('debug: [%d] %s(): ', (caller 0)[2], (caller 1)[3]) .
513             ((@_ > 1) ? shift(@_) : '%s') .
514             "\n",
515             @_;
516             }
517              
518             # ============================================================================
519             1; # [end Net::SNMP::MessageProcessing]