001: /*
002: * Portions Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: /*
027: * ===========================================================================
028: * IBM Confidential
029: * OCO Source Materials
030: * Licensed Materials - Property of IBM
031: *
032: * (C) Copyright IBM Corp. 1999 All Rights Reserved.
033: *
034: * The source code for this program is not published or otherwise divested of
035: * its trade secrets, irrespective of what has been deposited with the U.S.
036: * Copyright Office.
037: *
038: * Copyright 1997 The Open Group Research Institute. All rights reserved.
039: * ===========================================================================
040: *
041: */
042:
043: package sun.security.jgss.spi;
044:
045: import org.ietf.jgss.*;
046: import java.io.InputStream;
047: import java.io.OutputStream;
048: import java.security.Provider;
049:
050: /**
051: * This interface is implemented by a mechanism specific instance of a GSS
052: * security context.
053: * A GSSContextSpi object can be thought of having 3 states:
054: * -before initialization
055: * -during initialization with its peer
056: * -after it is established
057: * <p>
058: * The context options can only be requested in state 1. In state 3,
059: * the per message operations are available to the callers. The get
060: * methods for the context options will return the requested options
061: * while in state 1 and 2, and the established values in state 3.
062: * Some mechanisms may allow the access to the per-message operations
063: * and the context flags before the context is fully established. The
064: * isProtReady method is used to indicate that these services are
065: * available.
066: *<p>
067: * <strong>
068: * Context establishment tokens are defined in a mechanism independent
069: * format in section 3.1 of RFC 2743. The GSS-Framework will add
070: * and remove the mechanism independent header portion of this token format
071: * depending on whether a token is received or is being sent. The mechanism
072: * should only generate or expect to read the inner-context token portion..
073: * <p>
074: * On the other hands, tokens used for per-message calls are generated
075: * entirely by the mechanism. It is possible that the mechanism chooses to
076: * encase inner-level per-message tokens in a header similar to that used
077: * for initial tokens, however, this is upto the mechanism to do. The token
078: * to/from the per-message calls are opaque to the GSS-Framework.
079: * </strong>
080: * <p>
081: * An attempt has been made to allow for reading the peer's tokens from an
082: * InputStream and writing tokens for the peer to an OutputStream. This
083: * allows applications to pass in streams that are obtained from their network
084: * connections and thus minimize the buffer copies that will happen. This
085: * is especially important for tokens generated by wrap() which are
086: * proportional in size to the length of the application data being
087: * wrapped, and are probably also the most frequently used type of tokens.
088: * <p>
089: * It is anticipated that most applications will want to use wrap() in a
090: * fashion where they obtain the application bytes to wrap from a byte[]
091: * but want to output the wrap token straight to an
092: * OutputStream. Similarly, they will want to use unwrap() where they read
093: * the token directly form an InputStream but output it to some byte[] for
094: * the application to process. Unfortunately the high level GSS bindings
095: * do not contain overloaded forms of wrap() and unwrap() that do just
096: * this, however we have accomodated those cases here with the expectation
097: * that this will be rolled into the high level bindings sooner or later.
098: *
099: * @author Mayank Upadhyay
100: * @version 1.15, 05/05/07
101: */
102:
103: public interface GSSContextSpi {
104:
105: public Provider getProvider();
106:
107: // The specification for the following methods mirrors the
108: // specification of the same methods in the GSSContext interface, as
109: // defined in RFC 2853.
110:
111: public void requestLifetime(int lifetime) throws GSSException;
112:
113: public void requestMutualAuth(boolean state) throws GSSException;
114:
115: public void requestReplayDet(boolean state) throws GSSException;
116:
117: public void requestSequenceDet(boolean state) throws GSSException;
118:
119: public void requestCredDeleg(boolean state) throws GSSException;
120:
121: public void requestAnonymity(boolean state) throws GSSException;
122:
123: public void requestConf(boolean state) throws GSSException;
124:
125: public void requestInteg(boolean state) throws GSSException;
126:
127: public void setChannelBinding(ChannelBinding cb)
128: throws GSSException;
129:
130: public boolean getCredDelegState();
131:
132: public boolean getMutualAuthState();
133:
134: public boolean getReplayDetState();
135:
136: public boolean getSequenceDetState();
137:
138: public boolean getAnonymityState();
139:
140: public boolean isTransferable() throws GSSException;
141:
142: public boolean isProtReady();
143:
144: public boolean isInitiator();
145:
146: public boolean getConfState();
147:
148: public boolean getIntegState();
149:
150: public int getLifetime();
151:
152: public boolean isEstablished();
153:
154: public GSSNameSpi getSrcName() throws GSSException;
155:
156: public GSSNameSpi getTargName() throws GSSException;
157:
158: public Oid getMech() throws GSSException;
159:
160: public GSSCredentialSpi getDelegCred() throws GSSException;
161:
162: /**
163: * Initiator context establishment call. This method may be
164: * required to be called several times. A CONTINUE_NEEDED return
165: * call indicates that more calls are needed after the next token
166: * is received from the peer.
167: * <p>
168: * This method is called by the GSS-Framework when the application
169: * calls the initSecContext method on the GSSContext implementation
170: * that it has a reference to.
171: * <p>
172: * All overloaded forms of GSSContext.initSecContext() can be handled
173: * with this mechanism level initSecContext. Since the output token
174: * from this method is a fixed size, not exeedingly large, and a one
175: * time deal, an overloaded form that takes an OutputStream has not
176: * been defined. The GSS-Framwork can write the returned byte[] to any
177: * application provided OutputStream. Similarly, any application input
178: * int he form of byte arrays will be wrapped in an input stream by the
179: * GSS-Framework and then passed here.
180: * <p>
181: * <strong>
182: * The GSS-Framework will strip off the leading mechanism independent
183: * GSS-API header. In other words, only the mechanism specific
184: * inner-context token of RFC 2743 section 3.1 will be available on the
185: * InputStream.
186: * </strong>
187: *
188: * @param is contains the inner context token portion of the GSS token
189: * received from the peer. On the first call to initSecContext, there
190: * will be no token hence it will be ignored.
191: * @param mechTokenSize the size of the inner context token as read by
192: * the GSS-Framework from the mechanism independent GSS-API level
193: * header.
194: * @return any inner-context token required to be sent to the peer as
195: * part of a GSS token. The mechanism should not add the mechanism
196: * independent part of the token. The GSS-Framework will add that on
197: * the way out.
198: * @exception GSSException may be thrown
199: */
200: public byte[] initSecContext(InputStream is, int mechTokenSize)
201: throws GSSException;
202:
203: /**
204: * Acceptor's context establishment call. This method may be
205: * required to be called several times. A CONTINUE_NEEDED return
206: * call indicates that more calls are needed after the next token
207: * is received from the peer.
208: * <p>
209: * This method is called by the GSS-Framework when the application
210: * calls the acceptSecContext method on the GSSContext implementation
211: * that it has a reference to.
212: * <p>
213: * All overloaded forms of GSSContext.acceptSecContext() can be handled
214: * with this mechanism level acceptSecContext. Since the output token
215: * from this method is a fixed size, not exeedingly large, and a one
216: * time deal, an overloaded form that takes an OutputStream has not
217: * been defined. The GSS-Framwork can write the returned byte[] to any
218: * application provided OutputStream. Similarly, any application input
219: * int he form of byte arrays will be wrapped in an input stream by the
220: * GSS-Framework and then passed here.
221: * <p>
222: * <strong>
223: * The GSS-Framework will strip off the leading mechanism independent
224: * GSS-API header. In other words, only the mechanism specific
225: * inner-context token of RFC 2743 section 3.1 will be available on the
226: * InputStream.
227: * </strong>
228: *
229: * @param is contains the inner context token portion of the GSS token
230: * received from the peer.
231: * @param mechTokenSize the size of the inner context token as read by
232: * the GSS-Framework from the mechanism independent GSS-API level
233: * header.
234: * @return any inner-context token required to be sent to the peer as
235: * part of a GSS token. The mechanism should not add the mechanism
236: * independent part of the token. The GSS-Framework will add that on
237: * the way out.
238: * @exception GSSException may be thrown
239: */
240: public byte[] acceptSecContext(InputStream is, int mechTokenSize)
241: throws GSSException;
242:
243: /**
244: * Queries the context for largest data size to accomodate
245: * the specified protection and for the token to remain less then
246: * maxTokSize.
247: *
248: * @param qop the quality of protection that the context will be
249: * asked to provide.
250: * @param confReq a flag indicating whether confidentiality will be
251: * requested or not
252: * @param outputSize the maximum size of the output token
253: * @return the maximum size for the input message that can be
254: * provided to the wrap() method in order to guarantee that these
255: * requirements are met.
256: * @exception GSSException may be thrown
257: */
258: public int getWrapSizeLimit(int qop, boolean confReq, int maxTokSize)
259: throws GSSException;
260:
261: /**
262: * Provides per-message token encapsulation.
263: *
264: * @param is the user-provided message to be protected
265: * @param os the token to be sent to the peer. It includes
266: * the message from <i>is</i> with the requested protection.
267: * @param msgPro on input it contains the requested qop and
268: * confidentiality state, on output, the applied values
269: * @exception GSSException may be thrown
270: * @see MessageInfo
271: * @see unwrap
272: */
273: public void wrap(InputStream is, OutputStream os,
274: MessageProp msgProp) throws GSSException;
275:
276: /**
277: * For apps that want simplicity and don't care about buffer copies.
278: */
279: public byte[] wrap(byte inBuf[], int offset, int len,
280: MessageProp msgProp) throws GSSException;
281:
282: /**
283: * For apps that care about buffer copies but either cannot use streams
284: * or want to avoid them for whatever reason. (Say, they are using
285: * block ciphers.)
286: *
287: * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
288: *
289: public int wrap(byte inBuf[], int inOffset, int len,
290: byte[] outBuf, int outOffset,
291: MessageProp msgProp) throws GSSException;
292:
293: */
294:
295: /**
296: * For apps that want to read from a specific application provided
297: * buffer but want to write directly to the network stream.
298: */
299: /*
300: * Can be achieved by converting the input buffer to a
301: * ByteInputStream. Provided to keep the API consistent
302: * with unwrap.
303: *
304: * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
305: *
306: public void wrap(byte inBuf[], int offset, int len,
307: OutputStream os, MessageProp msgProp)
308: throws GSSException;
309: */
310:
311: /**
312: * Retrieves the message token previously encapsulated in the wrap
313: * call.
314: *
315: * @param is the token from the peer
316: * @param os unprotected message data
317: * @param msgProp will contain the applied qop and confidentiality
318: * of the input token and any informatory status values
319: * @exception GSSException may be thrown
320: * @see MessageInfo
321: * @see wrap
322: */
323: public void unwrap(InputStream is, OutputStream os,
324: MessageProp msgProp) throws GSSException;
325:
326: /**
327: * For apps that want simplicity and dont care about buffer copies.
328: */
329: public byte[] unwrap(byte inBuf[], int offset, int len,
330: MessageProp msgProp) throws GSSException;
331:
332: /**
333: * For apps that care about buffer copies but either cannot use streams
334: * or want to avoid them for whatever reason. (Say, they are using
335: * block ciphers.)
336: *
337: * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
338: *
339: public int unwrap(byte inBuf[], int inOffset, int len,
340: byte[] outBuf, int outOffset,
341: MessageProp msgProp) throws GSSException;
342:
343: */
344:
345: /**
346: * For apps that care about buffer copies and want to read
347: * straight from the network, but also want the output in a specific
348: * application provided buffer, say to reduce buffer allocation or
349: * subsequent copy.
350: *
351: * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
352: *
353: public int unwrap(InputStream is,
354: byte[] outBuf, int outOffset,
355: MessageProp msgProp) throws GSSException;
356: */
357:
358: /**
359: * Applies per-message integrity services.
360: *
361: * @param is the user-provided message
362: * @param os the token to be sent to the peer along with the
363: * message token. The message token <b>is not</b> encapsulated.
364: * @param msgProp on input the desired QOP and output the applied QOP
365: * @exception GSSException
366: */
367: public void getMIC(InputStream is, OutputStream os,
368: MessageProp msgProp) throws GSSException;
369:
370: public byte[] getMIC(byte[] inMsg, int offset, int len,
371: MessageProp msgProp) throws GSSException;
372:
373: /**
374: * Checks the integrity of the supplied tokens.
375: * This token was previously generated by getMIC.
376: *
377: * @param is token generated by getMIC
378: * @param msgStr the message to check integrity for
379: * @param msgProp will contain the applied QOP and confidentiality
380: * states of the token as well as any informatory status codes
381: * @exception GSSException may be thrown
382: */
383: public void verifyMIC(InputStream is, InputStream msgStr,
384: MessageProp mProp) throws GSSException;
385:
386: public void verifyMIC(byte[] inTok, int tokOffset, int tokLen,
387: byte[] inMsg, int msgOffset, int msgLen, MessageProp msgProp)
388: throws GSSException;
389:
390: /**
391: * Produces a token representing this context. After this call
392: * the context will no longer be usable until an import is
393: * performed on the returned token.
394: *
395: * @return exported context token
396: * @exception GSSException may be thrown
397: */
398: public byte[] export() throws GSSException;
399:
400: /**
401: * Releases context resources and terminates the
402: * context between 2 peer.
403: *
404: * @exception GSSException may be thrown
405: */
406: public void dispose() throws GSSException;
407: }
|