Community Documentation: File Validator (FV)

Documentation

How it works

Let's consider the operation of the system using a real example. Let there be a publisher Emercoin, which is its own validator (the simplest case). The publisher has released a binary installer for the Emercoin wallet for Windows, file name: emercoin-0.7.10-win64-setup.exe.

Publisher

The publisher Emercoin wishes to take advantage of the proposed FV system so that users can check the resulting binary and make sure they get exactly what the publisher distributes.

To do this, he hashes the file with the sha256 algorithm (the system assumes changing the algorithm if necessary), and receives the hash of the file:

169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

The publisher, based on the hash sum, creates a search name that will act as a key in Emercoin NVS:

fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

Here:

fv: Service prefix, File Validator
sha256: hashing algorithm (default sha256, but it is possible to replace it with other algorithms in the future)
hex string: hash sum of the file.

After that, the publisher submits the file for verification and signature to validators of his choice. In our example, the developer himself acts as a validator.

Validator

The validator has a unique name in Emercoin NVS, with which the Emercoin address is associated. The name has a service prefix “val:”, and can contain only lowercase Latin characters, as well as a period and minus. That is, the allowed set of characters is [a-z.-]. Spaces, tabs, special characters or symbols of national encodings are also prohibited. This limitation is intended to block manipulations that allow you to create externally similar names of validators and sign anything on their behalf. A typical example of such manipulation is outwardly similar, but different names: paypal - paypaI - paypa1.

For example, the name of the validator olegarch is correct, but the name o1egarch is incorrect, since it contains the number 1.

In our example, the validator is Emercoin, which owns the NVS name val:emercoin associated with address: EcXrMDf8YyLMFk6RCnkAnPm9fmDBfu5eQX

Based on the received file, the validator creates the search name in the same way as the publisher did. The publisher then creates a signature line:

emercoin|100|fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

Here:

emercoin: NVS name of the validator.
100: Trust level (reserved for future use).
fv..f6: search name similar to publisher.

The validator signs this line with the signmessage command in its wallet with the address EcXrMDf8YyLMFk6RCnkAnPm9fmDBfu5eQX associated with the validator name val:emercoin:

signmessage EcXrMDf8YyLMFk6RCnkAnPm9fmDBfu5eQX em..f6

Received digital signature IH0yysgQpP1xIjRcJPrWaDVrl9B35BfrNcgOdwNm1gjFeE2zpKZZooSd55LydWlPnnlfnLiI+2Q1VUzzsD/8irE=

The validator passes it to the publisher.

The publisher, having received a signature from the validator, creates and publishes an NVS record in the blockchain, where the search key is the name, and value contains a string with the signature:

SIG=emercoin|100|IH0yysgQpP1xIjRcJPrWaDVrl9B35BfrNcgOdwNm1gjFeE2zpKZZooSd55LydWlPnnlfnLiI+2Q1VUzzsD/8irE=

Here:

SIG=: A prefix specifying a digital signature.
emercoin: NVS name of the validator.
100: Trust level (reserved for future use).
IH..E=: digital signature of the validator.

Value can contain several signature lines and other lines containing arbitrary information about the file being signed. For example, a real NVS record about our file has the structure:

Name:

fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

Value:

Emercoin core wallet, full node
File: emercoin-0.7.10-win64-setup.exe
Download: https://emercoin.com/en/for-coinholders#download
SIG=emercoin|100|IH0yysgQpP1xIjRcJPrWaDVrl9B35BfrNcgOdwNm1gjFeE2zpKZZooSd55LydWlPnnlfnLiI+2Q1VUzzsD/8irE=
SIG=olegarch|100|H32Bp3cLoqBFvlyUIIXLrKX3TD+IG2aX2dmegy4oIxGEWeKBw9YTITKWaFWM4UdejEgpH5em4Gi/ZfoZFU69Owk=

Here we see that the file information contains signatures from two validators - emercoin and olegarch.

User

The user, having received a file from an untrusted source, wants to make sure that this file is exactly the one published by the publisher. To do this, they take the following actions:

Hashes the file, and gets its sha256 hash, for example with the command:

$ sha256sum emercoin-0.7.10-win64-setup.exe
169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a emercoin-0.7.10-win64-setup.exe

Based on the received hash, the user forms a search name in the same way as the publisher did (see above):

fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

Retrieves information about the received file from Emercoin NVS using the name_show command:

name_show fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a
{
  "name": "fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a",
  "value": "Emercoin core wallet, full node\nFile: emercoin-0.7.10-win64-setup.exe\nDownload: https://emercoin.com/en/for-coinholders#download\nSIG=emercoin|100|IH0yysgQpP1xIjRcJPrWaDVrl9B35BfrNcgOdwNm1gjFeE2zpKZZooSd55LydWlPnnlfnLiI+2Q1VUzzsD/8irE=\nSIG=olegarch|100|H32Bp3cLoqBFvlyUIIXLrKX3TD+IG2aX2dmegy4oIxGEWeKBw9YTITKWaFWM4UdejEgpH5em4Gi/ZfoZFU69Owk=",
  "txid": "a22fa9b5ac1725d30e6e6dc9bb2038b0a0afbe362031eb8b9d9a4392e0cc46ff",
  "address": "EfsrojhfLGf6LPYRFytiaGRVwYmQ9KsWN5",
  "expires_in": 957918,
  "expires_at": 1391644,
  "time": 1598137455
}

From the obtained result, extracts the lines with signatures:

SIG=emercoin|100|IH0yysgQpP1xIjRcJPrWaDVrl9B35BfrNcgOdwNm1gjFeE2zpKZZooSd55LydWlPnnlfnLiI+2Q1VUzzsD/8irE=
SIG=olegarch|100|H32Bp3cLoqBFvlyUIIXLrKX3TD+IG2aX2dmegy4oIxGEWeKBw9YTITKWaFWM4UdejEgpH5em4Gi/ZfoZFU69Owk=

The user verifies all or selectively some of the signatures as follows:

Extracts the name of the validator from the string, in our example emercoin.
By querying name_show on val:emercoin, gets the EMC address associated with this name: EcXrMDf8YyLMFk6RCnkAnPm9fmDBfu5eQX.
Extracts from the string the signature of the validator IH..e =
Forms a string for signature in the same way as the validator did:

fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

With the verifymessage request, the user verifies the validity of the signature:

verifymessage address signature signature_string

In our example, this is

verifymessage EcXrMDf8YyLMFk6RCnkAnPm9fmDBfu5eQX IH0yysgQpP1xIjRcJPrWaDVrl9B35BfrNcgOdwNm1gjFeE2zpKZZooSd55LydWlPnn=2UZZooSd55LydWlElf2lf
emercoin|100|fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a

Having received the result of the scan, the user decides what to do with the scanned file.

How to use it

Above, in the section “how it works”, a step-by-step algorithm was provided for both generating and publishing signatures and verifying files. It is clear that it is difficult to do all these operations manually, especially for the end user. Therefore, for practical use, we wrote the fv.php program, which can be downloaded from the Emercoin repository:

https://github.com/emercoin/FV

This program is also a “reference implementation” of the algorithms discussed above, and can be used as a practical example to write a similar program or to integrate the FV system into package managers or other programs and services.

The program was originally written for Linux / FreeBSD, but it can also be launched from the Windows command line, for example, according to the instructions:

https://stackoverflow.com/questions/12870880/run-php-file-in-windows-command-prompt-cmd

After downloading, in the program, you need to edit the URL to connect to the local wallet, setting there the current username / password / port parameters:

$ emcCONNECT="http://user:secret_pass@localhost:6662";

It is also possible for Windows to remove the first line of the file specifying the interpreter:

#!/usr/bin/php

Using the program

Testing

First, you need to make sure that the program starts without errors and connects correctly to the Emercoin wallet:

$ ./fv.php -getinfo

If the actual parameters are set correctly, the program will write the result to getinfo, and you can proceed to further work.

File check

To do this, you need to run the program with only one parameter - the file name, and it will carry out the entire validation process.

File info from NVS:
    Emercoin core wallet, full node
    File: emercoin-0.7.10-win64-setup.exe
    Download: https://emercoin.com/en/for-coinholders#download

Validation results:
    emercoin/EMERCOIN [Emercoin File Validator] created 2020-08-20 05:08; Signature PASSED
    olegarch/OLEGARCH [Oleg Khovayko FV] created 2020-08-20 02:08; Signature PASSED

In the example above, the program reports the creation time of the NVS record for this file (records that are too recent for old files may raise suspicion), as well as the results of signature checks. Here you can see that for this file, the signatures from both validators were verified successfully, and the file does not contain unauthorized changes.

Generating a validator signature

To generate a signature, your wallet must contain an NVS-record of the validator, and be fully unlocked.

To generate a signature, you need to specify the file name to the program, and a string containing the name of the validator and the level of trust (how much the validator trusts the publisher of the file). The second parameter must be enclosed in quotes, otherwise the command line interpreter will interpret the "|" as a shell pipe.

Startup example and result:

$ ./fv.php ./emercoin-0.7.10-win64-setup.exe 'olegarch|100'

FV signature for upload to NVS FV-record:
NVS Key:
	fv:sha256=169dc5dd293cd82f84737055403ae87a62008072d785376f56f6d309288a092a
Signature line:
	SIG=olegarch|100|H32Bp3cLoqBFvlyUIIXLrKX3TD+IG2aX2dmegy4oIxGEWeKBw9YTITKWaFWM4UdejEgpH5em4Gi/ZfoZFU69Owk=

As a result, the program returns an NVS-key and a signature for transmission to the publisher. The publisher can load these parameters into NVS, or combine signatures from several publishers into value.