org.cougaar.core.service.identity
Interface AgentIdentityService

All Superinterfaces:

org.cougaar.core.component.Service

public interface AgentIdentityService
extends org.cougaar.core.component.Service

This service is used by agents to obtain a cryptographic identity and transfer this identity if the agent moves.

The requestor must implement AgentIdentityClient.

Method Summary

void	acquire(TransferableIdentity id) Creates a cryptographic identity for an agent.
void	release() Notifies the cryptographic service that the cryptographic identity of the requestor is no longer needed.
TransferableIdentity	transferTo(MessageAddress targetNode) Notify the cryptographic service that an agent is about to move to another node.

Method Detail

acquire

void acquire(TransferableIdentity id)
             throws PendingRequestException,
                    IdentityDeniedException

Creates a cryptographic identity for an agent. This method is called by Cougaar core services before an agent is initialized.

If the agent already has a cryptographic identity, the method returns immediately. If the agent does not have a cryptographic key, or if no key is valid, a new key is created.

This service provider will call checkPermission() to make sure that only known entities will call the service.

If the 'id' parameter is not null, the cryptographic service attempts to install keys from an agent that was previously running on a remote node. The 'id' parameter should be the TransferableIdentity object that was returned on the original host when transferTo() was called. The TransferableIdentity should then have been sent to the new host when the agent was moved.

Parameters:

id - the identity of an agent that was moved from another node.

Throws:

PendingRequestException - the certificate authority did not sign the request immediately. The same request should be sent again later

IdentityDeniedException - the certificiate authority refused to sign the key

release

void release()

Notifies the cryptographic service that the cryptographic identity of the requestor is no longer needed. This does not mean the key should be revoked or deleted. The key is not used until the agent is restarted.

transferTo

TransferableIdentity transferTo(MessageAddress targetNode)

Notify the cryptographic service that an agent is about to move to another node. Depending on the cryptographic policy:

 - Wrap agent key pair and protect it with remote node public key
 - Revoke agent key (remote node must create a new key)
 

Parameters:

targetNode - the name of the remote NodeAgentagent where the agent will be run next.

Returns:

an encrypted object that should be sent to the remote node agent