PUBLICATION・DEPRECATION・TOMBSTONE は、ドキュメントバージョンの公表・使用中止の勧告・削除を記録する叙述 Edge であり、このページはその Edge で書くバージョン一覧ドキュメントの規格も定める(Codec 0x0B8L~0x0BAL)。
| 項目 | 値 |
|---|---|
| 名前 | PUBLICATION (規格ドキュメント BIND PUBLICATION) |
| TAG ID | 0x0B8L |
| Codec ID | 0x00000B80 |
| 規格ドキュメント | 0x00000000/codecs/0x00000B80/ (DECLARE 対象 0B80) |
| セクション | 5 0101 (Edge 叙述)、セクション内オフセット C = 24 |
| Kind | Edge · 系列: 叙述、まとまり: その他 |
| TAG WORD | 0000 1011 1000 LLLL (000K KKKC CCCC LLLL) |
| 索引の説明 | ドキュメントの公表。DOC-POINTER、コンテンツハッシュ |
| Hugo 側 | edge/publication.md (そちらは DEPRECATION、TOMBSTONE もあわせて扱う) |
フィールド (規格ドキュメント)
FIELD のドキュメント内の順序が Payload のフィールド順序である(Codec 規格ドキュメント)。Edge の Edge Id は FIELD で宣言しない。
| 順序 | フィールド(BIND) | FIELD | 幅 | 受け取る形式(CODEC) | ENUM |
|---|---|---|---|---|---|
| 1 | doc | #2 | レコード | 0410 DOC-POINTER, 0420 CODEC-POINTER | |
| 2 | hash | #4 | 生値 16 WORD |
ドキュメントの公表・deprecate・削除を記録する叙述 Edge と、その Edge で書くバージョン一覧ドキュメントの規格である。公表アドレスとバージョン一覧のバージョン一覧の形式を定める。
コード
| Codec | 名前 | Payload |
|---|---|---|
0x0B8L | PUBLICATION | Edge Id, DOC-POINTER, コンテンツハッシュ |
0x0B9L | DEPRECATION | Edge Id, DOC-POINTER |
0x0BAL | TOMBSTONE | Edge Id, DOC-POINTER, 理由区分 |
- 三つのコードはデコーダに内蔵する(0 層)。バージョン一覧はコードブックを参照せずに解釈される。
- 下位形式(Codec ごとの TAG)は置かない。Payload の最初の要素が Edge Id であるという Edge の規則をそのまま守る。
レイアウト
TAG WORD Edge, Codec 0x0B8L / 0x0B9L / 0x0BAL
[Length 拡張 TAG]
Edge Id LOCAL Reference レコード
ドキュメント DOC-POINTER Reference レコード (Issuer, ドキュメント ID, バージョン ID)。Codec のバージョン一覧は CODEC-POINTER
コンテンツハッシュ 16 WORD (PUBLICATION)
理由区分 1 WORD (TOMBSTONE)
| フィールド | 幅 | 説明 |
|---|---|---|
| Edge Id | LOCAL Reference レコード | 一覧内の通し番号。1 から振り、続けて付ける |
| ドキュメント | DOC-POINTER レコード | 公表したドキュメントの一つのバージョン(DOC-POINTER)。Issuer・ドキュメント ID はその一覧が扱うドキュメントと同じである。一覧ドキュメントが、パスなしでも何の一覧かを語れるようにする。バージョン ID はそのドキュメント内の通し番号(ドキュメントのバージョン)であり、0(最新)は使わない。Codec のバージョン一覧は CODEC-POINTER(Issuer, Codec ID, バージョン ID)を使う |
| コンテンツハッシュ | 16 WORD | そのバージョンのコンテンツハッシュ(SHA-256、ドキュメントのコンテンツハッシュ) |
| 理由区分 | 1 WORD | 削除理由の区分コード。コード表は未解決の問題である |
- DOC-POINTER の後の長さはコードごとに固定である(16、0、1 WORD)。異なれば拒否する。
- 時刻はレコードに入れない。そのレコードが最初に載った一覧ドキュメントの
RECORDED-ATが、公表・deprecate・削除の時刻である。
バージョン一覧ドキュメント
公表先はドキュメントごとにバージョン一覧ドキュメント一つを書き継ぐ: /<Issuer>/docs/<ドキュメント ID>/versions.geul(Codec は /<Issuer>/codecs/<Codec ID>/versions.geul、Issuer 一覧は下記)。そのドキュメントがその公表先で公表されたすべてのバージョンが一つの一覧に入る。
DOC-1WORD/2WORD/4WORD 全体の長さ
SPEC-VERSION 0x0001 (v1)
PARENT SHA-256-DIGEST Value。直前の一覧ドキュメントのコンテンツハッシュ (最初の一覧ならなし)
RECORDED-AT POSIX-TIMESTAMP-SECONDS Value。この一覧を出した時刻
NEXT-LOCAL-ID 次に割り当てる LOCAL ID (バージョンがあれば)
SIGNATURE 公表先の署名。対象はこの一覧ドキュメントのコンテンツハッシュ
BODY
PUBLICATION · DEPRECATION · TOMBSTONE …
END
- HEAD Meta: SPEC-VERSION, PARENT, RECORDED-AT, NEXT-LOCAL-ID, SIGNATURE.
- バージョン一覧ドキュメントには
DOC-IDを置かない(一覧ドキュメントの例外、DOC-ID)。一覧は公表ドキュメントではなく、そのドキュメントに付随する記録である。どのドキュメントの一覧かは、レコードの DOC-POINTER(ドキュメント ID)が語る。そのため、パスなしで(hashes/、ダンプ)受け取っても何の一覧か分かる。 - レコードのドキュメント ID は、すべてその一覧が扱うドキュメントでなければならない。別のドキュメントのレコードは拒否する。
- バージョン一覧ドキュメントは IMPORT を置かず、0 層の Codec だけを使う。BODY には PUBLICATION・DEPRECATION・TOMBSTONE だけを置く。ドキュメント名の BIND は置かない(公表アドレスとバージョン一覧)。
- 新しい一覧ドキュメントは、直前の一覧ドキュメントの BODY をそのまま前に置き、レコードを付け足す。直したり消したり順序を変えたりしない。
- 公表先が一覧に署名する。geul.org の公表は geul.org(GEUL Issuer)が、私的な公表はその Issuer が署名する。
- ドキュメント ID
0x0000000000000000は Issuer の用語定義の索引ドキュメントである(Issuer と公表)。Issuer 自身は ISSUER-POINTER で指す。
一覧ドキュメントのバージョン一覧
一覧ドキュメントは Issuer 一覧 issuers/ 一つである(公表アドレスとバージョン一覧)。Issuer 一覧もバージョン 1 から始まり、バージョン一覧 issuers/versions.geul を置く。レコードは予約ドキュメント ID の DOC-POINTER(0x00000000、0xFFFFFFFFFFFFFFFF、バージョン ID)で一覧のバージョンを指す。
- レコードの形式は上と同じである。そのため
hashes/で受け取っても何の一覧か分かる。 - 一覧ドキュメント自身(
<バージョン ID>.geul)もDOC-IDを置かない。 - ドキュメント ID
0xFFFFFFFFFFFFFFFFは、どの Issuer でも<Issuer>/docs/<ドキュメント ID>/のアドレスでは受け付けない(404)。 - 一覧の
latest.geulは保存しないエイリアスである。このバージョン一覧から最も新しいバージョンを探して、そのバイト列を出す。
規則
- PUBLICATION のバージョン ID は 1 から欠番なく昇順である。バージョン ID は公表先が割り当てる。
- 同じコンテンツハッシュを再び公表しない。すでにあれば、そのバージョン ID を返す。
- DEPRECATION・TOMBSTONE は、前に出た PUBLICATION のバージョン ID だけを指す。存在しないバージョンを指せば拒否する。
- バージョンの状態は、レコードを順に適用して計算する。公表済み → deprecated → 削除済み。削除されたバージョンは再び公表せず、提供しない。
- 最新バージョンは、deprecated でも削除済みでもない最も高いバージョン ID である。
- バージョン ID が 2 WORD の終端に達したら、そのドキュメントはそれ以上公表せず、新しいドキュメント ID で出す。
アドレス
/.well-known/geul/<Issuer>/docs/<ドキュメント ID>/versions.geul 最新の一覧ドキュメント (可変)
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul Codec の最新の一覧ドキュメント (可変)
/.well-known/geul/issuers/versions.geul Issuer 一覧の最新のバージョン一覧 (可変)
/.well-known/geul/<Issuer>/hashes/<コンテンツハッシュ>.geul 過去の一覧ドキュメント (不変)
- 可変なのは最新の一覧アドレスである。受け取った一覧は、署名、
RECORDED-AT、PARENTチェーンで検証する。 - 過去の一覧ドキュメントはすべて
<Issuer>/hashes/に残す。PARENTチェーンをたどれば、どの時点の一覧でもさかのぼれる。
検証
- 一覧ドキュメントに、定められた公表先の鍵の
SIGNATUREがなければならない。 - レコードのドキュメント ID が、要求したドキュメント ID と同じでなければならない。
- ロック記録に残った直前の一覧のコンテンツハッシュが、新しい一覧の
PARENTチェーンになければならない。その一覧の BODY は、新しい一覧の BODY の前半部分と同じでなければならない。 - 受け取ったドキュメントのコンテンツハッシュは、そのバージョン ID の PUBLICATION が記した値と同じでなければならず、ドキュメントの
DOC-IDは要求した Issuer・ドキュメント ID と同じでなければならない。一覧ドキュメントにはDOC-IDがない。
未解決の問題
- 理由区分のコード表。
- 署名アルゴリズムの既定値と
SIGNATUREPayload のレイアウト。 - 一覧が大きくなったときに Merkle ログ(包含・一貫性の証明)へ移す時期と形式。
- Issuer 単位の巻き戻し防止。一覧がドキュメントごとに別のチェーンをなすので、一つのドキュメントの一覧だけを古いものとして差し出す攻撃は、そのドキュメントのチェーンでしか防げない。
関連ページ
規格ドキュメント原文
規格ドキュメント 0x00000000/codecs/0x00000B80/latest.geul を geul show で読んだ姿である(16進は大文字)。
SPEC-VERSION 0x0001
DOC-ID 0x04260000000000000B8000000000
BODY
#1 DECLARE 0x0B80
#2 FIELD #1 record
#9 CODEC #2 0x0410
#4 FIELD #1 0x0010
#5 BIND #1 "PUBLICATION"
#6 BIND #2 "doc"
#8 BIND #4 "hash"
#10 CODEC #2 0x0420