Rust Cryptography Extension

Relevant source files

The following files were used as context for generating this wiki page:

• athena-crypto/src/lib.rs
• athena-crypto/Cargo.toml
• athena-crypto/pyproject.toml
• pyproject.toml
• src/athena_cli/stable_verification/score_submit.py
• AGENTS.md

The Rust Cryptography Extension (athena-crypto) is a high-performance native component of the Athena project designed to handle specialized cryptographic operations required for osu!stable client compatibility. Its primary responsibility is the decryption of score submission payloads which use a modified Rijndael algorithm that is not natively supported by standard Python libraries.

This extension is built using Rust and exposed to the Python environment via PyO3 and Maturin. By offloading these computationally intensive and non-standard decryption tasks to Rust, the system ensures both technical accuracy in reproducing the legacy client's behavior and high execution performance within the Python-based modular monolith.

Sources: athena-crypto/Cargo.toml, athena-crypto/pyproject.toml, README.md:103-107

Architecture and Integration

The extension is structured as a standalone Rust crate located in the athena-crypto/ directory. It uses maturin as the build backend to generate a Python extension module named athena_crypto.

Build System and Bindings

The integration between Rust and Python is managed through several configuration files:

• Cargo.toml: Defines the Rust dependencies, specifically pyo3 for Python bindings and simple-rijndael for the core cryptographic logic.
• athena-crypto/pyproject.toml: Configures maturin and specifies the Python module name.
• Root pyproject.toml: Includes athena-crypto as a local dependency in editable mode, allowing the main Python application to import it.

Sources: athena-crypto/Cargo.toml, athena-crypto/pyproject.toml, pyproject.toml:39, 48-49

Component Relationship

The following diagram illustrates how the Rust extension fits into the broader Athena architecture:

The diagram shows the flow from high-level Python services down to the specialized Rust implementation.
Sources: athena-crypto/src/lib.rs:8-12, src/athena_cli/stable_verification/score_submit.py:46-49

Cryptographic Implementation

The core functionality of the extension is the decrypt_score_payload function, which implements the specific Rijndael configuration used by the osu!stable client.

Key Logic and Constants

The implementation utilizes a block size of 32 bytes (256 bits). The decryption key is derived dynamically based on the provided osu! version or a default hardcoded fallback.

Constant/Variable	Value / Source	Description
RIJNDAEL_BLOCK_SIZE	32	The required block size for the cipher and IV.
DEFAULT_KEY	h89f2-890h2h89b34g-h80g134n90133	Fallback key used when no version is provided.
VERSION_PREFIX	osu!-scoreburgr---------	Prefix used when constructing version-specific keys.

Sources: athena-crypto/src/lib.rs:5, 34-42

Decryption Data Flow

The decryption process follows a strict sequence to ensure the integrity of the resulting plaintext:

The flowchart depicts the validation and key derivation steps before performing the actual decryption.
Sources: athena-crypto/src/lib.rs:14-60

Padding Handling

While the Rijndael cipher is initialized with ZeroPadding via the simple-rijndael crate, the extension includes a manual implementation of PKCS7 padding removal in the strip_pkcs7_padding function. This function validates the padding bytes and truncates the vector accordingly, returning a boolean flag indicating if the padding was correctly formed.

Sources: athena-crypto/src/lib.rs:63-82

API Reference

The Rust extension exposes a single primary function to the Python environment.

decrypt_score_payload

Decrypts the encrypted block sent during score submission.

Parameter	Type	Description
encrypted	bytes	The raw encrypted payload from the client.
iv	bytes	The 32-byte Initialization Vector.
osu_version	Optional[str]	The client version string used for key derivation.

Returns: tuple[str, bool] — A tuple containing the decrypted UTF-8 plaintext and a boolean indicating if the PKCS7 padding/checksum was valid.

Raises: PyValueError if the IV length is incorrect, data is empty, decryption fails, or the resulting bytes are not valid UTF-8.

Sources: athena-crypto/src/lib.rs:14-60

Usage in Verification

The extension is utilized by the athena_cli toolset to verify stable client compatibility. Specifically, the ScoreSubmitVerifier uses parsers that likely rely on these cryptographic capabilities to inspect "golden" fixtures and ensure the server's score intake logic matches expected legacy behavior.

Sources: src/athena_cli/stable_verification/score_submit.py:64-70, 102-108

Conclusion

The Rust Cryptography Extension is a critical bridge between Athena's modern Python architecture and the legacy requirements of the osu!stable protocol. By encapsulating non-standard Rijndael-256 CBC logic and version-based key derivation in a type-safe Rust module, the project maintains high performance while ensuring that sensitive score submission data is processed with bit-perfect accuracy relative to the original client implementation.