1 /*
2  * Copyright (C) 2014 The Android Open Source Project
3  * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5  *
6  * This code is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU General Public License version 2 only, as
8  * published by the Free Software Foundation.  Oracle designates this
9  * particular file as subject to the "Classpath" exception as provided
10  * by Oracle in the LICENSE file that accompanied this code.
11  *
12  * This code is distributed in the hope that it will be useful, but WITHOUT
13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
15  * version 2 for more details (a copy is included in the LICENSE file that
16  * accompanied this code).
17  *
18  * You should have received a copy of the GNU General Public License version
19  * 2 along with this work; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
21  *
22  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
23  * or visit www.oracle.com if you need additional information or have any
24  * questions.
25  */
26 
27 package java.security;
28 
29 import java.io.Serializable;
30 import java.util.Enumeration;
31 import java.util.Properties;
32 
33 /**
34  * <p>This class represents a scope for identities. It is an Identity
35  * itself, and therefore has a name and can have a scope. It can also
36  * optionally have a public key and associated certificates.
37  *
38  * <p>An IdentityScope can contain Identity objects of all kinds, including
39  * Signers. All types of Identity objects can be retrieved, added, and
40  * removed using the same methods. Note that it is possible, and in fact
41  * expected, that different types of identity scopes will
42  * apply different policies for their various operations on the
43  * various types of Identities.
44  *
45  * <p>There is a one-to-one mapping between keys and identities, and
46  * there can only be one copy of one key per scope. For example, suppose
47  * <b>Acme Software, Inc</b> is a software publisher known to a user.
48  * Suppose it is an Identity, that is, it has a public key, and a set of
49  * associated certificates. It is named in the scope using the name
50  * "Acme Software". No other named Identity in the scope has the same
51  * public  key. Of course, none has the same name as well.
52  *
53  * @see Identity
54  * @see Signer
55  * @see Principal
56  * @see Key
57  *
58  * @author Benjamin Renaud
59  *
60  * @deprecated This class is no longer used. Its functionality has been
61  * replaced by {@code java.security.KeyStore}, the
62  * {@code java.security.cert} package, and
63  * {@code java.security.Principal}.
64  */
65 @Deprecated
66 public abstract
67 class IdentityScope extends Identity {
68 
69     private static final long serialVersionUID = -2337346281189773310L;
70 
71     /* The system's scope */
72     private static IdentityScope scope;
73 
74     // initialize the system scope
initializeSystemScope()75     private static void initializeSystemScope() {
76 
77         String classname = AccessController.doPrivileged(
78                                 new PrivilegedAction<String>() {
79             public String run() {
80                 return Security.getProperty("system.scope");
81             }
82         });
83 
84         if (classname == null) {
85             return;
86 
87         } else {
88 
89             try {
90                 scope = (IdentityScope) Class.forName(classname).newInstance();
91             } catch (Exception e) {
92                 //Security.error("unable to establish a system scope from " +
93                 //             classname);
94                 e.printStackTrace();
95             }
96         }
97     }
98 
99     /**
100      * This constructor is used for serialization only and should not
101      * be used by subclasses.
102      */
IdentityScope()103     protected IdentityScope() {
104         this("restoring...");
105     }
106 
107     /**
108      * Constructs a new identity scope with the specified name.
109      *
110      * @param name the scope name.
111      */
IdentityScope(String name)112     public IdentityScope(String name) {
113         super(name);
114     }
115 
116     /**
117      * Constructs a new identity scope with the specified name and scope.
118      *
119      * @param name the scope name.
120      * @param scope the scope for the new identity scope.
121      *
122      * @exception KeyManagementException if there is already an identity
123      * with the same name in the scope.
124      */
IdentityScope(String name, IdentityScope scope)125     public IdentityScope(String name, IdentityScope scope)
126     throws KeyManagementException {
127         super(name, scope);
128     }
129 
130     /**
131      * Returns the system's identity scope.
132      *
133      * @return the system's identity scope, or {@code null} if none has been
134      *         set.
135      *
136      * @see #setSystemScope
137      */
getSystemScope()138     public static IdentityScope getSystemScope() {
139         if (scope == null) {
140             initializeSystemScope();
141         }
142         return scope;
143     }
144 
145 
146     /**
147      * Sets the system's identity scope.
148      *
149      * <p>First, if there is a security manager, its
150      * {@code checkSecurityAccess}
151      * method is called with {@code "setSystemScope"}
152      * as its argument to see if it's ok to set the identity scope.
153      *
154      * @param scope the scope to set.
155      *
156      * @exception  SecurityException  if a security manager exists and its
157      * {@code checkSecurityAccess} method doesn't allow
158      * setting the identity scope.
159      *
160      * @see #getSystemScope
161      * @see SecurityManager#checkSecurityAccess
162      */
setSystemScope(IdentityScope scope)163     protected static void setSystemScope(IdentityScope scope) {
164         check("setSystemScope");
165         IdentityScope.scope = scope;
166     }
167 
168     /**
169      * Returns the number of identities within this identity scope.
170      *
171      * @return the number of identities within this identity scope.
172      */
size()173     public abstract int size();
174 
175     /**
176      * Returns the identity in this scope with the specified name (if any).
177      *
178      * @param name the name of the identity to be retrieved.
179      *
180      * @return the identity named {@code name}, or null if there are
181      * no identities named {@code name} in this scope.
182      */
getIdentity(String name)183     public abstract Identity getIdentity(String name);
184 
185     /**
186      * Retrieves the identity whose name is the same as that of the
187      * specified principal. (Note: Identity implements Principal.)
188      *
189      * @param principal the principal corresponding to the identity
190      * to be retrieved.
191      *
192      * @return the identity whose name is the same as that of the
193      * principal, or null if there are no identities of the same name
194      * in this scope.
195      */
getIdentity(Principal principal)196     public Identity getIdentity(Principal principal) {
197         return getIdentity(principal.getName());
198     }
199 
200     /**
201      * Retrieves the identity with the specified public key.
202      *
203      * @param key the public key for the identity to be returned.
204      *
205      * @return the identity with the given key, or null if there are
206      * no identities in this scope with that key.
207      */
getIdentity(PublicKey key)208     public abstract Identity getIdentity(PublicKey key);
209 
210     /**
211      * Adds an identity to this identity scope.
212      *
213      * @param identity the identity to be added.
214      *
215      * @exception KeyManagementException if the identity is not
216      * valid, a name conflict occurs, another identity has the same
217      * public key as the identity being added, or another exception
218      * occurs. */
addIdentity(Identity identity)219     public abstract void addIdentity(Identity identity)
220     throws KeyManagementException;
221 
222     /**
223      * Removes an identity from this identity scope.
224      *
225      * @param identity the identity to be removed.
226      *
227      * @exception KeyManagementException if the identity is missing,
228      * or another exception occurs.
229      */
removeIdentity(Identity identity)230     public abstract void removeIdentity(Identity identity)
231     throws KeyManagementException;
232 
233     /**
234      * Returns an enumeration of all identities in this identity scope.
235      *
236      * @return an enumeration of all identities in this identity scope.
237      */
identities()238     public abstract Enumeration<Identity> identities();
239 
240     /**
241      * Returns a string representation of this identity scope, including
242      * its name, its scope name, and the number of identities in this
243      * identity scope.
244      *
245      * @return a string representation of this identity scope.
246      */
toString()247     public String toString() {
248         return super.toString() + "[" + size() + "]";
249     }
250 
check(String directive)251     private static void check(String directive) {
252         SecurityManager security = System.getSecurityManager();
253         if (security != null) {
254             security.checkSecurityAccess(directive);
255         }
256     }
257 
258 }
259