Improve documentation

Author: JobDoesburg

.github/workflows/publish.yml

@@ -57,25 +57,18 @@ jobs:
     name: Build and publish Python wheels
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.x'
-      - name: Create virtual environment and install maturin
-        run: |
-          python -m venv .venv
-          source .venv/bin/activate
-          pip install maturin
       - name: Build wheels
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.target }}
           args: --release --out dist --features python
           sccache: 'true'
           manylinux: auto
+          python-version: '3.8-3.13'
       - name: Upload wheels
         uses: actions/upload-artifact@v3
         with:
-          name: wheels
+          name: wheels-${{ matrix.target }}
           path: dist
 
   publish-python-sdist:
@@ -104,7 +97,7 @@ jobs:
       - name: Upload sdist
         uses: actions/upload-artifact@v3
         with:
-          name: wheels
+          name: sdist
           path: dist
 
   release-python:
@@ -119,7 +112,11 @@ jobs:
       - name: Download all artifacts
         uses: actions/download-artifact@v3
         with:
-          name: wheels
-          path: dist
+          path: artifacts
+      - name: Move files to dist
+        run: |
+          mkdir -p dist
+          find artifacts -name "*.whl" -exec cp {} dist/ \;
+          find artifacts -name "*.tar.gz" -exec cp {} dist/ \;
       - name: Publish to PyPI
         uses: PyPA/gh-action-pypi-publish@release/v1

Cargo.toml

@@ -1,15 +1,15 @@
 [package]
 name = "libpep"
 edition = "2021"
-version = "0.6.9"
+version = "0.6.10"
 authors = ["Bernard van Gastel <bvgastel@bitpowder.com>", "Job Doesburg <job@jobdoesburg.nl>"]
 homepage = "https://github.com/NOLAI/libpep"
 repository = "https://github.com/NOLAI/libpep"
 documentation = "https://docs.rs/libpep"
 license = "Apache-2.0"
-keywords = ["crypto", "pep", "pseudonimization"]
-categories = ["command-line-interface"]
-description = "implementation of PEP primitives, offering pseudonimization and encryption interfaces"
+keywords = ["crypto", "pep", "pseudonymization"]
+categories = ["cryptography", "algorithms"]
+description = "Implementation of PEP primitives, offering pseudonymization and encryption interfaces"
 readme = "README.md"
 
 [features]

README.md

@@ -1,10 +1,10 @@
 # `libpep`: Library for polymorphic pseudonymization and encryption
 [![Crates.io](https://img.shields.io/crates/v/libpep.svg)](https://crates.io/crates/libpep)
-[![Downloads](https://img.shields.io/crates/d/libpep.svg)](https://crates.io/crates/libpep)
-[![PyPI](https://img.shields.io/pypi/v/libpep-py.svg)](https://pypi.org/project/libpep-py/)
-[![PyPI Downloads](https://img.shields.io/pypi/dm/libpep-py.svg)](https://pypi.org/project/libpep-py/)
-[![npm](https://img.shields.io/npm/v/@nolai/libpep-wasm.svg)](https://www.npmjs.com/package/@nolai/libpep-wasm)
-[![npm Downloads](https://img.shields.io/npm/dm/@nolai/libpep-wasm.svg)](https://www.npmjs.com/package/@nolai/libpep-wasm)
+[![Downloads](https://img.shields.io/crates/d/libpep)](https://crates.io/crates/libpep)
+[![PyPI](https://img.shields.io/pypi/v/libpep-py)](https://pypi.org/project/libpep-py/)
+[![Downloads](https://img.shields.io/pypi/dm/libpep-py)](https://pypi.org/project/libpep-py/)
+[![npm](https://img.shields.io/npm/v/@nolai/libpep-wasm)](https://www.npmjs.com/package/@nolai/libpep-wasm)
+[![Downloads](https://img.shields.io/npm/dm/@nolai/libpep-wasm.svg)](https://www.npmjs.com/package/@nolai/libpep-wasm)
 [![License](https://img.shields.io/crates/l/libpep.svg)](https://crates.io/crates/libpep)
 [![Documentation](https://docs.rs/libpep/badge.svg)](https://docs.rs/libpep)
 [![Dependencies](https://deps.rs/repo/github/NOLAI/libpep/status.svg)](https://deps.rs/repo/github/NOLAI/libpep)
@@ -85,11 +85,16 @@ console.log(`Data point: ${data.as_hex()}`);
 ### API Structure
 
 Both Python and WASM bindings mirror the Rust API structure with the same modules:
-- `arithmetic` - Basic arithmetic operations on scalars and group elements
-- `elgamal` - ElGamal encryption and decryption
-- `primitives` - Core PEP operations (`rekey`, `reshuffle`, `rerandomize`)
-- `high_level` - User-friendly API with `Pseudonym` and `DataPoint` classes
-- `distributed` - Distributed n-PEP operations with multiple servers
+
+| Module | Description |
+|--------|-------------|
+| `arithmetic` | Basic arithmetic operations on scalars and group elements |
+| `elgamal` | ElGamal encryption and decryption primitives |
+| `primitives` | Core PEP operations (`rekey`, `reshuffle`, `rerandomize`) |
+| `high_level` | User-friendly API with `Pseudonym` and `DataPoint` classes |
+| `distributed` | Distributed n-PEP operations with multiple servers |
+
+For detailed API documentation, see [docs.rs/libpep](https://docs.rs/libpep).
 
 ## Applications
 
@@ -105,9 +110,17 @@ The factor `k` is typically tied to the *current session of a user*, which we ca
 When the same encrypted pseudonym is used multiple times, rerandomize is applied every time.
 This way a binary compare of the encrypted pseudonym will not leak any information.
 
-## Implementation
+## Security and Implementation
+
+This library uses the Ristretto encoding on Curve25519, implemented in the [`curve25519-dalek` crate](https://docs.rs/curve25519-dalek/latest/curve25519_dalek/), with [patches by Signal](https://github.com/signalapp/curve25519-dalek) for _lizard_ encoding of arbitrary 16 byte values into ristretto points.
 
-This library is using the Ristretto encoding on Curve25519, implemented in the [`curve25519-dalek` crate](https://docs.rs/curve25519-dalek/latest/curve25519_dalek/), but with [patches by Signal](https://github.com/signalapp/curve25519-dalek) for _lizard_ encoding of arbitrary 16 byte values into ristretto points. 
+### Security Considerations
+- All cryptographic operations use constant-time algorithms to prevent timing attacks
+- Random number generation uses cryptographically secure sources
+- The library has been designed for production use but hasn't yet undergone formal security auditing
+- Users should properly secure private keys and avoid exposing sensitive cryptographic material
+
+### Arithmetic Rules
 There are a number of arithmetic rules for scalars and group elements: group elements can be added and subtracted from each other.
 Scalars support addition, subtraction, and multiplication.
 Division can be done by multiplying with the inverse (using `s.invert()` for non-zero scalar `s`).
@@ -132,13 +145,27 @@ Depending on the use case, you can choose the appropriate level of abstraction.
 
 ## Development
 
+### Prerequisites
+- Rust 1.70+ (MSRV)
+- Node.js 18+ (for WASM bindings)
+- Python 3.8+ (for Python bindings)
+
+### Building and Testing
+
 Build and test the core Rust library:
 ```bash
 cargo build
 cargo test
+cargo clippy
 cargo doc --no-deps
 ```
 
+Run tests with different feature combinations:
+```bash
+cargo test --features elgamal3
+cargo test --features legacy-pep-repo-compatible
+```
+
 ## Building Bindings
 
 ### Python

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolai/libpep-wasm",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "description": "The WebAssembly version of the libpep library",
   "repository": {
     "type": "git",

pyproject.toml

@@ -20,6 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Programming Language :: Rust",
     "Topic :: Security :: Cryptography",
 ]

src/lib/distributed/systems.rs

@@ -110,7 +110,7 @@ impl PEPSystem {
         transcrypt(encrypted, transcryption_info)
     }
 
-    /// Transcrypt a batch of encrypted messages for one entity (see [`EncryptedEntityMessages`]),
+    /// Transcrypt a batch of encrypted messages for one entity (see [`EncryptedEntityData`]),
     /// from one pseudonymization domain and session to another, using [`TranscryptionInfo`].
     pub fn transcrypt_batch<R: RngCore + CryptoRng>(
         &self,

src/lib/high_level/ops.rs

@@ -167,7 +167,7 @@ pub fn rekey_batch<R: RngCore + CryptoRng>(
 /// A pair of encrypted pseudonyms and data points that relate to the same entity, used for batch transcryption.
 pub type EncryptedEntityData = (Vec<EncryptedPseudonym>, Vec<EncryptedDataPoint>);
 
-/// Batch transcryption of a slice of [`EncryptedEntityMessages`]s, using [`TranscryptionInfo`].
+/// Batch transcryption of a slice of [`EncryptedEntityData`]s, using [`TranscryptionInfo`].
 /// The order of the pairs (entities) is randomly shuffled to avoid linking them, but the internal
 /// order of pseudonyms and data points for the same entity is preserved.
 pub fn transcrypt_batch<R: RngCore + CryptoRng>(

src/lib/lib.rs

@@ -68,17 +68,7 @@ pub mod distributed {
     pub mod systems;
 }
 #[cfg(feature = "wasm")]
-mod wasm {
-    //! Wrappers for WebAssembly bindings.
-    //! Since WebAssembly does not support the polymorphic properties we use in the rest of the
-    //! library, we need to provide wrappers around all structs and functions.
-    //! This module is only available when the `wasm` feature is enabled.
-    mod arithmetic;
-    mod distributed;
-    mod elgamal;
-    mod high_level;
-    mod primitives;
-}
+pub mod wasm;
 
 #[cfg(feature = "python")]
 mod python;

src/lib/wasm/high_level.rs

@@ -385,7 +385,7 @@ pub struct WASMSessionKeyPair {
 #[wasm_bindgen(js_name = makeGlobalKeys)]
 pub fn wasm_make_global_keys() -> WASMGlobalKeyPair {
     let mut rng = rand::thread_rng();
-    let (public, secret) = make_global_keys(&mut rng);
+    let (public, secret) = crate::high_level::keys::make_global_keys(&mut rng);
     WASMGlobalKeyPair {
         public: WASMGlobalPublicKey::from(WASMGroupElement::from(public.0)),
         secret: WASMGlobalSecretKey::from(WASMScalarNonZero::from(secret.0)),
@@ -399,14 +399,14 @@ pub fn wasm_make_session_keys(
     session: &str,
     secret: &WASMEncryptionSecret,
 ) -> WASMSessionKeyPair {
-    let (public, secret) = make_session_keys(
-        &GlobalSecretKey(*global.0),
+    let (public, secret_key) = crate::high_level::keys::make_session_keys(
+        &GlobalSecretKey(global.0 .0),
         &EncryptionContext::from(session),
         &secret.0,
     );
     WASMSessionKeyPair {
         public: WASMSessionPublicKey::from(WASMGroupElement::from(public.0)),
-        secret: WASMSessionSecretKey::from(WASMScalarNonZero::from(secret.0)),
+        secret: WASMSessionSecretKey::from(WASMScalarNonZero::from(secret_key.0)),
     }
 }
 

src/lib/wasm/mod.rs

@@ -0,0 +1,55 @@
+//! WebAssembly bindings for libpep using wasm-bindgen.
+//!
+//! This module provides WebAssembly access to all libpep functionality including:
+//! - Basic arithmetic operations on group elements and scalars
+//! - ElGamal encryption and decryption  
+//! - PEP primitives (rekey, reshuffle, rsk operations)
+//! - High-level API for pseudonyms and data points
+//! - Distributed n-PEP systems
+//!
+//! This module is only available when the `wasm` feature is enabled.
+
+pub mod arithmetic;
+pub mod distributed;
+pub mod elgamal;
+pub mod high_level;
+pub mod primitives;
+
+use wasm_bindgen::prelude::*;
+
+/// Initialize the WASM module
+#[wasm_bindgen(start)]
+pub fn wasm_main() {
+    // Module initialization - can be used for setup
+}
+
+// Re-export all types from submodules for convenient access
+// This allows users to import directly from the main module if they prefer
+
+// Arithmetic types
+pub use arithmetic::{WASMGroupElement, WASMScalarCanBeZero, WASMScalarNonZero};
+
+// ElGamal types
+pub use elgamal::WASMElGamal;
+
+// Primitives
+pub use high_level::{WASMRekeyFactor, WASMReshuffleFactor};
+
+// High-level types and functions
+pub use high_level::{
+    wasm_make_global_keys as make_global_keys, wasm_make_session_keys as make_session_keys,
+    wasm_pseudonymize as pseudonymize, wasm_pseudonymize_batch as pseudonymize_batch,
+    wasm_rekey_batch as rekey_batch, wasm_rekey_data as rekey_data,
+    wasm_transcrypt_batch as transcrypt_batch, WASMDataPoint, WASMEncryptedDataPoint,
+    WASMEncryptedEntityData, WASMEncryptedPseudonym, WASMEncryptionSecret, WASMGlobalKeyPair,
+    WASMGlobalPublicKey, WASMGlobalSecretKey, WASMPseudonym, WASMPseudonymizationInfo,
+    WASMPseudonymizationSecret, WASMRSKFactors, WASMRekeyInfo, WASMSessionKeyPair,
+    WASMSessionPublicKey, WASMSessionSecretKey,
+};
+
+// Distributed types
+pub use distributed::{
+    wasm_make_blinded_global_secret_key as make_blinded_global_secret_key,
+    WASMBlindedGlobalSecretKey, WASMBlindingFactor, WASMOfflinePEPClient, WASMPEPClient,
+    WASMPEPSystem, WASMSessionKeyShare,
+};