org.csapi.jr.se.fw.fw_application.service_agreement
Interface ServiceAgreementManagement

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface ServiceAgreementManagement
extends CsapiInterface

This interface and the signServiceAgreement(), terminateServiceAgreement(), selectService() and initiateSignServiceAgreement() methods shall be implemented by a Framework.


Method Summary
 void initiateSignServiceAgreement(java.lang.String serviceToken)
          This method is used by the client application to initiate the sign service agreement process.
 java.lang.String selectService(java.lang.String serviceID)
          This method is used by the client application to identify the service that the client application wishes to use.
 org.csapi.jr.se.fw.SignatureAndServiceMgr signServiceAgreement(java.lang.String serviceToken, java.lang.String agreementText, java.lang.String signingAlgorithm)
          After the framework has called signServiceAgreement() on the application's IpAppServiceAgreementManagement interface, this method is used by the client application to request that the framework sign the service agreement, which allows the client application to use the service.
 void terminateServiceAgreement(java.lang.String serviceToken, java.lang.String terminationText, byte[] digitalSignature)
          This method is used by the client application to terminate an agreement for the service.
 

Method Detail

signServiceAgreement

public org.csapi.jr.se.fw.SignatureAndServiceMgr signServiceAgreement(java.lang.String serviceToken,
                                                                      java.lang.String agreementText,
                                                                      java.lang.String signingAlgorithm)
                                                               throws CommonException,
                                                                      AccessDeniedException,
                                                                      InvalidAgreementTextException,
                                                                      InvalidServiceTokenException,
                                                                      InvalidSigningAlgorithmException,
                                                                      ServiceAccessDeniedException,
                                                                      PlatformException
After the framework has called signServiceAgreement() on the application's IpAppServiceAgreementManagement interface, this method is used by the client application to request that the framework sign the service agreement, which allows the client application to use the service. A reference to the service manager interface of the service is returned to the client application. The service manager returned will be configured as per the service level agreement. If the framework uses service subscription, the service level agreement will be encapsulated in the subscription properties contained in the contract/profile for the client application, which will be a restriction of the registered properties. If the client application is not allowed to access the service, then an error code (P_SERVICE_ACCESS_DENIED) is returned. If the client application invokes this method before the processing (that is digital signature verification) the reponse of signServiceAgreement() on the application's IpAppServiceAgreementManagement interface completed, a TpCommonExceptions with ExceptionType P_INVALID_STATE may be raised to indicate that this method is currently unable to complete the method due to a race condition. In this case, the TpCommonExceptions with ExceptionType P_INVALID_STATE suggests the application to retry the method invocation after a reasonable amount of time has passed. There must be only one service instance per client application. Therefore, in case the client attempts to select a service for which it has already signed a service agreement and this service agreement has not been terminated, a reference to the already existing service manager will be returned. Returns : This contains the digital signature of the framework for the service agreement, and a reference to the service manager interface of the service. structure TpSignatureAndServiceMgr { digitalSignature: TpOctetSet; serviceMgrInterface: IpServiceRef; }; The digitalSignature 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 the agreement text given by the client application. The "external signature" construct shall not be used (that is the eContent field in the EncapsulatedContentInfo field shall be present and contain the agreement text string). The signing-time attribute, as defined in section 11.3 of RFC 2630, shall also be used to provide replay prevention. The serviceMgrInterface is a reference to the service manager interface for the selected service.

Parameters:
serviceToken - This is the token returned by the framework in a call to the selectService() method. This token is used to identify the service instance requested by the client application. If the serviceToken is invalid, or has expired, an error code (P_INVALID_SERVICE_TOKEN) is returned.
agreementText - This is the agreement text that is to be signed by the framework using the private key of the framework. If the agreementText is invalid, then an error code (P_INVALID_AGREEMENT_TEXT) is returned.
signingAlgorithm - This is the algorithm used to compute the digital signature. It shall be identical to the one chosen by the framework in response to IpAccess.selectSigningAlgorithm(). If the signingAlgorithm is not the chosen one, is invalid, or unknown to the framework, an error code (P_INVALID_SIGNING_ALGORITHM) is returned. The list of possible algorithms is as specified in the TpSigningAlgorithm table. The identifier used in this parameter must correspond to the digestAlgorithm and signatureAlgorithm fields in the SignerInfo field in the digitalSignature (see below).
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
InvalidAgreementTextException - Invalid agreement text
InvalidServiceTokenException - The service token has not been issued, or it has expired.
InvalidSigningAlgorithmException - Invalid signing algorithm
ServiceAccessDeniedException - The client application is not allowed to access this service.
PlatformException - The implementation detected an internal (for example, communication) error

terminateServiceAgreement

public void terminateServiceAgreement(java.lang.String serviceToken,
                                      java.lang.String terminationText,
                                      byte[] digitalSignature)
                               throws CommonException,
                                      AccessDeniedException,
                                      InvalidServiceTokenException,
                                      InvalidSignatureException,
                                      PlatformException
This method is used by the client application to terminate an agreement for the service.

Parameters:
serviceToken - This is the token passed back from the framework in a previous selectService() method call. This token is used to identify the service agreement to be terminated. If the serviceToken is invalid, or has expired, an error code (P_INVALID_SERVICE_TOKEN) is returned.
terminationText - This is the termination text that describes the reason for the termination of the service agreement.
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 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 signing algorithm used is the same as the signing algorithm given when the service agreement was signed using signServiceAgreement(). The framework uses this to check that the terminationText has been signed by the client application. If a match is made, the service agreement is terminated, otherwise an error code (P_INVALID_SIGNATURE) 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
InvalidServiceTokenException - The service token has not been issued, or it has expired.
InvalidSignatureException - Invalid digital signature
PlatformException - The implementation detected an internal (for example, communication) error

selectService

public java.lang.String selectService(java.lang.String serviceID)
                               throws CommonException,
                                      AccessDeniedException,
                                      InvalidServiceIdException,
                                      ServiceAccessDeniedException,
                                      PlatformException
This method is used by the client application to identify the service that the client application wishes to use. If the client application is not allowed to access the service, then the P_SERVICE_ACCESS_DENIED exception is thrown. Returns : This is a free format text token returned by the framework, which can be signed as part of a service agreement. This will contain operator specific information relating to the service level agreement. The serviceToken has a limited lifetime. If the lifetime of the serviceToken expires, a method accepting the serviceToken will return an error code (P_INVALID_SERVICE_TOKEN). Service Tokens will automatically expire if the client application or framework invokes the endAccess method on the other's corresponding access interface.

Parameters:
serviceID - This identifies the service required. If the serviceID is not recognised by the framework, an error code (P_INVALID_SERVICE_ID) 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
InvalidServiceIdException - Invalid service ID
ServiceAccessDeniedException - The client application is not allowed to access this service.
PlatformException - The implementation detected an internal (for example, communication) error

initiateSignServiceAgreement

public void initiateSignServiceAgreement(java.lang.String serviceToken)
                                  throws CommonException,
                                         InvalidServiceTokenException,
                                         ServiceAccessDeniedException,
                                         PlatformException
This method is used by the client application to initiate the sign service agreement process. This method shall be invoked following the application's call to selectService(), and before the signing of the service agreement can take place. If the client application is not allowed to initiate the sign service agreement process, the exception (P_SERVICE_ACCESS_DENIED) is thrown.

Parameters:
serviceToken - This is the token returned by the framework in a call to the selectService() method. This token is used to identify the service instance requested by the client application. If the serviceToken is invalid, or has expired, the exception (P_INVALID_SERVICE_TOKEN) is thrown.
Throws:
CommonException - Defines the structure of the exception class which is applicable to all methods.
InvalidServiceTokenException - The service token has not been issued, or it has expired.
ServiceAccessDeniedException - The client application is not allowed to access this service.
PlatformException - The implementation detected an internal (for example, communication) error