ghast_auth/lib.rs
1//! Authentication and connection setup for the ghast Minecraft Java Edition client library.
2//!
3//! This crate covers everything that happens *before* the game protocol takes over a socket:
4//!
5//! * [`offline`]: offline-mode identities. [`offline::offline_uuid`] derives the same UUID that
6//! vanilla and Bukkit/Paper servers assign to an offline player.
7//! * [`socks5`] and [`connect`]: an RFC 1928 / RFC 1929 SOCKS5 client (username/password auth,
8//! **remote DNS only**) and a [`connect::Connector`] that opens the game TCP connection, either
9//! directly or through a proxy, under a configurable [`connect::ProxyPolicy`].
10//! * [`crypto`]: the client side of the login Encryption Request: a fresh shared secret, RSA
11//! PKCS#1 v1.5 encryption with the server's key and the session-server hash.
12//! * `microsoft` (cargo feature `microsoft`, off by default): Microsoft account login through the
13//! OAuth device-code flow, Xbox Live, XSTS and Minecraft services, a token cache, and the
14//! session-server `join` call used by online-mode servers.
15//!
16//! # Example: offline identity over a SOCKS5 proxy
17//!
18//! ```no_run
19//! use ghast_auth::connect::{Connector, ProxyPolicy, TargetAddr};
20//! use ghast_auth::offline::OfflineProfile;
21//! use ghast_auth::socks5::Socks5Proxy;
22//!
23//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
24//! let profile = OfflineProfile::new("Steve")?;
25//! println!("{} has offline UUID {}", profile.name(), profile.uuid());
26//!
27//! let proxy: Socks5Proxy = "socks5h://user:secret@proxy.example:1080".parse()?;
28//! let connector = Connector::new()
29//! .with_proxy(proxy)
30//! .with_policy(ProxyPolicy::RequireProxyExceptLocal);
31//!
32//! // The domain name is sent to the proxy as-is; it is never resolved locally.
33//! let target: TargetAddr = "mc.example.net:25565".parse()?;
34//! let stream = connector.connect(&target).await?;
35//! // `stream` is a `tokio::net::TcpStream` with TCP_NODELAY set, ready for the handshake packet.
36//! # drop(stream);
37//! # Ok(())
38//! # }
39//! ```
40
41#![forbid(unsafe_code)]
42#![warn(missing_docs, rust_2018_idioms, unreachable_pub, unnameable_types)]
43
44pub mod connect;
45pub mod crypto;
46pub mod offline;
47pub mod socks5;
48
49#[cfg(feature = "microsoft")]
50pub mod microsoft;
51
52mod secret;
53
54pub use secret::SecretString;