| /* |
| * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.security.jgss; |
| |
| import org.ietf.jgss.*; |
| |
| /** |
| * The extended GSSContext interface for supporting additional |
| * functionalities not defined by {@code org.ietf.jgss.GSSContext}, |
| * such as querying context-specific attributes. |
| */ |
| public interface ExtendedGSSContext extends GSSContext { |
| /** |
| * Return the mechanism-specific attribute associated with {@code type}. |
| * <br><br> |
| * For each supported attribute type, the type for the output are |
| * defined below. |
| * <ol> |
| * <li>{@code KRB5_GET_TKT_FLAGS}: |
| * the returned object is a boolean array for the service ticket flags, |
| * which is long enough to contain all true bits. This means if |
| * the user wants to get the <em>n</em>'th bit but the length of the |
| * returned array is less than <em>n</em>, it is regarded as false. |
| * <li>{@code KRB5_GET_SESSION_KEY}: |
| * the returned object is an instance of {@link java.security.Key}, |
| * which has the following properties: |
| * <ul> |
| * <li>Algorithm: enctype as a string, where |
| * enctype is defined in RFC 3961, section 8. |
| * <li>Format: "RAW" |
| * <li>Encoded form: the raw key bytes, not in any ASN.1 encoding |
| * </ul> |
| * <li>{@code KRB5_GET_AUTHZ_DATA}: |
| * the returned object is an array of |
| * {@link com.sun.security.jgss.AuthorizationDataEntry}, or null if the |
| * optional field is missing in the service ticket. |
| * <li>{@code KRB5_GET_AUTHTIME}: |
| * the returned object is a String object in the standard KerberosTime |
| * format defined in RFC 4120 5.2.3 |
| * </ol> |
| * |
| * If there is a security manager, an {@link InquireSecContextPermission} |
| * with the name {@code type.mech} must be granted. Otherwise, this could |
| * result in a {@link SecurityException}.<p> |
| * |
| * Example: |
| * <pre> |
| * GSSContext ctxt = m.createContext(...) |
| * // Establishing the context |
| * if (ctxt instanceof ExtendedGSSContext) { |
| * ExtendedGSSContext ex = (ExtendedGSSContext)ctxt; |
| * try { |
| * Key key = (key)ex.inquireSecContext( |
| * InquireType.KRB5_GET_SESSION_KEY); |
| * // read key info |
| * } catch (GSSException gsse) { |
| * // deal with exception |
| * } |
| * } |
| * </pre> |
| * @param type the type of the attribute requested |
| * @return the attribute, see the method documentation for details. |
| * @throws GSSException containing the following |
| * major error codes: |
| * {@link GSSException#BAD_MECH GSSException.BAD_MECH} if the mechanism |
| * does not support this method, |
| * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE} if the |
| * type specified is not supported, |
| * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT} if the |
| * security context is invalid, |
| * {@link GSSException#FAILURE GSSException.FAILURE} for other |
| * unspecified failures. |
| * @throws SecurityException if a security manager exists and a proper |
| * {@link InquireSecContextPermission} is not granted. |
| * @see InquireSecContextPermission |
| */ |
| public Object inquireSecContext(InquireType type) |
| throws GSSException; |
| |
| /** |
| * Requests that the delegation policy be respected. When a true value is |
| * requested, the underlying context would use the delegation policy |
| * defined by the environment as a hint to determine whether credentials |
| * delegation should be performed. This request can only be made on the |
| * context initiator's side and it has to be done prior to the first |
| * call to <code>initSecContext</code>. |
| * <p> |
| * When this flag is false, delegation will only be tried when the |
| * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag} |
| * is true. |
| * <p> |
| * When this flag is true but the |
| * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag} |
| * is false, delegation will be only tried if the delegation policy permits |
| * delegation. |
| * <p> |
| * When both this flag and the |
| * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag} |
| * are true, delegation will be always tried. However, if the delegation |
| * policy does not permit delegation, the value of |
| * {@link #getDelegPolicyState} will be false, even |
| * if delegation is performed successfully. |
| * <p> |
| * In any case, if the delegation is not successful, the value returned |
| * by {@link GSSContext#getCredDelegState()} is false, and the value |
| * returned by {@link #getDelegPolicyState()} is also false. |
| * <p> |
| * Not all mechanisms support delegation policy. Therefore, the |
| * application should check to see if the request was honored with the |
| * {@link #getDelegPolicyState() getDelegPolicyState} method. When |
| * delegation policy is not supported, <code>requestDelegPolicy</code> |
| * should return silently without throwing an exception. |
| * <p> |
| * Note: for the Kerberos 5 mechanism, the delegation policy is expressed |
| * through the OK-AS-DELEGATE flag in the service ticket. When it's true, |
| * the KDC permits delegation to the target server. In a cross-realm |
| * environment, in order for delegation be permitted, all cross-realm TGTs |
| * on the authentication path must also have the OK-AS-DELAGATE flags set. |
| * @param state true if the policy should be respected |
| * @throws GSSException containing the following |
| * major error codes: |
| * {@link GSSException#FAILURE GSSException.FAILURE} |
| */ |
| public void requestDelegPolicy(boolean state) throws GSSException; |
| |
| /** |
| * Returns the delegation policy response. Called after a security context |
| * is established. This method can be only called on the initiator's side. |
| * See {@link ExtendedGSSContext#requestDelegPolicy}. |
| * @return the delegation policy response |
| */ |
| public boolean getDelegPolicyState(); |
| } |
