libjava/java/security/Identity.java

   1 /* Identity.java --- Identity Class
   2    Copyright (C) 1999, 2003, Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.security;
  39
  40 import java.io.Serializable;
  41 import java.util.Vector;
  42
  43 /**
  44  * <p>This class represents identities: real-world objects such as people,
  45  * companies or organizations whose identities can be authenticated using their
  46  * public keys. Identities may also be more abstract (or concrete) constructs,
  47  * such as daemon threads or smart cards.</p>
  48  *
  49  * <p>All Identity objects have a <i>name</i> and a <i>public key</i>. Names
  50  * are immutable. <i>Identities</i> may also be <b>scoped</b>. That is, if an
  51  * <i>Identity</i> is specified to have a particular <i>scope</i>, then the
  52  * <i>name</i> and <i>public key</i> of the <i>Identity</i> are unique within
  53  * that <i>scope</i>.</p>
  54  *
  55  * <p>An <i>Identity</i> also has a <i>set of certificates</i> (all certifying
  56  * its own <i>public key</i>). The <i>Principal</i> names specified in these
  57  * certificates need not be the same, only the key.</p>
  58  *
  59  * <p>An <i>Identity</i> can be subclassed, to include postal and email
  60  * addresses, telephone numbers, images of faces and logos, and so on.</p>
  61  *
  62  * @author Mark Benvenuto
  63  * @see IdentityScope
  64  * @see Signer
  65  * @see Principal
  66  * @deprecated This class is no longer used. Its functionality has been replaced
  67  * by <code>java.security.KeyStore</code>, the <code>java.security.cert</code>
  68  * package, and <code>java.security.Principal</code>.
  69  */
  70 public abstract class Identity implements Principal, Serializable
  71 {
  72   private static final long serialVersionUID = 3609922007826600659L;
  73
  74   private String name;
  75   private IdentityScope scope;
  76   private PublicKey publicKey;
  77   private String info;
  78   private Vector certificates;
  79
  80   /** Constructor for serialization only. */
  81   protected Identity()
  82   {
  83   }
  84
  85   /**
  86    * Constructs an identity with the specified name and scope.
  87    *
  88    * @param name the identity name.
  89    * @param scope the scope of the identity.
  90    * @throws KeyManagementException if there is already an identity with the
  91    * same name in the scope.
  92    */
  93   public Identity(String name, IdentityScope scope)
  94     throws KeyManagementException
  95   {
  96     this.name = name;
  97     this.scope = scope;
  98   }
  99
 100   /**
 101    * Constructs an identity with the specified name and no scope.
 102    *
 103    * @param name the identity name.
 104    */
 105   public Identity(String name)
 106   {
 107     this.name = name;
 108     this.scope = null;
 109   }
 110
 111   /**
 112    * Returns this identity's name.
 113    *
 114    * @return the name of this identity.
 115    */
 116   public final String getName()
 117   {
 118     return name;
 119   }
 120
 121   /**
 122    * Returns this identity's scope.
 123    *
 124    * @return the scope of this identity.
 125    */
 126   public final IdentityScope getScope()
 127   {
 128     return scope;
 129   }
 130
 131   /**
 132    * Returns this identity's public key.
 133    *
 134    * @return the public key for this identity.
 135    * @see #setPublicKey(java.security.PublicKey)
 136    */
 137   public PublicKey getPublicKey()
 138   {
 139     return publicKey;
 140   }
 141
 142   /**
 143    * <p>Sets this identity's public key. The old key and all of this identity's
 144    * certificates are removed by this operation.</p>
 145    *
 146    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 147    * </code> method is called with <code>"setIdentityPublicKey"</code> as its
 148    * argument to see if it's ok to set the public key.</p>
 149    *
 150    * @param key the public key for this identity.
 151    * @throws KeyManagementException if another identity in the identity's scope
 152    * has the same public key, or if another exception occurs.
 153    * @throws SecurityException if a security manager exists and its
 154    * <code>checkSecurityAccess()<code> method doesn't allow setting the public
 155    * key.
 156    * @see #getPublicKey()
 157    * @see SecurityManager#checkSecurityAccess(String)
 158    */
 159   public void setPublicKey(PublicKey key) throws KeyManagementException
 160   {
 161     SecurityManager sm = System.getSecurityManager();
 162     if (sm != null)
 163       sm.checkSecurityAccess("setIdentityPublicKey");
 164
 165     this.publicKey = key;
 166   }
 167
 168   /**
 169    * <p>Specifies a general information string for this identity.</p>
 170    *
 171    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 172    * </code> method is called with <code>"setIdentityInfo"</code> as its
 173    * argument to see if it's ok to specify the information string.</p>
 174    *
 175    * @param info the information string.
 176    * @throws SecurityException if a security manager exists and its
 177    * <code>checkSecurityAccess()</code> method doesn't allow setting the
 178    * information string.
 179    * @see #getInfo()
 180    * @see SecurityManager#checkSecurityAccess(String)
 181    */
 182   public void setInfo(String info)
 183   {
 184     SecurityManager sm = System.getSecurityManager();
 185     if (sm != null)
 186       sm.checkSecurityAccess("setIdentityInfo");
 187
 188     this.info = info;
 189   }
 190
 191   /**
 192    * Returns general information previously specified for this identity.
 193    *
 194    * @return general information about this identity.
 195    * @see #setInfo(String)
 196    */
 197   public String getInfo()
 198   {
 199     return info;
 200   }
 201
 202   /**
 203    * <p>Adds a certificate for this identity. If the identity has a public key,
 204    * the public key in the certificate must be the same, and if the identity
 205    * does not have a public key, the identity's public key is set to be that
 206    * specified in the certificate.</p>
 207    *
 208    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 209    * </code> method is called with <code>"addIdentityCertificate"</code> as its
 210    * argument to see if it's ok to add a certificate.</p>
 211    *
 212    * @param certificate the certificate to be added.
 213    * @throws KeyManagementException if the certificate is not valid, if the
 214    * public key in the certificate being added conflicts with this identity's
 215    * public key, or if another exception occurs.
 216    * @throws SecurityException if a security manager exists and its
 217    * <code>checkSecurityAccess()</code> method doesn't allow adding a
 218    * certificate.
 219    * @see SecurityManager#checkSecurityAccess(String)
 220    */
 221   public void addCertificate(Certificate certificate)
 222     throws KeyManagementException
 223   {
 224     SecurityManager sm = System.getSecurityManager();
 225     if (sm != null)
 226       sm.checkSecurityAccess("addIdentityCertificate");
 227
 228     // Check public key of this certificate against the first one in the vector
 229     if (certificates.size() > 0)
 230       {
 231         if (((Certificate) certificates.firstElement()).getPublicKey() != publicKey)
 232           throw new KeyManagementException("Public key does not match");
 233       }
 234     certificates.addElement(certificate);
 235   }
 236
 237   /**
 238    * <p>Removes a certificate from this identity.</p>
 239    *
 240    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 241    * </code> method is called with <code>"removeIdentityCertificate"</code> as
 242    * its argument to see if it's ok to remove a certificate.</p>
 243    *
 244    * @param certificate the certificate to be removed.
 245    * @throws KeyManagementException if the certificate is missing, or if
 246    * another exception occurs.
 247    * @throws SecurityException if a security manager exists and its
 248    * <code>checkSecurityAccess()</code> method doesn't allow removing a
 249    * certificate.
 250    * @see SecurityManager#checkSecurityAccess(String)
 251    */
 252   public void removeCertificate(Certificate certificate)
 253     throws KeyManagementException
 254   {
 255     SecurityManager sm = System.getSecurityManager();
 256     if (sm != null)
 257       sm.checkSecurityAccess("removeIdentityCertificate");
 258
 259     if (certificates.contains(certificate) == false)
 260       throw new KeyManagementException("Certificate not found");
 261
 262     certificates.removeElement(certificate);
 263   }
 264
 265   /**
 266    * Returns a copy of all the certificates for this identity.
 267    *
 268    * @return a copy of all the certificates for this identity.
 269    */
 270   public Certificate[] certificates()
 271   {
 272     Certificate certs[] = new Certificate[certificates.size()];
 273     int max = certificates.size();
 274     for (int i = 0; i < max; i++)
 275       certs[i] = (Certificate) certificates.elementAt(i);
 276
 277     return certs;
 278   }
 279
 280   /**
 281    * Tests for equality between the specified object and this identity. This
 282    * first tests to see if the entities actually refer to the same object, in
 283    * which case it returns <code>true</code>. Next, it checks to see if the
 284    * entities have the same <i>name</i> and the same <i>scope</i>. If they do,
 285    * the method returns <code>true</code>. Otherwise, it calls
 286    * <code>identityEquals()</code>, which subclasses should override.
 287    *
 288    * @param identity the object to test for equality with this identity.
 289    * @return <code>true</code> if the objects are considered equal, <code>false
 290    * </code>otherwise.
 291    * @see #identityEquals(Identity)
 292    */
 293   public final boolean equals(Object identity)
 294   {
 295     if (identity instanceof Identity)
 296       {
 297         if (identity == this)
 298           return true;
 299
 300         if ((((Identity) identity).getName() == this.name) &&
 301             (((Identity) identity).getScope() == this.scope))
 302           return true;
 303
 304         return identityEquals((Identity) identity);
 305       }
 306     return false;
 307   }
 308
 309   /**
 310    * Tests for equality between the specified <code>identity</code> and this
 311    * <i>identity</i>. This method should be overriden by subclasses to test for
 312    * equality. The default behavior is to return <code>true</code> if the names
 313    * and public keys are equal.
 314    *
 315    * @param identity the identity to test for equality with this identity.
 316    * @return <code>true</code> if the identities are considered equal,
 317    * <code>false</code> otherwise.
 318    * @see #equals(Object)
 319    */
 320   protected boolean identityEquals(Identity identity)
 321   {
 322     return ((identity.getName() == this.name) &&
 323             (identity.getPublicKey() == this.publicKey));
 324   }
 325
 326   /**
 327    * <p>Returns a short string describing this identity, telling its name and
 328    * its scope (if any).</p>
 329    *
 330    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 331    * </code> method is called with <code>"printIdentity"</code> as its argument
 332    * to see if it's ok to return the string.</p>
 333    *
 334    * @return information about this identity, such as its name and the name of
 335    * its scope (if any).
 336    * @throws SecurityException if a security manager exists and its
 337    * <code>checkSecurityAccess()</code> method doesn't allow returning a string
 338    * describing this identity.
 339    * @see SecurityManager#checkSecurityAccess(String)
 340    */
 341   public String toString()
 342   {
 343     SecurityManager sm = System.getSecurityManager();
 344     if (sm != null)
 345       sm.checkSecurityAccess("printIdentity");
 346
 347     /* TODO: Insert proper format here */
 348     return (name + ":@" + scope + " Public Key: " + publicKey);
 349   }
 350
 351   /**
 352    * <p>Returns a string representation of this identity, with optionally more
 353    * details than that provided by the <code>toString()</code> method without
 354    * any arguments.</p>
 355    *
 356    * <p>First, if there is a security manager, its <code>checkSecurityAccess()
 357    * </code> method is called with <code>"printIdentity"</code> as its argument
 358    * to see if it's ok to return the string.</p>
 359    *
 360    * @param detailed whether or not to provide detailed information.
 361    * @return information about this identity. If detailed is <code>true</code>,
 362    * then this method returns more information than that provided by the
 363    * <code>toString()</code> method without any arguments.
 364    * @throws SecurityException if a security manager exists and its
 365    * <code>checkSecurityAccess()</code> method doesn't allow returning a string
 366    * describing this identity.
 367    * @see #toString()
 368    * @see SecurityManager#checkSecurityAccess(String)
 369    */
 370   public String toString(boolean detailed)
 371   {
 372     SecurityManager sm = System.getSecurityManager();
 373     if (sm != null)
 374       sm.checkSecurityAccess("printIdentity");
 375
 376     if (detailed)
 377       {
 378         /* TODO: Insert proper detailed format here */
 379         return (name + ":@" + scope + " Public Key: " + publicKey);
 380       }
 381     else
 382       {
 383         /* TODO: Insert proper format here */
 384         return (name + ":@" + scope + " Public Key: " + publicKey);
 385       }
 386   }
 387
 388   /**
 389    * Returns a hashcode for this identity.
 390    *
 391    * @return a hashcode for this identity.
 392    */
 393   public int hashCode()
 394   {
 395     int ret = name.hashCode();
 396     if (publicKey != null)
 397       ret |= publicKey.hashCode();
 398     if (scope != null)
 399       ret |= scope.hashCode();
 400     if (info != null)
 401       ret |= info.hashCode();
 402     if (certificates != null)
 403       ret |= certificates.hashCode();
 404
 405     return ret;
 406   }
 407 }