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