Add support for Message based encryption and decryption

Signed-off-by: Jakub Jelen <jjelen@redhat.com>

Author: Jakuje

cryptoki/src/mechanism/aead.rs

@@ -89,3 +89,105 @@ impl<'a> GcmParams<'a> {
         self.inner.ulTagBits.into()
     }
 }
+
+/// The GCM generator function for the Initialization Vector
+#[derive(Debug, Clone, Copy)]
+pub enum GeneratorFunction {
+    /// `CKG_NO_GENERATE` no IV generation is done.
+    NoGenerate,
+    /// `CKG_GENERATE` the non-fixed part of IV is generated internally
+    Generate,
+    /// `CKG_GENERATE_COUNTER` the non-fixed part of IV is generated internally by incrementing
+    /// counter. Initially zero.
+    GenerateCounter,
+    /// `CKG_GENERATE_RANDOM` the non-fixed part of IV is generated internally by PRNG
+    GenerateRandom,
+    /// `CKG_GENERATE_COUNTER_XOR` the non-fixed part of IV xored with incrementing counter.
+    GenerateCounterXor,
+}
+
+/// Parameters for message based AES-GCM operations.
+#[derive(Debug, Copy, Clone)]
+#[repr(transparent)]
+pub struct GcmMessageParams<'a> {
+    inner: CK_GCM_MESSAGE_PARAMS,
+    _marker: PhantomData<&'a mut [u8]>,
+}
+
+impl<'a> GcmMessageParams<'a> {
+    /// Construct GCM parameters for message based operations
+    ///
+    /// # Arguments
+    ///
+    /// `iv` - The initialization vector.  This must be non-empty.  In PKCS#11
+    /// 3.0, the maximum length of the IV is 256 bytes.  A 12-byte IV may be
+    /// processed more efficiently than other lengths.
+    ///
+    /// `iv_fixed_bits` - number of bits of the original IV to preserve when
+    /// generating an new IV. These bits are counted from the Most significant
+    /// bits (to the right).
+    ///
+    /// `iv_generator` - Function used to generate a new IV. Each IV must be
+    /// unique for a given session.
+    ///
+    /// `tag` - The buffer to store the tag. Either to be passed in or returned if generated by
+    /// token.
+    ///
+    /// # Errors
+    /// This function returns an error if the length of `iv` does not
+    /// fit into an [Ulong].
+    pub fn new(
+        iv: &'a mut [u8],
+        iv_fixed_bits: Ulong,
+        iv_generator: GeneratorFunction,
+        tag: &'a mut [u8],
+    ) -> Result<Self, Error> {
+        let tag_bits = tag.len() * 8;
+        Ok(GcmMessageParams {
+            inner: CK_GCM_MESSAGE_PARAMS {
+                pIv: iv.as_mut_ptr(),
+                ulIvLen: iv.len().try_into()?,
+                ulIvFixedBits: iv_fixed_bits.into(),
+                ivGenerator: match iv_generator {
+                    GeneratorFunction::NoGenerate => CKG_NO_GENERATE,
+                    GeneratorFunction::Generate => CKG_GENERATE,
+                    GeneratorFunction::GenerateCounter => CKG_GENERATE_COUNTER,
+                    GeneratorFunction::GenerateRandom => CKG_GENERATE_RANDOM,
+                    GeneratorFunction::GenerateCounterXor => CKG_GENERATE_COUNTER_XOR,
+                },
+                pTag: tag.as_mut_ptr(),
+                ulTagBits: tag_bits.try_into()?,
+            },
+            _marker: PhantomData,
+        })
+    }
+
+    /// The initialization vector.
+    pub fn iv(&mut self) -> &mut [u8] {
+        // SAFETY: In the constructor, the IV always comes from a &'a mut [u8]
+        unsafe { slice::from_raw_parts_mut(self.inner.pIv, self.inner.ulIvLen as _) }
+    }
+
+    /// The length, in bits, of fixed part of the IV.
+    pub fn iv_fixed_bits(&self) -> Ulong {
+        self.inner.ulIvFixedBits.into()
+    }
+
+    /// The IV generator.
+    pub fn iv_generator(&self) -> GeneratorFunction {
+        match self.inner.ivGenerator {
+            CKG_NO_GENERATE => GeneratorFunction::NoGenerate,
+            CKG_GENERATE => GeneratorFunction::Generate,
+            CKG_GENERATE_COUNTER => GeneratorFunction::GenerateCounter,
+            CKG_GENERATE_RANDOM => GeneratorFunction::GenerateRandom,
+            CKG_GENERATE_COUNTER_XOR => GeneratorFunction::GenerateCounterXor,
+            _ => unreachable!(),
+        }
+    }
+
+    /// The authentication tag.
+    pub fn tag(&self) -> &'a [u8] {
+        // SAFETY: In the constructor, the tag always comes from a &'a [u8]
+        unsafe { slice::from_raw_parts(self.inner.pTag, (self.inner.ulTagBits / 8) as _) }
+    }
+}

cryptoki/src/mechanism/mechanism_info.rs

@@ -29,6 +29,9 @@ bitflags! {
         const EC_OID = CKF_EC_OID;
         const EC_UNCOMPRESS = CKF_EC_UNCOMPRESS;
         const EC_COMPRESS = CKF_EC_COMPRESS;
+        const MESSAGE_ENCRYPT = CKF_MESSAGE_ENCRYPT;
+        const MESSAGE_DECRYPT = CKF_MESSAGE_DECRYPT;
+        const MULTI_MESSAGE = CKF_MULTI_MESSAGE;
     }
 }
 
@@ -228,6 +231,27 @@ impl MechanismInfo {
     pub fn ec_compressed(&self) -> bool {
         self.flags.contains(MechanismInfoFlags::EC_COMPRESS)
     }
+
+    /// True if the mechanism can be used to encrypt messages
+    ///
+    /// See [`Session::encrypt_message`](crate::session::Session::encrypt_message)
+    pub fn message_encrypt(&self) -> bool {
+        self.flags.contains(MechanismInfoFlags::MESSAGE_ENCRYPT)
+    }
+
+    /// True if the mechanism can be used to decrypt encrypted messages
+    ///
+    /// See [`Session::decrypt`](crate::session::Session::decrypt_message)
+    pub fn message_decrypt(&self) -> bool {
+        self.flags.contains(MechanismInfoFlags::MESSAGE_DECRYPT)
+    }
+
+    /// True if the mechanism can be used with encrypt/decrypt_message_begin API.
+    /// One of message_* flag must also be set.
+    ///
+    pub fn multi_message(&self) -> bool {
+        self.flags.contains(MechanismInfoFlags::MULTI_MESSAGE)
+    }
 }
 
 impl std::fmt::Display for MechanismInfo {
@@ -269,7 +293,8 @@ mod test {
 HW | ENCRYPT | DECRYPT | DIGEST | SIGN | SIGN_RECOVER | VERIFY | \
 VERIFY_RECOVER | GENERATE | GENERATE_KEY_PAIR | WRAP | UNWRAP | DERIVE | \
 EXTENSION | EC_F_P | EC_F_2M | EC_ECPARAMETERS | EC_NAMEDCURVE | \
-EC_OID | EC_UNCOMPRESS | EC_COMPRESS";
+EC_OID | EC_UNCOMPRESS | EC_COMPRESS | MESSAGE_ENCRYPT | MESSAGE_DECRYPT | \
+MULTI_MESSAGE";
         let all = MechanismInfoFlags::all();
         let observed = format!("{all:#?}");
         println!("{observed}");

cryptoki/src/mechanism/mod.rs

@@ -805,6 +805,9 @@ pub enum Mechanism<'a> {
     AesKeyWrapPad,
     /// AES-GCM mechanism
     AesGcm(aead::GcmParams<'a>),
+    /// AES-GCM mechanism with message based API and parameters
+    // TODO Should we reuse the AesGcm and use Option<> to select parameter?
+    AesGcmMessage(aead::GcmMessageParams<'a>),
     /// AES-CBC-ENCRYPT-DATA mechanism
     ///
     /// The parameter to this mechanism is the initialization vector and the message to encrypt. These mechanisms allow
@@ -986,6 +989,7 @@ impl Mechanism<'_> {
             Mechanism::AesKeyWrap => MechanismType::AES_KEY_WRAP,
             Mechanism::AesKeyWrapPad => MechanismType::AES_KEY_WRAP_PAD,
             Mechanism::AesGcm(_) => MechanismType::AES_GCM,
+            Mechanism::AesGcmMessage(_) => MechanismType::AES_GCM,
             Mechanism::AesCbcEncryptData(_) => MechanismType::AES_CBC_ENCRYPT_DATA,
             Mechanism::AesCMac => MechanismType::AES_CMAC,
             Mechanism::RsaPkcsKeyPairGen => MechanismType::RSA_PKCS_KEY_PAIR_GEN,
@@ -1072,6 +1076,13 @@ impl From<&Mechanism<'_>> for CK_MECHANISM {
                     .try_into()
                     .expect("usize can not fit in CK_ULONG"),
             },
+            Mechanism::AesGcmMessage(params) => CK_MECHANISM {
+                mechanism,
+                pParameter: params as *const _ as *mut c_void,
+                ulParameterLen: size_of::<CK_GCM_MESSAGE_PARAMS>()
+                    .try_into()
+                    .expect("usize can not fit in CK_ULONG"),
+            },
             Mechanism::RsaPkcsPss(params)
             | Mechanism::Sha1RsaPkcsPss(params)
             | Mechanism::Sha256RsaPkcsPss(params)
@@ -1153,3 +1164,26 @@ fn make_mechanism<T>(mechanism: CK_MECHANISM_TYPE, param: &T) -> CK_MECHANISM {
             .expect("usize can not fit in CK_ULONG"),
     }
 }
+
+/// Type defining a specific mechanism parameters used for message based operations
+#[derive(Debug)]
+pub enum MessageParam<'a> {
+    /// AES-GCM mechanism with message based API and parameters
+    AesGcmMessage(aead::GcmMessageParams<'a>),
+}
+
+impl MessageParam<'_> {
+    pub(crate) fn as_ptr(&self) -> *mut ::std::os::raw::c_void {
+        match self {
+            MessageParam::AesGcmMessage(param) => param as *const _ as *mut c_void,
+        }
+    }
+
+    pub(crate) fn len(&self) -> CK_ULONG {
+        match self {
+            MessageParam::AesGcmMessage(_) => size_of::<CK_GCM_MESSAGE_PARAMS>()
+                .try_into()
+                .expect("usize can not fit in CK_ULONG"),
+        }
+    }
+}

cryptoki/src/session/message_decryption.rs

@@ -0,0 +1,142 @@
+// Copyright 2025 Contributors to the Parsec project.
+// SPDX-License-Identifier: Apache-2.0
+//! Encrypting data
+
+use crate::context::Function;
+use crate::error::{Result, Rv};
+use crate::mechanism::{Mechanism, MessageParam};
+use crate::object::ObjectHandle;
+use crate::session::Session;
+use cryptoki_sys::*;
+use std::convert::TryInto;
+
+impl Session {
+    /// Prepare a session for one or more Message-based decryption using the same mechanism and key
+    pub fn message_decrypt_init(&self, mechanism: &Mechanism, key: ObjectHandle) -> Result<()> {
+        let mut mechanism: CK_MECHANISM = mechanism.into();
+
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_MessageDecryptInit)(
+                self.handle(),
+                &mut mechanism as CK_MECHANISM_PTR,
+                key.handle(),
+            ))
+            .into_result(Function::MessageDecryptInit)?;
+        }
+
+        Ok(())
+    }
+
+    /// Decrypts a message in single part
+    pub fn decrypt_message(
+        &self,
+        param: &MessageParam,
+        aad: &[u8],
+        encrypted_data: &[u8],
+    ) -> Result<Vec<u8>> {
+        let mut data_len = 0;
+        // Get the output buffer length
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_DecryptMessage)(
+                self.handle(),
+                param.as_ptr(),
+                param.len(),
+                aad.as_ptr() as *mut u8,
+                aad.len().try_into()?,
+                encrypted_data.as_ptr() as *mut u8,
+                encrypted_data.len().try_into()?,
+                std::ptr::null_mut(),
+                &mut data_len,
+            ))
+            .into_result(Function::DecryptMessage)?;
+        }
+
+        let mut data = vec![0; data_len.try_into()?];
+
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_DecryptMessage)(
+                self.handle(),
+                param.as_ptr(),
+                param.len(),
+                aad.as_ptr() as *mut u8,
+                aad.len().try_into()?,
+                encrypted_data.as_ptr() as *mut u8,
+                encrypted_data.len().try_into()?,
+                data.as_mut_ptr(),
+                &mut data_len,
+            ))
+            .into_result(Function::DecryptMessage)?;
+        }
+
+        data.resize(data_len.try_into()?, 0);
+
+        Ok(data)
+    }
+
+    /// Begin multi-part message decryption operation
+    pub fn decrypt_message_begin(&self, param: MessageParam, aad: &[u8]) -> Result<()> {
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_DecryptMessageBegin)(
+                self.handle(),
+                param.as_ptr(),
+                param.len(),
+                aad.as_ptr() as *mut u8,
+                aad.len().try_into()?,
+            ))
+            .into_result(Function::DecryptMessageBegin)
+        }
+    }
+
+    /// Continue mutli-part message decryption operation
+    pub fn decrypt_message_next(
+        &self,
+        param: MessageParam,
+        encrypted_data: &[u8],
+        end: bool,
+    ) -> Result<Vec<u8>> {
+        let mut data_len = 0;
+        // Get the output buffer length
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_DecryptMessageNext)(
+                self.handle(),
+                param.as_ptr(),
+                param.len(),
+                encrypted_data.as_ptr() as *mut u8,
+                encrypted_data.len().try_into()?,
+                std::ptr::null_mut(),
+                &mut data_len,
+                if end { CKF_END_OF_MESSAGE } else { 0 },
+            ))
+            .into_result(Function::DecryptMessageNext)?;
+        }
+        let mut data = vec![0; data_len.try_into()?];
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_DecryptMessageNext)(
+                self.handle(),
+                param.as_ptr(),
+                param.len(),
+                encrypted_data.as_ptr() as *mut u8,
+                encrypted_data.len().try_into()?,
+                data.as_mut_ptr(),
+                &mut data_len,
+                if end { CKF_END_OF_MESSAGE } else { 0 },
+            ))
+            .into_result(Function::DecryptMessageNext)?;
+        }
+        data.resize(data_len.try_into()?, 0);
+
+        Ok(data)
+    }
+
+    /// Finishes Message-based decryption process
+    pub fn message_decrypt_final(&self) -> Result<()> {
+        unsafe {
+            Rv::from(get_pkcs11!(self.client(), C_MessageDecryptFinal)(
+                self.handle(),
+            ))
+            .into_result(Function::MessageDecryptFinal)?;
+        }
+
+        Ok(())
+    }
+}