home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / security / Identity.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  13.7 KB  |  475 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Identity.java    1.51 98/09/24
  3.  *
  4.  * Copyright 1996-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.security;
  16.  
  17. import java.io.Serializable;
  18. import java.util.*;
  19.  
  20. /**
  21.  * <p>This class represents identities: real-world objects such as people,
  22.  * companies or organizations whose identities can be authenticated using 
  23.  * their public keys. Identities may also be more abstract (or concrete) 
  24.  * constructs, such as daemon threads or smart cards.
  25.  *
  26.  * <p>All Identity objects have a name and a public key. Names are
  27.  * immutable. Identities may also be scoped. That is, if an Identity is
  28.  * specified to have a particular scope, then the name and public
  29.  * key of the Identity are unique within that scope.
  30.  *
  31.  * <p>An Identity also has a set of certificates (all certifying its own
  32.  * public key). The Principal names specified in these certificates need 
  33.  * not be the same, only the key.
  34.  *
  35.  * <p>An Identity can be subclassed, to include postal and email addresses,
  36.  * telephone numbers, images of faces and logos, and so on.
  37.  *
  38.  * @see IdentityScope
  39.  * @see Signer
  40.  * @see Principal
  41.  *
  42.  * @version 1.51
  43.  * @author Benjamin Renaud
  44.  * @deprecated This class is no longer used. Its functionality has been
  45.  * replaced by <code>java.security.KeyStore</code>, the
  46.  * <code>java.security.cert</code> package, and
  47.  * <code>java.security.Principal</code>.
  48.  */
  49.  
  50. public abstract class Identity implements Principal, Serializable {
  51.  
  52.     /** use serialVersionUID from JDK 1.1.x for interoperability */
  53.     private static final long serialVersionUID = 3609922007826600659L;
  54.  
  55.     /**
  56.      * The name for this identity.
  57.      *
  58.      * @serial
  59.      */
  60.     private String name;
  61.  
  62.     /**
  63.      * The public key for this identity.
  64.      *
  65.      * @serial
  66.      */
  67.     private PublicKey publicKey;
  68.  
  69.     /**
  70.      * Generic, descriptive information about the identity.
  71.      *
  72.      * @serial
  73.      */
  74.     String info = "No further information available.";
  75.  
  76.     /**
  77.      * The scope of the identity.
  78.      *
  79.      * @serial
  80.      */
  81.     IdentityScope scope;
  82.  
  83.     /**
  84.      * The certificates for this identity.
  85.      *
  86.      * @serial
  87.      */
  88.     Vector certificates;
  89.  
  90.     /**
  91.      * Constructor for serialization only.
  92.      */
  93.     protected Identity() {
  94.     this("restoring...");
  95.     }
  96.  
  97.     /**
  98.      * Constructs an identity with the specified name and scope.
  99.      *
  100.      * @param name the identity name.  
  101.      * @param scope the scope of the identity.
  102.      *
  103.      * @exception KeyManagementException if there is already an identity 
  104.      * with the same name in the scope.
  105.      */
  106.     public Identity(String name, IdentityScope scope) throws
  107.     KeyManagementException {
  108.     this(name);
  109.     this.scope = scope;
  110.     }
  111.  
  112.     /**
  113.      * Constructs an identity with the specified name and no scope.
  114.      *
  115.      * @param name the identity name.
  116.      */
  117.     public Identity(String name) {
  118.     this.name = name;
  119.     }
  120.  
  121.     /**
  122.      * Returns this identity's name.
  123.      *
  124.      * @return the name of this identity.
  125.      */
  126.     public final String getName() {
  127.     return name;
  128.     }
  129.  
  130.     /**
  131.      * Returns this identity's scope.
  132.      *
  133.      * @return the scope of this identity.
  134.      */
  135.     public final IdentityScope getScope() {
  136.     return scope;
  137.     }
  138.  
  139.     /**
  140.      * Returns this identity's public key.
  141.      * 
  142.      * @return the public key for this identity.
  143.      */
  144.     public PublicKey getPublicKey() {
  145.     return publicKey;
  146.     }
  147.  
  148.     /**
  149.      * Sets this identity's public key. The old key and all of this
  150.      * identity's certificates are removed by this operation. 
  151.      *
  152.      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code> 
  153.      * method is called with <code>"setIdentityPublicKey"</code> 
  154.      * as its argument to see if it's ok to set the public key. 
  155.      * 
  156.      * @param key the public key for this identity.
  157.      *
  158.      * @exception KeyManagementException if another identity in the 
  159.      * identity's scope has the same public key, or if another exception occurs.  
  160.      * 
  161.      * @exception  SecurityException  if a security manager exists and its  
  162.      * <code>checkSecurityAccess</code> method doesn't allow 
  163.      * setting the public key.
  164.      * 
  165.      * @see SecurityManager#checkSecurityAccess
  166.      */
  167.     /* Should we throw an exception if this is already set? */
  168.     public void setPublicKey(PublicKey key) throws KeyManagementException {
  169.  
  170.     check("setIdentityPublicKey");
  171.     this.publicKey = key;
  172.     certificates = new Vector();
  173.     }
  174.  
  175.     /**
  176.      * Specifies a general information string for this identity.
  177.      *
  178.      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code> 
  179.      * method is called with <code>"setIdentityInfo"</code> 
  180.      * as its argument to see if it's ok to specify the information string. 
  181.      * 
  182.      * @param info the information string.
  183.      * 
  184.      * @exception  SecurityException  if a security manager exists and its  
  185.      * <code>checkSecurityAccess</code> method doesn't allow 
  186.      * setting the information string.
  187.      * 
  188.      * @see #getInfo
  189.      * @see SecurityManager#checkSecurityAccess
  190.      */
  191.     public void setInfo(String info) {
  192.     check("setIdentityInfo");
  193.     this.info = info;
  194.     }
  195.  
  196.     /**
  197.      * Returns general information previously specified for this identity.
  198.      *
  199.      * @return general information about this identity.
  200.      *
  201.      * @see #setInfo
  202.      */
  203.     public String getInfo() {
  204.     return info;
  205.     }
  206.  
  207.     /**
  208.      * Adds a certificate for this identity. If the identity has a public
  209.      * key, the public key in the certificate must be the same, and if
  210.      * the identity does not have a public key, the identity's
  211.      * public key is set to be that specified in the certificate.
  212.      *
  213.      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code> 
  214.      * method is called with <code>"addIdentityCertificate"</code> 
  215.      * as its argument to see if it's ok to add a certificate. 
  216.      * 
  217.      * @param certificate the certificate to be added.
  218.      *
  219.      * @exception KeyManagementException if the certificate is not valid,
  220.      * if the public key in the certificate being added conflicts with
  221.      * this identity's public key, or if another exception occurs.
  222.      * 
  223.      * @exception  SecurityException  if a security manager exists and its  
  224.      * <code>checkSecurityAccess</code> method doesn't allow 
  225.      * adding a certificate.
  226.      * 
  227.      * @see SecurityManager#checkSecurityAccess
  228.      */
  229.     public void addCertificate(Certificate certificate)
  230.     throws KeyManagementException {
  231.  
  232.     check("addIdentityCertificate");
  233.  
  234.     if (certificates == null) {
  235.         certificates = new Vector();
  236.     }
  237.     if (publicKey != null) {
  238.         if (!keyEquals(publicKey, certificate.getPublicKey())) {
  239.         throw new KeyManagementException(
  240.             "public key different from cert public key");
  241.         }
  242.     } else {
  243.         publicKey = certificate.getPublicKey();
  244.     }
  245.     certificates.addElement(certificate);
  246.     }
  247.  
  248.    private boolean keyEquals(Key aKey, Key anotherKey) {
  249.     if (aKey.getFormat().equalsIgnoreCase(anotherKey.getFormat())) {
  250.         return MessageDigest.isEqual(aKey.getEncoded(), 
  251.                      anotherKey.getEncoded());
  252.     } else {
  253.         return false;
  254.     }
  255.     }
  256.  
  257.  
  258.     /**
  259.      * Removes a certificate from this identity.
  260.      *
  261.      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code> 
  262.      * method is called with <code>"removeIdentityCertificate"</code> 
  263.      * as its argument to see if it's ok to remove a certificate. 
  264.      * 
  265.      * @param certificate the certificate to be removed.
  266.      *
  267.      * @exception KeyManagementException if the certificate is
  268.      * missing, or if another exception occurs.
  269.      * 
  270.      * @exception  SecurityException  if a security manager exists and its  
  271.      * <code>checkSecurityAccess</code> method doesn't allow 
  272.      * removing a certificate.
  273.      * 
  274.      * @see SecurityManager#checkSecurityAccess
  275.      */
  276.     public void removeCertificate(Certificate certificate)
  277.     throws KeyManagementException {
  278.     check("removeIdentityCertificate");
  279.     if (certificates != null) {
  280.         certificates.removeElement(certificate);
  281.     }
  282.     }
  283.  
  284.     /**
  285.      * Returns a copy of all the certificates for this identity.  
  286.      * 
  287.      * @return a copy of all the certificates for this identity.  
  288.      */
  289.     public Certificate[] certificates() {
  290.     if (certificates == null) {
  291.         return new Certificate[0];
  292.     }
  293.     int len = certificates.size();
  294.     Certificate[] certs = new Certificate[len];
  295.     certificates.copyInto(certs);
  296.     return certs;
  297.     }
  298.  
  299.     /**
  300.      * Tests for equality between the specified object and this identity.
  301.      * This first tests to see if the entities actually refer to the same
  302.      * object, in which case it returns true. Next, it checks to see if
  303.      * the entities have the same name and the same scope. If they do, 
  304.      * the method returns true. Otherwise, it calls 
  305.      * {@link #identityEquals(Identity) identityEquals}, which subclasses should 
  306.      * override.
  307.      *
  308.      * @param identity the object to test for equality with this identity.  
  309.      *
  310.      * @return true if the objects are considered equal, false otherwise.
  311.      *
  312.      * @see #identityEquals 
  313.      */
  314.     public final boolean equals(Object identity) {
  315.  
  316.     if (identity == this) {
  317.         return true;
  318.     }
  319.  
  320.     if (identity instanceof Identity) {
  321.         Identity i = (Identity)identity;
  322.         if ((scope != null) && 
  323.         (i.getScope() == scope) && 
  324.         i.getName().equals(name)) {
  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.     return (name.equals(identity.name) && 
  348.         publicKey.equals(identity.publicKey));
  349.     }
  350.  
  351.     /**
  352.      * Returns a parsable name for identity: identityName.scopeName
  353.      */
  354.     String fullName() {
  355.     String parsable = name;
  356.     if (scope != null) {
  357.         parsable += "." + scope.getName();
  358.     }
  359.     return parsable;
  360.     }
  361.  
  362.     /**
  363.      * Returns a short string describing this identity, telling its
  364.      * name and its scope (if any).
  365.      *
  366.      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code> 
  367.      * method is called with <code>"printIdentity"</code> 
  368.      * as its argument to see if it's ok to return the string. 
  369.      *
  370.      * @return information about this identity, such as its name and the  
  371.      * name of its scope (if any).
  372.      * 
  373.      * @exception  SecurityException  if a security manager exists and its  
  374.      * <code>checkSecurityAccess</code> method doesn't allow 
  375.      * returning a string describing this identity.
  376.      * 
  377.      * @see SecurityManager#checkSecurityAccess
  378.      */
  379.     public String toString() {
  380.     check("printIdentity");
  381.     String printable = name;
  382.     if (scope != null) {
  383.         printable += "[" + scope.getName() + "]";
  384.     }
  385.     return printable;
  386.     }
  387.  
  388.     /**
  389.      * Returns a string representation of this identity, with
  390.      * optionally more details than that provided by the
  391.      * <code>toString</code> method without any arguments.
  392.      *
  393.      * <p>First, if there is a security manager, its <code>checkSecurityAccess</code> 
  394.      * method is called with <code>"printIdentity"</code> 
  395.      * as its argument to see if it's ok to return the string. 
  396.      *
  397.      * @param detailed whether or not to provide detailed information.  
  398.      *
  399.      * @return information about this identity. If <code>detailed</code>
  400.      * is true, then this method returns more information than that 
  401.      * provided by the <code>toString</code> method without any arguments.
  402.      *
  403.      * @exception  SecurityException  if a security manager exists and its  
  404.      * <code>checkSecurityAccess</code> method doesn't allow 
  405.      * returning a string describing this identity.
  406.      * 
  407.      * @see #toString
  408.      * @see SecurityManager#checkSecurityAccess
  409.      */
  410.     public String toString(boolean detailed) {
  411.     String out = toString();
  412.     if (detailed) {
  413.         out += "\n";
  414.         out += printKeys();
  415.         out += "\n" + printCertificates();
  416.         if (info != null) {
  417.         out += "\n\t" + info;
  418.         } else {
  419.         out += "\n\tno additional information available.";
  420.         }
  421.     }      
  422.     return out;
  423.     }
  424.  
  425.     String printKeys() {
  426.     String key = "";
  427.     if (publicKey != null) {
  428.         key = "\tpublic key initialized";
  429.     } else {
  430.         key = "\tno public key";
  431.     }
  432.     return key;
  433.     }
  434.  
  435.     String printCertificates() {
  436.     String out = "";
  437.     if (certificates == null) {
  438.         return "\tno certificates";
  439.     } else {
  440.         out += "\tcertificates: \n";
  441.         Enumeration e = certificates.elements();
  442.         int i = 1;
  443.         while (e.hasMoreElements()) {
  444.         Certificate cert = (Certificate)e.nextElement();
  445.         out += "\tcertificate " + i++ +
  446.             "\tfor  : " + cert.getPrincipal() + "\n";
  447.         out += "\t\t\tfrom : " + 
  448.             cert.getGuarantor() + "\n";
  449.         }
  450.     }
  451.     return out;
  452.     }
  453.     
  454.     /**
  455.      * Returns a hashcode for this identity.
  456.      *
  457.      * @return a hashcode for this identity.
  458.      */
  459.     public int hashCode() {
  460.     String scopedName = name;
  461.     if (scope != null) {
  462.         scopedName += scope.getName();
  463.     }
  464.     return scopedName.hashCode();
  465.     }
  466.  
  467.     private static void check(String directive) {
  468.     SecurityManager security = System.getSecurityManager();
  469.     if (security != null) {
  470.         security.checkSecurityAccess(directive);
  471.     }
  472.     }
  473. }
  474.  
  475.