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