kolo docsbeta

Logs

Um log é uma lista de entradas que só cresce. O dono assina o log, e qualquer pessoa com a chave pública do dono pode verificá-lo.

Nesta página

Um log kolo-log pertence a um único dono, a chave que escreve nele. As entradas só são adicionadas no final. Ninguém, nem mesmo o dono, consegue alterar uma entrada ou mudar a ordem delas sem que a mudança apareça.

Assinado e append-only

Todos os passos

Acrescentar uma entrada

As entradas não são encadeadas umas às outras por hashes. A árvore de Merkle as liga, e cada head assinado cobre todas as entradas anteriores.

  1. Append cria uma chave de entrada nova de 32 bytes. O valor é preenchido e cifrado com XChaCha20-Poly1305.
  2. O registro guarda o índice, o tamanho, um hash do texto cifrado e um compromisso com a chave. O dono o assina.
  3. A folha é o hash BLAKE2b-256 de 0x00 e do registro assinado. Ela entra na árvore pela direita.
  4. Cada nó acima é o hash de 0x01 e dos seus dois filhos, até uma raiz nova.
  5. O dono assina um head novo: o log, o tamanho e a raiz. Entrada, chave e head são gravados em um só commit.
  • Cada entrada ganha um registro assinado pelo dono. As folhas de uma árvore Merkle são os hashes desses registros assinados, calculados como na RFC 9162, usando BLAKE2b-256.
  • O dono assina o head da árvore: o tamanho do log e o hash da raiz.
  • Uma prova de inclusão mostra que uma entrada está em um head assinado. Uma prova de consistência mostra que um head mais novo só adicionou entradas a um mais antigo.

Um leitor precisa de duas coisas em que já confia: a chave pública do dono e o ID de 32 bytes do log. Heads, registros, provas e entradas podem vir de qualquer peer, porque o leitor confere cada um deles com esses dois valores.

Entradas criptografadas

Cada entrada é criptografada com a sua própria chave aleatória (XChaCha20-Poly1305). Um peer que tem o registro e o texto cifrado, mas não a chave, pode guardar a entrada, servir a entrada para outros e verificar as provas dela, sem conseguir lê-la. Quem recebe as chaves é decisão da aplicação; a kolo-sync pergunta isso a ela para cada peer.

Marcadores de exclusão

Todos os passos

Excluir uma entrada

Excluir tira o conteúdo, não a entrada: o registro fica, então todos os heads e provas continuam valendo.

  1. A entrada 2 é guardada como o seu registro assinado, o seu texto cifrado e a sua chave de entrada.
  2. Delete cria um marcador de exclusão: o log, o índice e o hash da folha, assinados pelo dono.
  3. O texto cifrado e a chave são descartados; o registro e o marcador ficam. A árvore e o head não mudam.
  4. Uma réplica confere o marcador e descarta a sua cópia desse texto cifrado e dessa chave. Ler a entrada dá ErrDeleted.
  5. Uma cópia feita antes, ou uma chave que alguém guardou, fica fora de alcance. A exclusão é feita da melhor forma possível.

O dono exclui uma entrada destruindo a chave dela e assinando um marcador de exclusão para ela. O registro assinado continua lá, então todas as provas continuam valendo, mas ninguém que siga o protocolo consegue mais ler a entrada. Exclusão explica o que isso promete e o que não promete.

Um único escritor

Um log tem exatamente um escritor. Não existe log compartilhado com vários escritores: um app com vários dispositivos ou várias pessoas usa um log por dispositivo ou pessoa, e cada peer mantém cópias somente leitura dos logs dos outros, chamadas réplicas. kolo-kv monta um armazenamento chave-valor sobre um desses logs.

Onde um log fica

Um kololog.Log guarda na memória só os hashes da sua árvore e uma cópia compacta de cada registro. Os seus textos cifrados, as suas chaves e os seus marcadores de exclusão ficam em um Storage: NewMemory guarda tudo na memória, e a kolo-store guarda em disco, gravando cada mudança como um único lote atômico e sincronizado. Cada mudança é um único commit no armazenamento, feito antes de a mudança aparecer, e um commit que falha deixa o log exatamente como estava. Um armazenamento pertence a um único log.