From 11fcf5c42f6a04c61f49618f1ae8201d768fec67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Thu, 5 Nov 2020 14:33:45 +0100 Subject: [PATCH] rust-sdk: Document the cross signing bootstrap method. --- matrix_sdk/src/client.rs | 53 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/matrix_sdk/src/client.rs b/matrix_sdk/src/client.rs index 14237e4d..7abfa5df 100644 --- a/matrix_sdk/src/client.rs +++ b/matrix_sdk/src/client.rs @@ -1832,7 +1832,58 @@ impl Client { })) } - /// TODO + /// Create and upload a new cross signing identity. + /// + /// # Arguments + /// + /// * `auth_data` - This request requires user interactive auth, the first + /// request needs to set this to `None` and will always fail with an + /// `UiaaResponse`. The response will contain information for the + /// interactive auth and the same request needs to be made but this time + /// with some `auth_data` provided. + /// + /// # Examples + /// ```no_run + /// # use std::{convert::TryFrom, collections::BTreeMap}; + /// # use matrix_sdk::{Client, identifiers::UserId}; + /// # use matrix_sdk::api::r0::uiaa::AuthData; + /// # use url::Url; + /// # use futures::executor::block_on; + /// # use serde_json::json; + /// # let user_id = UserId::try_from("@alice:example.org").unwrap(); + /// # let homeserver = Url::parse("http://example.com").unwrap(); + /// # let client = Client::new(homeserver).unwrap(); + /// # block_on(async { + /// + /// fn auth_data<'a>(user: &UserId, password: &str, session: Option<&'a str>) -> AuthData<'a> { + /// let mut auth_parameters = BTreeMap::new(); + /// let identifier = json!({ + /// "type": "m.id.user", + /// "user": user, + /// }); + /// auth_parameters.insert("identifier".to_owned(), identifier); + /// auth_parameters.insert("password".to_owned(), password.to_owned().into()); + /// // This is needed because of https://github.com/matrix-org/synapse/issues/5665 + /// auth_parameters.insert("user".to_owned(), user.as_str().into()); + /// AuthData::DirectRequest { + /// kind: "m.login.password", + /// auth_parameters, + /// session, + /// } + /// } + /// + /// if let Err(e) = client.bootstrap_cross_signing(None).await { + /// if let Some(response) = e.uiaa_response() { + /// let auth_data = auth_data(&user_id, "wordpass", response.session.as_deref()); + /// client + /// .bootstrap_cross_signing(Some(auth_data)) + /// .await + /// .expect("Couldn't bootstrap cross signing") + /// } else { + /// panic!("Error durign cross signing bootstrap {:#?}", e); + /// } + /// } + /// # }) #[cfg(feature = "encryption")] #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn bootstrap_cross_signing(&self, auth_data: Option>) -> Result<()> {