1 /*
2 * Copyright (c) 2009, 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 @jdk.Supported
36 public interface ExtendedGSSContext extends GSSContext {
37 /**
38 * Return the mechanism-specific attribute associated with {@code type}.
39 * <br><br>
40 * For each supported attribute type, the type for the output are
41 * defined below.
42 * <ol>
43 * <li>{@code KRB5_GET_TKT_FLAGS}:
44 * the returned object is a boolean array for the service ticket flags,
45 * which is long enough to contain all true bits. This means if
46 * the user wants to get the <em>n</em>'th bit but the length of the
47 * returned array is less than <em>n</em>, it is regarded as false.
48 * <li>{@code KRB5_GET_SESSION_KEY}:
49 * the returned object is an instance of {@link java.security.Key},
50 * which has the following properties:
51 * <ul>
52 * <li>Algorithm: enctype as a string, where
53 * enctype is defined in RFC 3961, section 8.
54 * <li>Format: "RAW"
55 * <li>Encoded form: the raw key bytes, not in any ASN.1 encoding
56 * </ul>
57 * <li>{@code KRB5_GET_AUTHZ_DATA}:
58 * the returned object is an array of
59 * {@link com.sun.security.jgss.AuthorizationDataEntry}, or null if the
60 * optional field is missing in the service ticket.
61 * <li>{@code KRB5_GET_AUTHTIME}:
62 * the returned object is a String object in the standard KerberosTime
63 * format defined in RFC 4120 5.2.3
64 * </ol>
65 *
66 * If there is a security manager, an {@link InquireSecContextPermission}
67 * with the name {@code type.mech} must be granted. Otherwise, this could
68 * result in a {@link SecurityException}.<p>
69 *
70 * Example:
71 * <pre>
72 * GSSContext ctxt = m.createContext(...)
73 * // Establishing the context
74 * if (ctxt instanceof ExtendedGSSContext) {
75 * ExtendedGSSContext ex = (ExtendedGSSContext)ctxt;
76 * try {
77 * Key key = (key)ex.inquireSecContext(
78 * InquireType.KRB5_GET_SESSION_KEY);
79 * // read key info
80 * } catch (GSSException gsse) {
81 * // deal with exception
82 * }
83 * }
84 * </pre>
85 * @param type the type of the attribute requested
86 * @return the attribute, see the method documentation for details.
87 * @throws GSSException containing the following
88 * major error codes:
89 * {@link GSSException#BAD_MECH GSSException.BAD_MECH} if the mechanism
90 * does not support this method,
91 * {@link GSSException#UNAVAILABLE GSSException.UNAVAILABLE} if the
92 * type specified is not supported,
93 * {@link GSSException#NO_CONTEXT GSSException.NO_CONTEXT} if the
94 * security context is invalid,
95 * {@link GSSException#FAILURE GSSException.FAILURE} for other
96 * unspecified failures.
97 * @throws SecurityException if a security manager exists and a proper
98 * {@link InquireSecContextPermission} is not granted.
99 * @see InquireSecContextPermission
100 */
101 public Object inquireSecContext(InquireType type)
102 throws GSSException;
103
104 /**
105 * Requests that the delegation policy be respected. When a true value is
106 * requested, the underlying context would use the delegation policy
107 * defined by the environment as a hint to determine whether credentials
108 * delegation should be performed. This request can only be made on the
109 * context initiator's side and it has to be done prior to the first
110 * call to <code>initSecContext</code>.
111 * <p>
112 * When this flag is false, delegation will only be tried when the
113 * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag}
114 * is true.
115 * <p>
116 * When this flag is true but the
117 * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag}
118 * is false, delegation will be only tried if the delegation policy permits
119 * delegation.
120 * <p>
121 * When both this flag and the
122 * {@link GSSContext#requestCredDeleg(boolean) credentials delegation flag}
123 * are true, delegation will be always tried. However, if the delegation
124 * policy does not permit delegation, the value of
125 * {@link #getDelegPolicyState} will be false, even
126 * if delegation is performed successfully.
127 * <p>
128 * In any case, if the delegation is not successful, the value returned
129 * by {@link GSSContext#getCredDelegState()} is false, and the value
130 * returned by {@link #getDelegPolicyState()} is also false.
131 * <p>
132 * Not all mechanisms support delegation policy. Therefore, the
133 * application should check to see if the request was honored with the
134 * {@link #getDelegPolicyState() getDelegPolicyState} method. When
135 * delegation policy is not supported, <code>requestDelegPolicy</code>
136 * should return silently without throwing an exception.
137 * <p>
138 * Note: for the Kerberos 5 mechanism, the delegation policy is expressed
139 * through the OK-AS-DELEGATE flag in the service ticket. When it's true,
140 * the KDC permits delegation to the target server. In a cross-realm
141 * environment, in order for delegation be permitted, all cross-realm TGTs
142 * on the authentication path must also have the OK-AS-DELAGATE flags set.
143 * @param state true if the policy should be respected
144 * @throws GSSException containing the following
145 * major error codes:
146 * {@link GSSException#FAILURE GSSException.FAILURE}
147 */
148 public void requestDelegPolicy(boolean state) throws GSSException;
149
150 /**
151 * Returns the delegation policy response. Called after a security context
152 * is established. This method can be only called on the initiator's side.
153 * See {@link ExtendedGSSContext#requestDelegPolicy}.
154 * @return the delegation policy response
155 */
156 public boolean getDelegPolicyState();
157 }