Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.able.platform
Class RMIVerifiableNamingSystem

    java.lang.Object
      java.rmi.server.RemoteObject
          org.jagent.service.util.RMIBasicService
              com.ibm.able.platform.AbleBasicService
                  com.ibm.able.platform.RMIVerifiableNamingSystem

All Implemented Interfaces:
  AblePersistenceSupportProcessor, org.jagent.service.IPService, java.rmi.Remote, RmiAblePlatformService, RmiAblePlatformServiceEventGenerator, org.jagent.service.RMIService, RMIVerifiableNamingService, java.io.Serializable, javax.agent.service.Service

public final class RMIVerifiableNamingSystem
extends AbleBasicService
implements RMIVerifiableNamingService, AblePersistenceSupportProcessor

The RMIVerifiableNamingSystem is a remote object that implements the RMIVerifiableNamingService interface. This class creates VerifiableAgentNameImpl objects and returns them to callers wrapped in serialized JGSS encoded byte[].

This object also serves as the "Certificate Authority" or trusted third party in a secure platform. It hands out VerifiableAgentNames (VAN)s that act like a certificate. These will be used for authentication and authorization throughout the platform. To authenticate a VAN, use the secure "isVerified" method. This V-ANS keeps track of all VANs it has handed out. It will verify that a VAN has not been tampered with or altered in any way since it was created. If this is the case, the VAN is considered verified.

Another verify method should be used when verifying VANs that are inside an AbleSecureKey. An expiraitonID will also be used to guarantee that this key has not already been used.

The getExpirationID method is used to get an ExpirationID to match your VAN. It should then be used to create AbleSecureKeys to make secure calls.

The releaseAgentName method is called when a VAN is being discared, and should no longer be used for authentication or authorization.

The other secure method is pushAndPull. This is only used to set up a secure context between this VerifiableAgentNamingService and the entity asking for the VAN, to create the actual VAN, and to verify the VAN later on. This uses JGSS to secure this communication. Once a VAN is received, that entity should use that VAN inside an AbleSecureKey to secure communication.

An AbleSecureKey is used to wrapper a VAN along with an expirationID that this service will keep track of. If someone wanted to call a secure method, they would first ask for an expirationID from this Service. This Service would create one and remember that it belongs to the VAN used to ask for it. The VAN and expirationID would then be placed into an AbleSecureKey and send to the secure method. That method would send the VAN and expirationID to this Service for verification. If this Service determines that the VAN and expirationID go together and that this is the first and only time this expirationID has been used, then the secure method can trust the caller.

See Also:
  Serialized Form

Field Summary

Fields inherited from class com.ibm.able.platform.AbleBasicService
`ANS_PRINCIPAL, LOCAL_PRINCIPAL, myAnsPrincipal, myKeyPair, myMsgLog, myPrincipal, mySecSppt, myServiceEventListeners, myServiceProperties, myTrcLog, myTrustLevel, myVerifiableAgentName, myVerifiableNamingService, Refreshing, REQUESTORS_PORT, Running, SOCKET_FACTORY, Terminated, Unknown`

Fields inherited from class java.rmi.server.RemoteObject
`ref`

Fields inherited from interface org.jagent.service.RMIService
`RMI, SERVICE_PROTOCOL`

Fields inherited from interface org.jagent.service.IPService
`SERVICE_HOST, SERVICE_PORT`

Constructor Summary
`RMIVerifiableNamingSystem(javax.agent.service.ServiceProperties env)` Creates a new RMIAgentNamingSystem with the given ServiceProperties.

Method Summary
`void` | `closeConversation(java.lang.String idToClose, AbleSecureKey theSecureKey)` Cleanup if a request is made to end a conversation.
`VerifiableAgentName` | `createAgentName(java.security.PublicKey publicKey, java.lang.String principal, java.lang.String vanIdentifier, AbleSecureKey secureKey)` The platform must be running secure for this method to succeed.
`javax.agent.AgentName` | `createInsecureName()` Creates a new Globally Unique Identifier, an AgentName.
`java.lang.String` | `getBindingName()` Abstract method from org.jagent.service.util.RMIBasicService.
`java.lang.String` | `getExpirationID(VerifiableAgentName van)` Get an expirationID from the VerifiableAgentNamingService that matches this VAN.
`boolean` | `isVerified(VerifiableAgentName agentName, java.lang.String expirationID)` Verifies that the VerifiableAgentName was created by this VerifiableAgentNamingService, and that it is untampered with and in the same condition as when it was created.
`java.lang.String` | `openConversation()` When this VerifiableAgentNamingService is aksed for a VerifiableAgentName,, it must use Kerberos to secure this process.
`byte[]` | `pushAndPull(java.lang.String convId, byte[] token)` This method handles the context establishment between this ANS and someone asking for a VAN.
`void` | `refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport, java.lang.Object[] persistedRecords)` Takes the persisted Objects that are read in, and sets them locally.
`void` | `releaseAgentName(AbleSecureKey theSecureKey)` This removes the VAN we created from our memory.
`void` | `terminateService(AbleSecureKey key)` Secure method the Naming Service will use to clean up it's PersistenceSupport.

Methods inherited from class com.ibm.able.platform.AbleBasicService
`addAblePlatformServiceEventListener, getAblePlatformServiceEventListeners, getState, notifyAblePlatformServiceEventListeners, removeAblePlatformServiceEventListener, setState, thenNotifyAblePlatformServiceEventListeners`

Methods inherited from class org.jagent.service.util.RMIBasicService
`bindServiceToRegistry, getServiceProperties, setServiceProperties, shutdown`

Methods inherited from class java.rmi.server.RemoteObject
`equals, getRef, hashCode, toString, toStub`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Methods inherited from interface com.ibm.able.platform.RmiAblePlatformService
`getState`

Methods inherited from interface com.ibm.able.platform.RmiAblePlatformServiceEventGenerator
`addAblePlatformServiceEventListener, getAblePlatformServiceEventListeners, removeAblePlatformServiceEventListener`

Constructor Detail

### RMIVerifiableNamingSystem

    public RMIVerifiableNamingSystem(javax.agent.service.ServiceProperties env)
                              throws java.lang.Exception

  Creates a new RMIAgentNamingSystem with the given ServiceProperties.

Parameters:
  `env` - The properties that will help define this Service.

Throws:
  `java.lang.Exception` -

  On naming errors creating this service's `VerifiableAgentName`.

  On errors looking up other required services.

Method Detail

### getBindingName

    public java.lang.String getBindingName()

  Abstract method from org.jagent.service.util.RMIBasicService.

  Returns:
    The binding name for this remote object

### terminateService

    public void terminateService(AbleSecureKey key)
                          throws AbleException,
                                 javax.agent.service.naming.NamingException

  Secure method the Naming Service will use to clean up it's PersistenceSupport. It will also attempt to clean up the GSSContexts it has created.

  Specified by:
    `terminateService` in interface `RmiAblePlatformService`
  Overrides:
    `terminateService` in class `AbleBasicService`
  Parameters:
    `key` - The key that is used to secure this communication.

  Throws:
    `AbleException` - If the caller is not authorized to make this call.

    `javax.agent.service.naming.NamingException` - On any naming error.

### refreshLocalFromPersistence

    public void refreshLocalFromPersistence(AblePersistenceSupport thePersistenceSupport,
                                            java.lang.Object[] persistedRecords)
                                     throws java.lang.Exception

  Takes the persisted Objects that are read in, and sets them locally. This Object's AblePersistenceSupport will call this method when it reads in all previously persisted VANs.

  Only the VANs that we do not have locally will be copied. Each Object in the passed in Object[] will itself be an Object[] that represents a row from the DB. Each row will hold a ((String)name)->(VAN).

  VANs are the only thing that this service will persist. GSSContexts are not serializable, thus not meant to be saved away. All existing proxies will have to initialize a new context with the V-ANS if it is ever taken down and started back up. Since contexts are not persisted, it doesn't make sense to persist convIds.

  This method is called one time during the lifetime of this AblePersistenceSupportProcessor Object. It is called the first time a successful connection is made to the PlatformPersistenceService and the persisted Objects are read in.

  Specified by:
    `refreshLocalFromPersistence` in interface `AblePersistenceSupportProcessor`
  Parameters:
    `thePersistenceSupport` - the object making the callback so that the processor can tell which AblePersistenceSupport object is making the call.

    `persistedRecords` - Object[] containing all of the rows of the table this Object persists to.

  Throws:
    `java.lang.Exception` -

    If the calling persistence support is not our local persistence support.

### openConversation

    public java.lang.String openConversation()
                                      throws java.rmi.RemoteException,
                                             javax.agent.service.naming.NamingException

  Description copied from interface: `RMIVerifiableNamingService`
  When this VerifiableAgentNamingService is aksed for a VerifiableAgentName,, it must use Kerberos to secure this process. The first thing they will do is call this method to create a context that both sides will use to securely talk to each other.

  Specified by:
    `openConversation` in interface `RMIVerifiableNamingService`
  Returns:
    String A conversation ID for the context that was created.

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

    If the platform is not secure.

    On errors creating the context credentials.

    `java.rmi.RemoteException` - On any remote error.

### pushAndPull

    public byte[] pushAndPull(java.lang.String convId,
                              byte[] token)
                       throws java.rmi.RemoteException,
                              javax.agent.service.naming.NamingException,
                              javax.agent.service.naming.NamingFailure

  Description copied from interface: `RMIVerifiableNamingService`
  This method handles the context establishment between this ANS and someone asking for a VAN. If the context is already established, it will be used for others to ask for a VAN.

  It passes GSS-encrypted, Java serialized objects as parameters.

  Specified by:
    `pushAndPull` in interface `RMIVerifiableNamingService`
  Parameters:
    `convId` - The Context that is to be use.

    `token` - Byte array stream holding the secure parameters.

  Throws:
    `javax.agent.service.naming.NamingFailure` - If the Context that is to be used does not exist.
    `javax.agent.service.naming.NamingException` -

    On any naming error.

    If the platform is not secure.

    On errors establishing a secure context.

    On errors wrapping the return message.

    `java.rmi.RemoteException` - On any remote error.

### closeConversation

    public void closeConversation(java.lang.String idToClose,
                                  AbleSecureKey theSecureKey)
                           throws java.rmi.RemoteException,
                                  javax.agent.service.naming.NamingException

  Description copied from interface: `RMIVerifiableNamingService`
  Cleanup if a request is made to end a conversation. This will close a conversation that exists in this service. The GSSContext that matches this conversation 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 `RMIVerifiableNamingService`
  Parameters:
    `idToClose` - The conversation that 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.

    `java.rmi.RemoteException` - On any remote error.

### createInsecureName

    public javax.agent.AgentName createInsecureName()

  Description copied from interface: `RMIVerifiableNamingService`
  Creates a new Globally Unique Identifier, an AgentName. Since the RMIAgentNamingServiceProxy still implements the original AgentNamingService interface, it still makes available the original createAgentName() method that returns a regular non-secure agent name. This is the method that the proxy will call on the VerifiableAgetnNamingService when createAgentName() is called.

  Specified by:
    `createInsecureName` in interface `RMIVerifiableNamingService`
  Returns:
    AgentName a unique non-secure AgentName ready for use.

### createAgentName

    public VerifiableAgentName createAgentName(java.security.PublicKey publicKey,
                                               java.lang.String principal,
                                               java.lang.String vanIdentifier,
                                               AbleSecureKey secureKey)
                                        throws java.rmi.RemoteException,
                                               javax.agent.service.naming.NamingException

  Description copied from interface: `RMIVerifiableNamingService`
  The platform must be running secure for this method to succeed.

  This will create and return a new VerifiableAgentName based off of the supplied parameters.

  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.

  Specified by:
    `createAgentName` in interface `RMIVerifiableNamingService`
  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` -

    If the platform is not secure.

    If the caller is not authenticated.

    If the requesting VAN is does not belong to one of the platform VMs.

    If the public key or principal is null.

    On any error creating the VerifiableAgentName.

    `java.rmi.RemoteException` - On any remote error.

### releaseAgentName

    public void releaseAgentName(AbleSecureKey theSecureKey)
                          throws java.rmi.RemoteException,
                                 javax.agent.service.naming.NamingException

  Description copied from interface: `RMIVerifiableNamingService`
  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 `RMIVerifiableNamingService`
  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.

    `java.rmi.RemoteException` - On any remote error.

### isVerified

    public boolean isVerified(VerifiableAgentName agentName,
                              java.lang.String expirationID)

  Description copied from interface: `RMIVerifiableNamingService`
  Verifies that the VerifiableAgentName was created by this VerifiableAgentNamingService, and that it is untampered with and in the same condition as when it was created.

  It just makes sure that the VAN and all nested VANs inside it are untampered with since they were created here.

  If any of the nested VANs do not verify, then this VAN does not verify.

  Specified by:
    `isVerified` in interface `RMIVerifiableNamingService`
  Parameters:
    `agentName` - The VerifiableAgentName to be verified.

    `expirationID` - When verifying a VAN inside an AbleSecureKey, this expiration ID will be included so the V-ANS will be able to determine if the AbleSecureKey has expired.

  Returns:
    true if the VerifiableAgentName is verified, falseotherwise.

### getExpirationID

    public java.lang.String getExpirationID(VerifiableAgentName van)
                                     throws java.rmi.RemoteException,
                                            javax.agent.service.naming.NamingException

  Description copied from interface: `RMIVerifiableNamingService`
  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 `RMIVerifiableNamingService`
  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` - If `van` is not verified.
    `java.rmi.RemoteException` - On any remote error.

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005