char/matrix-rust-sdk
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'qr-crate'

Browse source
This commit is contained in:
Damir Jelić 2021-06-07 14:03:29 +02:00
commit b6c7b317bf
9 changed files with 1097 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
Cargo.toml
View file

@ -1,6 +1,7 @@
[workspace]
members = [
"matrix_sdk",
"matrix_qrcode",
"matrix_sdk_base",
"matrix_sdk_test",
"matrix_sdk_test_macros",

24
matrix_qrcode/Cargo.toml Normal file
View file

@ -0,0 +1,24 @@
[package]
name = "matrix-qrcode"
version = "0.1.0"
authors = ["Damir Jelić <poljar@termina.org.uk>"]
edition = "2018"
[package.metadata.docs.rs]
features = ["docs"]
rustdoc-args = ["--cfg", "feature=\"docs\""]
[features]
default = ["decode_image"]
decode_image = ["image", "rqrr", "qrcode/image", "qrcode/svg"]
docs = ["decode_image"]
[dependencies]
base64 = "0.13.0"
byteorder = "1.4.3"
image = { version = "0.23.14", optional = true }
qrcode = { version = "0.12.0", default-features = false }
rqrr = { version = "0.3.2" , optional = true }
ruma-identifiers = "0.19.1"
thiserror = "1.0.24"

BIN
matrix_qrcode/data/self-no-master.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.7 KiB

BIN
matrix_qrcode/data/self-verification.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.4 KiB

BIN
matrix_qrcode/data/verification.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 4.2 KiB

61
matrix_qrcode/src/error.rs Normal file
View file

@ -0,0 +1,61 @@
// Copyright 2021 The Matrix.org Foundation C.I.C.
//
// 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.
use thiserror::Error;
/// Error type describing errors that happen while QR data is being decoded.
#[derive(Error, Debug)]
pub enum DecodingError {
/// Error decoding the QR code.
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
#[error(transparent)]
Qr(#[from] rqrr::DeQRError),
/// The QR code data is missing the mandatory Matrix header.
#[error("the decoded QR code is missing the Matrix header")]
Header,
/// The QR code data is containing an invalid, non UTF-8, flow id.
#[error(transparent)]
Utf8(#[from] std::string::FromUtf8Error),
/// The QR code data is using an unsupported or invalid verification mode.
#[error("the QR code contains an invalid verification mode: {0}")]
Mode(u8),
/// The flow id is not a valid event ID.
#[error(transparent)]
Identifier(#[from] ruma_identifiers::Error),
#[error(transparent)]
/// The QR code data does not contain all the necessary fields.
Read(#[from] std::io::Error),
/// The QR code data uses an invalid shared secret.
#[error("the QR code contains a too short shared secret, length: {0}")]
SharedSecret(usize),
/// The QR code data uses an invalid or unsupported version.
#[error("the QR code contains an invalid or unsupported version: {0}")]
Version(u8),
}
/// Error type describing errors that happen while QR data is being encoded.
#[derive(Error, Debug)]
pub enum EncodingError {
/// Error generating a QR code from the data, likely because the data
/// doesn't fit into a QR code.
#[error(transparent)]
Qr(#[from] qrcode::types::QrError),
/// Error decoding the identity keys as base64.
#[error(transparent)]
Base64(#[from] base64::DecodeError),
/// Error encoding the given flow id, the flow id is too large.
#[error("The verification flow id length can't be converted into a u16: {0}")]
FlowId(#[from] std::num::TryFromIntError),
}

225
matrix_qrcode/src/lib.rs Normal file
View file

@ -0,0 +1,225 @@
// Copyright 2021 The Matrix.org Foundation C.I.C.
//
// 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.
//! This crate implements methods to parse and generate QR codes that are used
//! for interactive verification in [Matrix](https://matrix.org/).
//!
//! It implements the QR format defined in the Matrix [spec].
//!
//! [spec]: https://spec.matrix.org/unstable/client-server-api/#qr-code-format
//!
//! ```no_run
//! # use matrix_qrcode::{QrVerification, DecodingError};
//! # fn main() -> Result<(), DecodingError> {
//! use image;
//!
//! let image = image::open("/path/to/my/image.png").unwrap();
//! let result = QrVerification::from_image(image)?;
//! # Ok(())
//! # }
//! ```
#![cfg_attr(feature = "docs", feature(doc_cfg))]
#![deny(
missing_debug_implementations,
dead_code,
trivial_casts,
missing_docs,
trivial_numeric_casts,
unused_extern_crates,
unused_import_braces,
unused_qualifications
)]
mod error;
mod types;
mod utils;
pub use error::{DecodingError, EncodingError};
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
pub use image;
pub use qrcode;
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
pub use rqrr;
pub use types::{
QrVerification, SelfVerificationData, SelfVerificationNoMasterKey, VerificationData,
};
#[cfg(test)]
mod test {
#[cfg(feature = "decode_image")]
use std::{convert::TryFrom, io::Cursor};
#[cfg(feature = "decode_image")]
use image::{ImageFormat, Luma};
#[cfg(feature = "decode_image")]
use qrcode::QrCode;
#[cfg(feature = "decode_image")]
use crate::utils::decode_qr;
use crate::{DecodingError, QrVerification};
#[cfg(feature = "decode_image")]
static VERIFICATION: &[u8; 4277] = include_bytes!("../data/verification.png");
#[cfg(feature = "decode_image")]
static SELF_VERIFICATION: &[u8; 1467] = include_bytes!("../data/self-verification.png");
#[cfg(feature = "decode_image")]
static SELF_NO_MASTER: &[u8; 1775] = include_bytes!("../data/self-no-master.png");
#[test]
#[cfg(feature = "decode_image")]
fn decode_qr_test() {
let image = Cursor::new(VERIFICATION);
let image = image::load(image, ImageFormat::Png).unwrap().to_luma8();
decode_qr(image).expect("Couldn't decode the QR code");
}
#[test]
#[cfg(feature = "decode_image")]
fn decode_test() {
let image = Cursor::new(VERIFICATION);
let image = image::load(image, ImageFormat::Png).unwrap().to_luma8();
let result = QrVerification::try_from(image).unwrap();
assert!(matches!(result, QrVerification::Verification(_)));
}
#[test]
#[cfg(feature = "decode_image")]
fn decode_encode_cycle() {
let image = Cursor::new(VERIFICATION);
let image = image::load(image, ImageFormat::Png).unwrap();
let result = QrVerification::from_image(image).unwrap();
assert!(matches!(result, QrVerification::Verification(_)));
let encoded = result.to_qr_code().unwrap();
let image = encoded.render::<Luma<u8>>().build();
let second_result = QrVerification::try_from(image).unwrap();
assert_eq!(result, second_result);
let bytes = result.to_bytes().unwrap();
let third_result = QrVerification::from_bytes(bytes).unwrap();
assert_eq!(result, third_result);
}
#[test]
#[cfg(feature = "decode_image")]
fn decode_encode_cycle_self() {
let image = Cursor::new(SELF_VERIFICATION);
let image = image::load(image, ImageFormat::Png).unwrap();
let result = QrVerification::try_from(image).unwrap();
assert!(matches!(result, QrVerification::SelfVerification(_)));
let encoded = result.to_qr_code().unwrap();
let image = encoded.render::<Luma<u8>>().build();
let second_result = QrVerification::from_luma(image).unwrap();
assert_eq!(result, second_result);
let bytes = result.to_bytes().unwrap();
let third_result = QrVerification::from_bytes(bytes).unwrap();
assert_eq!(result, third_result);
}
#[test]
#[cfg(feature = "decode_image")]
fn decode_encode_cycle_self_no_master() {
let image = Cursor::new(SELF_NO_MASTER);
let image = image::load(image, ImageFormat::Png).unwrap();
let result = QrVerification::from_image(image).unwrap();
assert!(matches!(result, QrVerification::SelfVerificationNoMasterKey(_)));
let encoded = result.to_qr_code().unwrap();
let image = encoded.render::<Luma<u8>>().build();
let second_result = QrVerification::try_from(image).unwrap();
assert_eq!(result, second_result);
let bytes = result.to_bytes().unwrap();
let third_result = QrVerification::try_from(bytes).unwrap();
assert_eq!(result, third_result);
}
#[test]
#[cfg(feature = "decode_image")]
fn decode_invalid_qr() {
let qr = QrCode::new(b"NonMatrixCode").expect("Can't build a simple QR code");
let image = qr.render::<Luma<u8>>().build();
let result = QrVerification::try_from(image);
assert!(matches!(result, Err(DecodingError::Header)))
}
#[test]
fn decode_invalid_header() {
let data = b"NonMatrixCode";
let result = QrVerification::from_bytes(data);
assert!(matches!(result, Err(DecodingError::Header)))
}
#[test]
fn decode_invalid_mode() {
let data = b"MATRIX\x02\x03";
let result = QrVerification::from_bytes(data);
assert!(matches!(result, Err(DecodingError::Mode(3))))
}
#[test]
fn decode_invalid_version() {
let data = b"MATRIX\x01\x03";
let result = QrVerification::from_bytes(data);
assert!(matches!(result, Err(DecodingError::Version(1))))
}
#[test]
fn decode_missing_data() {
let data = b"MATRIX\x02\x02";
let result = QrVerification::from_bytes(data);
assert!(matches!(result, Err(DecodingError::Read(_))))
}
#[test]
fn decode_short_secret() {
let data = b"MATRIX\
\x02\x02\x00\x07\
FLOW_ID\
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
SECRET";
let result = QrVerification::from_bytes(data);
assert!(matches!(result, Err(DecodingError::SharedSecret(_))))
}
#[test]
fn decode_invalid_room_id() {
let data = b"MATRIX\
\x02\x00\x00\x0f\
test:localhost\
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
SECRETISLONGENOUGH";
let result = QrVerification::from_bytes(data);
assert!(matches!(result, Err(DecodingError::Identifier(_))))
}
}

672
matrix_qrcode/src/types.rs Normal file
View file

@ -0,0 +1,672 @@
// Copyright 2021 The Matrix.org Foundation C.I.C.
//
// 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.
use std::{
convert::TryFrom,
io::{Cursor, Read},
};
use byteorder::{BigEndian, ReadBytesExt};
#[cfg(feature = "decode_image")]
use image::{DynamicImage, ImageBuffer, Luma};
use qrcode::QrCode;
use ruma_identifiers::EventId;
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
use crate::utils::decode_qr;
use crate::{
error::{DecodingError, EncodingError},
utils::{base_64_encode, to_bytes, to_qr_code, HEADER, MAX_MODE, MIN_SECRET_LEN, VERSION},
};
/// An enum representing the different modes a QR verification can be in.
#[derive(Clone, Debug, PartialEq)]
pub enum QrVerification {
/// The QR verification is verifying another user
Verification(VerificationData),
/// The QR verification is self-verifying and the current device trusts or
/// owns the master key
SelfVerification(SelfVerificationData),
/// The QR verification is self-verifying in which the current device does
/// not yet trust the master key
SelfVerificationNoMasterKey(SelfVerificationNoMasterKey),
}
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
impl TryFrom<DynamicImage> for QrVerification {
type Error = DecodingError;
fn try_from(image: DynamicImage) -> Result<Self, Self::Error> {
Self::from_image(image)
}
}
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
impl TryFrom<ImageBuffer<Luma<u8>, Vec<u8>>> for QrVerification {
type Error = DecodingError;
fn try_from(image: ImageBuffer<Luma<u8>, Vec<u8>>) -> Result<Self, Self::Error> {
Self::from_luma(image)
}
}
impl TryFrom<&[u8]> for QrVerification {
type Error = DecodingError;
fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
Self::from_bytes(value)
}
}
impl TryFrom<Vec<u8>> for QrVerification {
type Error = DecodingError;
fn try_from(value: Vec<u8>) -> Result<Self, Self::Error> {
Self::from_bytes(value)
}
}
impl QrVerification {
/// Decode and parse an image of a QR code into a `QrVerification`
///
/// The image will be converted into a grey scale image before decoding is
/// attempted
///
/// # Arguments
///
/// * `image` - The image containing the QR code.
///
/// # Example
/// ```no_run
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// use image;
///
/// let image = image::open("/path/to/my/image.png").unwrap();
/// let result = QrVerification::from_image(image)?;
/// # Ok(())
/// # }
/// ```
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
pub fn from_image(image: DynamicImage) -> Result<Self, DecodingError> {
let image = image.to_luma8();
Self::decode(image)
}
/// Decode and parse an grey scale image of a QR code into a
/// `QrVerification`
///
/// # Arguments
///
/// * `image` - The grey scale image containing the QR code.
///
/// # Example
/// ```no_run
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// use image;
///
/// let image = image::open("/path/to/my/image.png").unwrap();
/// let image = image.to_luma8();
/// let result = QrVerification::from_luma(image)?;
/// # Ok(())
/// # }
/// ```
#[cfg(feature = "decode_image")]
#[cfg_attr(feature = "docs", doc(cfg(decode_image)))]
pub fn from_luma(image: ImageBuffer<Luma<u8>, Vec<u8>>) -> Result<Self, DecodingError> {
Self::decode(image)
}
/// Parse the decoded payload of a QR code in byte slice form as a
/// `QrVerification`
///
/// This method is useful if you would like to do your own custom QR code
/// decoding.
///
/// # Arguments
///
/// * `bytes` - The raw bytes of a decoded QR code.
///
/// # Example
/// ```
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// let data = b"MATRIX\
/// \x02\x02\x00\x07\
/// FLOW_ID\
/// AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
/// BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
/// SHARED_SECRET";
///
/// let result = QrVerification::from_bytes(data)?;
/// # Ok(())
/// # }
/// ```
pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Result<Self, DecodingError> {
Self::decode_bytes(bytes)
}
/// Encode the `QrVerification` into a `QrCode`.
///
/// This method turns the `QrVerification` into a QR code that can be
/// rendered and presented to be scanned.
///
/// The encoding can fail if the data doesn't fit into a QR code or if the
/// identity keys that should be encoded into the QR code are not valid
/// base64.
///
/// # Example
/// ```
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// let data = b"MATRIX\
/// \x02\x02\x00\x07\
/// FLOW_ID\
/// AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
/// BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
/// SHARED_SECRET";
///
/// let result = QrVerification::from_bytes(data)?;
/// let encoded = result.to_qr_code().unwrap();
/// # Ok(())
/// # }
/// ```
pub fn to_qr_code(&self) -> Result<QrCode, EncodingError> {
match self {
QrVerification::Verification(v) => v.to_qr_code(),
QrVerification::SelfVerification(v) => v.to_qr_code(),
QrVerification::SelfVerificationNoMasterKey(v) => v.to_qr_code(),
}
}
/// Encode the `QrVerification` into a vector of bytes that can be encoded
/// as a QR code.
///
/// The encoding can fail if the identity keys that should be encoded are
/// not valid base64.
///
/// # Example
/// ```
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// let data = b"MATRIX\
/// \x02\x02\x00\x07\
/// FLOW_ID\
/// AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
/// BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
/// SHARED_SECRET";
///
/// let result = QrVerification::from_bytes(data)?;
/// let encoded = result.to_bytes().unwrap();
///
/// assert_eq!(data.as_ref(), encoded.as_slice());
/// # Ok(())
/// # }
/// ```
pub fn to_bytes(&self) -> Result<Vec<u8>, EncodingError> {
match self {
QrVerification::Verification(v) => v.to_bytes(),
QrVerification::SelfVerification(v) => v.to_bytes(),
QrVerification::SelfVerificationNoMasterKey(v) => v.to_bytes(),
}
}
/// Decode the byte slice containing the decoded QR code data.
///
/// The format is defined in the [spec].
///
/// The byte slice consists of the following parts:
///
/// * the ASCII string MATRIX
/// * one byte indicating the QR code version (must be 0x02)
/// * one byte indicating the QR code verification mode. one of the
/// following
/// values:
/// * 0x00 verifying another user with cross-signing
/// * 0x01 self-verifying in which the current device does trust the
/// master key
/// * 0x02 self-verifying in which the current device does not yet trust
/// the master key
/// * the event ID or transaction_id of the associated verification request
/// event, encoded as:
/// * two bytes in network byte order (big-endian) indicating the length
/// in bytes of the ID as a UTF-8 string
/// * the ID as a UTF-8 string
/// * the first key, as 32 bytes
/// * the second key, as 32 bytes
/// * a random shared secret, as a byte string. as we do not share the
/// length of the secret, and it is not a fixed size, clients will just
/// use the remainder of binary string as the shared secret.
///
/// [spec]: https://spec.matrix.org/unstable/client-server-api/#qr-code-format
fn decode_bytes(bytes: impl AsRef<[u8]>) -> Result<Self, DecodingError> {
let mut decoded = Cursor::new(bytes);
let mut header = [0u8; 6];
let mut first_key = [0u8; 32];
let mut second_key = [0u8; 32];
decoded.read_exact(&mut header)?;
let version = decoded.read_u8()?;
let mode = decoded.read_u8()?;
if header != HEADER {
return Err(DecodingError::Header);
} else if version != VERSION {
return Err(DecodingError::Version(version));
} else if mode > MAX_MODE {
return Err(DecodingError::Mode(mode));
}
let flow_id_len = decoded.read_u16::<BigEndian>()?;
let mut flow_id = vec![0; flow_id_len.into()];
decoded.read_exact(&mut flow_id)?;
decoded.read_exact(&mut first_key)?;
decoded.read_exact(&mut second_key)?;
let mut shared_secret = Vec::new();
decoded.read_to_end(&mut shared_secret)?;
if shared_secret.len() < MIN_SECRET_LEN {
return Err(DecodingError::SharedSecret(shared_secret.len()));
}
QrVerification::new(mode, flow_id, first_key, second_key, shared_secret)
}
/// Decode the given image of an QR code and if we find a valid code, try to
/// decode it as a `QrVerification`.
#[cfg(feature = "decode_image")]
fn decode(image: ImageBuffer<Luma<u8>, Vec<u8>>) -> Result<QrVerification, DecodingError> {
let decoded = decode_qr(image)?;
Self::decode_bytes(decoded)
}
fn new(
mode: u8,
flow_id: Vec<u8>,
first_key: [u8; 32],
second_key: [u8; 32],
shared_secret: Vec<u8>,
) -> Result<Self, DecodingError> {
let first_key = base_64_encode(&first_key);
let second_key = base_64_encode(&second_key);
let flow_id = String::from_utf8(flow_id)?;
let shared_secret = base_64_encode(&shared_secret);
match mode {
VerificationData::QR_MODE => {
let event_id = EventId::try_from(flow_id)?;
Ok(VerificationData::new(event_id, first_key, second_key, shared_secret).into())
}
SelfVerificationData::QR_MODE => {
Ok(SelfVerificationData::new(flow_id, first_key, second_key, shared_secret).into())
}
SelfVerificationNoMasterKey::QR_MODE => {
Ok(SelfVerificationNoMasterKey::new(flow_id, first_key, second_key, shared_secret)
.into())
}
m => Err(DecodingError::Mode(m)),
}
}
/// Get the flow id for this `QrVerification`.
///
/// This represents the ID as a string even if it is a `EventId`.
pub fn flow_id(&self) -> &str {
match self {
QrVerification::Verification(v) => &v.event_id.as_str(),
QrVerification::SelfVerification(v) => &v.transaction_id,
QrVerification::SelfVerificationNoMasterKey(v) => &v.transaction_id,
}
}
/// Get the first key of this `QrVerification`.
pub fn first_key(&self) -> &str {
match self {
QrVerification::Verification(v) => &v.first_master_key,
QrVerification::SelfVerification(v) => &v.master_key,
QrVerification::SelfVerificationNoMasterKey(v) => &v.device_key,
}
}
/// Get the second key of this `QrVerification`.
pub fn second_key(&self) -> &str {
match self {
QrVerification::Verification(v) => &v.second_master_key,
QrVerification::SelfVerification(v) => &v.device_key,
QrVerification::SelfVerificationNoMasterKey(v) => &v.master_key,
}
}
/// Get the secret of this `QrVerification`.
pub fn secret(&self) -> &str {
match self {
QrVerification::Verification(v) => &v.shared_secret,
QrVerification::SelfVerification(v) => &v.shared_secret,
QrVerification::SelfVerificationNoMasterKey(v) => &v.shared_secret,
}
}
}
/// The non-encoded data for the first mode of QR code verification.
///
/// This mode is used for verification between two users using their master
/// cross signing keys.
#[derive(Clone, Debug, PartialEq)]
pub struct VerificationData {
event_id: EventId,
first_master_key: String,
second_master_key: String,
shared_secret: String,
}
impl VerificationData {
const QR_MODE: u8 = 0x00;
/// Create a new `VerificationData` struct that can be encoded as a QR code.
///
/// # Arguments
/// * `event_id` - The event id of the `m.key.verification.request` event
/// that initiated the verification flow this QR code should be part of.
///
/// * `first_key` - Our own cross signing master key. Needs to be encoded as
/// unpadded base64
///
/// * `second_key` - The cross signing master key of the other user.
///
/// * ` shared_secret` - A random bytestring encoded as unpadded base64,
/// needs to be at least 8 bytes long.
pub fn new(
event_id: EventId,
first_key: String,
second_key: String,
shared_secret: String,
) -> Self {
Self { event_id, first_master_key: first_key, second_master_key: second_key, shared_secret }
}
/// Encode the `VerificationData` into a vector of bytes that can be
/// encoded as a QR code.
///
/// The encoding can fail if the master keys that should be encoded are not
/// valid base64.
///
/// # Example
/// ```
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// let data = b"MATRIX\
/// \x02\x00\x00\x0f\
/// $test:localhost\
/// AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
/// BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
/// SHARED_SECRET";
///
/// let result = QrVerification::from_bytes(data)?;
/// if let QrVerification::Verification(decoded) = result {
/// let encoded = decoded.to_bytes().unwrap();
/// assert_eq!(data.as_ref(), encoded.as_slice());
/// } else {
/// panic!("Data was encoded as an incorrect mode");
/// }
/// # Ok(())
/// # }
/// ```
pub fn to_bytes(&self) -> Result<Vec<u8>, EncodingError> {
to_bytes(
Self::QR_MODE,
&self.event_id.as_str(),
&self.first_master_key,
&self.second_master_key,
&self.shared_secret,
)
}
/// Encode the `VerificationData` into a `QrCode`.
///
/// This method turns the `VerificationData` into a QR code that can be
/// rendered and presented to be scanned.
///
/// The encoding can fail if the data doesn't fit into a QR code or if the
/// keys that should be encoded into the QR code are not valid base64.
pub fn to_qr_code(&self) -> Result<QrCode, EncodingError> {
to_qr_code(
Self::QR_MODE,
self.event_id.as_str(),
&self.first_master_key,
&self.second_master_key,
&self.shared_secret,
)
}
}
impl From<VerificationData> for QrVerification {
fn from(data: VerificationData) -> Self {
Self::Verification(data)
}
}
/// The non-encoded data for the second mode of QR code verification.
///
/// This mode is used for verification between two devices of the same user
/// where this device, that is creating this QR code, is trusting or owning
/// the cross signing master key.
#[derive(Clone, Debug, PartialEq)]
pub struct SelfVerificationData {
transaction_id: String,
master_key: String,
device_key: String,
shared_secret: String,
}
impl SelfVerificationData {
const QR_MODE: u8 = 0x01;
/// Create a new `SelfVerificationData` struct that can be encoded as a QR
/// code.
///
/// # Arguments
/// * `transaction_id` - The transaction id of this verification flow, the
/// transaction id was sent by the `m.key.verification.request` event
/// that initiated the verification flow this QR code should be part of.
///
/// * `master_key` - Our own cross signing master key. Needs to be encoded
/// as
/// unpadded base64
///
/// * `device_key` - The ed25519 key of the other device, encoded as
/// unpadded base64.
///
/// * ` shared_secret` - A random bytestring encoded as unpadded base64,
/// needs to be at least 8 bytes long.
pub fn new(
transaction_id: String,
master_key: String,
device_key: String,
shared_secret: String,
) -> Self {
Self { transaction_id, master_key, device_key, shared_secret }
}
/// Encode the `SelfVerificationData` into a vector of bytes that can be
/// encoded as a QR code.
///
/// The encoding can fail if the keys that should be encoded are not valid
/// base64.
///
/// # Example
/// ```
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// let data = b"MATRIX\
/// \x02\x01\x00\x06\
/// FLOWID\
/// AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
/// BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
/// SHARED_SECRET";
///
/// let result = QrVerification::from_bytes(data)?;
/// if let QrVerification::SelfVerification(decoded) = result {
/// let encoded = decoded.to_bytes().unwrap();
/// assert_eq!(data.as_ref(), encoded.as_slice());
/// } else {
/// panic!("Data was encoded as an incorrect mode");
/// }
/// # Ok(())
/// # }
/// ```
pub fn to_bytes(&self) -> Result<Vec<u8>, EncodingError> {
to_bytes(
Self::QR_MODE,
&self.transaction_id,
&self.master_key,
&self.device_key,
&self.shared_secret,
)
}
/// Encode the `SelfVerificationData` into a `QrCode`.
///
/// This method turns the `SelfVerificationData` into a QR code that can be
/// rendered and presented to be scanned.
///
/// The encoding can fail if the data doesn't fit into a QR code or if the
/// keys that should be encoded into the QR code are not valid base64.
pub fn to_qr_code(&self) -> Result<QrCode, EncodingError> {
to_qr_code(
Self::QR_MODE,
&self.transaction_id,
&self.master_key,
&self.device_key,
&self.shared_secret,
)
}
}
impl From<SelfVerificationData> for QrVerification {
fn from(data: SelfVerificationData) -> Self {
Self::SelfVerification(data)
}
}
/// The non-encoded data for the third mode of QR code verification.
///
/// This mode is used for verification between two devices of the same user
/// where this device, that is creating this QR code, is not trusting the
/// cross signing master key.
#[derive(Clone, Debug, PartialEq)]
pub struct SelfVerificationNoMasterKey {
transaction_id: String,
device_key: String,
master_key: String,
shared_secret: String,
}
impl SelfVerificationNoMasterKey {
const QR_MODE: u8 = 0x02;
/// Create a new `SelfVerificationData` struct that can be encoded as a QR
/// code.
///
/// # Arguments
/// * `transaction_id` - The transaction id of this verification flow, the
/// transaction id was sent by the `m.key.verification.request` event
/// that initiated the verification flow this QR code should be part of.
///
/// * `device_key` - The ed25519 key of our own device, encoded as unpadded
/// base64.
///
/// * `master_key` - Our own cross signing master key. Needs to be encoded
/// as
/// unpadded base64
///
/// * ` shared_secret` - A random bytestring encoded as unpadded base64,
/// needs to be at least 8 bytes long.
pub fn new(
transaction_id: String,
device_key: String,
master_key: String,
shared_secret: String,
) -> Self {
Self { transaction_id, device_key, master_key, shared_secret }
}
/// Encode the `SelfVerificationNoMasterKey` into a vector of bytes that can
/// be encoded as a QR code.
///
/// The encoding can fail if the keys that should be encoded are not valid
/// base64.
///
/// # Example
/// ```
/// # use matrix_qrcode::{QrVerification, DecodingError};
/// # fn main() -> Result<(), DecodingError> {
/// let data = b"MATRIX\
/// \x02\x02\x00\x06\
/// FLOWID\
/// AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\
/// BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\
/// SHARED_SECRET";
///
/// let result = QrVerification::from_bytes(data)?;
/// if let QrVerification::SelfVerificationNoMasterKey(decoded) = result {
/// let encoded = decoded.to_bytes().unwrap();
/// assert_eq!(data.as_ref(), encoded.as_slice());
/// } else {
/// panic!("Data was encoded as an incorrect mode");
/// }
/// # Ok(())
/// # }
/// ```
pub fn to_bytes(&self) -> Result<Vec<u8>, EncodingError> {
to_bytes(
Self::QR_MODE,
&self.transaction_id,
&self.device_key,
&self.master_key,
&self.shared_secret,
)
}
/// Encode the `SelfVerificationNoMasterKey` into a `QrCode`.
///
/// This method turns the `SelfVerificationNoMasterKey` into a QR code that
/// can be rendered and presented to be scanned.
///
/// The encoding can fail if the data doesn't fit into a QR code or if the
/// keys that should be encoded into the QR code are not valid base64.
pub fn to_qr_code(&self) -> Result<QrCode, EncodingError> {
to_qr_code(
Self::QR_MODE,
&self.transaction_id,
&self.device_key,
&self.master_key,
&self.shared_secret,
)
}
}
impl From<SelfVerificationNoMasterKey> for QrVerification {
fn from(data: SelfVerificationNoMasterKey) -> Self {
Self::SelfVerificationNoMasterKey(data)
}
}

114
matrix_qrcode/src/utils.rs Normal file
View file

@ -0,0 +1,114 @@
// Copyright 2021 The Matrix.org Foundation C.I.C.
//
// 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.
use std::convert::TryInto;
use base64::{decode_config, encode_config, STANDARD_NO_PAD};
#[cfg(feature = "decode_image")]
use image::{ImageBuffer, Luma};
use qrcode::{bits::Bits, EcLevel, QrCode, Version};
#[cfg(feature = "decode_image")]
use crate::error::DecodingError;
use crate::error::EncodingError;
pub(crate) const HEADER: &[u8] = b"MATRIX";
pub(crate) const VERSION: u8 = 0x2;
pub(crate) const MAX_MODE: u8 = 0x2;
pub(crate) const MIN_SECRET_LEN: usize = 8;
pub(crate) fn base_64_encode(data: &[u8]) -> String {
encode_config(data, STANDARD_NO_PAD)
}
pub(crate) fn base64_decode(data: &str) -> Result<Vec<u8>, base64::DecodeError> {
decode_config(data, STANDARD_NO_PAD)
}
pub(crate) fn to_bytes(
mode: u8,
flow_id: &str,
first_key: &str,
second_key: &str,
shared_secret: &str,
) -> Result<Vec<u8>, EncodingError> {
let flow_id_len: u16 = flow_id.len().try_into()?;
let flow_id_len = flow_id_len.to_be_bytes();
let first_key = base64_decode(first_key)?;
let second_key = base64_decode(second_key)?;
let shared_secret = base64_decode(shared_secret)?;
let data = [
HEADER,
&[VERSION],
&[mode],
flow_id_len.as_ref(),
flow_id.as_bytes(),
&first_key,
&second_key,
&shared_secret,
]
.concat();
Ok(data)
}
pub(crate) fn to_qr_code(
mode: u8,
flow_id: &str,
first_key: &str,
second_key: &str,
shared_secret: &str,
) -> Result<QrCode, EncodingError> {
let data = to_bytes(mode, flow_id, first_key, second_key, shared_secret)?;
// Mobile clients seem to have trouble decoding the QR code that gets
// generated by `QrCode::new()` it seems to add a couple of data segments
// with different data modes/types. The parsers seem to assume a single
// data type and since we start with an ASCII `MATRIX` header the rest of
// the data gets treated as a string as well.
//
// We make sure that there isn't an ECI bit set and we just push the bytes,
// this seems to help since the decoder doesn't assume an encoding and
// treats everything as raw bytes.
let mut bits = Bits::new(Version::Normal(7));
bits.push_byte_data(&data)?;
bits.push_terminator(EcLevel::L)?;
Ok(QrCode::with_bits(bits, EcLevel::L)?)
}
#[cfg(feature = "decode_image")]
pub(crate) fn decode_qr(image: ImageBuffer<Luma<u8>, Vec<u8>>) -> Result<Vec<u8>, DecodingError> {
let mut image = rqrr::PreparedImage::prepare(image);
let grids = image.detect_grids();
let mut error = None;
for grid in grids {
let mut decoded = Vec::new();
match grid.decode_to(&mut decoded) {
Ok(_) => {
if decoded.starts_with(HEADER) {
return Ok(decoded);
}
}
Err(e) => error = Some(e),
}
}
Err(error.map(|e| e.into()).unwrap_or_else(|| DecodingError::Header))
}