author | weijun |
Wed, 30 May 2018 22:24:20 +0800 | |
changeset 50307 | ba1b490901d4 |
parent 47216 | 71c04702a3d5 |
child 55599 | e6c430d4d217 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
2 |
* Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved. |
2 | 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 |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 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 |
* |
|
5506 | 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. |
|
2 | 24 |
*/ |
25 |
||
26 |
package org.ietf.jgss; |
|
27 |
||
28 |
import java.io.InputStream; |
|
29 |
import java.io.OutputStream; |
|
30 |
||
31 |
/** |
|
32 |
* This interface encapsulates the GSS-API security context and provides |
|
33 |
* the security services that are available over the context. Security |
|
34 |
* contexts are established between peers using locally acquired |
|
35 |
* credentials. Multiple contexts may exist simultaneously between a pair |
|
36 |
* of peers, using the same or different set of credentials. GSS-API |
|
37 |
* functions in a manner independent of the underlying transport protocol |
|
38 |
* and depends on its calling application to transport the tokens that are |
|
39 |
* generated by the security context between the peers.<p> |
|
40 |
* |
|
41 |
* If the caller instantiates the context using the default |
|
42 |
* <code>GSSManager</code> instance, then the Kerberos v5 GSS-API mechanism |
|
43 |
* is guaranteed to be available for context establishment. This mechanism |
|
44 |
* is identified by the Oid "1.2.840.113554.1.2.2" and is defined in RFC |
|
45 |
* 1964.<p> |
|
46 |
* |
|
47 |
* Before the context establishment phase is initiated, the context |
|
48 |
* initiator may request specific characteristics desired of the |
|
49 |
* established context. Not all underlying mechanisms support all |
|
50 |
* characteristics that a caller might desire. After the context is |
|
51 |
* established, the caller can check the actual characteristics and services |
|
52 |
* offered by that context by means of various query methods. When using |
|
53 |
* the Kerberos v5 GSS-API mechanism offered by the default |
|
54 |
* <code>GSSManager</code> instance, all optional services will be |
|
55 |
* available locally. They are mutual authentication, credential |
|
56 |
* delegation, confidentiality and integrity protection, and per-message |
|
57 |
* replay detection and sequencing. Note that in the GSS-API, message integrity |
|
58 |
* is a prerequisite for message confidentiality.<p> |
|
59 |
* |
|
60 |
* The context establishment occurs in a loop where the |
|
61 |
* initiator calls {@link #initSecContext(byte[], int, int) initSecContext} |
|
62 |
* and the acceptor calls {@link #acceptSecContext(byte[], int, int) |
|
63 |
* acceptSecContext} until the context is established. While in this loop |
|
64 |
* the <code>initSecContext</code> and <code>acceptSecContext</code> |
|
65 |
* methods produce tokens that the application sends over to the peer. The |
|
66 |
* peer passes any such token as input to its <code>acceptSecContext</code> |
|
67 |
* or <code>initSecContext</code> as the case may be.<p> |
|
68 |
* |
|
69 |
* During the context establishment phase, the {@link |
|
70 |
* #isProtReady() isProtReady} method may be called to determine if the |
|
71 |
* context can be used for the per-message operations of {@link |
|
72 |
* #wrap(byte[], int, int, MessageProp) wrap} and {@link #getMIC(byte[], |
|
73 |
* int, int, MessageProp) getMIC}. This allows applications to use |
|
74 |
* per-message operations on contexts which aren't yet fully |
|
75 |
* established.<p> |
|
76 |
* |
|
77 |
* After the context has been established or the <code>isProtReady</code> |
|
78 |
* method returns <code>true</code>, the query routines can be invoked to |
|
79 |
* determine the actual characteristics and services of the established |
|
80 |
* context. The application can also start using the per-message methods |
|
81 |
* of {@link #wrap(byte[], int, int, MessageProp) wrap} and |
|
82 |
* {@link #getMIC(byte[], int, int, MessageProp) getMIC} to obtain |
|
83 |
* cryptographic operations on application supplied data.<p> |
|
84 |
* |
|
85 |
* When the context is no longer needed, the application should call |
|
86 |
* {@link #dispose() dispose} to release any system resources the context |
|
87 |
* may be using.<p> |
|
88 |
* |
|
89 |
* A security context typically maintains sequencing and replay detection |
|
90 |
* information about the tokens it processes. Therefore, the sequence in |
|
91 |
* which any tokens are presented to this context for processing can be |
|
92 |
* important. Also note that none of the methods in this interface are |
|
93 |
* synchronized. Therefore, it is not advisable to share a |
|
94 |
* <code>GSSContext</code> among several threads unless some application |
|
95 |
* level synchronization is in place.<p> |
|
96 |
* |
|
97 |
* Finally, different mechanism providers might place different security |
|
98 |
* restrictions on using GSS-API contexts. These will be documented by the |
|
99 |
* mechanism provider. The application will need to ensure that it has the |
|
100 |
* appropriate permissions if such checks are made in the mechanism layer.<p> |
|
101 |
* |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
102 |
* The stream-based methods of {@code GSSContext} have been deprecated in |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
103 |
* Java SE 11. These methods have also been removed from |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
104 |
* <a href="http://tools.ietf.org/html/rfc8353"> |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
105 |
* RFC 8353: Generic Security Service API Version 2: Java Bindings Update</a> |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
106 |
* for the following reasons (see section 11): "The overloaded methods of |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
107 |
* GSSContext that use input and output streams as the means to convey |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
108 |
* authentication and per-message GSS-API tokens as described in Section 5.15 |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
109 |
* of RFC 5653 are removed in this update as the wire protocol |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
110 |
* should be defined by an application and not a library. It's also impossible |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
111 |
* to implement these methods correctly when the token has no self-framing |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
112 |
* (where the end cannot be determined), or the library has no knowledge of |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
113 |
* the token format (for example, as a bridge talking to another GSS library)". |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
114 |
* These methods include {@link #initSecContext(InputStream, OutputStream)}, |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
115 |
* {@link #acceptSecContext(InputStream, OutputStream)}, |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
116 |
* {@link #wrap(InputStream, OutputStream, MessageProp)}, |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
117 |
* {@link #unwrap(InputStream, OutputStream, MessageProp)}, |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
118 |
* {@link #getMIC(InputStream, OutputStream, MessageProp)}, |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
119 |
* and {@link #verifyMIC(InputStream, InputStream, MessageProp)}.<p> |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
120 |
* |
2 | 121 |
* The example code presented below demonstrates the usage of the |
122 |
* <code>GSSContext</code> interface for the initiating peer. Different |
|
123 |
* operations on the <code>GSSContext</code> object are presented, |
|
124 |
* including: object instantiation, setting of desired flags, context |
|
125 |
* establishment, query of actual context flags, per-message operations on |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
126 |
* application data, and finally context deletion. |
2 | 127 |
* |
128 |
* <pre> |
|
129 |
* // Create a context using default credentials |
|
130 |
* // and the implementation specific default mechanism |
|
131 |
* GSSManager manager ... |
|
132 |
* GSSName targetName ... |
|
133 |
* GSSContext context = manager.createContext(targetName, null, null, |
|
134 |
* GSSContext.INDEFINITE_LIFETIME); |
|
135 |
* |
|
136 |
* // set desired context options prior to context establishment |
|
137 |
* context.requestConf(true); |
|
138 |
* context.requestMutualAuth(true); |
|
139 |
* context.requestReplayDet(true); |
|
140 |
* context.requestSequenceDet(true); |
|
141 |
* |
|
142 |
* // establish a context between peers |
|
143 |
* |
|
144 |
* byte []inToken = new byte[0]; |
|
145 |
* |
|
146 |
* // Loop while there still is a token to be processed |
|
147 |
* |
|
148 |
* while (!context.isEstablished()) { |
|
149 |
* |
|
150 |
* byte[] outToken |
|
151 |
* = context.initSecContext(inToken, 0, inToken.length); |
|
152 |
* |
|
153 |
* // send the output token if generated |
|
154 |
* if (outToken != null) |
|
155 |
* sendToken(outToken); |
|
156 |
* |
|
157 |
* if (!context.isEstablished()) { |
|
158 |
* inToken = readToken(); |
|
159 |
* } |
|
160 |
* |
|
161 |
* // display context information |
|
162 |
* System.out.println("Remaining lifetime in seconds = " |
|
163 |
* + context.getLifetime()); |
|
164 |
* System.out.println("Context mechanism = " + context.getMech()); |
|
165 |
* System.out.println("Initiator = " + context.getSrcName()); |
|
166 |
* System.out.println("Acceptor = " + context.getTargName()); |
|
167 |
* |
|
168 |
* if (context.getConfState()) |
|
169 |
* System.out.println("Confidentiality (i.e., privacy) is available"); |
|
170 |
* |
|
171 |
* if (context.getIntegState()) |
|
172 |
* System.out.println("Integrity is available"); |
|
173 |
* |
|
174 |
* // perform wrap on an application supplied message, appMsg, |
|
175 |
* // using QOP = 0, and requesting privacy service |
|
176 |
* byte [] appMsg ... |
|
177 |
* |
|
178 |
* MessageProp mProp = new MessageProp(0, true); |
|
179 |
* |
|
180 |
* byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp); |
|
181 |
* |
|
182 |
* sendToken(tok); |
|
183 |
* |
|
184 |
* // release the local-end of the context |
|
185 |
* context.dispose(); |
|
186 |
* |
|
187 |
* </pre> |
|
188 |
* |
|
189 |
* @author Mayank Upadhyay |
|
190 |
* @since 1.4 |
|
191 |
*/ |
|
192 |
public interface GSSContext { |
|
193 |
||
194 |
/** |
|
195 |
* A lifetime constant representing the default context lifetime. This |
|
196 |
* value is set to 0. |
|
197 |
*/ |
|
198 |
public static final int DEFAULT_LIFETIME = 0; |
|
199 |
||
200 |
/** |
|
201 |
* A lifetime constant representing indefinite context lifetime. |
|
202 |
* This value must is set to the maximum integer value in Java - |
|
203 |
* {@link java.lang.Integer#MAX_VALUE Integer.MAX_VALUE}. |
|
204 |
*/ |
|
205 |
public static final int INDEFINITE_LIFETIME = Integer.MAX_VALUE; |
|
206 |
||
207 |
/** |
|
208 |
* Called by the context initiator to start the context creation |
|
209 |
* phase and process any tokens generated |
|
210 |
* by the peer's <code>acceptSecContext</code> method. |
|
211 |
* This method may return an output token which the application will need |
|
212 |
* to send to the peer for processing by its <code>acceptSecContext</code> |
|
213 |
* method. The application can call {@link #isEstablished() |
|
214 |
* isEstablished} to determine if the context establishment phase is |
|
215 |
* complete on this side of the context. A return value of |
|
216 |
* <code>false</code> from <code>isEstablished</code> indicates that |
|
217 |
* more tokens are expected to be supplied to |
|
218 |
* <code>initSecContext</code>. Upon completion of the context |
|
219 |
* establishment, the available context options may be queried through |
|
220 |
* the get methods.<p> |
|
221 |
* |
|
222 |
* Note that it is possible that the <code>initSecContext</code> method |
|
223 |
* return a token for the peer, and <code>isEstablished</code> return |
|
224 |
* <code>true</code> also. This indicates that the token needs to be sent |
|
225 |
* to the peer, but the local end of the context is now fully |
|
226 |
* established.<p> |
|
227 |
* |
|
228 |
* Some mechanism providers might require that the caller be granted |
|
229 |
* permission to initiate a security context. A failed permission check |
|
230 |
* might cause a {@link java.lang.SecurityException SecurityException} |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
231 |
* to be thrown from this method. |
2 | 232 |
* |
233 |
* @return a byte[] containing the token to be sent to the |
|
234 |
* peer. <code>null</code> indicates that no token is generated. |
|
235 |
* @param inputBuf token generated by the peer. This parameter is ignored |
|
236 |
* on the first call since no token has been received from the peer. |
|
237 |
* @param offset the offset within the inputBuf where the token begins. |
|
238 |
* @param len the length of the token. |
|
239 |
* |
|
240 |
* @throws GSSException containing the following |
|
241 |
* major error codes: |
|
242 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}, |
|
243 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC}, |
|
244 |
* {@link GSSException#NO_CRED GSSException.NO_CRED}, |
|
245 |
* {@link GSSException#CREDENTIALS_EXPIRED |
|
246 |
* GSSException.CREDENTIALS_EXPIRED}, |
|
247 |
* {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS}, |
|
248 |
* {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN}, |
|
249 |
* {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN}, |
|
250 |
* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}, |
|
251 |
* {@link GSSException#BAD_MECH GSSException.BAD_MECH}, |
|
252 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
253 |
*/ |
|
254 |
public byte[] initSecContext(byte inputBuf[], int offset, int len) |
|
255 |
throws GSSException; |
|
256 |
||
257 |
/** |
|
258 |
* Called by the context initiator to start the context creation |
|
259 |
* phase and process any tokens generated |
|
260 |
* by the peer's <code>acceptSecContext</code> method using |
|
261 |
* streams. This method may write an output token to the |
|
262 |
* <code>OutpuStream</code>, which the application will |
|
263 |
* need to send to the peer for processing by its |
|
264 |
* <code>acceptSecContext</code> call. Typically, the application would |
|
265 |
* ensure this by calling the {@link java.io.OutputStream#flush() flush} |
|
266 |
* method on an <code>OutputStream</code> that encapsulates the |
|
267 |
* connection between the two peers. The application can |
|
268 |
* determine if a token is written to the OutputStream from the return |
|
269 |
* value of this method. A return value of <code>0</code> indicates that |
|
270 |
* no token was written. The application can call |
|
271 |
* {@link #isEstablished() isEstablished} to determine if the context |
|
272 |
* establishment phase is complete on this side of the context. A |
|
273 |
* return value of <code>false</code> from <code>isEstablished</code> |
|
274 |
* indicates that more tokens are expected to be supplied to |
|
275 |
* <code>initSecContext</code>. |
|
276 |
* Upon completion of the context establishment, the available context |
|
277 |
* options may be queried through the get methods.<p> |
|
278 |
* |
|
279 |
* Note that it is possible that the <code>initSecContext</code> method |
|
280 |
* return a token for the peer, and <code>isEstablished</code> return |
|
281 |
* <code>true</code> also. This indicates that the token needs to be sent |
|
282 |
* to the peer, but the local end of the context is now fully |
|
283 |
* established.<p> |
|
284 |
* |
|
285 |
* The GSS-API authentication tokens contain a definitive start and |
|
286 |
* end. This method will attempt to read one of these tokens per |
|
287 |
* invocation, and may block on the stream if only part of the token is |
|
288 |
* available. In all other respects this method is equivalent to the |
|
289 |
* byte array based {@link #initSecContext(byte[], int, int) |
|
290 |
* initSecContext}.<p> |
|
291 |
* |
|
292 |
* Some mechanism providers might require that the caller be granted |
|
293 |
* permission to initiate a security context. A failed permission check |
|
294 |
* might cause a {@link java.lang.SecurityException SecurityException} |
|
295 |
* to be thrown from this method.<p> |
|
296 |
* |
|
297 |
* The following example code demonstrates how this method might be |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
298 |
* used: |
2 | 299 |
* <pre> |
300 |
* InputStream is ... |
|
301 |
* OutputStream os ... |
|
302 |
* GSSContext context ... |
|
303 |
* |
|
304 |
* // Loop while there is still a token to be processed |
|
305 |
* |
|
306 |
* while (!context.isEstablished()) { |
|
307 |
* |
|
308 |
* context.initSecContext(is, os); |
|
309 |
* |
|
310 |
* // send output token if generated |
|
311 |
* os.flush(); |
|
312 |
* } |
|
313 |
* </pre> |
|
314 |
* |
|
315 |
* |
|
316 |
* @return the number of bytes written to the OutputStream as part of the |
|
317 |
* token to be sent to the peer. A value of 0 indicates that no token |
|
318 |
* needs to be sent. |
|
319 |
* @param inStream an InputStream that contains the token generated by |
|
320 |
* the peer. This parameter is ignored on the first call since no token |
|
321 |
* has been or will be received from the peer at that point. |
|
322 |
* @param outStream an OutputStream where the output token will be |
|
323 |
* written. During the final stage of context establishment, there may be |
|
324 |
* no bytes written. |
|
325 |
* |
|
326 |
* @throws GSSException containing the following |
|
327 |
* major error codes: |
|
328 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}, |
|
329 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC}, |
|
330 |
* {@link GSSException#NO_CRED GSSException.NO_CRED}, |
|
331 |
* {@link GSSException#CREDENTIALS_EXPIRED GSSException.CREDENTIALS_EXPIRED}, |
|
332 |
* {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS}, |
|
333 |
* {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN}, |
|
334 |
* {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN}, |
|
335 |
* {@link GSSException#BAD_NAMETYPE GSSException.BAD_NAMETYPE}, |
|
336 |
* {@link GSSException#BAD_MECH GSSException.BAD_MECH}, |
|
337 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
338 |
* @deprecated The stream-based methods have been removed from RFC 8353. |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
339 |
* Use {@link #initSecContext(byte[], int, int)} instead. |
2 | 340 |
*/ |
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
341 |
@Deprecated(since="11") |
2 | 342 |
public int initSecContext(InputStream inStream, |
343 |
OutputStream outStream) throws GSSException; |
|
344 |
||
345 |
/** |
|
346 |
* Called by the context acceptor upon receiving a token from the |
|
347 |
* peer. This method may return an output token which the application |
|
348 |
* will need to send to the peer for further processing by its |
|
349 |
* <code>initSecContext</code> call.<p> |
|
350 |
* |
|
351 |
* The application can call {@link #isEstablished() isEstablished} to |
|
352 |
* determine if the context establishment phase is complete for this |
|
353 |
* peer. A return value of <code>false</code> from |
|
354 |
* <code>isEstablished</code> indicates that more tokens are expected to |
|
355 |
* be supplied to this method. Upon completion of the context |
|
356 |
* establishment, the available context options may be queried through |
|
357 |
* the get methods.<p> |
|
358 |
* |
|
359 |
* Note that it is possible that <code>acceptSecContext</code> return a |
|
360 |
* token for the peer, and <code>isEstablished</code> return |
|
361 |
* <code>true</code> also. This indicates that the token needs to be |
|
362 |
* sent to the peer, but the local end of the context is now fully |
|
363 |
* established.<p> |
|
364 |
* |
|
365 |
* Some mechanism providers might require that the caller be granted |
|
366 |
* permission to accept a security context. A failed permission check |
|
367 |
* might cause a {@link java.lang.SecurityException SecurityException} |
|
368 |
* to be thrown from this method.<p> |
|
369 |
* |
|
370 |
* The following example code demonstrates how this method might be |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
371 |
* used: |
2 | 372 |
* <pre> |
373 |
* byte[] inToken; |
|
374 |
* byte[] outToken; |
|
375 |
* GSSContext context ... |
|
376 |
* |
|
377 |
* // Loop while there is still a token to be processed |
|
378 |
* |
|
379 |
* while (!context.isEstablished()) { |
|
380 |
* inToken = readToken(); |
|
381 |
* outToken = context.acceptSecContext(inToken, 0, |
|
382 |
* inToken.length); |
|
383 |
* // send output token if generated |
|
384 |
* if (outToken != null) |
|
385 |
* sendToken(outToken); |
|
386 |
* } |
|
387 |
* </pre> |
|
388 |
* |
|
389 |
* |
|
390 |
* @return a byte[] containing the token to be sent to the |
|
391 |
* peer. <code>null</code> indicates that no token is generated. |
|
392 |
* @param inToken token generated by the peer. |
|
393 |
* @param offset the offset within the inToken where the token begins. |
|
394 |
* @param len the length of the token. |
|
395 |
* |
|
396 |
* @throws GSSException containing the following |
|
397 |
* major error codes: |
|
398 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}, |
|
399 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC}, |
|
400 |
* {@link GSSException#NO_CRED GSSException.NO_CRED}, |
|
401 |
* {@link GSSException#CREDENTIALS_EXPIRED |
|
402 |
* GSSException.CREDENTIALS_EXPIRED}, |
|
403 |
* {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS}, |
|
404 |
* {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN}, |
|
405 |
* {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN}, |
|
406 |
* {@link GSSException#BAD_MECH GSSException.BAD_MECH}, |
|
407 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
408 |
*/ |
|
409 |
public byte[] acceptSecContext(byte inToken[], int offset, int len) |
|
410 |
throws GSSException; |
|
411 |
||
412 |
/** |
|
413 |
* Called by the context acceptor to process a token from the peer using |
|
414 |
* streams. It may write an output token to the |
|
415 |
* <code>OutputStream</code>, which the application |
|
416 |
* will need to send to the peer for processing by its |
|
417 |
* <code>initSecContext</code> method. Typically, the application would |
|
418 |
* ensure this by calling the {@link java.io.OutputStream#flush() flush} |
|
419 |
* method on an <code>OutputStream</code> that encapsulates the |
|
420 |
* connection between the two peers. The application can call |
|
421 |
* {@link #isEstablished() isEstablished} to determine if the context |
|
422 |
* establishment phase is complete on this side of the context. A |
|
423 |
* return value of <code>false</code> from <code>isEstablished</code> |
|
424 |
* indicates that more tokens are expected to be supplied to |
|
425 |
* <code>acceptSecContext</code>. |
|
426 |
* Upon completion of the context establishment, the available context |
|
427 |
* options may be queried through the get methods.<p> |
|
428 |
* |
|
429 |
* Note that it is possible that <code>acceptSecContext</code> return a |
|
430 |
* token for the peer, and <code>isEstablished</code> return |
|
431 |
* <code>true</code> also. This indicates that the token needs to be |
|
432 |
* sent to the peer, but the local end of the context is now fully |
|
433 |
* established.<p> |
|
434 |
* |
|
435 |
* The GSS-API authentication tokens contain a definitive start and |
|
436 |
* end. This method will attempt to read one of these tokens per |
|
437 |
* invocation, and may block on the stream if only part of the token is |
|
438 |
* available. In all other respects this method is equivalent to the byte |
|
439 |
* array based {@link #acceptSecContext(byte[], int, int) |
|
440 |
* acceptSecContext}.<p> |
|
441 |
* |
|
442 |
* Some mechanism providers might require that the caller be granted |
|
443 |
* permission to accept a security context. A failed permission check |
|
444 |
* might cause a {@link java.lang.SecurityException SecurityException} |
|
445 |
* to be thrown from this method.<p> |
|
446 |
* |
|
447 |
* The following example code demonstrates how this method might be |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
448 |
* used: |
2 | 449 |
* <pre> |
450 |
* InputStream is ... |
|
451 |
* OutputStream os ... |
|
452 |
* GSSContext context ... |
|
453 |
* |
|
454 |
* // Loop while there is still a token to be processed |
|
455 |
* |
|
456 |
* while (!context.isEstablished()) { |
|
457 |
* |
|
458 |
* context.acceptSecContext(is, os); |
|
459 |
* |
|
460 |
* // send output token if generated |
|
461 |
* os.flush(); |
|
462 |
* } |
|
463 |
* </pre> |
|
464 |
* |
|
465 |
* |
|
466 |
* @param inStream an InputStream that contains the token generated by |
|
467 |
* the peer. |
|
468 |
* @param outStream an OutputStream where the output token will be |
|
469 |
* written. During the final stage of context establishment, there may be |
|
470 |
* no bytes written. |
|
471 |
* |
|
472 |
* @throws GSSException containing the following |
|
473 |
* major error codes: |
|
474 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}, |
|
475 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC}, |
|
476 |
* {@link GSSException#NO_CRED GSSException.NO_CRED}, |
|
477 |
* {@link GSSException#CREDENTIALS_EXPIRED |
|
478 |
* GSSException.CREDENTIALS_EXPIRED}, |
|
479 |
* {@link GSSException#BAD_BINDINGS GSSException.BAD_BINDINGS}, |
|
480 |
* {@link GSSException#OLD_TOKEN GSSException.OLD_TOKEN}, |
|
481 |
* {@link GSSException#DUPLICATE_TOKEN GSSException.DUPLICATE_TOKEN}, |
|
482 |
* {@link GSSException#BAD_MECH GSSException.BAD_MECH}, |
|
483 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
484 |
* |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
485 |
* @deprecated The stream-based methods have been removed from RFC 8353. |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
486 |
* Use {@link #acceptSecContext(byte[], int, int)} instead. |
2 | 487 |
*/ |
488 |
/* Missing return value in RFC. int should have been returned. |
|
489 |
* ----------------------------------------------------------- |
|
490 |
* |
|
491 |
* The application can determine if a token is written to the |
|
492 |
* OutputStream from the return value of this method. A return value of |
|
493 |
* <code>0</code> indicates that no token was written. |
|
494 |
* |
|
495 |
* @return <strong>the number of bytes written to the |
|
496 |
* OutputStream as part of the token to be sent to the peer. A value of |
|
497 |
* 0 indicates that no token needs to be |
|
498 |
* sent.</strong> |
|
499 |
*/ |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
500 |
@Deprecated(since="11") |
2 | 501 |
public void acceptSecContext(InputStream inStream, |
502 |
OutputStream outStream) throws GSSException; |
|
503 |
||
504 |
/** |
|
505 |
* Used during context establishment to determine the state of the |
|
506 |
* context. |
|
507 |
* |
|
508 |
* @return <code>true</code> if this is a fully established context on |
|
509 |
* the caller's side and no more tokens are needed from the peer. |
|
510 |
*/ |
|
511 |
public boolean isEstablished(); |
|
512 |
||
513 |
/** |
|
514 |
* Releases any system resources and cryptographic information stored in |
|
515 |
* the context object and invalidates the context. |
|
516 |
* |
|
517 |
* |
|
518 |
* @throws GSSException containing the following |
|
519 |
* major error codes: |
|
520 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
521 |
*/ |
|
522 |
public void dispose() throws GSSException; |
|
523 |
||
524 |
/** |
|
525 |
* Used to determine limits on the size of the message |
|
526 |
* that can be passed to <code>wrap</code>. Returns the maximum |
|
527 |
* message size that, if presented to the <code>wrap</code> method with |
|
528 |
* the same <code>confReq</code> and <code>qop</code> parameters, will |
|
529 |
* result in an output token containing no more |
|
530 |
* than <code>maxTokenSize</code> bytes.<p> |
|
531 |
* |
|
532 |
* This call is intended for use by applications that communicate over |
|
533 |
* protocols that impose a maximum message size. It enables the |
|
534 |
* application to fragment messages prior to applying protection.<p> |
|
535 |
* |
|
536 |
* GSS-API implementations are recommended but not required to detect |
|
537 |
* invalid QOP values when <code>getWrapSizeLimit</code> is called. |
|
538 |
* This routine guarantees only a maximum message size, not the |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
539 |
* availability of specific QOP values for message protection. |
2 | 540 |
* |
541 |
* @param qop the level of protection wrap will be asked to provide. |
|
542 |
* @param confReq <code>true</code> if wrap will be asked to provide |
|
543 |
* privacy, <code>false</code> otherwise. |
|
544 |
* @param maxTokenSize the desired maximum size of the token emitted by |
|
545 |
* wrap. |
|
546 |
* @return the maximum size of the input token for the given output |
|
547 |
* token size |
|
548 |
* |
|
549 |
* @throws GSSException containing the following |
|
550 |
* major error codes: |
|
551 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
552 |
* {@link GSSException#BAD_QOP GSSException.BAD_QOP}, |
|
553 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
554 |
*/ |
|
555 |
public int getWrapSizeLimit(int qop, boolean confReq, |
|
556 |
int maxTokenSize) throws GSSException; |
|
557 |
||
558 |
/** |
|
559 |
* Applies per-message security services over the established security |
|
560 |
* context. The method will return a token with the |
|
561 |
* application supplied data and a cryptographic MIC over it. |
|
562 |
* The data may be encrypted if confidentiality (privacy) was |
|
563 |
* requested.<p> |
|
564 |
* |
|
565 |
* The MessageProp object is instantiated by the application and used |
|
566 |
* to specify a QOP value which selects cryptographic algorithms, and a |
|
567 |
* privacy service to optionally encrypt the message. The underlying |
|
568 |
* mechanism that is used in the call may not be able to provide the |
|
569 |
* privacy service. It sets the actual privacy service that it does |
|
570 |
* provide in this MessageProp object which the caller should then |
|
571 |
* query upon return. If the mechanism is not able to provide the |
|
572 |
* requested QOP, it throws a GSSException with the BAD_QOP code.<p> |
|
573 |
* |
|
574 |
* Since some application-level protocols may wish to use tokens |
|
575 |
* emitted by wrap to provide "secure framing", implementations should |
|
576 |
* support the wrapping of zero-length messages.<p> |
|
577 |
* |
|
578 |
* The application will be responsible for sending the token to the |
|
579 |
* peer. |
|
580 |
* |
|
581 |
* @param inBuf application data to be protected. |
|
582 |
* @param offset the offset within the inBuf where the data begins. |
|
583 |
* @param len the length of the data |
|
584 |
* @param msgProp instance of MessageProp that is used by the |
|
585 |
* application to set the desired QOP and privacy state. Set the |
|
586 |
* desired QOP to 0 to request the default QOP. Upon return from this |
|
28059
e576535359cc
8067377: My hobby: caning, then then canning, the the can-can
martin
parents:
26629
diff
changeset
|
587 |
* method, this object will contain the actual privacy state that |
2 | 588 |
* was applied to the message by the underlying mechanism. |
589 |
* @return a byte[] containing the token to be sent to the peer. |
|
590 |
* |
|
591 |
* @throws GSSException containing the following major error codes: |
|
592 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
593 |
* {@link GSSException#BAD_QOP GSSException.BAD_QOP}, |
|
594 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
595 |
*/ |
|
596 |
public byte[] wrap(byte inBuf[], int offset, int len, |
|
597 |
MessageProp msgProp) throws GSSException; |
|
598 |
||
599 |
/** |
|
600 |
* Applies per-message security services over the established security |
|
601 |
* context using streams. The method will return a |
|
602 |
* token with the application supplied data and a cryptographic MIC over it. |
|
603 |
* The data may be encrypted if confidentiality |
|
604 |
* (privacy) was requested. This method is equivalent to the byte array |
|
605 |
* based {@link #wrap(byte[], int, int, MessageProp) wrap} method.<p> |
|
606 |
* |
|
607 |
* The application will be responsible for sending the token to the |
|
608 |
* peer. Typically, the application would |
|
609 |
* ensure this by calling the {@link java.io.OutputStream#flush() flush} |
|
610 |
* method on an <code>OutputStream</code> that encapsulates the |
|
611 |
* connection between the two peers.<p> |
|
612 |
* |
|
613 |
* The MessageProp object is instantiated by the application and used |
|
614 |
* to specify a QOP value which selects cryptographic algorithms, and a |
|
615 |
* privacy service to optionally encrypt the message. The underlying |
|
616 |
* mechanism that is used in the call may not be able to provide the |
|
617 |
* privacy service. It sets the actual privacy service that it does |
|
618 |
* provide in this MessageProp object which the caller should then |
|
619 |
* query upon return. If the mechanism is not able to provide the |
|
620 |
* requested QOP, it throws a GSSException with the BAD_QOP code.<p> |
|
621 |
* |
|
622 |
* Since some application-level protocols may wish to use tokens |
|
623 |
* emitted by wrap to provide "secure framing", implementations should |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
624 |
* support the wrapping of zero-length messages. |
2 | 625 |
* |
626 |
* @param inStream an InputStream containing the application data to be |
|
627 |
* protected. All of the data that is available in |
|
628 |
* inStream is used. |
|
629 |
* @param outStream an OutputStream to write the protected message |
|
630 |
* to. |
|
631 |
* @param msgProp instance of MessageProp that is used by the |
|
632 |
* application to set the desired QOP and privacy state. Set the |
|
633 |
* desired QOP to 0 to request the default QOP. Upon return from this |
|
28059
e576535359cc
8067377: My hobby: caning, then then canning, the the can-can
martin
parents:
26629
diff
changeset
|
634 |
* method, this object will contain the actual privacy state that |
2 | 635 |
* was applied to the message by the underlying mechanism. |
636 |
* |
|
637 |
* @throws GSSException containing the following |
|
638 |
* major error codes: |
|
639 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
640 |
* {@link GSSException#BAD_QOP GSSException.BAD_QOP}, |
|
641 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
642 |
* |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
643 |
* @deprecated The stream-based methods have been removed from RFC 8353. |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
644 |
* Use {@link #wrap(byte[], int, int, MessageProp)} instead. |
2 | 645 |
*/ |
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
646 |
@Deprecated(since="11") |
2 | 647 |
public void wrap(InputStream inStream, OutputStream outStream, |
648 |
MessageProp msgProp) throws GSSException; |
|
649 |
||
650 |
/** |
|
651 |
* Used to process tokens generated by the <code>wrap</code> method on |
|
652 |
* the other side of the context. The method will return the message |
|
653 |
* supplied by the peer application to its wrap call, while at the same |
|
654 |
* time verifying the embedded MIC for that message.<p> |
|
655 |
* |
|
656 |
* The MessageProp object is instantiated by the application and is |
|
657 |
* used by the underlying mechanism to return information to the caller |
|
658 |
* such as the QOP, whether confidentiality was applied to the message, |
|
659 |
* and other supplementary message state information.<p> |
|
660 |
* |
|
661 |
* Since some application-level protocols may wish to use tokens |
|
662 |
* emitted by wrap to provide "secure framing", implementations should |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
663 |
* support the wrapping and unwrapping of zero-length messages. |
2 | 664 |
* |
665 |
* @param inBuf a byte array containing the wrap token received from |
|
666 |
* peer. |
|
667 |
* @param offset the offset where the token begins. |
|
668 |
* @param len the length of the token |
|
669 |
* @param msgProp upon return from the method, this object will contain |
|
670 |
* the applied QOP, the privacy state of the message, and supplementary |
|
671 |
* information stating if the token was a duplicate, old, out of |
|
672 |
* sequence or arriving after a gap. |
|
673 |
* @return a byte[] containing the message unwrapped from the input |
|
674 |
* token. |
|
675 |
* |
|
676 |
* @throws GSSException containing the following |
|
677 |
* major error codes: |
|
678 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}, |
|
679 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC}, |
|
680 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
681 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
682 |
*/ |
|
683 |
public byte [] unwrap(byte[] inBuf, int offset, int len, |
|
684 |
MessageProp msgProp) throws GSSException; |
|
685 |
||
686 |
/** |
|
687 |
* Uses streams to process tokens generated by the <code>wrap</code> |
|
688 |
* method on the other side of the context. The method will return the |
|
689 |
* message supplied by the peer application to its wrap call, while at |
|
690 |
* the same time verifying the embedded MIC for that message.<p> |
|
691 |
* |
|
692 |
* The MessageProp object is instantiated by the application and is |
|
693 |
* used by the underlying mechanism to return information to the caller |
|
694 |
* such as the QOP, whether confidentiality was applied to the message, |
|
695 |
* and other supplementary message state information.<p> |
|
696 |
* |
|
697 |
* Since some application-level protocols may wish to use tokens |
|
698 |
* emitted by wrap to provide "secure framing", implementations should |
|
699 |
* support the wrapping and unwrapping of zero-length messages.<p> |
|
700 |
* |
|
701 |
* The format of the input token that this method |
|
702 |
* reads is defined in the specification for the underlying mechanism that |
|
703 |
* will be used. This method will attempt to read one of these tokens per |
|
704 |
* invocation. If the mechanism token contains a definitive start and |
|
705 |
* end this method may block on the <code>InputStream</code> if only |
|
706 |
* part of the token is available. If the start and end of the token |
|
707 |
* are not definitive then the method will attempt to treat all |
|
708 |
* available bytes as part of the token.<p> |
|
709 |
* |
|
4336 | 710 |
* Other than the possible blocking behavior described above, this |
2 | 711 |
* method is equivalent to the byte array based {@link #unwrap(byte[], |
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
712 |
* int, int, MessageProp) unwrap} method. |
2 | 713 |
* |
714 |
* @param inStream an InputStream that contains the wrap token generated |
|
715 |
* by the peer. |
|
716 |
* @param outStream an OutputStream to write the application message |
|
717 |
* to. |
|
718 |
* @param msgProp upon return from the method, this object will contain |
|
719 |
* the applied QOP, the privacy state of the message, and supplementary |
|
720 |
* information stating if the token was a duplicate, old, out of |
|
721 |
* sequence or arriving after a gap. |
|
722 |
* |
|
723 |
* @throws GSSException containing the following |
|
724 |
* major error codes: |
|
725 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN}, |
|
726 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC}, |
|
727 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
728 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
729 |
* |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
730 |
* @deprecated The stream-based methods have been removed from RFC 8353. |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
731 |
* Use {@link #unwrap(byte[], int, int, MessageProp)} instead. |
2 | 732 |
*/ |
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
733 |
@Deprecated(since="11") |
2 | 734 |
public void unwrap(InputStream inStream, OutputStream outStream, |
735 |
MessageProp msgProp) throws GSSException; |
|
736 |
||
737 |
/** |
|
738 |
* Returns a token containing a cryptographic Message Integrity Code |
|
739 |
* (MIC) for the supplied message, for transfer to the peer |
|
740 |
* application. Unlike wrap, which encapsulates the user message in the |
|
741 |
* returned token, only the message MIC is returned in the output |
|
742 |
* token.<p> |
|
743 |
* |
|
744 |
* Note that privacy can only be applied through the wrap call.<p> |
|
745 |
* |
|
746 |
* Since some application-level protocols may wish to use tokens emitted |
|
747 |
* by getMIC to provide "secure framing", implementations should support |
|
748 |
* derivation of MICs from zero-length messages. |
|
749 |
* |
|
750 |
* @param inMsg the message to generate the MIC over. |
|
751 |
* @param offset offset within the inMsg where the message begins. |
|
752 |
* @param len the length of the message |
|
753 |
* @param msgProp an instance of <code>MessageProp</code> that is used |
|
754 |
* by the application to set the desired QOP. Set the desired QOP to |
|
755 |
* <code>0</code> in <code>msgProp</code> to request the default |
|
756 |
* QOP. Alternatively pass in <code>null</code> for <code>msgProp</code> |
|
757 |
* to request the default QOP. |
|
758 |
* @return a byte[] containing the token to be sent to the peer. |
|
759 |
* |
|
760 |
* @throws GSSException containing the following |
|
761 |
* major error codes: |
|
762 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
763 |
* {@link GSSException#BAD_QOP GSSException.BAD_QOP}, |
|
764 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
765 |
*/ |
|
766 |
public byte[] getMIC(byte []inMsg, int offset, int len, |
|
767 |
MessageProp msgProp) throws GSSException; |
|
768 |
||
769 |
/** |
|
770 |
* Uses streams to produce a token containing a cryptographic MIC for |
|
771 |
* the supplied message, for transfer to the peer application. |
|
772 |
* Unlike wrap, which encapsulates the user message in the returned |
|
773 |
* token, only the message MIC is produced in the output token. This |
|
774 |
* method is equivalent to the byte array based {@link #getMIC(byte[], |
|
775 |
* int, int, MessageProp) getMIC} method. |
|
776 |
* |
|
777 |
* Note that privacy can only be applied through the wrap call.<p> |
|
778 |
* |
|
779 |
* Since some application-level protocols may wish to use tokens emitted |
|
780 |
* by getMIC to provide "secure framing", implementations should support |
|
781 |
* derivation of MICs from zero-length messages. |
|
782 |
* |
|
783 |
* @param inStream an InputStream containing the message to generate the |
|
784 |
* MIC over. All of the data that is available in |
|
785 |
* inStream is used. |
|
786 |
* @param outStream an OutputStream to write the output token to. |
|
787 |
* @param msgProp an instance of <code>MessageProp</code> that is used |
|
788 |
* by the application to set the desired QOP. Set the desired QOP to |
|
789 |
* <code>0</code> in <code>msgProp</code> to request the default |
|
790 |
* QOP. Alternatively pass in <code>null</code> for <code>msgProp</code> |
|
791 |
* to request the default QOP. |
|
792 |
* |
|
793 |
* @throws GSSException containing the following |
|
794 |
* major error codes: |
|
795 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
796 |
* {@link GSSException#BAD_QOP GSSException.BAD_QOP}, |
|
797 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
798 |
* |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
799 |
* @deprecated The stream-based methods have been removed from RFC 8353. |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
800 |
* Use {@link #getMIC(byte[], int, int, MessageProp)} instead. |
2 | 801 |
*/ |
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
802 |
@Deprecated(since="11") |
2 | 803 |
public void getMIC(InputStream inStream, OutputStream outStream, |
804 |
MessageProp msgProp) throws GSSException; |
|
805 |
||
806 |
/** |
|
807 |
* Verifies the cryptographic MIC, contained in the token parameter, |
|
808 |
* over the supplied message.<p> |
|
809 |
* |
|
810 |
* The MessageProp object is instantiated by the application and is used |
|
811 |
* by the underlying mechanism to return information to the caller such |
|
812 |
* as the QOP indicating the strength of protection that was applied to |
|
813 |
* the message and other supplementary message state information.<p> |
|
814 |
* |
|
815 |
* Since some application-level protocols may wish to use tokens emitted |
|
816 |
* by getMIC to provide "secure framing", implementations should support |
|
817 |
* the calculation and verification of MICs over zero-length messages. |
|
818 |
* |
|
819 |
* @param inToken the token generated by peer's getMIC method. |
|
820 |
* @param tokOffset the offset within the inToken where the token |
|
821 |
* begins. |
|
822 |
* @param tokLen the length of the token. |
|
823 |
* @param inMsg the application message to verify the cryptographic MIC |
|
824 |
* over. |
|
825 |
* @param msgOffset the offset in inMsg where the message begins. |
|
826 |
* @param msgLen the length of the message. |
|
827 |
* @param msgProp upon return from the method, this object will contain |
|
828 |
* the applied QOP and supplementary information stating if the token |
|
829 |
* was a duplicate, old, out of sequence or arriving after a gap. |
|
830 |
* |
|
831 |
* @throws GSSException containing the following |
|
832 |
* major error codes: |
|
833 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN} |
|
834 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC} |
|
835 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED} |
|
836 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
837 |
*/ |
|
838 |
public void verifyMIC(byte[] inToken, int tokOffset, int tokLen, |
|
839 |
byte[] inMsg, int msgOffset, int msgLen, |
|
840 |
MessageProp msgProp) throws GSSException; |
|
841 |
||
842 |
/** |
|
843 |
* Uses streams to verify the cryptographic MIC, contained in the token |
|
844 |
* parameter, over the supplied message. This method is equivalent to |
|
845 |
* the byte array based {@link #verifyMIC(byte[], int, int, byte[], int, |
|
846 |
* int, MessageProp) verifyMIC} method. |
|
847 |
* |
|
848 |
* The MessageProp object is instantiated by the application and is used |
|
849 |
* by the underlying mechanism to return information to the caller such |
|
850 |
* as the QOP indicating the strength of protection that was applied to |
|
851 |
* the message and other supplementary message state information.<p> |
|
852 |
* |
|
853 |
* Since some application-level protocols may wish to use tokens emitted |
|
854 |
* by getMIC to provide "secure framing", implementations should support |
|
855 |
* the calculation and verification of MICs over zero-length messages.<p> |
|
856 |
* |
|
857 |
* The format of the input token that this method |
|
858 |
* reads is defined in the specification for the underlying mechanism that |
|
859 |
* will be used. This method will attempt to read one of these tokens per |
|
860 |
* invocation. If the mechanism token contains a definitive start and |
|
861 |
* end this method may block on the <code>InputStream</code> if only |
|
862 |
* part of the token is available. If the start and end of the token |
|
863 |
* are not definitive then the method will attempt to treat all |
|
864 |
* available bytes as part of the token.<p> |
|
865 |
* |
|
4336 | 866 |
* Other than the possible blocking behavior described above, this |
2 | 867 |
* method is equivalent to the byte array based {@link #verifyMIC(byte[], |
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
868 |
* int, int, byte[], int, int, MessageProp) verifyMIC} method. |
2 | 869 |
* |
870 |
* @param tokStream an InputStream containing the token generated by the |
|
871 |
* peer's getMIC method. |
|
872 |
* @param msgStream an InputStream containing the application message to |
|
873 |
* verify the cryptographic MIC over. All of the data |
|
874 |
* that is available in msgStream is used. |
|
875 |
* @param msgProp upon return from the method, this object will contain |
|
876 |
* the applied QOP and supplementary information stating if the token |
|
877 |
* was a duplicate, old, out of sequence or arriving after a gap. |
|
878 |
* |
|
879 |
* @throws GSSException containing the following |
|
880 |
* major error codes: |
|
881 |
* {@link GSSException#DEFECTIVE_TOKEN GSSException.DEFECTIVE_TOKEN} |
|
882 |
* {@link GSSException#BAD_MIC GSSException.BAD_MIC} |
|
883 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED} |
|
884 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
885 |
* |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
886 |
* @deprecated The stream-based methods have been removed from RFC 8353. |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
887 |
* Use {@link #verifyMIC(byte[], int, int, byte[], int, int, MessageProp)} |
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
888 |
* instead. |
2 | 889 |
*/ |
50307
ba1b490901d4
8072996: Deprecate stream-based GSSContext methods
weijun
parents:
47216
diff
changeset
|
890 |
@Deprecated(since="11") |
2 | 891 |
public void verifyMIC(InputStream tokStream, InputStream msgStream, |
892 |
MessageProp msgProp) throws GSSException; |
|
893 |
||
894 |
/** |
|
895 |
* Exports this context so that another process may |
|
896 |
* import it.. Provided to support the sharing of work between |
|
897 |
* multiple processes. This routine will typically be used by the |
|
898 |
* context-acceptor, in an application where a single process receives |
|
899 |
* incoming connection requests and accepts security contexts over |
|
900 |
* them, then passes the established context to one or more other |
|
901 |
* processes for message exchange.<p> |
|
902 |
* |
|
903 |
* This method deactivates the security context and creates an |
|
904 |
* interprocess token which, when passed to {@link |
|
905 |
* GSSManager#createContext(byte[]) GSSManager.createContext} in |
|
906 |
* another process, will re-activate the context in the second process. |
|
907 |
* Only a single instantiation of a given context may be active at any |
|
908 |
* one time; a subsequent attempt by a context exporter to access the |
|
909 |
* exported security context will fail.<p> |
|
910 |
* |
|
911 |
* The implementation may constrain the set of processes by which the |
|
912 |
* interprocess token may be imported, either as a function of local |
|
913 |
* security policy, or as a result of implementation decisions. For |
|
914 |
* example, some implementations may constrain contexts to be passed |
|
915 |
* only between processes that run under the same account, or which are |
|
916 |
* part of the same process group.<p> |
|
917 |
* |
|
918 |
* The interprocess token may contain security-sensitive information |
|
919 |
* (for example cryptographic keys). While mechanisms are encouraged |
|
920 |
* to either avoid placing such sensitive information within |
|
921 |
* interprocess tokens, or to encrypt the token before returning it to |
|
922 |
* the application, in a typical GSS-API implementation this may not be |
|
923 |
* possible. Thus the application must take care to protect the |
|
924 |
* interprocess token, and ensure that any process to which the token |
|
925 |
* is transferred is trustworthy. <p> |
|
926 |
* |
|
927 |
* Implementations are not required to support the inter-process |
|
928 |
* transfer of security contexts. Calling the {@link #isTransferable() |
|
929 |
* isTransferable} method will indicate if the context object is |
|
930 |
* transferable.<p> |
|
931 |
* |
|
932 |
* Calling this method on a context that |
|
933 |
* is not exportable will result in this exception being thrown with |
|
934 |
* the error code {@link GSSException#UNAVAILABLE |
|
935 |
* GSSException.UNAVAILABLE}. |
|
936 |
* |
|
937 |
* @return a byte[] containing the exported context |
|
938 |
* @see GSSManager#createContext(byte[]) |
|
939 |
* |
|
940 |
* @throws GSSException containing the following |
|
941 |
* major error codes: |
|
942 |
* {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE}, |
|
943 |
* {@link GSSException#CONTEXT_EXPIRED GSSException.CONTEXT_EXPIRED}, |
|
944 |
* {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT}, |
|
945 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
946 |
*/ |
|
947 |
public byte [] export() throws GSSException; |
|
948 |
||
949 |
/** |
|
950 |
* Requests that mutual authentication be done during |
|
951 |
* context establishment. This request can only be made on the context |
|
952 |
* initiator's side and it has to be done prior to the first call to |
|
953 |
* <code>initSecContext</code>.<p> |
|
954 |
* |
|
955 |
* Not all mechanisms support mutual authentication and some mechanisms |
|
956 |
* might require mutual authentication even if the application |
|
957 |
* doesn't. Therefore, the application should check to see if the |
|
958 |
* request was honored with the {@link #getMutualAuthState() |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
959 |
* getMutualAuthState} method. |
2 | 960 |
* |
961 |
* @param state a boolean value indicating whether mutual |
|
4336 | 962 |
* authentication should be used or not. |
2 | 963 |
* @see #getMutualAuthState() |
964 |
* |
|
965 |
* @throws GSSException containing the following |
|
966 |
* major error codes: |
|
967 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
968 |
*/ |
|
969 |
public void requestMutualAuth(boolean state) throws GSSException; |
|
970 |
||
971 |
/** |
|
972 |
* Requests that replay detection be enabled for the |
|
4336 | 973 |
* per-message security services after context establishment. This |
2 | 974 |
* request can only be made on the context initiator's side and it has |
975 |
* to be done prior to the first call to |
|
976 |
* <code>initSecContext</code>. During context establishment replay |
|
977 |
* detection is not an option and is a function of the underlying |
|
978 |
* mechanism's capabilities.<p> |
|
979 |
* |
|
980 |
* Not all mechanisms support replay detection and some mechanisms |
|
981 |
* might require replay detection even if the application |
|
982 |
* doesn't. Therefore, the application should check to see if the |
|
983 |
* request was honored with the {@link #getReplayDetState() |
|
984 |
* getReplayDetState} method. If replay detection is enabled then the |
|
985 |
* {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken} and {@link |
|
986 |
* MessageProp#isOldToken() MessageProp.isOldToken} methods will return |
|
987 |
* valid results for the <code>MessageProp</code> object that is passed |
|
988 |
* in to the <code>unwrap</code> method or the <code>verifyMIC</code> |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
989 |
* method. |
2 | 990 |
* |
991 |
* @param state a boolean value indicating whether replay detection |
|
992 |
* should be enabled over the established context or not. |
|
993 |
* @see #getReplayDetState() |
|
994 |
* |
|
995 |
* @throws GSSException containing the following |
|
996 |
* major error codes: |
|
997 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
998 |
*/ |
|
999 |
public void requestReplayDet(boolean state) throws GSSException; |
|
1000 |
||
1001 |
/** |
|
1002 |
* Requests that sequence checking be enabled for the |
|
4336 | 1003 |
* per-message security services after context establishment. This |
2 | 1004 |
* request can only be made on the context initiator's side and it has |
1005 |
* to be done prior to the first call to |
|
1006 |
* <code>initSecContext</code>. During context establishment sequence |
|
1007 |
* checking is not an option and is a function of the underlying |
|
1008 |
* mechanism's capabilities.<p> |
|
1009 |
* |
|
1010 |
* Not all mechanisms support sequence checking and some mechanisms |
|
1011 |
* might require sequence checking even if the application |
|
1012 |
* doesn't. Therefore, the application should check to see if the |
|
1013 |
* request was honored with the {@link #getSequenceDetState() |
|
1014 |
* getSequenceDetState} method. If sequence checking is enabled then the |
|
1015 |
* {@link MessageProp#isDuplicateToken() MessageProp.isDuplicateToken}, |
|
1016 |
* {@link MessageProp#isOldToken() MessageProp.isOldToken}, |
|
1017 |
* {@link MessageProp#isUnseqToken() MessageProp.isUnseqToken}, and |
|
1018 |
* {@link MessageProp#isGapToken() MessageProp.isGapToken} methods will return |
|
1019 |
* valid results for the <code>MessageProp</code> object that is passed |
|
1020 |
* in to the <code>unwrap</code> method or the <code>verifyMIC</code> |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1021 |
* method. |
2 | 1022 |
* |
1023 |
* @param state a boolean value indicating whether sequence checking |
|
1024 |
* should be enabled over the established context or not. |
|
1025 |
* @see #getSequenceDetState() |
|
1026 |
* |
|
1027 |
* @throws GSSException containing the following |
|
1028 |
* major error codes: |
|
1029 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1030 |
*/ |
|
1031 |
public void requestSequenceDet(boolean state) throws GSSException; |
|
1032 |
||
1033 |
/** |
|
1034 |
* Requests that the initiator's credentials be |
|
1035 |
* delegated to the acceptor during context establishment. This |
|
1036 |
* request can only be made on the context initiator's side and it has |
|
1037 |
* to be done prior to the first call to |
|
1038 |
* <code>initSecContext</code>. |
|
1039 |
* |
|
1040 |
* Not all mechanisms support credential delegation. Therefore, an |
|
1041 |
* application that desires delegation should check to see if the |
|
1042 |
* request was honored with the {@link #getCredDelegState() |
|
1043 |
* getCredDelegState} method. If the application indicates that |
|
1044 |
* delegation must not be used, then the mechanism will honor the |
|
1045 |
* request and delegation will not occur. This is an exception |
|
1046 |
* to the general rule that a mechanism may enable a service even if it |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1047 |
* is not requested. |
2 | 1048 |
* |
1049 |
* @param state a boolean value indicating whether the credentials |
|
1050 |
* should be delegated or not. |
|
1051 |
* @see #getCredDelegState() |
|
1052 |
* |
|
1053 |
* @throws GSSException containing the following |
|
1054 |
* major error codes: |
|
1055 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1056 |
*/ |
|
1057 |
public void requestCredDeleg(boolean state) throws GSSException; |
|
1058 |
||
1059 |
/** |
|
1060 |
* Requests that the initiator's identity not be |
|
1061 |
* disclosed to the acceptor. This request can only be made on the |
|
1062 |
* context initiator's side and it has to be done prior to the first |
|
1063 |
* call to <code>initSecContext</code>. |
|
1064 |
* |
|
1065 |
* Not all mechanisms support anonymity for the initiator. Therefore, the |
|
1066 |
* application should check to see if the request was honored with the |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1067 |
* {@link #getAnonymityState() getAnonymityState} method. |
2 | 1068 |
* |
1069 |
* @param state a boolean value indicating if the initiator should |
|
1070 |
* be authenticated to the acceptor as an anonymous principal. |
|
1071 |
* @see #getAnonymityState |
|
1072 |
* |
|
1073 |
* @throws GSSException containing the following |
|
1074 |
* major error codes: |
|
1075 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1076 |
*/ |
|
1077 |
public void requestAnonymity(boolean state) throws GSSException; |
|
1078 |
||
1079 |
/** |
|
1080 |
* Requests that data confidentiality be enabled |
|
1081 |
* for the <code>wrap</code> method. This request can only be made on |
|
1082 |
* the context initiator's side and it has to be done prior to the |
|
1083 |
* first call to <code>initSecContext</code>. |
|
1084 |
* |
|
1085 |
* Not all mechanisms support confidentiality and other mechanisms |
|
1086 |
* might enable it even if the application doesn't request |
|
1087 |
* it. The application may check to see if the request was honored with |
|
1088 |
* the {@link #getConfState() getConfState} method. If confidentiality |
|
1089 |
* is enabled, only then will the mechanism honor a request for privacy |
|
1090 |
* in the {@link MessageProp#MessageProp(int, boolean) MessageProp} |
|
1091 |
* object that is passed in to the <code>wrap</code> method.<p> |
|
1092 |
* |
|
1093 |
* Enabling confidentiality will also automatically enable |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1094 |
* integrity. |
2 | 1095 |
* |
1096 |
* @param state a boolean value indicating whether confidentiality |
|
1097 |
* should be enabled or not. |
|
1098 |
* @see #getConfState() |
|
1099 |
* @see #getIntegState() |
|
1100 |
* @see #requestInteg(boolean) |
|
1101 |
* @see MessageProp |
|
1102 |
* |
|
1103 |
* @throws GSSException containing the following |
|
1104 |
* major error codes: |
|
1105 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1106 |
*/ |
|
1107 |
public void requestConf(boolean state) throws GSSException; |
|
1108 |
||
1109 |
/** |
|
1110 |
* Requests that data integrity be enabled |
|
1111 |
* for the <code>wrap</code> and <code>getMIC</code>methods. This |
|
1112 |
* request can only be made on the context initiator's side and it has |
|
1113 |
* to be done prior to the first call to <code>initSecContext</code>. |
|
1114 |
* |
|
1115 |
* Not all mechanisms support integrity and other mechanisms |
|
1116 |
* might enable it even if the application doesn't request |
|
1117 |
* it. The application may check to see if the request was honored with |
|
1118 |
* the {@link #getIntegState() getIntegState} method.<p> |
|
1119 |
* |
|
1120 |
* Disabling integrity will also automatically disable |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1121 |
* confidentiality. |
2 | 1122 |
* |
1123 |
* @param state a boolean value indicating whether integrity |
|
1124 |
* should be enabled or not. |
|
1125 |
* @see #getIntegState() |
|
1126 |
* |
|
1127 |
* @throws GSSException containing the following |
|
1128 |
* major error codes: |
|
1129 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1130 |
*/ |
|
1131 |
public void requestInteg(boolean state) throws GSSException; |
|
1132 |
||
1133 |
/** |
|
1134 |
* Requests a lifetime in seconds for the |
|
1135 |
* context. This method can only be called on the context initiator's |
|
1136 |
* side and it has to be done prior to the first call to |
|
1137 |
* <code>initSecContext</code>.<p> |
|
1138 |
* |
|
21278 | 1139 |
* The actual lifetime of the context will depend on the capabilities of |
2 | 1140 |
* the underlying mechanism and the application should call the {@link |
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1141 |
* #getLifetime() getLifetime} method to determine this. |
2 | 1142 |
* |
1143 |
* @param lifetime the desired context lifetime in seconds. Use |
|
1144 |
* <code>INDEFINITE_LIFETIME</code> to request an indefinite lifetime |
|
1145 |
* and <code>DEFAULT_LIFETIME</code> to request a default lifetime. |
|
1146 |
* @see #getLifetime() |
|
1147 |
* |
|
1148 |
* @throws GSSException containing the following |
|
1149 |
* major error codes: |
|
1150 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1151 |
*/ |
|
1152 |
public void requestLifetime(int lifetime) throws GSSException; |
|
1153 |
||
1154 |
/** |
|
1155 |
* Sets the channel bindings to be used during context |
|
1156 |
* establishment. This method can be called on both |
|
1157 |
* the context initiator's and the context acceptor's side, but it must |
|
1158 |
* be called before context establishment begins. This means that an |
|
1159 |
* initiator must call it before the first call to |
|
1160 |
* <code>initSecContext</code> and the acceptor must call it before the |
|
1161 |
* first call to <code>acceptSecContext</code>. |
|
1162 |
* |
|
1163 |
* @param cb the channel bindings to use. |
|
1164 |
* |
|
1165 |
* @throws GSSException containing the following |
|
1166 |
* major error codes: |
|
1167 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1168 |
*/ |
|
1169 |
public void setChannelBinding(ChannelBinding cb) throws GSSException; |
|
1170 |
||
1171 |
/** |
|
1172 |
* Determines if credential delegation is enabled on |
|
1173 |
* this context. It can be called by both the context initiator and the |
|
1174 |
* context acceptor. For a definitive answer this method must be |
|
1175 |
* called only after context establishment is complete. Note that if an |
|
1176 |
* initiator requests that delegation not be allowed the {@link |
|
1177 |
* #requestCredDeleg(boolean) requestCredDeleg} method will honor that |
|
1178 |
* request and this method will return <code>false</code> on the |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1179 |
* initiator's side from that point onwards. |
2 | 1180 |
* |
1181 |
* @return true if delegation is enabled, false otherwise. |
|
1182 |
* @see #requestCredDeleg(boolean) |
|
1183 |
*/ |
|
1184 |
public boolean getCredDelegState(); |
|
1185 |
||
1186 |
/** |
|
1187 |
* Determines if mutual authentication is enabled on |
|
1188 |
* this context. It can be called by both the context initiator and the |
|
1189 |
* context acceptor. For a definitive answer this method must be |
|
1190 |
* called only after context establishment is complete. An initiator |
|
1191 |
* that requests mutual authentication can call this method after |
|
1192 |
* context completion and dispose the context if its request was not |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1193 |
* honored. |
2 | 1194 |
* |
1195 |
* @return true if mutual authentication is enabled, false otherwise. |
|
1196 |
* @see #requestMutualAuth(boolean) |
|
1197 |
*/ |
|
1198 |
public boolean getMutualAuthState(); |
|
1199 |
||
1200 |
/** |
|
1201 |
* Determines if replay detection is enabled for the |
|
1202 |
* per-message security services from this context. It can be called by |
|
1203 |
* both the context initiator and the context acceptor. For a |
|
1204 |
* definitive answer this method must be called only after context |
|
1205 |
* establishment is complete. An initiator that requests replay |
|
1206 |
* detection can call this method after context completion and |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1207 |
* dispose the context if its request was not honored. |
2 | 1208 |
* |
1209 |
* @return true if replay detection is enabled, false otherwise. |
|
1210 |
* @see #requestReplayDet(boolean) |
|
1211 |
*/ |
|
1212 |
public boolean getReplayDetState(); |
|
1213 |
||
1214 |
/** |
|
1215 |
* Determines if sequence checking is enabled for the |
|
1216 |
* per-message security services from this context. It can be called by |
|
1217 |
* both the context initiator and the context acceptor. For a |
|
1218 |
* definitive answer this method must be called only after context |
|
1219 |
* establishment is complete. An initiator that requests sequence |
|
1220 |
* checking can call this method after context completion and |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1221 |
* dispose the context if its request was not honored. |
2 | 1222 |
* |
1223 |
* @return true if sequence checking is enabled, false otherwise. |
|
1224 |
* @see #requestSequenceDet(boolean) |
|
1225 |
*/ |
|
1226 |
public boolean getSequenceDetState(); |
|
1227 |
||
1228 |
/** |
|
1229 |
* Determines if the context initiator is |
|
1230 |
* anonymously authenticated to the context acceptor. It can be called by |
|
1231 |
* both the context initiator and the context acceptor, and at any |
|
1232 |
* time. <strong>On the initiator side, a call to this method determines |
|
1233 |
* if the identity of the initiator has been disclosed in any of the |
|
1234 |
* context establishment tokens that might have been generated thus far |
|
1235 |
* by <code>initSecContext</code>. An initiator that absolutely must be |
|
1236 |
* authenticated anonymously should call this method after each call to |
|
1237 |
* <code>initSecContext</code> to determine if the generated token |
|
1238 |
* should be sent to the peer or the context aborted.</strong> On the |
|
1239 |
* acceptor side, a call to this method determines if any of the tokens |
|
1240 |
* processed by <code>acceptSecContext</code> thus far have divulged |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1241 |
* the identity of the initiator. |
2 | 1242 |
* |
1243 |
* @return true if the context initiator is still anonymous, false |
|
1244 |
* otherwise. |
|
1245 |
* @see #requestAnonymity(boolean) |
|
1246 |
*/ |
|
1247 |
public boolean getAnonymityState(); |
|
1248 |
||
1249 |
/** |
|
1250 |
* Determines if the context is transferable to other processes |
|
1251 |
* through the use of the {@link #export() export} method. This call |
|
1252 |
* is only valid on fully established contexts. |
|
1253 |
* |
|
1254 |
* @return true if this context can be exported, false otherwise. |
|
1255 |
* |
|
1256 |
* @throws GSSException containing the following |
|
1257 |
* major error codes: |
|
1258 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1259 |
*/ |
|
1260 |
public boolean isTransferable() throws GSSException; |
|
1261 |
||
1262 |
/** |
|
1263 |
* Determines if the context is ready for per message operations to be |
|
1264 |
* used over it. Some mechanisms may allow the usage of the |
|
1265 |
* per-message operations before the context is fully established. |
|
1266 |
* |
|
1267 |
* @return true if methods like <code>wrap</code>, <code>unwrap</code>, |
|
1268 |
* <code>getMIC</code>, and <code>verifyMIC</code> can be used with |
|
1269 |
* this context at the current stage of context establishment, false |
|
1270 |
* otherwise. |
|
1271 |
*/ |
|
1272 |
public boolean isProtReady(); |
|
1273 |
||
1274 |
/** |
|
1275 |
* Determines if data confidentiality is available |
|
1276 |
* over the context. This method can be called by both the context |
|
1277 |
* initiator and the context acceptor, but only after one of {@link |
|
1278 |
* #isProtReady() isProtReady} or {@link #isEstablished() |
|
1279 |
* isEstablished} return <code>true</code>. If this method returns |
|
1280 |
* <code>true</code>, so will {@link #getIntegState() |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1281 |
* getIntegState} |
2 | 1282 |
* |
1283 |
* @return true if confidentiality services are available, false |
|
1284 |
* otherwise. |
|
1285 |
* @see #requestConf(boolean) |
|
1286 |
*/ |
|
1287 |
public boolean getConfState(); |
|
1288 |
||
1289 |
/** |
|
1290 |
* Determines if data integrity is available |
|
1291 |
* over the context. This method can be called by both the context |
|
1292 |
* initiator and the context acceptor, but only after one of {@link |
|
1293 |
* #isProtReady() isProtReady} or {@link #isEstablished() |
|
1294 |
* isEstablished} return <code>true</code>. This method will always |
|
1295 |
* return <code>true</code> if {@link #getConfState() getConfState} |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1296 |
* returns true. |
2 | 1297 |
* |
1298 |
* @return true if integrity services are available, false otherwise. |
|
1299 |
* @see #requestInteg(boolean) |
|
1300 |
*/ |
|
1301 |
public boolean getIntegState(); |
|
1302 |
||
1303 |
/** |
|
1304 |
* Determines what the remaining lifetime for this |
|
1305 |
* context is. It can be called by both the context initiator and the |
|
1306 |
* context acceptor, but for a definitive answer it should be called |
|
1307 |
* only after {@link #isEstablished() isEstablished} returns |
|
29820
7a3f0268f55b
8076223: Rest of tidy warning in javax.security / java.security
avstepan
parents:
28059
diff
changeset
|
1308 |
* true. |
2 | 1309 |
* |
1310 |
* @return the remaining lifetime in seconds |
|
1311 |
* @see #requestLifetime(int) |
|
1312 |
*/ |
|
1313 |
public int getLifetime(); |
|
1314 |
||
1315 |
/** |
|
1316 |
* Returns the name of the context initiator. This call is valid only |
|
1317 |
* after one of {@link #isProtReady() isProtReady} or {@link |
|
1318 |
* #isEstablished() isEstablished} return <code>true</code>. |
|
1319 |
* |
|
1320 |
* @return a GSSName that is an MN containing the name of the context |
|
1321 |
* initiator. |
|
1322 |
* @see GSSName |
|
1323 |
* |
|
1324 |
* @throws GSSException containing the following |
|
1325 |
* major error codes: |
|
1326 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1327 |
*/ |
|
1328 |
public GSSName getSrcName() throws GSSException; |
|
1329 |
||
1330 |
/** |
|
1331 |
* Returns the name of the context acceptor. This call is valid only |
|
1332 |
* after one of {@link #isProtReady() isProtReady} or {@link |
|
1333 |
* #isEstablished() isEstablished} return <code>true</code>. |
|
1334 |
* |
|
1335 |
* @return a GSSName that is an MN containing the name of the context |
|
1336 |
* acceptor. |
|
1337 |
* |
|
1338 |
* @throws GSSException containing the following |
|
1339 |
* major error codes: |
|
1340 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1341 |
*/ |
|
1342 |
public GSSName getTargName() throws GSSException; |
|
1343 |
||
1344 |
/** |
|
1345 |
* Determines what mechanism is being used for this |
|
1346 |
* context. This method may be called before the context is fully |
|
1347 |
* established, but the mechanism returned may change on successive |
|
1348 |
* calls in the negotiated mechanism case. |
|
1349 |
* |
|
1350 |
* @return the Oid of the mechanism being used |
|
1351 |
* |
|
1352 |
* @throws GSSException containing the following |
|
1353 |
* major error codes: |
|
1354 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1355 |
*/ |
|
1356 |
public Oid getMech() throws GSSException; |
|
1357 |
||
1358 |
/** |
|
1359 |
* Obtains the credentials delegated by the context |
|
1360 |
* initiator to the context acceptor. It should be called only on the |
|
1361 |
* context acceptor's side, and once the context is fully |
|
1362 |
* established. The caller can use the method {@link |
|
1363 |
* #getCredDelegState() getCredDelegState} to determine if there are |
|
1364 |
* any delegated credentials. |
|
1365 |
* |
|
1366 |
* @return a GSSCredential containing the initiator's delegated |
|
1367 |
* credentials, or <code>null</code> is no credentials |
|
1368 |
* were delegated. |
|
1369 |
* |
|
1370 |
* @throws GSSException containing the following |
|
1371 |
* major error codes: |
|
1372 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1373 |
*/ |
|
1374 |
public GSSCredential getDelegCred() throws GSSException; |
|
1375 |
||
1376 |
/** |
|
1377 |
* Determines if this is the context initiator. This |
|
1378 |
* can be called on both the context initiator's and context acceptor's |
|
1379 |
* side. |
|
1380 |
* |
|
1381 |
* @return true if this is the context initiator, false if it is the |
|
1382 |
* context acceptor. |
|
1383 |
* |
|
1384 |
* @throws GSSException containing the following |
|
1385 |
* major error codes: |
|
1386 |
* {@link GSSException#FAILURE GSSException.FAILURE} |
|
1387 |
*/ |
|
1388 |
public boolean isInitiator() throws GSSException; |
|
1389 |
} |