README.md revision da710add
150aadb33SDmitri TikhonovLiteSpeed QUIC (LSQUIC) Client Library README
250aadb33SDmitri Tikhonov=============================================
350aadb33SDmitri Tikhonov
450aadb33SDmitri TikhonovDescription
550aadb33SDmitri Tikhonov-----------
650aadb33SDmitri Tikhonov
750aadb33SDmitri TikhonovLiteSpeed QUIC (LSQUIC) Client Library is an open-source implementation
850aadb33SDmitri Tikhonovof QUIC functionality for clients.  It is released in the hope to speed
950aadb33SDmitri Tikhonovthe adoption of QUIC.  Most of the code in this distribution is used in
1050aadb33SDmitri Tikhonovour own products: LiteSpeed Web Server and ADC.  We think it is free of
1150aadb33SDmitri Tikhonovmajor problems.  Nevertheless, do not hesitate to report bugs back to us.
1250aadb33SDmitri TikhonovEven better, send us fixes and improvements!
1350aadb33SDmitri Tikhonov
141b97e4afSDmitri TikhonovCurrently supported QUIC versions are Q035, Q037, Q038, Q039, and Q041.
1550aadb33SDmitri TikhonovSupport for newer versions will be added soon after they are released.
1650aadb33SDmitri TikhonovThe version(s) specified by IETF QUIC WG will be added once the IETF
1750aadb33SDmitri Tikhonovversion of the protocol settles down a little.
1850aadb33SDmitri Tikhonov
1950aadb33SDmitri TikhonovDocumentation
2050aadb33SDmitri Tikhonov-------------
2150aadb33SDmitri Tikhonov
2250aadb33SDmitri TikhonovThe documentation for this module is admittedly sparse.  The API is
2350aadb33SDmitri Tikhonovdocumented in include/lsquic.h.  If you have doxygen, you can run
24e0197994SDmitri Tikhonov`doxygen dox.cfg` or `make docs`.  The example program is
2550aadb33SDmitri Tikhonovtest/http_client.c: a bare-bones, but working, QUIC client.  Have a look
2650aadb33SDmitri Tikhonovin EXAMPLES.txt to see how it can be used.
2750aadb33SDmitri Tikhonov
28e0197994SDmitri TikhonovRequirements
29e0197994SDmitri Tikhonov------------
3050aadb33SDmitri Tikhonov
31e0197994SDmitri TikhonovTo build LSQUIC, you need CMake, zlib, and BoringSSL.  The example program
32e0197994SDmitri Tikhonovuses libevent to provide the event loop.
3350aadb33SDmitri Tikhonov
34e0197994SDmitri TikhonovBuilding BoringSSL
35e0197994SDmitri Tikhonov------------------
36e0197994SDmitri Tikhonov
37e0197994SDmitri TikhonovBoringSSL is not packaged; you have to build it yourself.  The process is
38e0197994SDmitri Tikhonovstraightforward.  You will need `go` installed.
39e0197994SDmitri Tikhonov
40e0197994SDmitri Tikhonov1. Clone BoringSSL by issuing the following command:
41e0197994SDmitri Tikhonov
42e0197994SDmitri Tikhonov```
43e0197994SDmitri Tikhonovgit clone https://boringssl.googlesource.com/boringssl
44e0197994SDmitri Tikhonovcd boringssl
45e0197994SDmitri Tikhonov```
46e0197994SDmitri Tikhonov
47e0197994SDmitri Tikhonov2. Check out stable branch:
48e0197994SDmitri Tikhonov
49e0197994SDmitri Tikhonov```
5067b0dc15SDmitri Tikhonovgit checkout chromium-stable
51e0197994SDmitri Tikhonov```
52e0197994SDmitri Tikhonov
53e0197994SDmitri Tikhonov3. Compile the library
54e0197994SDmitri Tikhonov
55e0197994SDmitri Tikhonov```
56e0197994SDmitri Tikhonovcmake . &&  make
57e0197994SDmitri Tikhonov```
58e0197994SDmitri Tikhonov
59e0197994SDmitri TikhonovIf you want to turn on optimizations, do
60e0197994SDmitri Tikhonov
61e0197994SDmitri Tikhonov```
62e0197994SDmitri Tikhonovcmake -DCMAKE_BUILD_TYPE=Release . && make
63e0197994SDmitri Tikhonov```
64e0197994SDmitri Tikhonov
65e0197994SDmitri Tikhonov4. Install the library
66e0197994SDmitri Tikhonov
67e0197994SDmitri TikhonovThis is the manual step.  You will need to copy library files manually.
68e0197994SDmitri TikhonovLSQUIC client library needs two: `ssl/libssl.a` and `crypto/libcrypto.a`.
69e0197994SDmitri TikhonovTo install these in `/usr/local/lib`, you should do the following:
70e0197994SDmitri Tikhonov
71e0197994SDmitri Tikhonov```
72e0197994SDmitri TikhonovBORINGSSL_SOURCE=$PWD
73e0197994SDmitri Tikhonovcd /usr/local/lib
7467b0dc15SDmitri Tikhonovsudo cp $BORINGSSL_SOURCE/ssl/libssl.a .
7567b0dc15SDmitri Tikhonovsudo cp $BORINGSSL_SOURCE/crypto/libcrypto.a .
76e0197994SDmitri Tikhonov```
77e0197994SDmitri Tikhonov
78e0197994SDmitri TikhonovIf you do not want to install the library (or do not have root), you
79e0197994SDmitri Tikhonovcan do this instead:
80e0197994SDmitri Tikhonov
81e0197994SDmitri Tikhonov```
82e0197994SDmitri TikhonovBORINGSSL_SOURCE=$PWD
83e0197994SDmitri Tikhonovmkdir -p $HOME/tmp/boringssl-libs
84e0197994SDmitri Tikhonovcd $HOME/tmp/boringssl-libs
85e0197994SDmitri Tikhonovln -s $BORINGSSL_SOURCE/ssl/libssl.a
86e0197994SDmitri Tikhonovln -s $BORINGSSL_SOURCE/crypto/libcrypto.a
87e0197994SDmitri Tikhonov```
88e0197994SDmitri Tikhonov
89e0197994SDmitri TikhonovBuilding LSQUIC Client Library
90e0197994SDmitri Tikhonov------------------------------
91e0197994SDmitri Tikhonov
92e0197994SDmitri TikhonovLSQUIC's `http_client` and the tests link BoringSSL libraries statically.
93e0197994SDmitri TikhonovFollowing previous section, you can build LSQUIC as follows:
94e0197994SDmitri Tikhonov
9567b0dc15SDmitri Tikhonov1. Get the source code
9667b0dc15SDmitri Tikhonov
9767b0dc15SDmitri Tikhonov```
9867b0dc15SDmitri Tikhonovgit clone https://github.com/litespeedtech/lsquic-client.git
9967b0dc15SDmitri Tikhonovcd lsquic-client
10067b0dc15SDmitri Tikhonov```
10167b0dc15SDmitri Tikhonov
10267b0dc15SDmitri Tikhonov2. Compile the library
10367b0dc15SDmitri Tikhonov
10467b0dc15SDmitri Tikhonov
105e0197994SDmitri Tikhonov```
106e0197994SDmitri Tikhonovcmake -DBORINGSSL_INCLUDE=$BORINGSSL_SOURCE/include \
107e0197994SDmitri Tikhonov                                -DBORINGSSL_LIB=$HOME/tmp/boringssl-libs .
108e0197994SDmitri Tikhonovmake
109e0197994SDmitri Tikhonov```
110e0197994SDmitri Tikhonov
11167b0dc15SDmitri Tikhonov3. Run tests
112e0197994SDmitri Tikhonov
113e0197994SDmitri Tikhonov```
114e0197994SDmitri Tikhonovmake test
115e0197994SDmitri Tikhonov```
116e0197994SDmitri Tikhonov
117306ecefeSBrian ProdoehlBuilding with Docker
118306ecefeSBrian Prodoehl---------
119306ecefeSBrian ProdoehlThe library and http_client example can be built with Docker.
120306ecefeSBrian Prodoehl```
121306ecefeSBrian Prodoehldocker build -t lsquic-client .
122306ecefeSBrian Prodoehl```
123306ecefeSBrian Prodoehl
124306ecefeSBrian ProdoehlThen you can use the http_client example from the command line.
125306ecefeSBrian Prodoehl```
126306ecefeSBrian Prodoehldocker run -it --rm lsquic-client http_client -H www.google.com -s 74.125.22.106:443 -p /
127306ecefeSBrian Prodoehl```
128306ecefeSBrian Prodoehl
129e0197994SDmitri TikhonovPlatforms
130e0197994SDmitri Tikhonov---------
131e0197994SDmitri Tikhonov
132e0197994SDmitri TikhonovThe client library has been tested on the following platforms:
133e0197994SDmitri Tikhonov- Linux
134e0197994SDmitri Tikhonov  - x86_64
135e0197994SDmitri Tikhonov  - ARM (Raspberry Pi 3)
136e0197994SDmitri Tikhonov- FreeBSD
137e0197994SDmitri Tikhonov  - i386
138da710addSDmitri Tikhonov- Windows
139da710addSDmitri Tikhonov  - x86_64
140e0197994SDmitri Tikhonov- MacOS
141e0197994SDmitri Tikhonov  - x86_64
14250aadb33SDmitri Tikhonov
14350aadb33SDmitri TikhonovHave fun,
14450aadb33SDmitri Tikhonov
14550aadb33SDmitri TikhonovLiteSpeed QUIC Team.
14650aadb33SDmitri Tikhonov
14750aadb33SDmitri TikhonovCopyright (c) 2017 LiteSpeed Technologies Inc
148