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