Crate poulpy_ckks

Expand description

§poulpy-ckks

Backend-agnostic implementation of the CKKS (Cheon-Kim-Kim-Song) homomorphic encryption scheme, built from poulpy-core and poulpy-hal.

Public calls dispatch through explicit backend oep contracts. Public reference algorithms compose lower-layer operations; simple CKKS compositions are crate-private derived defaults on the contracts. A backend may replace a method while reusing the reference for other members of its family. Replacements must compute the same circuit and pass parity against a caller-selected validated implementation. Validation is transitive for the operations and parameter ranges covered by those tests.

The crate uses a bivariate polynomial representation over the Torus (base-2^{base2k} digits) instead of the RNS representation used by most other CKKS libraries. Public precision management is exposed through CKKSMeta:

log_delta: base-2 logarithm of the encoded plaintext scaling factor
log_sparsity: base-2 logarithm of the slot replication

Remaining homomorphic headroom, log_budget, is derived from the wrapped ciphertext or plaintext width as k() - log_delta; it is not stored in CKKSMeta.

CKKSMeta also records the SlotsKind of a value: whether its slots are known to be real, or may carry an imaginary part. Operations compose that claim, keeping Real only when every operand is real, so a caller can state it once at encoding time and have the pipelines specialize on it.

Together they define the semantic torus width of a value: k() = log_delta + log_budget. Storage is rounded up to the next multiple of base2k, so the allocated capacity max_k() may exceed the effective width k(). Arithmetic APIs update this metadata for you; buffers always stay at their allocated width, and allocating a destination at exactly the k you want is how results are narrowed.

Linear operations (additions, subtractions, plaintext additions, doubling, negation, copies, multiplication by ±i) do not normalize. Additions, subtractions and doubling clear the wrapped GLWE’s canonical flag, the others keep their operand’s, and the next operation that reads the digits through a DFT (products, rotations, conjugation, keyswitching, decryption) normalizes a flag-clear operand first. A value several such operations read is best normalized once with glwe_normalize_assign, and serializing requires a normalized ciphertext. Each lazy addition can grow the digits by one bit; a sum of n terms stays within i64 while n <= 2^(63 - base2k).

§Modules

Module	Role
`approximation`	Reusable minimax fitting, precision/depth selection, composite sign generation, and prepared interval-mapped polynomial evaluation
`encoding` / `reference::encoding`	Canonical slot ordering, quantization, and PaCo/SHIP embeddings, with explicit host reference helpers
`layouts`	CKKS ciphertext/plaintext wrappers and metadata-aware allocation helpers
`presets`	Ready-to-use parameter sets
`api`	The public op traits: leveled arithmetic (add, sub, mul, neg, rotate, conjugate), encryption, decryption, rescale, and scratch sizing
`api::CKKSBootstrappingOps`	API composition of encapsulated ModUp, DFT, and EvalMod; parameterized by `layouts::BootstrappingPlan`
`api::CKKSPaCoOps`	PaCo bootstrapping without ModUp or EvalMod; parameterized by `layouts::PaCoPlan` and a compiled `layouts::PaCoContext`

Re-exports§

pub use scalar::Quad;

Modules§

api
approximation: Reusable host-side polynomial approximation planning.
encoding: Backend-independent CKKS encoding algorithms.
layouts: CKKS-level data structures.
numerics: Platform-independent scalar math for CKKS setup and encoding.
oep: Backend contracts selected by the public CKKS API through delegates.
polynomial
power_basis
prelude: One-stop imports for the common CKKS path.
presets: Ready-to-use CKKS parameter sets.
reference: Callable CKKS algorithms built from core and HAL operations.
scalar: Portable quad-precision (IEEE 754 binary128) scalar for high-precision CKKS.

Macros§

impl_ckks_add_reference: Implements the CKKS addition contract with callable reference algorithms.
impl_ckks_bootstrapping_reference: Opts a standard backend into the CKKS reference bootstrapping pipeline.
impl_ckks_complex_polynomial_evaluation_reference
impl_ckks_conjugate_reference: Implements this contract with the callable reference algorithms.
impl_ckks_copy_reference: Implements this contract with the callable reference algorithms.
impl_ckks_dft_reference: Wires matrix generation and primitive DFT evaluation to their reference algorithms.
impl_ckks_encapsulated_mod_up_reference: Opts a backend into the CKKS reference encapsulated-ModUp pipeline.
impl_ckks_encryption_reference: Implements this contract with the callable reference algorithms.
impl_ckks_eval_mod_reference
impl_ckks_fold_reference: Opts a standard backend into the CKKS reference fold, for every input ring the reference folds.
impl_ckks_imag_reference: Implements this contract with the callable reference algorithms.
impl_ckks_infos: Implements the full CKKS scratch-view trait bundle for a nominal backend view wrapper: CKKSInfos, SetCKKSInfos, SetK, BSGSMeta, and SetBSGSMeta.
impl_ckks_mul_reference: Implements this contract with the callable reference algorithms.
impl_ckks_neg_reference: Implements this contract with the callable reference algorithms.
impl_ckks_plaintext_reference: Implements this contract with the callable reference algorithms.
impl_ckks_polynomial_evaluation_reference
impl_ckks_pow2_reference: Implements this contract with the callable reference algorithms.
impl_ckks_rotate_reference: Implements this contract with the callable reference algorithms.
impl_ckks_sub_reference: Implements the CKKS subtraction contract with callable reference algorithms.

Structs§

CKKSLayout: Allocation / precision spec for a CKKS value.
CKKSMeta: CKKS semantic precision metadata carried by ciphertexts and plaintexts.
CoeffsMeta: Coefficient metadata for plan-compiled operands: the DFT factor diagonals (layouts::DFTPlan), the EvalMod polynomial coefficients (layouts::EvalModPlan), and the BSGS polynomial encoders (polynomial::EncodeBSGS).

Enums§

CKKSCompositionError: CKKS composition and alignment errors returned by high-level operations.
CKKSError: Typed error returned by every fallible CKKS operation (the api op traits and the layers backing them).
SlotsKind: Which subfield the encoded slots are known to live in.

Traits§

CKKSCtBounds: Marker bound for CKKS ciphertext type parameters.
CKKSInfos: Common metadata accessors for CKKS ciphertext and plaintext containers.
CKKSModuleInfos: Ring-dependent CKKS slot geometry and automorphism identifiers.
CKKSPlaintextToBackendMut: Backend-compatible mutable CKKS plaintext storage.
CKKSPlaintextToBackendRef: Backend-compatible shared CKKS plaintext storage.
SetCKKSInfos: Mutable CKKS metadata access for ciphertext/plaintext containers.

Type Aliases§

CKKSResult: Result type of every fallible CKKS operation.