A kolo-blobs guarda os bytes de um arquivo e nada mais: nem nomes, nem pastas, nem versões. Write corta um arquivo em fragmentos em pontos que dependem do conteúdo (FastCDC), criptografa cada fragmento (AES-GCM, NIST SP 800-38D) com chaves derivadas por HKDF (RFC 5869) de uma chave aleatória para esse arquivo, monta uma árvore de Merkle sobre eles e retorna o ID do blob, o hash SHA-256 (FIPS 180-4) da raiz da árvore. Open retorna um leitor que verifica cada fragmento contra a árvore enquanto transmite, e lê qualquer intervalo buscando só os fragmentos que o cobrem. Com NewLogBackend, as partes de um blob são entradas de um log da kolo-store, então elas viajam com a kolo-sync e ficam guardadas em peers de fixação da kolo-pin, que só têm texto cifrado e nunca uma chave. O pacote Go se chama koloblobs.
De um arquivo a um ID de blob
Um blob é só os bytes de um arquivo. Nomes, pastas e versões ficam na camada de cima, como a kolo-files.
- Write corta o arquivo em fragmentos onde o conteúdo indica: pelo menos 256 KiB, cerca de 1 MiB em média. Os pontos de corte também dependem da chave do arquivo, então mudam com cada chave.
- Cada fragmento vira um objeto: um MAC de conteúdo de 32 bytes e depois o fragmento selado com AES-256-GCM com uma chave derivada da chave do arquivo e do conteúdo. O hash SHA-256 do objeto é o seu nome.
- Uma árvore lista o hash e o tamanho de cada objeto, até 256 filhos por nó. Um arquivo de até 256 fragmentos precisa de uma só raiz acima deles.
- A raiz também se compromete com a chave do arquivo. O ID do blob é o hash SHA-256 do objeto raiz, então ele nomeia cada byte do arquivo com essa chave.
- Uma versão nova escrita com a mesma chave corta os mesmos fragmentos longe da edição. Só o fragmento em volta dela e uma raiz nova são guardados; os outros objetos são compartilhados.
Instalação
go get github.com/ciranda-dev/kolo-blobsCompila com CGO_ENABLED=0 para gerar um binário só em Go. Compartilhe arquivos entre dois terminais mostra passo a passo como enviar um arquivo de um peer para outro com um código de compartilhamento.
Início rápido
Este programa guarda um arquivo de 20 MB em um log da kolo-store no disco, em um diretório temporário. Ele lê de volta 16 bytes do meio e depois guarda uma versão editada com a mesma chave.
package main
import (
"bytes"
"context"
"fmt"
"io"
"log"
"math/rand/v2"
"os"
"path/filepath"
koloblobs "github.com/ciranda-dev/kolo-blobs"
koloid "github.com/ciranda-dev/kolo-id"
kolostore "github.com/ciranda-dev/kolo-store"
)
func main() {
dir, err := os.MkdirTemp("", "kolo-blobs")
if err != nil {
log.Fatal(err)
}
defer os.RemoveAll(dir)
ctx := context.Background()
// A kolo-store log on disk holds the blob, one object per entry.
db, err := kolostore.OpenPebble(filepath.Join(dir, "store"))
if err != nil {
log.Fatal(err)
}
st := kolostore.New(db)
defer st.Close()
me, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
l, err := st.Create(me)
if err != nil {
log.Fatal(err)
}
blobs := koloblobs.New(koloblobs.NewLogBackend(l))
// A 20 MB file under a new key. The key and the ID are what a reader needs.
file := make([]byte, 20_000_000)
rand.NewChaCha8([32]byte{1}).Read(file)
key := koloblobs.NewKey()
id, err := blobs.Write(ctx, key, bytes.NewReader(file))
if err != nil {
log.Fatal(err)
}
fmt.Printf("stored %d bytes as %d log entries\n", len(file), l.Len())
// A range read fetches and checks only the chunk under it and the tree above it.
r, err := blobs.Open(ctx, id, key)
if err != nil {
log.Fatal(err)
}
part, err := io.ReadAll(io.NewSectionReader(r, 12_000_000, 16))
r.Close()
if err != nil {
log.Fatal(err)
}
fmt.Printf("bytes 12000000 to 12000016 match: %v\n", bytes.Equal(part, file[12_000_000:12_000_016]))
// An edited version under the same key shares every chunk away from the edit.
before := l.Len()
edited := append(append(append([]byte{}, file[:10_000_000]...), "an insertion"...), file[10_000_000:]...)
if _, err := blobs.Write(ctx, key, bytes.NewReader(edited)); err != nil {
log.Fatal(err)
}
fmt.Printf("the edited version added %d entries\n", l.Len()-before)
}Ele imprime:
stored 20000000 bytes as 17 log entries
bytes 12000000 to 12000016 match: true
the edited version added 2 entriesO primeiro número foi 17, 18 ou 19 em seis execuções, porque os limites dos fragmentos dependem da chave aleatória: os fragmentos mais uma raiz. A versão editada acrescenta o fragmento em volta da inserção e uma raiz nova.
Referência da API
A referência da API é gerada a partir do código Go e está em inglês.
Package koloblobs stores files as encrypted, content-addressed blobs for Kolo: the content layer under kolo-files, with no names, folders or versions.
Write cuts a file into content-defined chunks, encrypts each under keys derived from a random per-file key, builds a Merkle tree over them and returns the blob's ID, the hash of the tree's root. Open returns a Reader that checks every chunk against the tree while it streams, and reads any range by fetching only the chunks that cover it. Objects live in a Backend; LogBackend keeps them as kolo-log entries, so blobs travel with kolo-sync and rest on kolo-pin pinning peers, which hold only ciphertext and never a key.
Experimental: the API may change before v1.0.0.
Constantes
const (
// KeySize is the size in bytes of a file key.
KeySize = 32
// HashSize is the size in bytes of an object hash and a content ID.
HashSize = sha256.Size
// MaxObjectSize is the largest object, the largest kolo-log entry value that kolo-sync carries.
MaxObjectSize = 4128764
// ObjectOverhead is what encryption adds to a chunk or node: a 32-byte content MAC and a 16-byte tag.
ObjectOverhead = 48
// MaxChunkSize is the largest chunk of plaintext, so that its object is at most MaxObjectSize.
MaxChunkSize = MaxObjectSize - ObjectOverhead
// MinChunkSize is the smallest chunk the chunker cuts; only a blob's last chunk can be smaller.
MinChunkSize = 256 << 10
// Fanout is the most children a tree node lists.
Fanout = 256
// MaxHeight is the most node levels above the chunks; 256^6 chunks of MinChunkSize exceed MaxSize.
MaxHeight = 6
// MaxSize is the largest blob in bytes, the largest offset of io.Seeker.
MaxSize = math.MaxInt64
)Variáveis
var (
// ErrInvalidArgument means a nil store, backend, log, source, context or function, a negative or
// out-of-range offset, an unknown whence, or a Put whose hash is not the object's.
ErrInvalidArgument = errors.New("koloblobs: invalid argument")
// ErrNotFound means the backend does not have an object of the blob.
ErrNotFound = errors.New("koloblobs: object not found")
// ErrCorrupt means an object does not match its hash, does not decrypt or breaks a tree rule.
ErrCorrupt = errors.New("koloblobs: object does not verify")
// ErrWrongKey means the blob's root does not open under the key, or commits to another key.
ErrWrongKey = errors.New("koloblobs: wrong key for this blob")
// ErrTooLarge means a source longer than MaxSize, or an object over MaxObjectSize.
ErrTooLarge = errors.New("koloblobs: too large")
// ErrReadOnly means Put on a RemoteBackend, or on a LogBackend whose log cannot append.
ErrReadOnly = errors.New("koloblobs: backend is read-only")
// ErrClosed means a Read, ReadAt or Seek on a closed Reader.
ErrClosed = errors.New("koloblobs: reader closed")
)Tipos
type Backend
type Backend interface {
// Get returns the object stored under h, or an error wrapping ErrNotFound. The caller does not modify it.
// A Get that waits on the network returns when ctx is done.
Get(ctx context.Context, h Hash) ([]byte, error)
// Put stores obj under h, its SHA-256, atomically; an object already stored is not stored again. Put must not keep obj.
Put(ctx context.Context, h Hash, obj []byte) error
}Backend holds objects by hash. Implementations must be safe for concurrent use.
type FetchFunc
type FetchFunc func(ctx context.Context, index uint64) ([]byte, error)FetchFunc returns the value of a content-log entry, checked by the transport; deleted or keyless entries wrap kololog.ErrDeleted or kololog.ErrKeyUnavailable.
type Hash
type Hash [HashSize]byteHash is the SHA-256 of an object, the name a Backend stores it under.
func (Hash) String
func (h Hash) String() stringString returns the hash as lowercase hex.
type ID
type ID [HashSize]byteID is a blob's content ID: the hash of its root object.
func (ID) String
func (id ID) String() stringString returns the ID as lowercase hex.
type Key
type Key [KeySize]byteKey is a file key, for one file and its versions only; it formats and logs as [redacted].
func NewKey
func NewKey() KeyNewKey returns a random file key; use a new one for each file.
func (Key) Format
func (Key) Format(f fmt.State, _ rune)Format writes [redacted] for every verb, so no fmt verb prints the key.
func (Key) LogValue
func (Key) LogValue() slog.ValueLogValue returns [redacted].
func (Key) MarshalJSON
func (Key) MarshalJSON() ([]byte, error)MarshalJSON returns "[redacted]"; store a key only in a binary encoding.
func (Key) String
func (Key) String() stringString returns [redacted].
type LocateFunc
type LocateFunc func(h Hash) (uint64, bool)LocateFunc returns the content-log index of the object h, or false if it does not know it.
type Log
type Log interface {
Len() uint64
Get(index uint64) ([]byte, error)
EntryInfo(index uint64) (kololog.EntryInfo, error)
}Log is what a LogBackend reads: a kolo-store or kolo-log log or replica. One with an Append(v any) (uint64, error) method, such as a log, can also be written to. Get and EntryInfo must be safe for concurrent use: a LogBackend reads several entries at once when it indexes a log.
type LogBackend
type LogBackend struct {
// contains filtered or unexported fields
}LogBackend keeps objects as entries of a log, one per entry, indexed by hash on first use; it is safe for concurrent use.
func NewLogBackend
func NewLogBackend(l Log) *LogBackendNewLogBackend returns a Backend on l. Put appends to l if l has an Append method, and returns ErrReadOnly otherwise.
func (LogBackend) Get
func (b *LogBackend) Get(ctx context.Context, h Hash) ([]byte, error)Get returns the object stored under h, or ErrNotFound. Entries that are deleted or whose kolo-log key is not here cannot be read, and their objects are not found. ctx bounds the index scan.
func (LogBackend) Index
func (b *LogBackend) Index(ctx context.Context, h Hash) (uint64, error)Index returns the entry index of the object h in the log, or an error wrapping ErrNotFound; a deleted entry is not found. ctx bounds the index scan.
func (LogBackend) Put
func (b *LogBackend) Put(ctx context.Context, h Hash, obj []byte) errorPut appends obj as a new entry unless the log already holds it live. It returns ErrInvalidArgument if h is not the SHA-256 of obj and ErrTooLarge over MaxObjectSize. ctx bounds the index scan.
type Reader
type Reader struct {
// contains filtered or unexported fields
}Reader reads one blob as an io.Reader, io.ReaderAt and io.Seeker, checking every object before returning its bytes; it is safe for concurrent use, one call at a time.
func (Reader) Close
func (r *Reader) Close() errorClose clears the reader's key material and chunk; later reads return ErrClosed. Closing twice is fine.
func (Reader) Read
func (r *Reader) Read(p []byte) (int, error)Read reads from the current offset and advances it.
func (Reader) ReadAt
func (r *Reader) ReadAt(p []byte, off int64) (int, error)ReadAt reads len(p) bytes from offset off, or up to the end of the blob with io.EOF.
func (Reader) Seek
func (r *Reader) Seek(offset int64, whence int) (int64, error)Seek sets the offset of the next Read, as io.Seeker; an offset past the end reads io.EOF.
func (Reader) Size
func (r *Reader) Size() int64Size returns the blob's size in bytes.
type RemoteBackend
type RemoteBackend struct {
// contains filtered or unexported fields
}RemoteBackend reads objects from a content log on another peer, one entry per object; it is read-only and safe for concurrent use if fetch and locate are.
func NewRemoteBackend
func NewRemoteBackend(fetch FetchFunc, locate LocateFunc) *RemoteBackendNewRemoteBackend returns a Backend that finds an object's entry with locate and gets it with fetch.
func (RemoteBackend) Get
func (b *RemoteBackend) Get(ctx context.Context, h Hash) ([]byte, error)Get fetches the entry holding h; an unknown object or a deleted or keyless entry is ErrNotFound.
func (RemoteBackend) Put
func (b *RemoteBackend) Put(context.Context, Hash, []byte) errorPut returns ErrReadOnly: objects are written on the peer that owns the content log.
type Stats
type Stats struct {
BytesWritten uint64 // plaintext bytes Write read from its sources
BytesRead uint64 // plaintext bytes returned by Readers
ObjectsPut uint64 // objects passed to Backend.Put
ObjectsFetched uint64 // objects returned by Backend.Get
Rejected uint64 // fetched objects that failed a check
}Stats are a Store's totals since New.
type Store
type Store struct {
// contains filtered or unexported fields
}Store writes and reads blobs on a Backend; it is safe for concurrent use.
func New
func New(b Backend) *StoreNew returns a Store on b.
func (Store) Objects
func (s *Store) Objects(ctx context.Context, id ID, key Key) iter.Seq2[Hash, error]Objects lists the hash of every object of the blob id, root first, fetching the nodes but not the chunks; it stops at the first error, yielded with a zero Hash.
func (Store) Open
func (s *Store) Open(ctx context.Context, id ID, key Key) (*Reader, error)Open returns a Reader for the blob id under key after checking the root: ErrWrongKey for another key, ErrNotFound if the backend lacks it. The Reader passes ctx to every Backend.Get it makes.
func (Store) Stats
func (s *Store) Stats() StatsStats returns the store's totals; it is safe to call at any time.
func (Store) Write
func (s *Store) Write(ctx context.Context, key Key, src io.Reader) (ID, error)Write reads src to its end, stores it as a blob under key and returns its ID; the same bytes and key give the same ID, so a Write killed part way is resumed by running it again. It checks ctx between chunks.
Chunking, sealing and Put run as a pipeline, so a Write uses several cores and a slow Put does not hold up the chunker. Put is still called from one goroutine, one object at a time in chunk order, so the objects, the tree and the ID are those of a Write that does everything in turn. A panic of src or of Put reaches the caller of Write.
Bom saber
Os mesmos bytes com a mesma chave dão o mesmo ID e não guardam nenhum objeto novo. Assim, um Write que foi parado ou morto é retomado rodando-o de novo com a mesma chave e a mesma fonte, e uma versão nova escrita com a chave do arquivo guarda só os fragmentos que mudaram. A kolo-store acrescenta cada entrada de forma atômica e a sincroniza no disco, então uma escrita morta deixa só entradas inteiras. O custo de retomar é ler a fonte e calcular o hash dela de novo. Depois de uma falha ou um cancelamento, o Write para de ler a fonte na hora e não cifra mais fragmentos. Um pânico da fonte, do Put do backend ou da cifragem chega a quem chama o Write na goroutine dele, com o mesmo valor, então quem chama pode recuperá-lo; as goroutines da escrita terminam e os buffers dela são apagados.
Ler e verificar um intervalo
Cada objeto é verificado contra o hash que o pai lista, então uma leitura retorna os bytes certos ou um erro, nunca bytes errados.
- Open busca a raiz pelo ID do blob, verifica que o hash SHA-256 dela é o ID, a descriptografa e verifica o compromisso da chave. Outra chave dá ErrWrongKey.
- ReadAt desce um nó por nível, escolhido pelos tamanhos dos filhos que o pai lista, e verifica cada nó contra o hash que o pai informa.
- Ele busca só os fragmentos que cobrem o intervalo. Cada um é verificado contra o seu hash, descriptografado, e tem o MAC de conteúdo calculado de novo antes de um byte ser retornado.
- Um objeto que falta ou foi alterado para a leitura com ErrNotFound ou ErrCorrupt. Os bytes de antes voltam com o erro, nunca um byte errado.
- Os objetos vêm de um Backend: um log local da kolo-store, uma réplica copiada com a kolo-sync ou entradas buscadas uma a uma em outro peer.
Um Reader é um io.Reader, um io.ReaderAt e um io.Seeker, seguro para uso concorrente. Chamadas concorrentes a ReadAt rodam uma de cada vez, porque o lock fica preso enquanto um fragmento é buscado, então use um Reader por goroutine para buscar em paralelo. ReadAt busca um nó por nível da árvore e os fragmentos que cobrem o intervalo, e io.NewSectionReader(r, start, length) dá um intervalo como fluxo. Cada objeto é verificado antes de qualquer byte dele ser retornado; uma leitura que encontra um objeto ruim ou ausente retorna os bytes anteriores e o erro. O leitor passa o contexto dado a Open para cada Backend.Get, então encerrar o contexto encerra as leituras com ctx.Err().
NewLogBackend guarda cada objeto como uma entrada de um log ou réplica da kolo-store ou da kolo-log. O primeiro Get, Put ou Index dele lê e decifra uma vez cada entrada viva do log que tem a chave, sob o lock do backend, para indexar as entradas pelo hash do objeto. Essa primeira varredura custa uma leitura do log inteiro, não do blob, e o contexto a encerra com ctx.Err(); as chamadas seguintes leem só as entradas acrescentadas desde então. As entradas sem chave são lidas de novo, em janelas de 64 entradas em até 4 goroutines, só quando um Get ou um Index não acha o objeto, nunca em um Put. Para ler intervalos de um log grande sem essa varredura, use NewRemoteBackend com um fetch que lê o log (Get) e um locate a partir de uma tabela de objetos que o escritor fez com Objects e Index.
NewRemoteBackend(fetch, locate) lê um log de conteúdo em outro peer, uma entrada por objeto, por exemplo com o Fetch por intervalos da kolo-sync e a prova de inclusão de cada entrada. Uma leitura de um intervalo com ele busca a raiz, um nó por nível e os fragmentos sob o intervalo. Uma entrada que o peer serve sem a chave da kolo-log, como faz um peer de fixação, é lida como ErrNotFound, a não ser que o leitor tenha essa chave. Um blob em um peer de fixação é lido de dois jeitos: faça pull do log dele para uma réplica e pegue as chaves das entradas de um dos aparelhos do dono; ou, para ler intervalos com o dono offline, pegue uma vez o head do dono e as chaves das entradas do blob com FetchHead e FetchKeys da kolo-sync, guarde-os e ligue o fetch ao FetchWithKeys da kolo-sync com esse head. A kolo-sync então abre cada entrada localmente com a chave guardada, depois de fechar o stream; nenhuma chave chega ao peer de fixação, que não tem nenhuma. Uma chave guardada que não confere é kolosync.ErrKeyMismatch, retornado envolvido. O README tem o código.
Limites
Todos são constantes do formato, não configurações: cada uma vem de algo fora da biblioteca, e mudar uma mudaria todos os IDs. Nenhuma limita o tamanho de um arquivo abaixo de MaxSize; um arquivo ocupa tantos fragmentos e nós quantos precisar.
MaxObjectSize, 4.128.764 bytes: o maior valor de entrada da kolo-log que a kolo-sync carrega, então todo objeto sincroniza. Um leitor compara o tamanho de um objeto com ele antes de calcular o hash ou decifrar.ObjectOverhead, 48 bytes por objeto: o MAC do conteúdo (32) e a tag do GCM (16).MaxChunkSize, 4.128.716 bytes,MaxObjectSizemenosObjectOverhead. Um fragmento é cortado ali quando nenhum ponto de corte é encontrado.MinChunkSize, 262.144 bytes (256 KiB). Só o último fragmento de um blob é menor. Os fragmentos têm em média cerca de 1 MiB.Fanout, 256 filhos por nó. Um nó cheio tem cerca de 10 KiB.MaxHeight, 6 níveis: 256^6 fragmentos do tamanho mínimo passam deMaxSize, então nenhuma árvore honesta é mais alta, e um leitor recusa uma mais alta.MaxSize, 2^63 - 1 bytes, o maior deslocamento doio.Seekerdo Go. Uma fonte mais longa éErrTooLarge.KeySizeeHashSize, 32 bytes.ID.String()eHash.String()são hexadecimal em minúsculas.- Memória:
Writeroda o fragmentador, 2 goroutines de cifragem e oPutdo backend como uma esteira, então mantém no máximo 5 fragmentos em andamento, cada um com um buffer de texto em claro e um buffer de objeto, mais o buffer do fragmentador e um nó pendente por nível da árvore. UmReadermantém os nós do caminho até o último fragmento e o texto em claro desse fragmento. Nenhum dos dois depende do tamanho do arquivo: um arquivo gerado de 10 GiB é escrito e lido de volta com pico de heap de 54 MiB e pico de memória residente de 84 MiB, e de 82 MiB e 173 MiB por um log da kolo-store no Pebble, comGOMEMLIMIT=64MiB. UmLogBackendacrescenta o índice, que cresce com o log e não tem limite: cerca de 140 bytes de heap por entrada (142 medidos com 1 milhão de entradas), então um log de 10 milhões de entradas de um peer em que você não confia custa cerca de 1,4 GB depois de indexado. Objectsé a única operação cujo trabalho segue o tamanho que a raiz declara, e não os bytes pedidos: cerca de um hash porMinChunkSizedo tamanho declarado, até cerca de 2^45 paraMaxSize, com uma busca de nó a cada 256. Dê a ela um contexto com prazo para blobs de escritores em que você não confia.
Segurança
- A criptografia é criptografia determinística com uma chave derivada do conteúdo. O HKDF-SHA256 (RFC 5869) deriva três subchaves da chave do arquivo: uma chave de MAC do conteúdo, uma chave de objeto e a tabela que o fragmentador usa. Um objeto é um HMAC-SHA256 (RFC 2104) de 32 bytes do rótulo de tipo e do texto em claro sob a chave de MAC do conteúdo, seguido do texto em claro selado com AES-256-GCM (NIST SP 800-38D) sob uma chave que é o HMAC desse valor sob a chave de objeto, com um nonce fixo. Cada chave derivada criptografa um único texto em claro. Ao abrir, o leitor calcula o MAC de novo e recusa uma diferença com
ErrCorrupt, então cada texto em claro tem exatamente um objeto. - A deduplicação fica dentro de uma chave. Sem a chave ninguém consegue calcular um objeto, o hash dele ou os pontos de corte para um arquivo suposto, então quem tem os objetos não consegue testar se um arquivo conhecido está guardado. Chaves diferentes nunca compartilham um objeto.
- A raiz guarda
SHA-256("kolo-blobs/key/v0" ‖ key), verificado ao abrir, então um ID abre com uma única chave, e cada outro objeto fica fixado pelo hash na árvore: um ID dá um único texto em claro. Cada tipo de objeto (fragmento, nó, raiz) tem o próprio rótulo, e um objeto de um tipo nunca abre como outro. - O ID, o SHA-256 do objeto raiz, se compromete com a chave, o tamanho, a forma da árvore e cada fragmento, vem só do conteúdo e da chave, e não revela nada do conteúdo sem a chave.
- O que o armazenamento vê: em um
Backendpuro, o tamanho exato de cada objeto (o do fragmento mais 48 bytes), hashes repetidos e o número de objetos por escrita. Só oLogBackendpreenche: cada objeto é uma entrada da kolo-log, criptografada de novo com uma chave de entrada que o peer de armazenamento não tem e preenchida pela kolo-log, então um peer de fixação vê quantas entradas existem e os tamanhos com preenchimento, e quantas entradas novas cada versão acrescenta. Um peer que serveFetchouFetchWithKeyspara umRemoteBackendvê a identidade do leitor, quais entradas ele busca e quando, os tamanhos delas e o tamanho do head contra o qual ele confere, então fica sabendo a forma da árvore, qual blob é aberto, quais intervalos dele são lidos e onde uma leitura para. Nunca fica sabendo o conteúdo nem as chaves. - Os tamanhos dos fragmentos vêm de uma tabela derivada da chave do arquivo, então os pontos de corte não podem ser comparados entre chaves. Com a mesma chave, alguém que conhece ou escolhe parte de um arquivo e vê os tamanhos dos fragmentos pode aprender o bastante dessa tabela para testar palpites sobre outro conteúdo com essa chave a partir dos tamanhos dos fragmentos.
- Duas camadas de chaves em um log: as chaves de entrada da kolo-log protegem cada entrada em trânsito e em cada peer, e só viajam para peers com acesso
Keysda kolo-sync; a chave do arquivo protege o blob e viaja com o ID para quem pode lê-lo. Um peer de fixação não tem nenhuma das duas. O teste da biblioteca despeja o armazenamento de um peer de fixação e não encontra nenhuma chave de arquivo, subchave, chave de entrada, objeto de blob nem texto em claro. - Um valor
Key, um ponteiro para um ou um em um campo exportado de struct é impresso e registrado como[redacted]com fmt, slog e encoding/json. Em um campo não exportado de struct,%ve%+vdo fmt e o handler de texto do slog imprimem os bytes crus, então nunca guarde uma chave em um campo não exportado de uma struct que é impressa ou registrada.key[:]dá os bytes; guarde-os só criptografados. Nenhum erro leva bytes de chave nem conteúdo. Reader.Closeapaga as subchaves e o buffer de fragmento do leitor. As cópias internas das chaves de objeto nas cifras AES ficam na memória até o runtime reutilizá-las, como na kolo-log.- A exclusão é de melhor esforço, e esta biblioteca nunca exclui. Uma camada acima que remove um blob exclui as entradas dele do log com o
Deleteda kolo-log, que vale nos peers que seguem o protocolo; um peer que já tem a chave da entrada pode ficar com os dados. Veja Exclusão. Versões escritas com a mesma chave, e reescritas idênticas, compartilham entradas, então excluir osObjectsde uma versão quebra as outras: exclua só as entradas que nenhum blob mantido com a chave lista. Os objetos de uma escrita que nunca terminou ficam no log até serem excluídos.
Construir um sistema de atualização por cima
São fatos da biblioteca, não um recurso: a kolo-blobs não tem um sistema de atualização.
- Cada objeto é verificado contra o seu hash antes de devolver os bytes, então ler um blob até o fim verifica tudo contra o ID dele.
- Uma leitura de intervalo busca só os fragmentos que cobrem o intervalo, mais um nó da árvore por nível.
- O mesmo conteúdo só é deduplicado com a mesma chave. A kolo-files dá uma chave a cada arquivo, então conteúdo novo escrito no mesmo caminho de um volume da kolo-files reaproveita os fragmentos que não mudaram.
- Um peer de fixação serve só texto cifrado.
Limites conhecidos
- Sem instruções AES na CPU (algumas CPUs de 32 bits ou embarcadas), o AES em software do Go é mais lento.
- A primeira varredura do
LogBackendlê cada entrada viva com chave do log, então em um log grande a primeira leitura de um intervalo custa essa varredura.RemoteBackendcom uma tabela de objetos evita isso. - Todos os testes rodam em 127.0.0.1. Experimental. A API pode mudar antes da v1.0.0.
Erros
| Erro | Mensagem |
|---|---|
ErrClosed | koloblobs: reader closed |
ErrCorrupt | koloblobs: object does not verify |
ErrInvalidArgument | koloblobs: invalid argument |
ErrNotFound | koloblobs: object not found |
ErrReadOnly | koloblobs: backend is read-only |
ErrTooLarge | koloblobs: too large |
ErrWrongKey | koloblobs: wrong key for this blob |
Teste os erros com errors.Is; nenhum leva bytes de chave nem conteúdo. ErrNotFound também cobre uma entrada excluída e uma sem a chave em um LogBackend, e um objeto que locate não conhece ou que fetch informa como excluído ou sem chave em um RemoteBackend. Uma raiz que não abre com a chave, ou que se compromete com outra chave, é ErrWrongKey, e o mesmo vale para um objeto que não é a raiz dado como ID. Os erros da fonte e do backend voltam envolvidos, e Write retorna ctx.Err() quando o contexto termina.
Referências
- NIST FIPS 180-4 (2015).
- Usa: SHA-256, para os hashes de objeto, os IDs e o compromisso de chave.
- Não implementa: nada.
- RFC 2104, HMAC: Keyed-Hashing for Message Authentication (Informational, fevereiro de 1997).
- Usa: HMAC-SHA256, para o MAC do conteúdo e as chaves por objeto.
- Não implementa: nada.
- RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF) (Informational, maio de 2010).
- Usa: HKDF-SHA256, para as subchaves da chave de um arquivo.
- Não implementa: nada.
- NIST SP 800-38D (2007, GCM).
- Usa: AES-256-GCM, para a criptografia e a autenticidade dos objetos.
- Não implementa: os nonces aleatórios. Cada objeto tem a própria chave derivada e um nonce fixo.
- Xia et al., FastCDC: A Fast and Efficient Content-Defined Chunking Approach for Data Deduplication, USENIX ATC 2016.
- Usa: o gear hash, o salto de pontos de corte e a fragmentação normalizada, para o fragmentador.
- Não implementa: a tabela gear fixa. A tabela gear é derivada da chave do arquivo.
- RFC 5297, SIV Authenticated Encryption Using AES (Informational, October 2008) and RFC 8452, AES-GCM-SIV (Informational, April 2019).
- Usa: nada.
- Não implementa: SIV. Nem a RFC 5297 nem a RFC 8452 é declarada.