README.md 20.2 KB
Newer Older
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
1

Tewodros Beyene's avatar
Tewodros Beyene committed
2
# ETB
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
3

Tewodros Beyene's avatar
Tewodros Beyene committed
4 5 6
ETB is a framework for defining and executing distributed workflows that produce claims supported by evidence.
ETB uses Datalog as the workflow scripting language.
<!--  
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
7
It is composed of ETB2, which is a complete reengineering of the Evidential Tool Bus (ETB) using Java integrated with
Tewodros Beyene's avatar
Tewodros Beyene committed
8 9
the Distributed Evidence Network (DEN) implemented with Hyperledger Fabric.
The distributed network acts as a substrate for a secure distributed
10
execution of ETB2 services and it is based on a combination of distributed ledger technologies (DLT).
Tewodros Beyene's avatar
Tewodros Beyene committed
11
-->
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
12

Tewodros Beyene's avatar
Tewodros Beyene committed
13
## Getting Started with ETB
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
14

Tewodros Beyene's avatar
Tewodros Beyene committed
15
These instructions will get you an ETB node up and running on your local machine for testing purposes.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
16 17 18

### Prerequisites

Tewodros Beyene's avatar
Tewodros Beyene committed
19 20 21 22 23 24
The following components are required to compile and run ETB.
- JDK
- Maven

Optional
- eclipse
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
25

Tewodros Beyene's avatar
Tewodros Beyene committed
26
### Installation and preparation
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
27

Tewodros Beyene's avatar
Tewodros Beyene committed
28
1. Clone the ETB project  
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
29 30

	```console
Tewodros Beyene's avatar
Tewodros Beyene committed
31
	$ git clone https://git.fortiss.org/evidentia/etb.git
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
32 33
	```

Tewodros Beyene's avatar
Tewodros Beyene committed
34
2. Go to the cloned directory and build ETB
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
35 36

	```console
Tewodros Beyene's avatar
Tewodros Beyene committed
37
	$ cd ETB && mvn compile
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
38
	```
Tewodros Beyene's avatar
Tewodros Beyene committed
39
	Maven will import all the dependencies and build ETB. You can use standard maven procedures to run ETB from command line or from editors like eclipse. The rest of this README explains how to run ETB commands from the command line.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
40

Tewodros Beyene's avatar
Tewodros Beyene committed
41 42 43 44 45 46
	<!--  
	It is composed of ETB2, which is a complete reengineering of the Evidential Tool Bus (ETB) using Java integrated with
	the Distributed Evidence Network (DEN) implemented with Hyperledger Fabric.
	The distributed network acts as a substrate for a secure distributed
	execution of ETB2 services and it is based on a combination of distributed ledger technologies (DLT).
	The text **<span style="color:green">ETB built successfully</span>** at the end of the building process signals success.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
47 48 49 50 51 52 53 54 55 56

	```console
	javac -cp .:dependencies/commons-exec-1.3.jar:dependencies/commons-io-2.6.jar:dependencies/json-simple-2.1.2.jar:dependencies/org.json.jar -d . etbDL/engine/* etbDL/utils/* etbDL/etbDatalog.java etbDL/etbDatalogEngine.java etbDL/statement/* etbDL/output/* etbDL/services/* etbCS/utils/* etbCS/etbNode.java etbCS/clientMode.java
	Note: Some input files use or override a deprecated API.
	Note: Recompile with -Xlint:deprecation for details.
	Note: Some input files use unchecked or unsafe operations.
	Note: Recompile with -Xlint:unchecked for details.
	$ ETB2 built successfully$
	```

Tewodros Beyene's avatar
Tewodros Beyene committed
57
	The text <span style="color:red">ETB has failed to build</span> signals problem with the building process. One possible problem could be the access right for the **build.sh** shell script file, and make sure that it is executable by running the command below.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
58 59 60 61 62

	```console
	$ chmod -x build.sh
	```

Tewodros Beyene's avatar
Tewodros Beyene committed
63 64
	3. Let us set up ETB by adding the alias command **alias etb2='java -cp .:$dependencies/commons-exec-1.3.jar:dependencies/commons-io-2.6.jar:dependencies/json-simple-2.1.2.jar:dependencies/org.json.jar etb/etbCS/etbNode'** in your **bash_profile**, **bashrc** or similar locations.
	$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-add-claim \"advTwoStepCR('src/null_pointer.c', 'src/spec.c', Mr, Rr, Fr)\""
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
65

Tewodros Beyene's avatar
Tewodros Beyene committed
66 67 68
	-->

3. All available ETB commands can be seen by running the -help command.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
69 70

	```console
Tewodros Beyene's avatar
Tewodros Beyene committed
71
	$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-help"
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
72 73
	```

Tewodros Beyene's avatar
Tewodros Beyene committed
74
	This displays the help menu of ETB.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
75 76 77 78

	```console
	Overview:  ETB 2.0 - Evidential Tool Bus (Linux 64-bit version)

Tewodros Beyene's avatar
Tewodros Beyene committed
79
	Usage:     mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="[options] <inputs>"
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
80 81

	Options:
Tewodros Beyene's avatar
Tewodros Beyene committed
82 83 84 85 86

	-help/-h          shows this help menue
	-init <configFile>            initialises an entity at a given location
	-show-info        displays details of the node, like its port, claims, workflows, local services and available remote servers/services
	-show-modes      displays status of all evidentia modes
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
87
	-clean            removes available local services and remote servers from the server
Tewodros Beyene's avatar
Tewodros Beyene committed
88 89 90 91 92 93 94 95 96 97 98 99 100
	-uninit           deletes initialisation componenets of the node
	-set-port <port>        sets integer <port> as the port number of the entity
	-set-repo <dir>                 sets <dir> as the git repo used as working directory
	-set-mode <mode>                sets evidentia to the given mode, e.g., -noDEN, -DEN, etc.
	-add-service <configFile>       adds local service(s) to the server
	-rm-service <serviceID>                    removes local service(s) from the node
	-add-claim <query>          adds claim(s) to the etb node
	-rm-claim <claimID>                  removes claim(s) from the etb node
	-update-claim <claimID>     updates an outdated claim
	-upgrade-claim              upgrades an outdated claim
	-reconst-claim      reconstructs an outdated claim
	-export             exports services and workflows of the entity into a directory
	-import <dir>       imports services and workflows to the entity from the directory <dir>
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
101 102
	```

Tewodros Beyene's avatar
Tewodros Beyene committed
103
##  Running ETB
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
104

Tewodros Beyene's avatar
Tewodros Beyene committed
105
If we run ETB with the '-show-info' (or any other option) now, we get a notification that no ETB node is currently initialized at the given location.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
106

Tewodros Beyene's avatar
Tewodros Beyene committed
107 108 109 110
```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-show-info"
[error] no ETB node at this location (use -init to initialise an ETB node)
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
111

Tewodros Beyene's avatar
Tewodros Beyene committed
112
In this section, we see how an ETB node can be initialized on a local machine and used for integrating and continuous verification tasks to generate verification claims supported by evidences.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
113

Tewodros Beyene's avatar
Tewodros Beyene committed
114
### Node initialisation
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
115

116
The first step in using ETB is initializing an ETB node, which is done by running ETB with the option **-init <PathToInitFile\>**.
Tewodros Beyene's avatar
Tewodros Beyene committed
117 118 119
The initialization file specifies a port number and a directory to be used by the ETB node.
This specification is written in json.   
For example, the file *test/configFiles/init.txt*, which is part of this distribution, contains the following json object.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
120

121 122 123 124 125
```json
{
	"port": "4010",
	"repoDirPath": "TempRepo"
}
Tewodros Beyene's avatar
Tewodros Beyene committed
126
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
127

Tewodros Beyene's avatar
Tewodros Beyene committed
128 129
This specification will be used to initialize an ETB node at port **4010**, and the new node uses the directory **TempRepo** as its workspace.
If no director with that name exists, ETB will create it during the initialization process.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
130

Tewodros Beyene's avatar
Tewodros Beyene committed
131
We run the command below to initialize the ETB node.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
132

Tewodros Beyene's avatar
Tewodros Beyene committed
133 134 135
```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-init test/configFiles/initFile.txt"
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
136

Tewodros Beyene's avatar
Tewodros Beyene committed
137
A successful initialization of the node is signaled by the message below.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
138

Tewodros Beyene's avatar
Tewodros Beyene committed
139 140 141
```console
ETB node initialized (use -h to see more options to update the node)
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
142

Tewodros Beyene's avatar
Tewodros Beyene committed
143
Once a node is initialized, if we run ETB with the option '-show-info', we get information about the new node, as shown below.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
144

Tewodros Beyene's avatar
Tewodros Beyene committed
145 146 147 148 149 150 151 152 153 154
```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-show-info"
hostIP : 192.168.0.32
port : 4010
git repo path : ETB/TempRepo
==> total number of claims: 0
==> total number of workflows: 0
==> total number of local services: 0
==> total number of servers: 0
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
155

Tewodros Beyene's avatar
Tewodros Beyene committed
156
You can see that the port number and the git repo provided above during the initialization step in the node info. The hostIP parameter is the host machine's IP address, which is automatically read by ETB during the node initialization.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
157

Tewodros Beyene's avatar
Tewodros Beyene committed
158
Note that the number of claims, workflows, local services and servers are all set to zero. This is not surprising as the node is just created and we have not yet any of these components.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
159

Tewodros Beyene's avatar
Tewodros Beyene committed
160
### Adding service
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
161

Tewodros Beyene's avatar
Tewodros Beyene committed
162
Any service can be made available to the node by adding the service using the option **-add-service <PathToServiceSpecFile\>**, where the second argument is path to a specification file of the service.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
163

Tewodros Beyene's avatar
Tewodros Beyene committed
164
This specification file contains a json object with the following 3 entires.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
165

Tewodros Beyene's avatar
Tewodros Beyene committed
166
- *ID* - a unique identifier for the service.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
167

Tewodros Beyene's avatar
Tewodros Beyene committed
168
- *signature* - a list of argument types for a given service.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
169

Tewodros Beyene's avatar
Tewodros Beyene committed
170 171 172
	We currently support 4 argument types in ETB; *string*, *file*, *string_list* and *file_list*.
	Syntactically, a service signature is a list of such types separated by (at least one) space.
	For example, the signature '*file file_list string*' specifies that a given service has *file* as type for its first argument, *list of files* as type for its second argument, and *string* as type for its third argument.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
173

Tewodros Beyene's avatar
Tewodros Beyene committed
174
- *modes* - a set of possible service invocation modes.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
175

Tewodros Beyene's avatar
Tewodros Beyene committed
176 177 178 179 180
	A service mode for a given service defines which of the service arguments are given as inputs during its invocation, and which of its arguments are outputs expected to be produced at the end of its execution.
	Inspired by prolog predicate input/output notation, we use **+** for input arguments and **-** for output arguments.
	For example, the mode **++-** for a service with three arguments specifies that the first two arguments are inputs and the third argument is the output of the service.
	In ETB, a service can be invoked in different modes at different times, and hence, a set of such possible modes is one specification of the service.
	An example set of modes for a given service is is **{++-, +++}**.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
181 182


Tewodros Beyene's avatar
Tewodros Beyene committed
183
For example, the file *test/configFiles/service.txt*, which is part of this distribution, contains a service specification in the form of the json object given below.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
184

185 186 187 188 189 190
```json
{
	"ID": "genPDF",
	"signature": ["file", "file", "file"],
	"modes":["++-"]
}
Tewodros Beyene's avatar
Tewodros Beyene committed
191
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
192

Tewodros Beyene's avatar
Tewodros Beyene committed
193
We run the command below to add a service, e.g., the *genPDF* service specified above.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
194

Tewodros Beyene's avatar
Tewodros Beyene committed
195 196 197
```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-add-service test/configFiles/service.txt"
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
198

Tewodros Beyene's avatar
Tewodros Beyene committed
199
A successful addition of the service to the node is signaled by the message below.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
200

Tewodros Beyene's avatar
Tewodros Beyene committed
201 202 203
```console
=> service added successfully
```
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
204

205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275
By adding a service to the node, we make a given service available for the workflows to use the service.
The definition of the service, i.e., what is does with the inputs and how it produces its output must be specified by the service itself.
ETB enables this by automatically generating wrappers for each added service.
You can find the generated wrappers in the location *src/main/java/evidentia/wrappers*.
For each added service, ETB generates two wrapper template files, called ETB and user wrapper files.
For example, ETB generates the ETB wrapper file *genPDFETBWRP.java*, and the user wrapper file *genPDFWRP.java* for the *genPDF* service added above.

An ETB wrapper file, e.g., *genPDFETBWRP.java*, is used to automatically define all inputs and outputs of the service together their types, service invocation modes, evidence created during the service invocation, etc.
The ETB wrapper file is only for internal use by ETB.

A user wrapper file, e.g., *genPDFWRP.java*, extends the corresponding ETB wrapper file, and specifies the relation between service inputs and outputs.
This is done by overriding the *run* method.
You can see below the automatically generated *genPDFWRP.java* that the user needs to modify for the service to do something useful.

```java
public class genPDFWRP extends genPDFETBWRP {

	@Override
	public void run(){
		if (mode.equals("++-")) {
			//do something
		}
		else {
			System.out.println("unrecognized mode for genPDF");
		}
	}
}
```

As the *genPDF* service has three arguments, which can be inputs or outputs depending on the mode, ETB defines six variables in1, in2, and in3 for inputs and out1, out2, and out3 for outputs.
This definition is put in the ETB wrapper file *genPDFETBWRP.java*
As we specified above, the service has one mode, which is *++-*.
This means during the invocation of this mode, *in1* and *in2* will have input values, and ETB expects the result of the service execution to be written to *out3*.

You can see below the modified *run* method in the user wrapper.
The modified method now processes the input files *in1* and *in2*, and generates another file *out3*.
Remember, this service has *<file, file, file>* signature.

```java
	@Override
    public void run(){
        if (mode.equals("++-")) {
            File SourceFile = new File(in1);
            String FILEDIR = SourceFile.getParent();
            out3 = FILEDIR + "/" + in2 + "PDFreport.pdf";
            try {

                JSONParser parser = new JSONParser();
                Object JsonObj = parser.parse(new FileReader(in1));
                JSONArray Errors = (JSONArray) JsonObj;
                getReport(Errors, FILEDIR);


            } catch (IOException e) {
                e.printStackTrace();
            } catch (ParseException e) {
                e.printStackTrace();
            }
        }
        else {
            System.out.println("unrecognized mode for genPDF");
        }
    }
```

If the service could also be invoked in another mode, say *+--*, the *run* method will have another block for handing this mode.
It will be the user's responsibility to write the code which takes *in1* and generates *out2* and *out3* for this case as well.
As this wrappers are doing the input-to-output transformation themselves without calling external tools, they are acting as services.
However, the real power of ETB is when external services, e.g., testing or verification tools, are used in transforming the service inputs to outputs.  
In this case, the wrapper's role will be just formatting inputs and outputs, and hence, the name wrapper is more fitting.

Tewodros Beyene's avatar
Tewodros Beyene committed
276
### Removing service
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
277

Tewodros Beyene's avatar
Tewodros Beyene committed
278 279 280 281 282 283 284 285
If a service is no more required by an ETB node, it can be removed by running ETB with the option **-rm-service <serviceID\>**.
For example, to remove the service with ID *genPDF*, we run the command below.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-rm-service genPDF"
```

A successful removal of the service from the node is signaled by the message below.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
286

Tewodros Beyene's avatar
Tewodros Beyene committed
287 288 289 290 291 292 293 294
```console
=> service removed successfully
```

### Adding workflows

ETB uses Datalog as a scripting language to define verification workflows that employ services to accomplish integrated verification.
A workflow should be added to an ETB node to automate its execution.
295
This is done by adding the workflow using the option **-add-workflow <workFlowSpecificationFile\>**, where the second argument is path to a specification file of the workflow.
Tewodros Beyene's avatar
Tewodros Beyene committed
296 297 298 299 300 301 302 303 304 305

This workflow specification file contains a json object with the following 3 entires:

- *ID* - a unique identifier of the workflow

- *script* - path to a workflow script, which is a Datalog program that defines the logic of a given verification process.
Since ETB uses this script during the execution of the corresponding workflow, make sure workflow scripts are placed in the working directory of the node.

- *queries* - a list of queries (syntactically Datalog literals) that the workflow can compute the corresponding claims for.
	Syntactically, this list comprises a set of *query specifications*, where each *query specifications* is a tuple of the following 3 subcomponents separated by semicolons:
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
306 307

	- **name**: unique identifying string for the workflow
Tewodros Beyene's avatar
Tewodros Beyene committed
308

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
309 310
	- **signature**: list of data types in a bracket and separated by commas.
	An example *query signature* is *(file, file_list, string)*.
Tewodros Beyene's avatar
Tewodros Beyene committed
311

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
312 313 314 315
	- **mode**: invocation mode of the query. An example mode can be '*++-*'.

	An example *query list* is *{<twoStepCR; (file,file,file,file,file,file); +++++->, <threeStepCR; (file,file,file,file,file,file); +++++->}*.

Tewodros Beyene's avatar
Tewodros Beyene committed
316 317
 For example, the file *test/configFiles/workflow.txt*, which is part of this distribution, contains a workflow specification in the form of the json object given below.

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
318
```json
319 320 321 322 323 324 325 326 327 328 329
	{
		"ID": "twoStepCR",
		"script": "workflows/twoStepCR",
		"queries": [
			{
				"ID":"twoStepCR",
				"signature": ["file", "file", "file", "file"],
				"mode": "+---"
			}
		]
	}
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
330
```	
Tewodros Beyene's avatar
Tewodros Beyene committed
331 332 333

	We run the command below to add a workflow, e.g., the *twoStepCR* workflow specified above.

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
334 335 336
```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-add-workflow test/configFiles/workflow.txt"
```
Tewodros Beyene's avatar
Tewodros Beyene committed
337 338 339

	A successful addition of the workflow to the node is signaled by the message below.

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
340 341 342
```console
=> workflow added successfully
```	
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
343

Tewodros Beyene's avatar
Tewodros Beyene committed
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
### Removing workflow

A workflow can be removed by running ETB with the option **-rm-workflow <workflowID\>**.
For example, to remove the workflow with ID *twoStepCR*, we run the command below.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-rm-workflow twoStepCR"
```

A successful removal of the workflow from the node is confirmed by the following message.

```console
=> workflow removed successfully
```

359
### Adding claims
Tewodros Beyene's avatar
Tewodros Beyene committed
360

361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393
A claim is added to an ETB node using the option **-add-claim <query\>**, where the second argument is the query for whom the node is going to compute and add the corresponding claim.
An example query can be *twoStepCR('src/null_pointer.c', Mr, Rr, Fr)*, where *src/null_pointer.c* is the input, and the variables Mr, Rr and Fr represent the three outputs computed during the claim computation.

We run the command below to add a claim for the query specified above.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-add-claim \"twoStepCR('src/null_pointer.c', Mr, Rr, Fr)\""
```
Since the query should be given as a string, we must put it in double quotations. The Note that the quotation marks are escaped(in backslash) as maven's *-Dexec.args* itself expects list of strings.
If you are running ETB from eclipse, you can simply use *-add-claim "twoStepCR('src/null_pointer.c', Mr, Rr, Fr)"* as argument without the use of backslashes.

A successful addition of the claim to the node is signaled by the message below.

```console
=> claim added successfully
```

### Removing claims

A claim can be removed by running ETB with the option **-rm-claim <claimID\>**.
You can run ETB with the option '-show-info' to see details of existing claims, including the ID of each claim.
For example, to remove the claim with ID *89283923*, we run the command below.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-rm-claim 89283923"
```

A successful removal of the claim is confirmed by the following message.

```console
=> claim removed successfully
```

394 395 396 397 398 399
### Server mode
To run ETB in server mode run:
```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia"
```

400 401 402 403
### Node exporting and importing

Assume we have a node with a given set of services and workflows running at a given port and location.
If we want to have a different node, i.e., at different port or location, or even on another machine, node with the same services and workflows, ETB has the ability of exporting contents of the node and importing the contents to the other port.
404
Of course, the other port need to be initialized first.
405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438

To import contents of a given node, ETB is run with the option **-export <exportDir\>**, where the second argument is where the exported contents will be stored.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-export TEMP/toExport"
```

For example, after running the command above, ETB will export its content of the node to the directory *TEMP/toExport*.
This contents can be imported to another node by running ETB with option **-import <importDir\>**, where the second argument is a directory containing the contents to be  imported.
For example, if we have the contents to be imported (which are exported from another node) in the directoy *toImport*, we run the command below to import its contents to the node.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-import toImport"
```



### Node cleaning

If we want to remove all the service and claims in a given node, we can run ETB with the '-clean' option.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-clean"
```

### Node uninitialization

If we want to uninitialize an ETB node which was initialized at a given port and location, we can run ETB with the '-uninit' option.

```console
$ mvn exec:java -Dexec.mainClass="evidentia.Evidentia" -Dexec.args="-uninit"
```

Note that uninitialising a node results in permanent deletion of its working directory.
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
439

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
440
## Getting Started with the Distributed Evidence Network (DEN)
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
441
1. Start the distributed evidence network by following the instructions [here](https://git.fortiss.org/evidentia/den).
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
442
2. Copy cert.pem files from `crypto-config/peerOrganizations/../ca/` into `src/main/java/resources`  
Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
443
3. Copy `connection-profile.json` file to `src/main/java/resources`
444
4. Create a coordinator admin (admin_coordinator) and register coordinator user(coord).
Tewodros Beyene's avatar
Tewodros Beyene committed
445

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
446 447
### Start Entity
First, edit the `networkConfig.properties` file (found in src/main/resources/) with the network configurations.
Tewodros Beyene's avatar
Tewodros Beyene committed
448

Anastasios Kalogeropoulos's avatar
Anastasios Kalogeropoulos committed
449
 Then, run `Administrator.java` in order to:
Tewodros Beyene's avatar
Tewodros Beyene committed
450 451 452

    - enroll admin for the specified entity
    - register a user for the specified entity
453

454
Copy the admin and user coordinator identities (created in step 4) in the wallet directory.