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,82 @@
 
 Kernel TLS (kTLS) support for [Compio](https://github.com/compio-rs/compio).
 
+## 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()` with empty ancillary data
+  for application data writes. Enable this when using `compio-net`'s zero-copy send API
+  (introduced in compio#756), as it bypasses io-uring's `MSG_ZEROCOPY` flag which is
+  incompatible with 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

@@ -2,6 +2,81 @@
 
 为 [Compio](https://github.com/compio-rs/compio) 提供内核 TLS (kTLS) 支持。
 
+## 概述
+
+- 基于 [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()`
+  并传入空的辅助数据。当使用 `compio-net` 的零拷贝发送 API（compio#756 引入）时需要启用此
+  feature，因为它绕过了 io-uring 的 `MSG_ZEROCOPY` 标志，该标志与 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