Skip to content

Latest commit

 

History

History
129 lines (94 loc) · 5.13 KB

README.md

File metadata and controls

129 lines (94 loc) · 5.13 KB
Raw

Whiteflag WHL Utility

Introduction

Whiteflag is a fully neutral and secure communciations means based on blockchain technology. It enables near real-time communication in armed conflicts and disasters to exchange early warning and status information to create shared situational awareness.

This Whiteflag utility is a Node.js command line interface (CLI) that creates and sends Whiteflag messages for specified cultural heritage sites listed on the UNESCO World Heritage List. This is the digital equivalent of placing a physical protective sign.

Note that this utility only processes cultural heritage sites, because Whiteflag (currently) only defines a message (P52) that corresponds with the protective sign for cultural property i.a.w. the 1954 Hague Convention. The P52 protective sign message is followed by an R1(3) resource message with an URL linking the protective sign to the corresponding WHL entry.

This utility is for technology development, test and evaluation purposes only. This means that it is a tool in support of testing the Whiteflag protocol, but it is not designed and tested for secure usage and performance in a production environment.

Installation

Prerequisites

To deploy the Whiteflag WHL utility, make sure the following prerequisite software is installed:

Deployment

First, copy the repository to the deployment directory, such as /opt/whiteflag-whl. Please use a version tagged commit for a stable version.

After copying the repository, install the required Node.js modules of external software libraries and then create a global link to the package by running the following commands in the deployment directory:

npm install
npm link

Usage

To invoke the Whitefag WHL utility from the command line, use the wfwhl command with the following arguments from any directory:

wfwhl [-s <id> ...] [-w <url>|-f <file>]
      [-t -i <url> -b <blockchain> -a <address>] [-ov]

Options

The main options are the following:

  • -s, --sites : Specifies the world heritage site(s) by <id> number; multiple sites may be specified. If no sites are specified, all sites are processed.
  • -w, --web : The source <url> of the WHL in XML on the web. If not specified the default is https://whc.unesco.org/en/list/xml/. Cannot be used with -f.
  • -f, --file : The source <file> containing the WHL in XML. Cannot be used with -w.
  • -t, --transmit : Transmit the Whiteflag message(s) on the blockchain. Requires -i, -b and -a to be specified.
  • -i, --interface : The Whiteflag API REST interface <url> to post the message(s) to be sent.
  • -b, --blockchain : The <blockchain> to be used for sending the message(s).
  • -a, --address : The blockchain <address> to be used for sending the message(s).
  • -o, --stdout : Send the Whiteflag message(s) to stdout. This allows the data to be piped to other processes.
  • -v, --verbose : Provide detailed processing output.

Other supporting options are:

  • --help : Show help message.
  • --version : Show version number.
  • --config : Path to a JSON config file with preconfigured arguments; especially useful to specify Whiteflag API URL, blockchain and address.

Examples

To use the default WHL website as the source to create Whiteflag messages for world heritage site 23 and output them on standard output:

wfwhl -s 23 -o

To use a file with the WHL XML data as the source to create Whiteflag messages for 3 world heritage sites, with detailed processing information and the Whiteflag messages on standard output:

wfwhl -f /data/whl.xml -s 23 25 32 -o -v

To send Whiteflag messages for all cultural heritage sites from the WHL XML list contained in a file to standard output:

wfwhl -f /data/whl.xml -o

To transmit Whiteflag messages for 2 specified world heritage sites, with the Whiteflag API interface and blockchain details in a JSON configuration file and detailed processing information:

wfwhl -s 29 49 --config wfwhl.json -t -v

where the wfwhl.json configuration file contents may look as follows:

{
    "interface": "http://localhost:5746",
    "blockchain": "ethereum",
    "address": "10fe33a6a1B26877a2d6fA95eaf4153608B5B5f9"
}

License

The Whiteflag WHL utility is dedicated to the public domain under the Creative Commons CC0-1.0 Universal Public Domain Dedication. statement. Note that this only applies to this software, and that this explicitly DOES NOT imply endorsement or permission by UNESCO to use WHL information, which is subject to the terms and policies of the UNESCO World Heritage Centre. Please see LICENSE.md for details.

The Whiteflag WHL utility requires third party software packages, which are not part of this distribution and may be licenced differently.