1 /* 2 * Copyright (c) 2009, 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 package com.sun.security.jgss; 27 28 import org.ietf.jgss.*; 29 import sun.security.jgss.GSSContextImpl; 30 import sun.security.krb5.internal.AuthorizationData; 31 32 /** 33 * The extended GSSContext interface for supporting additional 34 * functionalities not defined by {@code org.ietf.jgss.GSSContext}, 35 * such as querying context-specific attributes. 36 */ 37 public interface ExtendedGSSContext extends GSSContext { 38 39 /** 40 * Return the mechanism-specific attribute associated with {@code type}. 41 * <p> 42 * If there is a security manager, an {@link InquireSecContextPermission} 43 * with the name {@code type.mech} must be granted. Otherwise, this could 44 * result in a {@link SecurityException}. 45 * <p> 46 * Example: 47 * <pre> 48 * GSSContext ctxt = m.createContext(...) 49 * // Establishing the context 50 * if (ctxt instanceof ExtendedGSSContext) { 51 * ExtendedGSSContext ex = (ExtendedGSSContext)ctxt; 52 * try { 53 * Key key = (key)ex.inquireSecContext( 54 * InquireType.KRB5_GET_SESSION_KEY); 55 * // read key info 56 * } catch (GSSException gsse) { 57 * // deal with exception 58 * } 59 * } 60 * </pre> 61 * @param type the type of the attribute requested 62 * @return the attribute, see the method documentation for details. 63 * @throws GSSException containing the following 64 * major error codes: 65 * {@link GSSException#BAD_MECH GSSException.BAD_MECH} if the mechanism 66 * does not support this method, 67 * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE} if the 68 * type specified is not supported, 69 * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT} if the 70 * security context is invalid, 71 * {@link GSSException#FAILURE GSSException.FAILURE} for other 72 * unspecified failures. 73 * @throws SecurityException if a security manager exists and a proper 74 * {@link InquireSecContextPermission} is not granted. 75 * @see InquireSecContextPermission 76 * @see InquireType 77 */ 78 public Object inquireSecContext(InquireType type) 79 throws GSSException; 80 81 /** 82 * Requests that the delegation policy be respected. When a true value is 83 * requested, the underlying context would use the delegation policy 84 * defined by the environment as a hint to determine whether credentials 85 * delegation should be performed. This request can only be made on the 86 * context initiator's side and it has to be done prior to the first 87 * call to <code>initSecContext</code>. 88 * <p> 89 * When this flag is false, delegation will only be tried when the 90 * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag} 91 * is true. 92 * <p> 93 * When this flag is true but the 94 * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag} 95 * is false, delegation will be only tried if the delegation policy permits 96 * delegation. 97 * <p> 98 * When both this flag and the 99 * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag} 100 * are true, delegation will be always tried. However, if the delegation 101 * policy does not permit delegation, the value of 102 * {@link #getDelegPolicyState} will be false, even 103 * if delegation is performed successfully. 104 * <p> 105 * In any case, if the delegation is not successful, the value returned 106 * by {@link GSSContext#getCredDelegState()} is false, and the value 107 * returned by {@link #getDelegPolicyState()} is also false. 108 * <p> 109 * Not all mechanisms support delegation policy. Therefore, the 110 * application should check to see if the request was honored with the 111 * {@link #getDelegPolicyState() getDelegPolicyState} method. When 112 * delegation policy is not supported, <code>requestDelegPolicy</code> 113 * should return silently without throwing an exception. 114 * <p> 115 * Note: for the Kerberos 5 mechanism, the delegation policy is expressed 116 * through the OK-AS-DELEGATE flag in the service ticket. When it's true, 117 * the KDC permits delegation to the target server. In a cross-realm 118 * environment, in order for delegation be permitted, all cross-realm TGTs 119 * on the authentication path must also have the OK-AS-DELAGATE flags set. 120 * @param state true if the policy should be respected 121 * @throws GSSException containing the following 122 * major error codes: 123 * {@link GSSException#FAILURE GSSException.FAILURE} 124 */ 125 public void requestDelegPolicy(boolean state) throws GSSException; 126 127 /** 128 * Returns the delegation policy response. Called after a security context 129 * is established. This method can be only called on the initiator's side. 130 * See {@link ExtendedGSSContext#requestDelegPolicy}. 131 * @return the delegation policy response 132 */ 133 public boolean getDelegPolicyState(); 134 }