1 /*
2 * Copyright (c) 1996, 2010, 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 java.security;
27
28 import java.io.Serializable;
29 import java.util.Enumeration;
30 import java.util.Properties;
31
32 /**
33 * <p>This class represents a scope for identities. It is an Identity
34 * itself, and therefore has a name and can have a scope. It can also
35 * optionally have a public key and associated certificates.
36 *
37 * <p>An IdentityScope can contain Identity objects of all kinds, including
38 * Signers. All types of Identity objects can be retrieved, added, and
39 * removed using the same methods. Note that it is possible, and in fact
40 * expected, that different types of identity scopes will
41 * apply different policies for their various operations on the
42 * various types of Identities.
43 *
44 * <p>There is a one-to-one mapping between keys and identities, and
45 * there can only be one copy of one key per scope. For example, suppose
46 * <b>Acme Software, Inc</b> is a software publisher known to a user.
47 * Suppose it is an Identity, that is, it has a public key, and a set of
48 * associated certificates. It is named in the scope using the name
49 * "Acme Software". No other named Identity in the scope has the same
50 * public key. Of course, none has the same name as well.
51 *
52 * @see Identity
53 * @see Signer
54 * @see Principal
55 * @see Key
56 *
57 * @author Benjamin Renaud
58 *
59 * @deprecated This class is no longer used. Its functionality has been
60 * replaced by <code>java.security.KeyStore</code>, the
61 * <code>java.security.cert</code> package, and
62 * <code>java.security.Principal</code>.
63 */
64 @Deprecated
65 public abstract
66 class IdentityScope extends Identity {
67
68 private static final long serialVersionUID = -2337346281189773310L;
69
70 /* The system's scope */
71 private static IdentityScope scope;
72
73 // initialize the system scope
74 private static void initializeSystemScope() {
75
76 String classname = AccessController.doPrivileged(
77 new PrivilegedAction<String>() {
78 public String run() {
79 return Security.getProperty("system.scope");
80 }
81 });
82
83 if (classname == null) {
84 return;
85
86 } else {
87
88 try {
89 Class.forName(classname);
90 } catch (ClassNotFoundException e) {
91 //Security.error("unable to establish a system scope from " +
92 // classname);
93 e.printStackTrace();
94 }
95 }
96 }
97
98 /**
99 * This constructor is used for serialization only and should not
100 * be used by subclasses.
101 */
102 protected IdentityScope() {
103 this("restoring...");
104 }
105
106 /**
107 * Constructs a new identity scope with the specified name.
108 *
109 * @param name the scope name.
110 */
111 public IdentityScope(String name) {
112 super(name);
113 }
114
115 /**
116 * Constructs a new identity scope with the specified name and scope.
117 *
118 * @param name the scope name.
119 * @param scope the scope for the new identity scope.
120 *
121 * @exception KeyManagementException if there is already an identity
122 * with the same name in the scope.
123 */
124 public IdentityScope(String name, IdentityScope scope)
125 throws KeyManagementException {
126 super(name, scope);
127 }
128
129 /**
130 * Returns the system's identity scope.
131 *
132 * @return the system's identity scope, or {@code null} if none has been
133 * set.
134 *
135 * @see #setSystemScope
136 */
137 public static IdentityScope getSystemScope() {
138 if (scope == null) {
139 initializeSystemScope();
140 }
141 return scope;
142 }
143
144
145 /**
146 * Sets the system's identity scope.
147 *
148 * <p>First, if there is a security manager, its
149 * <code>checkSecurityAccess</code>
150 * method is called with <code>"setSystemScope"</code>
151 * as its argument to see if it's ok to set the identity scope.
152 *
153 * @param scope the scope to set.
154 *
155 * @exception SecurityException if a security manager exists and its
156 * <code>checkSecurityAccess</code> method doesn't allow
157 * setting the identity scope.
158 *
159 * @see #getSystemScope
160 * @see SecurityManager#checkSecurityAccess
161 */
162 protected static void setSystemScope(IdentityScope scope) {
163 check("setSystemScope");
164 IdentityScope.scope = scope;
165 }
166
167 /**
168 * Returns the number of identities within this identity scope.
169 *
170 * @return the number of identities within this identity scope.
171 */
172 public abstract int size();
173
174 /**
175 * Returns the identity in this scope with the specified name (if any).
176 *
177 * @param name the name of the identity to be retrieved.
178 *
179 * @return the identity named <code>name</code>, or null if there are
180 * no identities named <code>name</code> in this scope.
181 */
182 public abstract Identity getIdentity(String name);
183
184 /**
185 * Retrieves the identity whose name is the same as that of the
186 * specified principal. (Note: Identity implements Principal.)
187 *
188 * @param principal the principal corresponding to the identity
189 * to be retrieved.
190 *
191 * @return the identity whose name is the same as that of the
192 * principal, or null if there are no identities of the same name
193 * in this scope.
194 */
195 public Identity getIdentity(Principal principal) {
196 return getIdentity(principal.getName());
197 }
198
199 /**
200 * Retrieves the identity with the specified public key.
201 *
202 * @param key the public key for the identity to be returned.
203 *
204 * @return the identity with the given key, or null if there are
205 * no identities in this scope with that key.
206 */
207 public abstract Identity getIdentity(PublicKey key);
208
209 /**
210 * Adds an identity to this identity scope.
211 *
212 * @param identity the identity to be added.
213 *
214 * @exception KeyManagementException if the identity is not
215 * valid, a name conflict occurs, another identity has the same
216 * public key as the identity being added, or another exception
217 * occurs. */
218 public abstract void addIdentity(Identity identity)
219 throws KeyManagementException;
220
221 /**
222 * Removes an identity from this identity scope.
223 *
224 * @param identity the identity to be removed.
225 *
226 * @exception KeyManagementException if the identity is missing,
227 * or another exception occurs.
228 */
229 public abstract void removeIdentity(Identity identity)
230 throws KeyManagementException;
231
232 /**
233 * Returns an enumeration of all identities in this identity scope.
234 *
235 * @return an enumeration of all identities in this identity scope.
236 */
237 public abstract Enumeration<Identity> identities();
238
239 /**
240 * Returns a string representation of this identity scope, including
241 * its name, its scope name, and the number of identities in this
242 * identity scope.
243 *
244 * @return a string representation of this identity scope.
245 */
246 public String toString() {
247 return super.toString() + "[" + size() + "]";
248 }
249
250 private static void check(String directive) {
251 SecurityManager security = System.getSecurityManager();
252 if (security != null) {
253 security.checkSecurityAccess(directive);
254 }
255 }
256
257 }