Java Dynamic Management Kit 5.0 Tutorial

SNMPv3 User-Based Security Model

As stated in the earlier SNMP chapters in this manual, SNMPv3 implements a much more sophisticated set of security mechanisms than the previous versions of SNMP. The SNMPv3 USM enables you to implement authentication and privacy in the communication that takes place between your SNMP agents and managers. SNMPv3 also introduces the concept of the authoritative SNMP engine and enables you to create authorized users for specific SNMPv3 agents.

Chapter 18, Creating an SNMP Agent and Chapter 19, Developing an SNMP Manager provided just enough information about configuring SNMPv3 security to enable you to run the examples in those chapters. The following sections provide a more complete description of SNMPv3 security.

SNMPv3 Engines

SNMPv3 introduces the notion of the authoritative SNMP engine. The concept of authoritative is defined as follows:

Authoritative engines receive acknowledged requests, namely get, set, getnext, getbulk and informs. Authoritative engines also send traps (unacknowledged)
Non-authoritative engines send the above acknowledged requests and receive unacknowledged traps

Being authoritative means that entities have the ability to accept or deny requests from other entities, depending upon whether or not both sides of the exchange have been appropriately configured to communicate with each other, and whether the request itself arrives in a timely fashion. To check the timeliness of a request, the authoritative engine checks the time of sending included in the request against its own internal clock. If the difference between the time of sending and the time of receipt recorded by the authoritative engine exceeds 150 seconds, the request is not considered timely and is rejected.

The authoritative engine also checks timeliness by reading the localEngineBoots value recorded in the request, and comparing it to the number of reboots that the sending engine has undergone. It checks this by calling the SnmpEngine.getEngineBoots. If the value recorded in the request and the value returned by SnmpEngine.getEngineBoots do not correspond, the request is rejected.

In general, agents are authoritative, and managers are non-authoritative. However, when receiving informs, managers are authoritative, and can accept or deny the informs according to their timeliness.

Java DMK 5.0 associates an SNMP engine with every SnmpV3AdaptorServer that is instantiated. Engines can be shared between several SNMP sessions. SNMP engines are identified by their engine ID.

Generating SNMPv3 Engine IDs

SNMPv3 engine ID objects are generated in accordance with SNMP RFC 2571. An engine discovers its ID in one of the following ways, each of which is tried in the order shown:

It is found in the engine's associated jdmk.security file
It is found using SnmpEngineParameters
It is computed by the SNMP adaptor, based on the host and port information, or it is computed by the SNMP session, based on time

In Java DMK 5.0, you can create new SNMP engine IDs either manually using a Java command line tool called EngineIdGenerator, or automatically in the code of your applications using the SnmpEngineId class. You can see the EngineIdGenerator tool in the examplesDir/Snmp/EngineId directory. You must provide either of EngineIdGenerator or SnmpEngineId with any of the following information:

An engine ID you have computed previously
An IP address or DNS host name
A UDP port
An Internet Assigned Numbers Authority (IANA) number

The EngineIdGenerator uses the SnmpEngineId class when generating engine IDs (see the Javadoc entry for SnmpEngineId for details). The SnmpEngineId class simplifies the configuration of SNMP entities by enabling you to identify engines using information that is easily comprehensible to humans, such as host names and port numbers, which it then converts into system-oriented hexadecimal engine IDs for you. The SnmpEngineId class also generates SNMP object identifiers (OIDs) from the engine IDs it creates. This is particularly useful when computing USM MIB user table indexes, as seen in Creating Users for SNMPv3 USM MIBs.

To Run the SNMP `EngineIdGenerator` Example

Compile the EngineIdGenerator class in examplesDir/Snmp/EngineId.
$ javac -classpath classpath EngineIdGenerator.java

Start the EngineIdGenerator tool.

$ javac -classpath classpath EngineIdGenerator
Start making your engine Id construct:(h for help)
#:

Typing h will provide examples of information you can provide.

Provide the relevant information to create the engine ID.

Declare your information, using the appropriate separators, as follows:

address:port:IANA number

All three inputs are used

address:port

The address and port you specify are used; the IANA number defaults to 42 (SUN Microsystems)

address

The address you specify is used; the port defaults to 161 and the IANA number defaults to 42 (SUN Microsystems)

:port

The port you specify is used; the host defaults to localhost and the IANA number defaults to 42 (SUN Microsystems)

::IANA number

The IANA number you specify is used; the host defaults to localhost and the IANA number defaults to 42 (SUN Microsystems)

:port:IANA number

The port and IANA number you specify are used; the host defaults to localhost

address::IANA number

The address and IANA number you specify are used; the port defaults to 161

::

The port defaults to 161, the address defaults to localhost and the IANA number defaults to 42 (SUN Microsystems)

For example, to specify all three of the address, port and IANA number, when prompted you might type:
Start making your engine Id construct:(h for help) #:localhost:8087:42 Generated engine Id ******** [0x8000002a05819dcb6200001f97] ******** #:

Press Control-C when you have finished generating engine IDs

SNMPv3 USM Configuration

The SNMPv3 USM is configured in a Java DMK text file, called jdmk.security. Every SNMP engine has an associated security file.

In a traditional agent and manager SNMP architecture, you will have one security file associated with the agent and one associated with the manager. Both files will have a very similar configuration.

The authoritative agent's security file contains all the security information users need when requests are received from the manager. The non-authoritative manager's security file contains all the security information users need when making requests of authoritative agents.

The following examples show typical security files for an agent and a manager.

Example 20–3 A Typical Agent `jdmk.security` File

localEngineID=myHost:8085
localEngineBoots=7

#Typical authenticated entry. Accepts requests from a user called 
#aSecureUser
userEntry=localEngineID,aSecureUser,aSecureUser,
usmHMACMD5AuthProtocol, mypasswd

#Typical authenticated and encrypted entry. Accepts requests from 
#aSecureUser
#userEntry=localEngineID,aSecureUser,aSecureUser,
#usmHMACMD5AuthProtocol, #mypasswd,usmDESPrivProtocol,mypasswd

The example agent jdmk.security file identifies the agent's associated SNMP engine using its host name and port number, records the number of times that engine has rebooted, and sets two possible security configurations for a user called aSecureUser. One possible configuration applies authentication to requests from aSecureUser. The second configuration, which is currently commented out and is therefore inactive, applies both authentication and privacy to requests from the same user.

Example 20–4 A Typical Manager `jdmk.security` File

#Typical authenticated entry. Makes requests to authoritative engine 
#myHost:8085 with some parameters.
userEntry=myHost:8085,aSecureUser,aSecureUser,usmHMACMD5AuthProtocol, 
mypasswd

#Typical authenticated and encrypted entry. Makes requests to authoritative 
#engine myHost:8085 with some parameters.
#userEntry=myHost:8085,aSecureUser,aSecureUser,usmHMACMD5AuthProtocol, 
#mypasswd,
#usmDESPrivProtocol,mypasswd

# #####APPENDED PROPERTY####
localEngineBoots=5

# #####APPENDED PROPERTY####
localEngineID=myOtherHost:8087

The example manager jdmk.security file sets two possible configurations to send requests from the user aSecureUser to the above agent. Again, the first configuration applies authentication to requests from aSecureUser, and the second configuration, which is currently commented out and is therefore inactive, applies both authentication and privacy.

Note –

The localEngineID for each of the manager and the agent must be different. If two entities that communicate with each other have the same local engine ID, behavior is unpredictable.

Adding Users to the Security Files

As you can see in Example 20–3 and Example 20–4, every user that has access to an agent is represented by a userEntry row in each of the agent's and the manager's security files. The example manager jdmk.security file is configured to send requests from aSecureUser to the agent, either with authentication only, or with privacy activated. The agent is configured to receive those requests.

You configure userEntry as follows, with the parameters separated commas:

userEntry=engine ID,user name,security name,authentication algorithm,authentication key, privacy algorithm,privacy key,storage type,template

The only mandatory parameters are the engine ID and the user name. All the other parameters are optional.

The possible values for the parameters are as follows:

Engine ID

A local or remote SNMP engine, defined in one of the following ways:

The string localEngineID, to denote the local engine
A hexadecimal string, as generated by EngineIdGenerator; for example, 0x8000002a05819dcb6e00001f95
A human readable string used to generate an engine ID, providing any or all of the host name, port and IANA number, as shown in Generating SNMPv3 Engine IDs

User name

Any human-readable string

Security name

Any human-readable string

Authentication algorithm

The following algorithms are permitted:

usmHMACMD5AuthProtocol
usmHMACSHAAuthProtocol
usmNoAuthProtocol

Authentication key

Any text password or any hexadecimal key starting with 0x; for example, 0x0098768905AB67EFAA855A453B665B12, of size:

0 to 32 inclusive for HMACMD5
0 to 40 inclusive for HMACSHA

Privacy algorithm

The following algorithms are permitted:

usmDESPrivProtocol
usmNoPrivProtocol

If no algorithm is specified, the default is usmNoPrivProtocol.

Any text password or any hexadecimal key starting with 0x; for example, 0x0098768905AB67EFAA855A453B665B12, of size 0 to 32 inclusive

If a hexadecimal string is provided, it must be a localized key

Storage type

A value of 3 denotes non-volatile, meaning that the user entry is flushed in the security file; any other value than 3 will be rejected, throwing an IllegalArgumentException

template

Can be either true or false:

If true, the row is a template, not seen from USM MIB. This kind of user is used when cloning users.

The default is false.

Enabling Privacy in SNMPv3 Agents

As shown in the example security files given in SNMPv3 USM Configuration, you can protect the communication between your SNMPv3 entities by enabling encryption, otherwise known as privacy.

The privacy algorithms used by SNMPv3 are the data encyption standard (DES) protocol from the Java Cryptography Extension (JCE) from the Java Development Kit (JDK) 1.4, as well as the secure hash algorithm (SHA) and message digest 5 (MD5) encryption protocols provided since JDK 1.2.

To run an SNMP entity with privacy enabled, you must configure both the entity itself and its corresponding security file. The following example shows the code for an SNMPv3 agent with privacy enabled, called AgentEncryptV3. This example is found in the examplesDir/Snmp/Agent directory.

Example 20–5 `AgentEncryptV3` Agent with Privacy Enabled

public class AgentEncryptV3 {

    static SnmpV3AdaptorServer snmpAdaptor = null;
    
    private static int nbTraps = -1;

    public static void main(String args[]) {
        
        final MBeanServer server;
        final ObjectName htmlObjName;
        final ObjectName snmpObjName;
        final ObjectName mibObjName;
        final ObjectName trapGeneratorObjName;
        int htmlPort = 8082;
        int snmpPort = 161;

        // Parse the number of traps to be sent.
       
			[...]

        // Initialize trace property.
        

         [...]         
         
         // SNMP specific code:
         

	    	// Set up encryption 
	  
		   //First create parameters.
	    	SnmpEngineParameters parameters = new SnmpEngineParameters();

	    	//Then activate encryption
	    	parameters.activateEncryption();

	    	//Create the SNMPv3 adaptor and pass it the parameters.
            snmpAdaptor = new SnmpV3AdaptorServer(parameters,
						  null,
						  null,
						  snmpPort,
						  null);
	    
	    	// Register the SNMP Adaptor in the MBean Server 
		   //
            server.registerMBean(snmpAdaptor, snmpObjName);

	    	// Register the USM MIB
		   snmpAdaptor.registerUsmMib(server, null);

	    	// Start the adaptor.
            snmpAdaptor.start();

            // Send a coldStart SNMP Trap. 
            // Use port = snmpPort+1.
            //
            print("NOTE: Sending a coldStart SNMP trap to each " +
		  		"destination defined in the ACL file...");

            snmpAdaptor.setTrapPort(new Integer(snmpPort+1));
            snmpAdaptor.snmpV1Trap(0, 0, null);
            println("Done.");
      
            // Create the MIB II (RFC 1213) and add it to the MBean server.
            //
            mibObjName= new ObjectName("snmp:class=RFC1213_MIB");
            Trace.send(Trace.LEVEL_TRACE, Trace.INFO_MISC, "Agent", "main", 
                       "Adding RFC1213-MIB to MBean server with name \n\t" +
                       mibObjName);

            // Create an instance of the customized MIB
            //
            RFC1213_MIB mib2 = new RFC1213_MIB_IMPL();
            server.registerMBean(mib2, mibObjName);
      
            // Bind the SNMP adaptor to the MIB to make the MIB 
            // accessible through the SNMP protocol adaptor.
            //
			    snmpAdaptor.addMib(mib2, "TEST-CONTEXT");

            // Create a LinkTrapGenerator.
            // Specify the ifIndex to use in the object name.
            //
            String trapGeneratorClass = "LinkTrapGenerator";
            int ifIndex = 1;
            trapGeneratorObjName = new ObjectName("trapGenerator" + 
                            ":class=LinkTrapGenerator,ifIndex=" + ifIndex);
            Trace.send(Trace.LEVEL_TRACE, Trace.INFO_MISC, "Agent", "main", 
                  "Adding LinkTrapGenerator to MBean server with name \n\t"+
		  		trapGeneratorObjName);
            LinkTrapGenerator trapGenerator = 
					new LinkTrapGenerator(nbTraps);
            server.registerMBean(trapGenerator, trapGeneratorObjName);

            println("\n>> Press Enter if you want to start sending traps."+
		    " SNMP V1 and SNMP V3 traps will be sent.");
            println("   -or-");
            println(">> Press Ctrl-C if you want to stop this agent.");
            java.lang.System.in.read();
            
            trapGenerator.start();
            
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

   }

By default, a Java DMK 5.0 agent handles requests that are authenticated, but not encrypted. To activate encryption, you need to set certain parameters when you instantiate the SNMP engine. As shown inExample 20–5, these parameters are passed to the engine using the SnmpEngineParameters class, as follows:

Firstly, the application creates new SNMP engine parameters, called parameters in this example, by calling SnmpEngineParameters:

SnmpEngineParameters parameters = new SnmpEngineParameters();
Then it activates encryption by making parameters call the activateEncryption method:

parameters.activateEncryption();
Finally, it then passes the parameters to the newly created SNMPv3 adaptor server:

snmpAdaptor = new SnmpV3AdaptorServer(parameters, null, null, snmpPort, null)

The AgentEncryptV3 application then continues with the registration of the SNMP adaptor server in the MBean server, binding the MIBs and calling LinkTrapGenerator in the same way as any other agent.

As well as the agent itself, you must also configure the security file associated with that agent. Example 20–6 shows the security file associated with AgentEncryptV3.

Example 20–6 Agent `jdmkencrypt.security` File

#Local engine Id. Will be read by the agent to configure the engine.
localEngineID=0x8000002a05819dcb6e00001f95
#Number of boots. Will be read by the agent to configure the engine.
localEngineBoots=0

#defaultUser configuration. Authentication and encryption.
userEntry=localEngineID,defaultUser,null,usmHMACMD5AuthProtocol,mypasswd,
usmDESPrivProtocol,mypasswd,3,

In this file, you can see that the DES privacy protocol is specified.

To Run the `AgentEncryptV3` Example

If you have not already done so, build and compile the AgentEncryptV3 example in examplesDir/Snmp/Agent.

Type the following commands:
$ mibgen -d . mib_II.txt $ javac -classpath classpath -d . *.java

Start the AgentEncryptV3 agent, passing it its associated security file, jdmkencrypt.security.

$ java -classpath classpath 
-Djdmk.security.file=./jdmkencrypt.security AgentEncryptV3

Press Enter to start sending traps

NOTE: Sending a linkDown SNMP trap for the Interface 1 to each 
destination defined in the ACL file...Done.
NOTE: Sending a linkDown SNMP trap for the Interface 1 to each 
destination defined in the ACL file...Done.

Press Control-C to stop the agent

Enabling Privacy in SNMPv3 Managers

If you enable privacy in your SNMPv3 agents, then you must also enable privacy in the corresponding manager. The following example shows the code for an SNMPv3 agent with privacy enabled, called SyncManagerEncryptV3. This example is found in the examplesDir/Snmp/Manager directory.

Example 20–7 `SyncManagerEncryptV3` Manager with Privacy Enabled

/**
 public class SyncManagerEncryptV3 {
   
    	public static void main(String argv[]) {
		SnmpSession session = null;
	
        if (argv.length != 2) {
            usage();
            java.lang.System.exit(1);
        }
	
			//Check arguments first
			//host and port.
        final String host = argv[0];
        final String port = argv[1];
	
        // Initialize trace property. 
 			[...] 
	

      	// Initialize the SNMP Manager API.
        //
	    	[...] 
	    

  		// Activate the encryption
	    
		   //

	   		// First create parameters.
	    	//
	    	final SnmpEngineParameters parameters = 
			new SnmpEngineParameters();

	    	// Then activate encryption
	    	parameters.activateEncryption();

	    	// Finaly create the session passing it the parameters.
	    	try {
			// When instantiating a session, a new SNMP V3 engine is 
			// instantiated.
			session= new SnmpSession(parameters,
					 null,
					 "SyncV3Manager session",
					 null);
	    	}catch(SnmpStatusException e) {
			println(e.getMessage());
			java.lang.System.exit(0);
	    }
	    	catch(IllegalArgumentException e) {
			//If the engine configuration is falty
			println(e.getMessage());
			java.lang.System.exit(0);
	    }
	    
	   		final SnmpEngine engine = session.getEngine();
	    
	    	// Create a SnmpPeer object 
		   //
	    	final SnmpUsmPeer agent = 
			new SnmpUsmPeer(engine, host, Integer.parseInt(port));
	    
	    	// Create parameters to associate to the entity to 
	    	// communicate with.
	  		//
	    	final SnmpUsmParameters p = 
			new SnmpUsmParameters(engine, "defaultUser");
	    
	    	// Set Security level 
	    	//
	     	p.setSecurityLevel(SnmpDefinitions.authPriv);

	    	// Register MIBS under the scope of a context.
			//
	    	p.setContextName("TEST-CONTEXT".getBytes());

	    	// Specify a contextEngineId. This is 
	    	//
	    	p.setContextEngineId(agent.getEngineId().getBytes());
	    
	    	// The newly created parameter must be associated to the agent.
	    	//
	    	agent.setParams(p);
	
	    
	    	// Discovery timeliness
	    	//
	    	agent.processUsmTimelinessDiscovery();
	    
	    	// A default peer (agent) can be associated to a SnmpSession. 
	   	   //
	   		session.setDefaultPeer(agent);
	    
	 	 	// Create a listener and dispatcher for SNMP traps 
	    	final SnmpEventReportDispatcher trapAgent =
			new SnmpEventReportDispatcher(engine, 
					      Integer.parseInt(port) + 1, 
					      taskServer, null);
	    	trapAgent.addTrapListener(new TrapListenerImpl());
            final Thread trapThread = new Thread(trapAgent);
	    	trapThread.setPriority(Thread.MAX_PRIORITY);
	    	trapThread.start();
	    
	    
	    	// Build the list of variables you want to query.
	    	// For debug purposes, you can associate a name to your list.
	    	//
	    	final SnmpVarBindList list = 
			new SnmpVarBindList("SyncManagerEncryptV3 varbind list");
	    
	    	// We want to read the "sysDescr" variable.
	    	//
            // We will thus query "sysDescr.0", as sysDescr is a scalar
	    		// variable (see RFC 1157, section 3.2.6.3.  Identification 
           	// of Object Instances, or RFC 2578, section 7.  Mapping of 
	    		// the OBJECT-TYPE macro).
	    		//
	    		list.addVarBind("sysDescr.0");
	    
	    	// Make the SNMP get request and wait for the result.
	    	//
	    	final SnmpRequest request = session.snmpGetRequest(null, list);
	    	println("SyncManagerEncryptV3::main:" + 
				 " Send get request to SNMP agent on " + 
				 host + " at port " + port);
	    	final boolean completed = request.waitForCompletion(10000);
	    
	    	// Check for a timeout of the request.
	    	//
            if (completed == false) {
                println("SyncManagerEncryptV3::main:" +
			" Request timed out. Check reachability of agent");
		
                // Print request.
                //
                println("Request: " + request.toString());
                java.lang.System.exit(0);
            }
	    
            // Check if the response contains an 
	    		// error.
            //
            final int errorStatus = request.getErrorStatus();
            if (errorStatus != SnmpDefinitions.snmpRspNoError) {
                println("Error status = " + 
				SnmpRequest.snmpErrorToString(errorStatus));
                println("Error index = " + 
				request.getErrorIndex());
                java.lang.System.exit(0);
            }
       
            // Display the content of the result.
            //
            final SnmpVarBindList result = request.getResponseVarBindList();
            println("Result: \n" + result);
       
            println("\n>> Press Enter if you want to stop" +
		    " this SNMP manager.\n");
            java.lang.System.in.read();
            
            // Nicely stop the session
            //
            session.destroySession();
       
	    		// End the SnmpEventReportDispatcher.
	    		//
	    		trapAgent.close();
	    		taskServer.terminate();

            //
            // That's all !
            //
            java.lang.System.exit(0);
     
				} catch(Exception e) {
            java.lang.System.err.println("SyncManagerEncryptV3::main:" +
					 " Exception occurred:" + e );
            e.printStackTrace();
        }
    }

    
}

By default, a Java DMK 5.0 manager handles requests that are authenticated, but not encrypted. To activate encryption, you need to set certain parameters when you instantiate the SNMP session. As shown in Example 20–7, these parameters are passed to the engine using the SnmpEngineParameters class, as follows:

Firstly, the application creates new SNMP engine parameters, called parameters in this example, by calling SnmpEngineParameters:

SnmpEngineParameters parameters = new SnmpEngineParameters();
Then it activates encryption by making parameters call the activateEncryption method:

parameters.activateEncryption();
Finally, it then passes the parameters to the newly created SNMPv3 session:

session= new SnmpSession(parameters, null, "SyncV3Manager session", null)

The SyncManagerEncryptV3 manager application then continues with the generation of a USM peer, defining the context and setting trap listeners in the same way as any other manager. Note, however, that in this manager, the security level is set to authPriv.

As well as the manager itself, you must also configure the security file associated with that manager. Example 20–8 shows the security file associated with SyncManagerEncryptV3.

Example 20–8 Manager `jdmkencrypt.security` File

#Authentication and encryption.
userEntry=0x8000002a05819dcb6e00001f95,defaultUser,,
usmHMACMD5AuthProtocol,mypasswd,usmDESPrivProtocol,mypasswd

# #####APPENDED PROPERTY####
localEngineBoots=2

# #####APPENDED PROPERTY####
localEngineID=0x8000002a05000000ebffd342ca

As was the case for the AgentEncryptV3 agent, in this file, you can see that the DES privacy protocol is specified.

To Run the `SyncManagerEncryptV3` Example

If you have not already done so, build and compile the AgentEncryptV3 example in examplesDir/Snmp/Agent.

Type the following commands:
$ mibgen -d . mib_II.txt $ javac -classpath classpath -d . *.java

Start the AgentEncryptV3 agent, passing it its associated security file, jdmkencrypt.security.
$ java -classpath classpath -Djdmk.security.file=./jdmkencrypt.security AgentEncryptV3
Press Enter to start sending traps.

Press Enter to start sending traps.

In another window, if you have not already done so, build and compile the SyncManagerEncryptV3 example in examplesDir/Snmp/Manager.

Type the following commands:
$ mibgen -mo -d . mib_II.txt $ javac -classpath classpath -d . *.java

Start the SyncManagerEncryptV3 manager, passing it its associated security file, jdmkencrypt.security, and specifying the host name and port number of the agent it is to communicate with.

$ java -classpath classpath -Djdmk.security.file=./jdmkencrypt.security 
SyncManagerEncryptV3 localhost 8085

You should see the manager start to receive encrypted traps from the agent.

SyncManagerEncryptV3::main: 
Send get request to SNMP agent on localhost at port 8085
Result: 
[Object ID : 1.3.6.1.2.1.1.1.0  (Syntax : String)
Value : SunOS sparc 5.8]

>> Press Enter if you want to stop this SNMP manager.

NOTE: TrapListenerImpl received trap V3:
        ContextEngineId : 0x8000002a05819dcb6e00001f95
        ContextName : TEST-CONTEXT
        VarBind list :
oid : 1.3.6.1.2.1.1.3.0 val : 0:0:40
oid : 1.3.6.1.6.3.1.1.4.1.0 val : 1.2.3.4.5.6.7.8.9.0
oid : 1.3.6.1.2.1.2.2.1.1.1 val : 1

Press Control-C in each window to stop both the agent and the manager

Creating Users for SNMPv3 USM MIBs

The SNMPv3 USM implemented in Java DMK 5.0 enables you to create users remotely in an SNMPv3 agent by accessing a MIB that has been registered in the SNMPv3 adaptor server. By default, the USM MIB is not registered in the adaptor server. You can register a MIB in the adaptor server by calling registerUsmMib.

$ snmpV3AdaptorServer.registerUsmMib()

Caution –

You can use registerUsmMib to register your MIB in the MBean server, making it available via the HTML server. This can be useful for debugging purposes, but this can also represent a security breach.

The CreateUsmMibUser example in the examplesDir/Snmp/UsmMib directory is a tool that uses the SNMPv3 manager API to instantiate a new user in an agent USM MIB. CreateUsmMibUser performs authenticated and encrypted communication with the agent Agent, which is found in the same directory.

The complete code for the CreateUsmMibUser example is too long to show here, but the process that it goes through to create new users remotely can be summarized as follows:

The CreateUsmMibUser class uses a user template, called defaultUser, to bootstrap the remote configuration of the USM MIB. Because defaultUser is a template, it does not appear in the USM MIB, and therefore it is not visible to remote managers. CreateUsmMibUser knows of defaultUser because it is present in its configuration file, manager.security, as shown in the following example.

Example 20–9 `manager.security` File for the `CreateUsmMibUser` Example

localEngineID=0x8000002a05000000ec6c315f54
localEngineBoots=0

# User to create remotely in the agent.
userEntry=0x000000000000000000000002,myNewUser,
myNewUser,usmHMACMD5AuthProtocol,newsyrup,
usmDESPrivProtocol,newsyrup

# Template user to be used by the manager
userEntry=0x000000000000000000000002,defaultUser,,
usmHMACMD5AuthProtocol,maplesyrup,usmDESPrivProtocol,
maplesyrup

CreateUsmMibUser uses the defaultUser template to send an initial secure configuration request to create a new user, called myNewUser in this example. The newly created user will be a normal user, and will thus appear in the USM MIB.

CreateUsmMibUser implements the key-change mechanism defined inSNMP RFC 2574. This enables you to allocate new keys to the newly created users. Calling getUsmKeyHandler enables you to compute key localization and delta generation. An instance of SnmpUsmKeyHandler is associated to each SNMP engine object. When one of the standard authentication algorithms is used when computing the key. Because the CreateUsmMibUser example operates with authentication activated, the new peer agent has to perform timeliness checks on the incoming requests for the creation of new users. If proven timely, the request for a new user is granted and the creation process proceeds. Otherwise, the request is rejected.
Once the request has been accepted and the data provided by the user has been parsed and processed, the CreateUsmMibUser clones a new userEntry in the agent's jdmk.security file. The cloned entry is based on the defaultUser template entry, with the new information provided by the user added using the cloneFromUser variables.
In the CreateUsmMibUser example, the new user myNewUser is remotely granted access to the agent Agent. The agent's initial security configuration is set in the jdmk.security file for Agent, which is found in the examplesDir/Snmp/UsmMib directory, as shown below:

Example 20–10 jdmk.securityFile for Agent in the CreateUsmMibUser Example
localEngineID=0x000000000000000000000002 localEngineBoots=0 userEntry=localEngineID,defaultUser,,usmHMACMD5AuthProtocol, maplesyrup,usmDESPrivProtocol,maplesyrup,3,true
As you can see, the jdmk.security file currently only allows the defaultUser template to access the agent. The CreateUsmMibUser class will remotely add an extra row to this file to allow myNewUser to access the agent too.

To Run the `CreateUsmMibUser` Example

If you have not already done so, build and compile the examples in examplesDir/Snmp/UsmMib.

Type the following commands:
$ javac -classpath classpath -d . *.java

Make sure that no other agents are running in examplesDir/Snmp/UsmMib, and start Agent.
$ java -classpath classpath -Djdmk.security.file=./jdmk.security Agent
Note –
The jdmk.security file must be writable if CreateUsmMibUser is to be able to add new user entries.

In another window, start the CreateUsmMibUser example.

When starting CreateUsmMibUser, you must point it to the manager.security configuration file, and specify the user name, the security level, the agent's host name and the port on which the agent is running. In this example, the security level is authentication and privacy enabled, and the agent is running on the local host.
$ java -classpath classpath -Djdmk.security.file=./manager.security CreateUsmMibUser defaultUser authPriv localhost 8085
You will see the following output:
Initializing creator. Ready for new user inputs.

When prompted, provide the configuration information for your new user.

The information you provide must correspond to users that you have already configured into your manager's security file. In this example, we are remotely adding the user myNewUser that is defined in manager.security to the agent Agent. You therefore provide the following information, all of which is found in the manager.security file. You can enter any value for the auth key random and the priv key ramdom.

Type the engine Id :0x000000000000000000000002
Type the new user name :myNewUser
Type the clone from user name :defaultUser
Type the security level :authPriv
Type the old priv password :maplesyrup
Type the new priv password :newsyrup
Type the priv key random :00000000000000000000000000000000
Type the auth protocol :usmHMACMD5AuthProtocol
Type the old auth password :maplesyrup
Type the new auth password :newsyrup
Type the auth key random :00000000000000000000000000000000

You will see the following output:

********** Input summary ************ 

        * Engine Id : 0x000000000000000000000002
        * New user name : myNewUser
        * Clone from : defaultUser
        * Security level : authPriv
        * Old priv password : maplesyrup
        * New priv password : newsyrup
        * Priv key random : 00000000000000000000000000000000
        * Auth protocol : usmHMACMD5AuthProtocol
        * Old auth password : maplesyrup
        * New auth password : newsyrup
        * Auth key random : 00000000000000000000000000000000
Do you agree (yes, no) [yes]:

Press Enter to confirm your inputs.

You should see the following confirmation:

***** New user [myNewUser] created.
***** Doing Priv key change
***** Priv key change DONE.
***** Doing Auth key change
***** Auth key change DONE.
***** Setting row status to active.
***** Setting row status to active DONE.

***** SUCCESSFULLY CREATED NEW ROW IN AGENT FOR USER : [myNewUser]*****


***** Making a sanity check get request on the spin 
lock with the newly created 
user [myNewUser] PRESS RETURN.

Press Enter to perform the sanity check.

You should see the following confirmation:
SANITY CHECK SUCCESSFUL, SPIN LOCK VALUE IS: 5 Ready for new user inputs. Type the engine Id (return to accept) [0x000000000000000000000002]:
You are then invited to provide configuration information for any other users you want to allow to access Agent.

Check that the new user has been granted access to the agent by looking at the agent's jdmk.security file.

You should see a new userEntry for the new user in the jdmk.security file.

Example 20–11 `jdmk.security` for `Agent` File after Running `CreateUsmMibUser`

localEngineID=0x000000000000000000000002
localEngineBoots=7

userEntry=0x000000000000000000000002,myNewUser,myNewUser,
usmHMACMD5AuthProtocol,0x87021D7BD9D101BA05EA6E3BF9D9BD4A,
usmDESPrivProtocol,0x87021D7BD9D101BA05EA6E3BF9D9BD4A,3,

userEntry=localEngineID,defaultUser,,usmHMACMD5AuthProtocol,maplesyrup,
usmDESPrivProtocol,maplesyrup,3,true

When you have added all your new users, press Control C in both windows to stop both Agent and CreateUsmMibUser

SNMPv3 User-Based Security Model

SNMPv3 Engines

Generating SNMPv3 Engine IDs

To Run the SNMP EngineIdGenerator Example

SNMPv3 USM Configuration

Example 20–3 A Typical Agent jdmk.security File

Example 20–4 A Typical Manager jdmk.security File

Adding Users to the Security Files

Enabling Privacy in SNMPv3 Agents

Example 20–5 AgentEncryptV3 Agent with Privacy Enabled

Example 20–6 Agent jdmkencrypt.security File

To Run the AgentEncryptV3 Example

Enabling Privacy in SNMPv3 Managers

Example 20–7 SyncManagerEncryptV3 Manager with Privacy Enabled

Example 20–8 Manager jdmkencrypt.security File

To Run the SyncManagerEncryptV3 Example