xref: /fizz/
Name Date Size

..27-Apr.-20224 KiB

.github/workflows/H11-Oct.-20214 KiB

.gitignoreH A D11-Oct.-20215

build/H19-May-20224 KiB

CODE_OF_CONDUCT.mdH A D11-Oct.-20213.3 KiB

CONTRIBUTING.mdH A D11-Oct.-20211.3 KiB

fizz/H03-Jun.-20224 KiB

LICENSEH A D11-Oct.-20211.5 KiB

logo2x.pngH A D11-Oct.-202122.2 KiB

README.mdH A D05-Mar.-20226.7 KiB

README.md

1<p align="center">
2  <img width="500" height="216" alt="Fizz" src="logo2x.png">
3</p>
4
5[![Support Ukraine](https://img.shields.io/badge/Support-Ukraine-FFD500?style=flat&labelColor=005BBB)](https://opensource.fb.com/support-ukraine)
6![linux](https://github.com/facebookincubator/fizz/workflows/linux/badge.svg?branch=main)
7![mac](https://github.com/facebookincubator/fizz/workflows/mac/badge.svg?branch=main)
8![windows](https://github.com/facebookincubator/fizz/workflows/windows/badge.svg?branch=main)
9
10Fizz is a TLS 1.3 implementation.
11
12Fizz currently supports TLS 1.3 drafts 28, 26 (both wire-compatible with the
13final specification), and 23. All major handshake modes are supported, including
14PSK resumption, early data, client authentication, and HelloRetryRequest.
15
16More background and details are available on the
17[Facebook Code Blog](https://engineering.fb.com/2018/08/06/security/fizz/).
18
19## Dependencies
20
21Fizz largely depends on three libraries: [folly](https://www.github.com/facebook/folly),
22[OpenSSL](https://www.openssl.org/), and [libsodium](https://github.com/jedisct1/libsodium).
23
24## Source Layout
25- `fizz/crypto`:   Cryptographic primitive implementations (most are wrapping
26                   OpenSSL or libsodium)
27- `fizz/record`:   TLS 1.3 record layer parsing
28- `fizz/protocol`: Common protocol code shared between client and server
29- `fizz/client`:   Client protocol implementation
30- `fizz/server`:   Server protocol implementation
31- `fizz/tool`:     Example CLI app source
32
33## Design
34
35The core protocol implementations are in `ClientProtocol` and `ServerProtocol`.
36`FizzClientContext` and `FizzServerContext` provide configuration options.
37`FizzClient` and `FizzServer` (which both inherit from `FizzBase`) provide
38applications with an interface to interact with the state machine.
39`FizzClient`/`FizzServer` receives events from the application layer, invokes the
40correct event handler, and invokes the application `ActionVisitor` to process the
41actions.
42
43`AsyncFizzClient` and `AsyncFizzServer` provide implementations of the folly
44`AsyncTransportWrapper` interface. They own an underlying transport (for example
45`AsyncSocket`) and perform the TLS handshake and encrypt/decrypt application
46data.
47
48## Features
49
50Fizz has several important features needed from a modern TLS library.
51
52### Performance
53
54Fizz supports scatter/gather IO by default via folly's IOBufs, and will encrypt
55data in-place whenever possible, saving memcpys. Due to this and several
56other optimizations, we found in our load balancer benchmarks that Fizz has 10%
57higher throughput than our prior SSL library which uses folly's
58[AsyncSSLSocket](https://github.com/facebook/folly/blob/master/folly/io/async/AsyncSSLSocket.h).
59Fizz also consumes less memory per connection than AsyncSSLSocket.
60
61### Async by default
62
63Fizz has asynchronous APIs to be able to offload functions like certificate
64signing and ticket decryption. The API is based on folly's
65[Futures](https://github.com/facebook/folly/tree/master/folly/futures) for painless
66async programming.
67
68### TLS features
69
70Fizz supports APIs like exported keying material as well as zero-copy APIs
71needed to use TLS in other protocols like QUIC.
72
73### Secure design abstractions
74
75Fizz is built on a custom state machine which uses the power of the C++ type system
76to treat states and actions as types of their own. As the code changes, this allows us
77to catch invalid state transitions as compilation errors instead of runtime errors and
78helps us move fast.
79
80## Sample Applications
81
82Fizz includes an example program that showcases the basic client/server functionality
83supported by Fizz. The binary is called `fizz` and it has similar usage to the
84`openssl` or `bssl` commands.
85
86For example, to start a TLS server on port 443 with a specified cert:
87```sh
88fizz server -accept 443 -cert foo.pem -key foo.key
89```
90
91Then, on the same host, you can connect with:
92
93```sh
94fizz client -connect localhost:443
95```
96
97Both ends will echo whatever data they receive and send any terminal input to the
98peer. Hitting CTRL+D on either end will terminate the connection.
99
100The source code for this program can be found under `fizz/tool`.
101
102## Building
103
104### Ubuntu 16.04 LTS
105
106To begin, you should install the dependencies we need for build. This largely
107consists of [folly](https://github.com/facebook/folly)'s dependencies, as well as
108[libsodium](https://github.com/jedisct1/libsodium).
109
110```sh
111sudo apt-get install \
112    g++ \
113    cmake \
114    libboost-all-dev \
115    libevent-dev \
116    libdouble-conversion-dev \
117    libgoogle-glog-dev \
118    libgflags-dev \
119    libiberty-dev \
120    liblz4-dev \
121    liblzma-dev \
122    libsnappy-dev \
123    make \
124    zlib1g-dev \
125    binutils-dev \
126    libjemalloc-dev \
127    libssl-dev \
128    pkg-config \
129    libsodium-dev
130```
131
132Then, build and install folly:
133
134```sh
135git clone https://github.com/facebook/folly
136mkdir folly/build_ && cd folly/build_
137cmake ..
138make -j $(nproc)
139sudo make install
140```
141
142And lastly, build and install fizz.
143
144```sh
145cd ../..
146git clone https://github.com/facebookincubator/fizz
147mkdir fizz/build_ && cd fizz/build_
148cmake ../fizz
149make -j $(nproc)
150sudo make install
151```
152
153### Building on Mac
154
155The following instructions were tested on MacOS High Sierra
156with Xcode 9.4.1. They should work with later Xcode versions as well.
157
158Run the helper script from within the `fizz` subdirectory. The helper
159script assumes that you have homebrew installed and are using homebrew
160as your package manager. To install homebrew use the instructions on
161the homebrew [website](https://brew.sh/).
162
163It will install and link the required dependencies and also build folly.
164This may take several minutes the first time.
165
166```sh
167cd fizz
168./mac-build.sh
169```
170
171After building, the directory `out/` will contain the libraries as well as
172`out/bin` will contain the `ClientSocket` and `ServerSocket` binaries.
173Running it again will be faster and only rebuild `fizz`.
174
175You can also install both `fizz` as well as `folly` to a custom directory
176using the build script, by supplying an `INSTALL_PREFIX` env var.
177
178```sh
179INSTALL_PREFIX=/usr/local ./mac-build.sh
180```
181
182You might need to run the script as root to install to certain directories.
183
184## Contributing
185
186We'd love to have your help in making Fizz better. If you're interested, please
187read our guide to [guide to contributing](CONTRIBUTING.md)
188
189## License
190Fizz is BSD licensed, as found in the LICENSE file.
191
192## Reporting and Fixing Security Issues
193
194Please do not open GitHub issues or pull requests - this makes the problem
195immediately visible to everyone, including malicious actors. Security issues in
196Fizz can be safely reported via Facebook's Whitehat Bug Bounty program:
197
198https://www.facebook.com/whitehat
199
200Facebook's security team will triage your report and determine whether or not is
201it eligible for a bounty under our program.
202