View Javadoc
1   /*
2    * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  /*
27   *
28   *  (C) Copyright IBM Corp. 1999 All Rights Reserved.
29   *  Copyright 1997 The Open Group Research Institute.  All rights reserved.
30   */
31  package sun.security.jgss.spi;
32  
33  import org.ietf.jgss.*;
34  import java.io.InputStream;
35  import java.io.OutputStream;
36  import java.security.Provider;
37  import com.sun.security.jgss.*;
38  
39  /**
40   * This interface is implemented by a mechanism specific instance of a GSS
41   * security context.
42   * A GSSContextSpi object can be thought of having 3 states:
43   *    -before initialization
44   *    -during initialization with its peer
45   *    -after it is established
46   * <p>
47   * The context options can only be requested in state 1. In state 3,
48   * the per message operations are available to the callers. The get
49   * methods for the context options will return the requested options
50   * while in state 1 and 2, and the established values in state 3.
51   * Some mechanisms may allow the access to the per-message operations
52   * and the context flags before the context is fully established. The
53   * isProtReady method is used to indicate that these services are
54   * available.
55   *<p>
56   * <strong>
57   * Context establishment tokens are defined in a mechanism independent
58   * format in section 3.1 of RFC 2743. The GSS-Framework will add
59   * and remove the mechanism independent header portion of this token format
60   * depending on whether a token is received or is being sent. The mechanism
61   * should only generate or expect to read the inner-context token portion..
62   * <p>
63   * On the other hands, tokens used for per-message calls are generated
64   * entirely by the mechanism. It is possible that the mechanism chooses to
65   * encase inner-level per-message tokens in a header similar to that used
66   * for initial tokens, however, this is upto the mechanism to do. The token
67   * to/from the per-message calls are opaque to the GSS-Framework.
68   * </strong>
69   * <p>
70   * An attempt has been made to allow for reading the peer's tokens from an
71   * InputStream and writing tokens for the peer to an OutputStream. This
72   * allows applications to pass in streams that are obtained from their network
73   * connections and thus minimize the buffer copies that will happen. This
74   * is especially important for tokens generated by wrap() which are
75   * proportional in size to the length of the application data being
76   * wrapped, and are probably also the most frequently used type of tokens.
77   * <p>
78   * It is anticipated that most applications will want to use wrap() in a
79   * fashion where they obtain the application bytes to wrap from a byte[]
80   * but want to output the wrap token straight to an
81   * OutputStream. Similarly, they will want to use unwrap() where they read
82   * the token directly form an InputStream but output it to some byte[] for
83   * the application to process. Unfortunately the high level GSS bindings
84   * do not contain overloaded forms of wrap() and unwrap() that do just
85   * this, however we have accomodated those cases here with the expectation
86   * that this will be rolled into the high level bindings sooner or later.
87   *
88   * @author Mayank Upadhyay
89   */
90  
91  public interface GSSContextSpi {
92  
93      public Provider getProvider();
94  
95      // The specification for the following methods mirrors the
96      // specification of the same methods in the GSSContext interface, as
97      // defined in RFC 2853.
98  
99      public void requestLifetime(int lifetime) throws GSSException;
100 
101     public void requestMutualAuth(boolean state) throws GSSException;
102 
103     public void requestReplayDet(boolean state) throws GSSException;
104 
105     public void requestSequenceDet(boolean state) throws GSSException;
106 
107     public void requestCredDeleg(boolean state) throws GSSException;
108 
109     public void requestAnonymity(boolean state) throws GSSException;
110 
111     public void requestConf(boolean state) throws GSSException;
112 
113     public void requestInteg(boolean state) throws GSSException;
114 
115     public void requestDelegPolicy(boolean state) throws GSSException;
116 
117     public void setChannelBinding(ChannelBinding cb) throws GSSException;
118 
119     public boolean getCredDelegState();
120 
121     public boolean getMutualAuthState();
122 
123     public boolean getReplayDetState();
124 
125     public boolean getSequenceDetState();
126 
127     public boolean getAnonymityState();
128 
129     public boolean getDelegPolicyState();
130 
131     public boolean isTransferable() throws GSSException;
132 
133     public boolean isProtReady();
134 
135     public boolean isInitiator();
136 
137     public boolean getConfState();
138 
139     public boolean getIntegState();
140 
141     public int getLifetime();
142 
143     public boolean isEstablished();
144 
145     public GSSNameSpi getSrcName() throws GSSException;
146 
147     public GSSNameSpi getTargName() throws GSSException;
148 
149     public Oid getMech() throws GSSException;
150 
151     public GSSCredentialSpi getDelegCred() throws GSSException;
152 
153     /**
154      * Initiator context establishment call. This method may be
155      * required to be called several times. A CONTINUE_NEEDED return
156      * call indicates that more calls are needed after the next token
157      * is received from the peer.
158      * <p>
159      * This method is called by the GSS-Framework when the application
160      * calls the initSecContext method on the GSSContext implementation
161      * that it has a reference to.
162      * <p>
163      * All overloaded forms of GSSContext.initSecContext() can be handled
164      * with this mechanism level initSecContext. Since the output token
165      * from this method is a fixed size, not exeedingly large, and a one
166      * time deal, an overloaded form that takes an OutputStream has not
167      * been defined. The GSS-Framwork can write the returned byte[] to any
168      * application provided OutputStream. Similarly, any application input
169      * int he form of byte arrays will be wrapped in an input stream by the
170      * GSS-Framework and then passed here.
171      * <p>
172      * <strong>
173      * The GSS-Framework will strip off the leading mechanism independent
174      * GSS-API header. In other words, only the mechanism specific
175      * inner-context token of RFC 2743 section 3.1 will be available on the
176      * InputStream.
177      * </strong>
178      *
179      * @param is contains the inner context token portion of the GSS token
180      * received from the peer. On the first call to initSecContext, there
181      * will be no token hence it will be ignored.
182      * @param mechTokenSize the size of the inner context token as read by
183      * the GSS-Framework from the mechanism independent GSS-API level
184      * header.
185      * @return any inner-context token required to be sent to the peer as
186      * part of a GSS token. The mechanism should not add the mechanism
187      * independent part of the token. The GSS-Framework will add that on
188      * the way out.
189      * @exception GSSException may be thrown
190      */
191     public byte[] initSecContext(InputStream is, int mechTokenSize)
192                         throws GSSException;
193 
194     /**
195      * Acceptor's context establishment call. This method may be
196      * required to be called several times. A CONTINUE_NEEDED return
197      * call indicates that more calls are needed after the next token
198      * is received from the peer.
199      * <p>
200      * This method is called by the GSS-Framework when the application
201      * calls the acceptSecContext method on the GSSContext implementation
202      * that it has a reference to.
203      * <p>
204      * All overloaded forms of GSSContext.acceptSecContext() can be handled
205      * with this mechanism level acceptSecContext. Since the output token
206      * from this method is a fixed size, not exeedingly large, and a one
207      * time deal, an overloaded form that takes an OutputStream has not
208      * been defined. The GSS-Framwork can write the returned byte[] to any
209      * application provided OutputStream. Similarly, any application input
210      * int he form of byte arrays will be wrapped in an input stream by the
211      * GSS-Framework and then passed here.
212      * <p>
213      * <strong>
214      * The GSS-Framework will strip off the leading mechanism independent
215      * GSS-API header. In other words, only the mechanism specific
216      * inner-context token of RFC 2743 section 3.1 will be available on the
217      * InputStream.
218      * </strong>
219      *
220      * @param is contains the inner context token portion of the GSS token
221      * received from the peer.
222      * @param mechTokenSize the size of the inner context token as read by
223      * the GSS-Framework from the mechanism independent GSS-API level
224      * header.
225      * @return any inner-context token required to be sent to the peer as
226      * part of a GSS token. The mechanism should not add the mechanism
227      * independent part of the token. The GSS-Framework will add that on
228      * the way out.
229      * @exception GSSException may be thrown
230      */
231     public byte[] acceptSecContext(InputStream is, int mechTokenSize)
232                         throws GSSException;
233 
234     /**
235      * Queries the context for largest data size to accommodate
236      * the specified protection and for the token to remain less then
237      * maxTokSize.
238      *
239      * @param qop the quality of protection that the context will be
240      *    asked to provide.
241      * @param confReq a flag indicating whether confidentiality will be
242      *    requested or not
243      * @param outputSize the maximum size of the output token
244      * @return the maximum size for the input message that can be
245      *    provided to the wrap() method in order to guarantee that these
246      *    requirements are met.
247      * @exception GSSException may be thrown
248      */
249     public int getWrapSizeLimit(int qop, boolean confReq, int maxTokSize)
250                         throws GSSException;
251 
252     /**
253      * Provides per-message token encapsulation.
254      *
255      * @param is the user-provided message to be protected
256      * @param os the token to be sent to the peer. It includes
257      *    the message from <i>is</i> with the requested protection.
258      * @param msgPro on input it contains the requested qop and
259      *    confidentiality state, on output, the applied values
260      * @exception GSSException may be thrown
261      * @see unwrap
262      */
263     public void wrap(InputStream is, OutputStream os, MessageProp msgProp)
264         throws GSSException;
265 
266     /**
267      * For apps that want simplicity and don't care about buffer copies.
268      */
269     public byte[] wrap(byte inBuf[], int offset, int len,
270                        MessageProp msgProp) throws GSSException;
271 
272     /**
273      * For apps that care about buffer copies but either cannot use streams
274      * or want to avoid them for whatever reason. (Say, they are using
275      * block ciphers.)
276      *
277      * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
278      *
279     public int wrap(byte inBuf[], int inOffset, int len,
280                     byte[] outBuf, int outOffset,
281                     MessageProp msgProp) throws GSSException;
282 
283     */
284 
285     /**
286      * For apps that want to read from a specific application provided
287      * buffer but want to write directly to the network stream.
288      */
289     /*
290      * Can be achieved by converting the input buffer to a
291      * ByteInputStream. Provided to keep the API consistent
292      * with unwrap.
293      *
294      * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
295      *
296     public void wrap(byte inBuf[], int offset, int len,
297                      OutputStream os, MessageProp msgProp)
298         throws GSSException;
299     */
300 
301     /**
302      * Retrieves the message token previously encapsulated in the wrap
303      * call.
304      *
305      * @param is the token from the peer
306      * @param os unprotected message data
307      * @param msgProp will contain the applied qop and confidentiality
308      *    of the input token and any informatory status values
309      * @exception GSSException may be thrown
310      * @see wrap
311      */
312     public void unwrap(InputStream is, OutputStream os,
313                         MessageProp msgProp) throws GSSException;
314 
315     /**
316      * For apps that want simplicity and don't care about buffer copies.
317      */
318     public byte[] unwrap(byte inBuf[], int offset, int len,
319                          MessageProp msgProp) throws GSSException;
320 
321     /**
322      * For apps that care about buffer copies but either cannot use streams
323      * or want to avoid them for whatever reason. (Say, they are using
324      * block ciphers.)
325      *
326      * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
327      *
328     public int unwrap(byte inBuf[], int inOffset, int len,
329                       byte[] outBuf, int outOffset,
330                       MessageProp msgProp) throws GSSException;
331 
332     */
333 
334     /**
335      * For apps that care about buffer copies and want to read
336      * straight from the network, but also want the output in a specific
337      * application provided buffer, say to reduce buffer allocation or
338      * subsequent copy.
339      *
340      * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext
341      *
342     public int unwrap(InputStream is,
343                        byte[] outBuf, int outOffset,
344                        MessageProp msgProp) throws GSSException;
345     */
346 
347     /**
348      * Applies per-message integrity services.
349      *
350      * @param is the user-provided message
351      * @param os the token to be sent to the peer along with the
352      *    message token. The message token <b>is not</b> encapsulated.
353      * @param msgProp on input the desired QOP and output the applied QOP
354      * @exception GSSException
355      */
356     public void getMIC(InputStream is, OutputStream os,
357                         MessageProp msgProp)
358                 throws GSSException;
359 
360     public byte[] getMIC(byte []inMsg, int offset, int len,
361                          MessageProp msgProp) throws GSSException;
362 
363     /**
364      * Checks the integrity of the supplied tokens.
365      * This token was previously generated by getMIC.
366      *
367      * @param is token generated by getMIC
368      * @param msgStr the message to check integrity for
369      * @param msgProp will contain the applied QOP and confidentiality
370      *    states of the token as well as any informatory status codes
371      * @exception GSSException may be thrown
372      */
373     public void verifyMIC(InputStream is, InputStream msgStr,
374                            MessageProp mProp) throws GSSException;
375 
376     public void verifyMIC(byte []inTok, int tokOffset, int tokLen,
377                           byte[] inMsg, int msgOffset, int msgLen,
378                           MessageProp msgProp) throws GSSException;
379 
380     /**
381      * Produces a token representing this context. After this call
382      * the context will no longer be usable until an import is
383      * performed on the returned token.
384      *
385      * @return exported context token
386      * @exception GSSException may be thrown
387      */
388     public byte[] export() throws GSSException;
389 
390     /**
391      * Releases context resources and terminates the
392      * context between 2 peer.
393      *
394      * @exception GSSException may be thrown
395      */
396     public void dispose() throws GSSException;
397 
398     /**
399      * Return the mechanism-specific attribute associated with (@code type}.
400      *
401      * @param type the type of the attribute requested
402      * @return the attribute
403      * @throws GSSException see {@link ExtendedGSSContext#inquireSecContext}
404      * for details
405      */
406     public Object inquireSecContext(InquireType type)
407             throws GSSException;
408 }