projects/xkyber_crypto/
Óscar Preciado

Expanded Documentation for xKyberCrypto Library

xKyberCrypto Documentation

xKyberCrypto is a Dart library focused on implementing post-quantum encryption based on the Kyber algorithm. Designed for applications requiring high cryptographic security, it provides functionalities for key generation, encryption, and decryption of messages.

1. Key Features

  1. Post-Quantum Encryption: Utilizes complex algebraic structures, including polynomials and modular transformations, to offer resistance against quantum computational attacks.
  2. Session Encryption: Messages are encrypted using session keys derived from the recipient's public key.
  3. Deterministic Noise: Uses AES in CTR mode to generate secure deterministic noise, essential for ensuring the unpredictability of encryption against side-channel attacks.

Expanded Library Modules and Features

2. Key Generation and Encryption

The library employs the Kyber Key Encapsulation Mechanism (KEM) for secure encryption. This scheme uses polynomial math and deterministic noise to produce secure key pairs and enables encryption through shared secret encapsulation and decapsulation.

  • kyber_keypair.dart: Defines the KyberKeyPair class, responsible for generating secure public-private key pairs. The private key is represented as a polynomial generated with deterministic noise, while the public key is derived from the private key using fixed polynomials and modular multiplication.

    Example:

    import 'package:xkyber_crypto/xkyber_crypto.dart';

void main() {
  final keyPair = KyberKeyPair.generate(); // Generates a secure key pair
  print('Public Key: ${keyPair.publicKey}');
  print('Private Key: ${keyPair.privateKey}');
}

  • kyber_kem.dart: Implements the Kyber KEM scheme with encapsulate() and decapsulate() methods. Encapsulation encrypts the message using the recipient’s public key, creating a shared secret. Decapsulation decrypts the message with the recipient’s private key to recover the shared secret.

    Example:

    final kem = KyberKEM(publicKey, privateKey);
final sharedSecret = kem.encapsulate(); // Encrypts and creates a shared key
final decryptedSecret = kem.decapsulate(sharedSecret); // Decrypts to retrieve the shared key

3. Modular Arithmetic and Polynomial Operations

The library relies on modular arithmetic for polynomial operations, which is fundamental in Kyber-based encryption.

  • modular_arithmetic.dart: This file includes modular operations such as modAdd, modMul, modInverse, and modPow, which are essential for maintaining coefficients within valid bounds during encryption.

    Example:

    import 'package:xkyber_crypto/modular_arithmetic.dart';

void main() {
  int result = modMul(3, 4, 3329); // Multiplies in modular arithmetic
  print(result); // Output will be within mod 3329 bounds
}

  • polynomial.dart: The Polynomial class represents polynomials and includes methods for addition, multiplication, and modular reduction. Polynomials are used to create public-private key pairs and are a crucial part of encryption.

    Example:

    Polynomial poly1 = Polynomial([1, 2, 3]);
Polynomial poly2 = Polynomial([4, 5, 6]);
Polynomial result = poly1.multiply(poly2, 3329); // Multiplies two polynomials
print(result.coefficients); // Resulting polynomial coefficients

4. Deterministic Noise Generation

Deterministic noise generation ensures that the encryption is unpredictable, even with a known seed.

  • deterministic_noise_generator.dart: This file defines the DeterministicNoiseGenerator class, which creates deterministic noise using AES in CTR mode. This approach ensures that noise is secure and reproducible.

    Example:

    import 'dart:typed_data';
import 'package:xkyber_crypto/deterministic_noise_generator.dart';

void main() {
  Uint8List seed = Uint8List.fromList([1, 2, 3, 4, 5, 6, 7, 8]);
  final noiseGenerator = DeterministicNoiseGenerator(seed, 16);
  Uint8List noise = noiseGenerator.generateNoise();
  print(noise); // Deterministically generated noise
}

  • noise_generator.dart: Expands on the noise generated using SHA-256 to produce secure noise values modulated to a specific range, necessary for cryptographic operations.

    Example:

    Uint8List noise = generateNoise(16, 3329);
print(noise); // Noise within the range of modulus 3329

5. Coefficient Encoding

Coefficient encoding transforms polynomial coefficients into a format suitable for storage or transmission.

  • coefficients_codec.dart: Provides methods for encoding and decoding coefficients in Base64. This is essential for serializing coefficients for transmission.

    Example:

    List<int> coefficients = [1234, 2345, 3328];
String encoded = encodeCoefficients(coefficients);
print(encoded); // Encoded in Base64

List<int> decoded = decodeCoefficients(encoded);
print(decoded); // Decoded coefficients match the original

6. Constant-Time Comparison

To avoid timing attacks, the library provides a constant-time comparison for encrypted values.

  • constant_time_comparison.dart: The constantTimeCompare() function checks equality between byte arrays without revealing timing information, thus preventing side-channel attacks.

    Example:

    import 'dart:typed_data';
import 'package:xkyber_crypto/constant_time_comparison.dart';

void main() {
  Uint8List data1 = Uint8List.fromList([1, 2, 3]);
  Uint8List data2 = Uint8List.fromList([1, 2, 3]);
  bool isEqual = constantTimeCompare(data1, data2);
  print(isEqual); // true if equal, in constant time
}

7. Polynomial Compression and Decompression

Polynomial compression is crucial for reducing data size in transmission, while decompression restores the polynomial to its approximate original state.

  • polynomial_compression.dart: Contains methods for compressing and decompressing polynomial coefficients. This process is necessary to minimize data size while maintaining enough information to reconstruct the original polynomial.

    Example:

    List<int> coefficients = [1234, 2345, 3328];
List<int> compressed = compressPolynomial(coefficients, 10, 3329);
print(compressed); // Compressed coefficients

List<int> decompressed = decompressPolynomial(compressed, 10, 3329);
print(decompressed); // Decompressed coefficients, close to original values

API Reference

  • XKyberCryptoBase: Main class for interacting with the xKyberCrypto library. It includes:
    • generateKeyPair(): Generates a public-private key pair.
    • encrypt(Uint8List message, Uint8List publicKey): Encrypts a message using a public key.
    • decrypt(List<int> ciphertext, Uint8List privateKey): Decrypts a message using a private key.
    • generateNoise(Uint8List seed): Generates deterministic noise from a seed.

Project Information

  • Name: xkyber_crypto
  • Version: 1.0.0
  • Dependencies:
    • crypto: ^3.0.0
    • pointycastle: ^3.5.0
  • License: MIT License
  • Project Page: GitHub Repository