1/*
2 * Copyright (c) 1996, 2017, 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
26package java.security;
27
28import java.io.Serializable;
29import java.util.Enumeration;
30import 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 * @since 1.1
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(since="1.2")
66public abstract
67class 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
75    private static void initializeSystemScope() {
76
77        String classname = AccessController.doPrivileged(
78                                new PrivilegedAction<>() {
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                Class.forName(classname);
91            } catch (ClassNotFoundException 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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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. */
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     */
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     */
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     */
247    public String toString() {
248        return super.toString() + "[" + size() + "]";
249    }
250
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