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
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.
- Append cria uma chave de entrada nova de 32 bytes. O valor é preenchido e cifrado com XChaCha20-Poly1305.
- O registro guarda o índice, o tamanho, um hash do texto cifrado e um compromisso com a chave. O dono o assina.
- A folha é o hash BLAKE2b-256 de 0x00 e do registro assinado. Ela entra na árvore pela direita.
- Cada nó acima é o hash de 0x01 e dos seus dois filhos, até uma raiz nova.
- 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
Excluir uma entrada
Excluir tira o conteúdo, não a entrada: o registro fica, então todos os heads e provas continuam valendo.
- A entrada 2 é guardada como o seu registro assinado, o seu texto cifrado e a sua chave de entrada.
- Delete cria um marcador de exclusão: o log, o índice e o hash da folha, assinados pelo dono.
- O texto cifrado e a chave são descartados; o registro e o marcador ficam. A árvore e o head não mudam.
- Uma réplica confere o marcador e descarta a sua cópia desse texto cifrado e dessa chave. Ler a entrada dá ErrDeleted.
- 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.