ABLE 2.0.0 07/02/2003 10:25:01

com.ibm.able.platform
Class RMIVerifiableNamingProxy

java.lang.Object
  |
  +--com.ibm.able.platform.RMIVerifiableNamingProxy
All Implemented Interfaces:
AblePlatformService, AblePlatformServiceEventGenerator, javax.agent.service.naming.AgentNamingService, java.io.Serializable, javax.agent.service.Service, VerifiableAgentNamingService

public class RMIVerifiableNamingProxy
extends java.lang.Object
implements VerifiableAgentNamingService, java.io.Serializable

The RMIVerifiableNamingProxy is a proxy for the RMI implementation of the AgentNamingService. Agents interact with this proxy as if they were interacting with the AgentNamingService directly. An RMIVerifiableNamingProxy contains a remote reference (i.e. a delegate) to an RMIAgentNamingService. This is where the actual work of the VerifiableNamingService takes place.

This proxy implements the VerifiableAgentNamingService interface, so it can be used to get VerifiableAgentNames. These names will be used throughout a secure platform to authenticate and authorize the holder of the VAN during secure method calls. JGSS will be used to initially authenticate the entity trying to get a VerifiableAgentName from the VerifiableNamingService.

NOTE: Part of this code take from Java documentation at http://java.sun.com/j2se/1.4/docs/api/org/ietf/jgss/GSSContext.html

See Also:
Serialized Form

Fields inherited from interface com.ibm.able.platform.VerifiableAgentNamingService
NAMING_SERVICE_COLUMN_NAMES, NAMING_SERVICE_COLUMN_TYPES, SERVICE_PATH
 
Fields inherited from interface javax.agent.service.naming.AgentNamingService
SERVICE_TYPE
 
Constructor Summary
RMIVerifiableNamingProxy(RMIVerifiableNamingService theDelegate, java.lang.String theAnsPrincipal, java.rmi.registry.Registry theRegistry, java.lang.String theAddress)
          Create a proxy over the specified RMI reference to a Verifiable Naming Service.
 
Method Summary
 void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
          Adds a service event listener to this service.
 void closeConversation(java.lang.String principal, AbleSecureKey key)
          Cleanup if a request is made to end a conversation.
static java.lang.String Copyright()
          Gets the copyright statement of this class.
 javax.agent.AgentName createAgentName()
           
 VerifiableAgentName createAgentName(java.security.PublicKey publicKey, java.lang.String principal, java.lang.String vanIdentifier)
          The platform must be running secure for this method to succeed.
 VerifiableAgentName createAgentName(java.security.PublicKey publicKey, java.lang.String principal, java.lang.String vanIdentifier, AbleSecureKey key)
          The platform must be running secure for this method to succeed.
 java.util.Vector getAblePlatformServiceEventListeners()
          Gets a collection of all service event listeners registered with this service event generator.
 java.lang.String getExpirationID(VerifiableAgentName van)
          Get an expirationID from the VerifiableAgentNamingService that matches this VAN.
 javax.agent.service.ServiceProperties getServiceProperties()
          Retrieve the service properties of the underlying service.
 boolean isVerified(VerifiableAgentName vanToVerify)
          Check if the VerifiableAgentNamingService knows of this VerifiableAgentName, and if it is valid and untampered with.
 boolean isVerified(VerifiableAgentName vanToVerify, java.lang.String expirationID)
          This isVerified version should be used when verifying a VerifiableAgentName when it is in an AbleSecureKey.
 void releaseAgentName(AbleSecureKey key)
          This removes the VAN we created from our memory.
 void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
          Removes a service event listener from this service.
 void setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties)
          Set the service properties of the underlying service.
 void terminateService(AbleSecureKey theSecureKey)
          Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.
 java.lang.String toString()
          Gets a string describing the contents of the object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RMIVerifiableNamingProxy

public RMIVerifiableNamingProxy(RMIVerifiableNamingService theDelegate,
                                java.lang.String theAnsPrincipal,
                                java.rmi.registry.Registry theRegistry,
                                java.lang.String theAddress)
Create a proxy over the specified RMI reference to a Verifiable Naming Service.
Parameters:
theDelegate - A reference to an RMI version of aa Verifiable Naming Service.

ansPrincipal - The kerberos principal of the Naming Service used to establish a context with the Naming Service.

theRegistry - The RMI registry at which the above Verifiable Naming Service is registered.

theAddress - The RMI address at which the above Verifiable Naming Service is registered.

Method Detail

createAgentName

public javax.agent.AgentName createAgentName()
                                      throws javax.agent.service.naming.NamingException,
                                             javax.agent.service.naming.NamingFailure
Specified by:
createAgentName in interface javax.agent.service.naming.AgentNamingService

createAgentName

public VerifiableAgentName createAgentName(java.security.PublicKey publicKey,
                                           java.lang.String principal,
                                           java.lang.String vanIdentifier)
                                    throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
The platform must be running secure for this method to succeed.

This method will make a GSS secured call to the RMIVerifiableAgentService and request a VerifiableAgentName.

Specified by:
createAgentName in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
publicKey - The Public Key that the new VerifiableAgentName is to be created with.

principal - The principal that the new VerifiableAgentName is to be created with, and that the GSS context should be created with.

vanIdentifier - If the new VerifiableAgentName is to be based off an existing VerifiableAgentName, this parameter can be set to identify this existing VerifiableAgentName. This will fail if the principal does not match the principal of the existing VerifiableAgentName.

Throws:
javax.agent.service.naming.NamingException - On naming errors.

If the principal is null.

If the publicKey is null.

On all errors setting up a GSS context to talk to the VerifiableAgentNamingService.

On all errors talking to the VerifiableAgentNamingService.

On errors wrapping the secure GSS messages being sent.


createAgentName

public VerifiableAgentName createAgentName(java.security.PublicKey publicKey,
                                           java.lang.String principal,
                                           java.lang.String vanIdentifier,
                                           AbleSecureKey key)
                                    throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
The platform must be running secure for this method to succeed.

This method will go to the RMIVerifiableAgentService and request a VerifiableAgentName. This should only be used by the platform pools when creating new agents.

If attempting to create a VAN whose new principal does not match the requesting VAN's principal, this will only succeed if the principal of the VAN making the request is a principal of one of the platform pools.

If you are not a platform pool, you should use the other create method: createAgentName(PublicKey, String, String).

Specified by:
createAgentName in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
publicKey - The Public Key that the new VerifiableAgentName is to be created with.

principal - The principal that the new VerifiableAgentName is to be created with. If this is not set, the principal will be the principal of the VerifiableAgentName making this call.

vanIdentifier - If the new VerifiableAgentName is to be based off an existing VerifiableAgentName, this parameter can be set to identify this existing VerifiableAgentName. This will fail if the principal does not match the principal of the existing VerifiableAgentName.

Throws:
javax.agent.service.naming.NamingException - On any naming error.

isVerified

public boolean isVerified(VerifiableAgentName vanToVerify)
                   throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
Check if the VerifiableAgentNamingService knows of this VerifiableAgentName, and if it is valid and untampered with.

This method should only be called if the platform is secure.

Specified by:
isVerified in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
vanToVerify - The VerifiableAgentName that is to be verified. This can not be null.

Returns:
boolean true if verified, otherwise false

Throws:
javax.agent.service.naming.NamingException -

If the vanToVerify is null.

On any naming error.


isVerified

public boolean isVerified(VerifiableAgentName vanToVerify,
                          java.lang.String expirationID)
                   throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
This isVerified version should be used when verifying a VerifiableAgentName when it is in an AbleSecureKey. This will not only verify the VerifiableAgentName, but also use the expirationID to guarantee that this AbleSecureKey has not already been used, and that the expirationID was assigned to this VerifiableAgentName.

This method should only be called if the platform is secure.

Specified by:
isVerified in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
vanToVerify - The VerifiableAgentName inside an AbleSecureKey that is to be verified. This can not be null.

expirationID - The expirationID inside the AbleSecureKey. This can not be null.

Returns:
boolean true if verified, otherwise false

Throws:
javax.agent.service.naming.NamingException -

If the expiration ID is null.

If the vanToVerify is null.

On any naming error.


releaseAgentName

public void releaseAgentName(AbleSecureKey key)
                      throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
This removes the VAN we created from our memory. This VAN will no longer be verified.

The VAN that will be released is the one that is signed and stored inside the theKey.

This method cannot be delegated using nested VANs inside an AbleSecureKey. The VAN that is to be released must be the one used to make the request.

Specified by:
releaseAgentName in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
theSecureKey - The AbleSecureKey that is used to secure communication. This key holds the VAN that will be released.

Throws:
javax.agent.service.naming.NamingException -

If the platform is not secure.

If the caller is not authenticated.

On any remote error.


getExpirationID

public java.lang.String getExpirationID(VerifiableAgentName van)
                                 throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
Get an expirationID from the VerifiableAgentNamingService that matches this VAN. This will then be used in an AbleSecureKey.

When the AbleSecureKey that is using this expirationID is verified, the VerifiableAgentNamingService will make sure that the expiraiton ID matches the VerifiableAgentName it was given to, and that it has not been used yet. This will prevent AbleSecureKeys from being used multiple times.

Specified by:
getExpirationID in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
van - The VerifiableAgentName that this expirationID must be used with.

Returns:
An expirationID this VerifiableAgentName can use in an AbleSecureKey.

Throws:
javax.agent.service.naming.NamingException - On any remote error.

closeConversation

public void closeConversation(java.lang.String principal,
                              AbleSecureKey key)
                       throws javax.agent.service.naming.NamingException
Description copied from interface: VerifiableAgentNamingService
Cleanup if a request is made to end a conversation. This will close a conversation that exists in this service. The GSSContext that this principal was using will be removed and disposed. Only a VerifiableAgentName that was created using this conversation will be allowed to close it.

Specified by:
closeConversation in interface VerifiableAgentNamingService
Following copied from interface: com.ibm.able.platform.VerifiableAgentNamingService
Parameters:
principal - The principal whose conversation is to be closed.

theSecureKey - AbleSecureKey used to secure communication.

Throws:
javax.agent.service.naming.NamingException -

If the platform is not secure.

If the caller is not authenticated.

If the context that is to be used does not exist.

If the caller is not authorized.

On any GSS error.


terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      throws AbleException,
                             javax.agent.service.naming.NamingException
Description copied from interface: AblePlatformService
Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.
Specified by:
terminateService in interface AblePlatformService
Following copied from interface: com.ibm.able.platform.AblePlatformService
Parameters:
theSecureKey - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.

Throws:
AbleException - On any remote error or Able error.
javax.agent.service.naming.NamingException - On any naming error.

getServiceProperties

public javax.agent.service.ServiceProperties getServiceProperties()
Retrieve the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; null is always returned.

Specified by:
getServiceProperties in interface javax.agent.service.Service
Returns:
null at all times.

setServiceProperties

public void setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties)
Set the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; the call is simply ignored.

Specified by:
setServiceProperties in interface javax.agent.service.Service
Parameters:
theServiceProperties - The service properties to be used by the service.


addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException
Description copied from interface: AblePlatformServiceEventGenerator
Adds a service event listener to this service.
Specified by:
addAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator
Following copied from interface: com.ibm.able.platform.AblePlatformServiceEventGenerator
Parameters:
theListener - Any object interested in listening for service events generated by this service.

Throws:
AbleException - On any error.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException
Description copied from interface: AblePlatformServiceEventGenerator
Removes a service event listener from this service.
Specified by:
removeAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator
Following copied from interface: com.ibm.able.platform.AblePlatformServiceEventGenerator
Parameters:
theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:
AbleException - On any error.

getAblePlatformServiceEventListeners

public java.util.Vector getAblePlatformServiceEventListeners()
                                                      throws AbleException
Description copied from interface: AblePlatformServiceEventGenerator
Gets a collection of all service event listeners registered with this service event generator.
Specified by:
getAblePlatformServiceEventListeners in interface AblePlatformServiceEventGenerator
Following copied from interface: com.ibm.able.platform.AblePlatformServiceEventGenerator
Returns:
All registered AblePlatformServiceEventListener objects.
Throws:
AbleException - On any error.

toString

public java.lang.String toString()
Gets a string describing the contents of the object.
Overrides:
toString in class java.lang.Object
Returns:
A string containing the current contents of the object.

Copyright

public static java.lang.String Copyright()
Gets the copyright statement of this class.
Returns:
this class's copyright statement.

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003