kolo docsbeta

kolo-blobs

Almacenamiento de archivos cifrado y direccionado por contenido. Guarda un archivo de cualquier tamaño, lee cualquier rango de él y mantenlo en peers de anclaje que no pueden leerlo.

En esta página

kolo-blobs guarda los bytes de un archivo y nada más: ni nombres, ni carpetas, ni versiones. Write corta un archivo en fragmentos por puntos que dependen de su contenido (FastCDC), cifra cada fragmento (AES-GCM, NIST SP 800-38D) con claves derivadas con HKDF (RFC 5869) de una clave aleatoria para ese archivo, construye un árbol de Merkle sobre ellos y devuelve el ID del blob, el hash SHA-256 (FIPS 180-4) de la raíz del árbol. Open devuelve un lector que comprueba cada fragmento contra el árbol mientras lo transmite, y lee cualquier rango trayendo solo los fragmentos que lo cubren. Con NewLogBackend, las piezas de un blob son entradas de un log de kolo-store, así que viajan con kolo-sync y se guardan en peers de anclaje de kolo-pin, que solo tienen texto cifrado y nunca una clave. El paquete de Go se llama koloblobs.

Todos los pasos

De un archivo a un ID de blob

Un blob son solo los bytes de un archivo. Los nombres, las carpetas y las versiones son de la capa de encima, como kolo-files.

  1. Write corta el archivo en fragmentos donde lo dice su contenido: al menos 256 KiB, cerca de 1 MiB de media. Los puntos de corte dependen también de la clave del archivo, así que cambian con cada clave.
  2. Cada fragmento se convierte en un objeto: un MAC de contenido de 32 bytes y luego el fragmento sellado con AES-256-GCM bajo una clave derivada de la clave del archivo y del contenido. El hash SHA-256 del objeto es su nombre.
  3. Un árbol enumera el hash y el tamaño de cada objeto, hasta 256 hijos por nodo. A un archivo de hasta 256 fragmentos le basta una sola raíz encima.
  4. La raíz también se compromete con la clave del archivo. El ID del blob es el hash SHA-256 del objeto raíz, así que nombra cada byte del archivo bajo esa clave.
  5. Una versión nueva escrita con la misma clave corta los mismos fragmentos lejos de la edición. Solo se guardan el fragmento de alrededor y una raíz nueva; los demás objetos se comparten.

Instalación

go get github.com/ciranda-dev/kolo-blobs

Compila con CGO_ENABLED=0 para obtener un binario solo en Go. Comparte archivos entre dos terminales explica paso a paso cómo enviar un archivo de un peer a otro con un código para compartir.

Inicio rápido

Este programa guarda un archivo de 20 MB en un log de kolo-store en disco, en un directorio temporal. Vuelve a leer 16 bytes del medio y luego guarda una versión editada con la misma clave.

main.go
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)
}

Imprime:

Texto
stored 20000000 bytes as 17 log entries
bytes 12000000 to 12000016 match: true
the edited version added 2 entries

El primer número fue 17, 18 o 19 en seis ejecuciones, porque los límites de los fragmentos dependen de la clave aleatoria: los fragmentos más una raíz. La versión editada añade el fragmento que rodea la inserción y una raíz nueva.

Referencia de la API

La referencia de la API se genera a partir del código Go y está en inglés.

Paquete koloblobs · github.com/ciranda-dev/kolo-blobs · v0.1.0

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
)

Variables

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]byte

Hash is the SHA-256 of an object, the name a Backend stores it under.

func (Hash) String
func (h Hash) String() string

String returns the hash as lowercase hex.

type ID

type ID [HashSize]byte

ID is a blob's content ID: the hash of its root object.

func (ID) String
func (id ID) String() string

String returns the ID as lowercase hex.

type Key

type Key [KeySize]byte

Key is a file key, for one file and its versions only; it formats and logs as [redacted].

func NewKey
func NewKey() Key

NewKey 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.Value

LogValue 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() string

String 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) *LogBackend

NewLogBackend 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) error

Put 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() error

Close 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() int64

Size 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) *RemoteBackend

NewRemoteBackend 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) error

Put 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) *Store

New 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() Stats

Stats 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.

Conviene saber

Los mismos bytes con la misma clave dan el mismo ID y no guardan ningún objeto nuevo. Así, un Write que se detuvo o se mató se reanuda ejecutándolo otra vez con la misma clave y la misma fuente, y una versión nueva escrita con la clave del archivo solo guarda los fragmentos que cambiaron. kolo-store añade cada entrada de forma atómica y la sincroniza en disco, así que una escritura matada solo deja entradas completas. El coste de reanudar es volver a leer y calcular el hash de la fuente. Tras un fallo o una cancelación, Write deja de leer la fuente en el acto y no cifra más fragmentos. Un pánico de la fuente, del Put del backend o del cifrado llega a quien llama a Write en su propia goroutine, con el mismo valor, así que quien llama puede recuperarlo; las goroutines de la escritura terminan y sus búferes se borran.

Todos los pasos

Leer y comprobar un rango

Cada objeto se comprueba contra el hash que enumera su padre, así que una lectura devuelve los bytes correctos o un error, nunca bytes erróneos.

  1. Open trae la raíz por el ID del blob, comprueba que su hash SHA-256 es el ID, la descifra y comprueba el compromiso de la clave. Otra clave da ErrWrongKey.
  2. ReadAt baja un nodo por nivel, elegido por los tamaños de los hijos que enumera su padre, y comprueba cada nodo contra el hash que da su padre.
  3. Trae solo los fragmentos que cubren el rango. Cada uno se comprueba contra su hash, se descifra y se vuelve a calcular su MAC de contenido antes de devolver un byte.
  4. Un objeto que falta o que se alteró detiene la lectura con ErrNotFound o ErrCorrupt. Los bytes anteriores llegan con el error, nunca un byte erróneo.
  5. Los objetos vienen de un Backend: un log local de kolo-store, una réplica copiada con kolo-sync o entradas traídas una a una de otro peer.

Un Reader es un io.Reader, un io.ReaderAt y un io.Seeker, seguro para uso concurrente. Las llamadas concurrentes a ReadAt se ejecutan de una en una, porque el bloqueo se mantiene mientras se trae un fragmento, así que usa un Reader por goroutine para traer en paralelo. ReadAt trae un nodo por nivel del árbol y los fragmentos que cubren el rango, y io.NewSectionReader(r, start, length) da un rango como flujo. Cada objeto se comprueba antes de devolver cualquiera de sus bytes; una lectura que encuentra un objeto incorrecto o ausente devuelve los bytes anteriores y el error. El lector pasa el contexto dado a Open a cada Backend.Get, así que terminarlo termina las lecturas con ctx.Err().

NewLogBackend guarda cada objeto como una entrada de un log o una réplica de kolo-store o de kolo-log. Su primer Get, Put o Index lee y descifra una vez cada entrada viva del log que tiene su clave, con el bloqueo del backend, para indexar las entradas por hash de objeto. Ese primer recorrido cuesta una lectura del log entero, no del blob, y el contexto lo termina con ctx.Err(); las llamadas siguientes solo leen las entradas añadidas desde entonces. Las entradas sin clave se vuelven a leer, en ventanas de 64 entradas en hasta 4 goroutines, solo cuando un Get o un Index no encuentran el objeto, nunca en un Put. Para leer rangos de un log grande sin ese recorrido, usa NewRemoteBackend con un fetch que lea el log (Get) y un locate a partir de una tabla de objetos que el escritor hizo con Objects e Index.

NewRemoteBackend(fetch, locate) lee un log de contenido en otro peer, una entrada por objeto, por ejemplo con el Fetch por rangos de kolo-sync y la prueba de inclusión de cada entrada. Una lectura de un rango con él trae la raíz, un nodo por nivel y los fragmentos que hay bajo el rango. Una entrada que el peer sirve sin su clave de kolo-log, como hace un peer de anclaje, se lee como ErrNotFound salvo que el lector tenga esa clave. Un blob en un peer de anclaje se lee de dos formas: haz pull de su log a una réplica y obtén las claves de las entradas de uno de los dispositivos del propietario; o, para leer rangos con el propietario desconectado, obtén una vez el head del propietario y las claves de las entradas del blob con FetchHead y FetchKeys de kolo-sync, guárdalos y conecta fetch a FetchWithKeys de kolo-sync con ese head. kolo-sync abre entonces cada entrada en local con la clave guardada, después de cerrar el stream; ninguna clave llega al peer de anclaje, que no tiene ninguna. Una clave guardada que no coincide es kolosync.ErrKeyMismatch, devuelto envuelto. El README tiene el código.

Límites

Todos son constantes del formato, no ajustes: cada una se deduce de algo externo a la biblioteca, y cambiar una cambiaría todos los ID. Ninguna limita el tamaño de un archivo por debajo de MaxSize; un archivo ocupa tantos fragmentos y nodos como necesita.

  • MaxObjectSize, 4.128.764 bytes: el mayor valor de entrada de kolo-log que lleva kolo-sync, así que todo objeto se sincroniza. Un lector compara el tamaño de un objeto con él antes de calcular su hash o descifrarlo.
  • ObjectOverhead, 48 bytes por objeto: el MAC del contenido (32) y la etiqueta de GCM (16).
  • MaxChunkSize, 4.128.716 bytes, MaxObjectSize menos ObjectOverhead. Un fragmento se corta ahí cuando no se encuentra ningún punto de corte.
  • MinChunkSize, 262.144 bytes (256 KiB). Solo el último fragmento de un blob es más pequeño. Los fragmentos miden en promedio cerca de 1 MiB.
  • Fanout, 256 hijos por nodo. Un nodo lleno ocupa unos 10 KiB.
  • MaxHeight, 6 niveles: 256^6 fragmentos del tamaño mínimo superan MaxSize, así que ningún árbol honesto es más alto, y un lector rechaza uno más alto.
  • MaxSize, 2^63 - 1 bytes, el mayor desplazamiento del io.Seeker de Go. Una fuente más larga es ErrTooLarge.
  • KeySize y HashSize, 32 bytes. ID.String() y Hash.String() son hexadecimal en minúsculas.
  • Memoria: Write ejecuta el troceador, 2 goroutines de cifrado y el Put del backend como una cadena, así que mantiene como mucho 5 fragmentos en curso, cada uno con un búfer de texto en claro y un búfer de objeto, más el búfer del troceador y un nodo pendiente por nivel del árbol. Un Reader mantiene los nodos del camino hasta su último fragmento y el texto en claro de ese fragmento. Ninguno depende del tamaño del archivo: un archivo generado de 10 GiB se escribe y se vuelve a leer con un pico de heap de 54 MiB y un pico de memoria residente de 84 MiB, y de 82 MiB y 173 MiB a través de un log de kolo-store en Pebble, con GOMEMLIMIT=64MiB. Un LogBackend añade su índice, que crece con el log y no tiene límite: unos 140 bytes de heap por entrada (142 medidos con 1 millón de entradas), así que un log de 10 millones de entradas de un peer en el que no confías cuesta unos 1,4 GB una vez indexado.
  • Objects es la única operación cuyo trabajo sigue el tamaño que declara la raíz y no los bytes pedidos: cerca de un hash por cada MinChunkSize del tamaño declarado, hasta unos 2^45 para MaxSize, con una lectura de nodo por cada 256. Dale un contexto con plazo para blobs de escritores en los que no confíes.

Seguridad

  • El cifrado es cifrado determinista con una clave derivada del contenido. HKDF-SHA256 (RFC 5869) deriva tres subclaves de la clave del archivo: una clave de MAC del contenido, una clave de objeto y la tabla que usa el troceador. Un objeto es un HMAC-SHA256 (RFC 2104) de 32 bytes de su etiqueta de tipo y su texto en claro con la clave de MAC del contenido, seguido del texto en claro sellado con AES-256-GCM (NIST SP 800-38D) con una clave que es el HMAC de ese valor con la clave de objeto, y un nonce fijo. Cada clave derivada cifra un solo texto en claro. Al abrir, el lector vuelve a calcular el MAC y rechaza una diferencia con ErrCorrupt, así que cada texto en claro tiene exactamente un objeto.
  • La deduplicación se queda dentro de una clave. Sin la clave nadie puede calcular un objeto, su hash ni sus puntos de corte para un archivo supuesto, así que quien tenga los objetos no puede comprobar si un archivo conocido está guardado. Claves distintas nunca comparten un objeto.
  • La raíz contiene SHA-256("kolo-blobs/key/v0" ‖ key), que se comprueba al abrir, así que un ID se abre con una sola clave, y cada otro objeto queda fijado por su hash en el árbol: un ID da un solo texto en claro. Cada tipo de objeto (fragmento, nodo, raíz) tiene su propia etiqueta, y un objeto de un tipo nunca se abre como otro.
  • El ID, el SHA-256 del objeto raíz, compromete la clave, el tamaño, la forma del árbol y cada fragmento, sale solo del contenido y de la clave, y no revela nada del contenido sin la clave.
  • Lo que ve el almacenamiento: en un Backend sin más, el tamaño exacto de cada objeto (el de su fragmento más 48 bytes), los hashes repetidos y el número de objetos por escritura. Solo LogBackend rellena: cada objeto es una entrada de kolo-log, cifrada otra vez con una clave de entrada que el peer de almacenamiento no tiene y rellenada por kolo-log, así que un peer de anclaje ve cuántas entradas hay y sus tamaños con relleno, y cuántas entradas nuevas añade cada versión. Un peer que sirve Fetch o FetchWithKeys a un RemoteBackend ve la identidad del lector, qué entradas trae y cuándo, sus tamaños y el tamaño del head con el que las comprueba, así que sabe la forma del árbol, qué blob se abre, qué rangos de él se leen y dónde se detiene una lectura. Nunca sabe el contenido ni las claves.
  • Los tamaños de los fragmentos salen de una tabla derivada de la clave del archivo, así que los puntos de corte no se pueden emparejar entre claves. Con una misma clave, alguien que conozca o elija parte de un archivo y vea los tamaños de los fragmentos puede llegar a saber lo bastante de esa tabla para poner a prueba suposiciones sobre otro contenido con esa clave a partir de sus tamaños de fragmento.
  • Dos capas de claves en un log: las claves de entrada de kolo-log protegen cada entrada en tránsito y en cada peer, y solo viajan a peers con acceso Keys de kolo-sync; la clave del archivo protege el blob y viaja con el ID a quienes pueden leerlo. Un peer de anclaje no tiene ninguna. La prueba de la biblioteca vuelca el almacén de un peer de anclaje y no encuentra ninguna clave de archivo, subclave, clave de entrada, objeto de blob ni texto en claro.
  • Un valor Key, un puntero a uno o uno en un campo exportado de un struct se imprime y se registra como [redacted] con fmt, slog y encoding/json. En un campo no exportado de un struct, %v y %+v de fmt y el manejador de texto de slog imprimen los bytes en bruto, así que nunca guardes una clave en un campo no exportado de un struct que se imprima o se registre. key[:] da los bytes; guárdalos solo cifrados. Ningún error lleva bytes de clave ni contenido.
  • Reader.Close borra las subclaves y el búfer de fragmento del lector. Las copias internas de las claves de objeto en los cifradores AES se quedan en memoria hasta que el runtime las reutiliza, como en kolo-log.
  • El borrado es de mejor esfuerzo, y esta biblioteca nunca borra. Una capa superior que elimina un blob borra sus entradas del log con el Delete de kolo-log, que se cumple en los peers que siguen el protocolo; un peer que ya tiene la clave de la entrada puede quedarse con los datos. Consulta Borrado. Las versiones escritas con una misma clave, y las reescrituras idénticas, comparten entradas, así que borrar los Objects de una versión rompe las demás: borra solo las entradas que no lista ningún blob conservado con esa clave. Los objetos de una escritura que nunca se completó se quedan en el log hasta que se borran.

Construir un sistema de actualización encima

Son hechos de la biblioteca, no una función: kolo-blobs no tiene un sistema de actualización.

  • Cada objeto se comprueba contra su hash antes de devolver sus bytes, así que leer un blob hasta el final lo comprueba entero contra su ID.
  • Una lectura de rango trae solo los fragmentos que cubren el rango, más un nodo del árbol por nivel.
  • El mismo contenido se deduplica solo bajo la misma clave. kolo-files da una clave a cada archivo, así que el contenido nuevo escrito en la misma ruta de un volumen de kolo-files reutiliza sus fragmentos sin cambios.
  • Un peer de anclaje sirve solo texto cifrado.

Límites conocidos

  • Sin instrucciones AES en la CPU (algunas CPU de 32 bits o embebidas), el AES por software de Go es más lento.
  • El primer recorrido de LogBackend lee cada entrada viva con clave del log, así que en un log grande la primera lectura de un rango cuesta ese recorrido. RemoteBackend con una tabla de objetos lo evita.
  • Todas las pruebas se ejecutan en 127.0.0.1. Experimental. La API puede cambiar antes de la v1.0.0.

Errores

ErrorMensaje
ErrClosedkoloblobs: reader closed
ErrCorruptkoloblobs: object does not verify
ErrInvalidArgumentkoloblobs: invalid argument
ErrNotFoundkoloblobs: object not found
ErrReadOnlykoloblobs: backend is read-only
ErrTooLargekoloblobs: too large
ErrWrongKeykoloblobs: wrong key for this blob

Comprueba los errores con errors.Is; ninguno lleva bytes de clave ni contenido. ErrNotFound también cubre una entrada borrada y una sin su clave en un LogBackend, y un objeto que locate no conoce o que fetch informa como borrado o sin clave en un RemoteBackend. Una raíz que no se abre con la clave, o que compromete otra clave, es ErrWrongKey, y también lo es un objeto que no es la raíz dado como ID. Los errores de la fuente y del backend llegan envueltos, y Write devuelve ctx.Err() cuando termina el contexto.

Referencias