Struct RingElem 

pub struct RingElem { /* private fields */ }

Canonical element of R_q = Z_q[x] / (f(x)).

Each operation applies the corresponding polynomial arithmetic and then reduces modulo f(x).

Implementations

impl RingElem

pub fn params(&self) -> &Params

Returns the validated parameter set that defines this element’s ring.

Examples found in repository

examples/common/pke.rs (line 181)

fn ensure_element_matches_context(
    ctx: &RingContext,
    element: &RingElem,
) -> Result<(), ExamplePkeError> {
    // Structural parameter equality check.
    if element.params() != ctx.params() {
        return Err(ExamplePkeError::ParameterMismatch);
    }
    Ok(())
}

examples/common/codec.rs (line 137)

pub fn decode_message_scaled_bits_example(
    element: &RingElem,
    output_len_bytes: usize,
) -> Result<Vec<u8>, CodecError> {
    // Decode limit follows the same bit-capacity convention used at encode time.
    let capacity_bits = element.params().max_degree();
    let requested_bits = output_len_bytes.saturating_mul(8);
    if requested_bits > capacity_bits {
        return Err(CodecError::DecodeLengthTooLong {
            requested_bits,
            capacity_bits,
        });
    }

    let q = element.params().modulus();
    // Threshold window near middle of modulus range.
    // Values in `[q/4, 3q/4)` decode to 1; others decode to 0.
    let lower = q / 4;
    let upper = (3 * q) / 4;

    let mut out = vec![0_u8; output_len_bytes];
    for bit_index in 0..requested_bits {
        let coeff = element.coefficients()[bit_index];
        let bit = coeff >= lower && coeff < upper;
        if bit {
            // Restore little-endian bit position.
            out[bit_index / 8] |= 1_u8 << (bit_index % 8);
        }
    }

    Ok(out)
}

/// Compresses one coefficient into `bits` bits.
pub fn compress_coefficient_example(value: u64, modulus: u64, bits: u8) -> Result<u16, CodecError> {
    validate_compression_bits(bits)?;

    // Quantization levels = 2^bits.
    let levels = 1_u128 << bits;
    let q = modulus as u128;
    let v = (value % modulus) as u128;

    // Rounded scaling from `[0, q)` into `[0, 2^bits)`.
    let compressed = ((v * levels + (q / 2)) / q) % levels;
    Ok(compressed as u16)
}

/// Decompresses one `bits`-bit coefficient back into `Z_q`.
pub fn decompress_coefficient_example(
    compressed: u16,
    modulus: u64,
    bits: u8,
) -> Result<u64, CodecError> {
    validate_compression_bits(bits)?;

    let levels = 1_u128 << bits;
    let q = modulus as u128;
    let c = (compressed as u128) % levels;

    // Rounded inverse scaling from `[0, 2^bits)` back into `[0, q)`.
    let decompressed = (c * q + (levels / 2)) / levels;
    Ok((decompressed % q) as u64)
}

/// Compresses all coefficients of a ring element into `bits` bits each.
pub fn compress_ring_elem_example(element: &RingElem, bits: u8) -> Result<Vec<u16>, CodecError> {
    validate_compression_bits(bits)?;

    let q = element.params().modulus();
    // Compress each coefficient independently.
    let mut packed = Vec::with_capacity(element.coefficients().len());
    for &coeff in element.coefficients() {
        packed.push(compress_coefficient_example(coeff, q, bits)?);
    }
    Ok(packed)
}

pub fn polynomial(&self) -> &Polynomial

Returns the underlying canonical polynomial representative.

pub fn into_polynomial(self) -> Polynomial

Consumes and returns the underlying polynomial representative.

pub fn coefficients(&self) -> &[u64]

Returns the dense coefficient slice of the canonical representative.

Examples found in repository

examples/common/codec.rs (line 154)

pub fn decode_message_scaled_bits_example(
    element: &RingElem,
    output_len_bytes: usize,
) -> Result<Vec<u8>, CodecError> {
    // Decode limit follows the same bit-capacity convention used at encode time.
    let capacity_bits = element.params().max_degree();
    let requested_bits = output_len_bytes.saturating_mul(8);
    if requested_bits > capacity_bits {
        return Err(CodecError::DecodeLengthTooLong {
            requested_bits,
            capacity_bits,
        });
    }

    let q = element.params().modulus();
    // Threshold window near middle of modulus range.
    // Values in `[q/4, 3q/4)` decode to 1; others decode to 0.
    let lower = q / 4;
    let upper = (3 * q) / 4;

    let mut out = vec![0_u8; output_len_bytes];
    for bit_index in 0..requested_bits {
        let coeff = element.coefficients()[bit_index];
        let bit = coeff >= lower && coeff < upper;
        if bit {
            // Restore little-endian bit position.
            out[bit_index / 8] |= 1_u8 << (bit_index % 8);
        }
    }

    Ok(out)
}

/// Compresses one coefficient into `bits` bits.
pub fn compress_coefficient_example(value: u64, modulus: u64, bits: u8) -> Result<u16, CodecError> {
    validate_compression_bits(bits)?;

    // Quantization levels = 2^bits.
    let levels = 1_u128 << bits;
    let q = modulus as u128;
    let v = (value % modulus) as u128;

    // Rounded scaling from `[0, q)` into `[0, 2^bits)`.
    let compressed = ((v * levels + (q / 2)) / q) % levels;
    Ok(compressed as u16)
}

/// Decompresses one `bits`-bit coefficient back into `Z_q`.
pub fn decompress_coefficient_example(
    compressed: u16,
    modulus: u64,
    bits: u8,
) -> Result<u64, CodecError> {
    validate_compression_bits(bits)?;

    let levels = 1_u128 << bits;
    let q = modulus as u128;
    let c = (compressed as u128) % levels;

    // Rounded inverse scaling from `[0, 2^bits)` back into `[0, q)`.
    let decompressed = (c * q + (levels / 2)) / levels;
    Ok((decompressed % q) as u64)
}

/// Compresses all coefficients of a ring element into `bits` bits each.
pub fn compress_ring_elem_example(element: &RingElem, bits: u8) -> Result<Vec<u16>, CodecError> {
    validate_compression_bits(bits)?;

    let q = element.params().modulus();
    // Compress each coefficient independently.
    let mut packed = Vec::with_capacity(element.coefficients().len());
    for &coeff in element.coefficients() {
        packed.push(compress_coefficient_example(coeff, q, bits)?);
    }
    Ok(packed)
}

pub fn trimmed_coefficients(&self) -> Vec<u64>

Returns coefficients trimmed to the actual degree.

pub fn degree(&self) -> Option<usize>

Returns the representative’s polynomial degree.

Examples found in repository

examples/helpers_codec.rs (line 71)

fn main() {
    // Use a power-of-two cyclotomic-style modulus polynomial `x^32 + 1`.
    let mut modulus_poly = vec![0_u64; 32 + 1];
    modulus_poly[0] = 1;
    modulus_poly[32] = 1;
    // Create validated context (n=32, q=998244353, primitive root=3).
    let ctx =
        RingContext::from_parts(32, 998_244_353, &modulus_poly, 3).expect("context should build");

    // Message to encode. Each bit maps into one coefficient slot.
    let message = b"Rust";
    // Encode bytes -> ring element with coefficients in `{0, floor((q+1)/2)}`.
    let encoded =
        encode_message_scaled_bits_example(&ctx, message).expect("message encoding should work");
    // Decode ring element -> bytes (threshold decoding in coefficient domain).
    let decoded = decode_message_scaled_bits_example(&encoded, message.len())
        .expect("message decoding should work");
    // End-to-end correctness check.
    assert_eq!(decoded, message);

    // Quantize coefficients to 11-bit buckets.
    let compressed = compress_ring_elem_example(&encoded, 11).expect("compression should work");
    // Lift quantized coefficients back into `Z_q`.
    let decompressed =
        decompress_ring_elem_example(&ctx, &compressed, 11).expect("decompression should work");

    // Print summary values to inspect behavior quickly.
    println!("decoded_message={:?}", String::from_utf8_lossy(&decoded));
    println!("compressed_coeffs={}", compressed.len());
    println!("decompressed_degree={:?}", decompressed.degree());
}

examples/helpers_sampling.rs (line 128)

fn main() {
    // Configure modulus polynomial `x^16 + 1`.
    //
    // We allocate `max_degree + 1` coefficients and set:
    // - constant term: 1
    // - x^16 term: 1
    // - all intermediate terms: 0
    let mut modulus_poly = vec![0_u64; 16 + 1];
    modulus_poly[0] = 1;
    modulus_poly[16] = 1;
    // Build validated ring context with NTT-friendly modulus and primitive root.
    let ctx =
        RingContext::from_parts(16, 998_244_353, &modulus_poly, 3).expect("context should build");

    // Deterministic seed makes this executable reproducible.
    let mut rng = ExampleRng::new(0xA11C_E123_0000_0001);

    // Uniform sample in `R_q`: every coefficient is sampled independently in `[0, q)`.
    let uniform =
        sample_uniform_poly_example(&ctx, &mut rng).expect("uniform sampling should work");
    // Centered-binomial sample: each coefficient is small noise around 0.
    let cbd = sample_cbd_poly_example(&ctx, 3, &mut rng).expect("CBD sampling should work");
    // Gaussian-like sample from Box-Muller + integer rounding.
    let gaussian =
        sample_discrete_gaussian_poly_example(&ctx, 2.5, &mut rng).expect("gaussian should work");
    // Raw integer rejection sample in `[0, 1000)`.
    let below = sample_rejection_u64_below_example(1_000, &mut rng).expect("rejection should work");

    // Print concise observable properties so this can be used as a smoke run.
    println!("uniform_degree={:?}", uniform.degree());
    println!("cbd_degree={:?}", cbd.degree());
    println!("gaussian_degree={:?}", gaussian.degree());
    println!("sample_below_1000={below}");
}

pub fn is_zero(&self) -> bool

Returns whether the element is additive identity.

pub fn add(&self, rhs: &Self) -> Result<Self, PolynomialError>

Adds two ring elements.

Examples found in repository

examples/common/pke.rs (line 118)

pub fn keygen_example<R: CryptoRng>(
    ctx: &RingContext,
    noise_eta: u8,
    rng: &mut R,
) -> Result<(ExamplePublicKey, ExampleSecretKey), ExamplePkeError> {
    // Public random polynomial.
    let a = sample_uniform_poly_example(ctx, rng)?;
    // Secret small-noise polynomial.
    let s = sample_cbd_poly_example(ctx, noise_eta, rng)?;
    // Public error polynomial.
    let e = sample_cbd_poly_example(ctx, noise_eta, rng)?;

    // RLWE public relation: b = a*s + e.
    let b = a.mul(&s)?.add(&e)?;

    Ok((ExamplePublicKey { a, b }, ExampleSecretKey { s }))
}

/// Encrypts a byte message using the example key.
///
/// The message is encoded using scaled bits from [`encode_message_scaled_bits_example`].
pub fn encrypt_example<R: CryptoRng>(
    ctx: &RingContext,
    public_key: &ExamplePublicKey,
    message: &[u8],
    noise_eta: u8,
    rng: &mut R,
) -> Result<ExampleCiphertext, ExamplePkeError> {
    // Ensure all key elements come from the same validated parameter set.
    ensure_element_matches_context(ctx, &public_key.a)?;
    ensure_element_matches_context(ctx, &public_key.b)?;

    // Encode message bits into ring element form.
    let m = encode_message_scaled_bits_example(ctx, message)?;
    // Fresh encryption randomness + masking errors.
    let r = sample_cbd_poly_example(ctx, noise_eta, rng)?;
    let e1 = sample_cbd_poly_example(ctx, noise_eta, rng)?;
    let e2 = sample_cbd_poly_example(ctx, noise_eta, rng)?;

    // RLWE encryption equations:
    //   u = a*r + e1
    //   v = b*r + e2 + m
    let u = public_key.a.mul(&r)?.add(&e1)?;
    let v = public_key.b.mul(&r)?.add(&e2)?.add(&m)?;

    Ok(ExampleCiphertext { u, v })
}

pub fn sub(&self, rhs: &Self) -> Result<Self, PolynomialError>

Subtracts two ring elements.

Examples found in repository

examples/common/pke.rs (line 169)

pub fn decrypt_example(
    ctx: &RingContext,
    secret_key: &ExampleSecretKey,
    ciphertext: &ExampleCiphertext,
    output_len_bytes: usize,
) -> Result<Vec<u8>, ExamplePkeError> {
    // Context checks prevent cross-parameter misuse.
    ensure_element_matches_context(ctx, &secret_key.s)?;
    ensure_element_matches_context(ctx, &ciphertext.u)?;
    ensure_element_matches_context(ctx, &ciphertext.v)?;

    // Recover encoded message:
    //   v - s*u = (a*s + e)r + e2 + m - s(a*r + e1)
    //           = m + (e*r + e2 - s*e1)
    // Small noise lets threshold decoder recover bits.
    let recovered = ciphertext.v.sub(&secret_key.s.mul(&ciphertext.u)?)?;
    Ok(decode_message_scaled_bits_example(
        &recovered,
        output_len_bytes,
    )?)
}

pub fn mul(&self, rhs: &Self) -> Result<Self, PolynomialError>

Multiplies two ring elements.

Examples found in repository

examples/common/pke.rs (line 118)

pub fn keygen_example<R: CryptoRng>(
    ctx: &RingContext,
    noise_eta: u8,
    rng: &mut R,
) -> Result<(ExamplePublicKey, ExampleSecretKey), ExamplePkeError> {
    // Public random polynomial.
    let a = sample_uniform_poly_example(ctx, rng)?;
    // Secret small-noise polynomial.
    let s = sample_cbd_poly_example(ctx, noise_eta, rng)?;
    // Public error polynomial.
    let e = sample_cbd_poly_example(ctx, noise_eta, rng)?;

    // RLWE public relation: b = a*s + e.
    let b = a.mul(&s)?.add(&e)?;

    Ok((ExamplePublicKey { a, b }, ExampleSecretKey { s }))
}

/// Encrypts a byte message using the example key.
///
/// The message is encoded using scaled bits from [`encode_message_scaled_bits_example`].
pub fn encrypt_example<R: CryptoRng>(
    ctx: &RingContext,
    public_key: &ExamplePublicKey,
    message: &[u8],
    noise_eta: u8,
    rng: &mut R,
) -> Result<ExampleCiphertext, ExamplePkeError> {
    // Ensure all key elements come from the same validated parameter set.
    ensure_element_matches_context(ctx, &public_key.a)?;
    ensure_element_matches_context(ctx, &public_key.b)?;

    // Encode message bits into ring element form.
    let m = encode_message_scaled_bits_example(ctx, message)?;
    // Fresh encryption randomness + masking errors.
    let r = sample_cbd_poly_example(ctx, noise_eta, rng)?;
    let e1 = sample_cbd_poly_example(ctx, noise_eta, rng)?;
    let e2 = sample_cbd_poly_example(ctx, noise_eta, rng)?;

    // RLWE encryption equations:
    //   u = a*r + e1
    //   v = b*r + e2 + m
    let u = public_key.a.mul(&r)?.add(&e1)?;
    let v = public_key.b.mul(&r)?.add(&e2)?.add(&m)?;

    Ok(ExampleCiphertext { u, v })
}

/// Decrypts an example ciphertext and decodes the requested number of output bytes.
pub fn decrypt_example(
    ctx: &RingContext,
    secret_key: &ExampleSecretKey,
    ciphertext: &ExampleCiphertext,
    output_len_bytes: usize,
) -> Result<Vec<u8>, ExamplePkeError> {
    // Context checks prevent cross-parameter misuse.
    ensure_element_matches_context(ctx, &secret_key.s)?;
    ensure_element_matches_context(ctx, &ciphertext.u)?;
    ensure_element_matches_context(ctx, &ciphertext.v)?;

    // Recover encoded message:
    //   v - s*u = (a*s + e)r + e2 + m - s(a*r + e1)
    //           = m + (e*r + e2 - s*e1)
    // Small noise lets threshold decoder recover bits.
    let recovered = ciphertext.v.sub(&secret_key.s.mul(&ciphertext.u)?)?;
    Ok(decode_message_scaled_bits_example(
        &recovered,
        output_len_bytes,
    )?)
}

pub fn neg(&self) -> Self

Returns additive inverse.

pub fn scalar_mul(&self, scalar: u64) -> Self

Multiplies by a scalar in Z_q.

Trait Implementations

impl Clone for RingElem

fn clone(&self) -> RingElem

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RingElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for RingElem

fn eq(&self, other: &RingElem) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for RingElem

impl StructuralPartialEq for RingElem