/*
 * 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 org.ietf.jgss.GSSContext, such as querying context-specific attributes. /**
 * 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 type. 


For each supported attribute type, the type for the output are
defined below.

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 n'th bit but the length of the
returned array is less than n, it is regarded as false.
KRB5_GET_SESSION_KEY: the returned object is an instance of Key, which has the following properties: 

   
Algorithm: enctype as a string, where
       enctype is defined in RFC 3961, section 8.
   
Format: "RAW"
   
Encoded form: the raw key bytes, not in any ASN.1 encoding
   
KRB5_GET_AUTHZ_DATA: the returned object is an array of AuthorizationDataEntry, or null if the optional field is missing in the service ticket. 
KRB5_GET_AUTHTIME: the returned object is a String object in the standard KerberosTime format defined in RFC 4120 5.2.3 
 If there is a security manager, an InquireSecContextPermission with the name type.mech must be granted. Otherwise, this could result in a SecurityException.

Example:
     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
         }
     }

Params:
type – the type of the attribute requested
Throws:
GSSException – containing the following major error codes: GSSException.BAD_MECH if the mechanism does not support this method, GSSException.UNAVAILABLE if the type specified is not supported, GSSException.NO_CONTEXT if the security context is invalid, GSSException.FAILURE for other unspecified failures.
SecurityException – if a security manager exists and a proper InquireSecContextPermission is not granted.
See Also:
InquireSecContextPermission
Returns:
the attribute, see the method documentation for details./**
     * 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 initSecContext.
 When this flag is false, delegation will only be tried when the credentials delegation flag is true. 
 When this flag is true but the credentials delegation flag is false, delegation will be only tried if the delegation policy permits delegation. 
 When both this flag and the credentials delegation flag are true, delegation will be always tried. However, if the delegation policy does not permit delegation, the value of getDelegPolicyState will be false, even if delegation is performed successfully. 
 In any case, if the delegation is not successful, the value returned by GSSContext.getCredDelegState() is false, and the value returned by getDelegPolicyState() is also false. 
 Not all mechanisms support delegation policy. Therefore, the application should check to see if the request was honored with the getDelegPolicyState method. When delegation policy is not supported, requestDelegPolicy
should return silently without throwing an exception.

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.
Params:
state – true if the policy should be respected
Throws:
GSSException – containing the following major error codes: GSSException.FAILURE/**
     * 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 requestDelegPolicy. 
Returns:
the delegation policy response/**
     * 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();
}