KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > security > SecurityModel


1 /*_############################################################################
2   _##
3   _## SNMP4J - SecurityModel.java
4   _##
5   _## Copyright 2003-2007 Frank Fock and Jochen Katz (SNMP4J.org)
6   _##
7   _## Licensed under the Apache License, Version 2.0 (the "License");
8   _## you may not use this file except in compliance with the License.
9   _## You may obtain a copy of the License at
10   _##
11   _## http://www.apache.org/licenses/LICENSE-2.0
12   _##
13   _## Unless required by applicable law or agreed to in writing, software
14   _## distributed under the License is distributed on an "AS IS" BASIS,
15   _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   _## See the License for the specific language governing permissions and
17   _## limitations under the License.
18   _##
19   _##########################################################################*/
20
21
22
23
24
25 package org.snmp4j.security;
26
27 import java.io.*;
28 import org.snmp4j.mp.StatusInformation;
29 import org.snmp4j.smi.OctetString;
30 import org.snmp4j.smi.Integer32;
31 import org.snmp4j.asn1.BERInputStream;
32 // for JavaDoc
33 import org.snmp4j.mp.SnmpConstants;
34 import org.snmp4j.asn1.BEROutputStream;
35
36 /**
37  * The <code>SecurityModel</code> interface as described in RFC3411 §4.4.
38  *
39  * @author Frank Fock
40  * @version 1.0
41  */
42 public interface SecurityModel {
43
44   int SECURITY_MODEL_ANY = 0;
45   int SECURITY_MODEL_SNMPv1 = 1;
46   int SECURITY_MODEL_SNMPv2c = 2;
47   int SECURITY_MODEL_USM = 3;
48
49   /**
50    * Gets the ID of the security model.
51    * @return
52    * one of the integer constants defined in the {@link SecurityModel}
53    * interface.
54    * @see SecurityModel#SECURITY_MODEL_ANY
55    * @see SecurityModel#SECURITY_MODEL_SNMPv1
56    * @see SecurityModel#SECURITY_MODEL_SNMPv2c
57    * @see SecurityModel#SECURITY_MODEL_USM
58    */
59   int getID();
60
61   /**
62    * Creates a new {@link SecurityParameters} instance that corresponds to this
63    * security model.
64    * @return
65    * a new <code>SecurityParameters</code> instance.
66    */
67   SecurityParameters newSecurityParametersInstance();
68
69   /**
70    * Creates a new {@link SecurityStateReference} instance that corresponds to
71    * this security model.
72    * @return
73    * a new <code>SecurityStateReference</code> instance.
74    */
75   SecurityStateReference newSecurityStateReference();
76
77   /**
78    * Generate a request message.
79    * @param messageProcessingModel
80    * the ID of the message processing model (SNMP version) to use.
81    * @param globalData
82    * the message header and admin data.
83    * @param maxMessageSize
84    * the maximum message size of the sending (this) SNMP entity for the
85    * selected transport mapping (determined by the message processing model).
86    * @param securityModel
87    * the security model for the outgoing message.
88    * @param securityEngineID
89    * the authoritative SNMP entity.
90    * @param securityName
91    * the principal on behalf of this message is generated.
92    * @param securityLevel
93    * the requested {@link SecurityLevel}.
94    * @param scopedPDU
95    * a BERInputStream containing the message (plain text) payload.
96    * @param securityParameters
97    * returns the {@link SecurityParameters} filled by the security model.
98    * @param wholeMsg
99    * returns the complete generated message in a <code>BEROutputStream</code>.
100    * The buffer of <code>wholeMsg</code> is set to <code>null</code> by the
101    * caller and must be set by the implementation of this method.
102    * @throws IOException
103    * if generation of the message fails because of an internal or an resource
104    * error.
105    * @return
106    * the error status of the message generation. On success
107    * {@link SnmpConstants#SNMPv3_USM_OK} is returned, otherwise one of the
108    * other <code>SnmpConstants.SNMPv3_USM_*</code> values is returned.
109    */
110   int generateRequestMessage(int messageProcessingModel,
111                              byte[] globalData,
112                              int maxMessageSize,
113                              int securityModel,
114                              byte[] securityEngineID,
115                              byte[] securityName,
116                              int securityLevel,
117                              BERInputStream scopedPDU,
118                              // out parameters
119 SecurityParameters securityParameters,
120                              BEROutputStream wholeMsg) throws IOException;
121
122   /**
123    * Generates a response message.
124    * @param messageProcessingModel
125    * the ID of the message processing model (SNMP version) to use.
126    * @param globalData
127    * the message header and admin data.
128    * @param maxMessageSize
129    * the maximum message size of the sending (this) SNMP entity for the
130    * selected transport mapping (determined by the message processing model).
131    * @param securityModel
132    * the security model for the outgoing message.
133    * @param securityEngineID
134    * the authoritative SNMP entity.
135    * @param securityName
136    * the principal on behalf of this message is generated.
137    * @param securityLevel
138    * the requested {@link SecurityLevel}.
139    * @param scopedPDU
140    * a BERInputStream containing the message (plain text) payload.
141    * @param securityStateReference
142    * a {@link SecurityStateReference} instance providing information from
143    * original request.
144    * @param securityParameters
145    * returns the {@link SecurityParameters} filled by the security model.
146    * @param wholeMsg
147    * returns the complete generated message in a <code>BEROutputStream</code>.
148    * The buffer of <code>wholeMsg</code> is set to <code>null</code> by the
149    * caller and must be set by the implementation of this method.
150    * @throws IOException
151    * if generation of the message fails because of an internal or an resource
152    * error.
153    * @return
154    * the error status of the message generation. On success
155    * {@link SnmpConstants#SNMPv3_USM_OK} is returned, otherwise one of the
156    * other <code>SnmpConstants.SNMPv3_USM_*</code> values is returned.
157    */
158   int generateResponseMessage(int messageProcessingModel,
159                               byte[] globalData,
160                               int maxMessageSize,
161                               int securityModel,
162                               byte[] securityEngineID,
163                               byte[] securityName,
164                               int securityLevel,
165                               BERInputStream scopedPDU,
166                               SecurityStateReference securityStateReference,
167                               // out parameters
168 SecurityParameters securityParameters,
169                               BEROutputStream wholeMsg) throws IOException;
170
171   /**
172    * Processes an incoming message and returns its plaintext payload.
173    * @param messageProcessingModel
174    * the ID of the message processing model (SNMP version) to use.
175    * @param maxMessageSize
176    * the maximum message size of the message processing model for the
177    * transport mapping associated with this message's source address less
178    * the length of the maximum header length of the message processing model.
179    * This value is used by the security model to determine the
180    * <code>maxSizeResponseScopedPDU</code> value.
181    * @param securityParameters
182    * the {@link SecurityParameters} for the received message.
183    * @param securityModel
184    * the {@link SecurityModel} instance for the receied message.
185    * @param securityLevel
186    * the {@link SecurityLevel} ID.
187    * @param wholeMsg
188    * the <code>BERInputStream</code> containing the whole message as recieved
189    * on the wire.
190    * @param securityEngineID
191    * the authoritative SNMP entity.
192    * @param securityName
193    * the identification of the principal.
194    * @param scopedPDU
195    * returns the message (plaintext) payload into the supplied
196    * <code>BEROutputStream</code>.
197    * The buffer of <code>scopedPDU</code> is set to <code>null</code> by the
198    * caller and must be set by the implementation of this method.
199    * @param maxSizeResponseScopedPDU
200    * the determined maxmimum size for a response PDU.
201    * @param securityStateReference
202    * the <code>SecurityStateReference</code> information needed for
203    * a response.
204    * @param statusInfo
205    * the <code>StatusInformation</code> needed to generate reports if
206    * processing of the incoming message failed.
207    * @throws IOException
208    * if an unexpected (internal) or an resource error occured.
209    * @return
210    * the error status of the message processing. On success
211    * {@link SnmpConstants#SNMPv3_USM_OK} is returned, otherwise one of the
212    * other <code>SnmpConstants.SNMPv3_USM_*</code> values is returned.
213    */
214   int processIncomingMsg(int messageProcessingModel,
215                          int maxMessageSize,
216                          SecurityParameters securityParameters,
217                          SecurityModel securityModel,
218                          int securityLevel,
219                          BERInputStream wholeMsg,
220                          OctetString securityEngineID,
221                          OctetString securityName,
222                          // out parameters
223 BEROutputStream scopedPDU,
224                          Integer32 maxSizeResponseScopedPDU,
225                          SecurityStateReference securityStateReference,
226                          StatusInformation statusInfo) throws IOException;
227
228 }
229
230
Popular Tags