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 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
// Copyright 2021 Damir Jelić
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! A Rust implementation of Olm and Megolm
//!
//! vodozemac is a Rust reimplementation of
//! [libolm](https://gitlab.matrix.org/matrix-org/olm), a cryptographic library
//! used for end-to-end encryption in [Matrix](https://matrix.org). At its core, it
//! is an implementation of the Olm and Megolm cryptographic ratchets, along
//! with a high-level API to easily establish cryptographic communication
//! channels employing those ratchets with other parties. It also implements
//! some other miscellaneous cryptographic functionality which is useful for
//! building Matrix clients, such as [SAS][sas].
//!
//! [sas]:
//! <https://spec.matrix.org/v1.2/client-server-api/#short-authentication-string-sas-verification>
//!
//! # Olm
//!
//! Olm is an implementation of the [Double Ratchet
//! algorithm](https://whispersystems.org/docs/specifications/doubleratchet/), very
//! similar to that employed by the Signal Protocol. It allows the establishment
//! of a 1-to-1 private communication channel, with perfect forward secrecy and
//! self-healing properties.
//!
//! A detailed technical specification can be found at
//! <https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/olm.md>.
//!
//! For more information on using vodozemac for Olm, see the [`olm`] module.
//!
//! # Megolm
//!
//! Megolm is an AES-based single ratchet for group conversations with a large
//! number of participants, where using Olm would be cost prohibitive because it
//! would imply encrypting each message individually for each participant.
//! Megolm sidesteps this by encrypting messages with a symmetric ratchet,
//! shared once with each participant and then reused for a sequence of messages
//! before rotating.
//!
//! This is a trade-off in which we lose Olm's self-healing properties, because
//! someone in possession of a Megolm session at a particular state can derive
//! all future states. However, if the attacker is only able to obtain the
//! session in a ratcheted state, they cannot use it to decrypt messages
//! encrypted with an earlier state. This preserves forward secrecy.
//!
//! A detailed technical specification can be found at
//! <https://gitlab.matrix.org/matrix-org/olm/-/blob/master/docs/megolm.md>.
//!
//! For more information on using vodozemac for Megolm, see the [`megolm`]
//! module.
//!
//! # Features
//!
//! ## Supported
//!
//! - [Olm](https://matrix-org.github.io/vodozemac/vodozemac/olm/index.html)
//! - [Megolm](https://matrix-org.github.io/vodozemac/vodozemac/megolm/index.html)
//! - [libolm pickle format](#legacy-pickles) (read-only)
//! - [Modern pickle format](#modern-pickles)
//! - [SAS (Short Authentication Strings)](https://matrix-org.github.io/vodozemac/vodozemac/sas/index.html)
//!
//! ## Unsupported
//!
//! - Creating asymmetric [server-side message key
//! backups][legacy-message-key-backup], since they are slated to be replaced
//! with symmetric backups.
//!
//! ## Planned
//!
//! - Symmetric [server-side message key backups][symmetric-message-key-backup]
//! - Importing asymmetric [server-side message key
//! backups][legacy-message-key-backup], for compatibility with existing
//! backups created by libolm.
//!
//! [legacy-message-key-backup]:
//! <https://spec.matrix.org/v1.2/client-server-api/#server-side-key-backups>
//!
//! [symmetric-message-key-backup]:
//! https://github.com/uhoreg/matrix-doc/blob/symmetric-backups/proposals/3270-symmetric-megolm-backup.md
//!
//! # Feature flags
//!
//! ## Low-level API
//!
//! Feature: `low-level-api` (default: off)
//!
//! Vodozemac exposes some lower-level structs and functions that are only
//! useful in very advanced use cases. These should *not* be needed by the vast
//! majority of users.
//!
//! Extreme care must be taken when using such APIs, as incorrect usage can lead
//! to broken sessions.
//!
//! # Pickling
//!
//! vodozemac supports serializing its entire internal state into a form
//! a "pickle". The state can subsequently be restored from such a pickle
//! ("unpickled") in order to continue operation. This is used to support some
//! Matrix features like device dehydration.
//!
//! ## Legacy pickles
//!
//! The legacy pickle format is a simple binary format used by libolm.
//! Implemented for interoperability with current clients which are using
//! libolm. Only *unpickling* is supported.
//!
//! ## Modern pickles
//!
//! The crate also implements a modern pickling mechanism using
//! [Serde](https://serde.rs/). The exact serialization format is not mandated
//! nor specified by this crate, but you can serialize to and deserialize from
//! any format supported by Serde.
//!
//! The following structs support pickling:
//!
//! - [`olm::Account`]
//! - [`olm::Session`]
//! - [`megolm::GroupSession`]
//! - [`megolm::InboundGroupSession`]
//!
//! For example, the following will print out the JSON representing the
//! serialized `Account` and will leave no new copies of the account's secrets
//! in memory:
//!
//! ```rust
//! use anyhow::Result;
//! use vodozemac::olm::{Account, AccountPickle};
//!
//! const PICKLE_KEY: [u8; 32] = [0u8; 32];
//!
//! fn main() -> Result<()>{
//! let mut account = Account::new();
//!
//! account.generate_one_time_keys(10);
//! account.generate_fallback_key();
//!
//! let pickle = account.pickle().encrypt(&PICKLE_KEY);
//!
//! let account2: Account = AccountPickle::from_encrypted(&pickle, &PICKLE_KEY)?.into();
//!
//! assert_eq!(account.identity_keys(), account2.identity_keys());
//!
//! Ok(())
//! }
//! ```
//!
//! You can unpickle a pickle-able struct directly from its serialized form:
//!
//! ```rust
//! # use anyhow::Result;
//! # use vodozemac::olm::{Account, AccountPickle};
//! # use zeroize::Zeroize;
//! #
//! # fn main() -> Result<()> {
//! # let some_account = Account::new();
//! let mut json_str = serde_json::to_string(&some_account.pickle())?;
//! // This will produce an account which is identical to `some_account`.
//! let account: Account = serde_json::from_str::<AccountPickle>(&json_str)?.into();
//!
//! json_str.zeroize();
//! #
//! # Ok(())
//! # }
//! ```
//!
//! However, the pickle-able structs do not implement `serde::Serialize`
//! themselves. If you want to serialize to a format other than JSON, you should
//! instead call the `.pickle()` method to obtain a special serializable struct.
//! This struct *does* implement `Serialize` and can therefore be serialized
//! into any format supported by `serde`. To get back to the original struct
//! from such as serializable struct, just call `.unpickle()`.
//!
//! ```rust
//! use anyhow::Result;
//! use vodozemac::olm::Account;
//!
//! fn main() -> Result<()> {
//! let account = Account::new();
//! let account: Account = account.pickle().into(); // this is identity
//!
//! Ok(())
//! }
//! ```
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
mod cipher;
mod types;
mod utilities;
pub mod ecies;
pub mod hazmat;
pub mod megolm;
pub mod olm;
#[cfg(feature = "insecure-pk-encryption")]
pub mod pk_encryption;
pub mod sas;
pub use base64::DecodeError as Base64DecodeError;
pub use prost::DecodeError as ProtoBufDecodeError;
pub use types::{
Curve25519PublicKey, Curve25519SecretKey, Ed25519Keypair, Ed25519PublicKey, Ed25519SecretKey,
Ed25519Signature, KeyError, KeyId, SharedSecret, SignatureError,
};
pub use utilities::{base64_decode, base64_encode};
/// Error type describing the various ways Vodozemac pickles can fail to be
/// decoded.
#[derive(Debug, thiserror::Error)]
pub enum PickleError {
/// The pickle wasn't valid base64.
#[error("The pickle wasn't valid base64: {0}")]
Base64(#[from] base64::DecodeError),
/// The encrypted pickle could not have been decrypted.
#[error("The pickle couldn't be decrypted: {0}")]
Decryption(#[from] cipher::DecryptionError),
/// The serialized Vodozemac object couldn't be deserialized.
#[error("The pickle couldn't be deserialized: {0}")]
Serialization(#[from] serde_json::Error),
}
/// Error type describing the various ways libolm pickles can fail to be
/// decoded.
#[cfg(feature = "libolm-compat")]
#[derive(Debug, thiserror::Error)]
pub enum LibolmPickleError {
/// The pickle is missing a valid version.
#[error("The pickle doesn't contain a version")]
MissingVersion,
/// The pickle has a unsupported version.
#[error("The pickle uses an unsupported version, expected {0}, got {1}")]
Version(u32, u32),
/// The pickle wasn't valid base64.
#[error("The pickle wasn't valid base64: {0}")]
Base64(#[from] Base64DecodeError),
/// The pickle could not have been decrypted.
#[error("The pickle couldn't be decrypted: {0}")]
Decryption(#[from] cipher::DecryptionError),
/// The pickle contains an invalid public key.
#[error("The pickle contained an invalid ed25519 public key {0}")]
PublicKey(#[from] KeyError),
/// The pickle does not contain a valid receiving or sending chain. A valid
/// Olm session needs to have at least one of them.
#[error("The pickle didn't contain a valid Olm session")]
InvalidSession,
/// The payload of the pickle could not be decoded.
#[error(transparent)]
Decode(#[from] matrix_pickle::DecodeError),
/// The object could not be encoded as a pickle.
#[error(transparent)]
Encode(#[from] matrix_pickle::EncodeError),
}
/// Error type describing the different ways message decoding can fail.
#[derive(Debug, thiserror::Error)]
pub enum DecodeError {
/// The Olm message has an invalid type.
#[error("The message has an invalid type, expected 0 or 1, got {0}")]
MessageType(usize),
/// The message is missing a valid version.
#[error("The message didn't contain a version")]
MissingVersion,
/// The message doesn't have enough data to be correctly decoded.
#[error("The message was too short, it didn't contain a valid payload")]
MessageTooShort(usize),
/// The message has a unsupported version.
#[error("The message didn't have a valid version, expected {0}, got {1}")]
InvalidVersion(u8, u8),
/// An embedded public key couldn't be decoded.
#[error("The message contained an invalid public key: {0}")]
InvalidKey(#[from] KeyError),
/// The embedded message authentication code couldn't be decoded.
#[error("The message contained a MAC with an invalid size, expected {0}, got {1}")]
InvalidMacLength(usize, usize),
/// An embedded signature couldn't be decoded.
#[error("The message contained an invalid Signature: {0}")]
Signature(#[from] SignatureError),
/// The message couldn't be decoded as a valid protocol buffer message.
#[error(transparent)]
ProtoBufError(#[from] ProtoBufDecodeError),
/// The message wasn't valid base64.
#[error("The message wasn't valid base64: {0}")]
Base64(#[from] Base64DecodeError),
}
/// The version of vodozemac that is being used.
pub static VERSION: &str = env!("CARGO_PKG_VERSION");
#[cfg(test)]
fn corpus_data_path(fuzz_target: &str) -> std::path::PathBuf {
let manifest_dir =
std::env::var("CARGO_MANIFEST_DIR").expect("Cargo always sets the manifest dir");
let mut afl_dir = std::path::PathBuf::from(manifest_dir);
afl_dir.push("afl");
afl_dir.push(fuzz_target);
afl_dir.push("in");
afl_dir
}
#[cfg(test)]
fn run_corpus<F>(fuzz_target: &str, method: F)
where
F: FnOnce(&[u8]) + Copy,
{
let dir = corpus_data_path(fuzz_target);
let corpus = std::fs::read_dir(dir).expect("Couldn't read the corpus directory");
for input in corpus {
let input = input.expect("Couldn't read the input file");
let data = std::fs::read(input.path()).expect("Couldn't read the input file");
method(&data)
}
}