// SPDX-License-Identifier: BSD-2-Clause

/*

 * crypto/psk/client.rs - Interfaces and types for client-side PSK support in libcoap-rs.

 * This file is part of the libcoap-rs crate, see the README and LICENSE files for

 * more information and terms of use.

 * Copyright © 2021-2024 The NAMIB Project Developers, all rights reserved.

 * See the README as well as the LICENSE file for more information.

 */

use crate::crypto::psk::key::PskKey;

use crate::error::SessionCreationError;

use crate::session::CoapClientSession;

use crate::types::CoapAddress;

use crate::CoapContext;

use libcoap_sys::{

    coap_dtls_cpsk_info_t, coap_dtls_cpsk_t, coap_new_client_session_psk2, coap_proto_t, coap_session_t,

    coap_str_const_t, COAP_DTLS_CPSK_SETUP_VERSION,

};

use std::cell::RefCell;

use std::ffi::{c_char, c_void, CString, NulError};

use std::fmt::Debug;

use std::ptr::NonNull;

use std::rc::{Rc, Weak};

/// Builder for a client-side DTLS encryption context for use with pre-shared keys (PSK).

#[derive(Debug)]

pub struct ClientPskContextBuilder<'a> {

    ctx: ClientPskContextInner<'a>,

}

impl<'a> ClientPskContextBuilder<'a> {

    /// Creates a new context builder with the given `key` as the default key to use.

    ///

    /// # Implementation details (informative, not covered by semver guarantees)

    ///

    /// Providing a raw public key will set `psk_info` to the provided key in the underlying

    /// [`coap_dtls_cpsk_t`] structure.

    /// Sets the key provider that provides pre-shared keys based on the PSK hint received by the

    /// server.

    ///

    /// # Implementation details (informative, not covered by semver guarantees)

    ///

    /// Setting a `key_provider` will set the `validate_ih_call_back` of the underlying

    /// [`coap_dtls_cpsk_t`] to a wrapper function, which will then call the key provider.

    ///

    /// Keys returned by the key provider will be stored in the context for at least as long as they

    /// are used by the respective session.

    /// Consumes this builder to construct the resulting PSK context.

        }

}

impl<'a> From<ClientPskContext<'a>> for crate::crypto::ClientCryptoContext<'a> {

}

impl ClientPskContextBuilder<'_> {

    /// Enables or disables support for EC JPAKE ([RFC 8236](https://datatracker.ietf.org/doc/html/rfc8236))

    /// key exchanges in (D)TLS.

    ///

    /// # Implementation details (informative, not covered by semver guarantees)

    ///

    /// Equivalent to setting `ec_jpake` in the underlying [`coap_dtls_cpsk_t`] structure.

    #[cfg(dtls_ec_jpake_support)]

    /// Enables or disables use of DTLS connection IDs ([RFC 9146](https://datatracker.ietf.org/doc/rfc9146/)).

    ///

    /// # Implementation details (informative, not covered by semver guarantees)

    ///

    /// Equivalent to setting `use_cid` in the underlying [`coap_dtls_cpsk_t`] structure.

    #[cfg(dtls_cid_support)]

    /// Sets the server name indication that should be sent to servers if the built

    /// [`ClientPskContext`] is used.

    ///

    /// `client_sni` should be convertible into a byte string that does not contain null bytes.

    /// Typically, you would provide a `&str` or `String`.

    ///

    /// # Errors

    ///

    /// Will return [`NulError`] if the provided byte string contains null bytes.

    ///

    /// # Implementation details (informative, not covered by semver guarantees)

    ///

    /// Equivalent to setting `client_sni` in the underlying [`coap_dtls_cpsk_t`] structure.

    ///

    /// The provided `client_sni` will be converted into a `Box<[u8]>`, which will be owned and

    /// stored by the built context.

        // For some reason, client_sni is not immutable here.

        // While I don't see any reason why libcoap would modify the string, it is not strictly

        // forbidden for it to do so, so simply using CString::into_raw() is not an option (as it

        // does not allow modifications to client_sni that change the length).

}

/// Client-side encryption context for PSK-based (D)TLS sessions.

#[derive(Clone, Debug)]

pub struct ClientPskContext<'a> {

    /// Inner structure of this context.

    inner: Rc<RefCell<ClientPskContextInner<'a>>>,

}

impl ClientPskContext<'_> {

    /// Returns a pointer to the PSK to use for a given `identity_hint` and `session`, or

    /// [`std::ptr::null()`] if the provided identity hint and/or session are unacceptable.

    ///

    /// The returned pointer is guaranteed to remain valid as long as the underlying

    /// [`ClientPskContextInner`] is not dropped.

    /// As the [`ClientPskContext`] is also stored in the [`CoapClientSession`] instance, this

    /// implies that the pointer is valid for at least as long as the session is.

    ///

    /// **Important:** After the underlying [`ClientPskContextInner`] is dropped, the returned

    /// pointer will no longer be valid and should no longer be dereferenced.

        } else {

        }

    /// Creates a raw CoAP session object that is bound to and utilizes this encryption context.

    ///

    /// # Safety

    ///

    /// This [`ClientPskContext`] must outlive the returned [`coap_session_t`].

}

impl<'a> ClientPskContext<'a> {

    /// Restores a [`ClientPskContext`] from a pointer to its inner structure (i.e., from the

    /// user-provided pointer given to DTLS callbacks).

    ///

    /// # Panics

    ///

    /// Panics if the given pointer is a null pointer or the inner structure was already dropped.

    ///

    /// # Safety

    /// The provided pointer must be a valid reference to a [`RefCell<ClientPskContextInner>`]

    /// instance created from a call to [`Weak::into_raw()`].

}

/// Inner structure of a client-side PSK context.

#[derive(Debug)]

struct ClientPskContextInner<'a> {

    /// Raw configuration object.

    raw_cfg: Box<coap_dtls_cpsk_t>,

    /// User-supplied key provider.

    key_provider: Option<Box<dyn ClientPskHintKeyProvider<'a> + 'a>>,

    /// Store for `coap_dtls_cpsk_info_t` instances that we provided in previous identity hint

    /// callback invocations.

    ///

    /// The stored pointers *must* all be created from [`Box::into_raw`].

    ///

    /// Using `Vec<coap_dtls_cpsk_info_t>` instead is not an option, as a `Vec` resize may cause the

    /// instances to be moved to a different place in memory, invalidating pointers provided to

    /// libcoap.

    provided_keys: Vec<*mut coap_dtls_cpsk_info_t>,

    /// Server Name Indication to send to servers.

    client_sni: Option<Box<[u8]>>,

}

impl Drop for ClientPskContextInner<'_> {

            // SAFETY: Vector has only ever been filled by instances created from to_raw_cpsk_info.

        }

            // SAFETY: If we set this, it must have been a call to Weak::into_raw with the correct

            //         type.

}

/// Trait for types that can provide the appropriate pre-shared key for a given PSK hint sent by the

/// server.

pub trait ClientPskHintKeyProvider<'a>: Debug {

    /// Returns the appropriate pre-shared key for a given `identity_hint` and the given `session`,

    /// or `None` if the session should be aborted/no key is available.

    fn key_for_identity_hint(

        &self,

        identity_hint: Option<&[u8]>,

        session: &CoapClientSession<'_>,

    ) -> Option<PskKey<'a>>;

}

impl<'a, T: Debug> ClientPskHintKeyProvider<'a> for T

where

    T: AsRef<PskKey<'a>>,

{

    /// Returns the key if the supplied `identity_hint` is `None` or the key's identity matches the

    /// hint.

        } else {

        }

}

/// Raw PSK identity hint callback that can be provided to libcoap.

///

/// # Safety

///

/// This function expects the arguments to be provided in a way that libcoap would when invoking

/// this function as an identity hint callback.

///

/// Additionally, `arg` must be a valid argument to [`ClientPskContext::from_raw`].