2362N/A * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * (C) Copyright IBM Corp. 1999 All Rights Reserved. 0N/A * Copyright 1997 The Open Group Research Institute. All rights reserved. 0N/A * This interface is implemented by a mechanism specific instance of a GSS 0N/A * A GSSContextSpi object can be thought of having 3 states: 0N/A * -before initialization 0N/A * -during initialization with its peer 0N/A * -after it is established 0N/A * The context options can only be requested in state 1. In state 3, 0N/A * the per message operations are available to the callers. The get 0N/A * methods for the context options will return the requested options 0N/A * while in state 1 and 2, and the established values in state 3. 0N/A * Some mechanisms may allow the access to the per-message operations 0N/A * and the context flags before the context is fully established. The 0N/A * isProtReady method is used to indicate that these services are 0N/A * Context establishment tokens are defined in a mechanism independent 0N/A * format in section 3.1 of RFC 2743. The GSS-Framework will add 0N/A * and remove the mechanism independent header portion of this token format 0N/A * depending on whether a token is received or is being sent. The mechanism 0N/A * should only generate or expect to read the inner-context token portion.. 0N/A * On the other hands, tokens used for per-message calls are generated 0N/A * entirely by the mechanism. It is possible that the mechanism chooses to 0N/A * encase inner-level per-message tokens in a header similar to that used 0N/A * for initial tokens, however, this is upto the mechanism to do. The token 0N/A * to/from the per-message calls are opaque to the GSS-Framework. 0N/A * An attempt has been made to allow for reading the peer's tokens from an 0N/A * InputStream and writing tokens for the peer to an OutputStream. This 0N/A * allows applications to pass in streams that are obtained from their network 0N/A * connections and thus minimize the buffer copies that will happen. This 0N/A * is especially important for tokens generated by wrap() which are 0N/A * proportional in size to the length of the application data being 0N/A * wrapped, and are probably also the most frequently used type of tokens. 0N/A * It is anticipated that most applications will want to use wrap() in a 0N/A * fashion where they obtain the application bytes to wrap from a byte[] 0N/A * but want to output the wrap token straight to an 0N/A * OutputStream. Similarly, they will want to use unwrap() where they read 0N/A * the token directly form an InputStream but output it to some byte[] for 0N/A * the application to process. Unfortunately the high level GSS bindings 0N/A * do not contain overloaded forms of wrap() and unwrap() that do just 0N/A * this, however we have accomodated those cases here with the expectation 0N/A * that this will be rolled into the high level bindings sooner or later. 0N/A * @author Mayank Upadhyay 0N/A // The specification for the following methods mirrors the 0N/A // specification of the same methods in the GSSContext interface, as 0N/A // defined in RFC 2853. 0N/A * Initiator context establishment call. This method may be 0N/A * required to be called several times. A CONTINUE_NEEDED return 0N/A * call indicates that more calls are needed after the next token 0N/A * is received from the peer. 0N/A * This method is called by the GSS-Framework when the application 0N/A * calls the initSecContext method on the GSSContext implementation 0N/A * that it has a reference to. 0N/A * with this mechanism level initSecContext. Since the output token 0N/A * from this method is a fixed size, not exeedingly large, and a one 0N/A * time deal, an overloaded form that takes an OutputStream has not 0N/A * been defined. The GSS-Framwork can write the returned byte[] to any 0N/A * application provided OutputStream. Similarly, any application input 0N/A * int he form of byte arrays will be wrapped in an input stream by the 0N/A * GSS-Framework and then passed here. 0N/A * The GSS-Framework will strip off the leading mechanism independent 0N/A * GSS-API header. In other words, only the mechanism specific 0N/A * inner-context token of RFC 2743 section 3.1 will be available on the 0N/A * @param is contains the inner context token portion of the GSS token 0N/A * received from the peer. On the first call to initSecContext, there 0N/A * will be no token hence it will be ignored. 0N/A * @param mechTokenSize the size of the inner context token as read by 0N/A * the GSS-Framework from the mechanism independent GSS-API level 0N/A * @return any inner-context token required to be sent to the peer as 0N/A * part of a GSS token. The mechanism should not add the mechanism 0N/A * independent part of the token. The GSS-Framework will add that on 0N/A * @exception GSSException may be thrown 0N/A * Acceptor's context establishment call. This method may be 0N/A * required to be called several times. A CONTINUE_NEEDED return 0N/A * call indicates that more calls are needed after the next token 0N/A * is received from the peer. 0N/A * This method is called by the GSS-Framework when the application 0N/A * calls the acceptSecContext method on the GSSContext implementation 0N/A * that it has a reference to. 0N/A * All overloaded forms of GSSContext.acceptSecContext() can be handled 0N/A * with this mechanism level acceptSecContext. Since the output token 0N/A * from this method is a fixed size, not exeedingly large, and a one 0N/A * time deal, an overloaded form that takes an OutputStream has not 0N/A * been defined. The GSS-Framwork can write the returned byte[] to any 0N/A * application provided OutputStream. Similarly, any application input 0N/A * int he form of byte arrays will be wrapped in an input stream by the 0N/A * GSS-Framework and then passed here. 0N/A * The GSS-Framework will strip off the leading mechanism independent 0N/A * GSS-API header. In other words, only the mechanism specific 0N/A * inner-context token of RFC 2743 section 3.1 will be available on the 0N/A * @param is contains the inner context token portion of the GSS token 0N/A * received from the peer. 0N/A * @param mechTokenSize the size of the inner context token as read by 0N/A * the GSS-Framework from the mechanism independent GSS-API level 0N/A * @return any inner-context token required to be sent to the peer as 0N/A * part of a GSS token. The mechanism should not add the mechanism 0N/A * independent part of the token. The GSS-Framework will add that on 0N/A * @exception GSSException may be thrown 0N/A * Queries the context for largest data size to accomodate 0N/A * the specified protection and for the token to remain less then 0N/A * @param qop the quality of protection that the context will be 0N/A * @param confReq a flag indicating whether confidentiality will be 0N/A * @param outputSize the maximum size of the output token 0N/A * @return the maximum size for the input message that can be 0N/A * provided to the wrap() method in order to guarantee that these 0N/A * requirements are met. 0N/A * @exception GSSException may be thrown 0N/A * Provides per-message token encapsulation. 0N/A * @param is the user-provided message to be protected 0N/A * @param os the token to be sent to the peer. It includes 0N/A * the message from <i>is</i> with the requested protection. 0N/A * @param msgPro on input it contains the requested qop and 0N/A * confidentiality state, on output, the applied values 0N/A * @exception GSSException may be thrown 0N/A * For apps that want simplicity and don't care about buffer copies. 0N/A * For apps that care about buffer copies but either cannot use streams 0N/A * or want to avoid them for whatever reason. (Say, they are using 0N/A * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext 0N/A public int wrap(byte inBuf[], int inOffset, int len, 0N/A byte[] outBuf, int outOffset, 0N/A MessageProp msgProp) throws GSSException; 0N/A * For apps that want to read from a specific application provided 0N/A * buffer but want to write directly to the network stream. 0N/A * Can be achieved by converting the input buffer to a 0N/A * ByteInputStream. Provided to keep the API consistent 0N/A * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext 0N/A public void wrap(byte inBuf[], int offset, int len, 0N/A OutputStream os, MessageProp msgProp) 0N/A throws GSSException; 0N/A * Retrieves the message token previously encapsulated in the wrap 0N/A * @param is the token from the peer 0N/A * @param os unprotected message data 0N/A * @param msgProp will contain the applied qop and confidentiality 0N/A * of the input token and any informatory status values 0N/A * @exception GSSException may be thrown 0N/A * For apps that want simplicity and dont care about buffer copies. 0N/A * For apps that care about buffer copies but either cannot use streams 0N/A * or want to avoid them for whatever reason. (Say, they are using 0N/A * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext 0N/A public int unwrap(byte inBuf[], int inOffset, int len, 0N/A byte[] outBuf, int outOffset, 0N/A MessageProp msgProp) throws GSSException; 0N/A * For apps that care about buffer copies and want to read 0N/A * straight from the network, but also want the output in a specific 0N/A * application provided buffer, say to reduce buffer allocation or 0N/A * NOTE: This method is not defined in public class org.ietf.jgss.GSSContext 0N/A public int unwrap(InputStream is, 0N/A byte[] outBuf, int outOffset, 0N/A MessageProp msgProp) throws GSSException; 0N/A * Applies per-message integrity services. 0N/A * @param is the user-provided message 0N/A * @param os the token to be sent to the peer along with the 0N/A * message token. The message token <b>is not</b> encapsulated. 0N/A * @param msgProp on input the desired QOP and output the applied QOP 0N/A * @exception GSSException 0N/A * Checks the integrity of the supplied tokens. 0N/A * This token was previously generated by getMIC. 0N/A * @param is token generated by getMIC 0N/A * @param msgStr the message to check integrity for 0N/A * @param msgProp will contain the applied QOP and confidentiality 0N/A * states of the token as well as any informatory status codes 0N/A * @exception GSSException may be thrown 0N/A * Produces a token representing this context. After this call 0N/A * the context will no longer be usable until an import is 0N/A * performed on the returned token. 0N/A * @return exported context token 0N/A * @exception GSSException may be thrown 0N/A * Releases context resources and terminates the 0N/A * context between 2 peer. 0N/A * @exception GSSException may be thrown 1535N/A * Return the mechanism-specific attribute associated with (@code type}. 1535N/A * @param type the type of the attribute requested 1535N/A * @throws GSSException see {@link ExtendedGSSContext#inquireSecContext}