KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*_############################################################################
2   _##
3   _## SNMP4J - AuthenticationProtocol.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 org.snmp4j.smi.OID;
28 import org.snmp4j.smi.OctetString;
29
30 /**
31  * The <code>AuthenticationProtocol</code> interface defines a common
32  * interface for all SNMP authentication protocols.
33  *
34  * @author Frank Fock
35  * @version 1.0
36  */
37 public interface AuthenticationProtocol extends SecurityProtocol {
38
39   int MESSAGE_AUTHENTICATION_CODE_LENGTH = 12;
40
41   /**
42    * Authenticates an outgoing message.
43    *
44    * This method fills the authentication parameters field of the
45    * given message. The parameter <code>digestOffset</code> offset is pointing
46    * inside the message buffer and must be zeroed before the authentication
47    * value is computed.
48    *
49    * @param authenticationKey
50    * the authentication key to be used for authenticating the message.
51    * @param message
52    * the entire message for which the digest should be determined.
53    * @param messageOffset
54    * the offset in <code>message</code> where the message actually starts.
55    * @param messageLength
56    * the actual message length (may be smaller than
57    * <code>message.length</code>).
58    * @param digest
59    * the offset in <code>message</code> where to store the digest.
60    * @return
61    * <code>true</code> if the message digest has been successfully computed
62    * and set, <code>false</code> otherwise.
63    */
64   boolean authenticate(byte[] authenticationKey,
65                        byte[] message,
66                        int messageOffset,
67                        int messageLength,
68                        ByteArrayWindow digest);
69
70   /**
71    * Authenticates an incoming message.
72    *
73    * This method checks if the value in the authentication parameters
74    * field of the message is valid.
75    *
76    * The following procedure is used to verify the authenitcation value
77    * <UL>
78    * <LI> copy the authentication value to a temp buffer
79    * <LI> zero the auth field
80    * <LI> recalculate the authenthication value
81    * <LI> compare the two authentcation values
82    * <LI> write back the received authentication value
83    * </UL>
84    *
85    * @param authenticationKey
86    * the authentication key to be used for authenticating the message.
87    * @param message
88    * the entire message for which the digest should be determined.
89    * @param messageOffset
90    * the offset in <code>message</code> where the message actually starts.
91    * @param messageLength
92    * the actual message length (may be smaller than
93    * <code>message.length</code>).
94    * @param digest
95    * the digest of the <code>message</code>.
96    * @return
97    * <code>true</code> if the message is authentic, <code>false</code>
98    * otherwise.
99    */
100   boolean isAuthentic(byte[] authenticationKey,
101                       byte[] message,
102                       int messageOffset,
103                       int messageLength,
104                       ByteArrayWindow digest);
105
106
107   /**
108    * Computes the delta digest needed to remotely change an user's
109    * authenitcation key. The length of the old key (e.g. 16 for MD5,
110    * 20 for SHA) must match the length of the new key.
111    *
112    * @param oldKey
113    * the old authentication/privacy key.
114    * @param newKey
115    * the new authentication/privacy key.
116    * @param random
117    * the random 'seed' to be used to produce the digest.
118    * @return
119    * the byte array representing the delta for key change operations.
120    * To obtain the key change value, append this delta to the
121    * <code>random</code> array.
122    */
123   byte[] changeDelta(byte[] oldKey,
124                      byte[] newKey,
125                      byte[] random);
126
127   /**
128    * Gets the OID uniquely identifying the authentication protocol.
129    * @return
130    * an <code>OID</code> instance.
131    */
132   OID getID();
133
134   /**
135    * Generates the localized key for the given password and engine id.
136    *
137    * @param passwordString
138    * the authentication pass phrase.
139    * @param engineID
140    * the engine ID of the authoritative engine.
141    * @return
142    * the localized authentication key.
143    */
144   byte[] passwordToKey(OctetString passwordString, byte[] engineID);
145
146   /**
147    * Generates a hash value for the given data.
148    *
149    * @param data
150    * the data
151    * @return
152    * the generated hash.
153    */
154   byte[] hash(byte[] data);
155
156   /**
157    * Generates a hash value for the given data.
158    *
159    * @param data
160    * the data
161    * @param offset
162    * offset into data
163    * @param length
164    * length of data to hash
165    * @return
166    * the generated hash.
167    */
168   byte[] hash(byte[] data, int offset, int length);
169
170   /**
171    * Gets the length of the digest generated by this authentication protocol.
172    * This value can be used to compute the BER encoded length of the security
173    * parameters for authentication.
174    *
175    * @return
176    * the number of bytes of digests generated by this authentication
177    * procotol.
178    */
179   int getDigestLength();
180 }
181
182
Popular Tags