uploads

func OpenEnvelope ¶

func OpenEnvelope(payload string, unwrapAESKey func(wrappedKey []byte) (aesKey []byte, err error)) ([]byte, error)

OpenEnvelope is the inverse of SealEnvelope. The caller supplies an unwrap function that decrypts the RSA-OAEP-wrapped AES key (typically a KMS AsymmetricDecrypt call against the version recorded in env.KeyVersion); this package stays GCP-free.

The split lets break-glass / reader code reuse the same AES-GCM / base64 logic the upload side uses, without forcing every SDK consumer to pull in cloud.google.com/go/kms.

func OpenStream ¶ added in v0.1.343

func OpenStream(r io.Reader, unwrapAESKey func(keyVersion string, wrappedKey []byte) ([]byte, error)) (io.Reader, error)

OpenStream parses the header and calls unwrapAESKey with the stored key version and RSA-OAEP-SHA256-wrapped DEK. As with OpenEnvelope, the callback can use KMS without exposing the RSA private key to this package.

The key version is untrusted until a chunk authenticates; the callback must scope key lookup to the caller's authorized org. It must not modify wrappedKey, which is part of the authenticated header.

Read the returned reader to EOF to verify the complete stream. Each chunk authenticates before its plaintext is returned, and modification, deletion, reordering, splicing or a missing final chunk causes a read error.

The returned reader is not safe for concurrent use.

func SealEnvelope ¶

func SealEnvelope(plaintext []byte, publicKeyPEM, algorithm, keyVersion string) (string, error)

SealEnvelope produces the JSON-encoded payload string the upload service expects in the request's payload field. It mirrors the browser's hybrid AES-GCM / RSA-OAEP encryption minus the network call:

1. Generate a fresh AES-256 key + 12-byte IV.
2. AES-256-GCM encrypt the plaintext.
3. Parse the SPKI PEM into an RSA public key.
4. RSA-OAEP-SHA256 wrap the AES key.
5. Base64-encode each binary field, marshal the envelope.

The algorithm parameter is the value advertised by the server's GetOrgPublicKey response; mismatch against the client's hardcoded EncryptionAlgorithm is a hard failure rather than silently producing payloads no reader can decrypt.

keyVersion is the CryptoKeyVersion (e.g. "1") that wrapped this envelope, recorded so post-rotation readers know which private key to call AsymmetricDecrypt against.

func SealStream ¶ added in v0.1.343

func SealStream(w io.Writer, orgPub *rsa.PublicKey, algorithm, keyVersion string) (io.WriteCloser, error)

SealStream returns a writer that encrypts everything written to it into w as a stream envelope: a binary header followed by AES-GCM chunks in the STREAM construction.

A fresh AES-256 data encryption key is generated per stream and RSA-OAEP-SHA256-wrapped under orgPub in the header, mirroring SealEnvelope's hybrid scheme. The header is written before SealStream returns, and is bound into every chunk as additional authenticated data.

algorithm and keyVersion are the values advertised with orgPub by the server's GetOrgPublicKey response. As in SealEnvelope, a mismatch against the client's hardcoded EncryptionAlgorithm is a hard failure rather than silently producing payloads no reader can decrypt. keyVersion is the positive decimal CryptoKeyVersion, recorded so readers can select the same key after rotation.

The caller must Close the returned writer to emit the final chunk; a stream whose final chunk is missing does not open. Close does not close w, which the caller still owns.

The returned writer is not safe for concurrent use.

package main

import (
	"bytes"
	"crypto/rand"
	"crypto/rsa"
	"crypto/sha256"
	"fmt"
	"hash/crc32"
	"io"

	"chainguard.dev/sdk/uploads"
)

func main() {
	priv, err := rsa.GenerateKey(rand.Reader, 3072)
	if err != nil {
		panic(err)
	}

	// In production the destination is an object-storage writer and the
	// ciphertext is never held in memory; a buffer stands in here so the
	// example can check the checksum against the finished bytes.
	var sealed bytes.Buffer
	cw := uploads.NewCRC32CWriter(&sealed)
	sw, err := uploads.SealStream(cw, &priv.PublicKey, uploads.EncryptionAlgorithm, "1")
	if err != nil {
		panic(err)
	}
	if _, err := io.WriteString(sw, "hello argos"); err != nil {
		panic(err)
	}
	// Close seals the final chunk. A stream missing it does not open.
	if err := sw.Close(); err != nil {
		panic(err)
	}
	// The incrementally accumulated checksum is ready as soon as the last
	// byte is written, which is what a caller that cannot buffer needs.
	fmt.Println(cw.Sum32() == crc32.Checksum(sealed.Bytes(), crc32.MakeTable(crc32.Castagnoli)))

	// A production callback selects the stored key version in Cloud KMS.
	r, err := uploads.OpenStream(&sealed, func(keyVersion string, wrapped []byte) ([]byte, error) {
		if keyVersion != "1" {
			return nil, fmt.Errorf("unknown key version %q", keyVersion)
		}
		return rsa.DecryptOAEP(sha256.New(), rand.Reader, priv, wrapped, nil)
	})
	if err != nil {
		panic(err)
	}
	plaintext, err := io.ReadAll(r)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s\n", plaintext)
}

Output:
true
hello argos