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

All Superinterfaces:
CsapiInterface, java.io.Serializable

public interface AppServiceAgreementManagement
extends CsapiInterface

This interface and the signServiceAgreement() and terminateServiceAgreement() methods shall be implemented by an application.


Method Summary
 byte[] signServiceAgreement(java.lang.String serviceToken, java.lang.String agreementText, java.lang.String signingAlgorithm)
          Upon receipt of the initiateSignServiceAgrement() method from the client application, this method is used by the framework to request that the client application sign an agreement on the service.
 void terminateServiceAgreement(java.lang.String serviceToken, java.lang.String terminationText, byte[] digitalSignature)
          This method is used by the framework to terminate an agreement for the service.
 

Method Detail

signServiceAgreement

public byte[] signServiceAgreement(java.lang.String serviceToken,
                                   java.lang.String agreementText,
                                   java.lang.String signingAlgorithm)
                            throws CommonException,
                                   InvalidAgreementTextException,
                                   InvalidServiceTokenException,
                                   InvalidSigningAlgorithmException
Upon receipt of the initiateSignServiceAgrement() method from the client application, this method is used by the framework to request that the client application sign an agreement on the service. The framework provides the service agreement text for the client application to sign. 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 agrees, it signs the service agreement, returning its digital signature to the framework. Returns : 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 agreement text given by the framework. 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). The signing-time attribute, as defined in section 11.3 of RFC 2630, shall also be used to provide replay prevention. If the signature is incorrect the serviceToken will be expired immediately.

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 to which this service agreement corresponds. (If the client application selects many services, it can determine which selected service corresponds to the service agreement by matching the service token). If the serviceToken is invalid, or not known by the client application, then the P_INVALID_SERVICE_TOKEN exception is thrown.
agreementText - This is the agreement text that is to be signed by the client application using the private key of the client application. If the agreementText is invalid, then the P_INVALID_AGREEMENT_TEXT exception is thrown.
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 client application, the P_INVALID_SIGNING_ALGORITHM exception is thrown. 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.
InvalidAgreementTextException - Invalid agreement text
InvalidServiceTokenException - The service token has not been issued, or it has expired.
InvalidSigningAlgorithmException - Invalid signing algorithm

terminateServiceAgreement

public void terminateServiceAgreement(java.lang.String serviceToken,
                                      java.lang.String terminationText,
                                      byte[] digitalSignature)
                               throws CommonException,
                                      InvalidServiceTokenException,
                                      InvalidSignatureException
This method is used by the framework 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 unknown to the client application, the P_INVALID_SERVICE_TOKEN exception will be thrown.
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 confirm its identity to the client application. The client application can check that the terminationText has been signed by the framework. If a match is made, the service agreement 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.
InvalidServiceTokenException - The service token has not been issued, or it has expired.
InvalidSignatureException - Invalid digital signature