Crate qualia2fa_core

Expand description

The Qualia2FA core library.

This crate carries the two-factor authentication (2FA) core logic of Qualia2FA and deliberately contains no user interface or command-line entry point, so that front ends such as a GUI, a CLI, or a mobile application can each depend on this library as a separate crate.

§Purity contract

This library is a pure logic library with no I/O and no clock:

It does not access the file system, the network, or environment variables, and it does not read the system clock.
The current time is passed in by the caller as u64 Unix seconds.
Randomness comes only from getrandom, never through a user-space PRNG.
#![forbid(unsafe_code)] — the whole crate contains no unsafe.

§Status

Implemented: Base32 (RFC 4648), HOTP (RFC 4226), TOTP (RFC 6238), Steam Guard, mOTP, Yandex OTP, otpauth:// parsing, the encrypted vault, recovery files, device pairing, and the sync protocol.

§Usage

// Version number.
assert_eq!(qualia2fa_core::VERSION, env!("CARGO_PKG_VERSION"));

// Base32 decoding (RFC 4648); tolerates lowercase, missing padding, and whitespace.
use qualia2fa_core::{base32, ExposeSecret};
let seed = base32::decode("MZXW6YTBOI======").expect("valid Base32");
assert_eq!(seed.expose_secret(), b"foobar");

§License

Licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later); see COPYING.LESSER and LICENSE in the repository root.

Re-exports§

pub use auth::Responder;
pub use auth::Verified;
pub use auth::Verifier;
pub use flow::DeviceKeys;
pub use flow::Joiner;
pub use flow::Login;
pub use flow::Registered;
pub use flow::SecureStore;
pub use pairing::Adoption;
pub use pairing::JoinerSession;
pub use pairing::NonceLog;
pub use pairing::PendingSession;
pub use pairing::QrPayload;
pub use recovery::KdfParams;
pub use recovery::export as export_recovery;
pub use recovery::import as import_recovery;
pub use lock::FILE_LEN as LOCK_WRAP_LEN;
pub use lock::LockMarker;
pub use lock::LockPending;
pub use lock::WrapHeader;
pub use lock::unwrap as unwrap_lock_password;
pub use lock::wrap as wrap_lock_password;
pub use transport::Recipient;
pub use transport::Roster;
pub use transport::SharePlan;
pub use transport::SyncOutcome;
pub use transport::SyncSession;
pub use transport::Transport;
pub use transport::TransportCapabilities;
pub use getrandom;

Modules§

auth: Challenge-response: prove possession of the master key without handing it over.
base32: Base32 encoding and decoding (RFC 4648 §6).
export: Writing the vault out in a form that can be read again somewhere else.
flow: Orchestration of the two user journeys: registration and login.
import: Reading entries from another authenticator’s export.
lock: Unlock password: wrapping the master key for the application lock.
motp: mOTP (Mobile-OTP).
otp: HOTP (RFC 4226) and TOTP (RFC 6238).
pairing: Device-login pairing: hand the master key to a new device.
portable: Portable vault containers: the master key and the vault ciphertext in one file.
recovery: Recovery keys: backing up the master key with a user passphrase.
sync: Envelope for sync payloads: serialize → compress → whole-payload AEAD.
transport: Transport abstraction: this module only knows how to move a run of bytes to a peer. It knows nothing about WiFi, QR codes or Bluetooth.
uri: otpauth:// URI parsing (Google Authenticator Key URI Format), plus the motp: scheme.
vault: Encrypted vault: on-disk format, entry encryption and decryption, atomic writes.
yaotp: Yandex OTP (yaotp), the scheme behind Yandex.Key.

Structs§

DeviceId: Public types of device identity.
DevicePublicKey: Public types of device identity.
DeviceSignature: Public types of device identity.
SecretBox: Wrapper type for values that contains secrets, which attempts to limit accidental exposure and ensure secrets are wiped from memory when dropped. (e.g. passwords, cryptographic keys, access tokens or other credentials)

Enums§

Error: The unified error type of this library.

Constants§

VERSION: Version of this library, taken from package.version in Cargo.toml.

Traits§

ExposeSecret: Expose a reference to an inner secret
ExposeSecretMut: Expose a mutable reference to an inner secret

Type Aliases§

Result: The unified result type of this library.
SecretBytes: Byte secrets: OTP seeds, master keys, session keys, and the like are all carried by this type.
SecretSlice: Secret slice type.
SecretString: Secret string type.