ML-KEM/ML-DSA part 2: param builder

Splitting up sfackler#2405 into a few parts as suggest by @alex.

This adds the param-builder and other openssl-sys changes.

Original commit message:

Add internal module to simplify working with OSSL_PARAM structure
We discussed that this API is not well suitable for the end users
but still, it required for several operations in OpenSSL 3.* so
instead of calling to FFI for every use of this API, this
introduces simple wrappers that allow building of the params
and their usage.

Signed-off-by: Jakub Jelen <[email protected]>
Co-authored-by: Justus Winter <[email protected]>

Author: swenson

openssl-sys/build/run_bindgen.rs

@@ -58,6 +58,7 @@ const INCLUDES: &str = "
 #endif
 
 #if OPENSSL_VERSION_NUMBER >= 0x30000000
+#include <openssl/param_build.h>
 #include <openssl/provider.h>
 #endif
 

openssl-sys/src/handwritten/mod.rs

@@ -16,6 +16,8 @@ pub use self::kdf::*;
 pub use self::object::*;
 pub use self::ocsp::*;
 #[cfg(ossl300)]
+pub use self::param_build::*;
+#[cfg(ossl300)]
 pub use self::params::*;
 pub use self::pem::*;
 pub use self::pkcs12::*;
@@ -56,6 +58,8 @@ mod kdf;
 mod object;
 mod ocsp;
 #[cfg(ossl300)]
+mod param_build;
+#[cfg(ossl300)]
 mod params;
 mod pem;
 mod pkcs12;

openssl-sys/src/handwritten/param_build.rs

@@ -0,0 +1,32 @@
+use super::super::*;
+use libc::*;
+
+/* OpenSSL 3.* only */
+
+extern "C" {
+    pub fn OSSL_PARAM_BLD_new() -> *mut OSSL_PARAM_BLD;
+    pub fn OSSL_PARAM_BLD_free(bld: *mut OSSL_PARAM_BLD);
+    pub fn OSSL_PARAM_BLD_push_BN(
+        bld: *mut OSSL_PARAM_BLD,
+        key: *const c_char,
+        bn: *const BIGNUM,
+    ) -> c_int;
+    pub fn OSSL_PARAM_BLD_push_utf8_string(
+        bld: *mut OSSL_PARAM_BLD,
+        key: *const c_char,
+        buf: *const c_char,
+        bsize: usize,
+    ) -> c_int;
+    pub fn OSSL_PARAM_BLD_push_octet_string(
+        bld: *mut OSSL_PARAM_BLD,
+        key: *const c_char,
+        buf: *const c_void,
+        bsize: usize,
+    ) -> c_int;
+    pub fn OSSL_PARAM_BLD_push_uint(
+        bld: *mut OSSL_PARAM_BLD,
+        key: *const c_char,
+        buf: c_uint,
+    ) -> c_int;
+    pub fn OSSL_PARAM_BLD_to_param(bld: *mut OSSL_PARAM_BLD) -> *mut OSSL_PARAM;
+}

openssl-sys/src/handwritten/types.rs

@@ -1140,6 +1140,9 @@ pub struct OSSL_PARAM {
     return_size: size_t,
 }
 
+#[cfg(ossl300)]
+pub enum OSSL_PARAM_BLD {}
+
 #[cfg(ossl300)]
 pub enum EVP_KDF {}
 #[cfg(ossl300)]

openssl/src/kdf.rs

@@ -25,15 +25,24 @@ impl Drop for EvpKdfCtx {
 cfg_if::cfg_if! {
     if #[cfg(all(ossl320, not(osslconf = "OPENSSL_NO_ARGON2")))] {
         use std::cmp;
-        use std::ffi::c_void;
         use std::ffi::CStr;
-        use std::mem::MaybeUninit;
         use std::ptr;
         use foreign_types::ForeignTypeRef;
         use libc::c_char;
         use crate::{cvt, cvt_p};
         use crate::lib_ctx::LibCtxRef;
         use crate::error::ErrorStack;
+        use crate::ossl_param::OsslParamBuilder;
+
+        const OSSL_KDF_PARAM_PASSWORD: &[u8; 5] = b"pass\0";
+        const OSSL_KDF_PARAM_SALT: &[u8; 5] = b"salt\0";
+        const OSSL_KDF_PARAM_SECRET: &[u8; 7] = b"secret\0";
+        const OSSL_KDF_PARAM_ITER: &[u8; 5] = b"iter\0";
+        const OSSL_KDF_PARAM_SIZE: &[u8; 5] = b"size\0";
+        const OSSL_KDF_PARAM_THREADS: &[u8; 8] = b"threads\0";
+        const OSSL_KDF_PARAM_ARGON2_AD: &[u8; 3] = b"ad\0";
+        const OSSL_KDF_PARAM_ARGON2_LANES: &[u8; 6] = b"lanes\0";
+        const OSSL_KDF_PARAM_ARGON2_MEMCOST: &[u8; 8] = b"memcost\0";
 
         #[allow(clippy::too_many_arguments)]
         pub fn argon2d(
@@ -94,72 +103,40 @@ cfg_if::cfg_if! {
             salt: &[u8],
             ad: Option<&[u8]>,
             secret: Option<&[u8]>,
-            mut iter: u32,
-            mut lanes: u32,
-            mut memcost: u32,
+            iter: u32,
+            lanes: u32,
+            memcost: u32,
             out: &mut [u8],
         ) -> Result<(), ErrorStack> {
-            unsafe {
+            let libctx = ctx.map_or(ptr::null_mut(), ForeignTypeRef::as_ptr);
+            let max_threads = unsafe {
                 ffi::init();
-                let libctx = ctx.map_or(ptr::null_mut(), ForeignTypeRef::as_ptr);
-
-                let max_threads = ffi::OSSL_get_max_threads(libctx);
-                let mut threads = 1;
-                // If max_threads is 0, then this isn't a threaded build.
-                // If max_threads is > u32::MAX we need to clamp since
-                // argon2's threads parameter is a u32.
-                if max_threads > 0 {
-                    threads = cmp::min(lanes, cmp::min(max_threads, u32::MAX as u64) as u32);
-                }
-                let mut params: [ffi::OSSL_PARAM; 10] =
-                    core::array::from_fn(|_| MaybeUninit::<ffi::OSSL_PARAM>::zeroed().assume_init());
-                let mut idx = 0;
-                params[idx] = ffi::OSSL_PARAM_construct_octet_string(
-                    b"pass\0".as_ptr() as *const c_char,
-                    pass.as_ptr() as *mut c_void,
-                    pass.len(),
-                );
-                idx += 1;
-                params[idx] = ffi::OSSL_PARAM_construct_octet_string(
-                    b"salt\0".as_ptr() as *const c_char,
-                    salt.as_ptr() as *mut c_void,
-                    salt.len(),
-                );
-                idx += 1;
-                params[idx] =
-                    ffi::OSSL_PARAM_construct_uint(b"threads\0".as_ptr() as *const c_char, &mut threads);
-                idx += 1;
-                params[idx] =
-                    ffi::OSSL_PARAM_construct_uint(b"lanes\0".as_ptr() as *const c_char, &mut lanes);
-                idx += 1;
-                params[idx] =
-                    ffi::OSSL_PARAM_construct_uint(b"memcost\0".as_ptr() as *const c_char, &mut memcost);
-                idx += 1;
-                params[idx] =
-                    ffi::OSSL_PARAM_construct_uint(b"iter\0".as_ptr() as *const c_char, &mut iter);
-                idx += 1;
-                let mut size = out.len() as u32;
-                params[idx] =
-                    ffi::OSSL_PARAM_construct_uint(b"size\0".as_ptr() as *const c_char, &mut size);
-                idx += 1;
-                if let Some(ad) = ad {
-                    params[idx] = ffi::OSSL_PARAM_construct_octet_string(
-                        b"ad\0".as_ptr() as *const c_char,
-                        ad.as_ptr() as *mut c_void,
-                        ad.len(),
-                    );
-                    idx += 1;
-                }
-                if let Some(secret) = secret {
-                    params[idx] = ffi::OSSL_PARAM_construct_octet_string(
-                        b"secret\0".as_ptr() as *const c_char,
-                        secret.as_ptr() as *mut c_void,
-                        secret.len(),
-                    );
-                    idx += 1;
-                }
-                params[idx] = ffi::OSSL_PARAM_construct_end();
-
+                ffi::OSSL_get_max_threads(libctx)
+            };
+            let mut threads = 1;
+            // If max_threads is 0, then this isn't a threaded build.
+            // If max_threads is > u32::MAX we need to clamp since
+            // argon2id's threads parameter is a u32.
+            if max_threads > 0 {
+                threads = cmp::min(lanes, cmp::min(max_threads, u32::MAX as u64) as u32);
+            }
+            let bld = OsslParamBuilder::new()?;
+            bld.add_octet_string(OSSL_KDF_PARAM_PASSWORD, pass)?;
+            bld.add_octet_string(OSSL_KDF_PARAM_SALT, salt)?;
+            bld.add_uint(OSSL_KDF_PARAM_THREADS, threads)?;
+            bld.add_uint(OSSL_KDF_PARAM_ARGON2_LANES, lanes)?;
+            bld.add_uint(OSSL_KDF_PARAM_ARGON2_MEMCOST, memcost)?;
+            bld.add_uint(OSSL_KDF_PARAM_ITER, iter)?;
+            let size = out.len() as u32;
+            bld.add_uint(OSSL_KDF_PARAM_SIZE, size)?;
+            if let Some(ad) = ad {
+                bld.add_octet_string(OSSL_KDF_PARAM_ARGON2_AD, ad)?;
+            }
+            if let Some(secret) = secret {
+                bld.add_octet_string(OSSL_KDF_PARAM_SECRET, secret)?;
+            }
+            let params = bld.to_param()?;
+            unsafe {
                 let argon2 = EvpKdf(cvt_p(ffi::EVP_KDF_fetch(
                     libctx,
                     kdf_identifier.as_ptr() as *const c_char,

openssl/src/lib.rs

@@ -177,6 +177,8 @@ pub mod memcmp;
 pub mod nid;
 #[cfg(not(osslconf = "OPENSSL_NO_OCSP"))]
 pub mod ocsp;
+#[cfg(ossl300)]
+mod ossl_param;
 pub mod pkcs12;
 pub mod pkcs5;
 #[cfg(not(any(boringssl, awslc)))]

openssl/src/ossl_param.rs

@@ -0,0 +1,182 @@
+//! OSSL_PARAM management for OpenSSL 3.*
+//!
+//! The OSSL_PARAM structure represents generic attribute that can represent various
+//! properties in OpenSSL, including keys and operations.
+//!
+//! For convinience, the OSSL_PARAM_BLD builder can be used to dynamically construct
+//! these structure.
+//!
+//! Note, that this module is available only in OpenSSL 3.* and
+//! only internally for this crate!
+
+// Depending on which version of OpenSSL is used, and which algorithms
+// are exposed in the bindings, not all of these functions are used.
+#![allow(dead_code)]
+
+use crate::bn::{BigNum, BigNumRef};
+use crate::error::ErrorStack;
+use crate::util;
+use crate::{cvt, cvt_p};
+use foreign_types::{ForeignType, ForeignTypeRef};
+use libc::{c_char, c_uint, c_void};
+use openssl_macros::corresponds;
+use std::ffi::CStr;
+use std::ptr;
+
+foreign_type_and_impl_send_sync! {
+    type CType = ffi::OSSL_PARAM;
+    fn drop = ffi::OSSL_PARAM_free;
+
+    /// `OsslParam` constructed using `OsslParamBuilder`.
+    pub struct OsslParam;
+    /// Reference to `OsslParam`.
+    pub struct OsslParamRef;
+}
+
+impl OsslParam {}
+
+impl OsslParamRef {
+    /// Locates the `OsslParam` in the `OsslParam` array
+    #[corresponds(OSSL_PARAM_locate)]
+    pub fn locate(&self, key: &[u8]) -> Result<&OsslParamRef, ErrorStack> {
+        unsafe {
+            let param = cvt_p(ffi::OSSL_PARAM_locate(
+                self.as_ptr(),
+                key.as_ptr() as *const c_char,
+            ))?;
+            Ok(OsslParamRef::from_ptr(param))
+        }
+    }
+
+    /// Get `BigNum` from the current `OsslParam`
+    #[corresponds(OSSL_PARAM_get_BN)]
+    pub fn get_bn(&self) -> Result<BigNum, ErrorStack> {
+        unsafe {
+            let mut bn: *mut ffi::BIGNUM = ptr::null_mut();
+            cvt(ffi::OSSL_PARAM_get_BN(self.as_ptr(), &mut bn))?;
+            Ok(BigNum::from_ptr(bn))
+        }
+    }
+
+    /// Get `&str` from the current `OsslParam`
+    #[corresponds(OSSL_PARAM_get_utf8_string)]
+    pub fn get_utf8_string(&self) -> Result<&str, ErrorStack> {
+        unsafe {
+            let mut val: *const c_char = ptr::null_mut();
+            cvt(ffi::OSSL_PARAM_get_utf8_string_ptr(self.as_ptr(), &mut val))?;
+            Ok(CStr::from_ptr(val).to_str().unwrap())
+        }
+    }
+
+    /// Get octet string (as `&[u8]) from the current `OsslParam`
+    #[corresponds(OSSL_PARAM_get_octet_string)]
+    pub fn get_octet_string(&self) -> Result<&[u8], ErrorStack> {
+        unsafe {
+            let mut val: *const c_void = ptr::null_mut();
+            let mut val_len: usize = 0;
+            cvt(ffi::OSSL_PARAM_get_octet_string_ptr(
+                self.as_ptr(),
+                &mut val,
+                &mut val_len,
+            ))?;
+            Ok(util::from_raw_parts(val as *const u8, val_len))
+        }
+    }
+}
+
+foreign_type_and_impl_send_sync! {
+    type CType = ffi::OSSL_PARAM_BLD;
+    fn drop = ffi::OSSL_PARAM_BLD_free;
+
+    /// Builder used to construct `OsslParam`.
+    pub struct OsslParamBuilder;
+    /// Reference to `OsslParamBuilder`.
+    pub struct OsslParamBuilderRef;
+}
+
+impl OsslParamBuilder {
+    /// Returns a builder for a OsslParam arrays.
+    ///
+    /// The array is initially empty.
+    #[corresponds(OSSL_PARAM_BLD_new)]
+    pub fn new() -> Result<OsslParamBuilder, ErrorStack> {
+        unsafe {
+            ffi::init();
+
+            cvt_p(ffi::OSSL_PARAM_BLD_new()).map(OsslParamBuilder)
+        }
+    }
+
+    /// Constructs the `OsslParam`.
+    #[corresponds(OSSL_PARAM_BLD_to_param)]
+    pub fn to_param(&self) -> Result<OsslParam, ErrorStack> {
+        unsafe {
+            let params = cvt_p(ffi::OSSL_PARAM_BLD_to_param(self.0))?;
+            Ok(OsslParam::from_ptr(params))
+        }
+    }
+}
+
+impl OsslParamBuilderRef {
+    /// Adds a `BigNum` to `OsslParamBuilder`.
+    ///
+    /// Note, that both key and bn need to exist until the `to_param` is called!
+    #[corresponds(OSSL_PARAM_BLD_push_BN)]
+    pub fn add_bn(&self, key: &[u8], bn: &BigNumRef) -> Result<(), ErrorStack> {
+        unsafe {
+            cvt(ffi::OSSL_PARAM_BLD_push_BN(
+                self.as_ptr(),
+                key.as_ptr() as *const c_char,
+                bn.as_ptr(),
+            ))
+            .map(|_| ())
+        }
+    }
+
+    /// Adds a utf8 string to `OsslParamBuilder`.
+    ///
+    /// Note, that both `key` and `buf` need to exist until the `to_param` is called!
+    #[corresponds(OSSL_PARAM_BLD_push_utf8_string)]
+    pub fn add_utf8_string(&self, key: &[u8], buf: &str) -> Result<(), ErrorStack> {
+        unsafe {
+            cvt(ffi::OSSL_PARAM_BLD_push_utf8_string(
+                self.as_ptr(),
+                key.as_ptr() as *const c_char,
+                buf.as_ptr() as *const c_char,
+                buf.len(),
+            ))
+            .map(|_| ())
+        }
+    }
+
+    /// Adds a octet string to `OsslParamBuilder`.
+    ///
+    /// Note, that both `key` and `buf` need to exist until the `to_param` is called!
+    #[corresponds(OSSL_PARAM_BLD_push_octet_string)]
+    pub fn add_octet_string(&self, key: &[u8], buf: &[u8]) -> Result<(), ErrorStack> {
+        unsafe {
+            cvt(ffi::OSSL_PARAM_BLD_push_octet_string(
+                self.as_ptr(),
+                key.as_ptr() as *const c_char,
+                buf.as_ptr() as *const c_void,
+                buf.len(),
+            ))
+            .map(|_| ())
+        }
+    }
+
+    /// Adds a unsigned int to `OsslParamBuilder`.
+    ///
+    /// Note, that both `key` and `buf` need to exist until the `to_param` is called!
+    #[corresponds(OSSL_PARAM_BLD_push_uint)]
+    pub fn add_uint(&self, key: &[u8], val: u32) -> Result<(), ErrorStack> {
+        unsafe {
+            cvt(ffi::OSSL_PARAM_BLD_push_uint(
+                self.as_ptr(),
+                key.as_ptr() as *const c_char,
+                val as c_uint,
+            ))
+            .map(|_| ())
+        }
+    }
+}