User-based security agent available

["glenn (g.) waters" <[e-mail]>]

An implementation of a SNMPv2 agent based on the new USEC security
model is available from:

	ftp://ftp.cisco.com/ftp/kzm/cmusnmp-1.1b-v2usec.tar.gz

The file README.usec, included in the distribution, describes how
to build, install and use the agent and applications.

The implementation notes for the agent follow.

/gww

----

	  User-based Security Model Implementation Notes

1.0 Introduction

The CMU SNMP package, cmusnmp-1.1b, is a set of SNMPv1 manager
applications and a SNMPv1 agent.  This package was used as the basis for
implementing the USEC proposal.  In addition, a number of files from the
cmusnmp-2.1.2 package were merged in with the cmusnmp-1.1b package.
These files were to implement SNMPv2 protocol operations and SNMPv2 SMI.
This work is not specifically discussed here.

*Aside* 
I started with the CMU 1.1 code because I had previously
implemented a security model similar to the USEC model.  The previous
work was based on the CMU 1.1 agent and did not have any SNMPv2
features.  It was thought to be easier to continue using my modified
code and retrofit the SNMPv2 protocol and SMI features back into the
SNMPv1 agent as opposed to retrofitting my existing security model
changes into the CMU 2.1.2 code.  
*End Aside*

The goals of my effort were to make this package compliant with the
SNMPv2 User-Based security model and the rest of the SNMPv2 documents as
modified for supporting security models (see
<draft-kzm-snmpv2-*alt-*.txt>).

The modifications consisted of changing the API layer to support both
managers and agents and then modifying the agent to be compliant.  Very
few changes were required to the manager applications.

My primary interest in this work was timely completion of the work while
remaining compliant to the specifications.  As such, the APIs could have
been reworked substantially to better support this work.

2.0 API Changes

The major change to the API layer was the addition of the USEC security
parameters to the "session" structure.

The routines to implement encoding and decoding of the parameters field
total about 200 lines of code.  There is nothing complex in the code,
just some precision in catching errors in the correct order.  The
authentication algorithm (timeliness, checking agentID, etc) was trivial
to implement.

The API is written such that both the agent and applications may make
use of it.  As such, the session structure originally intended for
applications was used by the agent.  Given more time, the session
structure would have to split into two separate structures.  A session
structure, for applications that really have sessions, and a parameters
structure that contains the security model parameters.

2.1 Agent changes

Implementing the usecAgent objects was trivial.  The agentTime requires
taking a snapshot of the system clock at agent boot time.  All agentTime
references were relative to the initial agent start time.

The agentBoots took six lines of code to implement.  Read a file
containing the agentBoots object, increment the value, then write it
back out.

AgentID is fixed based on the private enterprise number bnr(35) and the
IP address of the agent host.

I picked a value of 1450 for MMS.  One line of code dealt with checking
the MMS that should be used on a response -- based on the minimum of the
received MMS and my local MMS.

The routines that build and parse the parameters field were in the API;
the routines just had to be called from the agent.  The SNMP version
number was used to select when the USEC model authentication routines
were to be invoked.

When a communication was received, the userName had to be parsed out of
the parameters before passing the parameters to the API for full
authentication checking.  This was required to setup the session
structure with the correct userName, key, and qoS.  It also required
doing some trivial checking on the correct encoding of the parameters
field.

The configuration file processing took 300 lines of code.  Nothing
complex here.

2.2 Manager changes

The goal was to not change a line of code in the applications.  This was
accomplished for the most part.

The security model did not necessitate any change in the applications.
The SNMPv2 features did.  snmpwalk was modified to understand the
Report-PDU and error codes in the varbinds.  The other applications were
modified to indicate that a report was received.  This change could have
been left out, but was performed to give clearer output from the
applications.

The snmpget application was cloned to produce the snmpbulk application.
About 10 lines of code were added to deal with new parameters for
selecting the non-repeaters and repetitions counts.  One other line of
code was changed to change the PDU type from get to getbulk.

The session open API call was modified to parse the community string,
select the correct SNMP version, and synchronize the usecAgent objects
if appropriate.  This is all hidden from the application.  The only
downside to the approach I used is that the first character of the
"community" name was used to indicate whether this was a v1 or a v2
communication.

3.0 Summary

The USEC model code took about two days to write.  I did not find any
parts there were difficult to implement.  The most complex part of the
task was getting to know the CMU SNMP code.  This was my first exposure
to it.  Overall the task was very easy.
-- 

/Glenn Waters, [e-mail], Bell-Northern Research Ltd., [phone]