Skip to content

Commit

Permalink
docs : add keylog model documents.
Browse files Browse the repository at this point in the history
Signed-off-by: cfc4n <cfc4n.cs@gmail.com>
  • Loading branch information
cfc4n committed Dec 2, 2023
1 parent b7df4cf commit fa7f33f
Show file tree
Hide file tree
Showing 3 changed files with 89 additions and 19 deletions.
62 changes: 51 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,6 @@
* bash audit, capture bash command for Host Security Audit.
* mysql query SQL audit, support mysqld 5.6\5.7\8.0, and mariadDB.

# eCapture Architecture
![](./images/ecapture-architecture.png)

# eCapture User Manual

[![eCapture User Manual](./images/ecapture-user-manual.png)](https://www.youtube.com/watch?v=CoDIjEQCvvA "eCapture User Manual")
Expand All @@ -53,18 +50,58 @@ flag to set shard library path.

If target program is compile statically, you can set program path as `--libssl` flag value directly。

### Pcapng result
## Modules
The eCapture tool comprises 8 modules that respectively support plaintext capture for TLS/SSL encryption libraries like OpenSSL, GnuTLS, NSPR, BoringSSL, and GoTLS. Additionally, it facilitates software audits for Bash, MySQL, and PostgreSQL applications.
* bash capture bash command
* gnutls capture gnutls text content without CA cert for gnutls libraries.
* gotls Capturing plaintext communication from Golang programs encrypted with TLS/HTTPS.
* mysqld capture sql queries from mysqld 5.6/5.7/8.0 .
* nss capture nss/nspr encrypted text content without CA cert for nss/nspr libraries.
* postgres capture sql queries from postgres 10+.
* tls use to capture tls/ssl text content without CA cert. (Support openssl 1.0.x/1.1.x/3.0.x or newer).
You can use `ecapture -h` to view the list of subcommands.

`./ecapture tls -i eth0 -w pcapng -p 443` capture plaintext packets save as pcapng file, use `Wireshark` read it
directly.
## OpenSSL Module

### plaintext result
The OpenSSL module supports three capture modes:

`./ecapture tls` will capture all plaintext context ,output to console, and capture `Master Secret` of `openssl TLS`
save to `ecapture_masterkey.log`. You can also use `tcpdump` to capture raw packet,and use `Wireshark` to read them
with `Master Secret` settings.
- `pcap`/`pcapng` mode stores captured plaintext data in pcap-NG format.
- `keylog`/`key` mode saves the TLS handshake keys to a file.
- `text` mode directly captures plaintext data, either outputting to a specified file or printing to the command line.

>
### Pcap Mode

You can specify `-m pcap` or `-m pcapng` and use it in conjunction with `--pcapfile` and `-i` parameters. The default value for `--pcapfile` is `ecapture_openssl.pcapng`.

```shell
./ecapture tls -m pcap -i eth0 --pcapfile=ecapture.pcapng --port=443
```

This command saves captured plaintext data packets as a pcapng file, which can be viewed using `Wireshark`.

### Keylog Mode

You can specify `-m keylog` or `-m key` and use it in conjunction with the `--keylogfile` parameter, which defaults to `ecapture_masterkey.log`.

The captured OpenSSL TLS `Master Secret` information is saved to `--keylogfile`. You can also enable `tcpdump` packet capture and then use `Wireshark` to open the file and set the `Master Secret` path to view plaintext data packets.

```shell
./ecapture tls -m keylog -keylogfile=openssl_keylog.log
```

You can also directly use the `tshark` software for real-time decryption and display:

```shell
tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_data -f "port 443" -i eth0
```

### Text Mode

`./ecapture tls -m text` will output all plaintext data packets. (Starting from v0.7.0, it no longer captures SSLKEYLOG information.)

## GoTLS Module

Similar to the OpenSSL module.

### check your server BTF config:

Expand Down Expand Up @@ -114,6 +151,9 @@ capture bash command.
ps -ef | grep foo
```

# eCapture Architecture
![](./images/ecapture-architecture.png)

# What's eBPF
[eBPF](https://ebpf.io)

Expand Down
1 change: 1 addition & 0 deletions README_CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,7 @@ tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_

## gotls 模块
与openssl模块类似。

### 验证方法:

```shell
Expand Down
45 changes: 37 additions & 8 deletions README_JA.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,18 +53,47 @@ eCapture はデフォルトで `/etc/ld.so.conf` ファイルを検索し、

ターゲットプログラムが静的にコンパイルされる場合、プログラムパスを `--libssl` フラグの値として直接設定することができます。

### Pcapng 結果
## 模块介绍
eCapture 有8个模块,分别支持openssl/gnutls/nspr/boringssl/gotls等类库的TLS/SSL加密类库的明文捕获、Bash、Mysql、PostGres软件审计。
* bash capture bash command
* gnutls capture gnutls text content without CA cert for gnutls libraries.
* gotls Capturing plaintext communication from Golang programs encrypted with TLS/HTTPS.
* mysqld capture sql queries from mysqld 5.6/5.7/8.0 .
* nss capture nss/nspr encrypted text content without CA cert for nss/nspr libraries.
* postgres capture sql queries from postgres 10+.
* tls use to capture tls/ssl text content without CA cert. (Support openssl 1.0.x/1.1.x/3.0.x or newer).

你可以通过`ecapture -h`来查看这些自命令列表。

## openssl 模块
openssl模块支持3中捕获模式
* pcap/pcapng模式,将捕获的明文数据以pcap-NG格式存储。
* keylog/key模式,保存TLS的握手密钥到文件中。
* text模式,直接捕获明文数据,输出到指定文件中,或者打印到命令行。
### Pcap 模式
你可以通过`-m pcap``-m pcapng`参数来指定,需要配合`--pcapfile``-i`参数使用。其中`--pcapfile`参数的默认值为`ecapture_openssl.pcapng`
```shell
./ecapture tls -m pcap -i eth0 --pcapfile=ecapture.pcapng --port=443
```
将捕获的明文数据包保存为pcapng文件,可以使用`Wireshark`打开查看。

`./ecapture tls -i eth0 -w pcapng -p 443` 平文パケットをキャプチャして pcapng ファイルとして保存し、 `Wireshark`
でそれを直接読みます。
### keylog 模式
你可以通过`-m keylog``-m key`参数来指定,需要配合`--keylogfile`参数使用,默认为`ecapture_masterkey.log`
捕获的openssl TLS的密钥`Master Secret`信息,将保存到`--keylogfile`中。你也可以同时开启`tcpdump`抓包,再使用`Wireshark`打开,设置`Master Secret`路径,查看明文数据包。
```shell
./ecapture tls -m keylog -keylogfile=openssl_keylog.log
```

### 平文結果
也可以直接使用`tshark`软件实时解密展示。
```shell
tshark -o tls.keylog_file:ecapture_masterkey.log -Y http -T fields -e http.file_data -f "port 443" -i eth0
```
### text 模式
`./ecapture tls -m text ` 将会输出所有的明文数据包。(v0.7.0起,不再捕获SSLKEYLOG信息。)

`./ecapture tls` はすべてのプレーンテキストのコンテキストをキャプチャしてコンソールに出力し、`openssl TLS``Master Secret` をキャプチャして
`ecapture_masterkey.log` に保存することができます。また、`tcpdump` を使って生のパケットをキャプチャし、
`Wireshark` を使って `Master Secret` 設定でそれらを読み込むことができます。

>
## gotls 模块
与openssl模块类似。

### サーバーの BTF 設定を確認:

Expand Down

0 comments on commit fa7f33f

Please sign in to comment.