From 4291c2a5bf905a3b4d497d8fec2fd1000679ef35 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 10:48:40 +0100 Subject: [PATCH 01/15] Translate from multiple docs Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 182 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 content/rsf-spec/index.md diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md new file mode 100644 index 0000000..f6016e8 --- /dev/null +++ b/content/rsf-spec/index.md @@ -0,0 +1,182 @@ +--- +rfc: +start_date: 2018-04-04 +pr: +status: draft +--- + +# The Register Serialisation Format + +## Summary + +This RFC aims to collect in one place the current implementation of RSF so it +can be added to the specification and it can be evolved with new RFCs when +required. + +The Register Serialisation Format, from now on RSF, is an event log describing +the evolution of the Register data and metadata. + + +## RSF Grammar + +RSF is a positional line-based textual format separated by tabs. Each +line defines a command to apply to a Register state to obtain the next state. + +This specification uses the Augmented Backus-Naur Form (ABNF) as defined by +[RFC5234](https://tools.ietf.org/html/rfc5234) and refined by +[RFC7405](https://tools.ietf.org/html/rfc7405). It assumes the following +definitions: + +* RFC5234: `ALPHA` (letters), `CRLF` (carriage return, line feed), `DIGIT` + (decimal digits), `HEXDIG` (hexadecimal digits) and `HTAB` (horizontal tab). +* Registers specification: [`CANONREP`][canon-rep] (canonical representation). + Note that, in turn, it depends on [RFC8259](https://tools.ietf.org/html/rfc8259). + +```abnf +log = command *(CRLF command) [CRLF] +command = add-item / append-entry / assert-root-hash + +assert-root-hash = %s"assert-root-hash" HTAB hash + +add-item = %s"add-item" HTAB CANONREP + +append-entry = %s"append-entry" HTAB type HTAB key HTAB timestamp HTAB hash-list +type = "user" / "system" +key = alphanum / %x2D / %x5F +hash-list = hash *(list-separator hash) +hash = "sha-256:" 64(HEXDIG) ; sha-256 +list-separator = ";" ; hash list separator + +alphanum = ALPHA / DIGIT + +; timestamp +timestamp = date "T" time +date = century year DSEP month DSEP day ; date YYYY-MM-DD +time = hour TSEP minute TSEP second TZ ; time HH:MM:SSZ + +; date +century = 2DIGIT ; 00-99 +year = 2DIGIT ; 00-99 +month = 2DIGIT ; 01-12 +day = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on month/year +DSEP = "-" ; date separator + +; time +hour = 2DIGIT ; 00-24 +minute = 2DIGIT ; 00-59 +second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap-second rules +TSEP = ":" ; time separator +TZ = "Z" ; timezone +``` + +## Media type + +The current media type is `application/uk-gov-rsf`. It should change to +`application/vnd.rsf` to align with [RFC6838](https://tools.ietf.org/html/rfc6838). + +TODO: Or `text/vnd.rsf+tab-separated-values` if we want to express RSF is a +type on top of TSV. In any case `vnd` needs to be prefixed because the media +type is not registered with IANA. + + +## Commands + +### `assert-root-hash` command + +Asserts that the provided root hash is the same as the one computed from the +current entry log as defined in the [Digital Proofs][digital-proofs] +specification. + +#### Arguments + +1. The `hash` of the root tree. + +For example, the empty root hash: + +``` +assert-root-hash sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 +``` + +### `add-item` command + +Adds a new [Item resource][item-res] to the register. It will require an +[`append-entry` command](#append-entry-command) to make it visible to users. + +#### Arguments + +1. The [canonical representation][canon-rep] of the item. + +For exeample: + +``` +add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kingdom of Great Britain and Northern Ireland"} +``` + +### `append-entry` command + +Appends a new [Entry resource][entry-res] to the register. + +#### Arguments + +1. The `type` of the entry determines if the entry belongs to the data log + (`user`) or to the metadata log (`system`). +2. The `key` of the entry. The primary key field is the field with the same + name as the register. +3. The `timestamp` of the entry. This is the time at which the entry was + appended to the register. +4. The `hash` of the item for which the entry was appended. This is the + [sha-256 hash of the item][canon-rep]. + +For example: + +``` +append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d7927bf159bc254b8881c45d95945617237f6 +``` + + +## Rules + +A RSF list of commands is expected to conform to the following rules: + +* [Commands](#commands) are executed in order of appearance, top to bottom. +* Entries are numbered in sequence in order of appearance starting with 1 if + the register is empty, otherwise incrementing on the latest entry number + found in the register. +* An [`append-entry` command](#append-entry-command) must always appear after + the [`add-item` command](#add-item-command) that introduces the item is + referencing. +* It is illegal to have orphan items. An `add-item` must have at least one + `append-entry` referencing to the item. +* It is illegal to have broken references. An `append-entry` must reference an + item previously introduced by an `add-item` command. +* The item in the `add-item` command must always be in the canonical form. + + +## Examples + +### Simple RSF + +``` +add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kingdom of Great Britain and Northern Ireland"} +append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d7927bf159bc254b8881c45d95945617237f6 +``` + +### All commands in use + +``` +assert-root-hash sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 +add-item {"cardinality":"1","datatype":"string","field":"country","phase":"beta","register":"country","text":"The country's 2-letter ISO 3166-2 alpha2 code."} +add-item {"cardinality":"1","datatype":"string","field":"name","phase":"beta","text":"The commonly-used name of a record."} +add-item {"cardinality":"1","datatype":"string","field":"official-name","phase":"beta","text":"The official or technical name of a record."} +append-entry system field:country 2017-01-10T17:16:07Z sha-256:a303d05bdbeb029440344e0f1148f5524b4a2f9076d1b0f36a95ff7d5eeedb0e +append-entry system field:name 2017-01-10T17:16:07Z sha-256:a7a9f2237dadcb3980f6ff8220279a3450778e9c78b6f0f12febc974d49a4a9f +append-entry system field:official-name 2017-01-10T17:16:07Z sha-256:5c4728f439f6cbc6c7eea42992b858afc78c182962ba35d169f49db2c88e1e41 +add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kingdom of Great Britain and Northern Ireland"} +append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d7927bf159bc254b8881c45d95945617237f6 +``` + + +[item-res]: https://openregister.github.io/specification/#item-resource +[entry-res]: https://openregister.github.io/specification/#entry-resource +[canon-rep]: https://openregister.github.io/specification/#sha-256-item-hash +[digital-proofs]: http://openregister.github.io/specification/#digital-proofs From 9b73b7341fd149c6f72e48e1b7a1380d4e6297a9 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 12:45:56 +0100 Subject: [PATCH 02/15] Remove alternative media type Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index f6016e8..e082c98 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -74,10 +74,6 @@ TZ = "Z" ; timezone The current media type is `application/uk-gov-rsf`. It should change to `application/vnd.rsf` to align with [RFC6838](https://tools.ietf.org/html/rfc6838). -TODO: Or `text/vnd.rsf+tab-separated-values` if we want to express RSF is a -type on top of TSV. In any case `vnd` needs to be prefixed because the media -type is not registered with IANA. - ## Commands From 9c5b85a15f42622449216c77cc77c9f6a81bd59e Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 13:28:43 +0100 Subject: [PATCH 03/15] Add type checking section Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 46 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index e082c98..f623a35 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -130,7 +130,7 @@ append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d79 ``` -## Rules +## Validation rules A RSF list of commands is expected to conform to the following rules: @@ -148,6 +148,47 @@ A RSF list of commands is expected to conform to the following rules: * The item in the `add-item` command must always be in the canonical form. +### Type checking + +Although not part of the RSF specification, it is worth mentioning that a +Registers' implementation is expected to type check the data according to the +computed schema. + +#### Metadata + +A metadata item must conform to the metadata schema + +[TODO: This needs definition]. + +#### Data + +A data item must conform to the current schema derived from the previous +system entries. A type checker is expected to verify: + +* It has the primary key defined. +* Fieldnames exist in the schema. +* Cardinality is consistent. +* Datatype is consistent. + +Given the example “[All commands in use](#all-commands-example)”, a new data +item is valid if: + +* It has the primary key, `country` defined. +* It has at most one `name` field and one `official-name` field. +* The `country` field has cardinality 1. +* The `country` field is a String. +* The `name` field has cardinality 1. +* The `name` field is a String. +* The `official-name` field has cardinality 1. +* The `official-name` field is a String. + +Each datatype must be parsed according to the [datatype specification][datatype-spec]. + +A RSF patch (set of commands) must be treated as a single transaction. If +there is a validation error, the whole patch must be rejected and any changes +to the state rolled back. + + ## Examples ### Simple RSF @@ -157,7 +198,7 @@ add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kin append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d7927bf159bc254b8881c45d95945617237f6 ``` -### All commands in use +### All commands in use ``` assert-root-hash sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 @@ -176,3 +217,4 @@ append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d79 [entry-res]: https://openregister.github.io/specification/#entry-resource [canon-rep]: https://openregister.github.io/specification/#sha-256-item-hash [digital-proofs]: http://openregister.github.io/specification/#digital-proofs +[datatype-spec]: http://openregister.github.io/specification/#datatypes From d445451018743dcec22c23bee2756aa8945553df Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 13:51:35 +0100 Subject: [PATCH 04/15] Add multi-item example Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index f623a35..be9b96a 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -198,6 +198,15 @@ add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kin append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d7927bf159bc254b8881c45d95945617237f6 ``` +### Multiple items + +``` +add-item {"local-authority-eng":"LND","local-authority-type":"NMD","name":"London"} +add-item {"local-authority-eng":"LEI","local-authority-type":"NMD","name":"Leicester"} +add-item {"local-authority-eng":"CHE","local-authority-type":"NMD","name":"Cheshire"} +append-entry user NMD 2016-04-05T13:23:05Z sha-256:490636974f8087e4518d222eba08851dd3e2b85095f2b1427ff6ecd3fa482435;sha-256:8b748c574bf975990e47e69df040b47126d2a0a3895b31dce73988fba2ba27d8;sha-256:eb3ee00e6149cd734a7fa7e1f01a5fbf5fb50e1b38a065fd97d6ad3017750351 +``` + ### All commands in use ``` From be5981101281afe860434abd727e50be9f9375da Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 14:00:29 +0100 Subject: [PATCH 05/15] Note on REST API Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 49 +++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index be9b96a..01564be 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -16,8 +16,13 @@ required. The Register Serialisation Format, from now on RSF, is an event log describing the evolution of the Register data and metadata. +## Motivation -## RSF Grammar +TODO + +## Explanation + +### RSF Grammar RSF is a positional line-based textual format separated by tabs. Each line defines a command to apply to a Register state to obtain the next state. @@ -69,21 +74,31 @@ TSEP = ":" ; time separator TZ = "Z" ; timezone ``` -## Media type +### Media type The current media type is `application/uk-gov-rsf`. It should change to `application/vnd.rsf` to align with [RFC6838](https://tools.ietf.org/html/rfc6838). +### REST API + +TODO + +The current implementation uses `GET /download-rsf`. The main issue with that +is that diverges from the rest of the API where serialisation is expressed +either via suffix or via media type. The problem with using the same approach, +say `GET /register.rsf` is that we are not providing the same information when +querying `GET /register.json`. + -## Commands +### Commands -### `assert-root-hash` command +#### `assert-root-hash` command Asserts that the provided root hash is the same as the one computed from the current entry log as defined in the [Digital Proofs][digital-proofs] specification. -#### Arguments +##### Arguments 1. The `hash` of the root tree. @@ -93,12 +108,12 @@ For example, the empty root hash: assert-root-hash sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ``` -### `add-item` command +#### `add-item` command Adds a new [Item resource][item-res] to the register. It will require an [`append-entry` command](#append-entry-command) to make it visible to users. -#### Arguments +##### Arguments 1. The [canonical representation][canon-rep] of the item. @@ -108,11 +123,11 @@ For exeample: add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kingdom of Great Britain and Northern Ireland"} ``` -### `append-entry` command +#### `append-entry` command Appends a new [Entry resource][entry-res] to the register. -#### Arguments +##### Arguments 1. The `type` of the entry determines if the entry belongs to the data log (`user`) or to the metadata log (`system`). @@ -130,7 +145,7 @@ append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d79 ``` -## Validation rules +### Validation rules A RSF list of commands is expected to conform to the following rules: @@ -148,19 +163,19 @@ A RSF list of commands is expected to conform to the following rules: * The item in the `add-item` command must always be in the canonical form. -### Type checking +#### Type checking Although not part of the RSF specification, it is worth mentioning that a Registers' implementation is expected to type check the data according to the computed schema. -#### Metadata +##### Metadata A metadata item must conform to the metadata schema [TODO: This needs definition]. -#### Data +##### Data A data item must conform to the current schema derived from the previous system entries. A type checker is expected to verify: @@ -189,16 +204,16 @@ there is a validation error, the whole patch must be rejected and any changes to the state rolled back. -## Examples +### Examples -### Simple RSF +#### Simple RSF ``` add-item {"country":"GB","name":"United Kingdom","official-name":"The United Kingdom of Great Britain and Northern Ireland"} append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d7927bf159bc254b8881c45d95945617237f6 ``` -### Multiple items +#### Multiple items ``` add-item {"local-authority-eng":"LND","local-authority-type":"NMD","name":"London"} @@ -207,7 +222,7 @@ add-item {"local-authority-eng":"CHE","local-authority-type":"NMD","name":"Chesh append-entry user NMD 2016-04-05T13:23:05Z sha-256:490636974f8087e4518d222eba08851dd3e2b85095f2b1427ff6ecd3fa482435;sha-256:8b748c574bf975990e47e69df040b47126d2a0a3895b31dce73988fba2ba27d8;sha-256:eb3ee00e6149cd734a7fa7e1f01a5fbf5fb50e1b38a065fd97d6ad3017750351 ``` -### All commands in use +#### All commands in use ``` assert-root-hash sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 From 8b211c3aff8992d2289536617ae5810a63dfcbc4 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 14:34:20 +0100 Subject: [PATCH 06/15] Reword root hash argument Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 01564be..4efbccf 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -100,7 +100,7 @@ specification. ##### Arguments -1. The `hash` of the root tree. +1. The `hash` of the root of the tree. For example, the empty root hash: From 11b0c181244d4adfd21dd0e12984f91674aeeac2 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 5 Apr 2018 15:54:44 +0100 Subject: [PATCH 07/15] Add thoughts on a new resource that is what RSF represents Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 4efbccf..16970cf 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -89,6 +89,25 @@ either via suffix or via media type. The problem with using the same approach, say `GET /register.rsf` is that we are not providing the same information when querying `GET /register.json`. +What is a good name for a resource that represents the whole raw database? + +``` +# RSF + +GET /{db resource}.rsf + +GET /{db resource} +Accept: application/vnd.rsf + + +# JSON Lines — Hypothetical + +GET /{db resource}.jsonl + +GET /{db resource}.jsonl +Accept: application/x-ndjson +``` + ### Commands From 1816e46c104a44c68d66e3785a77a0e179e9377f Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Fri, 20 Apr 2018 14:33:59 +0100 Subject: [PATCH 08/15] Fix typo Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 16970cf..88e2d43 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -185,7 +185,7 @@ A RSF list of commands is expected to conform to the following rules: #### Type checking Although not part of the RSF specification, it is worth mentioning that a -Registers' implementation is expected to type check the data according to the +Registers implementation is expected to type check the data according to the computed schema. ##### Metadata From 3ed047469a4dc9e763ad33fd48a2026ed61cda93 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Fri, 20 Apr 2018 14:48:01 +0100 Subject: [PATCH 09/15] Reword add-item command as suggested by @nacnudus Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 88e2d43..4edbe8c 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -129,8 +129,9 @@ assert-root-hash sha-256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991 #### `add-item` command -Adds a new [Item resource][item-res] to the register. It will require an -[`append-entry` command](#append-entry-command) to make it visible to users. +Adds a new [Item resource][item-res] to the register. There must be at least +an [`append-entry` command](#append-entry-command) referencing the item's hash +later on to make the RSF patch [valid](#validation-rules). ##### Arguments @@ -164,7 +165,7 @@ append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d79 ``` -### Validation rules +### Validation rules A RSF list of commands is expected to conform to the following rules: From 08fb49e8556cd2374b790bfd4eb41a6809b5ac7e Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 3 May 2018 16:38:00 +0100 Subject: [PATCH 10/15] Fix ABNF case sensitive tokens Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 4edbe8c..32b5109 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -1,7 +1,7 @@ --- rfc: start_date: 2018-04-04 -pr: +pr: openregisters/registers-rfc#12 status: draft --- @@ -46,16 +46,16 @@ assert-root-hash = %s"assert-root-hash" HTAB hash add-item = %s"add-item" HTAB CANONREP append-entry = %s"append-entry" HTAB type HTAB key HTAB timestamp HTAB hash-list -type = "user" / "system" +type = %s"user" / %s"system" key = alphanum / %x2D / %x5F hash-list = hash *(list-separator hash) -hash = "sha-256:" 64(HEXDIG) ; sha-256 +hash = %s"sha-256:" 64(HEXDIG) ; sha-256 list-separator = ";" ; hash list separator alphanum = ALPHA / DIGIT ; timestamp -timestamp = date "T" time +timestamp = date %s"T" time date = century year DSEP month DSEP day ; date YYYY-MM-DD time = hour TSEP minute TSEP second TZ ; time HH:MM:SSZ @@ -71,7 +71,7 @@ hour = 2DIGIT ; 00-24 minute = 2DIGIT ; 00-59 second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap-second rules TSEP = ":" ; time separator -TZ = "Z" ; timezone +TZ = %s"Z" ; timezone ``` ### Media type From 36b9540d314c883dfef068582797600a053f49c7 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 3 May 2018 16:43:01 +0100 Subject: [PATCH 11/15] Add download-rsf range endpoints Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 32b5109..0b3bd9e 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -108,6 +108,12 @@ GET /{db resource}.jsonl Accept: application/x-ndjson ``` +It is also possible to get a register patch in RSF: + +* `GET /download-rsf/{n}`. Returns the RSF patch from the entry number `n` + (non inclusive) to the most recent entry number. +* `GET /download-rsf/{n}/{m}`. Returns the RSF patch from the entry number `n` + (non inclusive) to the entry number `m` (inclusive). ### Commands From 72883636ea2dc4968a0e2a43144d47825e04c166 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 3 May 2018 17:12:31 +0100 Subject: [PATCH 12/15] Fix the assert-root-hash behaviour Explains that the current behaviour uses only data entries to generate the root hash which leaves metadata entries unasserted. Also makes explicit that the numbering for data and metadata logs are independent. Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 0b3bd9e..d97b30e 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -120,9 +120,12 @@ It is also possible to get a register patch in RSF: #### `assert-root-hash` command Asserts that the provided root hash is the same as the one computed from the -current entry log as defined in the [Digital Proofs][digital-proofs] +current user entry log as defined in the [Digital Proofs][digital-proofs] specification. +Note that the system entries are not part of the root hash computation and are +not asserted in any way. + ##### Arguments 1. The `hash` of the root of the tree. @@ -176,9 +179,12 @@ append-entry user GB 2010-11-12T13:14:15Z sha-256:08bef0039a4f0fb52f3a5ce4b97d79 A RSF list of commands is expected to conform to the following rules: * [Commands](#commands) are executed in order of appearance, top to bottom. -* Entries are numbered in sequence in order of appearance starting with 1 if - the register is empty, otherwise incrementing on the latest entry number +* User entries are numbered in sequence in order of appearance starting with 1 + if the register is empty, otherwise incrementing on the latest entry number found in the register. +* System entries are numbered in sequence in order of appearance starting with + 1 if the register is empty, otherwise incrementing on the latest entry + number found in the register. * An [`append-entry` command](#append-entry-command) must always appear after the [`add-item` command](#add-item-command) that introduces the item is referencing. From f7e10aee25047f09d126e8bc7fae5d70c3aa9f66 Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 3 May 2018 17:17:09 +0100 Subject: [PATCH 13/15] Fix ABNF for entry keys Ensures keys have one or more characters where the first is alphanumeric. Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index d97b30e..bb888a7 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -47,7 +47,7 @@ add-item = %s"add-item" HTAB CANONREP append-entry = %s"append-entry" HTAB type HTAB key HTAB timestamp HTAB hash-list type = %s"user" / %s"system" -key = alphanum / %x2D / %x5F +key = alphanum *(alphanum / %x2D / %x5F) hash-list = hash *(list-separator hash) hash = %s"sha-256:" 64(HEXDIG) ; sha-256 list-separator = ";" ; hash list separator From 4cad6f68a99d26245e8cfabccfc87a46060f4c9b Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 3 May 2018 17:20:52 +0100 Subject: [PATCH 14/15] Add identical consecutive rule Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index bb888a7..4572600 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -192,6 +192,7 @@ A RSF list of commands is expected to conform to the following rules: `append-entry` referencing to the item. * It is illegal to have broken references. An `append-entry` must reference an item previously introduced by an `add-item` command. +* It is illegal to have two identical consecutive `append-entry` commands. * The item in the `add-item` command must always be in the canonical form. From 3c97dd876974a3cf85a2f5717e398a270afd3a8f Mon Sep 17 00:00:00 2001 From: Arnau Siches Date: Thu, 3 May 2018 17:24:00 +0100 Subject: [PATCH 15/15] Fix rule for orphan entries Signed-off-by: Arnau Siches --- content/rsf-spec/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/rsf-spec/index.md b/content/rsf-spec/index.md index 4572600..19973ac 100644 --- a/content/rsf-spec/index.md +++ b/content/rsf-spec/index.md @@ -187,11 +187,11 @@ A RSF list of commands is expected to conform to the following rules: number found in the register. * An [`append-entry` command](#append-entry-command) must always appear after the [`add-item` command](#add-item-command) that introduces the item is - referencing. + referencing *unless* the item already exists in the register. * It is illegal to have orphan items. An `add-item` must have at least one `append-entry` referencing to the item. * It is illegal to have broken references. An `append-entry` must reference an - item previously introduced by an `add-item` command. + existing item or an item previously introduced by an `add-item` command. * It is illegal to have two identical consecutive `append-entry` commands. * The item in the `add-item` command must always be in the canonical form.