1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179
#![doc = include_str!("../README.md")]
//! ## Quick Start
//! For a quick start to learn how OpenMLS works here's the basic code to set
//! up to parties and have them create a group.
//!
//! ```
//! use openmls::prelude::*;
//! use openmls_rust_crypto::{OpenMlsRustCrypto};
//!
//! // Define cipher suite ...
//! let ciphersuite = Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519;
//! // ... and the crypto backend to use.
//! let backend = &OpenMlsRustCrypto::default();
//!
//! // Now let's create two participants.
//!
//! // A helper to create and store credentials.
//! fn generate_credential_bundle(
//! identity: Vec<u8>,
//! credential_type: CredentialType,
//! signature_algorithm: SignatureScheme,
//! backend: &impl OpenMlsCryptoProvider,
//! ) -> Result<Credential, CredentialError> {
//! let credential_bundle =
//! CredentialBundle::new(identity, credential_type, signature_algorithm, backend)?;
//! let credential_id = credential_bundle.credential()
//! .signature_key()
//! .tls_serialize_detached()
//! .expect("Error serializing signature key.");
//! // Store the credential bundle into the key store so OpenMLS has access
//! // to it.
//! backend
//! .key_store()
//! .store(&credential_id, &credential_bundle)
//! .expect("An unexpected error occurred.");
//! Ok(credential_bundle.into_parts().0)
//! }
//!
//! // A helper to create key package bundles.
//! fn generate_key_package_bundle(
//! ciphersuites: &[Ciphersuite],
//! credential: &Credential,
//! backend: &impl OpenMlsCryptoProvider,
//! ) -> Result<KeyPackage, KeyPackageBundleNewError> {
//! // Fetch the credential bundle from the key store
//! let credential_id = credential
//! .signature_key()
//! .tls_serialize_detached()
//! .expect("Error serializing signature key.");
//! let credential_bundle = backend
//! .key_store()
//! .read(&credential_id)
//! .expect("An unexpected error occurred.");
//!
//! // Create the key package bundle
//! let key_package_bundle =
//! KeyPackageBundle::new(ciphersuites, &credential_bundle, backend, vec![])?;
//!
//! // Store it in the key store
//! let key_package_id = key_package_bundle.key_package()
//! .hash_ref(backend.crypto())
//! .expect("Could not hash KeyPackage.");
//! backend
//! .key_store()
//! .store(key_package_id.value(), &key_package_bundle)
//! .expect("An unexpected error occurred.");
//! Ok(key_package_bundle.into_parts().0)
//! }
//!
//! // First they need credentials to identify them
//! let sasha_credential = generate_credential_bundle(
//! "Sasha".into(),
//! CredentialType::Basic,
//! ciphersuite.signature_algorithm(),
//! backend,
//! )
//! .expect("An unexpected error occurred.");
//!
//! let maxim_credential = generate_credential_bundle(
//! "Maxim".into(),
//! CredentialType::Basic,
//! ciphersuite.signature_algorithm(),
//! backend,
//! )
//! .expect("An unexpected error occurred.");
//!
//! // Then they generate key packages to facilitate the asynchronous handshakes
//! // in MLS
//!
//! // Generate KeyPackages
//! let sasha_key_package = generate_key_package_bundle(&[ciphersuite], &sasha_credential, backend)
//! .expect("An unexpected error occurred.");
//!
//! let maxim_key_package = generate_key_package_bundle(&[ciphersuite], &maxim_credential, backend)
//! .expect("An unexpected error occurred.");
//!
//! // Now Sasha starts a new group ...
//! let mut sasha_group = MlsGroup::new(
//! backend,
//! &MlsGroupConfig::default(),
//! GroupId::from_slice(b"My First Group"),
//! sasha_key_package
//! .hash_ref(backend.crypto())
//! .expect("Could not hash KeyPackage.")
//! .as_slice(),
//! )
//! .expect("An unexpected error occurred.");
//!
//! // ... and invites Maxim.
//! // The key package has to be retrieved from Maxim in some way. Most likely
//! // via a server storing key packages for users.
//! let (mls_message_out, welcome) = sasha_group
//! .add_members(backend, &[maxim_key_package])
//! .expect("Could not add members.");
//!
//! // Sasha merges the pending commit that adds Maxim.
//! sasha_group
//! .merge_pending_commit()
//! .expect("error merging pending commit");
//!
//! // Now Maxim can join the group.
//! let mut maxim_group = MlsGroup::new_from_welcome(
//! backend,
//! &MlsGroupConfig::default(),
//! welcome,
//! // The public tree is need and transferred out of band.
//! // It is also possible to use the [`RatchetTreeExtension`]
//! Some(sasha_group.export_ratchet_tree()),
//! )
//! .expect("Error joining group from Welcome");
//! ```
//!
//! [//]: # "links and badges"
//! [user Manual]: https://openmls.tech/book
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(not(test), forbid(unsafe_code))]
#![cfg_attr(not(feature = "test-utils"), deny(missing_docs))]
#![deny(rustdoc::broken_intra_doc_links)]
#![deny(rustdoc::private_intra_doc_links)]
// === Testing ===
/// Single place, re-exporting all structs and functions needed for integration tests
#[cfg(any(feature = "test-utils", test))]
pub mod prelude_test;
#[cfg(any(feature = "test-utils", test))]
pub use rstest_reuse;
#[cfg(any(feature = "test-utils", test))]
#[macro_use]
pub mod test_utils;
// === Modules ===
#[macro_use]
mod utils;
pub mod error;
// Public
pub mod ciphersuite;
pub mod credentials;
pub mod extensions;
pub mod framing;
pub mod group;
pub mod key_packages;
pub mod messages;
pub mod schedule;
pub mod treesync;
pub mod versions;
// Private
mod binary_tree;
mod key_store;
mod tree;
/// Single place, re-exporting the most used public functions.
pub mod prelude;