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

com.ibm.able.platform
Interface VerifiableAgentNamingService

All Superinterfaces:
AblePlatformService, AblePlatformServiceEventGenerator, javax.agent.service.naming.AgentNamingService, javax.agent.service.Service
All Known Implementing Classes:
RMIVerifiableNamingProxy

public interface VerifiableAgentNamingService
extends javax.agent.service.naming.AgentNamingService, AblePlatformService

An agent name is said to be verifiable if it holds a private key that matches a public key which the VerifiableAgentNamingService holds onto and trusts.

An implementation of this VerifiableAgentNamingService interface can be used to work with these VerifiableAgentNames by creating, verifying and releasing the VerifiableAgentNames. An Expiration ID can also be received that will be used in AbleSecureKeys to guarantee that they are not reused.


Field Summary
static java.lang.String[] NAMING_SERVICE_COLUMN_NAMES
          Defined the column names and type for the table the Naming Service will persist to.
static java.lang.String[] NAMING_SERVICE_COLUMN_TYPES
           
static java.lang.String SERVICE_PATH
          The well-known service path.
 
Fields inherited from interface javax.agent.service.naming.AgentNamingService
SERVICE_TYPE
 
Method Summary
 void closeConversation(java.lang.String principal, AbleSecureKey key)
          Cleanup if a request is made to end a conversation.
 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.lang.String getExpirationID(VerifiableAgentName van)
          Get an expirationID from the VerifiableAgentNamingService that matches this VAN.
 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.
 
Methods inherited from interface javax.agent.service.naming.AgentNamingService
createAgentName
 
Methods inherited from interface javax.agent.service.Service
getServiceProperties, setServiceProperties
 
Methods inherited from interface com.ibm.able.platform.AblePlatformService
terminateService
 
Methods inherited from interface com.ibm.able.platform.AblePlatformServiceEventGenerator
addAblePlatformServiceEventListener, getAblePlatformServiceEventListeners, removeAblePlatformServiceEventListener
 

Field Detail

SERVICE_PATH

public static final java.lang.String SERVICE_PATH
The well-known service path.

NAMING_SERVICE_COLUMN_NAMES

public static final java.lang.String[] NAMING_SERVICE_COLUMN_NAMES
Defined the column names and type for the table the Naming Service will persist to. It will take an object, a VerifiableAgentName

NAMING_SERVICE_COLUMN_TYPES

public static final java.lang.String[] NAMING_SERVICE_COLUMN_TYPES
Method Detail

createAgentName

public VerifiableAgentName createAgentName(java.security.PublicKey publicKey,
                                           java.lang.String principal,
                                           java.lang.String vanIdentifier)
                                    throws javax.agent.service.naming.NamingException,
                                           javax.agent.service.naming.NamingFailure
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.

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

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

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

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

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.


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

(C) Copyright IBM Corporation 1999, 2003