We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
FIWARE.OpenSpecification.Security.Context-basedSecurity and Compliance.Open RESTful API Specification - FIWARE Forge Wiki

FIWARE.OpenSpecification.Security.Context-basedSecurity and Compliance.Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Context-based Security & Compliance API

Please check the Legal Notice to understand the rights to use FI-WARE Open Specifications.

PRRS Framework API Core

The PRRS Framework API is a RESTful, resource-oriented API accessed via HTTP that uses XML/JSON representation for information interchange.

The PRRS Framework is the core engine in the Context-based Security & Compliance GE. It provides run-time support to applications performing dynamic selection and deployment of optional security enablers. The PRRS Framework API offers the following functions:

  • securityRequest: to receive requests with end-user security requirements and context constraints to be processed by the Context-based Security & Compliance GE
  • events: to receive notifications from Context-monitors about violation in the validation rules by the deployed and monitored optional security enablers

Context-Monitor API

The context monitors used by the Context-based Security & Compliance GE to monitor the end-user context information and the behaviour and conformances with the validation rules of the security services deployed by the PRRS Framework must offer the following function:

  • validationRules: to receive from the PRRS Framework the validation rules to be monitored in a new deployed security service
  • contextEvents: to receive notifications from the FI-WARE Context-Broker GE on changes in context information provided by the end-user in the security request and published in there.

Marketplace API

In order to deploy available optional security GEs from FI-WARE Marketplace, the PRRS Framework must connect to FI-WARE Marketplace GE to recover urls of USDL descriptions of optional security GEs. First, the operation GET /offering/store/{storeName}/offerings is used to recover all available resources in the stores where the end-user has authentication. Then, for each resource returned, the <url> field is search because it has the location of the USDL for the service.

More information about the Marketplace API can be found in: FIWARE.OpenSpecification.Apps.MarketplaceOfferingsREST

Intended Audience

This specification is intended for both software developers and reimplementors of this API. For the former, this document provides a full specification of how to interoperate with the PRRS service that implements the PRRS Framework API included in the Context-based security and compliance GE. For the latter, this specification indicates the interface to be implemented and provided to clients.

To use this information, the reader should firstly have a general understanding of the Generic Enabler (available on FIWARE.ArchitectureDescription.Security.Context-based security & compliance). The reader should also be familiar with:

  • ReSTful web services
  • HTTP/1.1
  • JSON and XML data serialization formats

API Change History

This version of the PRRS Framework API replaces and obsoletes all previous versions.

The most recent changes are described in the table below:

Revision Date Changes Summary
Oct 31, 2012
  • Initial version.
Mar 30, 2013
  • Updated version.
Apr 22, 2013
  • Second version.

How to Read This Document

In the whole document it is taken the assumption that reader is familiarized with REST architecture style. However, the interface was carefully designed to be extremely simple to use, thus to require minimal integration effort from software developers interested in the PRRS functionalities. Therefore, no special notation or particular constructs were needed in producing this description.

General Context-based Security & Compliance API Information

Resources Summary

A graphical diagram in which we can see the different URIs exposed in the API.

Context-based Security and Compliance API REST

Authentication

No additional authentication information is required by the service in the RESTful API. The authentication information required by the Context-based Security & Compliance GE is the one required to access the FI-WARE Marketplace GE so the end-user only can access to the services he has access. For FI-WARE Second Release, it is assumed that end-user must configure the user/password to be used by the PRRS Framework and the stores where he has access. That user/password will be used by the PRRS Framework to recover the FI-WARE optional security enablers available for the user.

Representation Format

Security Requests

Current version of the PRRS Framework API only supports XML (Content-Type:text/xml) for the delivering of security requests. In future releases, this information could be also provided in a HTML FORM (Content-Type:multipart/form-data) or JSON (Content-Type:application/json). The following information can be provided in a securityRequest:

  • serviceName:

The name of a specific implementation of an optional security enabler as it is stored and offered in the way of resource in the Marketplace. This field is optional and it is only present in case the security service required is known by the user who sends a direct request to the PRRS Framework.

  • securityRule:

The name of a security scheme that integrates a set of security specifications defined through a USDL-SEC Security Profile. This field is optional and it is not considered when the serviceName field is present.

  • securitySpec:

List of security specifications required by the end-user to be included in the security service selected by the PRRS. This field is optional and it is not considered when the serviceName or the serviceType field are present. Each security specification will be provided with the name of the parameter in usdl-sec vocabulary and its value. For example: usdl-sec:SecurityMeasure=access_control.

  • contextDesc:

List of user-context constraints that must be considered by the PRRS in the selection of the security service. This field is optional and the security request can include more than one contextDesc field. This list can include:

- Context information related to USDL attributes (not USDL-SEC) provided as preferences by the user to be considered in the selection of services
- Configuration parameters to be considered in the selection or deployment of the services
- Context data published by the user in the FI-WARE Context Broker GE. In this last case, the context information must be provided indicating the entity type and the entity id as they are published in the FI-WARE Context Broker GE
  • clientEndpoint:

Endpoint to access the client application that sends the security request. This information will be used by the PRRS after processing the request to provide the end-user application with the details to access to the security service selected and to notify about changes in case of user-context non compliance detection. This field is mandatory.

Below it is shown the Security Request XML Schema used:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   
    <xs:complexType name="contextType">
        <xs:choice>
            <xs:element name="preferenceRule" type="preferenceType" minOccurs="0" maxOccurs="1"/>
            <xs:element name="configuration" type="configType" minOccurs="0" maxOccurs="1"/>
            <xs:element name="entityContextBroker" type="contextBrokerType" minOccurs="0" maxOccurs="1"/>
        </xs:choice>
    </xs:complexType>
  
    <xs:complexType name="contextBrokerType">
        <xs:sequence>          
            <xs:element name="entityId" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="entityType" type="xs:string" minOccurs="1" maxOccurs="1"/>  
            <xs:element name="attribute" type="xs:string" minOccurs="0" maxOccurs="1"/>
            <xs:element name="contextValue" type="xs:string" minOccurs="0" maxOccurs="1"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="preferenceType">
        <xs:sequence>
            <xs:element name="param" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="value" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="priority" type="xs:int" minOccurs="0" maxOccurs="1"/>     
            <xs:element name="mandatory" type="xs:boolean" minOccurs="0" maxOccurs="1"/>  
        </xs:sequence>
    </xs:complexType>
  
    <xs:complexType name="configType">
        <xs:sequence>
            <xs:element name="param" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="value" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="description" type="xs:string" minOccurs="0" maxOccurs="1"/>     
        </xs:sequence>
    </xs:complexType>
  
   <xs:complexType name="specType">
        <xs:sequence>
            <xs:element name="param" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="value" type="xs:string" minOccurs="1" maxOccurs="1"/>          
        </xs:sequence>
    </xs:complexType>
  
    <xs:complexType name="ruleType">
        <xs:sequence>
            <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="domain" type="xs:string" minOccurs="0" maxOccurs="1"/>          
        </xs:sequence>
    </xs:complexType>
  
   <xs:complexType name="securityRequest">
         <xs:sequence>
               <xs:element name="serviceName" type="xs:string" minOccurs="0" maxOccurs="1" />          
               <xs:element name="securityRule" type="ruleType" minOccurs="0" maxOccurs="1" />          
            <xs:element name="securitySpec" type="specType" minOccurs="0" maxOccurs="unbounded" />
            <xs:element name="contextDesc" type="contextType" minOccurs="0" maxOccurs="unbounded" />
            <xs:element name="clientEndpoint" type="xs:string" minOccurs="1" maxOccurs="1" />
         </xs:sequence>      
    </xs:complexType>
  
    <xs:element name="securityRequest" type="securityRequest"/>
</xs:schema>

Events

Current version of the PRRS Framework API only supports JSON (Content-Type:application/json) for the delivering of events from the Context-Monitor. The following information must be provided for each event:

  • ruleId: It identifies the validation rule monitored by the context-monitor which has been violated.
  • eventType: It identifies the type of event received. Currently there are three event types identified:
1 = NonAvailability (the service is not available)
2 = NonCompliance (the service is not compliance with the validation rule monitored)
3 = ContextChange (new context value not compliant with the end-user constraints)
  • meaning: It is a short description of the event.
  • serviceId: It identifies the deployed service monitored.
  • additionalInfo: Additional info provided by the monitor that sends the event to the PRRS Framework.

Below is described the JSON schema used:

{
    "name": "event",
    "properties": {
        "ruleId": {
            "type": "number",
            "description": "Monitored validation rule identifier",
            "required": true
        },
        "eventType": {
            "type": "number",
            "description": "Event type identifier",
            "required": true
        },
        "meaning": {
            "type": "string",
            "description": "Description of the event detected",
            "required": true
        },
        "serviceId": {
            "type": "number",
            "description": "Monitored service identifier",
            "required": true
        },
        "additionalInfo": {
             "type": "string",
            "description": "Additional information provided by the monitor",
            "required": false
        }
    }
}

Validation Rules

Current version of the PRRS Framework API only supports JSON (Content-Type:application/json) for the delivery of validation rules to the Context-Monitor. The following information must be provided for each rule:

  • ruleID: It identifies the validation rule sent from the PRRS Framework to the Context-Monitor.
  • eventType: It identifies the type of event received. Currently there are three event types identified:
1 = NonAvailability (the service is not available)
2 = NonCompliance (the service is not compliance with the validation rule monitored)
3 = ContextChange (new context value not compliant with the end-user constraints)
  • formulae: This is the validation rule itself that allow the Context-Monitor identify what must be monitored.
  • parameter: It identifies the value provided in the value property. It depends on the monitor and it can be null if it is not required.
  • value: Value provided with the validation rule to the monitor. It depends on the monitor and it can be null if it is not required.
  • summary: Short name for the validation rule.
  • description: Description of the validation rule.
  • scope: Scope of the validation rule. Currently only the scope global is considered and it indicates that the validation rule must be send to the monitor by every deployed service.
  • serviceId: It identifies the deployed service to be monitored.

Below is shown the JSON schema used for Validation Rules:


{
    "name": "rule",
    "properties": {
        "ruleId": {
            "type": "number",
            "description": "Monitored validation rule identifier",
            "required": true
        },
        "eventType": {
            "type": "number",
            "description": "Event type identifier",
            "required": true
        },
        "formulae": {
            "type": "string",
            "description": "Validation rule",
            "required": true
        },
        "parameter": {
            "type": "string",
            "description": "Name of the parameter provided",
            "required": false
        },
        "value": {
            "type": "string",
            "description": "Value of the parameter provided with the validation rule",
            "required": false
        },
        "summary": {
             "type": "string",
            "description": "Short name of the validation rule",
            "required": false
        },
        "description": {
             "type": "string",
            "description": "Description of the validation rule",
            "required": false
        },
        "scope": {
             "type": "string",
            "description": "Scope of the rule",
            "required": true
        },
        "serviceId": {
            "type": "number",
            "description": "Monitored service identifier",
            "required": true
        }        
    }
}

Representation Transport

Resource representation is transmitted between client and server by using HTTP 1.1 protocol, as defined by IETF RFC-2616. Each time an HTTP request contains payload, a Content-Type header shall be used to specify the MIME type of wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Resource Identification

The security requests are uniquely identified by their URI which include a requestID (for example: /PRRS/securityRequest/13fa1681-b209-476b-9aad-8245fd3dbc65). The requestID can be used to modify or delete a security request by the end-user.

Links and References

Limits

We can manage the capacity of the system in order to prevent the abuse of the system through some limitations. These limitations will be configured by the operator and may differ from one implementation to other of the GE implementation.

Rate Limits

Given the specificity of the service, i.e. receiving security requests to include in a composition, it is not foreseen a massive amount of requests per user at the same time.

Versions

Only one version of the Open Specification is currently supported.

Extensions

The Context-based Security & Compliance GE could be extended in the future to be integrated with some Composition Editor to provide a graphical user interface (GUI) that makes easier the selection of security requirements and user-context constraints by the end-user.

At the moment, we are assuming the end-user knows the available usdl-sec vocabulary (or available security services in the Marketplace) as well as the user-context information and additional security rules published in the FI-WARE Context Broker GE.

Faults

Synchronous Faults

Error codes are returned in the body of the response. The description section returns a human-readable message for displaing end users.

Example:

<exception>
<description>Resource Not found</description>
<errorCode>404</errorCode>
<reasonPhrase>Not Found</reasonPhrase>
</exception>
Fault ElementAssociated Error CodesExpected in All Requests?
Unauthorized403YES
Not Found404YES
Limit Fault413YES
Internal Server error50XYES

Asynchronous Faults

No Asynchronous Faults are used by the PRRS.

API Operations

Verb URI Description
POST /PRRS/securityrequest Send a security request to the PRRS Framework.
DELETE /PRRS/securityrequest/{RequestID} Remove a specific security request done by a client and undeployed associated services.
POST /PRRS/events Send an event to the PRRS Framework.
POST /ContextMonitor/validationRules Send validation rules from the PRRS Framework to a Context-Monitor
DELETE /ContextMonitor/validationRules/{RuleID} Remove a validation rule from the Context-Monitor

Status Codes

200 OK

The security request was handled successfully and transmitted in response message.

201 Created

The security request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the security request, but is not returning any content.

304 Not Modified

Indicates the resource has not been modified since last requested. Typically, the HTTP client provides a header like the If-Modified-Since header to provide a time against which to compare. Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received in comparison to the entirety of the page being re-processed by the server, then sent again using more bandwidth of the server and client.

400 Bad Request

The security request cannot be fulfilled due to bad syntax.

404 Not Found

The security requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict.

500 Internal Server Error

A generic error message, given when no more specific message is suitable.

Security Requests

There are several ways to request services through the operation:

POST /PRRS/securityrequest

for all of them, described previously and with examples further on, the PRRS service must return an XML that matches the following specification:

Correct Response Status Code: HTTP 200 OK

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
     
    <xs:complexType name="result">
        <xs:choice>
        	<xs:element name="error" type="errorMessage" minOccurs="0" maxOccurs="1"/>        	
        	<xs:element name="securitySolutions" type="solutionList" minOccurs="0" maxOccurs="1"/>        	
        </xs:choice>
    </xs:complexType>
    
    <xs:complexType name="errorMessage">
        <xs:sequence>            
            <xs:element name="errorId" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="errorMsg" type="xs:string" minOccurs="1" maxOccurs="1"/>                
        </xs:sequence>
    </xs:complexType>

	<xs:complexType name="solutionList">
		<xs:sequence>            
             <xs:element name="securitySolution" type="solutionMsg" minOccurs="1" maxOccurs="unbounded"/>    
        </xs:sequence>
	</xs:complexType>
	
    <xs:complexType name="solutionMsg">
        <xs:sequence>
            <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="endpoint" type="xs:string" minOccurs="1" maxOccurs="1"/> 
            <xs:element name="WADL" type="xs:string" minOccurs="0" maxOccurs="1"/>       
            <xs:element name="USDL" type="xs:string" minOccurs="1" maxOccurs="1"/>    
        </xs:sequence>
    </xs:complexType>
        
   <xs:complexType name="securityRequestResponse">
         <xs:sequence>
           	<xs:element name="success" type="xs:boolean" minOccurs="1" maxOccurs="1" />            
           	<xs:element name="result" type="result" minOccurs="1" maxOccurs="1" />                        
         </xs:sequence>
         <xs:attribute name="id" type="xs:string"/>
    </xs:complexType>
    
    <xs:element name="request" type="securityRequestResponse"/>
</xs:schema>
  • As an example of success:

<request id="ff13-34A9">
<success>true</success>
<result>
  <securitySolutions>
    <securitySolution>
      <name>MySecuritySolution</name>
      <endpoint>http://company.com/service/resource</endpoint>
      <USDL>http://company.com/service/USDL</USDL>
    </securitySolution>
    <securitySolution>
      <name>MySecuritySolution2</name>
      <endpoint>http://company2.com/service/resource</endpoint>
      <USDL>http://company2.com/service/USDL</USDL>
    </securitySolution>
  </securitySolutions>
</result>
</request>
  • As an example of failure:

<request id="FF13-34AA">
<success>false</success>
<result>
   <error>
      <errorId>"0034-A52F"</errorId>
      <errorMsg>Not found suitable solutions</errorMsg>
   </error>
</result>
</request>

Request service by ServiceName

A client application must provide the following XML to request a service to the PRRS Framework when the service name is already known.

Here is shown an XML example of the security request that must be provided in the request body:

<securityRequest>  
       <serviceName>CBS</serviceName>
       <clientEndpoint>http://86.24.57.14:7777/bobApp</clientEndpoint>
</securityRequest>

Request service by ServiceRule

Below it is shown an XML example of the security request that must be provided in the request body for finding a service with a specified security rule:

<securityRequest>  
       <securityRule>
               <name>DataProtection</name>
       </securityRule>
       <clientEndpoint>http://86.24.57.14:7777/bobApp</clientEndpoint>
</securityRequest>

Request service by SecuritySpecs

Below it is shown an XML example of the security request that must be provided in the request body to request a service compliant with a given security specifications to the PRRS Framework:

<securityRequest>  
     <securitySpec>
           <param>usdl-sec:SecurityMeasure</param>
           <value>access_control</value>
      </securitySpec>
      <securitySpec>
           <param>usdl-sec:TechnologyType</param>
           <value>IPSec</value>
       </securitySpec>
      <clientEndpoint>http://86.24.57.14:7777/bobApp</clientEndpoint>
</securityRequest>

Request service with user-context constraints

Below it is shown an XML example of the security request format that must be provided in the request body to add user-context constraints:

<securityRequest>  
      <securityRule><name>DataProtection</name></securityRule>
      <contextDesc>
              <preferenceRule>
                  <param>usdl-core:hasServiceProvider</param>
                   <value>ATOS</value>
                   <priority>3</priority>
                   <mandatory>false</mandatory>
              </preferenceRule>
       </contextDesc>
       <contextDesc>
               <configuration>
                   <param>LAN</param>
                   <value>EN</value>
                  <description>Language</description>
              </configuration>
       </contextDesc>
       <clientEndpoint>http://86.24.57.14:7777/bobApp</clientEndpoint>
</securityRequest>

Remove required security service

The following operation must be invoked to remove a security requirement in the PRRS Framework. When this operation is received, the service which was selected and deployed to support this request is undeployed and removed from the Context Monitor.

DELETE /PRRS/securityrequest/{RequestID}

The PRRS Framework service must return a JSON that matches the following specification:

Response Status Code: HTTP 200 OK

{
    "name": "response",
    "properties": {
        "success": {
            "type": "boolean",
            "description": "It indicates if the operation was successful",
            "required": true
        },
        "result": {
            "type": "string",
            "description": "Result of the operation performed",
            "required": true
        }        
    }
}
  • As an example of success when the security request has been removed and the associated service undeployed, the following JSON is returned:
{"success":"true",
 "result":"Security request removed from PRRS Framework."
}
  • As an example of failure, the following JSON is returned:
{"success":"false",
 "result":"Error removing security request from PRRS Framework."

Add validation rule to the Context Monitor

The following operation provided by the Context Monitor is invoked by the PRRS Framework when a new service is selected to support a security requirement received:

POST /PRRS/ContextMonitor/validationrules

The validation rules must be provided in JSON format. Below it is shown an example:

{"rule": {
        "ruleId":"1",
        "eventType":"1",
        "formulae":"checkServiceWADL",
        "parameter":"WADL",
        "value":"http://localhost:8080/DBA/services/DBA?_wadl",
        "summary":"Monitor availability of the operations offered by the service (WADL)",
        "description":"Operations included in WADL are checked to validate availability",
        "scope":"global",
        "serviceId": "3"
        }
}

The Context-Monitor service must return to the PRRS Framework that sent the validation rule a JSON that matches the following specification:

Response Status Code: HTTP 200 OK

{
    "name": "response",
    "properties": {
        "success": {
            "type": "boolean",
            "description": "It indicates if the operation was successful",
            "required": true
        },
        "result": {
            "type": "string",
            "description": "Result of the operation performed",
            "required": true
        }        
    }
}
* As an example of success when the validation rule has been added to the Context-Monitor, the following JSON is returned:

<pre>
{"success":"false",
 "result":"Error adding validation rule to PRRS Context-Monitor."
}
  • As an example of failure when the validation rule can not be added to the monitoring performed by the Context-Monitor, the following JSON is returned:
{"success":"true",
 "result":"Validation rule added to PRRS Context-Monitor."
}

Remove validation rule from the Context Monitor

The following operation provided by the Context Monitor is invoked by the PRRS Framework to remove a validation rule when a monitored service is undeployed:

DELETE /PRRS/ContextMonitor/validationrules/{RuleID}

Response Status Code: HTTP 200 OK

  • If the validation rule has been successfully removed from the Context-Monitor, the following JSON is returned:
{"success":"true",
 "result":"Error removing validation rule from PRRS Context-Monitor."
}
  • If the operation has an error and the validation rule can not be removed from the Context-Monitor, the following JSON is returned:
{"success":"false",
 "result":"Validation rule removed from PRRS Context-Monitor."
}

Send events to the PRRS Framework

The following operation must be invoked by a Context Monitor to send events to the PRRS Framework:

POST /PRRS/events

The event must be provided in JSON format as described earlier. Below it is shown an example:

{"event": {
        "ruleId": "1",
        "eventType": "1",
        "meaning": "Service not available",
        "serviceId": "3",
        "additionalInfo": "Error: operation not available",
        }
}

The PRRS service must return to the Context-Monitor that sent the event a JSON that matches the following specification:

Response Status Code: HTTP 200 OK

{
    "name": "response",
    "properties": {
        "success": {
            "type": "boolean",
            "description": "It indicates if the operation was successful",
            "required": true
        },
        "result": {
            "type": "string",
            "description": "Result of the operation performed",
            "required": true
        }        
    }
}
  • As an example of success when the event has been successfully registered in the PRRS Framework, the following JSON is returned:
{"success":"true",
 "result":"Event registered!"
}
  • As an example of not success when the event can not be registered in the PRRS Framework, the following JSON is returned:
{"success":"false",
 "result":"Event not registered!"
}
Personal tools
Create a book