kyberlib/macros.rs
1// Copyright © 2024 kyberlib. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3
4//! # KyberLib Macros
5//!
6//! A collection of utility macros for various operations like assertions, logging, and executing tasks,
7//! specifically designed for `no_std` environments in Rust. These macros provide essential functionalities
8//! like logging, assertions, and value comparisons without relying on the standard library.
9
10/// Asserts that a given expression is true. Panics if the assertion fails.
11///
12/// # Examples
13///
14/// ```
15/// use kyberlib::kyberlib_assert;
16/// kyberlib_assert!(1 + 1 == 2);
17/// ```
18#[macro_export]
19macro_rules! kyberlib_assert {
20 ($cond:expr $(,)?) => {
21 if !$cond {
22 // Handle assertion failure in your custom way, e.g., by logging or panic
23 // You can define your custom panic handler in a no_std environment.
24 panic!("Assertion failed: {}", stringify!($cond));
25 }
26 };
27}
28
29/// Returns the minimum of the given values.
30///
31/// # Examples
32///
33/// ```
34/// use kyberlib::kyberlib_min;
35/// let min = kyberlib_min!(1, 2, 3);
36/// assert_eq!(min, 1);
37/// ```
38#[macro_export]
39macro_rules! kyberlib_min {
40 ($x:expr $(, $xs:expr)*) => {{
41 let mut min = $x;
42 $(min = if $xs < min { $xs } else { min };)*
43 min
44 }};
45}
46
47/// Returns the maximum of the given values.
48///
49/// # Examples
50///
51/// ```
52/// use kyberlib::kyberlib_max;
53/// let max = kyberlib_max!(1, 2, 3);
54/// assert_eq!(max, 3);
55/// ```
56#[macro_export]
57macro_rules! kyberlib_max {
58 ($x:expr $(, $xs:expr)*) => {{
59 let mut max = $x;
60 $(max = if $xs > max { $xs } else { max };)*
61 max
62 }};
63}
64
65/// Generates a public and private key pair for CCA-secure Kyber key encapsulation mechanism.
66///
67/// # Arguments
68///
69/// * `pk` - Output public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
70/// * `sk` - Output private key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
71/// * `_rng` - Random number generator implementing RngCore + CryptoRng.
72/// * `_seed` - Optional seed for key generation.
73///
74/// # Errors
75///
76/// Returns a `KyberLibError` on failure.
77#[macro_export]
78macro_rules! kyberlib_generate_key_pair {
79 ($pk:expr, $sk:expr, $rng:expr, $seed:expr) => {
80 kyberlib::kem::generate_key_pair($pk, $sk, $rng, $seed)
81 };
82}
83
84/// Generates cipher text and a shared secret for a given public key.
85///
86/// # Arguments
87///
88/// * `ct` - Output cipher text (an already allocated array of CRYPTO_CIPHERTEXTBYTES bytes).
89/// * `ss` - Output shared secret (an already allocated array of CRYPTO_BYTES bytes).
90/// * `pk` - Input public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
91/// * `_rng` - Random number generator implementing RngCore + CryptoRng.
92/// * `_seed` - Optional seed for random number generation.
93///
94/// # Errors
95///
96/// Returns a `KyberLibError` on failure.
97#[macro_export]
98macro_rules! kyberlib_encrypt_message {
99 ($ct:expr, $ss:expr, $pk:expr, $rng:expr, $seed:expr) => {
100 kyberlib::kem::encrypt_message($ct, $ss, $pk, $rng, $seed)
101 };
102}
103
104/// Generates a shared secret for a given cipher text and private key.
105///
106/// # Arguments
107///
108/// * `ss` - Output shared secret (an already allocated array of CRYPTO_BYTES bytes).
109/// * `ct` - Input cipher text (an already allocated array of CRYPTO_CIPHERTEXTBYTES bytes).
110/// * `sk` - Input private key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
111///
112/// On failure, `ss` will contain a pseudo-random value.
113#[macro_export]
114#[doc = "Macro to decrypt a message using the Kyber key encapsulation mechanism."]
115macro_rules! kyberlib_decrypt_message {
116 ($ss:expr, $ct:expr, $sk:expr) => {
117 kyberlib::kem::decrypt_message($ss, $ct, $sk)
118 };
119}
120
121/// Initiates a Unilaterally Authenticated Key Exchange.
122///
123/// # Arguments
124///
125/// * `pubkey` - Input public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
126/// * `rng` - Random number generator implementing RngCore + CryptoRng.
127///
128/// # Returns
129///
130/// The bytes to send when initiating a unilateral key exchange (UakeSendInit).
131#[cfg(feature = "hazmat")]
132#[macro_export]
133#[doc = "Macro to initiate a Unilaterally Authenticated Key Exchange."]
134macro_rules! kyberlib_uake_client_init {
135 ($pubkey:expr, $rng:expr) => {
136 kyberlib::hazmat::kex::Uake::new().client_init($pubkey, $rng)
137 };
138}
139
140/// Handles the output of a `kyberlib_uake_client_init()` request.
141///
142/// # Arguments
143///
144/// * `send_a` - The bytes received from the `kyberlib_uake_client_init()` request.
145/// * `secretkey` - The secret key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
146/// * `rng` - Random number generator implementing RngCore + CryptoRng.
147///
148/// # Returns
149///
150/// The bytes to send when responding to a unilateral key exchange (UakeSendResponse).
151#[cfg(feature = "hazmat")]
152#[macro_export]
153#[doc = "Macro to handle the output of a Unilaterally Authenticated Key Exchange."]
154macro_rules! kyberlib_uake_server_receive {
155 ($send_a:expr, $secretkey:expr, $rng:expr) => {
156 kyberlib::hazmat::kex::Uake::new()
157 .server_receive($send_a, $secretkey, $rng)
158 };
159}
160
161/// Decapsulates and authenticates the shared secret from the output of
162/// `kyberlib_uake_server_receive()`.
163///
164/// # Arguments
165///
166/// * `send_b` - The bytes received from the `kyberlib_uake_server_receive()` request.
167///
168/// # Returns
169///
170/// Nothing (the shared secret is stored in the `Uake` struct).
171#[cfg(feature = "hazmat")]
172#[macro_export]
173#[doc = "Macro to decapsulate and authenticate the shared secret from a Unilaterally Authenticated Key Exchange."]
174macro_rules! kyberlib_uake_client_confirm {
175 ($send_b:expr) => {
176 kyberlib::hazmat::kex::Uake::new().client_confirm($send_b)
177 };
178}
179
180/// Initiates a Mutually Authenticated Key Exchange.
181///
182/// # Arguments
183///
184/// * `pubkey` - Input public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
185/// * `rng` - Random number generator implementing RngCore + CryptoRng.
186///
187/// # Returns
188///
189/// The bytes to send when initiating a mutual key exchange (AkeSendInit).
190#[cfg(feature = "hazmat")]
191#[macro_export]
192#[doc = "Macro to initiate a Mutually Authenticated Key Exchange."]
193macro_rules! kyberlib_ake_client_init {
194 ($pubkey:expr, $rng:expr) => {
195 kyberlib::hazmat::kex::Ake::new().client_init($pubkey, $rng)
196 };
197}
198
199/// Handles and authenticates the output of a `kyberlib_ake_client_init()` request.
200///
201/// # Arguments
202///
203/// * `ake_send_a` - The bytes received from the `kyberlib_ake_client_init()` request.
204/// * `pubkey` - The public key (an already allocated array of CRYPTO_PUBLICKEYBYTES bytes).
205/// * `secretkey` - The secret key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
206/// * `rng` - Random number generator implementing RngCore + CryptoRng.
207///
208/// # Returns
209///
210/// The bytes to send when responding to a mutual key exchange (AkeSendResponse).
211#[cfg(feature = "hazmat")]
212#[macro_export]
213#[doc = "Macro to handle the output of a Mutually Authenticated Key Exchange."]
214macro_rules! kyberlib_ake_server_receive {
215 ($ake_send_a:expr, $pubkey:expr, $secretkey:expr, $rng:expr) => {
216 kyberlib::hazmat::kex::Ake::new().server_receive(
217 $ake_send_a,
218 $pubkey,
219 $secretkey,
220 $rng,
221 )
222 };
223}
224
225/// Decapsulates and authenticates the shared secret from the output of
226/// `kyberlib_ake_server_receive()`.
227///
228/// # Arguments
229///
230/// * `send_b` - The bytes received from the `kyberlib_ake_server_receive()` request.
231/// * `secretkey` - The secret key (an already allocated array of CRYPTO_SECRETKEYBYTES bytes).
232///
233/// # Returns
234///
235/// Nothing (the shared secret is stored in the `Ake` struct).
236#[cfg(feature = "hazmat")]
237#[macro_export]
238#[doc = "Macro to decapsulate and authenticate the shared secret from a Mutually Authenticated Key Exchange."]
239macro_rules! kyberlib_ake_client_confirm {
240 ($send_b:expr, $secretkey:expr) => {
241 kyberlib::hazmat::kex::Ake::new()
242 .client_confirm($send_b, $secretkey)
243 };
244}