capi

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 22, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package capi contains the pure-Go logic that backs the C ABI shared-library entry points in cmd/cshared/main.go. Splitting the logic out of the file that imports "C" lets the API surface be exercised by ordinary `go test` (no cgo, no -buildmode=c-shared dance) and keeps the C-bridge file thin.

The package is internal and is consumed only by cmd/cshared/main.go (the //export wrappers) and the matching test file. External callers must go through the C ABI surface.

Index

Constants

View Source 
const (
	BlobSlotN  = 0 // shared (Single + Triple): noiseSeed + KeyN
	BlobSlotD  = 1 // Single only: dataSeed + KeyD
	BlobSlotS  = 2 // Single only: startSeed + KeyS
	BlobSlotL  = 3 // optional (any mode): dedicated lockSeed + KeyL
	BlobSlotD1 = 4 // Triple only: dataSeed1 + KeyD1
	BlobSlotD2 = 5
	BlobSlotD3 = 6
	BlobSlotS1 = 7 // Triple only: startSeed1 + KeyS1
	BlobSlotS2 = 8
	BlobSlotS3 = 9
)

Blob slot identifiers — name the per-component slot in a blob's Single (N / D / S) or Triple (N / D1..D3 / S1..S3) layout, with L (lockSeed) shared across both modes. Slot ordering is stable across releases; bindings rely on the numeric values.

View Source 
const (
	BlobOptLockSeed = 1 << 0 // include KeyL + LS slot in the blob
	BlobOptMAC      = 1 << 1 // include MACKey + MACName in the blob
)

Export option bitmask flags — passed to BlobExport / BlobExport3 to enable optional sections of the blob. Without a flag the corresponding handle slots are not consulted and the resulting blob omits the matching JSON fields.

Variables

This section is empty.

Functions

func Channels 

func Channels() int

Channels returns the number of channels per pixel in the RGBWYOPA container layout (build-time constant, currently 8). Read-only.

func GetBarrierFill 

func GetBarrierFill() int

func GetBitSoup 

func GetBitSoup() int

func GetLockSoup 

func GetLockSoup() int

func GetMaxWorkers 

func GetMaxWorkers() int

func GetNonceBits 

func GetNonceBits() int

func HashCount 

func HashCount() int

HashCount returns the number of PRF-grade hash primitives shipped with the library — currently 9, matching len(hashes.Registry).

func HashName 

func HashName(i int) string

HashName returns the canonical name of the i-th hash primitive in iteration order, or "" when i is out of range.

func HashWidth 

func HashWidth(i int) int

HashWidth returns the native intermediate-state width of the i-th hash primitive in bits (128 / 256 / 512), or 0 when i is out of range.

func HeaderSize 

func HeaderSize() int

HeaderSize returns the current ciphertext-chunk header size in bytes (nonce + 2-byte width + 2-byte height). Tracks the active nonce-size override set via ITB_SetNonceBits / SetNonceBits, so streaming consumers always know how many bytes to read before calling ITB_ParseChunkLen on a fresh chunk.

Default configuration: 16 (nonce) + 4 (dimensions) = 20 bytes. Under SetNonceBits(256): 32 + 4 = 36 bytes. Under SetNonceBits(512): 64 + 4 = 68 bytes.

func LastError 

func LastError() string

LastError returns the textual reason for the most recent non-OK status produced by any capi call.

func LastMismatchField 

func LastMismatchField() string

LastMismatchField returns the JSON field name from the most recent non-OK Import / PeekConfig call that returned StatusEasyMismatch. Returns "" when the most recent failure was something other than a mismatch (or when no Import call has run yet on this thread).

func MACCount 

func MACCount() int

MACCount returns the number of shipped MAC primitives (currently 3).

func MACRegistryKeySize 

func MACRegistryKeySize(i int) int

MACRegistryKeySize returns the recommended key size in bytes for the i-th shipped MAC primitive, or 0 when i is out of range.

func MACRegistryMinKeyBytes 

func MACRegistryMinKeyBytes(i int) int

MACRegistryMinKeyBytes returns the minimum acceptable key length (bytes) for the i-th shipped MAC primitive, or 0 when i is out of range.

func MACRegistryName 

func MACRegistryName(i int) string

MACRegistryName returns the canonical name of the i-th shipped MAC primitive in iteration order, or "" when i is out of range.

func MACRegistryTagSize 

func MACRegistryTagSize(i int) int

MACRegistryTagSize returns the tag size in bytes for the i-th shipped MAC primitive, or 0 when i is out of range.

func MaxKeyBits 

func MaxKeyBits() int

MaxKeyBits returns the maximum supported ITB key width in bits (build-time constant, currently 2048). Read-only — there is no matching setter.

func NewBlob128 

func NewBlob128() (id BlobHandleID, st Status)

NewBlob128 / NewBlob256 / NewBlob512 construct an empty BlobHandle at the given width with the matching itb.Blob{N} attached. The caller populates the slots via BlobSetKey / BlobSetComponents / BlobSetMACKey / BlobSetMACName before calling BlobExport / BlobExport3, or feeds a JSON blob through BlobImport / BlobImport3 to populate the slots from a prior Export.

func NewBlob256 

func NewBlob256() (id BlobHandleID, st Status)

func NewBlob512 

func NewBlob512() (id BlobHandleID, st Status)

func NewEasy 

func NewEasy(primitive string, keyBits int, macName string, mode int) (id EasyHandleID, st Status)

NewEasy builds a fresh easy.Encryptor handle for the given primitive / key_bits / MAC / mode combination. Empty primitive ("") and keyBits == 0 select the package defaults ("areion512" / 1024) on the easy side; empty macName ("") selects "kmac256". Mode must be 1 (Single Ouroboros) or 3 (Triple Ouroboros).

The deferred recoverEasyPanic translates any easy-side panic (unknown primitive, invalid key_bits, crypto/rand failure during PRF / seed / MAC key generation) into a clean FFI Status code rather than tearing down the host process.

func NewEasyMixed 

func NewEasyMixed(primN, primD, primS, primL string, keyBits int, macName string) (id EasyHandleID, st Status)

NewEasyMixed builds a Single-Ouroboros easy.Encryptor with per-slot PRF primitive selection across the noise / data / start trio plus an optional dedicated lockSeed. Surfaces easy.NewMixed across the FFI boundary; mirrors NewEasy's panic-to-Status recovery for unknown primitive / invalid key_bits / mixed-width / crypto/rand failure.

Empty primL signals "no dedicated lockSeed" (3-slot encryptor). Non-empty primL allocates a 4th slot under that primitive and auto-couples BitSoup + LockSoup on the on-direction, matching easy.NewMixed's constructor contract.

func NewEasyMixed3 

func NewEasyMixed3(primN, primD1, primD2, primD3, primS1, primS2, primS3, primL string, keyBits int, macName string) (id EasyHandleID, st Status)

NewEasyMixed3 is the Triple-Ouroboros counterpart of NewEasyMixed — accepts 7 per-slot primitive names (noise + 3 data + 3 start) plus the optional dedicated lockSeed primitive. See NewEasyMixed for the construction contract.

func NewMAC 

func NewMAC(name string, key []byte) (id MACHandleID, st Status)

NewMAC builds a fresh MAC handle keyed by key for the named primitive (one of "kmac256", "hmac-sha256", "hmac-blake3"). The resulting closure is rooted behind a cgo.Handle and exposed to the C side as an opaque MACHandleID.

The deferred recoverPanic translates any panic raised inside the primitive constructor (e.g. an internal blake3 / sha3 invariant violation) into StatusInternal rather than letting it cross the cgo boundary.

func NewSeed 

func NewSeed(hashName string, keyBits int) (id HandleID, st Status)

NewSeed builds a fresh seed for hashName at the requested ITB key width (512..2048, multiple of the primitive's native hash width). The native hash width is looked up in hashes.Registry; the resulting Seed{128|256|512} is rooted behind a cgo.Handle and exposed as an opaque HandleID.

The factory invokes the named hash primitive's WithKey-less constructor, which calls crypto/rand.Read to materialise a fresh fixed key. crypto/rand failures (chrooted /dev/urandom etc.) are rare but possible; the deferred recoverPanic translates them into StatusInternal rather than letting a panic cross the cgo boundary.

func NewSeedFromComponents 

func NewSeedFromComponents(hashName string, components []uint64, hashKey []byte) (id HandleID, st Status)

NewSeedFromComponents builds a seed for hashName from caller- supplied uint64 components (deterministic counterpart of NewSeed which generates the components from crypto/rand). The hashKey argument is optional — pass an empty slice for a CSPRNG-generated hash key (the random-key path), or a slice of the primitive's native fixed-key length for the persistence-restore path.

Component count must be in [8, MaxKeyBits/64] and a multiple of 8. hashKey, when non-empty, must be exactly the primitive's native key size (16 for aescmac, 32 for areion256/blake2{s,b256}/blake3/ chacha20, 64 for areion512/blake2b512). hashKey is ignored for "siphash24" (must be empty).

The resulting handle is rooted behind a cgo.Handle; SeedHashKey returns the fixed key in use (the supplied one if hashKey was non-empty, otherwise the freshly generated one).

func NewUnwrapStreamReader 

func NewUnwrapStreamReader(name string, key, wireNonce []byte) (id WrapStreamHandleID, st Status)

NewUnwrapStreamReader builds a handle whose Update calls reverse the outer keystream emitted by a matching NewWrapStreamWriter. The caller passes the leading nonce bytes from the wire as wireNonce; subsequent Update calls XOR caller-supplied ciphertext back to plaintext under the keystream advancing from counter zero.

wireNonce length must equal NonceSize(name); a shorter or longer slice returns StatusBadInput.

func NewWrapStreamWriter 

func NewWrapStreamWriter(name string, key, outNonce []byte) (id WrapStreamHandleID, n int, st Status)

NewWrapStreamWriter draws a fresh nonce, builds the outer keystream under (name, key, nonce), and returns a handle whose Update calls XOR caller bytes against the keystream. The nonce is written into outNonce so the caller can emit it once at stream start (the typical wire layout is `nonce || updates...`).

outNonce capacity must be at least NonceSize(name). On success the handle is rooted behind a cgo.Handle and exposed as an opaque uintptr. On StatusBufferTooSmall the required nonce capacity is reported via the same outNonce length convention as WrapInPlace — the caller resizes outNonce and retries.

The deferred recoverPanic translates any keystream-construction panic (crypto/rand failure, cipher.NewCTR initialisation failure) into StatusInternal rather than crossing the cgo boundary.

Types

type BlobHandle 

type BlobHandle struct {
	// contains filtered or unexported fields
}

BlobHandle wraps a single *itb.Blob{128,256,512} behind an opaque uintptr crossing the cgo boundary. The width discriminator pins the struct to one of the three width-specific containers; only the matching pointer is non-nil for any given handle. The FFI layer pins the value via runtime/cgo.Handle so it survives across the C boundary without leaking the internal type.

Mirrors the SeedHandle pattern in handles.go — same width tag, same three-pointer layout — but holds blob containers rather than seeds. Mode (1 = Single, 3 = Triple) is meta state on the underlying itb.Blob{N}.Mode field; Import / Import3 update it from the parsed blob and Export / Export3 read the explicitly-targeted slots without consulting it.

type BlobHandleID 

type BlobHandleID uintptr

BlobHandleID is the opaque uintptr passed across the C ABI as a blob reference. Internally a runtime/cgo.Handle that maps back to a *BlobHandle on the Go heap.

type EasyHandle 

type EasyHandle struct {
	// contains filtered or unexported fields
}

EasyHandle wraps a single *easy.Encryptor behind an opaque uintptr crossing the cgo boundary. The Encryptor owns its own seed slots, MAC closure, and per-instance Config snapshot — the FFI layer just pins it via runtime/cgo.Handle so the value survives across the C boundary without leaking the internal type.

Mirrors the SeedHandle / MACHandle pattern in handles.go and macs.go; the only structural difference is that one EasyHandle replaces what used to be three (or seven) separate seed handles plus one MAC handle.

type EasyHandleID 

type EasyHandleID uintptr

EasyHandleID is the opaque uintptr passed across the C ABI as an Encryptor reference. Internally a runtime/cgo.Handle that maps back to an *EasyHandle on the Go heap.

type HandleID 

type HandleID uintptr

HandleID is the opaque uintptr passed across the C ABI as a seed reference. Internally a runtime/cgo.Handle that maps back to a *SeedHandle on the Go heap.

type MACHandle 

type MACHandle struct {
	// contains filtered or unexported fields
}

MACHandle wraps a pre-keyed itb.MACFunc behind an opaque uintptr crossing the cgo boundary, mirroring the SeedHandle design. The closure carries pre-keyed primitive state (cSHAKE256 absorb-state, pooled hmac.Hash, blake3.Hasher template) so per-call invocation has no key-derivation cost.

type MACHandleID 

type MACHandleID uintptr

MACHandleID is the opaque uintptr passed across the C ABI as a MAC reference. Internally a runtime/cgo.Handle that maps back to a *MACHandle on the Go heap.

type SeedHandle 

type SeedHandle struct {
	// contains filtered or unexported fields
}

SeedHandle is the FFI-side handle representing one ITB seed. It erases the underlying Seed{128|256|512} type behind a uintptr that is stable across the cgo boundary, while keeping the actual *Seed pointer rooted on the Go heap (cgo.Handle pins the value against GC). Three handles together — noise, data, start — feed Encrypt and Decrypt; the underlying width must match across the trio.

type Status 

type Status int

Status is the integer error code returned by every capi entry point. Mirrors the ITB_OK / ITB_ERR_* constants exposed through the C ABI surface and must stay numerically stable across releases. 

const (
	StatusOK             Status = 0
	StatusBadHash        Status = 1
	StatusBadKeyBits     Status = 2
	StatusBadHandle      Status = 3
	StatusBadInput       Status = 4
	StatusBufferTooSmall Status = 5
	StatusEncryptFailed  Status = 6
	StatusDecryptFailed  Status = 7
	StatusSeedWidthMix   Status = 8
	StatusBadMAC         Status = 9
	StatusMACFailure     Status = 10

	// Easy encryptor (itb/easy sub-package) sentinel codes. The
	// numeric block 11..18 is dedicated to the Encryptor surface so
	// the lower codes 0..10 remain reserved for the low-level
	// Encrypt / Decrypt path. Bindings translate each code into a
	// distinct exception class (or sentinel attribute) on the
	// language-side wrapper.
	StatusEasyClosed               Status = 11
	StatusEasyMalformed            Status = 12
	StatusEasyVersionTooNew        Status = 13
	StatusEasyUnknownPrimitive     Status = 14
	StatusEasyUnknownMAC           Status = 15
	StatusEasyBadKeyBits           Status = 16
	StatusEasyMismatch             Status = 17
	StatusEasyLockSeedAfterEncrypt Status = 18

	// Native Blob (itb.Blob128 / Blob256 / Blob512) sentinel codes.
	// The numeric block 19..22 is dedicated to the low-level state-
	// blob surface so the lower codes 0..18 remain reserved for
	// the seed-handle / Encrypt / Decrypt / Encryptor paths.
	// Bindings translate each code into a distinct exception class
	// on the language-side wrapper.
	StatusBlobModeMismatch  Status = 19
	StatusBlobMalformed     Status = 20
	StatusBlobVersionTooNew Status = 21
	StatusBlobTooManyOpts   Status = 22

	// Streaming AEAD end-of-stream signals raised by the binding-side
	// stream-loop helpers when the input transcript is malformed at
	// the terminator boundary. Returned by the binding's wrapper, not
	// by the per-chunk ABI handlers.
	StatusStreamTruncated  Status = 23
	StatusStreamAfterFinal Status = 24

	StatusInternal Status = 99
)

func AttachLockSeed 

func AttachLockSeed(noise, lock HandleID) (st Status)

AttachLockSeed wires a dedicated lockSeed handle onto an existing noise seed handle, exposing the low-level [Seed128.AttachLockSeed] / [Seed256.AttachLockSeed] / [Seed512.AttachLockSeed] mutators across the C ABI. The per-chunk PRF closure for the bit-permutation overlay captures BOTH the lockSeed's Components AND its Hash function, so the lockSeed primitive may legitimately differ from the noise seed primitive within the same native width — keying-material isolation plus algorithm diversity for defence-in-depth on the overlay path.

The two handles must share the same native hash width; mixing widths returns StatusSeedWidthMix. The underlying seed mutator panics in three documented misuse cases — self-attach, component- array aliasing, and post-Encrypt switching — plus the bit-soup- builder ErrLockSeedOverlayOff guard fires later on Encrypt time if neither BitSoup nor LockSoup is engaged on the active dispatch path. The deferred recover here translates the three attach-time panics to StatusBadInput; the overlay-off guard panics elsewhere (build*PRF) and is not visible from this entry point.

The lockSeed handle remains owned by the caller — AttachLockSeed only records the pointer on the noise seed; releasing the lockSeed via FreeSeed before the noise seed is used invalidates the dedicated derivation path. The standard pairing is: keep lockSeed alive for the lifetime of the noise seed.

Bindings exposing AttachLockSeed must engage the bit-permutation overlay (set_bit_soup(1) or set_lock_soup(1) at the global setter level for the legacy entry points; cfg.LockSoup / cfg.BitSoup for the Cfg variants) before the first Encrypt call, otherwise the overlay-off guard inside the build-PRF closure raises itb.ErrLockSeedOverlayOff.

func BlobExport 

func BlobExport(id BlobHandleID, optsBitmask int, out []byte) (n int, st Status)

BlobExport serialises the handle's Single-Ouroboros state (3 seeds + 3 hash keys, plus optional dedicated lockSeed and MAC) into a JSON blob. Mirrors itb.Blob{N}.Export — the bitmask flags (BlobOptLockSeed / BlobOptMAC) opt the matching sections in.

Caller-allocated-buffer convention: pass len(out) == 0 to probe for the required size, then resize and retry.

Mode on the underlying blob is stamped to 1 (Single) on success, matching the Import path so post-Export inspection via BlobMode reports the correct value. Bits in optsBitmask outside the documented BlobOptLockSeed / BlobOptMAC range are rejected with StatusBadInput before any serialisation runs — future- incompatibility guard against bindings setting an unknown bit expecting an option that doesn't exist yet.

func BlobExport3 

func BlobExport3(id BlobHandleID, optsBitmask int, out []byte) (n int, st Status)

BlobExport3 serialises the handle's Triple-Ouroboros state (1 noise + 3 data + 3 start seeds + 7 hash keys, plus optional lockSeed and MAC). Mirrors itb.Blob{N}.Export3. Bits outside the documented BlobOptLockSeed / BlobOptMAC range are rejected with StatusBadInput; Mode on the underlying blob is stamped to 3 on success.

func BlobGetComponents 

func BlobGetComponents(id BlobHandleID, slot int, out []uint64) (n int, st Status)

BlobGetComponents copies the seed components from the requested slot into out and returns the number of uint64 elements that were available on the handle. Same caller-allocated-buffer probe pattern as BlobGetKey: len(out) == 0 returns the required capacity in n with st == StatusBufferTooSmall.

An unset slot returns (0, StatusOK) — distinguishable from the buffer-too-small case by the status code, not by n alone.

func BlobGetKey 

func BlobGetKey(id BlobHandleID, slot int, out []byte) (n int, st Status)

BlobGetKey copies the hash key bytes from the requested slot into out and returns the number of bytes that were available on the handle. The caller-allocated-buffer convention applies: a probe pass with len(out) == 0 returns the required capacity in n with st == StatusBufferTooSmall, so bindings can size their buffer in two phases.

For the 128-bit width the slot may carry zero bytes (siphash24 path) — n == 0 then signals "no key", not "buffer too small". The discriminator is len(out) on the call: if out is nil and the slot is empty, returns (0, StatusOK).

func BlobGetMACKey 

func BlobGetMACKey(id BlobHandleID, out []byte) (n int, st Status)

BlobGetMACKey copies the MAC key from the handle into out using the standard caller-allocated-buffer probe pattern.

func BlobGetMACName 

func BlobGetMACName(id BlobHandleID) (name string, st Status)

BlobGetMACName returns the MAC name from the handle, or "" if no MAC is associated with this blob.

func BlobImport 

func BlobImport(id BlobHandleID, data []byte) (st Status)

BlobImport parses a Single-Ouroboros JSON blob produced by a prior Export call (Go-side or FFI-side), populates the handle's slots, and applies the captured globals via SetNonceBits / SetBarrierFill / SetBitSoup / SetLockSoup. Mirrors itb.Blob{N}.Import — same transactional semantics: on error the pre-Import state is preserved.

Returns StatusBlobModeMismatch when the blob is mode=3 (call BlobImport3 instead), StatusBlobMalformed on parse / shape failure, StatusBlobVersionTooNew on a version field higher than this build supports.

func BlobImport3 

func BlobImport3(id BlobHandleID, data []byte) (st Status)

BlobImport3 is the Triple-Ouroboros counterpart of BlobImport. Same error contract; mirrors itb.Blob{N}.Import3.

func BlobMode 

func BlobMode(id BlobHandleID) (int, Status)

BlobMode returns the blob's mode field (0 = unset, 1 = Single, 3 = Triple). Set to 1 / 3 by the most recent Import / Import3 call, or by any successful Export / Export3 call. A freshly constructed handle has Mode == 0 until the caller drives one of these state transitions.

func BlobSetComponents 

func BlobSetComponents(id BlobHandleID, slot int, comps []uint64) (st Status)

BlobSetComponents stores the seed components for the requested slot on the blob handle. The components slice is copied into the handle (the underlying *Seed{N} is constructed if it does not exist yet on this slot). Component count must satisfy the same 8..MaxKeyBits/64 multiple-of-8 invariants as NewSeedFromComponents — the validation is deferred to Export / Import where blob.go applies it consistently.

func BlobSetKey 

func BlobSetKey(id BlobHandleID, slot int, key []byte) (st Status)

BlobSetKey stores the hash key bytes for the requested slot on the blob handle. The slot is one of the BlobSlot* constants; the bytes must match the width-native fixed-key length for the 256 / 512 widths (32 / 64 bytes), or be empty / 16 bytes for the 128 width (siphash24 has no internal key, aescmac is 16 bytes).

The key is copied into the handle, so the caller may release the source buffer immediately. Subsequent BlobGetKey calls on the same slot return a fresh copy of the stored bytes.

Returns StatusBadInput on an unknown slot or wrong key length. Subsequent BlobExport / BlobExport3 calls read from the slots the caller populated; unset slots are treated as zero / empty at Export time.

func BlobSetMACKey 

func BlobSetMACKey(id BlobHandleID, key []byte) (st Status)

BlobSetMACKey stores the optional MAC key bytes on the handle. The bytes are copied; pass an empty slice to clear a previously-set key. BlobExport / BlobExport3 only emits the MAC section when the caller supplies BlobOptMAC in the option bitmask AND the MAC key on the handle is non-empty.

func BlobSetMACName 

func BlobSetMACName(id BlobHandleID, name string) (st Status)

BlobSetMACName stores the optional MAC name on the handle (e.g. "kmac256", "hmac-blake3"). Pass an empty string to clear a previously-set name. Like the MAC key, the name is only emitted in the blob when BlobOptMAC is supplied to BlobExport / BlobExport3 AND the name is non-empty.

func BlobWidth 

func BlobWidth(id BlobHandleID) (hashes.Width, Status)

BlobWidth returns the native hash width of an existing blob handle (128, 256, or 512). Bindings call this to size their downstream buffers — e.g. a 32-byte vs 64-byte hash key buffer for BlobGetKey.

func Decrypt 

func Decrypt(noise, data, start HandleID, ciphertext, out []byte) (n int, st Status)

Decrypt is the inverse of Encrypt. Same caller-allocated-buffer convention; outLen receives the recovered plaintext length on success or the required capacity on StatusBufferTooSmall.

func Decrypt3 

func Decrypt3(
	noise, data1, data2, data3, start1, start2, start3 HandleID,
	ciphertext, out []byte,
) (n int, st Status)

Decrypt3 is the inverse of Encrypt3. Same convention.

func DecryptAuth 

func DecryptAuth(
	noise, data, start HandleID, mac MACHandleID,
	ciphertext, out []byte,
) (n int, st Status)

DecryptAuth is the inverse of EncryptAuth. On MAC verification failure (tampered ciphertext, wrong key, mismatched MAC primitive) returns StatusMACFailure; on structural / dispatch errors returns the matching status. The MAC-failure path is distinguished from generic decrypt failure to give bindings a precise error code for integrity-violation reporting.

func DecryptAuth3 

func DecryptAuth3(
	noise, data1, data2, data3, start1, start2, start3 HandleID,
	mac MACHandleID, ciphertext, out []byte,
) (n int, st Status)

DecryptAuth3 is the inverse of EncryptAuth3.

func DecryptStreamAuth 

func DecryptStreamAuth(
	noise, data, start HandleID, mac MACHandleID,
	ciphertext, out []byte,
	streamID [32]byte, cumulativePixelOffset uint64,
) (n int, finalFlag bool, st Status)

DecryptStreamAuth is the inverse of EncryptStreamAuth. The recovered finalFlag is reported back through the returned bool. On MAC verification failure (tampered ciphertext, wrong key, mismatched streamID, mismatched cumulativePixelOffset, mismatched primitive) returns StatusMACFailure; on structural / dispatch errors returns the matching status.

func DecryptStreamAuth3 

func DecryptStreamAuth3(
	noise, data1, data2, data3, start1, start2, start3 HandleID,
	mac MACHandleID, ciphertext, out []byte,
	streamID [32]byte, cumulativePixelOffset uint64,
) (n int, finalFlag bool, st Status)

DecryptStreamAuth3 is the inverse of EncryptStreamAuth3.

func EasyClose 

func EasyClose(id EasyHandleID) (st Status)

EasyClose zeroes the encryptor's PRF keys, MAC key, and seed components and marks the instance closed. Subsequent method calls on the same handle return StatusEasyClosed.

Idempotent — multiple Close calls return StatusOK without panic. The handle itself remains valid (Close does not delete the cgo.Handle); use FreeEasy to release the handle slot.

func EasyDecrypt 

func EasyDecrypt(id EasyHandleID, ciphertext, out []byte) (n int, st Status)

EasyDecrypt is the inverse of EasyEncrypt. Same buffer convention. Wrong-seed input on non-authenticated mode produces random-looking plaintext rather than a status; the easy package matches the underlying itb.Decrypt* contract — non-Auth mode has no failure signal by design. For integrity-protected decryption use EasyDecryptAuth, which classifies the MAC failure as a distinct StatusMACFailure.

func EasyDecryptAuth 

func EasyDecryptAuth(id EasyHandleID, ciphertext, out []byte) (n int, st Status)

EasyDecryptAuth verifies and decrypts an authenticated ciphertext produced by EasyEncryptAuth. On MAC verification failure (tampered ciphertext, wrong MAC key, mismatched MAC primitive across sender and receiver) returns StatusMACFailure; structural / dispatch errors return StatusDecryptFailed. The MAC-failure path is distinguished so bindings can present it as a typed integrity violation rather than generic decrypt failure.

func EasyDecryptStreamAuth 

func EasyDecryptStreamAuth(
	id EasyHandleID, ciphertext, out []byte,
	streamID [32]byte, cumulativePixelOffset uint64,
) (n int, finalFlag bool, st Status)

EasyDecryptStreamAuth verifies and decrypts a single Streaming AEAD chunk produced by EasyEncryptStreamAuth. The recovered finalFlag is reported back through the returned bool. On MAC verification failure (tampered ciphertext, wrong MAC key, mismatched streamID, mismatched cumulativePixelOffset, mismatched MAC primitive) returns StatusMACFailure; structural / dispatch errors return StatusDecryptFailed.

func EasyEncrypt 

func EasyEncrypt(id EasyHandleID, plaintext, out []byte) (n int, st Status)

EasyEncrypt encrypts plaintext through the encryptor handle. Plain mode — no MAC tag attached; for authenticated encryption use EasyEncryptAuth. Same caller-allocated-buffer convention as the low-level Encrypt: out is the destination buffer, the returned n reports bytes written on success or required capacity on StatusBufferTooSmall.

The encryptor's per-instance Config snapshot (BitSoup, LockSoup, LockSeed, NonceBits, BarrierFill, ChunkSize) is consumed automatically — process-wide setters do not affect a constructed encryptor, which is the whole point of the easy package.

func EasyEncryptAuth 

func EasyEncryptAuth(id EasyHandleID, plaintext, out []byte) (n int, st Status)

EasyEncryptAuth encrypts plaintext and attaches a MAC tag using the encryptor's bound MAC closure. Same buffer convention as EasyEncrypt.

func EasyEncryptStreamAuth 

func EasyEncryptStreamAuth(
	id EasyHandleID, plaintext, out []byte,
	streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool,
) (n int, st Status)

EasyEncryptStreamAuth encrypts a single Streaming AEAD chunk through the encryptor handle, threading the streaming-binding components (streamID, cumulativePixelOffset, finalFlag) into the per-chunk MAC input. Same caller-allocated-buffer convention as EasyEncryptAuth. The Encryptor's bound MAC closure is reused for every chunk of a stream; the caller drives the loop, supplying a CSPRNG-fresh streamID once at stream start, the running cumulativePixelOffset per chunk, and finalFlag = true on the terminating chunk only.

func EasyExport 

func EasyExport(id EasyHandleID, out []byte) (n int, st Status)

EasyExport serialises the encryptor's full state (PRF keys, seed components, MAC key, dedicated lockSeed material when active) as a JSON blob into the caller-allocated buffer. Same caller-allocated- buffer convention as Encrypt / Decrypt: the returned n carries the bytes written on success or the required capacity on StatusBufferTooSmall, so callers can probe with a zero-capacity pass to discover the size, then resize and retry.

The blob shape is documented in easy/state.go (stateBlobV1). v1 carries the structural state (primitive / key_bits / mode / mac / seeds / prf_keys / mac_key / lock_seed); per-instance configuration knobs (NonceBits, BarrierFill, BitSoup, LockSoup, ChunkSize) are not serialised — both sides communicate them via deployment config.

func EasyHasPRFKeys 

func EasyHasPRFKeys(id EasyHandleID) (v int, st Status)

EasyHasPRFKeys returns 1 when the encryptor's primitive uses fixed PRF keys per seed slot (every shipped primitive except siphash24), 0 otherwise. Bindings consult this before iterating slot indices against EasyPRFKey, mirroring the easy.Encryptor.PRFKeys() == nil check on the Go side.

func EasyHeaderSize 

func EasyHeaderSize(id EasyHandleID) (v int, st Status)

EasyHeaderSize forwards to Encryptor.HeaderSize — the per-instance ciphertext-chunk header size in bytes (nonce + 2-byte width + 2-byte height). Tracks the encryptor's own NonceBits, NOT the process-wide HeaderSize() reading.

func EasyImport 

func EasyImport(id EasyHandleID, blob []byte) (st Status)

EasyImport replaces the encryptor's PRF keys, seed components, MAC key, and (optionally) dedicated lockSeed material with the values carried in a JSON blob produced by a prior EasyExport call. Returns StatusOK on success or one of the StatusEasy* / StatusInternal codes on failure; on error the encryptor's pre-Import state is unchanged (Encryptor.Import is transactional on the easy side).

The state blob carries the authoritative LockSeed setting — a blob with lock_seed:true elevates a default-LockSeed=0 receiver to LockSeed=1, and a blob without lock_seed demotes a pre-Import LockSeed=1 receiver to LockSeed=0 (the receiver's pre-Import dedicated-lockSeed material is zeroed and discarded). The four other configuration dimensions (primitive, key_bits, mode, mac) are rejected on mismatch via StatusEasyMismatch — the receiver's hash / MAC factories were bound at New / New3 time and cannot be rewired by Import. The offending field is captured in lastMismatchField for retrieval via EasyLastMismatchField.

func EasyIsMixed 

func EasyIsMixed(id EasyHandleID) (v int, st Status)

EasyIsMixed returns 1 if the encryptor was constructed via NewEasyMixed / NewEasyMixed3 (per-slot primitive selection), 0 if it was constructed via NewEasy (single primitive across all slots).

func EasyKeyBits 

func EasyKeyBits(id EasyHandleID) (v int, st Status)

EasyKeyBits returns the per-seed key width in bits — one of 512, 1024, 2048.

func EasyMACKey 

func EasyMACKey(id EasyHandleID) (out []byte, st Status)

EasyMACKey returns a defensive copy of the encryptor's bound MAC fixed key. Save these bytes alongside the seed components for cross-process restore via the EasyExport / EasyImport JSON path.

func EasyMACName 

func EasyMACName(id EasyHandleID) (name string, st Status)

EasyMACName returns the canonical MAC primitive name the encryptor was constructed with.

func EasyMode 

func EasyMode(id EasyHandleID) (v int, st Status)

EasyMode returns 1 (Single Ouroboros, 3 seeds) or 3 (Triple Ouroboros, 7 seeds). The integer encoding mirrors the Encrypt / Encrypt3x distinction at the low-level API.

func EasyNonceBits 

func EasyNonceBits(id EasyHandleID) (v int, st Status)

EasyNonceBits forwards to Encryptor.NonceBits — the per-instance nonce size in bits (128 / 256 / 512). Falls back to the global itb.GetNonceBits reading when no per-instance override has been installed via EasySetNonceBits.

func EasyPRFKey 

func EasyPRFKey(id EasyHandleID, slot int) (out []byte, st Status)

EasyPRFKey returns the fixed PRF key bytes for one seed slot (defensive copy). Returns StatusBadInput when the primitive has no fixed PRF keys (siphash24 — caller should consult EasyHasPRFKeys first) or when slot is out of range.

func EasyParseChunkLen 

func EasyParseChunkLen(id EasyHandleID, header []byte) (n int, st Status)

EasyParseChunkLen forwards to Encryptor.ParseChunkLen — the per-instance chunk-length parser. Reports the total wire length of one ciphertext chunk after inspecting only the fixed-size header at the front of the supplied buffer. Returns StatusBadInput on too-short buffer, zero dimensions, or width × height overflow.

func EasyPeekConfig 

func EasyPeekConfig(blob []byte) (primitive string, keyBits int, mode int, mac string, st Status)

EasyPeekConfig parses a state blob's metadata (primitive, key_bits, mode, mac) without performing full validation, allowing a caller to inspect a saved blob before constructing a matching encryptor.

Returns StatusOK with the parsed fields on success; StatusEasyMalformed (and on bindings the LastError text) on JSON parse failure / kind mismatch / too-new version / unknown mode value. The deferred recover translates the easy package's panic policy (PeekConfig panics on malformed input) into a Status return.

func EasyPrimitive 

func EasyPrimitive(id EasyHandleID) (name string, st Status)

EasyPrimitive returns the canonical hash primitive name the encryptor was constructed with. Mirrors the read-only Primitive field on the Go struct. Encryptors built via NewEasyMixed / NewEasyMixed3 return the literal "mixed" — bindings then enumerate per-slot primitives via EasyPrimitiveAt.

func EasyPrimitiveAt 

func EasyPrimitiveAt(id EasyHandleID, slot int) (name string, st Status)

EasyPrimitiveAt returns the canonical hash primitive name bound to the given seed slot index. For single-primitive encryptors every slot returns the same name EasyPrimitive reports; for mixed-mode encryptors each slot can carry an independently chosen primitive within the same native hash width.

Slot ordering is canonical: 0 = noiseSeed, then dataSeed{,1..3}, then startSeed{,1..3}; the optional dedicated lockSeed sits at the trailing slot when present. Out-of-range slots return the empty string with StatusOK; bindings can also read EasyIsMixed to detect whether per-slot enumeration is meaningful.

func EasySeedComponents 

func EasySeedComponents(id EasyHandleID, slot int) (out []uint64, st Status)

EasySeedComponents returns the uint64 components for one seed slot (defensive copy). Slot index follows the canonical ordering: Single = [noise, data, start]; Triple = [noise, data1, data2, data3, start1, start2, start3]; the dedicated lockSeed slot is appended at the end (index 3 / 7) when LockSeed is active.

Save these alongside EasyPRFKey output for cross-process restore via Encryptor.Import (the FFI-side path goes through EasyExport / EasyImport instead, which packs all material into one JSON blob).

func EasySeedCount 

func EasySeedCount(id EasyHandleID) (n int, st Status)

EasySeedCount returns the number of seed slots held by the encryptor: 3 (Single without LockSeed), 4 (Single with LockSeed), 7 (Triple without LockSeed), 8 (Triple with LockSeed). Used by bindings to determine the valid range for the slot index passed to EasySeedComponents / EasyPRFKey.

func EasySetBarrierFill 

func EasySetBarrierFill(id EasyHandleID, n int) (st Status)

EasySetBarrierFill forwards to Encryptor.SetBarrierFill. Valid values: 1, 2, 4, 8, 16, 32. Any other value yields StatusBadInput.

func EasySetBitSoup 

func EasySetBitSoup(id EasyHandleID, mode int) (st Status)

EasySetBitSoup forwards to Encryptor.SetBitSoup. 0 = byte-level split (default); non-zero = bit-level Bit Soup split.

func EasySetChunkSize 

func EasySetChunkSize(id EasyHandleID, n int) (st Status)

EasySetChunkSize forwards to Encryptor.SetChunkSize. 0 selects the auto-detect heuristic from itb.ChunkSize.

func EasySetLockSeed 

func EasySetLockSeed(id EasyHandleID, mode int) (st Status)

EasySetLockSeed forwards to Encryptor.SetLockSeed. Valid values: 0 (off), 1 (on). Any other value yields StatusBadInput. Calling this method after the encryptor has produced its first ciphertext yields StatusEasyLockSeedAfterEncrypt — the bit-permutation derivation path cannot change mid-session without breaking decryptability of pre-switch ciphertext.

func EasySetLockSoup 

func EasySetLockSoup(id EasyHandleID, mode int) (st Status)

EasySetLockSoup forwards to Encryptor.SetLockSoup. Non-zero values auto-couple BitSoup=1 on the encryptor (mirroring the global itb.SetLockSoup contract).

func EasySetNonceBits 

func EasySetNonceBits(id EasyHandleID, n int) (st Status)

EasySetNonceBits forwards to Encryptor.SetNonceBits. Valid values: 128, 256, 512. Any other value yields StatusBadInput.

func Encrypt 

func Encrypt(noise, data, start HandleID, plaintext, out []byte) (n int, st Status)

Encrypt encrypts plaintext using the (noise, data, start) seed trio. All three handles must wrap seeds of the same native hash width; otherwise StatusSeedWidthMix is returned.

out is caller-allocated. On success the encrypted payload is written to out[:n] and n is reported back through outLen. If cap(out) is too small, StatusBufferTooSmall is returned and outLen is set to the size that would have been written so the caller can resize and retry.

func Encrypt3 

func Encrypt3(
	noise, data1, data2, data3, start1, start2, start3 HandleID,
	plaintext, out []byte,
) (n int, st Status)

Encrypt3 is the Triple Ouroboros counterpart of Encrypt. It takes 7 seed handles (1 shared noise + 3 data + 3 start) and produces one ciphertext that splits the plaintext into three interleaved snake payloads. The on-wire format is the same shape as the non-Triple ciphertext (same nonce + dimensions header + raw container) — only the internal split / interleave differs.

All 7 handles must share the same native hash width and must be pairwise distinct (the underlying itb.Encrypt3x* enforces the seven-seed isolation invariant). Same caller-allocated-buffer convention as Encrypt: returned n carries the bytes written on success or the required capacity on StatusBufferTooSmall.

func EncryptAuth 

func EncryptAuth(
	noise, data, start HandleID, mac MACHandleID,
	plaintext, out []byte,
) (n int, st Status)

EncryptAuth is the Authenticated counterpart of Encrypt: it computes a MAC tag over the encrypted payload (under the barrier but inside the container, mirroring ITB's MAC-Inside-Encrypt construction) and embeds the tag into the ciphertext alongside the data. Same caller-allocated-buffer convention as Encrypt; returned n is the bytes written on success or required capacity on StatusBufferTooSmall.

func EncryptAuth3 

func EncryptAuth3(
	noise, data1, data2, data3, start1, start2, start3 HandleID,
	mac MACHandleID, plaintext, out []byte,
) (n int, st Status)

EncryptAuth3 is the seven-seed Triple Ouroboros + Auth variant. Same convention as Encrypt3 plus a MAC handle. All seven seeds must share the same native hash width.

func EncryptStreamAuth 

func EncryptStreamAuth(
	noise, data, start HandleID, mac MACHandleID,
	plaintext, out []byte,
	streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool,
) (n int, st Status)

EncryptStreamAuth is the Streaming AEAD counterpart of EncryptAuth: the per-chunk MAC is computed over the encoded payload extended with the streaming-binding components — a 32-byte streamID, the running cumulativePixelOffset, and the finalFlag byte. Same caller-allocated buffer convention as EncryptAuth; returned n is bytes written on success or required capacity on StatusBufferTooSmall. The streaming binding additions are passed through to the underlying Go-core EncryptStreamAuthenticated{N} family by hash-width dispatch.

func EncryptStreamAuth3 

func EncryptStreamAuth3(
	noise, data1, data2, data3, start1, start2, start3 HandleID,
	mac MACHandleID, plaintext, out []byte,
	streamID [32]byte, cumulativePixelOffset uint64, finalFlag bool,
) (n int, st Status)

EncryptStreamAuth3 is the seven-seed Triple Ouroboros + Streaming AEAD variant. Same convention as EncryptStreamAuth plus the seven-seed shape from EncryptAuth3. All seven seeds must share the same native hash width.

func FreeBlob 

func FreeBlob(id BlobHandleID) (st Status)

FreeBlob releases the cgo.Handle backing a BlobHandleID. Wipes every key-material slot (per-slot hash keys, the seed Components arrays for every populated slot, the optional MAC key) before the cgo.Handle.Delete call so the discarded state does not linger in memory until the GC reclaims it. The wipe is best-effort — fixed-size [32]byte / [64]byte arrays embedded in the Blob{N} struct can be cleared in place; the [Seed{N}] pointers are nil-ed out after their Components slices are cleared so the underlying seed structs become eligible for GC.

The deferred recover translates a stale / zero handle panic from cgo.Handle.Delete into StatusBadHandle.

The blob structs do not own any resource that requires a Close step (no goroutines, no OS handles), so unlike FreeEasy this is a pure wipe + Delete with no separate close.

Threading constraint mirrors FreeSeed: the wipe runs in-place on the live Blob{N} struct, so calling FreeBlob concurrently with an in-flight Export / Import / Get / Set on the same handle is a caller error and produces wrong output (cleared key bytes, zero components) rather than a late panic. Bindings must serialise FreeBlob against every concurrent use of the handle.

func FreeEasy 

func FreeEasy(id EasyHandleID) (st Status)

FreeEasy releases the cgo.Handle backing an EasyHandleID after calling Close on the underlying encryptor (which zeroes PRF keys, MAC key, and seed components before releasing them to GC). The double-zero — Close from FreeEasy AND the explicit ITB_Easy_Close FFI entry point — is intentional: bindings that forget the explicit Close still get key material zeroed when they release the handle, while bindings that DO call Close hit Close's idempotent fast path here.

The deferred recover translates any panic from cgo.Handle.Delete (stale / zero handle) into StatusBadHandle.

func FreeMAC 

func FreeMAC(id MACHandleID) (st Status)

FreeMAC releases a MAC handle. Subsequent uses return StatusBadMAC.

The MAC fixed key is captured opaquely inside the itb.MACFunc closure (cSHAKE256 absorb state, pooled hmac.Hash, blake3.Hasher template) — capi has no public API to wipe the captured bytes before release, so the best-effort here is to nil out the closure reference so the Go GC can reclaim the captured state at the next collection cycle. Callers that need stricter wiping must avoid holding sibling references and arrange for an immediate GC.

func FreeSeed 

func FreeSeed(id HandleID) (st Status)

FreeSeed releases the cgo.Handle, allowing the *Seed to be garbage-collected. The handle must not be used after this call; repeat calls return StatusBadHandle (cgo.Handle.Delete panics on a stale handle, the deferred recover translates that into a clean FFI error code).

The PRF fixed key (hashKey) and the seed Components slice carry caller-sensitive material. Both are wiped before the cgo.Handle.Delete call so the discarded state does not linger in memory until the GC reclaims it. The wipe is best-effort — the underlying *Seed{N}.Hash closure may have captured the same key by value, in which case only the Go-runtime closure release reaches the residual copy.

Threading constraint: the wipe runs in-place on the live Components / hashKey slices. Calling FreeSeed concurrently with an in-flight Encrypt / Decrypt that holds the same handle is a caller error and produces wrong-decrypt rather than a late panic — the sibling thread sees zeroed components mid-derivation and emits garbage. Bindings must serialise FreeSeed against every concurrent use of the handle.

func FreeWrapStream 

func FreeWrapStream(id WrapStreamHandleID) (st Status)

FreeWrapStream releases the cgo.Handle backing a WrapStreamHandleID, allowing the underlying *WrapStreamHandle (and the keystream cipher state it captured) to be reclaimed by the GC. The deferred recover translates a stale / zero handle panic into StatusBadHandle.

The keystream's internal state (cipher.Stream / chacha20.Cipher / sipCTR) is captured opaquely inside the wrapper.Keystream closure — capi has no public API to wipe the captured bytes before release, so the best-effort here is to nil out the closure reference so the GC can reclaim the captured state at the next collection cycle. Callers that need stricter wiping must avoid holding sibling references and arrange for an immediate GC.

func MACName 

func MACName(id MACHandleID) (string, Status)

MACName returns the canonical name a MAC handle was built with.

func MACTagSize 

func MACTagSize(id MACHandleID) (int, Status)

MACTagSize returns the tag size in bytes of an existing MAC handle.

func ParseChunkLen 

func ParseChunkLen(header []byte) (int, Status)

ParseChunkLen reports the total wire size of a chunk after inspecting only the fixed-size header at the front of the buffer.

The header layout is [nonce || width(2) || height(2)] where the nonce length comes from the process-wide configuration (itb.GetNonceBits / 8 bytes). chunk_total = headerSize + width * height * itb.Channels.

Unlike itb.ParseChunkLen, this helper requires only the header bytes to be present — it does not insist that the entire chunk body already sit in the buffer. That is the semantic streaming FFI consumers want: read 20 bytes from disk → ask for chunk_len → read the remaining (chunk_len - 20) bytes → hand the full chunk to Decrypt. The body-length check at decrypt time stays inside the cipher entry points where it belongs.

Returns StatusBadInput when the buffer is shorter than the header, the dimensions are zero / overflow, or the announced pixel count exceeds the container pixel cap.

func SeedComponents 

func SeedComponents(id HandleID) ([]uint64, Status)

SeedComponents returns the seed's underlying key components as a slice of uint64. Length is keyBits/64 (8..32). Counterpart of the caller-supplied components passed to NewSeedFromComponents — save these alongside SeedHashKey for cross-process restore.

func SeedHashKey 

func SeedHashKey(id HandleID) ([]byte, Status)

SeedHashKey returns the fixed key the underlying hash closure is bound to. The bytes returned are the random key NewSeed* / NewSeedFromComponents* generated at construction (or the explicit key the caller supplied, on the persistence-restore path) — save them across processes alongside the seed components for encrypt-today / decrypt-tomorrow flows.

SipHash-2-4 has no internal fixed key (its keying material is the per-call seed components), so the returned slice is empty for "siphash24" — callers can detect this via len(key) == 0 and rely on SeedComponents alone for SipHash persistence.

func SeedHashName 

func SeedHashName(id HandleID) (string, Status)

SeedHashName returns the canonical hash name an existing seed handle was built with.

func SeedWidth 

func SeedWidth(id HandleID) (hashes.Width, Status)

SeedWidth returns the native hash width of an existing seed handle.

func SetBarrierFill 

func SetBarrierFill(n int) (st Status)

SetBarrierFill accepts 1, 2, 4, 8, 16, 32. Any other value yields StatusBadInput; the underlying itb panic is recovered.

func SetBitSoup 

func SetBitSoup(mode int) Status

func SetLockSoup 

func SetLockSoup(mode int) Status

func SetMaxWorkers 

func SetMaxWorkers(n int) Status

func SetNonceBits 

func SetNonceBits(n int) (st Status)

SetNonceBits accepts 128, 256, or 512. Any other value yields StatusBadInput; the underlying itb panic is recovered.

func Unwrap 

func Unwrap(name string, key, wire, out []byte) (n int, st Status)

Unwrap reverses Wrap. The leading nonce is read from wire; the remaining bytes are XOR-decrypted under (key, nonce) into out. Same caller-allocated-buffer convention as Wrap; the recovered payload size is len(wire) - NonceSize(name).

func UnwrapInPlace 

func UnwrapInPlace(name string, key, wire []byte) (n int, st Status)

UnwrapInPlace strips the leading nonce from wire and XORs the remainder in place. wire is MUTATED. Returns the body length (len(wire) - NonceSize(name)) on success.

func Wrap 

func Wrap(name string, key, blob, out []byte) (n int, st Status)

Wrap seals one ITB ciphertext blob under the named outer cipher. The wire form is `nonce || keystream-XOR(blob)` where the nonce is freshly drawn from crypto/rand per call. Same caller- allocated-buffer convention as Encrypt: returned n carries the bytes written on success or the required capacity on StatusBufferTooSmall.

func WrapInPlace 

func WrapInPlace(name string, key, blob, outNonce []byte) (n int, st Status)

WrapInPlace XORs blob in place under a freshly-drawn outer keystream and writes the per-stream nonce into outNonce. The caller is expected to emit nonce || blob to the wire (or carry both fragments separately). blob is MUTATED.

outNonce capacity must be at least NonceSize(name). On success n carries NonceSize(name) (the bytes written into outNonce). On StatusBufferTooSmall n carries the required nonce capacity.

func WrapStreamUpdate 

func WrapStreamUpdate(id WrapStreamHandleID, src, dst []byte) (n int, st Status)

WrapStreamUpdate XORs src into dst under the handle's keystream, advancing the cipher counter by len(src) bytes. dst MAY equal src (in-place mutation); dst capacity must be >= len(src).

On StatusBufferTooSmall the n return reports the required dst capacity (i.e. len(src)).

func WrapperKeySize 

func WrapperKeySize(name string) (n int, st Status)

WrapperKeySize reports the byte length of the keystream-cipher key for the named outer cipher. Returns StatusBadInput on an unknown cipher name.

func WrapperNonceSize 

func WrapperNonceSize(name string) (n int, st Status)

WrapperNonceSize reports the on-wire nonce length the named outer cipher emits per stream. Returns StatusBadInput on an unknown cipher name.

func (Status) String 

func (s Status) String() string

String returns a short human-readable label for the status code. Used by the FFI ITB_LastError() entry point and by test failure messages.

type WrapStreamHandle 

type WrapStreamHandle struct {
	// contains filtered or unexported fields
}

WrapStreamHandle wraps a single outer cipher Keystream behind an opaque uintptr crossing the cgo boundary. The keystream counter advances monotonically across Update calls until the handle is freed; no per-Update reinit cost.

Mirrors the SeedHandle / MACHandle pattern in handles.go and macs.go — the cgo.Handle pins the value so the *Keystream stays rooted on the Go heap until FreeWrapStream is called.

type WrapStreamHandleID 

type WrapStreamHandleID uintptr

WrapStreamHandleID is the opaque uintptr passed across the C ABI as a wrap-stream reference. Internally a runtime/cgo.Handle that maps back to a *WrapStreamHandle on the Go heap.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.