1 // NAME
2 // $RCSfile: SnmpContextv3Face.java,v $
3 // DESCRIPTION
4 // [given below in javadoc format]
5 // DELTA
6 // $Revision: 3.20 $
7 // CREATED
8 // $Date: 2009/03/05 12:56:17 $
9 // COPYRIGHT
10 // Westhawk Ltd
11 // TO DO
12 //
13
14 /*
15 * Copyright (C) 2000 - 2006 by Westhawk Ltd
16 * <a href="www.westhawk.co.uk">www.westhawk.co.uk</a>
17 *
18 * Permission to use, copy, modify, and distribute this software
19 * for any purpose and without fee is hereby granted, provided
20 * that the above copyright notices appear in all copies and that
21 * both the copyright notice and this permission notice appear in
22 * supporting documentation.
23 * This software is provided "as is" without express or implied
24 * warranty.
25 * author <a href="mailto:snmp@westhawk.co.uk">Tim Panton</a>
26 */
27
28 package uk.co.westhawk.snmp.stack;
29
30 /*-
31 * ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲
32 * SNMP Java Client
33 * ჻჻჻჻჻჻
34 * Copyright 2023 MetricsHub, Westhawk
35 * ჻჻჻჻჻჻
36 * This program is free software: you can redistribute it and/or modify
37 * it under the terms of the GNU Lesser General Public License as
38 * published by the Free Software Foundation, either version 3 of the
39 * License, or (at your option) any later version.
40 *
41 * This program is distributed in the hope that it will be useful,
42 * but WITHOUT ANY WARRANTY; without even the implied warranty of
43 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
44 * GNU General Lesser Public License for more details.
45 *
46 * You should have received a copy of the GNU General Lesser Public
47 * License along with this program. If not, see
48 * <http://www.gnu.org/licenses/lgpl-3.0.html>.
49 * ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱
50 */
51 import uk.co.westhawk.snmp.pdu.*;
52
53 import java.util.Arrays;
54 import java.util.Collections;
55 import java.util.HashSet;
56 import java.util.Set;
57
58 /**
59 * This interface contains the SNMP context interface that is needed by every
60 * PDU to send a SNMP v3 request.
61 *
62 * See <a href="http://www.ietf.org/rfc/rfc3414.txt">SNMP-USER-BASED-SM-MIB</a>,
63 * <a href="http://www.ietf.org/rfc/rfc3411.txt">RFC 3411</a>,
64 * <a href="http://www.ietf.org/rfc/rfc3826.txt">RFC 3826 (AES)</a>
65 *
66 * @author <a href="mailto:snmp@westhawk.co.uk">Birgit Arkesteijn</a>
67 * @version $Revision: 3.20 $ $Date: 2009/03/05 12:56:17 $
68 */
69 public interface SnmpContextv3Face extends SnmpContextBasisFace {
70 static final String version_id = "@(#)$Id: SnmpContextv3Face.java,v 3.20 2009/03/05 12:56:17 birgita Exp $ Copyright Westhawk Ltd";
71
72 /**
73 * The SNMPv1 security model. This has value 1.
74 * The stack does not implement this security model.
75 */
76 public final static int SNMPv1_Security_Model = (byte) (0x1);
77
78 /**
79 * The SNMPv2c security model. This has value 2.
80 * The stack does not implement this security model.
81 */
82 public final static int SNMPv2c_Security_Model = (byte) (0x2);
83
84 /**
85 * The USM security model. This has value 3.
86 * This stack only implements this security model!
87 */
88 public final static int USM_Security_Model = (byte) (0x3);
89
90 /**
91 * The MD5 protocol type.
92 */
93 public final static int MD5_PROTOCOL = 0;
94
95 /**
96 * The SHA-1 protocol type.
97 */
98 public final static int SHA1_PROTOCOL = 1;
99
100 /**
101 * The DES encryption type.
102 */
103 public final static int DES_ENCRYPT = 2;
104
105 /**
106 * The AES 128 encryption type.
107 */
108 public final static int AES_ENCRYPT = 3;
109
110 /**
111 * The AES 192 encryption type.
112 */
113 public static final int AES192_ENCRYPT = 8;
114
115 /**
116 * The AES 256 encryption type.
117 */
118 public static final int AES256_ENCRYPT = 9;
119
120 /**
121 * The default value for the (security) user name. This is
122 * "initial".
123 */
124 public final static String DEFAULT_USERNAME = "initial";
125
126 /**
127 * The default Context Name. This is the zero length string, i.e. "".
128 */
129 public final static String DEFAULT_CONTEXT_NAME = "";
130
131 /**
132 * The array with the String represensations of the protocols.
133 */
134 public final static String PROTOCOL_NAMES[] = {
135 "MD5",
136 "SHA1",
137 "DES",
138 "AES",
139 "SHA256",
140 "SHA512",
141 "SHA224",
142 "SHA384",
143 "AES192",
144 "AES256",
145 };
146
147 /**
148 * The NoAuth protocol type.
149 */
150 public static final int NO_AUTH_PROTOCOL = PROTOCOL_NAMES.length;
151
152 /**
153 * The SHA-256 protocol type.
154 */
155 public static final int SHA256_PROTOCOL = 4;
156
157 /**
158 * The SHA-512 protocol type.
159 */
160 public static final int SHA512_PROTOCOL = 5;
161
162 /**
163 * The SHA-224 protocol type.
164 */
165 public static final int SHA224_PROTOCOL = 6;
166
167 /**
168 * The SHA-224 protocol type.
169 */
170 public static final int SHA384_PROTOCOL = 7;
171
172 /**
173 * Authentication protocols codes that are supported by SNMPv3.
174 */
175 public static final Set<Integer> AUTH_PROTOCOLS = Collections.unmodifiableSet(
176 new HashSet<>(Arrays.asList(MD5_PROTOCOL, SHA1_PROTOCOL,
177 SHA256_PROTOCOL, SHA512_PROTOCOL,
178 SHA224_PROTOCOL, SHA384_PROTOCOL)));
179 /**
180 * Privacy protocols codes that are supported by SNMPv3.
181 */
182 public static final Set<Integer> PRIVACY_PROTOCOLS = Collections.unmodifiableSet( new HashSet<>(
183 Arrays.asList(AES_ENCRYPT, AES192_ENCRYPT, AES256_ENCRYPT, DES_ENCRYPT)));
184
185 public static final Set<Integer> AES_PRIVACY_PROTOCOLS = Collections.unmodifiableSet( new HashSet<>(
186 Arrays.asList(AES_ENCRYPT, AES192_ENCRYPT, AES256_ENCRYPT)));
187
188
189 /**
190 * Returns the username.
191 *
192 * @return the username
193 */
194 public String getUserName();
195
196 /**
197 * Sets the username.
198 * This username will be used for all PDUs sent with this context.
199 * The username corresponds to the 'msgUserName' in
200 * <a href="http://www.ietf.org/rfc/rfc3414.txt">SNMP-USER-BASED-SM-MIB</a>.
201 * The default value is "initial".
202 *
203 * @param newUserName The new username
204 */
205 public void setUserName(String newUserName);
206
207 /**
208 * Returns if authentication is used or not.
209 * By default no authentication will be used.
210 *
211 * @return true if authentication is used, false if not
212 */
213 public boolean isUseAuthentication();
214
215 /**
216 * Sets whether authentication has to be used.
217 * By default no authentication will be used.
218 *
219 * @param newUseAuthentication The use of authentication
220 */
221 public void setUseAuthentication(boolean newUseAuthentication);
222
223 /**
224 * Returns the user authentication password.
225 * This password will be transformed into the user authentication secret key.
226 *
227 * @return The user authentication password
228 */
229 public String getUserAuthenticationPassword();
230
231 /**
232 * Sets the user authentication password.
233 * This password will be transformed into the user authentication secret
234 * key. A user MUST set this password.
235 *
236 * @param newUserAuthPassword The user authentication password
237 */
238 public void setUserAuthenticationPassword(String newUserAuthPassword)
239 throws IllegalArgumentException;
240
241 /**
242 * Sets the protocol to be used for authentication.
243 * This can either be MD5 or SHA-1.
244 * By default MD5 will be used.
245 *
246 * @param protocol The authentication protocol to be used
247 * @see #MD5_PROTOCOL
248 * @see #SHA1_PROTOCOL
249 */
250 public void setAuthenticationProtocol(int protocol)
251 throws IllegalArgumentException;
252
253 /**
254 * Returns the protocol to be used for authentication.
255 * This can either be MD5 or SHA-1.
256 * By default MD5 will be used.
257 *
258 * @return The authentication protocol to be used
259 * @see #MD5_PROTOCOL
260 * @see #SHA1_PROTOCOL
261 */
262 public int getAuthenticationProtocol();
263
264 /**
265 * Sets the protocol to be used for privacy.
266 * This can either be DES or AES.
267 * By default DES will be used.
268 *
269 * @param protocol The privacy protocol to be used
270 * @see #DES_ENCRYPT
271 * @see #AES_ENCRYPT
272 */
273 public void setPrivacyProtocol(int protocol)
274 throws IllegalArgumentException;
275
276 /**
277 * Returns the protocol to be used for privacy.
278 * This can either be DES or AES.
279 * By default DES will be used.
280 *
281 * @return The privacy protocol to be used
282 * @see #DES_ENCRYPT
283 * @see #AES_ENCRYPT
284 */
285 public int getPrivacyProtocol();
286
287 /**
288 * Returns if privacy is used or not.
289 * By default no privacy will be used.
290 *
291 * @return true if privacy is used, false if not
292 */
293 public boolean isUsePrivacy();
294
295 /**
296 * Sets whether privacy has to be used.
297 * By default no privacy will be used.
298 *
299 * @param newUsePrivacy The use of privacy
300 */
301 public void setUsePrivacy(boolean newUsePrivacy);
302
303 /**
304 * Returns the user privacy password.
305 * This password will be transformed into the user privacy secret key.
306 *
307 * @return The user privacy password
308 */
309 public String getUserPrivacyPassword();
310
311 /**
312 * Sets the user privacy password.
313 * This password will be transformed into the user privacy secret
314 * key. A user MUST set this password.
315 *
316 * @param newUserAuthPassword The user privacy password
317 */
318 public void setUserPrivacyPassword(String newUserAuthPassword)
319 throws IllegalArgumentException;
320
321 /**
322 * Sets the contextEngineID.
323 * See <a href="http://www.ietf.org/rfc/rfc3411.txt">RFC 3411</a>.
324 *
325 * A contextEngineID uniquely
326 * identifies an SNMP entity that may realize an instance of a context
327 * with a particular contextName.
328 *
329 * <p>
330 * Note, when the stack is an authoritative engine, this parameter should
331 * equal the UsmAgent.getSnmpEngineId(). See the StackUsage
332 * documentation for an explanation.
333 * </p>
334 *
335 * <p>
336 * If the contextEngineID is of length zero, the encoder will use the
337 * (discovered)
338 * snmpEngineId.
339 * </p>
340 *
341 * @see UsmAgent#getSnmpEngineId()
342 * @param newContextEngineId The contextEngineID
343 */
344 public void setContextEngineId(byte[] newContextEngineId)
345 throws IllegalArgumentException;
346
347 /**
348 * Returns the contextEngineID.
349 *
350 * @return The contextEngineID
351 */
352 public byte[] getContextEngineId();
353
354 /**
355 * Sets the contextName.
356 * See <a href="http://www.ietf.org/rfc/rfc3411.txt">RFC 3411</a>.
357 *
358 * A contextName is used to name a context. Each contextName MUST be
359 * unique within an SNMP entity.
360 * By default this is "".
361 *
362 * @param newContextName The contextName
363 * @see #DEFAULT_CONTEXT_NAME
364 */
365 public void setContextName(String newContextName);
366
367 /**
368 * Returns the contextName.
369 *
370 * @return The contextName
371 */
372 public String getContextName();
373
374 /**
375 * Adds a discovery PDU.
376 * This is for internal use only and should
377 * NOT be called by the developer.
378 *
379 * This is called by the the PDU itself and is added to the interface to
380 * cover the different kind of Contexts.
381 *
382 * @param pdu the discovery PDU
383 * @return PDU is succesful added
384 */
385 public boolean addDiscoveryPdu(DiscoveryPdu pdu)
386 throws java.io.IOException, PduException;
387
388 /**
389 * Encodes a discovery PDU.
390 * This is for internal use only and should
391 * NOT be called by the developer.
392 *
393 * This is called by the the PDU itself and is added to the interface to
394 * cover the different kind of Contexts.
395 *
396 * @return The encoded packet
397 */
398 public byte[] encodeDiscoveryPacket(byte msg_type, int rId, int errstat,
399 int errind, java.util.Enumeration ve, Object obj)
400 throws java.io.IOException, EncodingException;
401
402 /**
403 * Sets the UsmAgent, needed when this stack is used as authoritative
404 * SNMP engine. This interface provides authentiation details, like its
405 * clock and its Engine ID.
406 *
407 * @since 4_14
408 * @param agent The USM authoritative interface
409 */
410 public void setUsmAgent(UsmAgent agent);
411
412 /**
413 * Returns the UsmAgent.
414 *
415 * @since 4_14
416 * @see #setUsmAgent
417 */
418 public UsmAgent getUsmAgent();
419
420 }