passring/
lib.rs

1// Copyright (C) 2024 Stanislav Zhevachevskyi
2// 
3// This program is free software: you can redistribute it and/or modify
4// it under the terms of the GNU Affero General Public License as published by
5// the Free Software Foundation, either version 3 of the License, or
6// (at your option) any later version.
7// 
8// This program is distributed in the hope that it will be useful,
9// but WITHOUT ANY WARRANTY; without even the implied warranty of
10// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11// GNU Affero General Public License for more details.
12// 
13// You should have received a copy of the GNU Affero General Public License
14// along with this program.  If not, see <http://www.gnu.org/licenses/>.
15
16//! # Passring
17//! 
18//! Cryptographic library for secure voting systems.
19//! 
20//! Passring is a cryptographic library for secure voting systems. It provides a set of cryptographic primitives for 
21//! secure voting systems, including key generation, encryption, decryption, and signature generation.
22//! 
23//! For more information, see the [Passring whitepaper](https://docs.nau-digital.com/passring/whitepaper).
24//! ## Features
25//! 
26//! - **Secure**: Passring uses the latest cryptographic algorithms to ensure the security of the voting system.
27//! - **Fast**: Passring is optimized for performance and can handle large volumes of data.
28//! - **Easy to use**: Passring provides a simple and easy-to-use API for developers.
29//! 
30//! ## Algorithms
31//! 
32//! Passring uses the following cryptographic algorithms:
33//! 
34//! - **ChaCha20-Poly1305**: For encryption and decryption of payloads.
35//! - **Curve25519 and Ristretto**: For key generation.
36//! - **bLSAG**: For signature generation. bLSAG is a ring signature scheme described in the Chapter 3 of [Zero to Monero 2.0 (Z2M2)](https://www.getmonero.org/library/Zero-to-Monero-2-0-0.pdf).
37//! 
38//! ## Usage
39//! 
40//! To use Passring in your project, add it as dependency using Cargo:
41//! 
42//! ```bash
43//! cargo add passring
44//! ```
45//! 
46//! NOTE: If you want to serialize and deserialize keys/signatures, you need to enable the `serde` feature:
47//! 
48//! ```bash
49//! cargo add passring --features=serde
50//! ```
51//! 
52//! Here is an example of how to use Passring to create a new voting system:
53//! 
54//! ```rust
55//! use chacha20poly1305::{ChaCha20Poly1305, KeyInit};
56//! use passring::{Passring, PrivateKey, PublicKey};
57//! use passring::payload::ClearPayload;
58//! use passring::traits::Random;
59//! use rand_core::OsRng;
60//! use passring::choices::{BasicVotingChoice, VotingChoice};
61//!
62//! // Generate a new voting ID
63//! let voting_id = uuid::Uuid::new_v4();
64//!
65//! // Generate a new private key and public key
66//! let private_key = PrivateKey::random(&mut OsRng);
67//! let public_key = PublicKey::from(private_key);
68//!
69//! // Ring must be retrieved from the Verifier
70//! let ring: Vec<PublicKey> = (0..9).map(|_| PublicKey::random(&mut OsRng)).chain(std::iter::once(public_key)).collect();
71//!
72//! // Create a new Passring instance
73//! let passring = Passring::new(voting_id, ring);
74//!
75//! // Create a new clear payload
76//!
77//! let choice = VotingChoice::Basic { choice: BasicVotingChoice::For }; // The choice of the voter
78//! let clear_payload = ClearPayload::new_random(voting_id, choice, &mut OsRng);
79//!
80//! // Encrypt the clear payload
81//! let key = ChaCha20Poly1305::generate_key(&mut OsRng); // Generate a new key
82//! let payload = clear_payload.encrypt(&key, &mut OsRng).expect("Failed to encrypt payload");
83//!
84//! // Issue a new signature
85//! let full_signature = passring.issue::<OsRng>(payload, private_key).expect("Failed to issue signature");
86//!
87//! // Verify the signature
88//! passring.verify(&full_signature).expect("Failed to verify signature");
89//!
90//! // validate the signature (when the key is known)
91//! passring.validate(&full_signature, &key).expect("Failed to validate signature");
92//!
93//! println!("Signature is valid");
94//! ```
95
96pub mod errors;
97pub mod key;
98pub mod passring;
99pub mod signature;
100pub mod traits;
101pub mod payload;
102pub mod choices;
103
104pub use crate::key::{private::PrivateKey, public::PublicKey};
105pub use crate::passring::Passring;
106
107/// Result type for Passring operations.
108type Result<T> = std::result::Result<T, errors::PassringError>;
109
110pub const VERSION: &str = env!("CARGO_PKG_VERSION");
passring/lib.rs

passring/
lib.rs
