From 54409d9e8a1345d5377accb8e4ff3a6b004bdd9b Mon Sep 17 00:00:00 2001 From: RTAkland Date: Wed, 9 Sep 2026 02:38:38 +0800 Subject: [PATCH] Append built-in crypto description --- README.md | 18 ++++++++---------- docs/Embedded-cryptography.md | 32 ++++++++++++++++++++++++++++++++ docs/Get-started.md | 2 +- docs/README.md | 13 ++++++------- 4 files changed, 47 insertions(+), 18 deletions(-) create mode 100644 docs/Embedded-cryptography.md diff --git a/README.md b/README.md index 17ce0f0..c3bf9a3 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,14 @@ A lightweight minecraft client-side protocol library for Kotlin Native and JVM ## Implementation details -- [x] **Online Mode Authentication & Encryption**: See [Implement Encryption](docs/implement-encryption.md) -- [x] **Structured `TextComponent` Parser**: TextComponent AST decoder (Some packets fallback to Raw NBTCompound) -- [x] **Command Tree Parser (0x10)**: Full binary graph decoder for brigadier nodes, argument types, and suggestions -- [ ] **Recipe Book & Recipe Data (0x3F, 0x4A, 0x4B, 0x4C, 0x85)**: Recipe layout declarations and client-side recipe - settings -- [ ] **Chunk & World Data (0x2D)**: Level Chunk Data with Light decoder (Bitsets, Paletted Containers, Direct/Indirect - Palettes) -- [ ] **Light Engine Update (0x30)**: Sky & Block light nibble array parser -- [ ] **Explosion Event Decoder (0x24)**: Knockback vectors and destroyed block offsets array -- [ ] **Debug Packets Parsing (0x1A - 0x1E)**: Debug subs, block/entity states, and game performance sample events +- [x] **Online Mode Authentication & Encryption/Decryption**: See [Embedded cryptography](docs/Embedded-cryptography.md) +- [x] **Structured `TextComponent` Parser**: TextComponent AST decoder +- [x] **Command Tree Parser**: Full binary graph decoder for brigadier nodes, argument types, and suggestions +- [ ] **Recipe Book & Recipe Data**: Recipe layout declarations and client-side recipe settings +- [ ] **Chunk & World Data**: Level Chunk Data with Light decoder (Paletted Containers, Direct/Indirect Palettes) +- [ ] **Light Engine Update**: Sky & Block light nibble array parser +- [ ] **Explosion Event Decoder**: Knockback vectors and destroyed block offsets array +- [ ] **Debug Packets Parsing**: Debug subs, block/entity states, and game performance sample events - [ ] **Particle Parsing** - [ ] **Slot Data Parsing** diff --git a/docs/Embedded-cryptography.md b/docs/Embedded-cryptography.md new file mode 100644 index 0000000..bc73306 --- /dev/null +++ b/docs/Embedded-cryptography.md @@ -0,0 +1,32 @@ +Starting with version `0.2.0` (`26.2-0.2.0`), `libmc` includes a built-in cryptography implementation. +It uses the JDK's built-in cryptographic APIs on the JVM platform and a pure-Kotlin implementation +on `kotlin-native` platforms. However, due to a lack of low-level optimizations, performance results +in encoding and decoding tests are significantly slower than JDK's built-in implementations + +A simplified table below shows the benchmark results: + +| Algorithm | Data Size (Bytes) | libmc's Built-in (ops/s) | JDK's Built-in (ops/s) | Gap | +|:-------------------------|:------------------|:-------------------------|:-----------------------|:-------------------------------------------| +| **AES-128-CFB8 Encrypt** | 32 | 112,554.27 | 1,527,235.11 | **~13.6 times slower than JDK's built-in** | +| | 1,024 | 2,976.95 | 49,842.94 | **~16.7 times slower than JDK's built-in** | +| | 65,536 | 45.04 | 773.46 | **~17.2 times slower than JDK's built-in** | +| **AES-128-CFB8 Decrypt** | 32 | 115,031.69 | 1,515,218.15 | **~13.2 times slower than JDK's built-in** | +| | 1,024 | 2,925.74 | 49,868.55 | **~17.0 times slower than JDK's built-in** | +| | 65,536 | 48.47 | 777.11 | **~16.0 times slower than JDK's built-in** | +| **RSA-1024 Encrypt** | 16 | 163.87 | 91,600.51 | **~559 times slower than JDK's built-in** | +| | 64 | 158.27 | 93,042.81 | **~587 times slower than JDK's built-in** | +| | 117 | 160.95 | 94,826.94 | **~589 times slower than JDK's built-in** | +| **SHA-1 Hashing** | 64 | 2,134,974.72 | 11,609,497.92 | **~5.4 times slower than JDK's built-in** | +| | 1,024 | 259,804.80 | 1,856,575.14 | **~7.1 times slower than JDK's built-in** | +| | 65,536 | 4,485.95 | 32,132.67 | **~7.2 times slower than JDK's built-in** | + +> **Benchmark Environment:** +> - **CPU:** AMD Ryzen 5 5500U (6 Cores / 12 Threads @ 2.10GHz) +> - **RAM:** 16GB DDR4 2667MHz +> - **OS:** Windows 11 64-bit +> - **Runtime:** Microsoft Build of OpenJDK 17.0.8, Kotlin 2.4.10 (MingwX64 & JVM) + +**Fortunately**, except for `AES-128-CFB8` (which requires continuous stream encryption/decryption during networking), +the other operations (RSA & SHA-1) are only executed once during the initial server authentication phase + +If you have optimized native algorithm implementations (via `cinterop` or other approaches), PRs are welcome \ No newline at end of file diff --git a/docs/Get-started.md b/docs/Get-started.md index f270dcb..eb47ad1 100644 --- a/docs/Get-started.md +++ b/docs/Get-started.md @@ -20,7 +20,7 @@ public fun main() = runBlocking { > In the example code above, a `MinecraftClient` is created. This client will connect to an offline server at > `127.0.0.1:25565` using `MyBot` as the player name, and replaces the underlying TCP Socket > implementation with a `ktor-network` based TCP Socket. (For details on how to create a SocketEngine, please refer -> to [Implementing TCP Socket](Impl-TCP-Socket.md). For details on how to +> to [Implementing TCP Socket](Impl-tcp-socket.md). For details on how to > create a Context, please refer to [Required APIs](README.md#required-apis)) > MinecraftClient implements CoroutineScope, and calling `client.connect()` will execute the connection on a background > thread. Blocking thread to prevent the application from exiting diff --git a/docs/README.md b/docs/README.md index 540c31b..687b389 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,19 +9,18 @@ module relies on the following dependencies: ## Required APIs -| Module Name | Required | Notes | -|:-------------|:------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| TCP Socket | Yes | The `protocol` module does not have a built-in TCP Socket implementation. [Implement TCP Socket](Impl-TCP-Socket.md) | -| HTTP Client | Conditional | Required only when logging into an `online-mode` server to send join request to mojang's session server. [Implement HTTP Client](Impl-HTTP-Client.md) | +| Module Name | Required | Notes | +|:------------|:------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| +| TCP Socket | Yes | The `protocol` module does not have a built-in TCP Socket implementation. [Implement TCP Socket](Impl-tcp-socket.md) | +| HTTP Client | Conditional | Required only when logging into an `online-mode` server to send join request to mojang's session server. [Implement HTTP Client](Impl-http-client.md) | # Get started # Protocol > `libmc-protocol` is current under development. It only supports the latest Minecraft version -> (Current supported Minecraft version: `26.2`, Protocol Version: `776`) - +> (Current supported Minecraft version: `26.2`, Protocol Version Number: `776`) ## NBT & SNBT -[NBT & SNBT](en/NBT-SNBT.md) \ No newline at end of file +[NBT & SNBT](nbt-snbt.md) \ No newline at end of file