xref: /aosp_15_r20/external/bcc/tools/sslsniff_example.txt (revision 387f9dfdfa2baef462e92476d413c7bc2470293e) 
1Demonstrations of sslsniff.py
2
3
4This tool traces the write/send and read/recv functions of OpenSSL,
5GnuTLS and NSS.  Data passed to this functions is printed as plain
6text.  Useful, for example, to sniff HTTP before encrypted with SSL.
7
8
9Output of tool executing in other shell "curl https://example.com"
10
11% sudo python sslsniff.py
12FUNC         TIME(s)            COMM             PID    LEN
13WRITE/SEND   0.000000000        curl             12915  75
14----- DATA -----
15GET / HTTP/1.1
16Host: example.com
17User-Agent: curl/7.50.1
18Accept: */*
19
20
21----- END DATA -----
22
23READ/RECV    0.127144585        curl             12915  333
24----- DATA -----
25HTTP/1.1 200 OK
26Cache-Control: max-age=604800
27Content-Type: text/html
28Date: Tue, 16 Aug 2016 15:42:12 GMT
29Etag: "359670651+gzip+ident"
30Expires: Tue, 23 Aug 2016 15:42:12 GMT
31Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT
32Server: ECS (iad/18CB)
33Vary: Accept-Encoding
34X-Cache: HIT
35x-ec-custom-error: 1
36Content-Length: 1270
37
38
39----- END DATA -----
40
41READ/RECV    0.129967972        curl             12915  1270
42----- DATA -----
43<!doctype html>
44<html>
45<head>
46    <title>Example Domain</title>
47
48    <meta charset="utf-8" />
49    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
50    <meta name="viewport" content="width=device-width, initial-scale=1" />
51    <style type="text/css">
52    body {
53        background-color: #f0f0f2;
54        margin: 0;
55        padding: 0;
56        font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif;
57
58    }
59    div {
60        w
61----- END DATA (TRUNCATED, 798 bytes lost) -----
62
63Using the --hexdump option you will get the exact same output, only the lines
64between DATA and END DATA will differ. Those will be replaced with a 16 byte
65(32 characters) wide hex-dump, an example of a block of output from sslsniff
66called with that option is
67
68READ/RECV    7.405609173        curl             201942 1256
69----- DATA -----
703c21646f63747970652068746d6c3e0a
713c68746d6c3e0a3c686561643e0a2020
7220203c7469746c653e4578616d706c65
7320446f6d61696e3c2f7469746c653e0a
740a202020203c6d657461206368617273
7565743d227574662d3822202f3e0a2020
7620203c6d65746120687474702d657175
7769763d22436f6e74656e742d74797065
782220636f6e74656e743d22746578742f
7968746d6c3b20636861727365743d7574
80662d3822202f3e0a202020203c6d6574
8161206e616d653d2276696577706f7274
822220636f6e74656e743d227769647468
833d6465766963652d77696474682c2069
846e697469616c2d7363616c653d312220
852f3e0a202020203c7374796c65207479
8670653d22746578742f637373223e0a20
87202020626f6479207b0a202020202020
8820206261636b67726f756e642d636f6c
896f723a20236630663066323b0a202020
9020202020206d617267696e3a20303b0a
91202020202020202070616464696e673a
9220303b0a2020202020202020666f6e74
932d66616d696c793a202d6170706c652d
9473797374656d2c2073797374656d2d75
95692c20426c696e6b4d61635379737465
966d466f6e742c20225365676f65205549
97222c20224f70656e2053616e73222c20
982248656c766574696361204e65756522
99----- END DATA (TRUNCATED, 792 bytes lost) -----
100
101This is useful to sniff binary protocols where the UTF-8 decode might insert a
102lot of characters that are not printable or even Unicode replacement
103characters.
104
105
106Use -l or --latency option to show function latency, and show handshake latency
107by using both -l and --handshake. This is useful for SSL/TLS performance
108analysis. Tracing output of "echo | openssl s_client -connect example.com:443":
109
110# ./sslsniff.py -l --handshake
111FUNC         TIME(s)            COMM             PID     LEN    LAT(ms)
112WRITE/SEND   0.000000000        openssl          10377   1      0.005
113----- DATA -----
114
115
116----- END DATA -----
117
118Trace localhost server instead of example.com. It takes 0.7ms for server
119handshake before secure connection is ready for initial SSL_read or SSL_write.
120
121# ./sslsniff.py -l --handshake
122FUNC         TIME(s)            COMM             PID     LEN    LAT(ms)
123HANDSHAKE    0.000000000        nginx            7081    1      0.699
124WRITE/SEND   0.000132180        openssl          14800   1      0.010
125----- DATA -----
126
127
128----- END DATA -----
129
130READ/RECV    0.000136583        nginx            7081    1      0.004
131----- DATA -----
132
133
134----- END DATA -----
135
136Tracing output of "echo | gnutls-cli -p 443 example.com":
137
138# ./sslsniff.py -l --handshake
139FUNC         TIME(s)            COMM             PID     LEN    LAT(ms)
140WRITE/SEND   0.000000000        gnutls-cli       43554   1      0.012
141----- DATA -----
142
143
144----- END DATA -----
145
146Tracing output of "echo | gnutls-cli -p 443 --insecure localhost":
147
148# ./sslsniff.py -l --handshake
149FUNC         TIME(s)            COMM             PID     LEN    LAT(ms)
150HANDSHAKE    0.000000000        nginx            7081    1      0.710
151WRITE/SEND   0.000045126        gnutls-cli       43752   1      0.014
152----- DATA -----
153
154
155----- END DATA -----
156
157READ/RECV    0.000049464        nginx            7081    1      0.004
158----- DATA -----
159
160
161----- END DATA -----
162
163Tracing few extra libraries (useful for docker containers and other isolated
164apps)
165
166# ./sslsniff.py --extra-lib openssl:/var/lib/docker/overlay2/l/S4EMHE/lib/libssl.so.1.1
167
168
169
170USAGE message:
171
172usage: sslsniff.py [-h] [-p PID] [-u UID] [-x] [-c COMM] [-o] [-g] [-n] [-d]
173                   [--hexdump] [--max-buffer-size MAX_BUFFER_SIZE] [-l]
174                   [--handshake] [--extra-lib EXTRA_LIB]
175
176Sniff SSL data
177
178optional arguments:
179  -h, --help            show this help message and exit
180  -p PID, --pid PID     sniff this PID only.
181  -u UID, --uid UID     sniff this UID only.
182  -x, --extra           show extra fields (UID, TID)
183  -c COMM, --comm COMM  sniff only commands matching string.
184  -o, --no-openssl      do not show OpenSSL calls.
185  -g, --no-gnutls       do not show GnuTLS calls.
186  -n, --no-nss          do not show NSS calls.
187  -d, --debug           debug mode.
188  --hexdump             show data as hexdump instead of trying to decode it as
189                        UTF-8
190  --max-buffer-size MAX_BUFFER_SIZE
191                        Size of captured buffer
192  -l, --latency         show function latency
193  --handshake           show SSL handshake latency, enabled only if latency
194                        option is on.
195  --extra-lib EXTRA_LIB
196                        Intercept calls from extra library
197                        (format: lib_type:lib_path)
198
199
200
201examples:
202    ./sslsniff              # sniff OpenSSL and GnuTLS functions
203    ./sslsniff -p 181       # sniff PID 181 only
204    ./sslsniff -u 1000      # sniff only UID 1000
205    ./sslsniff -c curl      # sniff curl command only
206    ./sslsniff --no-openssl # don't show OpenSSL calls
207    ./sslsniff --no-gnutls  # don't show GnuTLS calls
208    ./sslsniff --no-nss     # don't show NSS calls
209    ./sslsniff --hexdump    # show data as hex instead of trying to decode it as UTF-8
210    ./sslsniff -x           # show process UID and TID
211    ./sslsniff -l           # show function latency
212    ./sslsniff -l --handshake  # show SSL handshake latency
213    ./sslsniff --extra-lib openssl:/path/libssl.so.1.1 # sniff extra library
214