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 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).
`static boolean` | `lowerTrustLevelLogged(VerifiableAgentName theVerifiableAgentName, AbleSecureKey theSecureKey, java.lang.String theAction)` Checks the primordial TrustLevel in the SecureKey to see whether it is lower than the TrustLevel of the passed in VerifiableAgentName's TrustLevel.
`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).
`static void` | `verifyTrustLevel(VerifiableAgentName theVerifiableAgentName, 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

### lowerTrustLevelLogged

    public static boolean lowerTrustLevelLogged(VerifiableAgentName theVerifiableAgentName,
                                                AbleSecureKey theSecureKey,
                                                java.lang.String theAction)

  Checks the primordial TrustLevel in the SecureKey to see whether it is lower than the TrustLevel of the passed in VerifiableAgentName's TrustLevel.

  If the primordial TrustLevel is lower, it means that somebody at the bottom of the chain is less trustworthy than the VerifiableAgentName. 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 the VerifiableAgentName's trust level, allow the action by returning the proper indication to the calling method.

  Parameters:
    `theVerifiableAgentName` - a VerifiableAgentName that a key will be compared against.

    `theSecureKey` - a secure key which is to be validated against the passed in VerifiableAgentName 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 key's trust level is lower than the VerifaibleAgentName's trust level and the attempted action has been logged. If the key's trust level is as good or better than the VerifiableAgentName's trust level and the requested action can proceed, false is returned.

### verifyTrustLevel

    public static void verifyTrustLevel(VerifiableAgentName theVerifiableAgentName,
                                        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 VerifiableAgentName. Log the attempt, and throw an exception.

  If the primordial trust level is greater than or equal to the VerifiableAgentName's trust level, allow the action by doing nothing.

  Parameters:
    `theVerifiableAgentName` - a VerifiableAgentName that a key will be compared against.

    `theSecureKey` - a secure key which is to be validated against the passed in VerifiableAgentName 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 key's trust level is lower than the VerifiableAgentName's trust level.

### 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.
  Throws:
    `javax.agent.service.naming.NamingException`

### 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.
  Throws:
    `javax.agent.service.naming.NamingException`

### 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.
    `javax.agent.service.naming.NamingException`

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

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