org.csapi.jr.se.fw.fw_access.trust_and_security
Interface Access

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface Access
extends CsapiInterface

This interface shall be implemented by a Framework. As a minimum requirement the obtainInterface() and obtainInterfaceWithCallback(), selectSigningAlgorithm() and terminateAccess() methods shall be implemented.


Method Summary
 void endAccess(org.csapi.jr.se.fw.Property[] endAccessProperties)
          Deprecated.  
 java.lang.String[] listInterfaces()
          The client uses this method to obtain the names of all interfaces supported by the framework.
 org.csapi.jr.se.CsapiInterface obtainInterface(java.lang.String interfaceName)
          This method is used to obtain other framework interfaces.
 org.csapi.jr.se.CsapiInterface obtainInterfaceWithCallback(java.lang.String interfaceName, org.csapi.jr.se.CsapiInterface clientInterface)
          This method is used to obtain other framework interfaces.
 void releaseInterface(java.lang.String interfaceName)
          Deprecated.  
 void relinquishInterface(java.lang.String interfaceName, java.lang.String terminationText, byte[] digitalSignature)
          The client uses this method to release an instance of a framework interface that was obtained during this access session.
 java.lang.String selectSigningAlgorithm(java.lang.String signingAlgorithmCaps)
          The client uses this method to inform the Framework of the different signing algorithms it supports for use in all cases where digital signatures are required.
 void terminateAccess(java.lang.String terminationText, byte[] digitalSignature)
          The terminateAccess method is used by the client to request that its access session with the framework is ended.
 

Method Detail

obtainInterface

public org.csapi.jr.se.CsapiInterface obtainInterface(java.lang.String interfaceName)
                                               throws CommonException,
                                                      AccessDeniedException,
                                                      InvalidInterfaceNameException,
                                                      PlatformException
This method is used to obtain other framework interfaces. The client uses this method to obtain interface references to other framework interfaces. (The obtainInterfaceWithCallback method should be used if the client is required to supply a callback interface to the framework.) Returns : This is the reference to the interface requested.

Parameters:
interfaceName - The name of the framework interface to which a reference to the interface is requested. If the interfaceName is invalid, the framework returns an error code (P_INVALID_INTERFACE_NAME).
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
InvalidInterfaceNameException - Invalid interface name.
PlatformException - The implementation detected an internal (for example, communication) error

obtainInterfaceWithCallback

public org.csapi.jr.se.CsapiInterface obtainInterfaceWithCallback(java.lang.String interfaceName,
                                                                  org.csapi.jr.se.CsapiInterface clientInterface)
                                                           throws CommonException,
                                                                  AccessDeniedException,
                                                                  InvalidInterfaceNameException,
                                                                  InvalidInterfaceTypeException,
                                                                  PlatformException
This method is used to obtain other framework interfaces. The client uses this method to obtain interface references to other framework interfaces, when it is required to supply a callback interface to the framework. (The obtainInterface method should be used when no callback interface needs to be supplied.) Returns : This is the reference to the interface requested.

Parameters:
interfaceName - The name of the framework interface to which a reference to the interface is requested. If the interfaceName is invalid, the framework returns an error code (P_INVALID_INTERFACE_NAME).
clientInterface - This is the reference to the client interface, which is used for callbacks. If a client interface is not needed, then this method should not be used. (The obtainInterface method should be used when no callback interface needs to be supplied.) If the interface reference is not of the correct type, the framework returns an error code (P_INVALID_INTERFACE_TYPE).
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
InvalidInterfaceNameException - Invalid interface name.
InvalidInterfaceTypeException - The interface reference supplied by the client is the wrong type.
PlatformException - The implementation detected an internal (for example, communication) error

endAccess

public void endAccess(org.csapi.jr.se.fw.Property[] endAccessProperties)
               throws CommonException,
                      AccessDeniedException,
                      InvalidPropertyException,
                      PlatformException
Deprecated.  

This method is deprecated and will be removed in a later release. It is replaced with terminateAccess. The endAccess operation is used by the client to request that its access session with the framework is ended. After it is invoked, the client will no longer be authenticated with the framework. The client will not be able to use the references to any of the framework interfaces gained during the access session. Any calls to these interfaces will fail.

Parameters:
endAccessProperties - This is a list of properties that can be used to tell the framework the actions to perform when ending the access session (for example existing service sessions may be stopped, or left running). If a property is not recognised by the framework, an error code (P_INVALID_PROPERTY) is returned.
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
InvalidPropertyException - The framework does not recognise the property supplied by the client
PlatformException - The implementation detected an internal (for example, communication) error

listInterfaces

public java.lang.String[] listInterfaces()
                                  throws CommonException,
                                         AccessDeniedException,
                                         PlatformException
The client uses this method to obtain the names of all interfaces supported by the framework. It can then obtain the interfaces it wishes to use using either obtainInterface() or obtainInterfaceWithCallback(). Returns : The frameworkInterfaces parameter contains a list of interfaces that the framework makes available.

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

releaseInterface

public void releaseInterface(java.lang.String interfaceName)
                      throws CommonException,
                             AccessDeniedException,
                             InvalidInterfaceNameException,
                             PlatformException
Deprecated.  

This method is deprecated and will be removed in a later release. It is replaced with relinquishInterface. The client uses this method to release a framework interface that was obtained during this access session.

Parameters:
interfaceName - This is the name of the framework interface which is being released. If the interfaceName is invalid, the framework throws the P_INVALID_INTERFACE_NAME exception. If the interface has not been given to the client during this access session, then the P_TASK_REFUSED exception will be thrown.
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
InvalidInterfaceNameException - Invalid interface name.
PlatformException - The implementation detected an internal (for example, communication) error

selectSigningAlgorithm

public java.lang.String selectSigningAlgorithm(java.lang.String signingAlgorithmCaps)
                                        throws CommonException,
                                               AccessDeniedException,
                                               NoAcceptableSigningAlgorithmException,
                                               PlatformException
The client uses this method to inform the Framework of the different signing algorithms it supports for use in all cases where digital signatures are required. The Framework will select one of the suggested algorithms. This method shall be the first method invoked by the client on IpAccess. The algorithm chosen as a result of the response to this method remains valid for an instance of IpAccess and until this method is re-invoked by the client. If an algorithm that is acceptable to the framework within the capability of the client cannot be found, the framework throws the P_NO_ACCEPTABLE_SIGNING_ALGORITHM exception. Returns: selectedAlgorithm. This is the signing algorithm chosen by the Framework. The chosen algorithm shall be taken from the list proposed by the Client.

Parameters:
signingAlgorithmCaps - The list of signing algorithms 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
NoAcceptableSigningAlgorithmException - No signing algorithm, which is acceptable to the framework, is supported by the client
PlatformException - The implementation detected an internal (for example, communication) error

terminateAccess

public void terminateAccess(java.lang.String terminationText,
                            byte[] digitalSignature)
                     throws CommonException,
                            InvalidSignatureException,
                            PlatformException
The terminateAccess method is used by the client to request that its access session with the framework is ended. After it is invoked, the client will no longer be authenticated with the framework. The client will not be able to use the references to any of the framework interfaces gained during the access session. Any calls to these interfaces will fail. Also, all remaining service instances created by the framework either directly in this access session or on behalf of the client during this access session shall be terminated.

Parameters:
terminationText - This is the termination text describes the reason for the termination of the access session.
digitalSignature - This contains a CMS (Cryptographic Message Syntax) object (as defined in RFC 2630) with content type Signed-data. The signature is calculated and created as per section 5 of RFC 2630. The content is made of the termination text. The "external signature" construct shall not be used (that is the eContent field in the EncapsulatedContentInfo field shall be present and contain the termination text string). The signing-time attribute, as defined in section 11.3 of RFC 2630, shall also be used to provide replay prevention. The client uses this to confirm its identity to the framework. The framework can check that the terminationText has been signed by the client. If a match is made, the access session is terminated, otherwise the P_INVALID_SIGNATURE exception will be thrown.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidSignatureException - Invalid digital signature
PlatformException - The implementation detected an internal (for example, communication) error

relinquishInterface

public void relinquishInterface(java.lang.String interfaceName,
                                java.lang.String terminationText,
                                byte[] digitalSignature)
                         throws CommonException,
                                InvalidSignatureException,
                                InvalidInterfaceNameException,
                                PlatformException
The client uses this method to release an instance of a framework interface that was obtained during this access session.

Parameters:
interfaceName - This is the name of the framework interface which is being released. If the interfaceName is invalid, the framework throws the P_INVALID_INTERFACE_NAME exception. If the interface has not been given to the client during this access session, then the P_TASK_REFUSED exception will be thrown.
terminationText - This is the termination text describes the reason for the release of the interface. This text is required simply because the digitalSignature parameter requires a terminationText to sign.
digitalSignature - This contains a CMS (Cryptographic Message Syntax) object (as defined in RFC 2630) with content type Signed-data. The signature is calculated and created as per section 5 of RFC 2630. The content is made of the termination text. The "external signature" construct shall not be used (that is the eContent field in the EncapsulatedContentInfo field shall be present and contain the termination text string). The signing-time attribute, as defined in section 11.3 of RFC 2630, shall also be used to provide replay prevention. The client uses this to confirm its identity to the framework. The framework can check that the terminationText has been signed by the client. If a match is made, the interface is released, otherwise the P_INVALID_SIGNATURE exception will be thrown.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidSignatureException - Invalid digital signature
InvalidInterfaceNameException - Invalid interface name.
PlatformException - The implementation detected an internal (for example, communication) error