PUBLICATION, DEPRECATION y TOMBSTONE son Edge de enunciado que registran la publicación, la recomendación de desuso y la eliminación de versiones de un documento, y esta página fija además la especificación del documento de lista de versiones que se escribe con esos Edge (Codec 0x0B8L~0x0BAL).
| Elemento | Valor |
|---|---|
| Nombre | PUBLICATION (BIND del documento de especificación PUBLICATION) |
| TAG ID | 0x0B8L |
| Codec ID | 0x00000B80 |
| Documento de especificación | 0x00000000/codecs/0x00000B80/ (destino de DECLARE 0B80) |
| Sección | 5 0101 (enunciado de Edge), desplazamiento dentro de la sección C = 24 |
| Kind | Edge · familia: enunciado, grupo: otros |
| TAG WORD | 0000 1011 1000 LLLL (000K KKKC CCCC LLLL) |
| Descripción del índice | Publicación de un documento. DOC-POINTER, hash de contenido |
| Lado Hugo | edge/publication.md (esa página trata también DEPRECATION y TOMBSTONE) |
Campos (documento de especificación)
El orden de los FIELD dentro del documento es el orden de los campos del Payload (documento de especificación de Codec). El Edge Id de un Edge no se declara con FIELD.
| Orden | Campo (BIND) | FIELD | Ancho | Formato que acepta (CODEC) | ENUM |
|---|---|---|---|---|---|
| 1 | doc | #2 | registro | 0410 DOC-POINTER, 0420 CODEC-POINTER | |
| 2 | hash | #4 | valor en bruto 16 WORD |
Es la especificación de los Edge de enunciado que registran la publicación, el desuso (deprecate) y la eliminación de un documento, y del documento de lista de versiones que se escribe con esos Edge. Fija el formato de la lista de versiones de dirección de publicación y lista de versiones.
Códigos
| Codec | Nombre | Payload |
|---|---|---|
0x0B8L | PUBLICATION | Edge Id, DOC-POINTER, hash de contenido |
0x0B9L | DEPRECATION | Edge Id, DOC-POINTER |
0x0BAL | TOMBSTONE | Edge Id, DOC-POINTER, categoría de motivo |
- Los tres códigos se integran en el decodificador (capa 0). La lista de versiones se interpreta sin consultar el libro de codecs.
- No hay subformatos (TAG propio del Codec). Se mantiene tal cual la regla de Edge de que el primer elemento del Payload es el Edge Id.
Layout
TAG WORD Edge, Codec 0x0B8L / 0x0B9L / 0x0BAL
[TAG de extensión de Length]
Edge Id registro Reference LOCAL
documento registro Reference DOC-POINTER (Issuer, ID de documento, ID de versión). La lista de versiones de un codec usa CODEC-POINTER
hash de contenido 16 WORD (PUBLICATION)
categoría de motivo 1 WORD (TOMBSTONE)
| Campo | Ancho | Descripción |
|---|---|---|
| Edge Id | registro Reference LOCAL | Número de orden dentro de la lista. Se asigna desde 1 y se encadena |
| documento | registro DOC-POINTER | Una versión del documento publicado (DOC-POINTER). El Issuer y el ID de documento son los del documento que trata esa lista. Hace que el documento de lista diga de qué es lista incluso sin ruta. El ID de versión es el número de orden dentro de ese documento (versión de documento) y no se usa 0 (la más reciente). La lista de versiones de un codec usa CODEC-POINTER (Issuer, Codec ID, ID de versión) |
| hash de contenido | 16 WORD | Hash de contenido de esa versión (SHA-256, hash de contenido de documento) |
| categoría de motivo | 1 WORD | Código de categoría del motivo de eliminación. La tabla de códigos es un problema abierto |
- La longitud tras DOC-POINTER es fija para cada código (16, 0, 1 WORD). Si es distinta, se rechaza.
- No se pone la hora en el registro. El
RECORDED-ATdel documento de lista donde se registró por primera vez ese registro es la hora de publicación, deprecate o eliminación.
Documento de lista de versiones
El publicador mantiene encadenado un documento de lista de versiones por cada documento: /<Issuer>/docs/<ID de documento>/versions.geul (para un codec, /<Issuer>/codecs/<Codec ID>/versions.geul; para la lista de Issuer, más abajo). En una sola lista entran todas las versiones de ese documento publicadas por ese publicador.
DOC-1WORD/2WORD/4WORD longitud total
SPEC-VERSION 0x0001 (v1)
PARENT Value SHA-256-DIGEST. Hash de contenido del documento de lista anterior (si es la primera lista, no hay)
RECORDED-AT Value POSIX-TIMESTAMP-SECONDS. Momento en que se emitió esta lista
NEXT-LOCAL-ID Siguiente LOCAL ID a asignar (si hay versiones)
SIGNATURE Firma del publicador. El objetivo es el hash de contenido de este documento de lista
BODY
PUBLICATION · DEPRECATION · TOMBSTONE …
END
- Meta de HEAD: SPEC-VERSION, PARENT, RECORDED-AT, NEXT-LOCAL-ID, SIGNATURE.
- El documento de lista de versiones no lleva
DOC-ID(excepción de los documentos de lista, DOC-ID). La lista no es un documento publicado sino un registro anejo a ese documento. De qué documento es la lista lo dice el DOC-POINTER (ID de documento) del registro. Por eso, aunque se reciba sin ruta (hashes/, volcado), se sabe de qué es la lista. - Todos los ID de documento de los registros deben ser el del documento que trata esa lista. Se rechazan los registros de otros documentos.
- El documento de lista de versiones no lleva IMPORT y usa solo Codec de capa 0. En BODY solo hay PUBLICATION·DEPRECATION·TOMBSTONE. No lleva BIND de nombre de documento (dirección de publicación y lista de versiones).
- El nuevo documento de lista conserva delante, tal cual, el BODY del documento de lista anterior y le añade registros. No modifica, no borra ni reordena.
- El publicador firma la lista. La publicación de geul.org la firma geul.org (Issuer GEUL), y la publicación privada la firma su Issuer.
- El ID de documento
0x0000000000000000es el documento índice de definición de términos del Issuer (Issuer y publicación). El propio Issuer se señala con ISSUER-POINTER.
Lista de versiones del documento de lista
El documento de lista es uno solo, la lista de Issuer issuers/ (dirección de publicación y lista de versiones). La lista de Issuer también empieza en la versión 1 y tiene la lista de versiones issuers/versions.geul. El registro señala la versión de la lista con el DOC-POINTER del ID de documento reservado (0x00000000, 0xFFFFFFFFFFFFFFFF, ID de versión).
- El formato del registro es el mismo de arriba. Por eso, aunque se reciba por
hashes/, se sabe de qué es la lista. - El propio documento de lista (
<ID de versión>.geul) tampoco llevaDOC-ID. - El ID de documento
0xFFFFFFFFFFFFFFFFno se recibe en ningún Issuer con la dirección<Issuer>/docs/<ID de documento>/(404). - El
latest.geulde la lista es un alias que no se almacena. Busca la versión más reciente en esta lista de versiones y emite sus bytes.
Reglas
- El ID de versión de PUBLICATION va en orden ascendente desde 1 sin saltos. El ID de versión lo asigna el publicador.
- No se vuelve a publicar el mismo hash de contenido. Si ya existe, se devuelve ese ID de versión.
- DEPRECATION y TOMBSTONE solo señalan el ID de versión de un PUBLICATION anterior. Si señalan una versión inexistente, se rechaza.
- El estado de una versión se calcula aplicando los registros en orden. publicada → deprecated → eliminada. Una versión eliminada no se vuelve a publicar ni se entrega.
- La versión más reciente es el ID de versión más alto que no es deprecated ni eliminado.
- Cuando el ID de versión llega al final de 2 WORD, ese documento no se publica más y se emite con un nuevo ID de documento.
Direcciones
/.well-known/geul/<Issuer>/docs/<ID de documento>/versions.geul último documento de lista (mutable)
/.well-known/geul/<Issuer>/codecs/<Codec ID>/versions.geul último documento de lista del codec (mutable)
/.well-known/geul/issuers/versions.geul última lista de versiones de la lista de Issuer (mutable)
/.well-known/geul/<Issuer>/hashes/<hash de contenido>.geul documentos de lista anteriores (inmutable)
- Lo mutable es la dirección de la última lista. La lista recibida se verifica con la firma,
RECORDED-ATy la cadenaPARENT. - Todos los documentos de lista anteriores se conservan en
<Issuer>/hashes/. Siguiendo la cadenaPARENTse puede reconstruir la lista de cualquier momento.
Verificación
- El documento de lista debe tener la
SIGNATUREde la clave del publicador establecida. - El ID de documento de los registros debe ser igual al ID de documento solicitado.
- El hash de contenido de la lista anterior que queda en el registro de bloqueo debe estar en la cadena
PARENTde la nueva lista. El BODY de esa lista debe ser igual a la parte inicial del BODY de la nueva lista. - El hash de contenido del documento recibido debe ser igual al valor escrito en el PUBLICATION de ese ID de versión, y el
DOC-IDdel documento debe ser igual al Issuer y al ID de documento solicitados. El documento de lista no tieneDOC-ID.
Problemas abiertos
- Tabla de códigos de la categoría de motivo.
- Valor por defecto del algoritmo de firma y layout del Payload de
SIGNATURE. - Cuándo y en qué formato pasar a un registro Merkle (pruebas de inclusión y consistencia) cuando la lista crezca.
- Prevención de retroceso a nivel de Issuer. Como la lista forma una cadena aparte por cada documento, el ataque de presentar como antigua solo la lista de un documento se bloquea únicamente con la cadena de ese documento.
Páginas relacionadas
- Edge, BIND, DOC-POINTER
- Issuer y publicación, dirección de publicación y lista de versiones, documento
Texto original del documento de especificación
Así se ve el documento de especificación 0x00000000/codecs/0x00000B80/latest.geul leído con geul show (hexadecimal en mayúsculas).
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