From 067df19a6d14c225e94234415bd7e5a81f6cb976 Mon Sep 17 00:00:00 2001 From: olegfomenko Date: Thu, 2 May 2024 13:09:33 +0300 Subject: [PATCH] adding guides to docs --- .../core/003-csca-list-proposal-guide.md | 137 ++++++++++++++++++ docs/common/core/004-core.md | 10 ++ index.md | 2 + 3 files changed, 149 insertions(+) create mode 100644 docs/common/core/003-csca-list-proposal-guide.md create mode 100644 docs/common/core/004-core.md diff --git a/docs/common/core/003-csca-list-proposal-guide.md b/docs/common/core/003-csca-list-proposal-guide.md new file mode 100644 index 00000000..e607f232 --- /dev/null +++ b/docs/common/core/003-csca-list-proposal-guide.md @@ -0,0 +1,137 @@ +--- +layout: default +title: CSCA List proposal guide +--- + + +# CSCA List proposal guide + +## Overview + +This guide is focused on working with `rarimo-cored` CLI app. + +CSCA Master List is a list of root certificates of passport signing authorities. +The list itself is provided by [ICAO](https://www.icao.int/Pages/default.aspx) and contains +root certificates of passport issuing authorities for a lot of countries. +When obtained the passport signer's root certificate, you can check its presence in the Merkle tree, +stored on Rarimo chain in a decentralized manner. +This is how you ensure that the passport is signed by an eligible entity. + +Technical details can be found in [CSCA List Rarimo Core module](https://github.com/rarimo/rarimo-core/x/cscalist/README.md). + +The keys of CSCA signers can be compromised or updated, ergo list updates must be handled. +This is done via proposals. The guide will help you in creating and verifying proposals on list changes. + +## Pre-requisites + +CLI is required in order to convert CSCA List from LDIF to leaves, which are sent to proposal. +You can also verify someone's CSCA list proposals with it to prevent fraud. + +1. Install Go [https://go.dev/doc/install](https://go.dev/doc/install) +2. Install `rarimo-cored` CLI app: +```bash +go install github.com/rarimo/rarimo-core/cmd/rarimo-cored +``` +This should install the `rarimo-cored` binary into your `$GOPATH/bin` directory. +You can call the CLI from that dir, or add it to your `$PATH`: +```bash +export PATH=$PATH:$(go env GOPATH)/bin +``` + + +Some commands require network RPC in order to fetch state. +You can put it into environment variable for convenient command calls: +```bash +export RPC=https://your-rpc +``` + +## Monitor changes + +The proposal mechanism was implemented due to inability of automatic fetch of CSCA list. +This is why you have to monitor the list manually if you are interested in up-to-date storage. + +### Download the list +1. Go to [ICAO website](https://pkddownloadsg.icao.int/) +2. Accept terms and pass captcha below +3. Find "The latest collection of CSCA Master Lists" on the page and download it +4. You should have a `.ldif` file in your downloads with name like `icaopkd-002-complete-*.ldif` + +### Compare with state + +```bash +rarimo-cored --node $RPC query cscalist ldif-tree-diff your-file.ldif +``` +If roots are different, the list was changed and the proposal must be created to update the tree. + +## Create proposal + +Most likely, you have already filled basic proposal data in the block scan (title, description, etc.). You should have the file with CSCA list, see **Download the list** subsection. Assuming the file name is `your-file.ldif`. + +Obtain primary data for your proposal: +```bash +cd ~/Downloads # or wherever you have the file +rarimo-cored query cscalist parse-ldif --output-format hash your-file.ldif your-output-file.txt +``` + +`your-output-file.txt` will contain the big list of hashes of public keys from the LDIF file. Example: +``` +0x1d4dd579478a38c00f58a4d94263ff2bb0459992c073ebb7a6991194e44157f2 +0x0dcc4019fccc7ad4fbb535a40633cc32f99a18096a736b21e695e35e964209ae +0x01a3d79b678d79a8f912b693c4d57b38cf0e44ef413b7684e92a664e98c911ed +``` +If this is `ReplaceCSCAListProposal`, just copy the hashes to the proposal `leaves` field. + +For `EditCSCAListProposal` the process is more complicated: + +### Method 1 + +1. Obtain the old Master List LDIF file, which tree is stored on-chain at the moment. +If you don't have it, use **Method 2** instead. +2. Optional: ensure that the list from file is the same as on-chain: +```bash +rarimo-cored --node $RPC query cscalist ldif-tree-diff your-old-file.ldif +``` +You expect to see message that the trees' roots are the same. +Otherwise, seek for an actual `your-old-file.ldif`. +3. Extract the hashes from your old file: +```bash +rarimo-cored query cscalist parse-ldif --output-format hash your-old-file.ldif old-output-file.txt +``` +4. Compare `your-output-file.txt` and `old-output-file.txt` to find the differences. +You can use `diff`, `vimdiff` or any preferable tool. +- hashes present only in `your-output-file.txt` are to be added +- hashes present only in `old-output-file.txt` are to be removed +5. Put acquired hashes into respective fields: `toAdd`, `toRemove` + +### Method 2 + +1. Fetch the current hashes from the Merkle tree: +```bash +rarimo-cored --node $RPC query cscalist tree > current-tree.txt +``` +2. Iterate over the `current-tree.txt` manually and collect `key` values. +You may put them into `old-output-file.txt`. + +3. Perform steps 4 and 5 from **Method 1**. + +Congratulations! You should now have your proposal ready for submission. + +## Verify proposal + +In order to vote for the proposal, you need to ensure that its content corresponds to the actual state of CSCA List. + +Firstly, download the list from [ICAO website](https://pkddownloadsg.icao.int/) +and prepare the list of hashes, like described in **Create proposal** section. + +Secondly, check whether the proposal makes any difference to the current state: +```bash +rarimo-cored --node $RPC query cscalist ldif-tree-diff your-file.ldif +``` +If there is no difference, the proposal does not make sense, and you should vote 'No' or 'NoWithVeto'. + +If this is `ReplaceCSCAListProposal`, just compare the `leaves` field with `your-output-file.txt`. It is possible that you could have the different order of hashes due to ICAO change of order. Therefore, you may wish to sort both lists, e.g. with `sort` command. + +For `EditCSCAListProposal`, you need to perform the same steps as in **Create proposal** section. +Then compare the `toAdd` and `toRemove` fields with the differences between `your-output-file.txt` and `old-output-file.txt`. + +If you get the same results as in the proposal, it is correct, and you can vote for it. diff --git a/docs/common/core/004-core.md b/docs/common/core/004-core.md new file mode 100644 index 00000000..22b2d4e8 --- /dev/null +++ b/docs/common/core/004-core.md @@ -0,0 +1,10 @@ +--- +layout: default +title: Guides +--- + +# Guides + +* [Adding new operation](./001-adding-operation.md) +* [Creating genesis file](./002-creating-genesis.md) +* [Creating CSCA update proposal](./003-csca-list-proposal-guide.md) \ No newline at end of file diff --git a/index.md b/index.md index 875116eb..acd302b8 100644 --- a/index.md +++ b/index.md @@ -21,6 +21,8 @@ Based on Tendermint + Cosmos SDK blockchain core the main goal is to provide val ### 4. 🚀 [Bridging Overview](./docs/common/bridging/001-bridging.md) +### 5. 📚 [Guides](./docs/common/core/004-core.md) + ## Chains ### 1. 🌎 [Mainnet information](./docs/common/mainnet/001-mainnet.md)