java.security

Class Identity

Implemented Interfaces:
Principal, Serializable
Known Direct Subclasses:
IdentityScope, Signer

public abstract class Identity
extends Object
implements Principal, Serializable

This class represents identities: real-world objects such as people, companies or organizations whose identities can be authenticated using their public keys. Identities may also be more abstract (or concrete) constructs, such as daemon threads or smart cards.

All Identity objects have a name and a public key. Names are immutable. Identities may also be scoped. That is, if an Identity is specified to have a particular scope, then the name and public key of the Identity are unique within that scope.

An Identity also has a set of certificates (all certifying its own public key). The Principal names specified in these certificates need not be the same, only the key.

An Identity can be subclassed, to include postal and email addresses, telephone numbers, images of faces and logos, and so on.

See Also:
IdentityScope, Signer, Principal, Serialized Form

Constructor Summary

Identity()
Constructor for serialization only.
Identity(String name)
Constructs an identity with the specified name and no scope.
Identity(String name, IdentityScope scope)
Constructs an identity with the specified name and scope.

Method Summary

void
addCertificate(Certificate certificate)
Adds a certificate for this identity.
Certificate[]
certificates()
Returns a copy of all the certificates for this identity.
boolean
equals(Object identity)
Tests for equality between the specified object and this identity.
String
getInfo()
Returns general information previously specified for this identity.
String
getName()
Returns this identity's name.
PublicKey
getPublicKey()
Returns this identity's public key.
IdentityScope
getScope()
Returns this identity's scope.
int
hashCode()
Returns a hashcode for this identity.
protected boolean
identityEquals(Identity identity)
Tests for equality between the specified identity and this identity.
void
removeCertificate(Certificate certificate)
Removes a certificate from this identity.

First, if there is a security manager, its checkSecurityAccess() method is called with "removeIdentityCertificate" as its argument to see if it's ok to remove a certificate.

void
setInfo(String info)
Specifies a general information string for this identity.

First, if there is a security manager, its checkSecurityAccess() method is called with "setIdentityInfo" as its argument to see if it's ok to specify the information string.

void
setPublicKey(PublicKey key)
Sets this identity's public key.
String
toString()
Returns a short string describing this identity, telling its name and its scope (if any).

First, if there is a security manager, its checkSecurityAccess() method is called with "printIdentity" as its argument to see if it's ok to return the string.

String
toString(boolean detailed)
Returns a string representation of this identity, with optionally more details than that provided by the toString() method without any arguments.

First, if there is a security manager, its checkSecurityAccess() method is called with "printIdentity" as its argument to see if it's ok to return the string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Identity

protected Identity()
Constructor for serialization only.

Identity

public Identity(String name)
Constructs an identity with the specified name and no scope.
Parameters:
name - the identity name.

Identity

public Identity(String name,
                IdentityScope scope)
            throws KeyManagementException
Constructs an identity with the specified name and scope.
Parameters:
name - the identity name.
scope - the scope of the identity.
Throws:
KeyManagementException - if there is already an identity with the same name in the scope.

Method Details

addCertificate

public void addCertificate(Certificate certificate)
            throws KeyManagementException
Adds a certificate for this identity. If the identity has a public key, the public key in the certificate must be the same, and if the identity does not have a public key, the identity's public key is set to be that specified in the certificate.

First, if there is a security manager, its checkSecurityAccess() method is called with "addIdentityCertificate" as its argument to see if it's ok to add a certificate.

Parameters:
certificate - the certificate to be added.
Throws:
KeyManagementException - if the certificate is not valid, if the public key in the certificate being added conflicts with this identity's public key, or if another exception occurs.
SecurityException - if a security manager exists and its checkSecurityAccess() method doesn't allow adding a certificate.

certificates

public Certificate[] certificates()
Returns a copy of all the certificates for this identity.
Returns:
a copy of all the certificates for this identity.

equals

public final boolean equals(Object identity)
Tests for equality between the specified object and this identity. This first tests to see if the entities actually refer to the same object, in which case it returns true. Next, it checks to see if the entities have the same name and the same scope. If they do, the method returns true. Otherwise, it calls identityEquals(), which subclasses should override.
Specified by:
equals in interface Principal
Overrides:
equals in interface Object
Parameters:
identity - the object to test for equality with this identity.
Returns:
true if the objects are considered equal, false otherwise.

getInfo

public String getInfo()
Returns general information previously specified for this identity.
Returns:
general information about this identity.

getName

public final String getName()
Returns this identity's name.
Specified by:
getName in interface Principal
Returns:
the name of this identity.

getPublicKey

public PublicKey getPublicKey()
Returns this identity's public key.
Returns:
the public key for this identity.

getScope

public final IdentityScope getScope()
Returns this identity's scope.
Returns:
the scope of this identity.

hashCode

public int hashCode()
Returns a hashcode for this identity.
Specified by:
hashCode in interface Principal
Overrides:
hashCode in interface Object
Returns:
a hashcode for this identity.

identityEquals

protected boolean identityEquals(Identity identity)
Tests for equality between the specified identity and this identity. This method should be overriden by subclasses to test for equality. The default behavior is to return true if the names and public keys are equal.
Parameters:
identity - the identity to test for equality with this identity.
Returns:
true if the identities are considered equal, false otherwise.

removeCertificate

public void removeCertificate(Certificate certificate)
            throws KeyManagementException
Removes a certificate from this identity.

First, if there is a security manager, its checkSecurityAccess() method is called with "removeIdentityCertificate" as its argument to see if it's ok to remove a certificate.

Parameters:
certificate - the certificate to be removed.
Throws:
KeyManagementException - if the certificate is missing, or if another exception occurs.
SecurityException - if a security manager exists and its checkSecurityAccess() method doesn't allow removing a certificate.

setInfo

public void setInfo(String info)
Specifies a general information string for this identity.

First, if there is a security manager, its checkSecurityAccess() method is called with "setIdentityInfo" as its argument to see if it's ok to specify the information string.

Parameters:
info - the information string.
Throws:
SecurityException - if a security manager exists and its checkSecurityAccess() method doesn't allow setting the information string.

setPublicKey

public void setPublicKey(PublicKey key)
            throws KeyManagementException
Sets this identity's public key. The old key and all of this identity's certificates are removed by this operation.

First, if there is a security manager, its checkSecurityAccess() method is called with "setIdentityPublicKey" as its argument to see if it's ok to set the public key.

Parameters:
key - the public key for this identity.
Throws:
KeyManagementException - if another identity in the identity's scope has the same public key, or if another exception occurs.
SecurityException - if a security manager exists and its checkSecurityAccess() method doesn't allow setting the public key.

toString

public String toString()
Returns a short string describing this identity, telling its name and its scope (if any).

First, if there is a security manager, its checkSecurityAccess() method is called with "printIdentity" as its argument to see if it's ok to return the string.

Specified by:
toString in interface Principal
Overrides:
toString in interface Object
Returns:
information about this identity, such as its name and the name of its scope (if any).
Throws:
SecurityException - if a security manager exists and its checkSecurityAccess() method doesn't allow returning a string describing this identity.

toString

public String toString(boolean detailed)
Returns a string representation of this identity, with optionally more details than that provided by the toString() method without any arguments.

First, if there is a security manager, its checkSecurityAccess() method is called with "printIdentity" as its argument to see if it's ok to return the string.

Parameters:
detailed - whether or not to provide detailed information.
Returns:
information about this identity. If detailed is true, then this method returns more information than that provided by the toString() method without any arguments.
Throws:
SecurityException - if a security manager exists and its checkSecurityAccess() method doesn't allow returning a string describing this identity.

Identity.java --- Identity Class Copyright (C) 1999, 2003, Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.