Package org.jcsp.net.security

# Interface SecurityAuthority

All Superinterfaces:
  `Serializable`, `ServiceUserObject`

All Known Subinterfaces:
  `SecurityService`

All Known Implementing Classes:
  `SimpleSecurityAuthority`

public interface SecurityAuthority extends ServiceUserObject, Serializable

Defines the service for dealing with authenticating users via a challenge/response scheme. Currently only one user may be logged onto the security authority at any one time. The currently logged on user will be used for creating the responses to challenges. Any number of users may be regarded as 'permitted' and any response from one of these will be considered valid.

An instance of the security authority service can be used to generate concrete user IDs and tokens when users log on. This might be a purely internally resolved scheme or perhaps be linked to information from a system level domain (eg the user's logon account).

To negotiate starting a link, the security authorities at each end should create challenges to send. The peer nodes will create responses from these challenges which indicate the log in of the user at that node. The security authority creating the challenge can then be used to validate the response determining whether the user generating the response is permitted to connect to this node.

For example:

            // Node 1                                           // Node 2
     SecurityAuthority sa = ...;                         SecurityAuthority sa = ...;

     Challenge c = sa.createChallenge ();                // receive a challenge 'c' and send the response
     // send 'c' to the other node and receive 'r'       Challenge c = ...;
     Response r = ...;                                   Response r = sa.createResponse (c);

     if (sa.validateResponse (c, r)) {
       // access is permitted
     } else {
       // access is denied
     }

To set the current user, ie the one which will create the response, use the `logonUser` method. Obtaining a concrete user token is the responsibility of the concrete implementation. Similarly creating the user IDs is the responsibility of the concrete implementation. No methods are defined in this interface for these purposes because the number of parameters may vary depending on how users authenticate. For example they may supply a username/password pair, just a username string in a weaker system, or perhaps other, non-string credentials.

To set the users which are currently permitted, ie will be considered to have generated a valid response the `permitUserAccess` method must be used. To remove a user from this set the `denyUserAccess` method should be used.

Author:
  Quickstone Technologies Limited

## Method Summary

Modifier and Type
Method
Description
`Challenge`
`createChallenge()`
Creates and returns a new challenge object.
`Response`
`createResponse(Challenge c)`
Create a response for the given challenge coded with the currently logged on user.
`void`
`denyUserAccess(UserID u)`
Removes a user ID from the set of users considered by this authority to create valid responses to challenges.
`void`
`logoffUser()`
Clears the currently logged on user.
`void`
`logonUser(UserToken u)`
Sets the currently logged on user.
`void`
`permitUserAccess(UserID u)`
Adds a user ID to the set of users considered by this authority to create valid responses to challenges.
`boolean`
`validateResponse(Challenge c, Response r)`
Determines if a response is valid for the given challenge.

## Method Details

### createChallenge

Challenge createChallenge()

Creates and returns a new challenge object. The challenge should be used as soon as possible and only once as it may be logged by the authority, timestamped or protected in some other way. The caller should retain a copy for use in the `validateResponse` method.

Returns:
  the challenge object.

### validateResponse

boolean validateResponse(Challenge c, Response r)

Determines if a response is valid for the given challenge. The challenge must have been generated by a call to `createChallenge`. This should be called as soon as the response is available and only once as there may be timestamping or other protection schemes in place.

Parameters:
  `c` - the challenge as returned by `createChallenge` and as passed to `createResponse`.
  `r` - the response from `createResponse`.
Returns:
  true if the response is valid and the user permitted. False otherwise.

### createResponse

Response createResponse(Challenge c)
Create a response for the given challenge coded with the currently logged on user.

Parameters:
  `c` - the challenge created by `createChallenge`.
Returns:
  the response to be returned to the originator authority.

### logonUser

void logonUser(UserToken u) throws AccessDeniedException
Sets the currently logged on user.

Parameters:
  `u` - the token identifying an authenticated user.
Throws:
  `AccessDeniedException` - if the user token is not valid for this authority.

### logoffUser

void logoffUser()
Clears the currently logged on user.

### permitUserAccess

void permitUserAccess(UserID u) throws AccessDeniedException
Adds a user ID to the set of users considered by this authority to create valid responses to challenges.

Parameters:
  `u` - the user ID to add.
Throws:
  `AccessDeniedException` - if the user ID is not valid for this authority.

### denyUserAccess

void denyUserAccess(UserID u) throws AccessDeniedException
Removes a user ID from the set of users considered by this authority to create valid responses to challenges.

Parameters:
  `u` - the user ID to remove.
Throws:
  `AccessDeniedException` - if the user ID is not valid for this authority.