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