/* * 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();}