Source for java.security.Identity

   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., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 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().equals(this.name)) &&
 301:         (((Identity) identity).getScope().equals(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().equals(this.name)) &&
 323:         (identity.getPublicKey().equals(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: }