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
Interface RMIVerifiableNamingService

All Superinterfaces:
  java.rmi.Remote, RmiAblePlatformService, RmiAblePlatformServiceEventGenerator

All Known Implementing Classes:
  RMIVerifiableNamingSystem

public interface RMIVerifiableNamingService
extends java.rmi.Remote, RmiAblePlatformService

Defines the behavior of a Verifiable Naming Service. A Naming Service produces Globally Unique IDentifiers (GUIDs) or AgentNames. This interface is the network interface to the service. All traffic is encrypted using JGSS. A proxy, RMIAgentNamingServiceProxy, is the only class which speaks using this interface. This interface is the service side interface. The agent side interface is VerifiableAgentNamingService.

See Also:
  `RMIVerifiableNamingSystem`

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 theSecureKey)` 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` | `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[] tokens)` This method handles the context establishment between this ANS and someone asking for a VAN.
`void` | `releaseAgentName(AbleSecureKey theSecureKey)` This removes the VAN we created from our memory.

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

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

Method Detail

### openConversation

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

  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.

  Returns:
    String A conversation ID for the context that was created.

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

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

    If the platform is not secure.

    On errors creating the context credentials.

### pushAndPull

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

  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.

  Parameters:
    `convId` - The Context that is to be use.

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

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

    `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.

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

### closeConversation

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

  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.

  Parameters:
    `idToClose` - The conversation that is to be closed.

    `theSecureKey` - AbleSecureKey used to secure communication.

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

    `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.

### createInsecureName

    public javax.agent.AgentName createInsecureName()
                                             throws java.rmi.RemoteException

  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.

  Returns:
    AgentName a unique non-secure AgentName ready for use.

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

### createAgentName

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

  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.

  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

  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.

  Parameters:
    `theSecureKey` - The AbleSecureKey that is used to secure communication. This key holds the VAN that will be released.

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

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

    If the platform is not secure.

    If the caller is not authenticated.

### getExpirationID

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

  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.

  Parameters:
    `van` - The VerifiableAgentName that this expirationID must be used with.

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

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

    `javax.agent.service.naming.NamingException` - If `van` is not verified.

### isVerified

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

  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.

  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.

  Throws:
    `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