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.Optional Security Enablers.ContentBasedSecurity.Open RESTful API Specification - FIWARE Forge Wiki

FIWARE.OpenSpecification.Security.Optional Security Enablers.ContentBasedSecurity.Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Content Based Security GE API

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

Content Based Security API Core

The Content Based Security (CBS) API provides services that encrypt, decrypt, sign and verify data. It is a RESTful API accessed via HTTP that uses XML-based and JSON-based representations for information interchange. Note that data to be protected need not be either XML or JSON.

Intended Audience

This specification is intended for software developers and reimplementers of this API. For the former, this document provides a full specification of how to interoperate with the Content Based Security API to encrypt, sign, decrypt and/or verify data. For the latter, this specification describes the interface to be provided to allow clients to interoperate with the Content Based Security.

In order to use this specification, the reader should first have a general understanding of the Content Based Security Optional Generic Enabler supporting the API.

Throughout this specification it is assumed that the reader is familiar with:

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

API Change History

Current version is: Version 1.0.0, 15/4/2013

This version of the Content Based Security API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
Apr 19, 2013
  • Version 1 of the Content Based Security GE API Guide.

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see FIWARE.ArchitectureDescription.Security.Optional Security Enablers.ContentBasedSecurity

Additional Resources

You can download the most current version of this document from the FIWARE API specification website at FIWARE.OpenSpecification.Security.Optional Security Enablers.ContentBasedSecurity.Open RESTful API Specification. For more details about the Content Based Security Service that this API is based upon, please refer to FIWARE.ArchitectureDescription.Security.Optional Security Enablers.ContentBasedSecurity.

General CBS API Information

Resources Summary

The mapping of CBS functionality to a resource tree is shown in the figure below.

CBS API resource tree

Authentication

Users authenticate using Basic or Digest authentication prior to accessing the service.

Representation Format

The Content Based Security API supports the transmission of XML and JSON documents. The request format is specified using the Content-Type header and is required for operations that have a request body. The response format can be specified in requests using the Accept header.

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 the wrapped representation. In addition, both client and server may use as many HTTP headers as they consider necessary.

Limits

Limits are not yet specified for Version 1 of the Content Based Security GE.

Versions

Querying the version is not supported in Version 1 of the Content Based Security GE.

Extensions

Querying extensions is not supported in Version 1 of the Content Based Security GE.

Faults

Fault ElementAssociated Error CodesExpected in All Requests?Description
Bad Request400YesThe request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on).
Unauthorised401YesClient authentication is required.
Forbidden403YesThe request was a valid request and the server understood it, but is refusing to fulfil it, e.g. because the rule set installed in the server does not permit the request.
Not Found404YesThe request specified a URI of a resource that does not exist.
Method Not Allowed405YesThe HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
Not Acceptable406YesThe resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
Internal Server Error500YesThe server encountered an unexpected condition which prevented it from fulfilling the request.
Not Implemented501YesThe server does not (currently) support the functionality required to fulfil the request.
Service Unavailable503YesThe server is currently unable to handle the request due to temporary overloading or maintenance of the server.

Data Types

This subsection describes the data structures used in the Content Based Security API.

Type: UnprotectedContainer

A data type representing an unprotected data container (i.e. before encryption and/or signing have been applied).

NameTypeRequiredDescription
modetexttrueThe data protection mode to be applied to the protected representation of this container. Possible values are:
  • ENCRYPT
  • SIGN
  • SIGN_THEN_ENCRYPT
  • ENCRYPT_THEN_SIGN
headerskeyValue [0..*]falseA collection of keyValue entries representing headers to be included in the container. If there are no header entries, this may be omitted.

In some cases a particular implementation or deployment may require particular header entries to be present, e.g. the mime-type of the data. The difference between container headers and container metadata is that metadata is included as input to the container key generation algorithm, while headers are not.

metadatakeyValue [0..*]falseA collection of keyValue entries representing metadata to be included in the container. If there are no metadata entries, this may be omitted.

In some cases a particular implementation or deployment may require particular metadata entries to be present. The difference between container headers and container metadata is that metadata is included as input to the container key generation algorithm, while headers are not.

payloadbase64 encoded binarytrueThe data (plaintext) to which the specified protection mode will be applied to the protected representation of this container.

Type: ProtectedContainer

A data type representing a protected container (i.e. after encrypting and/or signing).

NameTypeRequiredDescription
protectedContainerbase64 encoded binarytrueThis is the protected data returned to the user. The protected data is returned in a base64 encoded container.

Type: KeyValue

The KeyValue type is used in container headers and metadata to map a key to a value. The key name is used as the element name, while the value is the element content.

NameTypeRequiredDescription
keytexttrueKey with which the specified value is to be associated
valuetexttrueValue to be associated with the specified key

API Operations

In this section we describe each operation in depth. The operations are divided into two functions: CBS Producer and CBS Consumer. The CBS Producer functionality performs encryption and/or signs the provided data. The CBS Consumer decrypts and/or verifies the signature on the provided container.

CBS Producer

Request

POST //{serverRoot}/fiware.cbs.producer.service.webapp/api/cbss/protect

Request Parameters

None.

Request Body

A representation of the unprotected container to which the CBSS will apply protection.

Response

200 OK – The request was successful. The response body contains a representation of the protected container.

403 Forbidden - The user was not authorised to protect the data

Example Request

XML request:

POST /api/cbss/protect HTTP/1.1
Accept: application/xml
Content-type: application/xml

<unprotectedContainer>
 <mode>SIGN_THEN_ENCRYPT</mode>
 <headers>
  <key>value</key>
  ...
 </headers>
 <metadata>
  <key>value</key>
  ...
 </metadata>
 <payload>TWFuIGlzIGRpc3Rpbmd1a...</payload>
</unprotectedContainer>

JSON request:

POST /api/cbss/protect HTTP/1.1
Accept: application/json
Content-type: application/json

{
    "mode":"SIGN_THEN_ENCRYPT",
    "headers":{
        "key":"value",
        ...
    },
    "metadata":{
        "key":"value",
        ...
    },
    "payload":"TWFuIGlzIGRpc3Rpbmd1a..."
}

Example Response (Success)

XML response:

HTTP/1.1 200 OK
Content-Type: application/xml

<protectedContainer>dWVkIGFuZCBpbmRlZmF0aWdhY...</protectedContainer>

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{   
    "protectedContainer":" dWVkIGFuZCBpbmRlZmF0aWdhY..."
}

Example Response (Failure)

If the installed rule set does not permit the client to make the request, the following response will be returned:

HTTP/1.1 403 Forbidden

Encrypt failed (not authorised).

CBS Consumer

Request

POST //{serverRoot}/fiware.cbs.consumer.service.webapp/api/cbss/unprotect

Request Parameters

None.

Request Body

A representation of the protected container from which the CBSS will remove protection.

Response

200 OK – The request was successful. The response body contains a representation of the unprotected container.

400 Bad Request - The signature verification failed.

403 Forbidden - The user was not authorised to remove protection from the data.

Example Request

XML request:

POST /api/cbss/unprotect
Accept: application/xml
Content-Type: application/xml

<protectedContainer>dWVkIGFuZCBpbmRlZmF0aWdhY...</protectedContainer>

JSON request:

POST /api/cbss/unprotect HTTP/1.1
Accept: application/json
Content-type: application/json

{
    "protectedContainer":" dWVkIGFuZCBpbmRlZmF0aWdhY..."
}

Example Response (Success)

XML response:

HTTP/1.1 200 OK
Content-Type: application/xml

<unprotectedContainer>
 <mode>SIGN_THEN_ENCRYPT</mode>
 <headers>
  <key>value</key>
  ...
 </headers>
 <metadata>
  <key>value</key>
  ...
 </metadata>
 <payload>TWFuIGlzIGRpc3Rpbmd1a...</payload>
</unprotectedContainer>

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "mode":"SIGN_THEN_ENCRYPT",
    "headers":{
        "key":"value",
        ...
    },
    "metadata":{
        "key":"value",
        ...
    },
    "payload":"TWFuIGlzIGRpc3Rpbmd1a..."
}

Example Response (Failure)

If the installed rule set does not permit the client to make the request, the following response will be returned:

HTTP/1.1 403 Forbidden

Decrypt failed (not authorised).

If the signature verification failed, the following response will be returned:

HTTP/1.1 400 Bad request

Signature verification failed.
Personal tools
Create a book