This document describes the encryption service developed at ITESM as a tool for encrypting and decrypting FIWARE data models.
FIWARE is a curated framework of open source platform components to accelerate the development of Smart solutions. The FIWARE platform provides a rather simple yet powerful set of APIs (Application Programming Interfaces) that ease the development of Smart Applications in multiple vertical sectors.
The main and only mandatory component of any "Powered by FIWARE" platform or solution is the FIWARE Orion Context Broker Generic Enabler, which brings a cornerstone function in any smart solution: the need to manage context information in a highly decentralized and large-scale manner, enabling to perform updates and bring access to context.
FIWARE data models have been harmonized to enable data portability for different applications including, but not limited, to Smart Cities. They are intended to be used together with FIWARE NGSI version 2.
The application can be seen as two stand-alone services, one that uses tokens as a security measure and the second one that uses sessions as a security measure. Both stand-alone services enable the encryption and decryption of all up-to-date available FIWARE data models published in FIWARE Data Models official site.
The encryption service can be installed on any Operative System.
The following software must be previously installed in the server which will hold the encryption service.
Furthermore, the following ports containers are required.
- ngsi_nodejs 8000 (only for the token-based service)
- ngsi_python 2121 (only for the session-based service)
In the following, the service specifications are described. These specifications apply to both stand-alone services mentioned above. The inputs that the encryption service expect are listed below.
- Orion URL Source or a JSON payload
- Orion URL Target or a JSON payload
- User name
- User email
- Keys generated by the encryption process
- Token generated by the encryption service
In the following are described several details about the encryption service.
- Due to context broker’s limits on attribute lengths, the encryption algorithm relies on 8-bit keys.
- For each attribute of the JSON payload, a key is generated. All the keys are integrated into a single file. This single file is then sent to the user via email.
The services that both stand-alone implemented services comprise are:
- Sign up
- Sign in
- Encryption of a local JSON file
- Encryption of entities from an Orion Context Broker URL
- Encryption of a local JSON file or entities from an Orion Context Broker URL and send them to a Context Broker URL
- Decryption of a local JSON file
- Decryption of entities from an Orion Context Broker URL
- Decryption of a local JSON file or entities from an Orion Context Broker URL and send them to a Context Broker URL
The initial authentication procedure carried out by the encryption service is performed via an email verification process. This process allows a user to authenticate itself within the service. It is noteworthy that the authentication procedure currently works only with Gmail accounts. The process is simplified as follows:
Input: User name (#3 in the overall input definition) and User email (#4 in the overall input definition)
Output: Token generated by the encryption service
Postman/Insomnia specifications
HTTP endpoint:
POST
Uri: http://ngsi-edlayer/signup
Params (Form URL Encoded):
name: User name (3)
email: User email (4)
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
The stand-alone encryption service that uses tokens as a verification measure is described below.
The following procedure denotes the instructions to deploy and execute the encryption service that will reside in the server.
-
Open a terminal in the location of the service's folder:
cd token_based
-
Execute the docker pull command:
docker pull smartsdk/encryption-service-token
-
Start the docker compose:
sudo docker-compose up -d
-
Check docker containers status:
docker ps
-
Verify that the service is up and running:
http://localhost:8000
This service allows the user to authenticate itself for the first time into the encryption service.
Input:
3 and 4
Output:
6 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/signup
Input params:
name: 3
email: 4
This service allows the user to authenticate itself into the encryption service and use the several encryption and decryption services implemented.
Input:
3 and 4
Output:
6 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/authenticate
Input params:
name: 3
email: 4
This process shows an example of how a user uploads a local JSON file into the service, encrypt it, sees the encrypted JSON file through the postman/insomnia interface, and receives the keys for decrypt the JSON file via email. To download the encrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the encrypted JSON file to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1 and 6
Output:
2 via postman/insomnia interface and 5 via email
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/encrypt
Input params:
json: document in JSON format
Headers:
Authorization: user token
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user specifies entities from an Orion Context Broker URL, encrypt them, sees the encrypted entities through the postman/insomnia interface, and receives the keys for decrypt the JSON file via email. To download the encrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the encrypted entities to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1 and 2
Output:
2 via postman/insomnia interface and 5 via email
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/encrypt/ocb-local
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
Headers:
Authorization: user token
Fiware-Service:'default'
Fiware-ServicePath:'/'
Encryption of a local JSON file or entities from an Orion Context Broker URL and send them to a Context Broker URL
This process shows an example of how a user specifies entities from an Orion Context Broker URL or uploads a local JSON file, encrypt them/it, and send the encrypted entities to an Orion Context Broker URL. Furthermore, the service shows the encrypted JSON file or entities through the postman/insomnia interface and the user receives the keys for decrypt the information via email. To download the encrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download directly from the postman/insomnia interface.
Input:
1 and 2
Output:
2 via postman/insomnia interface and 5 via email
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/encrypt/ocb
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
urlTo: http://192.168.10.193:1026/v2/entities
Headers:
Authorization: user token
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user uploads a local encrypted JSON file and its corresponding key's file into the service, decrypt it, and sees the decrypted JSON file through the postman/insomnia interface. To download the decrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the decrypted JSON file to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1 and 5
Output:
2 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/decrypt
Input params:
json: document in JSON format
key: keys sent to users email
Headers:
Authorization: user token
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user specifies entities from an Orion Context Broker URL and uploads its corresponding key's file into the service, decrypt them, and sees the decrypted entities through the postman/insomnia interface. To download the decrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the decrypted entities to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1, 2, and 5
Output:
2 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/decrypt/ocb-local
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
key : keys sent to users email
Headers:
Authorization: user token
Fiware-Service:'default'
Fiware-ServicePath:'/'
Decryption of a local JSON file or entities from an Orion Context Broker URL and send them to a Context Broker URL
This process shows an example of how a user specifies entities from an Orion Context Broker URL or uploads a local JSON file with its corresponding key's file, decrypt them/it, and then send the decrypted entities to an Orion Context Broker URL. Furthermore, the service shows the decrypted JSON file or entities through the postman/insomnia interface. To download the decrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface.
Input:
1, 2, and 5
Output:
2 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:8000/decrypt/ocb
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
urlTo: http://192.168.10.193:1026/v2/entities
key : keys sent to users email
Headers:
Authorization: user token
Fiware-Service:'default'
Fiware-ServicePath:'/'
The stand-alone encryption service that uses sessions as a verification measure is described below.
The following procedure denotes the instructions to deploy and execute the encryption service that will reside in the server.
-
Open a terminal in the location of the service's folder:
cd ../data-encryption/session based
-
Create a new folder called “data”:
mkdir data
-
Start the docker compose:
sudo docker-compose up -d
-
Check docker containers status:
docker ps
-
Verify that the service is up and running:
http://localhost:2121
This service allows the user to authenticate itself for the first time into the encryption service.
Input:
3 and 4
Output:
Verification via email
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/signup
Input params:
name: 3
email: 4
password: user password
This service allows the user to authenticate itself into the encryption service and use the several encryption and decryption services implemented.
Input:
3
Output:
6 via email or postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/login
Input params:
name: 3
password: user password
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user uploads a local JSON file into the service, encrypt it, sees the encrypted JSON file through the postman/insomnia interface, and receives the keys for decrypt the JSON file via email. To download the encrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the encrypted JSON file to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1
Output:
2 via postman/insomnia interface and 5 via email
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/encrypt
Input params:
json: document in JSON format
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user specifies entities from an Orion Context Broker URL, encrypt them, sees the encrypted entities through the postman/insomnia interface, and receives the keys for decrypt the JSON file via email. To download the encrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the encrypted entities to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1 and 2
Output:
5 via email or postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/encrypt/ocb/local
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
Encryption of a local JSON file or entities from an Orion Context Broker URL and send them to a Context Broker URL
This process shows an example of how a user specifies entities from an Orion Context Broker URL or uploads a local JSON file, encrypt them/it, and then send the encrypted entities to an Orion Context Broker URL. Furthermore, the service shows the encrypted JSON file or entities through the postman/insomnia interface and the user receives the keys for decrypt the information via email. To download the encrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface.
Input:
1 and 2
Output:
5 via email or postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/encrypt/ocb
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
urlTo: http://192.168.10.193:1026/v2/entities
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user uploads a local encrypted JSON file and its corresponding key's file into the service, decrypt it, and then sees the decrypted JSON file through the postman/insomnia interface. To download the decrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the decrypted JSON file to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1 and 5
Output:
2 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/decrypt
Input params:
json: document in JSON format
key: keys sent to users email
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
This process shows an example of how a user specifies entities from an Orion Context Broker URL and uploads its corresponding key's file into the service, decrypt them, and then sees the decrypted entities through the postman/insomnia interface. To download the decrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface. This service does not send the decrypted entities to an Orion Context Broker URL; the service that allows this is explained below.
Input:
1, 2, and 5
Output:
2 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/decrypt/ocb/local
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
key : keys sent to users email
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
Decryption of a local JSON file or entities from an Orion Context Broker URL and send them to a Context Broker URL
This process shows an example of how a user specifies entities from an Orion Context Broker URL or uploads a local JSON file with its corresponding key's file, decrypt them/it, and then send the decrypted entities to an Orion Context Broker URL. Furthermore, the service shows the decrypted JSON file or entities through the postman/insomnia interface. To download the decrypted JSON file, the user must copy the postman/insomnia response into a text file and save it with the JSON extension or download it directly from the postman/insomnia interface.
Input:
1, 2, and 5
Output:
2 via postman/insomnia interface
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/decrypt/ocb
Input params:
urlFrom: example http://127.0.0.1:1026/v2/entities
id: id attribute to identify the entity
type: type attribute to identify the entity
urlTo: http://192.168.10.193:1026/v2/entities
key : keys sent to users email
Headers:
Fiware-Service:'default'
Fiware-ServicePath:'/'
This service allows the user to sign out of the encryption service.
Input:
None
Output:
None
Postman/Insomnia specifications
Http endpoint:
URL: http://127.0.0.1:2121/logout
Input params:
None
