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

com.ibm.able.platform
Class AbleSecuritySupport

java.lang.Object
  |
  +--com.ibm.able.platform.AbleSecuritySupport

public final class AbleSecuritySupport
extends java.lang.Object

AbleSecuritySupport is a support object that others can use to provide security for their objects.

Services, agents, and other parts of the platform may wish to provide secure methods to their users, and to help do so, a SecuritySupport object can be instantiated. A SecuritySupport object provides methods to create Able SecureKey objects and to encode and decode the contents of SecureKey objects.

Note that this object is purposely not serializable. It should be marked as "transient" in the parent container, and created or restored as necessary in the parent.


Constructor Summary
AbleSecuritySupport(java.security.KeyPair theKeyPair, VerifiableAgentName theVerifiableAgentName, VerifiableAgentNamingService theVerifiableNamingService, AbleLogger theMsgLog, AbleLogger theTrcLog)
          Creates a new AbleSecuritySupport object with the specified properties.
AbleSecuritySupport(java.security.KeyPair theKeyPair, VerifiableAgentName theVerifiableAgentName, VerifiableAgentNamingService theVerifiableNamingService, AbleLogger theMsgLog, AbleLogger theTrcLog, java.lang.String theCryptographyAlgorithm, java.lang.String theCryptographyProvider)
          Creats a new AbleSecuritySupport object with the specified properties; this form allows the cryptography algorithm and cryptography provider to be overridden, rather than defaulting to the values specified in the AblePlatform object.
 
Method Summary
 AbleSecureKey generateKey()
          Generates and returns an Able SecureKey using the verifiable agent name and private key specified when this security support object was created.
 AbleSecureKey generateKey(AbleSecureKey theSecureKey)
          Generates and returns an Able SecureKey using the verifiable agent name and private key specified when this security support object was created; also, sets the new key's previous verifiable agent name from the one contained in the specified secure key.
 boolean lowerTrustLevelLogged(AbleSecureKey theSecureKey, java.lang.String theAction)
          Checks the primordial TrustLevel in the SecureKey to see whether it is lower than the TrustLevel of the support object's parent container TrustLevel (taken from the VerifiableAgentName of the parent container).
 void verifyKey(AbleSecureKey theSecureKey)
          Verifies that the specified AbleSecureKey is not null and that the key verifies with the Verifiable Agent Naming Service.
 void verifyKeyExists(AbleSecureKey theSecureKey)
          Verifiesthat the specified AbleSecureKey is not null.
 void verifyTrustLevel(AbleSecureKey theSecureKey, java.lang.String theAction)
          Checks the primordial TrustLevel in the SecureKey to see whether it is lower than the TrustLevel of the support object's parent container TrustLevel (taken from the VerifiableAgentName of the parent container).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbleSecuritySupport

public AbleSecuritySupport(java.security.KeyPair theKeyPair,
                           VerifiableAgentName theVerifiableAgentName,
                           VerifiableAgentNamingService theVerifiableNamingService,
                           AbleLogger theMsgLog,
                           AbleLogger theTrcLog)
Creates a new AbleSecuritySupport object with the specified properties.
Parameters:
theKeyPair - The parent container's KeyPair, used to secure information within an Able secure key.

theVerifiableAgentName - The parent container's verifiable agent name.

theVerifiableNamingService - A reference to the verifiable naming service so that verifiable agent names can be verified.

theMsgLog - A reference to an ABLE logger that can be used to log informational, warning, and error messages.

theTrcLog - A reference to an ABLE logger that can be used to log debugging and trace statements.


AbleSecuritySupport

public AbleSecuritySupport(java.security.KeyPair theKeyPair,
                           VerifiableAgentName theVerifiableAgentName,
                           VerifiableAgentNamingService theVerifiableNamingService,
                           AbleLogger theMsgLog,
                           AbleLogger theTrcLog,
                           java.lang.String theCryptographyAlgorithm,
                           java.lang.String theCryptographyProvider)
Creats a new AbleSecuritySupport object with the specified properties; this form allows the cryptography algorithm and cryptography provider to be overridden, rather than defaulting to the values specified in the AblePlatform object.
Parameters:
theKeyPair - The parent container's KeyPair, used to secure information within an Able secure key.

theVerifiableAgentName - The parent container's verifiable agent name.

theVerifiableNamingService - A reference to the verifiable naming service so that verifiable agent names can be verified.

theMsgLog - A reference to an ABLE logger that can be used to log informational, warning, and error messages.

theTrcLog - A reference to an ABLE logger that can be used to log debugging and trace statements.

theCryptographyAlgorithm - A cryptography algorthim.

theCryptographyProvider - A cryptography provider.

Method Detail

generateKey

public AbleSecureKey generateKey()
                          throws javax.agent.service.naming.NamingException
Generates and returns an Able SecureKey using the verifiable agent name and private key specified when this security support object was created.
Returns:
a valid Able secure key, or null if a NamingException is caught whilst generating the key.

generateKey

public AbleSecureKey generateKey(AbleSecureKey theSecureKey)
                          throws javax.agent.service.naming.NamingException
Generates and returns an Able SecureKey using the verifiable agent name and private key specified when this security support object was created; also, sets the new key's previous verifiable agent name from the one contained in the specified secure key.
Parameters:
theSecureKey - a secure key from which a verifiable agent name is extracted and then placed into a new secure key as the previous verifiable agent name.

Returns:
a valid Able secure key, or null if a NamingException is caught whilst generating the key.

lowerTrustLevelLogged

public boolean lowerTrustLevelLogged(AbleSecureKey theSecureKey,
                                     java.lang.String theAction)
Checks the primordial TrustLevel in the SecureKey to see whether it is lower than the TrustLevel of the support object's parent container TrustLevel (taken from the VerifiableAgentName of the parent container).

If the primordial TrustLevel is lower, it means that somebody at the bottom of the chain is less trustworthy than the parent container and is attempting to run one of my parent's secure methods. Log the attempt, and return a boolean to the caller indicating that the requested action is not to be performed.

If the primordial trust level is greater than or equal to my parent's own trust level, allow the action by returning the proper indication to the calling method.

Parameters:
theSecureKey - a secure key provided to one of the parent's target methods and which the target method wants validated with regard to trust levels.

theAction - The name of the method that the caller is trying to run. This name will show up in the message log if the action is not allowed.

Returns:
true if the requestor's trust level is lower than the parent container's trust level and the attempted action has been logged. If the requestor's trust level is as good or better than the parent container's trust level and the requested action can proceed, false is returned.

verifyTrustLevel

public void verifyTrustLevel(AbleSecureKey theSecureKey,
                             java.lang.String theAction)
                      throws AbleException
Checks the primordial TrustLevel in the SecureKey to see whether it is lower than the TrustLevel of the support object's parent container TrustLevel (taken from the VerifiableAgentName of the parent container).

If the primordial TrustLevel is lower, it means that somebody at the bottom of the chain is less trustworthy than the parent container and is attempting to run one of my parent's secure methods. Log the attempt, and throw an exception.

If the primordial trust level is greater than or equal to my parent's own trust level allow the action by doing nothing.

Parameters:
theSecureKey - a secure key provided to one of the parent's target methods and which the target method wants validated with regard to trust levels.

theAction - The name of the method that the caller is trying to run. This name will show up in the message log if the action is not allowed.

Throws:
AbleException - if the caller's trust level is lower than the parent container's trust level.

verifyKey

public void verifyKey(AbleSecureKey theSecureKey)
               throws AbleException,
                      javax.agent.service.naming.NamingException
Verifies that the specified AbleSecureKey is not null and that the key verifies with the Verifiable Agent Naming Service.
Parameters:
theSecureKey - a secure key provided to one of the parent's target methods and which the target method wants verified with the Verifiable Naming Service.

Throws:
AbleException - if there are any problems with the secure key or its contents.
NamigException - if the Verifiable Naming Service cannot verifiy the Verifiable Agent Name contained within the secure key.

verifyKeyExists

public void verifyKeyExists(AbleSecureKey theSecureKey)
                     throws AbleException
Verifiesthat the specified AbleSecureKey is not null.
Parameters:
theSecureKey - a secure key provided to one of the parent's target methods and which the target method wants to make sure that the key is not null.

Throws:
AbleException - if the secure key is null.

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

(C) Copyright IBM Corporation 1999, 2003