liboscore 0.2.7

//! Wrapper around the `liboscore` C library, which implements the [OSCORE
//! RFC](https://datatracker.ietf.org/doc/html/rfc8613), and thus symmetric encryption for the
//! [CoAP protocol](https://datatracker.ietf.org/doc/html/rfc7252).
//!
//! To ensure proper setup and teardown of data structures that include references, several
//! functions in this library take callbacks in which the accessed data is used; for example, an
//! encrypted message is passed to [`protect_request()`] along with a callback, and the plaintext
//! is then passed back to the caller in that callback closure inside `protect_request()`. While
//! nothing in this library is a potentially-blocking operation (and thus worht async'ifying),
//! there might be asynchronous code in callbacks: Therefore, asynchronous versions of the
//! functions are provided that take asynchronous callbacks. They are functionally identical.
//! Future versions of this crate might consider other idioms rather than callbacks (e.g.
//! destructors) to avoid going through callbacks altogether.
#![no_std]
// We need these linked in
extern crate liboscore_cryptobackend;
extern crate liboscore_msgbackend;

use core::mem::MaybeUninit;

mod platform;

// FIXME: pub only for tests?
pub mod raw;

mod impl_message;
pub use impl_message::ProtectedMessage;

mod oscore_option;
pub use oscore_option::OscoreOption;

mod algorithms;
pub use algorithms::{AeadAlg, AlgorithmNotSupported, HkdfAlg};

mod primitive;
pub use primitive::{DeriveError, PrimitiveContext, PrimitiveImmutables};

#[track_caller]
#[inline]
fn poll_once_expect_immediate<R>(future: impl core::future::Future<Output = R>) -> R {
    let future = core::pin::pin!(future);
    let mut context = core::task::Context::from_waker(core::task::Waker::noop());
    match future.poll(&mut context) {
        core::task::Poll::Ready(r) => r,
        core::task::Poll::Pending => unreachable!("The function's only await point is in the callback, and the provided callback has none."),
    }
}

#[non_exhaustive]
#[derive(Debug, Copy, Clone)]
pub enum PrepareError {
    /// The security context can not provide protection for this message
    SecurityContextUnavailable,
}

impl PrepareError {
    /// Construct a Rust error type out of the C type
    ///
    /// This returns a result to be easily usable with the `?` operator.
    fn new(input: raw::oscore_prepare_result) -> Result<(), Self> {
        match input {
            raw::oscore_prepare_result_OSCORE_PREPARE_OK => Ok(()),
            raw::oscore_prepare_result_OSCORE_PREPARE_SECCTX_UNAVAILABLE => {
                Err(PrepareError::SecurityContextUnavailable)
            }
            _ => unreachable!(),
        }
    }
}

#[non_exhaustive]
#[derive(Debug, Copy, Clone)]
pub enum FinishError {
    Size,
    Crypto,
}

impl FinishError {
    /// Construct a Rust error type out of the C type
    ///
    /// This returns a result to be easily usable with the `?` operator.
    fn new(input: raw::oscore_finish_result) -> Result<(), Self> {
        match input {
            raw::oscore_finish_result_OSCORE_FINISH_OK => Ok(()),
            raw::oscore_finish_result_OSCORE_FINISH_ERROR_SIZE => Err(FinishError::Size),
            raw::oscore_finish_result_OSCORE_FINISH_ERROR_CRYPTO => Err(FinishError::Crypto),
            _ => unreachable!(),
        }
    }
}

#[derive(Debug, Copy, Clone)]
pub enum ProtectError {
    Prepare(PrepareError),
    Finish(FinishError),
}

impl From<PrepareError> for ProtectError {
    fn from(e: PrepareError) -> Self {
        ProtectError::Prepare(e)
    }
}

impl From<FinishError> for ProtectError {
    fn from(e: FinishError) -> Self {
        ProtectError::Finish(e)
    }
}

#[non_exhaustive]
#[derive(Debug, Copy, Clone)]
pub enum UnprotectRequestError {
    Duplicate,
    Invalid,
}

impl UnprotectRequestError {
    /// Construct a Rust error type out of the C type
    ///
    /// This returns a result to be easily usable with the `?` operator.
    fn new(input: raw::oscore_unprotect_request_result) -> Result<(), Self> {
        match input {
            raw::oscore_unprotect_request_result_OSCORE_UNPROTECT_REQUEST_OK => Ok(()),
            raw::oscore_unprotect_request_result_OSCORE_UNPROTECT_REQUEST_DUPLICATE => {
                Err(UnprotectRequestError::Duplicate)
            }
            raw::oscore_unprotect_request_result_OSCORE_UNPROTECT_REQUEST_INVALID => {
                Err(UnprotectRequestError::Invalid)
            }
            _ => unreachable!(),
        }
    }
}

#[non_exhaustive]
#[derive(Debug, Copy, Clone)]
pub enum UnprotectResponseError {
    Invalid,
}

impl UnprotectResponseError {
    /// Construct a Rust error type out of the C type
    ///
    /// This returns a result to be easily usable with the `?` operator.
    fn new(input: raw::oscore_unprotect_response_result) -> Result<(), Self> {
        match input {
            raw::oscore_unprotect_response_result_OSCORE_UNPROTECT_RESPONSE_OK => Ok(()),
            raw::oscore_unprotect_response_result_OSCORE_UNPROTECT_RESPONSE_INVALID => {
                Err(UnprotectResponseError::Invalid)
            }
            _ => unreachable!(),
        }
    }
}

/// Protects an OSCORE request.
///
/// The message into which the ciphertext is to be written is passed in as `request`; the actual
/// writing happens while there is a protected message configured during a callback.
///
/// Along with any output of the callback, this produces a request identity that will be needed
/// later to unprotect the response.
///
/// For sync callbacks, see [`protect_request`].
// FIXME we should carry the context around, but that'd require it to have a shared portion that we
// can then clone and combine with the oscore_requestid_t.
pub async fn async_protect_request<R>(
    request: impl liboscore_msgbackend::WithMsgNative,
    ctx: &mut PrimitiveContext,
    writer: impl AsyncFnOnce(&mut ProtectedMessage) -> R,
) -> Result<(raw::oscore_requestid_t, R), ProtectError> {
    request
        .async_with_msg_native(async |msg| {
            let mut plaintext = MaybeUninit::uninit();
            let mut request_data = MaybeUninit::uninit();
            // Safety: Everything that needs to be initialized is
            let prepare_ok = unsafe {
                raw::oscore_prepare_request(
                    msg,
                    plaintext.as_mut_ptr(),
                    ctx.as_mut(),
                    request_data.as_mut_ptr(),
                )
            };
            PrepareError::new(prepare_ok)?;
            // Safety: Initialized after successful return
            let plaintext = unsafe { plaintext.assume_init() };
            let request_data = unsafe { request_data.assume_init() };

            let mut plaintext = crate::ProtectedMessage::new(plaintext);
            let user_carry = writer(&mut plaintext).await;
            plaintext.flush();
            let mut plaintext = plaintext.into_inner();

            let mut returned_msg = MaybeUninit::uninit();
            // Safety: Everything that needs to be initialized is
            let finish_ok =
                unsafe { raw::oscore_encrypt_message(&mut plaintext, returned_msg.as_mut_ptr()) };
            FinishError::new(finish_ok)?;
            // We're discarding the native message that's in returned_msg. If it were owned (which
            // would be a valid choice for with_inmemory_write), the closure might be required to
            // return it, but it currently isn't.

            Ok((request_data, user_carry))
        })
        .await
}

/// Synchronous version of [`async_protect_request`], see there.
pub fn protect_request<R>(
    request: impl liboscore_msgbackend::WithMsgNative,
    ctx: &mut PrimitiveContext,
    writer: impl FnOnce(&mut ProtectedMessage) -> R,
) -> Result<(raw::oscore_requestid_t, R), ProtectError> {
    poll_once_expect_immediate(async_protect_request(request, ctx, async |m| writer(m)))
}

/// Unprotects an OSCORE request.
///
/// The message from which the ciphertext is read in as `request` (and taken mutably because it is
/// decrypted in-place, rendering it nonsensical to any other CoAP processing); the actual
/// processing of the plaintext happens while there is a protected message configured during a
/// callback.
///
/// Along with the output of the callback, this produces a request identity that will be needed to
/// later protect the response(s).
///
/// For sync callbacks, see [`unprotect_request`].
pub async fn async_unprotect_request<R>(
    request: impl liboscore_msgbackend::WithMsgNative,
    oscoreoption: OscoreOption<'_>, // Here's where we need to cheat a bit: We both take the message
    // writably, *and* we take data out of that message through
    // another pointer. This is legal because we don't alter any
    // option values, or more precisely, we don't alter the OSCORE
    // option's value, but yet it's slightly uncomfortable (and
    // users may need to resort to unsafe to call this).
    ctx: &mut PrimitiveContext,
    reader: impl AsyncFnOnce(&ProtectedMessage) -> R,
) -> Result<(raw::oscore_requestid_t, R), UnprotectRequestError> {
    request
        .async_with_msg_native(async |nativemsg| {
            let mut plaintext = MaybeUninit::uninit();
            let mut request_data = MaybeUninit::uninit();
            let decrypt_ok = unsafe {
                raw::oscore_unprotect_request(
                    nativemsg,
                    plaintext.as_mut_ptr(),
                    &oscoreoption.into_inner(),
                    ctx.as_mut(),
                    request_data.as_mut_ptr(),
                )
            };
            // We could introduce extra handling of Invalid if our handlers had a notion of being (even
            // security-wise) idempotent, or if we supported B.1 recovery here.
            UnprotectRequestError::new(decrypt_ok)?;

            let plaintext = unsafe { plaintext.assume_init() };
            let request_data = unsafe { request_data.assume_init() };

            let plaintext = ProtectedMessage::new(plaintext);

            let user_data = reader(&plaintext).await;

            unsafe { raw::oscore_release_unprotected(&mut plaintext.into_inner()) };

            Ok((request_data, user_data))
        })
        .await
}

/// Synchronous version of [`async_unprotect_request`], see there.
pub fn unprotect_request<R>(
    request: impl liboscore_msgbackend::WithMsgNative,
    oscoreoption: OscoreOption<'_>,
    ctx: &mut PrimitiveContext,
    reader: impl FnOnce(&ProtectedMessage) -> R,
) -> Result<(raw::oscore_requestid_t, R), UnprotectRequestError> {
    poll_once_expect_immediate(async_unprotect_request(
        request,
        oscoreoption,
        ctx,
        async |m| reader(m),
    ))
}

/// Protects an OSCORE response.
///
/// The message into which the ciphertext is to be written is passed in as `response`; the actual
/// writing happens while there is a protected message configured during a callback.
///
/// The `correlation` data (to be carried over from the corresponding request operation) is not
/// consumed, but altered: if at all, only the first response can use the nonce of the request.
/// Later uses will create larger responses that include an own nonce.
pub async fn async_protect_response<R>(
    response: impl liboscore_msgbackend::WithMsgNative,
    ctx: &mut PrimitiveContext,
    correlation: &mut raw::oscore_requestid_t,
    writer: impl AsyncFnOnce(&mut ProtectedMessage) -> R,
) -> Result<R, ProtectError> {
    response
        .async_with_msg_native(async |nativemsg| {
            let mut plaintext = MaybeUninit::uninit();
            // Safety: Everything that needs to be initialized is
            let prepare_ok = unsafe {
                raw::oscore_prepare_response(
                    nativemsg,
                    plaintext.as_mut_ptr(),
                    ctx.as_mut(),
                    correlation,
                )
            };
            PrepareError::new(prepare_ok)?;
            // Safety: Initialized after successful return
            let plaintext = unsafe { plaintext.assume_init() };

            let mut plaintext = crate::ProtectedMessage::new(plaintext);
            let user_data = writer(&mut plaintext).await;
            plaintext.flush();
            let mut plaintext = plaintext.into_inner();

            let mut returned_msg = MaybeUninit::uninit();
            // Safety: Everything that needs to be initialized is
            let finish_ok =
                unsafe { raw::oscore_encrypt_message(&mut plaintext, returned_msg.as_mut_ptr()) };
            FinishError::new(finish_ok)?;
            // We're discarding the native message that's in returned_msg. If it were owned (which
            // would be a valid choice for with_inmemory_write), the closure might be required to
            // return it, but it currently isn't.

            Ok(user_data)
        })
        .await
}

/// Synchronous version of [`async_protect_response`], see there.
pub fn protect_response<R>(
    response: impl liboscore_msgbackend::WithMsgNative,
    ctx: &mut PrimitiveContext,
    correlation: &mut raw::oscore_requestid_t,
    writer: impl FnOnce(&mut ProtectedMessage) -> R,
) -> Result<R, ProtectError> {
    poll_once_expect_immediate(async_protect_response(
        response,
        ctx,
        correlation,
        async |m| writer(m),
    ))
}

/// Unprotects an OSCORE response.
///
/// The message from which the ciphertext is read in as `response` (and taken mutably because it is
/// decrypted in-place, rendering it nonsensical to any other CoAP processing); the actual
/// processing of the plaintext happens while there is a protected message configured during a
/// callback.
///
/// The `correlation` data is to be carried over from the corresponding request operation.
//
// A narrower set of requirements than &MutableWritableMessage, like
// "ReadableMessageWithMutablePayload", would suffice, but none such trait is useful outside of
// here ... though, for CBOR decoding, maybe, where we memmove around indefinite length strings
// into place?
pub async fn async_unprotect_response<R>(
    response: impl liboscore_msgbackend::WithMsgNative,
    ctx: &mut PrimitiveContext,
    oscoreoption: OscoreOption<'_>,
    correlation: &mut raw::oscore_requestid_t,
    reader: impl AsyncFnOnce(&ProtectedMessage) -> R,
) -> Result<R, UnprotectResponseError> {
    response
        .async_with_msg_native(async |nativemsg| {
            let mut plaintext = MaybeUninit::uninit();
            let decrypt_ok = unsafe {
                raw::oscore_unprotect_response(
                    nativemsg,
                    plaintext.as_mut_ptr(),
                    &oscoreoption.into_inner(),
                    ctx.as_mut(),
                    correlation,
                )
            };
            UnprotectResponseError::new(decrypt_ok)?;

            let plaintext = unsafe { plaintext.assume_init() };

            let plaintext = ProtectedMessage::new(plaintext);

            let user_data = reader(&plaintext).await;

            unsafe { raw::oscore_release_unprotected(&mut plaintext.into_inner()) };

            Ok(user_data)
        })
        .await
}

/// Synchronous version of [`async_unprotect_response`], see there.
pub fn unprotect_response<R>(
    response: impl liboscore_msgbackend::WithMsgNative,
    ctx: &mut PrimitiveContext,
    oscoreoption: OscoreOption<'_>,
    correlation: &mut raw::oscore_requestid_t,
    reader: impl FnOnce(&ProtectedMessage) -> R,
) -> Result<R, UnprotectResponseError> {
    poll_once_expect_immediate(async_unprotect_response(
        response,
        ctx,
        oscoreoption,
        correlation,
        async |m| reader(m),
    ))
}