org.csapi.jr.se.fw.fw_access.trust_and_security
Interface APILevelAuthentication
- All Superinterfaces:
- Authentication, CsapiInterface, java.io.Serializable
- public interface APILevelAuthentication
- extends Authentication
The API Level Authentication Framework interface is used by the client to authenticate the Framework. It is also used to initiate the authentication process. If the IpAPILevelAuthentication interface is implemented by a Framework, then selectEncryptionMethod(), selectAuthenticationMechanism(), authenticate(), challenge(), abortAuthentication() and authenticationSucceeded () shall be implemented. IpAPILevelAuthentication inherits the requirements of IpAuthentication, therefore requestAccess() shall be implemented.
Method Summary |
void |
abortAuthentication()
The client uses this method to abort the authentication process where the framework is authenticating the client. |
byte[] |
authenticate(byte[] challenge)
Deprecated. |
void |
authenticationSucceeded()
The client uses this method to inform the framework of the success of the authentication attempt. |
byte[] |
challenge(byte[] challenge)
This method is used by the client to authenticate the framework. |
java.lang.String |
selectAuthenticationMechanism(java.lang.String authMechanismList)
The client uses this method to inform the Framework of the different authentication mechanisms it supports as part of API level Authentication. |
java.lang.String |
selectEncryptionMethod(java.lang.String encryptionCaps)
Deprecated. |
selectEncryptionMethod
public java.lang.String selectEncryptionMethod(java.lang.String encryptionCaps)
throws CommonException,
AccessDeniedException,
NoAcceptableEncryptionCapabilityException,
PlatformException
- Deprecated.
- This method is deprecated and replaced by selectAuthenticationMechanism(). It shall only be used when the IpAPILevelAuthentication interface is obtained by using the deprecated method initiateAuthentication() instead of initiateAuthenticationWithVersion() on the IpInitial interface. This method will be removed in a later release.
The client uses this method to initiate the authentication process. The framework returns its preferred mechanism. This should be within capability of the client. If a mechanism that is acceptable to the framework within the capability of the client cannot be found, the framework throws the P_NO_ACCEPTABLE_ENCRYPTION_CAPABILITY exception. Once the framework has returned its preferred mechanism, it will wait for a predefined unit of time before invoking the client's authenticate() method (the wait is to ensure that the client can initialise any resources necessary to use the prescribed encryption method).
Returns : This is returned by the framework to indicate the mechanism preferred by the framework for the encryption process. If the value of the prescribedMethod returned by the framework is not understood by the client, it is considered a catastrophic error and the client must abort.
- Parameters:
encryptionCaps
- This is the means by which the encryption mechanisms supported by the client are conveyed to the framework.
- Throws:
CommonException
- Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException
- The client is not currently authenticated with the framework
NoAcceptableEncryptionCapabilityException
- No encryption mechanism, which is acceptable to the framework, is supported by the client
PlatformException
- The implementation detected an internal (for example, communication) error
authenticate
public byte[] authenticate(byte[] challenge)
throws CommonException,
AccessDeniedException,
PlatformException
- Deprecated.
- This method is deprecated and replaced by challenge(). It shall only be used when the IpAPILevelAuthentication interface is obtained by using the deprecated method initiateAuthentication() instead of initiateAuthenticationWithVersion() on the IpInitial interface. This method will be removed in a later release.
This method is used by the client to authenticate the framework. The challenge will be encrypted using the mechanism prescribed by selectEncryptionMethod. The framework must respond with the correct responses to the challenges presented by the client. The domainID received in the initiateAuthentication() can be used by the framework to reference the correct public key for the client (the key management system is currently outside of the scope of the OSA APIs). The number of exchanges is dependent on the policies of each side. The authentication of the framework is deemed successful when the authenticationSucceeded method is invoked by the client.
The invocation of this method may be interleaved with authenticate() calls by the framework on the client's APILevelAuthentication interface.
Returns : This is the response of the framework to the challenge of the client in the current sequence. The response will be based on the challenge data, decrypted with the mechanism prescribed by selectEncryptionMethod().
- Parameters:
challenge
- The challenge presented by the client to be responded to by the framework. The challenge mechanism used will be in accordance with the IETF PPP Authentication Protocols - Challenge Handshake Authentication Protocol (RFC 1994). The challenge will be encrypted with the mechanism prescribed by selectEncryptionMethod().
- Throws:
CommonException
- Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException
- The client is not currently authenticated with the framework
PlatformException
- The implementation detected an internal (for example, communication) error
abortAuthentication
public void abortAuthentication()
throws CommonException,
AccessDeniedException,
PlatformException
- The client uses this method to abort the authentication process where the framework is authenticating the client. This method is invoked if the client no longer wishes to continue the authentication process, (unless the framework responded incorrectly to a challenge in which case no further communication with the framework should occur.) If this method has been invoked before the client has been authenticated by the Framework, calls to the requestAccess operation on IpAPILevelAuthentication will return an error code (P_ACCESS_DENIED), until the client has been properly authenticated. If this method is invoked after the client has been authenticated by the Framework, it shall not result in the immediate removal of the client's authentication. (The Framework may wish to authenticate the client again, however).
- Throws:
CommonException
- Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException
- The client is not currently authenticated with the framework
PlatformException
- The implementation detected an internal (for example, communication) error
authenticationSucceeded
public void authenticationSucceeded()
throws CommonException,
AccessDeniedException,
PlatformException
- The client uses this method to inform the framework of the success of the authentication attempt. Calls to this method have no impact on the client's rights to call requestAccess(), which depend exclusively on the framework's successful authentication of the client.
- Throws:
CommonException
- Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException
- The client is not currently authenticated with the framework
PlatformException
- The implementation detected an internal (for example, communication) error
selectAuthenticationMechanism
public java.lang.String selectAuthenticationMechanism(java.lang.String authMechanismList)
throws CommonException,
AccessDeniedException,
NoAcceptableAuthenticationMechanismException,
PlatformException
- The client uses this method to inform the Framework of the different authentication mechanisms it supports as part of API level Authentication. The Framework will select one of the suggested authentication mechanisms and that mechanism shall be used for authentication by both Framework and Client. The authentication mechanism chosen as a result of the response to this method remains valid for an instance of IpAPILevelAuthentication and until this method is re-invoked by the client. If a mechanism that is acceptable to the framework within the capability of the client cannot be found, the framework throws the P_NO_ACCEPTABLE_AUTHENTICATION_MECHANISM exception.
This method shall only be used when the IpAPILevelAuthentication interface is obtained by using initiateAuthenticationWithVersion() on the IpInitial interface.
Returns: selectedMechanism. This is the authentication mechanism chosen by the Framework. The chosen mechanism shall be taken from the list of mechanisms proposed by the Client.
- Parameters:
authMechanismList
- The list of authentication mechanisms supported by the client.
- Throws:
CommonException
- Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException
- The client is not currently authenticated with the framework
NoAcceptableAuthenticationMechanismException
- No authentication mechanism, which is acceptable to the framework, is supported by the client
PlatformException
- The implementation detected an internal (for example, communication) error
challenge
public byte[] challenge(byte[] challenge)
throws CommonException,
AccessDeniedException,
PlatformException
- This method is used by the client to authenticate the framework. The framework must respond with the correct responses to the challenges presented by the client. The domainID received in the initiateAuthenticationWithVersion() can be used by the framework to reference the correct public key for the client (the key management system is currently outside of the scope of the OSA APIs). The number of exchanges is dependent on the policies of each side. The authentication of the framework is deemed successful when the authenticationSucceeded method is invoked by the client.
The invocation of this method may be interleaved with challenge() calls by the framework on the client's APILevelAuthentication interface.
This method shall only be used when the IpAPILevelAuthentication interface is obtained by using initiateAuthenticationWithVersion() on the IpInitial interface.
Returns : This is the response of the framework to the challenge of the client in the current sequence. The formatting of this parameter shall be according to section 4.1 of RFC 1994. A complete CHAP Response packet shall be used to carry the response string. The Response packet shall make the contents of this returned parameter. The Name field of the CHAP Response packet shall be present but not contain any useful value.
- Parameters:
challenge
- The challenge presented by the client to be responded to by the framework. The challenge format used will be in accordance with the IETF PPP Authentication Protocols - Challenge Handshake Authentication Protocol (RFC 1994).
The formatting of the challenge value shall be according to section 4.1 of RFC 1994. A complete CHAP Request packet shall be used to carry the challenge value. The Name field of the CHAP Request packet shall be present but not contain any useful value.
- Throws:
CommonException
- Defines the structure of the exception class which is applicable to all methods.
AccessDeniedException
- The client is not currently authenticated with the framework
PlatformException
- The implementation detected an internal (for example, communication) error