KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > security > Identity


1 /*
2  * @(#)Identity.java 1.61 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7  
8 package java.security;
9
10 import java.io.Serializable JavaDoc;
11 import java.util.*;
12
13 /**
14  * <p>This class represents identities: real-world objects such as people,
15  * companies or organizations whose identities can be authenticated using
16  * their public keys. Identities may also be more abstract (or concrete)
17  * constructs, such as daemon threads or smart cards.
18  *
19  * <p>All Identity objects have a name and a public key. Names are
20  * immutable. Identities may also be scoped. That is, if an Identity is
21  * specified to have a particular scope, then the name and public
22  * key of the Identity are unique within that scope.
23  *
24  * <p>An Identity also has a set of certificates (all certifying its own
25  * public key). The Principal names specified in these certificates need
26  * not be the same, only the key.
27  *
28  * <p>An Identity can be subclassed, to include postal and email addresses,
29  * telephone numbers, images of faces and logos, and so on.
30  *
31  * @see IdentityScope
32  * @see Signer
33  * @see Principal
34  *
35  * @version 1.61
36  * @author Benjamin Renaud
37  * @deprecated This class is no longer used. Its functionality has been
38  * replaced by <code>java.security.KeyStore</code>, the
39  * <code>java.security.cert</code> package, and
40  * <code>java.security.Principal</code>.
41  */

42 @Deprecated JavaDoc
43 public abstract class Identity implements Principal JavaDoc, Serializable JavaDoc {
44
45     /** use serialVersionUID from JDK 1.1.x for interoperability */
46     private static final long serialVersionUID = 3609922007826600659L;
47
48     /**
49      * The name for this identity.
50      *
51      * @serial
52      */

53     private String JavaDoc name;
54
55     /**
56      * The public key for this identity.
57      *
58      * @serial
59      */

60     private PublicKey JavaDoc publicKey;
61
62     /**
63      * Generic, descriptive information about the identity.
64      *
65      * @serial
66      */

67     String JavaDoc info = "No further information available.";
68
69     /**
70      * The scope of the identity.
71      *
72      * @serial
73      */

74     IdentityScope JavaDoc scope;
75
76     /**
77      * The certificates for this identity.
78      *
79      * @serial
80      */

81     Vector certificates;
82
83     /**
84      * Constructor for serialization only.
85      */

86     protected Identity() {
87     this("restoring...");
88     }
89
90     /**
91      * Constructs an identity with the specified name and scope.
92      *
93      * @param name the identity name.
94      * @param scope the scope of the identity.
95      *
96      * @exception KeyManagementException if there is already an identity
97      * with the same name in the scope.
98      */

99     public Identity(String JavaDoc name, IdentityScope JavaDoc scope) throws
100     KeyManagementException JavaDoc {
101     this(name);
102     if (scope != null) {
103         scope.addIdentity(this);
104     }
105     this.scope = scope;
106     }
107
108     /**
109      * Constructs an identity with the specified name and no scope.
110      *
111      * @param name the identity name.
112      */

113     public Identity(String JavaDoc name) {
114     this.name = name;
115     }
116
117     /**
118      * Returns this identity's name.
119      *
120      * @return the name of this identity.
121      */

122     public final String JavaDoc getName() {
123     return name;
124     }
125
126     /**
127      * Returns this identity's scope.
128      *
129      * @return the scope of this identity.
130      */

131     public final IdentityScope JavaDoc getScope() {
132     return scope;
133     }
134
135     /**
136      * Returns this identity's public key.
137      *
138      * @return the public key for this identity.
139      *
140      * @see #setPublicKey
141      */

142     public PublicKey JavaDoc getPublicKey() {
143     return publicKey;
144     }
145
146     /**
147      * Sets this identity's public key. The old key and all of this
148      * identity's certificates are removed by this operation.
149      *
150      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code>
151      * method is called with <code>"setIdentityPublicKey"</code>
152      * as its argument to see if it's ok to set the public key.
153      *
154      * @param key the public key for this identity.
155      *
156      * @exception KeyManagementException if another identity in the
157      * identity's scope has the same public key, or if another exception occurs.
158      *
159      * @exception SecurityException if a security manager exists and its
160      * <code>checkSecurityAccess</code> method doesn't allow
161      * setting the public key.
162      *
163      * @see #getPublicKey
164      * @see SecurityManager#checkSecurityAccess
165      */

166     /* Should we throw an exception if this is already set? */
167     public void setPublicKey(PublicKey JavaDoc key) throws KeyManagementException JavaDoc {
168
169     check("setIdentityPublicKey");
170     this.publicKey = key;
171     certificates = new Vector();
172     }
173
174     /**
175      * Specifies a general information string for this identity.
176      *
177      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code>
178      * method is called with <code>"setIdentityInfo"</code>
179      * as its argument to see if it's ok to specify the information string.
180      *
181      * @param info the information string.
182      *
183      * @exception SecurityException if a security manager exists and its
184      * <code>checkSecurityAccess</code> method doesn't allow
185      * setting the information string.
186      *
187      * @see #getInfo
188      * @see SecurityManager#checkSecurityAccess
189      */

190     public void setInfo(String JavaDoc info) {
191     check("setIdentityInfo");
192     this.info = info;
193     }
194
195     /**
196      * Returns general information previously specified for this identity.
197      *
198      * @return general information about this identity.
199      *
200      * @see #setInfo
201      */

202     public String JavaDoc getInfo() {
203     return info;
204     }
205
206     /**
207      * Adds a certificate for this identity. If the identity has a public
208      * key, the public key in the certificate must be the same, and if
209      * the identity does not have a public key, the identity's
210      * public key is set to be that specified in the certificate.
211      *
212      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code>
213      * method is called with <code>"addIdentityCertificate"</code>
214      * as its argument to see if it's ok to add a certificate.
215      *
216      * @param certificate the certificate to be added.
217      *
218      * @exception KeyManagementException if the certificate is not valid,
219      * if the public key in the certificate being added conflicts with
220      * this identity's public key, or if another exception occurs.
221      *
222      * @exception SecurityException if a security manager exists and its
223      * <code>checkSecurityAccess</code> method doesn't allow
224      * adding a certificate.
225      *
226      * @see SecurityManager#checkSecurityAccess
227      */

228     public void addCertificate(Certificate JavaDoc certificate)
229     throws KeyManagementException JavaDoc {
230
231     check("addIdentityCertificate");
232
233     if (certificates == null) {
234         certificates = new Vector();
235     }
236     if (publicKey != null) {
237         if (!keyEquals(publicKey, certificate.getPublicKey())) {
238         throw new KeyManagementException JavaDoc(
239             "public key different from cert public key");
240         }
241     } else {
242         publicKey = certificate.getPublicKey();
243     }
244     certificates.addElement(certificate);
245     }
246
247     private boolean keyEquals(Key JavaDoc aKey, Key JavaDoc anotherKey) {
248         String JavaDoc aKeyFormat = aKey.getFormat();
249         String JavaDoc anotherKeyFormat = anotherKey.getFormat();
250     if ((aKeyFormat == null) ^ (anotherKeyFormat == null))
251         return false;
252     if (aKeyFormat != null && anotherKeyFormat != null)
253         if (!aKeyFormat.equalsIgnoreCase(anotherKeyFormat))
254         return false;
255     return java.util.Arrays.equals(aKey.getEncoded(),
256                      anotherKey.getEncoded());
257     }
258
259
260     /**
261      * Removes a certificate from this identity.
262      *
263      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code>
264      * method is called with <code>"removeIdentityCertificate"</code>
265      * as its argument to see if it's ok to remove a certificate.
266      *
267      * @param certificate the certificate to be removed.
268      *
269      * @exception KeyManagementException if the certificate is
270      * missing, or if another exception occurs.
271      *
272      * @exception SecurityException if a security manager exists and its
273      * <code>checkSecurityAccess</code> method doesn't allow
274      * removing a certificate.
275      *
276      * @see SecurityManager#checkSecurityAccess
277      */

278     public void removeCertificate(Certificate JavaDoc certificate)
279     throws KeyManagementException JavaDoc {
280     check("removeIdentityCertificate");
281     if (certificates != null) {
282         certificates.removeElement(certificate);
283     }
284     }
285
286     /**
287      * Returns a copy of all the certificates for this identity.
288      *
289      * @return a copy of all the certificates for this identity.
290      */

291     public Certificate JavaDoc[] certificates() {
292     if (certificates == null) {
293         return new Certificate JavaDoc[0];
294     }
295     int len = certificates.size();
296     Certificate JavaDoc[] certs = new Certificate JavaDoc[len];
297     certificates.copyInto(certs);
298     return certs;
299     }
300
301     /**
302      * Tests for equality between the specified object and this identity.
303      * This first tests to see if the entities actually refer to the same
304      * object, in which case it returns true. Next, it checks to see if
305      * the entities have the same name and the same scope. If they do,
306      * the method returns true. Otherwise, it calls
307      * {@link #identityEquals(Identity) identityEquals}, which subclasses should
308      * override.
309      *
310      * @param identity the object to test for equality with this identity.
311      *
312      * @return true if the objects are considered equal, false otherwise.
313      *
314      * @see #identityEquals
315      */

316     public final boolean equals(Object JavaDoc identity) {
317
318     if (identity == this) {
319         return true;
320     }
321
322     if (identity instanceof Identity JavaDoc) {
323         Identity JavaDoc i = (Identity JavaDoc)identity;
324         if (this.fullName().equals(i.fullName())) {
325         return true;
326         } else {
327         return identityEquals(i);
328         }
329     }
330     return false;
331     }
332
333     /**
334      * Tests for equality between the specified identity and this identity.
335      * This method should be overriden by subclasses to test for equality.
336      * The default behavior is to return true if the names and public keys
337      * are equal.
338      *
339      * @param identity the identity to test for equality with this identity.
340      *
341      * @return true if the identities are considered equal, false
342      * otherwise.
343      *
344      * @see #equals
345      */

346     protected boolean identityEquals(Identity JavaDoc identity) {
347     if (!name.equalsIgnoreCase(identity.name))
348         return false;
349     
350     if ((publicKey == null) ^ (identity.publicKey == null))
351         return false;
352
353     if (publicKey != null && identity.publicKey != null)
354         if (!publicKey.equals(identity.publicKey))
355         return false;
356
357     return true;
358
359     }
360
361     /**
362      * Returns a parsable name for identity: identityName.scopeName
363      */

364     String JavaDoc fullName() {
365     String JavaDoc parsable = name;
366     if (scope != null) {
367         parsable += "." + scope.getName();
368     }
369     return parsable;
370     }
371
372     /**
373      * Returns a short string describing this identity, telling its
374      * name and its scope (if any).
375      *
376      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code>
377      * method is called with <code>"printIdentity"</code>
378      * as its argument to see if it's ok to return the string.
379      *
380      * @return information about this identity, such as its name and the
381      * name of its scope (if any).
382      *
383      * @exception SecurityException if a security manager exists and its
384      * <code>checkSecurityAccess</code> method doesn't allow
385      * returning a string describing this identity.
386      *
387      * @see SecurityManager#checkSecurityAccess
388      */

389     public String JavaDoc toString() {
390     check("printIdentity");
391     String JavaDoc printable = name;
392     if (scope != null) {
393         printable += "[" + scope.getName() + "]";
394     }
395     return printable;
396     }
397
398     /**
399      * Returns a string representation of this identity, with
400      * optionally more details than that provided by the
401      * <code>toString</code> method without any arguments.
402      *
403      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code>
404      * method is called with <code>"printIdentity"</code>
405      * as its argument to see if it's ok to return the string.
406      *
407      * @param detailed whether or not to provide detailed information.
408      *
409      * @return information about this identity. If <code>detailed</code>
410      * is true, then this method returns more information than that
411      * provided by the <code>toString</code> method without any arguments.
412      *
413      * @exception SecurityException if a security manager exists and its
414      * <code>checkSecurityAccess</code> method doesn't allow
415      * returning a string describing this identity.
416      *
417      * @see #toString
418      * @see SecurityManager#checkSecurityAccess
419      */

420     public String JavaDoc toString(boolean detailed) {
421     String JavaDoc out = toString();
422     if (detailed) {
423         out += "\n";
424         out += printKeys();
425         out += "\n" + printCertificates();
426         if (info != null) {
427         out += "\n\t" + info;
428         } else {
429         out += "\n\tno additional information available.";
430         }
431     }
432     return out;
433     }
434
435     String JavaDoc printKeys() {
436     String JavaDoc key = "";
437     if (publicKey != null) {
438         key = "\tpublic key initialized";
439     } else {
440         key = "\tno public key";
441     }
442     return key;
443     }
444
445     String JavaDoc printCertificates() {
446     String JavaDoc out = "";
447     if (certificates == null) {
448         return "\tno certificates";
449     } else {
450         out += "\tcertificates: \n";
451         Enumeration e = certificates.elements();
452         int i = 1;
453         while (e.hasMoreElements()) {
454         Certificate JavaDoc cert = (Certificate JavaDoc)e.nextElement();
455         out += "\tcertificate " + i++ +
456             "\tfor : " + cert.getPrincipal() + "\n";
457         out += "\t\t\tfrom : " +
458             cert.getGuarantor() + "\n";
459         }
460     }
461     return out;
462     }
463     
464     /**
465      * Returns a hashcode for this identity.
466      *
467      * @return a hashcode for this identity.
468      */

469     public int hashCode() {
470     return name.hashCode();
471     }
472
473     private static void check(String JavaDoc directive) {
474     SecurityManager JavaDoc security = System.getSecurityManager();
475     if (security != null) {
476         security.checkSecurityAccess(directive);
477     }
478     }
479 }
480
Popular Tags