age: add DecryptReaderAt

Author: FiloSottile

age.go

@@ -252,13 +252,12 @@ func (e *NoIdentityMatchError) Unwrap() []error {
 }
 
 // Decrypt decrypts a file encrypted to one or more identities.
-//
-// It returns a Reader reading the decrypted plaintext of the age file read
-// from src. All identities will be tried until one successfully decrypts the file.
+// All identities will be tried until one successfully decrypts the file.
 // Native, non-interactive identities are tried before any other identities.
 //
-// If no identity matches the encrypted file, the returned error will be of type
-// [NoIdentityMatchError].
+// Decrypt returns a Reader reading the decrypted plaintext of the age file read
+// from src. If no identity matches the encrypted file, the returned error will
+// be of type [NoIdentityMatchError].
 func Decrypt(src io.Reader, identities ...Identity) (io.Reader, error) {
 	hdr, payload, err := format.Parse(src)
 	if err != nil {
@@ -278,6 +277,58 @@ func Decrypt(src io.Reader, identities ...Identity) (io.Reader, error) {
 	return stream.NewDecryptReader(streamKey(fileKey, nonce), payload)
 }
 
+// DecryptReaderAt decrypts a file encrypted to one or more identities.
+// All identities will be tried until one successfully decrypts the file.
+// Native, non-interactive identities are tried before any other identities.
+//
+// DecryptReaderAt takes an underlying [io.ReaderAt] and its total encrypted
+// size, and returns a ReaderAt of the decrypted plaintext and the plaintext
+// size. These can be used for example to instantiate an [io.SectionReader],
+// which implements [io.Reader] and [io.Seeker]. Note that ReaderAt by
+// definition disregards the seek position of src.
+//
+// The ReadAt method of the returned ReaderAt can be called concurrently.
+// The ReaderAt will internally cache the most recently decrypted chunk.
+// DecryptReaderAt reads and decrypts the final chunk before returning,
+// to authenticate the plaintext size.
+//
+// If no identity matches the encrypted file, the returned error will be of
+// type [NoIdentityMatchError].
+func DecryptReaderAt(src io.ReaderAt, encryptedSize int64, identities ...Identity) (io.ReaderAt, int64, error) {
+	srcReader := io.NewSectionReader(src, 0, encryptedSize)
+	hdr, payload, err := format.Parse(srcReader)
+	if err != nil {
+		return nil, 0, fmt.Errorf("failed to read header: %w", err)
+	}
+	buf := &bytes.Buffer{}
+	if err := hdr.Marshal(buf); err != nil {
+		return nil, 0, fmt.Errorf("failed to serialize header: %w", err)
+	}
+
+	fileKey, err := decryptHdr(hdr, identities...)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	nonce := make([]byte, streamNonceSize)
+	if _, err := io.ReadFull(payload, nonce); err != nil {
+		return nil, 0, fmt.Errorf("failed to read nonce: %w", err)
+	}
+
+	payloadOffset := int64(buf.Len()) + int64(len(nonce))
+	payloadSize := encryptedSize - payloadOffset
+	plaintextSize, err := stream.PlaintextSize(payloadSize)
+	if err != nil {
+		return nil, 0, err
+	}
+	payloadReaderAt := io.NewSectionReader(src, payloadOffset, payloadSize)
+	r, err := stream.NewDecryptReaderAt(streamKey(fileKey, nonce), payloadReaderAt, payloadSize)
+	if err != nil {
+		return nil, 0, err
+	}
+	return r, plaintextSize, nil
+}
+
 func decryptHdr(hdr *format.Header, identities ...Identity) ([]byte, error) {
 	if len(identities) == 0 {
 		return nil, errors.New("no identities specified")

internal/inspect/inspect.go

@@ -10,7 +10,6 @@ import (
 	"filippo.io/age/armor"
 	"filippo.io/age/internal/format"
 	"filippo.io/age/internal/stream"
-	"golang.org/x/crypto/chacha20poly1305"
 )
 
 type Metadata struct {
@@ -88,9 +87,9 @@ func Inspect(r io.Reader, fileSize int64) (*Metadata, error) {
 		}
 		data.Sizes.Armor = tr.count - fileSize
 	}
-	data.Sizes.Overhead = streamOverhead(fileSize - data.Sizes.Header)
-	if data.Sizes.Overhead > fileSize-data.Sizes.Header {
-		return nil, fmt.Errorf("payload too small to be a valid age file")
+	data.Sizes.Overhead, err = streamOverhead(fileSize - data.Sizes.Header)
+	if err != nil {
+		return nil, fmt.Errorf("failed to compute stream overhead: %w", err)
 	}
 	data.Sizes.MinPayload = fileSize - data.Sizes.Header - data.Sizes.Overhead
 	data.Sizes.MaxPayload = data.Sizes.MinPayload
@@ -114,13 +113,15 @@ func (tr *trackReader) Read(p []byte) (int, error) {
 	return n, err
 }
 
-func streamOverhead(payloadSize int64) int64 {
+func streamOverhead(payloadSize int64) (int64, error) {
 	const streamNonceSize = 16
-	const encChunkSize = stream.ChunkSize + chacha20poly1305.Overhead
-	payloadSize -= streamNonceSize
-	if payloadSize <= 0 {
-		return streamNonceSize
+	if payloadSize < streamNonceSize {
+		return 0, fmt.Errorf("encrypted size too small: %d", payloadSize)
+	}
+	encryptedSize := payloadSize - streamNonceSize
+	plaintextSize, err := stream.PlaintextSize(encryptedSize)
+	if err != nil {
+		return 0, err
 	}
-	chunks := (payloadSize + encChunkSize - 1) / encChunkSize
-	return streamNonceSize + chunks*chacha20poly1305.Overhead
+	return payloadSize - plaintextSize, nil
 }

internal/inspect/inspect_test.go

@@ -0,0 +1,46 @@
+package inspect
+
+import (
+	"fmt"
+	"testing"
+
+	"filippo.io/age/internal/stream"
+)
+
+func TestStreamOverhead(t *testing.T) {
+	tests := []struct {
+		payloadSize int64
+		want        int64
+		wantErr     bool
+	}{
+		{payloadSize: 0, wantErr: true},
+		{payloadSize: 15, wantErr: true},
+		{payloadSize: 16, wantErr: true},
+		{payloadSize: 16 + 15, wantErr: true},
+		{payloadSize: 16 + 16, want: 16 + 16}, // empty plaintext
+		{payloadSize: 16 + 1 + 16, want: 16 + 16},
+		{payloadSize: 16 + stream.ChunkSize + 16, want: 16 + 16},
+		{payloadSize: 16 + stream.ChunkSize + 16 + 1, wantErr: true},
+		{payloadSize: 16 + stream.ChunkSize + 16 + 15, wantErr: true},
+		{payloadSize: 16 + stream.ChunkSize + 16 + 16, wantErr: true}, // empty final chunk
+		{payloadSize: 16 + stream.ChunkSize + 16 + 1 + 16, want: 16 + 16 + 16},
+	}
+	for _, tt := range tests {
+		name := "payloadSize=" + fmt.Sprint(tt.payloadSize)
+		t.Run(name, func(t *testing.T) {
+			got, gotErr := streamOverhead(tt.payloadSize)
+			if gotErr != nil {
+				if !tt.wantErr {
+					t.Errorf("streamOverhead() failed: %v", gotErr)
+				}
+				return
+			}
+			if tt.wantErr {
+				t.Fatal("streamOverhead() succeeded unexpectedly")
+			}
+			if got != tt.want {
+				t.Errorf("streamOverhead() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}

internal/stream/stream.go

@@ -8,15 +8,42 @@ package stream
 import (
 	"bytes"
 	"crypto/cipher"
+	"encoding/binary"
 	"errors"
 	"fmt"
 	"io"
+	"sync/atomic"
 
 	"golang.org/x/crypto/chacha20poly1305"
 )
 
 const ChunkSize = 64 * 1024
 
+func EncryptedChunkCount(encryptedSize int64) (int64, error) {
+	chunks := (encryptedSize + encChunkSize - 1) / encChunkSize
+
+	plaintextSize := encryptedSize - chunks*chacha20poly1305.Overhead
+	expChunks := (plaintextSize + ChunkSize - 1) / ChunkSize
+	// Empty plaintext, the only case that allows (and requires) an empty chunk.
+	if plaintextSize == 0 {
+		expChunks = 1
+	}
+	if expChunks != chunks {
+		return 0, fmt.Errorf("invalid encrypted payload size: %d", encryptedSize)
+	}
+
+	return chunks, nil
+}
+
+func PlaintextSize(encryptedSize int64) (int64, error) {
+	chunks, err := EncryptedChunkCount(encryptedSize)
+	if err != nil {
+		return 0, err
+	}
+	plaintextSize := encryptedSize - chunks*chacha20poly1305.Overhead
+	return plaintextSize, nil
+}
+
 type DecryptReader struct {
 	a   cipher.AEAD
 	src io.Reader
@@ -135,6 +162,12 @@ func incNonce(nonce *[chacha20poly1305.NonceSize]byte) {
 	panic("stream: chunk counter wrapped around")
 }
 
+func nonceForChunk(chunkIndex int64) *[chacha20poly1305.NonceSize]byte {
+	var nonce [chacha20poly1305.NonceSize]byte
+	binary.BigEndian.PutUint64(nonce[3:11], uint64(chunkIndex))
+	return &nonce
+}
+
 func setLastChunkFlag(nonce *[chacha20poly1305.NonceSize]byte) {
 	nonce[len(nonce)-1] = lastChunkFlag
 }
@@ -312,3 +345,102 @@ func (r *EncryptReader) feedBuffer() error {
 
 	return nil
 }
+
+type DecryptReaderAt struct {
+	a      cipher.AEAD
+	src    io.ReaderAt
+	size   int64
+	chunks int64
+	cache  atomic.Pointer[cachedChunk]
+}
+
+type cachedChunk struct {
+	off  int64
+	data []byte
+}
+
+func NewDecryptReaderAt(key []byte, src io.ReaderAt, size int64) (*DecryptReaderAt, error) {
+	aead, err := chacha20poly1305.New(key)
+	if err != nil {
+		return nil, err
+	}
+
+	// Check that size is valid by decrypting the final chunk.
+	chunks, err := EncryptedChunkCount(size)
+	if err != nil {
+		return nil, err
+	}
+	finalChunkIndex := chunks - 1
+	finalChunkOff := finalChunkIndex * encChunkSize
+	finalChunkSize := size - finalChunkOff
+	finalChunk := make([]byte, finalChunkSize)
+	if _, err := src.ReadAt(finalChunk, finalChunkOff); err != nil {
+		return nil, fmt.Errorf("failed to read final chunk: %w", err)
+	}
+	nonce := nonceForChunk(finalChunkIndex)
+	setLastChunkFlag(nonce)
+	plaintext, err := aead.Open(finalChunk[:0], nonce[:], finalChunk, nil)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decrypt and authenticate final chunk: %w", err)
+	}
+	cache := &cachedChunk{off: finalChunkOff, data: plaintext}
+
+	plaintextSize := size - chunks*chacha20poly1305.Overhead
+	r := &DecryptReaderAt{a: aead, src: src, size: plaintextSize, chunks: chunks}
+	r.cache.Store(cache)
+	return r, nil
+}
+
+func (r *DecryptReaderAt) ReadAt(p []byte, off int64) (n int, err error) {
+	if off < 0 || off > r.size {
+		return 0, fmt.Errorf("offset out of range [0:%d]: %d", r.size, off)
+	}
+	if len(p) == 0 {
+		return 0, nil
+	}
+	chunk := make([]byte, encChunkSize)
+	for len(p) > 0 && off < r.size {
+		chunkIndex := off / ChunkSize
+		chunkOff := chunkIndex * encChunkSize
+		encSize := r.size + r.chunks*chacha20poly1305.Overhead
+		chunkSize := min(encSize-chunkOff, encChunkSize)
+
+		cached := r.cache.Load()
+		var plaintext []byte
+		if cached != nil && cached.off == chunkOff {
+			plaintext = cached.data
+		} else {
+			nn, err := r.src.ReadAt(chunk[:chunkSize], chunkOff)
+			if err == io.EOF {
+				if int64(nn) != chunkSize {
+					err = io.ErrUnexpectedEOF
+				} else {
+					err = nil
+				}
+			}
+			if err != nil {
+				return n, fmt.Errorf("failed to read chunk at offset %d: %w", chunkOff, err)
+			}
+			nonce := nonceForChunk(chunkIndex)
+			if chunkIndex == r.chunks-1 {
+				setLastChunkFlag(nonce)
+			}
+			plaintext, err = r.a.Open(chunk[:0], nonce[:], chunk[:chunkSize], nil)
+			if err != nil {
+				return n, fmt.Errorf("failed to decrypt and authenticate chunk at offset %d: %w", chunkOff, err)
+			}
+			r.cache.Store(&cachedChunk{off: chunkOff, data: plaintext})
+		}
+
+		plainChunkOff := int(off - chunkIndex*ChunkSize)
+		copySize := min(len(plaintext)-plainChunkOff, len(p))
+		copy(p, plaintext[plainChunkOff:plainChunkOff+copySize])
+		p = p[copySize:]
+		off += int64(copySize)
+		n += copySize
+	}
+	if off == r.size {
+		return n, io.EOF
+	}
+	return n, nil
+}