Debian Codegraph @

ssl-proxies/src/main/java/org/gridforum/jgss/ExtendedGSSContext.java

raw
1 /*
2 * Copyright 1999-2010 University of Chicago
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
5 * compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License is
10 * distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
11 * express or implied.
12 *
13 * See the License for the specific language governing permissions and limitations under the License.
14 */
15 package org.gridforum.jgss;
16
17 import org.ietf.jgss.GSSCredential;
18 import org.ietf.jgss.GSSException;
19 import org.ietf.jgss.GSSContext;
20 import org.ietf.jgss.Oid;
21
22 /**
23 * Defines Java API for setting and getting context options and delegation extensions as defined in the
24 * <a href="http://www.gridforum.org/security/gsi/draft-ggf-gss-extensions-08.pdf">GSS-API Extensions document</a>.
25 * Some of the functions might not specify all the parameters as in the document.
26 * <BR><BR>Notes:
27 * <UL>
28 * <LI>Extensions are not supported in initDelegation and acceptDelegation</LI>
29 * </UL>
30 * <BR>
31 * Here is a sample code showing how the delegation API might be used:
32 * <pre>
33 * ExtendedGSSContext client = ....
34 * ExtendedGSSContext server = ....
35 *
36 * byte [] input = new byte[0];
37 * byte [] output = null;
38 * do {
39 * output = client.initDelegation(null, null, 0, input, 0, input.length);
40 * input = server.acceptDelegation(0, output, 0, output.length);
41 * } while (!client.isDelegationFinished());
42 *
43 * GSSCredential cred = server.getDelegatedCredential();
44 * ...
45 * </pre>
46 * Because delegation can be performed multiple times on the same contexts, the <code>do { ... } while ();</code>
47 * block should be used to properly reset the delegation state (The state of <code>isDelegationFinished</code>
48 * is reset on the initial call to <code>initDelegation</code> or <code>acceptDelegation</code>.
49 */
50 public interface ExtendedGSSContext extends GSSContext {
51
52 /**
53 * Sets a context option. It can be called by context initiator or acceptor
54 * but prior to the first call to initSecContext, acceptSecContext, initDelegation
55 * or acceptDelegation.
56 *
57 * @param option
58 * option type.
59 * @param value
60 * option value.
61 * @exception GSSException containing the following major error codes:
62 * <code>GSSException.FAILURE</code>
63 */
64 public void setOption(Oid option, Object value)
65 throws GSSException;
66
67 /**
68 * Gets a context option. It can be called by context initiator or acceptor.
69 *
70 * @param option option type.
71 * @return value option value. Maybe be null.
72 * @exception GSSException containing the following major error codes:
73 * <code>GSSException.FAILURE</code>
74 */
75 public Object getOption(Oid option)
76 throws GSSException;
77
78 /**
79 * Initiate the delegation of a credential.
80 *
81 * This functions drives the initiating side of the credential
82 * delegation process. It is expected to be called in tandem with the
83 * <code>acceptDelegation</code> function.
84 *
85 *
86 * @param cred
87 * The credential to be delegated. May be null
88 * in which case the credential associated with the security
89 * context is used.
90 * @param mechanism
91 * The desired security mechanism. May be null.
92 * @param lifetime
93 * The requested period of validity (seconds) of the delegated
94 * credential.
95 * @return A token that should be passed to <code>acceptDelegation</code> if
96 * <code>isDelegationFinished</code> returns false. May be null.
97 * @exception GSSException containing the following major error codes:
98 * <code>GSSException.FAILURE</code>
99 */
100 public byte[] initDelegation(GSSCredential cred,
101 Oid mechanism,
102 int lifetime,
103 byte[] buf, int off, int len)
104 throws GSSException;
105
106 /**
107 * Accept a delegated credential.
108 *
109 * This functions drives the accepting side of the credential
110 * delegation process. It is expected to be called in tandem with the
111 * <code>initDelegation</code> function.
112 *
113 * @param lifetime
114 * The requested period of validity (seconds) of the delegated
115 * credential.
116 * @return A token that should be passed to <code>initDelegation</code> if
117 * <code>isDelegationFinished</code> returns false. May be null.
118 * @exception GSSException containing the following major error codes:
119 * <code>GSSException.FAILURE</code>
120 */
121 public byte[] acceptDelegation(int lifetime,
122 byte[] but, int off, int len)
123 throws GSSException;
124
125 /**
126 * Returns the delegated credential that was delegated using
127 * the <code>initDelegation</code> and <code>acceptDelegation</code>
128 * functions. This is to be called on the delegation accepting
129 * side once once <code>isDelegationFinished</code> returns true.
130 *
131 * @return The delegated credential. Might be null if credential
132 * delegation is not finished.
133 */
134 public GSSCredential getDelegatedCredential();
135
136 /**
137 * Used during delegation to determine the state of the delegation.
138 *
139 * @return true if delegation was completed, false otherwise.
140 */
141 public boolean isDelegationFinished();
142
143 /**
144 * Retrieves arbitrary data about this context.
145 *
146 * @param oid the oid of the information desired.
147 * @return the information desired. Might be null.
148 * @exception GSSException containing the following major error codes:
149 * <code>GSSException.FAILURE</code>
150 */
151 public Object inquireByOid(Oid oid) throws GSSException;
152
153 /**
154 * Specifies a list of ciphers that will not be used.
155 * @param ciphers The list of banned ciphers.
156 */
157 public void setBannedCiphers(String[] ciphers);
158 }