From 621877b5ad49d0260cedf4c19b45fa2a06f17f58 Mon Sep 17 00:00:00 2001 From: Sebastian Schmittner Date: Tue, 8 Dec 2020 09:38:03 +0100 Subject: [PATCH] usage section improved (partly moved to package description). fixes #33 --- README.md | 36 +++++++++++++++++++----------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index d46567e..80d1979 100644 --- a/README.md +++ b/README.md @@ -5,41 +5,43 @@ ![Docker Release Build](https://github.com/RalphTro/epcis-event-hash-generator/workflows/Docker%20Release%20Build/badge.svg) This is a proposal/reference implementation for a method to uniquely identify an EPCIS event or validate the integrity thereof. To this end, a syntax-/representation-agnostic approach based on hashing is developed. -The PROTOTYPICAL DEMO SOFTWARE takes an EPCIS Document (either formatted in XML or JSON-LD) and returns the hash value(s) of the contained EPCIS events representing a unique fingerprint of the latter. +The PROTOTYPICAL DEMO SOFTWARE takes an EPCIS Document (either formatted in XML or JSON-LD) and returns the hash value(s) of the contained EPCIS events representing a unique fingerprint thereof. ![EPCIS event hash generator algorithm illustration](docs/epcisEventHashGenerator.jpg) -## Usage (TL;DR) -The script may be used as a command line utility like this: -``` -python epcis_event_hash_generator/main.py -h -``` +## TL;DR -Tests are run via -``` -cd tests; pytest -``` -where pytests needs to be intalles (`pip install pytest`). +The implementation provided here is a prototypical reference implementation meant for testing against other implementations, but **not meant for production**. If you discover that this implementation does not conform perfectly to the algorithm description or contains any other bugs, please file an issue at https://github.com/RalphTro/epcis-event-hash-generator/issues . -Build webapi docker image +### Command Line +The Hashing Algorithm described below is implemented as a python script, including a command line utility which can be run directly after checking out this repository via ``` -docker build . -f Dockerfile.webapi -t event-hash-generator +git clone https://github.com/RalphTro/epcis-event-hash-generator.git ``` -Run container +For usage information run ``` - docker run -p 5000:5000 event-hash-generator +epcis_event_hash_generator/main.py -h ``` -Sample request (note: replace {..} with full json/json-ld event payload) + +### Web Service + +The script also comes wrapped as a web service in a docker image for ease of integration into a testing environment. +You may use + +- [the latest release version of the web service container](https://github.com/RalphTro/epcis-event-hash-generator/packages/484860 ). See here for usage. + +You may also build the image directly from the code using e.g. ``` -curl --location --request -POST 'http://localhost:5000/hash' --header 'Content-Type: application/json' --data-raw '{..}' +docker build . -f Dockerfile.webapi -t event-hash-generator:nightly ``` + ## Introduction There are situations in which organisations require to uniquely refer to a specific EPCIS event. For instance, companies may only want to store the hash value of a given EPCIS event on a distributed shared ledger ('blockchain') instead of any actual payload. Digitally signed and in conjunction with a unique timestamp, this is a powerful and effective way to prove the integrity of the underlying event data. Another use case consists to use such an approach to populate the eventID field with values that are intrinsic to the EPCIS event - if an organisation captures an event without an eventID (which is not required as of the standard) and sends that event to a business partner who needs to assign a unique ID, they can agree that the business partner populates the eventID field applying this methodology before storing the event on the server. If the organisation later wants to query for that specific event, it knows how the eventID was created, thus is able to query for it through the eventID value. EPCIS events have a couple of differences to other electronic documents: