From b477b9f7607d0184aa7435f49c0ffd6ef6a8c995 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Wed, 30 Nov 2022 13:29:55 +0100 Subject: [PATCH] chore: Document our libolm pickling methods --- src/megolm/group_session.rs | 32 +++++++++++++++++++++-------- src/megolm/inbound_group_session.rs | 32 +++++++++++++++++++++-------- src/olm/account/mod.rs | 22 +++++++++++++------- src/olm/session/mod.rs | 8 ++++++++ 4 files changed, 69 insertions(+), 25 deletions(-) diff --git a/src/megolm/group_session.rs b/src/megolm/group_session.rs index 4151c1e5..c7f861a7 100644 --- a/src/megolm/group_session.rs +++ b/src/megolm/group_session.rs @@ -141,15 +141,11 @@ impl GroupSession { pickle.into() } - #[cfg(feature = "libolm-compat")] - pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { - use libolm::Pickle; - - use crate::utilities::pickle_libolm; - - pickle_libolm::(self.into(), pickle_key) - } - + /// Create a [`GroupSession`] object by unpickling a session pickle + /// in libolm legacy pickle format. + /// + /// Such pickles are encrypted and need to first be decrypted using + /// `pickle_key`. #[cfg(feature = "libolm-compat")] pub fn from_libolm_pickle( pickle: &str, @@ -161,6 +157,24 @@ impl GroupSession { unpickle_libolm::(pickle, pickle_key, PICKLE_VERSION) } + + /// Pickle an [`GroupSession`] into a libolm pickle format. + /// + /// This pickle can be restored using the + /// [`InboundGroupSession::from_libolm_pickle`] method, or can be used in + /// the [`libolm`] C library. + /// + /// The pickle will be encryptd using the pickle key. + /// + /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/ + #[cfg(feature = "libolm-compat")] + pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { + use libolm::Pickle; + + use crate::utilities::pickle_libolm; + + pickle_libolm::(self.into(), pickle_key) + } } /// A format suitable for serialization which implements [`serde::Serialize`] diff --git a/src/megolm/inbound_group_session.rs b/src/megolm/inbound_group_session.rs index 2640036b..b361a28b 100644 --- a/src/megolm/inbound_group_session.rs +++ b/src/megolm/inbound_group_session.rs @@ -365,15 +365,11 @@ impl InboundGroupSession { Self::from(pickle) } - #[cfg(feature = "libolm-compat")] - pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { - use libolm::Pickle; - - use crate::utilities::pickle_libolm; - - pickle_libolm::(self.into(), pickle_key) - } - + /// Create a [`InboundGroupSession`] object by unpickling a session pickle + /// in libolm legacy pickle format. + /// + /// Such pickles are encrypted and need to first be decrypted using + /// `pickle_key`. #[cfg(feature = "libolm-compat")] pub fn from_libolm_pickle( pickle: &str, @@ -385,6 +381,24 @@ impl InboundGroupSession { unpickle_libolm::(pickle, pickle_key, PICKLE_VERSION) } + + /// Pickle an [`InboundGroupSession`] into a libolm pickle format. + /// + /// This pickle can be restored using the + /// [`InboundGroupSession::from_libolm_pickle`] method, or can be used in + /// the [`libolm`] C library. + /// + /// The pickle will be encryptd using the pickle key. + /// + /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/ + #[cfg(feature = "libolm-compat")] + pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { + use libolm::Pickle; + + use crate::utilities::pickle_libolm; + + pickle_libolm::(self.into(), pickle_key) + } } /// A format suitable for serialization which implements [`serde::Serialize`] diff --git a/src/olm/account/mod.rs b/src/olm/account/mod.rs index c5d148fe..479e35b7 100644 --- a/src/olm/account/mod.rs +++ b/src/olm/account/mod.rs @@ -373,6 +373,21 @@ impl Account { unpickle_libolm::(pickle, pickle_key, PICKLE_VERSION) } + /// Pickle an [`Account`] into a libolm pickle format. + /// + /// This pickle can be restored using the `[Account::from_libolm_pickle]` + /// method, or can be used in the [`libolm`] C library. + /// + /// The pickle will be encryptd using the pickle key. + /// + /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/ + #[cfg(feature = "libolm-compat")] + pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { + use self::libolm::Pickle; + use crate::utilities::pickle_libolm; + pickle_libolm::(self.into(), pickle_key) + } + #[cfg(all(any(fuzzing, test), feature = "libolm-compat"))] pub fn from_decrypted_libolm_pickle(pickle: &[u8]) -> Result { use std::io::Cursor; @@ -386,13 +401,6 @@ impl Account { pickle.try_into() } - - #[cfg(feature = "libolm-compat")] - pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { - use self::libolm::Pickle; - use crate::utilities::pickle_libolm; - pickle_libolm::(self.into(), pickle_key) - } } impl Default for Account { diff --git a/src/olm/session/mod.rs b/src/olm/session/mod.rs index 687e7043..1093c213 100644 --- a/src/olm/session/mod.rs +++ b/src/olm/session/mod.rs @@ -336,6 +336,14 @@ impl Session { unpickle_libolm::(pickle, pickle_key, libolm::PICKLE_VERSION) } + /// Pickle an [`Session`] into a libolm pickle format. + /// + /// This pickle can be restored using the [`Session::from_libolm_pickle`] + /// method, or can be used in the [`libolm`] C library. + /// + /// The pickle will be encryptd using the pickle key. + /// + /// [`libolm`]: https://gitlab.matrix.org/matrix-org/olm/ #[cfg(feature = "libolm-compat")] pub fn to_libolm_pickle(&self, pickle_key: &[u8]) -> Result { use self::libolm::Pickle;