epic: first committed version

Author: fantix

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  check:
+    name: Check ${{ matrix.arch }}
+    runs-on: ${{ matrix.runs-on }}
+    strategy:
+      matrix:
+        include:
+          - arch: x86_64
+            runs-on: ubuntu-24.04
+          - arch: aarch64
+            runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rustfmt
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - name: Check kTLS environment
+        run: bash scripts/check-ktls.sh
+      - name: Run all checks
+        run: bash scripts/check.sh

.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Publish
+        run: cargo publish --token ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Extract release notes
+        id: extract-release-notes
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to compio-ktls
+
+Thank you for your interest in contributing to compio-ktls!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/compio-ktls.git`
+3. Create a new branch: `git checkout -b my-feature`
+
+## Development Setup
+
+### Prerequisites
+
+- Linux kernel 6.6 LTS or newer (for running tests)
+- kTLS kernel module loaded: `sudo modprobe tls`
+
+Run the environment check script:
+
+```bash
+./scripts/check-ktls.sh
+```
+
+### Running Tests
+
+```bash
+# Run all checks (fmt, clippy, tests, doc)
+./scripts/check.sh
+
+# Or run individually
+cargo +nightly fmt --all -- --check
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+cargo doc --all-features --no-deps
+```
+
+## Making Changes
+
+1. **Code Style**: Follow the project's code style. Run `cargo fmt` before committing.
+2. **Tests**: Add tests for new functionality. Ensure all tests pass.
+3. **Documentation**: Update documentation for public APIs.
+4. **Commit Messages**: Write clear, concise commit messages.
+
+## Pull Request Process
+
+1. Ensure all tests pass locally
+2. Update documentation if needed
+3. Create a pull request with a clear description of changes
+4. Address any feedback from reviewers
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Help create a welcoming environment for all contributors
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same licenses as the project (Apache-2.0 OR MulanPSL-2.0).
+

Cargo.toml

@@ -5,8 +5,46 @@ edition = "2024"
 description = "Kernel TLS (kTLS) support for Compio"
 repository = "https://github.com/fantix/compio-ktls"
 license = "Apache-2.0 OR MulanPSL-2.0"
+authors = ["Fantix King <fantix.king@gmail.com>"]
 keywords = ["ktls", "tls", "compio", "async", "kernel"]
 categories = ["asynchronous", "network-programming", "cryptography"]
 readme = "README.md"
 
 [dependencies]
+rustls = { version = "0.23", default-features = false, optional = true }
+
+[dependencies.compio-io]
+version = "0.9"
+default-features = false
+features = ["ancillary", "bytemuck"]
+
+[dependencies.compio-buf]
+version = "0.8"
+default-features = false
+
+[target."cfg(target_os = \"linux\")".dependencies]
+libc = "0.2"
+ktls-core = "0.0.5"
+
+[features]
+default = ["rustls"]
+rustls = ["dep:rustls", "ktls-core/shim-rustls"]
+ring = ["rustls", "rustls/ring"]
+app-write-with-empty-ancillary = []
+
+[dev-dependencies]
+compio = { version = "0.18", features = ["net", "rustls", "macros"] }
+rustls-native-certs = "0.8"
+rustls-pemfile = "2.2"
+
+[patch.crates-io.compio]
+git = "https://github.com/fantix/compio.git"
+rev = "a40dbc4685898f61f8a6702da9aa38872e5f7629"
+
+[patch.crates-io.compio-io]
+git = "https://github.com/fantix/compio.git"
+rev = "a40dbc4685898f61f8a6702da9aa38872e5f7629"
+
+[patch.crates-io.compio-buf]
+git = "https://github.com/fantix/compio.git"
+rev = "a40dbc4685898f61f8a6702da9aa38872e5f7629"

README.md

@@ -2,6 +2,88 @@
 
 Kernel TLS (kTLS) support for [Compio](https://github.com/compio-rs/compio).
 
+[![中文](https://img.shields.io/badge/Zh-中文-informational?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAQCAYAAAAWGF8bAAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAFKADAAQAAAABAAAAEAAAAABHXVY9AAABc0lEQVQ4EaWSOy8EURTHd+wDEY94JVtgg9BI1B6dQqHiE1CrRasT30DpC2hVQimiFkJWVsSj2U1EsmQH4/ff3CO3WDuDk/zmf8/jnntm7qRSMRZFUQ4WYSimNFmaRlsgq8F83K6WuALyva4mixbc+kfJcGqa7CqU4AjaocNpG5oHsx7qB3EqQRC8K4g/gazAMbFTBdbgL1Zh0w2EbnMVHdMrd4LZNotZmIZJKMAemC2z0MS6oDlYhzOQ6c3yGR5Fec4OGPvEHCmn3np+kfyT51+QH8afcbFLTfjgFVS9tZrpwC4v1k9M39w3NTQrBxSM4127SAmNoBt0Ma3QyHRwGUIYdQUh0+c0wZsLPKKH8AwvoHgNlmABZLtwBdqnP0DD9IEG2If6N0oz5SbYSfW4PYhvgNmUxU1JZGEEAsUyjPmB7lhBA1Xe7NMWpuzXa39fnC7lN1b/mZttSNLQv9XXZs2US9LwzjU5R+/d+n/CBx9I2uELeXrRajeDqHwAAAAASUVORK5CYII=)](README.zh.md)
+[![CI](https://img.shields.io/github/actions/workflow/status/fantix/compio-ktls/ci.yml?label=CI&logo=github)](https://github.com/fantix/compio-ktls/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-Apache--2.0-success?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAgCAYAAAASYli2AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAGqSURBVHgBrVbtcYMwDFVy/V82KCMwAp2g2aDtJGSDZoPQDegE0AmSDUwngA1UKYggHBtwyLvTgcF66ONZCcAdQMSMrCEzZHGILzvHZJFaf+AYxxCyTDlmQm5k3cj1EEJ4Qjf085322UI4KrJrCTabTXFDKKmU8uUjWSLvfy2yWixWWbDf16g58tBGadWQsUc/GuZ6Es4YbpGK6ehewI9iLkIMiO7Up7z11AoctcOJyF6pObWOMMJBVy6wmI0rapv9EiGxt3T5nIiOETvePaN99LCTTCL3B0/tfALvYbCTWww4pFJ6HHe4HCXLppVgU0dKP2RvsBwJzESwQ3czfDj0dXRpzODydFkhe+a6nBTqMhPybabCrybSzaUcrVgtSrl2miPhbufqqyn6tWnQN6lxPIGbgHSNi4+FHal1tCDdHt+uh1zDs2ez/VtRy94/soJqVoEPOD4hjdTPrlkKIVANOaJ/VBVzPP2AZelwc2pJ7d2xl2WRw1JC5VQJKc/Ivkm8zkdaWwJ0zLdQbBVZBMOgWE8I3bSpYCU0YUI1OsNK3PPPYZ5QDnoND8A/4kV4DUnNfc8AAAAASUVORK5CYII=)](https://www.apache.org/licenses/LICENSE-2.0)
+[![license](https://img.shields.io/badge/license-MulanPSL--2.0-success?logo=opensourceinitiative&logoColor=white)](https://license.coscl.org.cn/MulanPSL2/)
+
+## Overview
+
+- Built on top of [ktls-core](https://github.com/hanyu-dev/ktls)
+- Not tied to any specific Compio runtime implementation
+- Pluggable TLS implementations (currently supports Rustls)
+- Currently supports TLS 1.3 only
+- Supports NewSessionTicket, KeyUpdate, and Alert message handling
+
+## Features
+
+- `rustls` (default): Enable Rustls integration
+- `ring`: Use ring as the crypto backend
+- `app-write-with-empty-ancillary`: Use `write_with_ancillary()` instead of `write()` for
+  application data writes. compio-rs/compio#756 introduced zero-copy writes for io-uring,
+  which changed the default behavior of `write()` in a way that breaks on kTLS-enabled
+  sockets. Enable this feature when using io-uring to work around the conflict between
+  zero-copy writes and kTLS.
+
+## Usage
+
+```rust
+use compio_ktls::{KtlsConnector, KtlsAcceptor};
+
+// Client side
+let connector = KtlsConnector::from(client_config);
+match connector.connect("example.com", tcp_stream).await? {
+    Ok(stream) => {
+        // kTLS enabled successfully
+    }
+    Err(stream) => {
+        // kTLS unavailable, fallback to original stream
+    }
+}
+
+// Server side
+let acceptor = KtlsAcceptor::from(server_config);
+match acceptor.accept(tcp_stream).await? {
+    Ok(stream) => {
+        // kTLS enabled successfully
+    }
+    Err(stream) => {
+        // kTLS unavailable, fallback to original stream
+    }
+}
+```
+
+## Requirements
+
+Requires Linux kernel with kTLS support, version 6.6 LTS or newer is recommended.
+
+Check if the kTLS module is loaded:
+
+```bash
+lsmod | grep tls
+```
+
+If not loaded, you can manually load it:
+
+```bash
+sudo modprobe tls
+```
+
+Also requires Rustls with `enable_secret_extraction` enabled:
+
+```rust
+use std::sync::Arc;
+use rustls::ClientConfig;
+
+let mut config = ClientConfig::builder()
+    .dangerous()
+    .with_custom_certificate_verifier(/* ... */)
+    .with_no_client_auth();
+
+config.enable_secret_extraction = true;
+
+let config = Arc::new(config);
+```
 
 ## License
 

README.zh.md

@@ -1,7 +1,88 @@
 # compio-ktls
 
-为 [Compio](https://github.com/compio-rs/compio) 提供内核 TLS (kTLS) 支持。
+[Compio](https://github.com/compio-rs/compio) 的内核 TLS (kTLS) 支持！
 
+[![English](https://img.shields.io/badge/英文-English-informational?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABsAAAAQCAYAAADnEwSWAAAABGdBTUEAALGPC/xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAG6ADAAQAAAABAAAAEAAAAACiF0fSAAABJUlEQVQ4EWP8//8/MwMDAysQEw0YGRl/EK0YWSHQsgogJgX8RNZPCpuJFMWUqqWrZSw4XBsCFL+FQ+4/DnEUYWC8gNKCEDB+X8MlgIKVWCJMD64ADwOorwmIHyNhdyDbFYgPAfFXIAaBV0CcCTIG5DNsLo0GKnDEYc8+oGsvQ+UEgLQMkrpYIDsSiJGjRxTInwY07wmuYCxDMgCdmQUUgFmGLheNLoDEzwG5gBFJgFQmNr3ZQEPsgfgImmEquHy2BajwHZpiGPcmjAGk0aPgCDCIp4HkgcHWA6RsQGwoEMEVZ9VATZdgqkig7yKp/YjEBjORIxJdjhw+3tIFVzCGAoPBEo9ta4E+f4NHHqsULstqsKpGCJ4BMkm2jNrBiHAOFhZdLQMA8pKhkQYZiokAAAAASUVORK5CYII=)](README.md)
+[![CI](https://img.shields.io/github/actions/workflow/status/fantix/compio-ktls/ci.yml?label=CI&logo=github)](https://github.com/fantix/compio-ktls/actions/workflows/test.yml)
+[![许可](https://img.shields.io/badge/许可-Apache--2.0-success?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAgCAYAAAASYli2AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAGqSURBVHgBrVbtcYMwDFVy/V82KCMwAp2g2aDtJGSDZoPQDegE0AmSDUwngA1UKYggHBtwyLvTgcF66ONZCcAdQMSMrCEzZHGILzvHZJFaf+AYxxCyTDlmQm5k3cj1EEJ4Qjf085322UI4KrJrCTabTXFDKKmU8uUjWSLvfy2yWixWWbDf16g58tBGadWQsUc/GuZ6Es4YbpGK6ehewI9iLkIMiO7Up7z11AoctcOJyF6pObWOMMJBVy6wmI0rapv9EiGxt3T5nIiOETvePaN99LCTTCL3B0/tfALvYbCTWww4pFJ6HHe4HCXLppVgU0dKP2RvsBwJzESwQ3czfDj0dXRpzODydFkhe+a6nBTqMhPybabCrybSzaUcrVgtSrl2miPhbufqqyn6tWnQN6lxPIGbgHSNi4+FHal1tCDdHt+uh1zDs2ez/VtRy94/soJqVoEPOD4hjdTPrlkKIVANOaJ/VBVzPP2AZelwc2pJ7d2xl2WRw1JC5VQJKc/Ivkm8zkdaWwJ0zLdQbBVZBMOgWE8I3bSpYCU0YUI1OsNK3PPPYZ5QDnoND8A/4kV4DUnNfc8AAAAASUVORK5CYII=)](https://www.apache.org/licenses/LICENSE-2.0)
+[![许可](https://img.shields.io/badge/许可-MulanPSL--2.0-success?logo=opensourceinitiative&logoColor=white)](https://license.coscl.org.cn/MulanPSL2/)
+
+## 概述
+
+- 基于 [ktls-core](https://github.com/hanyu-dev/ktls) 实现
+- 不锁定特定的 Compio 运行时实现
+- 可插拔的 TLS 实现（目前支持 Rustls）
+- 目前仅支持 TLS 1.3
+- 支持 NewSessionTicket、KeyUpdate 和 Alert 消息处理
+
+## 可选 features
+
+- `rustls`（默认）：启用 Rustls 集成
+- `ring`：使用 ring 作为加密后端
+- `app-write-with-empty-ancillary`：在写入应用数据时使用 `write_with_ancillary()` 而非
+  `write()`。compio-rs/compio#756 引入了 io-uring 的零拷贝写入，改变了 `write()`
+  的默认行为，而这会在启用了 kTLS 的 socket 上出错。因此，使用 io-uring 时，应启用该 feature
+  来绕过 zero-copy 写入与 kTLS 的冲突。
+
+## 使用方法
+
+```rust
+use compio_ktls::{KtlsConnector, KtlsAcceptor};
+
+// 客户端
+let connector = KtlsConnector::from(client_config);
+match connector.connect("example.com", tcp_stream).await? {
+    Ok(stream) => {
+        // 成功启用 kTLS
+    }
+    Err(stream) => {
+        // kTLS 不可用，回退到原始 stream
+    }
+}
+
+// 服务端
+let acceptor = KtlsAcceptor::from(server_config);
+match acceptor.accept(tcp_stream).await? {
+    Ok(stream) => {
+        // 成功启用 kTLS
+    }
+    Err(stream) => {
+        // kTLS 不可用，回退到原始 stream
+    }
+}
+```
+
+## 环境要求
+
+需要 Linux 内核支持 kTLS，建议使用 6.6 或更新版本的 LTS 内核。
+
+检查内核是否已加载 kTLS 模块：
+
+```bash
+lsmod | grep tls
+```
+
+如果没有加载，可以手动加载：
+
+```bash
+sudo modprobe tls
+```
+
+另需 Rustls 启用 `enable_secret_extraction`：
+
+```rust
+use std::sync::Arc;
+use rustls::ClientConfig;
+
+let mut config = ClientConfig::builder()
+    .dangerous()
+    .with_custom_certificate_verifier(/* ... */)
+    .with_no_client_auth();
+
+config.enable_secret_extraction = true;
+
+let config = Arc::new(config);
+```
 
 ## 许可证
 

rustfmt.toml

@@ -0,0 +1,19 @@
+unstable_features = true
+
+style_edition = "2024"
+
+group_imports = "StdExternalCrate"
+imports_granularity = "Crate"
+reorder_imports = true
+
+wrap_comments = true
+normalize_comments = true
+
+reorder_impl_items = true
+condense_wildcard_suffixes = true
+enum_discrim_align_threshold = 20
+use_field_init_shorthand = true
+
+format_strings = true
+format_code_in_doc_comments = true
+format_macro_matchers = true