1# Fuzzer for libgsm codec
2
3## Plugin Design Considerations
4The fuzzer plugin for GSM is designed based on the understanding of the
5codec and tries to achieve the following:
6
7##### Maximize code coverage
8The configuration parameters are not hardcoded, but instead selected based on
9incoming data. This ensures more code paths are reached by the fuzzer.
10
11GSM supports the following options:
121. Verbosity (parameter name: `GSM_VERBOSE`)
132. Fastness (parameter name: `GSM_OPT_FAST`)
143. WAV49 Format (parameter name: `GSM_OPT_WAV49`)
154. LTP Cut speed-up (encoder only) (parameter name: `GSM_OPT_LTP_CUT`)
16
17| Parameter| Valid Values| Configured Value|
18|------------- |-------------| ----- |
19| `GSM_VERBOSE` | 0. `Verbosity disabled` 1. `Verbosity enabled` | Bit 0 (LSB) of 1st byte of data. |
20| `GSM_OPT_FAST`   | 0. `Regular algorithm will be used` 1. `Faster version of the algorithm will be used`  | Bit 1 (LSB) of 1st byte of data. |
21| `GSM_OPT_LTP_CUT`   | 0. `Disable LTP cut-off optimization` 1. `Enable LTP cut-off optimization`  | Bit 2 (LSB) of 1st byte of data. |
22| `GSM_OPT_WAV49`   | 0. `Disable WAV49 output in the encoder.` 1. `Enable WAV49 format in the encoder.`  | Bit 3 (LSB) of 1st byte of data. |
23
24This also ensures that the plugin is always deterministic for any given input.
25
26##### Maximize utilization of input data
27The plugin feeds the entire input data to the codec using a loop.
28###### For the Decoder:
29 * If the size of media file is less than 65 bytes, (65 - size) bytes are padded and then sent to
30 the decoder so that decode happens for all the input files, regardless of their size.
31 GSM decoder consumes alternating frames of 33 and 32 bytes, so 65 bytes of input are needed.
32 * If the decode operation was successful, the input is advanced by the frame size
33 * If the decode operation was un-successful, the input is still advanced by frame size so
34that the fuzzer can proceed to feed the next frame.
35###### For the Encoder:
36 * If the size of media file is less than 320 bytes(160 signed 16-bit words), bytes are padded and then sent to
37 the encoder so that encode happens for all the input files, regardless of their size.
38 GSM encoder consumes 160 signed 16-bit words, so 320 bytes of input are needed.
39 * If the encode operation was successful, the input is advanced by the frame size
40 * If the encode operation was un-successful, the input is still advanced by frame size so
41that the fuzzer can proceed to feed the next frame.
42
43This ensures that the plugin tolerates any kind of input (empty, huge,
44malformed, etc) and doesnt `exit()` on any input and thereby increasing the
45chance of identifying vulnerabilities.
46
47## Build
48
49This describes steps to build gsm_dec_fuzzer and gsm_enc_fuzzer binaries.
50
51### Android
52
53#### Steps to build
54Build the fuzzer
55```
56  $ mm -j$(nproc) gsm_dec_fuzzer
57  $ mm -j$(nproc) gsm_enc_fuzzer
58```
59
60#### Steps to run
61Create a directory CORPUS_DIR and copy some gsm files (decoder)/raw files (encoder) to that folder
62Push this directory to device.
63
64To run on device
65```
66  $ adb sync data
67  $ adb shell /data/fuzz/arm64/gsm_dec_fuzzer/gsm_dec_fuzzer CORPUS_DIR
68  $ adb shell /data/fuzz/arm64/gsm_enc_fuzzer/gsm_enc_fuzzer CORPUS_DIR
69```
70To run on host
71```
72  $ $ANDROID_HOST_OUT/fuzz/x86_64/gsm_dec_fuzzer/gsm_dec_fuzzer CORPUS_DIR
73  $ $ANDROID_HOST_OUT/fuzz/x86_64/gsm_enc_fuzzer/gsm_enc_fuzzer CORPUS_DIR
74```
75
76## References:
77 * http://llvm.org/docs/LibFuzzer.html
78 * https://github.com/google/oss-fuzz
79