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  ;
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  
43  public abstract class Identity implements Principal  , Serializable   {
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   name;
54  
55      /**
56       * The public key for this identity.
57       *
58       * @serial
59       */
60      private PublicKey   publicKey;
61  
62      /**
63       * Generic, descriptive information about the identity.
64       *
65       * @serial
66       */
67      String   info = "No further information available.";
68  
69      /**
70       * The scope of the identity.
71       *
72       * @serial
73       */
74      IdentityScope   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   name, IdentityScope   scope) throws
100     KeyManagementException   {
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   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   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   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   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   key) throws KeyManagementException   {
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   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   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   certificate)
229     throws KeyManagementException   {
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  (
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   aKey, Key   anotherKey) {
248         String   aKeyFormat = aKey.getFormat();
249         String   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   certificate)
279     throws KeyManagementException   {
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  [] certificates() {
292     if (certificates == null) {
293         return new Certificate  [0];
294     }
295     int len = certificates.size();
296     Certificate  [] certs = new Certificate  [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   identity) {
317 
318     if (identity == this) {
319         return true;
320     }
321 
322     if (identity instanceof Identity  ) {
323         Identity   i = (Identity  )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   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   fullName() {
365     String   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   toString() {
390     check("printIdentity");
391     String   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   toString(boolean detailed) {
421     String   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   printKeys() {
436     String   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   printCertificates() {
446     String   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   cert = (Certificate  )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   directive) {
474     SecurityManager   security = System.getSecurityManager();
475     if (security != null) {
476         security.checkSecurityAccess(directive);
477     }
478     }
479 }
480
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags