1 /*
2 * Copyright (c) 2001, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package com.sun.jmx.snmp.internal;
26
27 import com.sun.jmx.snmp.SnmpTooBigException;
28 import com.sun.jmx.snmp.SnmpStatusException;
29 import com.sun.jmx.snmp.SnmpUnknownSecModelException;
30 import com.sun.jmx.snmp.SnmpSecurityException;
31 import com.sun.jmx.snmp.SnmpSecurityParameters;
32
33 /**
34 * Security sub system interface. To allow engine integration, a security sub system must implement this interface.
35 * <p><b>This API is a Sun Microsystems internal API and is subject
36 * to change without notice.</b></p>
37 */
38 public interface SnmpSecuritySubSystem extends SnmpSubSystem {
39 /**
40 * Instantiates an <CODE>SnmpSecurityCache</CODE> that is dependant to the model implementation. This call is routed to the dedicated model according to the model ID.
41 * @param id The model ID.
42 * @return The model dependant security cache.
43 */
44 public SnmpSecurityCache createSecurityCache(int id) throws SnmpUnknownSecModelException;
45 /**
46 * To release the previously created cache. This call is routed to the dedicated model according to the model ID.
47 * @param id The model ID.
48 * @param cache The security cache to release.
49 */
50 public void releaseSecurityCache(int id,
51 SnmpSecurityCache cache) throws SnmpUnknownSecModelException;
52
53 /**
54 * Called when a request is to be sent to the network. It must be securized. This call is routed to the dedicated model according to the model ID.
55 * <BR>The specified parameters are defined in RFC 2572 (see also the {@link com.sun.jmx.snmp.SnmpV3Message} class).
56 * @param cache The cache that has been created by calling <CODE>createSecurityCache</CODE> on this model.
57 * @param version The SNMP protocol version.
58 * @param msgID The current request id.
59 * @param msgMaxSize The message max size.
60 * @param msgFlags The message flags (reportable, Auth and Priv).
61 * @param msgSecurityModel This current security model.
62 * @param params The security parameters that contain the model dependant parameters.
63 * @param contextEngineID The context engine ID.
64 * @param contextName The context name.
65 * @param data The marshalled varbind list
66 * @param dataLength The marshalled varbind list length.
67 * @param outputBytes The buffer to fill with securized request. This is a representation independant marshalled format. This buffer will be sent to the network.
68 * @return The marshalled byte number.
69 */
70 public int generateRequestMsg(SnmpSecurityCache cache,
71 int version,
72 int msgID,
73 int msgMaxSize,
74 byte msgFlags,
75 int msgSecurityModel,
76 SnmpSecurityParameters params,
77 byte[] contextEngineID,
78 byte[] contextName,
79 byte[] data,
80 int dataLength,
81 byte[] outputBytes)
82 throws SnmpTooBigException, SnmpStatusException, SnmpSecurityException, SnmpUnknownSecModelException;
83
84 /**
85 * Called when a response is to be sent to the network. It must be securized. This call is routed to the dedicated model according to the model ID.
86 * <BR>The specified parameters are defined in RFC 2572 (see also the {@link com.sun.jmx.snmp.SnmpV3Message} class).
87 * @param cache The cache that has been created by calling <CODE>createSecurityCache</CODE> on this model.
88 * @param version The SNMP protocol version.
89 * @param msgID The current request id.
90 * @param msgMaxSize The message max size.
91 * @param msgFlags The message flags (reportable, Auth and Priv).
92 * @param msgSecurityModel This current security model.
93 * @param params The security parameters that contain the model dependant parameters.
94 * @param contextEngineID The context engine ID.
95 * @param contextName The context name.
96 * @param data The marshalled varbind list
97 * @param dataLength The marshalled varbind list length.
98 * @param outputBytes The buffer to fill with securized request. This is a representation independant marshalled format. This buffer will be sent to the network.
99 * @return The marshalled byte number.
100 */
101 public int generateResponseMsg(SnmpSecurityCache cache,
102 int version,
103 int msgID,
104 int msgMaxSize,
105 byte msgFlags,
106 int msgSecurityModel,
107 SnmpSecurityParameters params,
108 byte[] contextEngineID,
109 byte[] contextName,
110 byte[] data,
111 int dataLength,
112 byte[] outputBytes)
113 throws SnmpTooBigException, SnmpStatusException,
114 SnmpSecurityException, SnmpUnknownSecModelException;
115 /**
116 * Called when a request is received from the network. It handles authentication and privacy. This call is routed to the dedicated model according to the model ID.
117 * <BR>The specified parameters are defined in RFC 2572 (see also the {@link com.sun.jmx.snmp.SnmpV3Message} class).
118 * @param cache The cache that has been created by calling <CODE>createSecurityCache</CODE> on this model.
119 * @param version The SNMP protocol version.
120 * @param msgID The current request id.
121 * @param msgMaxSize The message max size.
122 * @param msgFlags The message flags (reportable, Auth and Priv)
123 * @param msgSecurityModel This current security model.
124 * @param params The security parameters in a marshalled format. The informations cointained in this array are model dependant.
125 * @param contextEngineID The context engine ID or null if encrypted.
126 * @param contextName The context name or null if encrypted.
127 * @param data The marshalled varbind list or null if encrypted.
128 * @param encryptedPdu The encrypted pdu or null if not encrypted.
129 * @param decryptedPdu The decrypted pdu. If no decryption is to be done, the passed context engine ID, context name and data could be used to fill this object.
130 * @return The decoded security parameters.
131
132 */
133 public SnmpSecurityParameters
134 processIncomingRequest(SnmpSecurityCache cache,
135 int version,
136 int msgID,
137 int msgMaxSize,
138 byte msgFlags,
139 int msgSecurityModel,
140 byte[] params,
141 byte[] contextEngineID,
142 byte[] contextName,
143 byte[] data,
144 byte[] encryptedPdu,
145 SnmpDecryptedPdu decryptedPdu)
146 throws SnmpStatusException, SnmpSecurityException, SnmpUnknownSecModelException;
147 /**
148 * Called when a response is received from the network. It handles authentication and privacy. This call is routed to the dedicated model according to the model ID.
149 * <BR>The specified parameters are defined in RFC 2572 (see also the {@link com.sun.jmx.snmp.SnmpV3Message} class).
150 * @param cache The cache that has been created by calling <CODE>createSecurityCache</CODE> on this model.
151 * @param version The SNMP protocol version.
152 * @param msgID The current request id.
153 * @param msgMaxSize The message max size.
154 * @param msgFlags The message flags (reportable, Auth and Priv).
155 * @param msgSecurityModel This current security model.
156 * @param params The security parameters in a marshalled format. The informations cointained in this array are model dependant.
157 * @param contextEngineID The context engine ID or null if encrypted.
158 * @param contextName The context name or null if encrypted.
159 * @param data The marshalled varbind list or null if encrypted.
160 * @param encryptedPdu The encrypted pdu or null if not encrypted.
161 * @param decryptedPdu The decrypted pdu. If no decryption is to be done, the passed context engine ID, context name and data could be used to fill this object.
162 * @return The security parameters.
163
164 */
165 public SnmpSecurityParameters processIncomingResponse(SnmpSecurityCache cache,
166 int version,
167 int msgID,
168 int msgMaxSize,
169 byte msgFlags,
170 int msgSecurityModel,
171 byte[] params,
172 byte[] contextEngineID,
173 byte[] contextName,
174 byte[] data,
175 byte[] encryptedPdu,
176 SnmpDecryptedPdu decryptedPdu)
177 throws SnmpStatusException, SnmpSecurityException, SnmpUnknownSecModelException;
178 }