README.md
1# Fuzzer for libopus decoder
2
3## Plugin Design Considerations
4The fuzzer plugin for opus decoder is designed based on the understanding of the
5codec and tries to achieve the following:
6
7##### Maximize code coverage
8
9This fuzzer provides support for both single stream and multi stream inputs,
10thus enabling fuzzing for API's provided for single stream as well as multi
11stream.
12
13Following arguments are passed to OPUS_DEC_CREATE_API:
14
151. Sampling frequency (parameter name: `Fs`)
162. Number of channels (parameter name: `channels`)
17
18| Parameter| Valid Values| Configured Value|
19|------------- |-------------| ----- |
20| `Fs` | `8000 ` `12000 ` `16000 ` `24000 ` `48000 ` | Derived from Byte-9 of input stream|
21| `channels` | `1 ` `2 ` | Derived from Byte-9 of input stream |
22
23##### Maximize utilization of input data
24The plugin feeds the entire input data to the codec. Frame sizes are determined only
25after the call to extractor, so in absence of call to extractor,
26we feed the entire data to the decoder.
27This ensures that the plugin tolerates any kind of input (empty, huge,
28malformed, etc) and doesnt `exit()` on any input and thereby increasing the
29chance of identifying vulnerabilities.
30
31## Build
32
33This describes steps to build opus_dec_fuzzer and opus_multistream_dec_fuzzer binary.
34
35## Android
36
37### Steps to build
38Build the fuzzer
39```
40 $ mm -j$(nproc) opus_dec_fuzzer
41 $ mm -j$(nproc) opus_multistream_dec_fuzzer
42```
43
44### Steps to run
45Create a directory CORPUS_DIR and copy some opus files to that folder.
46Push this directory to device.
47
48To run on device
49```
50 $ adb sync data
51 $ adb shell /data/fuzz/arm64/opus_dec_fuzzer/opus_dec_fuzzer CORPUS_DIR
52 $ adb shell /data/fuzz/arm64/opus_multistream_dec_fuzzer/opus_multistream_dec_fuzzer CORPUS_DIR
53```
54To run on host
55```
56 $ $ANDROID_HOST_OUT/fuzz/x86_64/opus_dec_fuzzer/opus_dec_fuzzer CORPUS_DIR
57 $ $ANDROID_HOST_OUT/fuzz/x86_64/opus_multistream_dec_fuzzer/opus_multistream_dec_fuzzer CORPUS_DIR
58```
59
60# Fuzzer for libopus encoder
61
62## Plugin Design Considerations
63The fuzzer plugin for opus encoder is designed based on the understanding of the
64codec and tries to achieve the following:
65
66##### Maximize code coverage
67
68This fuzzer provides support for both single stream and multi stream inputs,
69thus enabling fuzzing for API's provided for single stream as well as multi
70stream.
71Following arguments are passed to OPUS_ENC_CREATE_API:
72
731. Sampling rate (parameter name: `sampleRate`)
742. Number of channels (parameter name: `channels`)
75
76| Parameter| Valid Values| Configured Value|
77|------------- |-------------| ----- |
78| `sampleRate` | `8000 ` `12000 ` `16000 ` `24000 ` `48000 ` | An index ranging from 0-4 is calculated using first byte of data which is used to assign value to `sampleRate` from array `kSampleRates`|
79| `channels` (single stream) | `1 ` `2 ` | Calculated using second byte of data |
80| `channels` (multi stream) | In range `1 `- `255 ` | Calculated using second byte of data |
81
82Following arguments are passed to OPUS_ENC_CTL_API:
83
841. OPUS_SET_BITRATE (parameter name: `bitRate`)
852. OPUS_SET_COMPLEXITY (parameter name: `complexity`)
863. OPUS_SET_APPLICATION (parameter name: `application`)
874. OPUS_SET_DTX (parameter name: `setDTX`)
885. OPUS_SET_SIGNAL (parameter name: `signal`)
896. OPUS_SET_VBR (parameter name: `setVBR`)
907. OPUS_SET_VBR_CONSTRAINT (parameter name: `setVBRConstraint`)
918. OPUS_SET_FORCE_CHANNELS (parameter name: `forceChannel`)
929. OPUS_SET_MAX_BANDWIDTH (parameter name: `maxBandwidth`)
9310. OPUS_SET_INBAND_FEC (parameter name: `setInbandFec`)
9411. OPUS_SET_PACKET_LOSS_PERC (parameter name: `pktLoss`)
9512. OPUS_SET_LSB_DEPTH (parameter name: `lsbDepth`)
9613. OPUS_SET_PREDICTION_DISABLED (parameter name: `setPredDisable`)
9714. OPUS_SET_EXPERT_FRAME_DURATION (parameter name: `frameSizeEnum`)
98
99| Parameter| Valid Values| Configured Value|
100|------------- |-------------| ----- |
101| `bitRate` | In range `500 ` to `512000 ` | Calculated using all bits of 3rd, 4th and 5th byte of data |
102| `complexity` |0.`0 ` 1.`1 ` 2.`2 ` 3.`3 ` 4.`4 ` 5.`5 ` 6.`6 ` 7.`7 ` 8.`8 ` 9.`9 ` 10.`10 ` | Calculated using all bits of 6th byte of data |
103| `application` | 0.`OPUS_APPLICATION_VOIP ` 1.`OPUS_APPLICATION_AUDIO ` 2.`OPUS_APPLICATION_RESTRICTED_LOWDELAY ` | Calculated using all bits of 7th byte of data |
104| `setDTX` | 0.`0 ` 1.`1 ` | Calculated using bit 0 of 8th byte of data |
105| `signal` | 0.`OPUS_AUTO ` 1.`OPUS_SIGNAL_VOICE ` 2.`OPUS_SIGNAL_MUSIC ` | Calculated using bit 0 and bit 1 of 9th byte of data |
106| `setVBR` | 0.`0 ` 1.`1 ` | Calculated using bit 0 of 10th byte of data |
107| `setVBRConstraint` | 0.`0 ` 1.`1 ` | Calculated using bit 0 of 11th byte of data |
108| `forceChannel` | 0.`OPUS_AUTO ` 1.`1 ` 2.`2 ` | Calculated using all bits of 12th byte of data |
109| `maxBandwidth` | 0.`OPUS_BANDWIDTH_NARROWBAND ` 1.`OPUS_BANDWIDTH_MEDIUMBAND ` 2.`OPUS_BANDWIDTH_WIDEBAND ` 3.`OPUS_BANDWIDTH_SUPERWIDEBAND ` 4.`OPUS_BANDWIDTH_FULLBAND ` | Calculated using all bits of 13th byte of data |
110| `setInbandFec` | 0.`0 ` 1.`1 ` | Calculated using bit 0 of 14th byte of data |
111| `pktLoss` | 0.`0 ` 1.`1 ` 2.`2 ` 3.`5 `| Calculated using all bits of 15th byte of data |
112| `lsbDepth` | 0.`8 ` 1.`24 ` | Calculated using bit 0 of 16th byte of data |
113| `setPredDisable` | 0.`0 ` 1.`1 ` | Calculated using bit 0 of 17th byte of data |
114| `frameSizeEnum` | 0.`OPUS_FRAMESIZE_2_5_MS ` 1.`OPUS_FRAMESIZE_5_MS ` 2.`OPUS_FRAMESIZE_10_MS ` 3.`OPUS_FRAMESIZE_20_MS ` 4.`OPUS_FRAMESIZE_40_MS ` 5.`OPUS_FRAMESIZE_60_MS ` 6.`OPUS_FRAMESIZE_80_MS ` 7.`OPUS_FRAMESIZE_100_MS ` 8.`OPUS_FRAMESIZE_120_MS ` | Calculated using all bits of 18th byte of data |
115
116
117##### Maximize utilization of input data
118The plugin feeds the entire input data to the codec. For buffer size which is not a multiple of mNumPcmBytesPerInputFrame, we will accumulate the input and keep it. Once the input is filled with expected number of bytes, we will send it to encoder. This ensures that the plugin tolerates any kind of input (empty, huge,
119malformed, etc) and doesnt `exit()` on any input and thereby increasing the chance of identifying vulnerabilities.
120
121## Build
122
123This describes steps to build opus_enc_fuzzer and opus_multistream_enc_fuzzer.
124
125## Android
126
127### Steps to build
128Build the fuzzer
129```
130 $ mm -j$(nproc) opus_enc_fuzzer
131 $ mm -j$(nproc) opus_multistream_enc_fuzzer
132```
133
134### Steps to run
135Create a directory CORPUS_DIR and copy some raw media files to that folder.
136Push this directory to device.
137
138To run on device
139```
140 $ adb sync data
141 $ adb shell /data/fuzz/arm64/opus_enc_fuzzer/opus_enc_fuzzer CORPUS_DIR
142 $ adb shell /data/fuzz/arm64/opus_multistream_enc_fuzzer/opus_multistream_enc_fuzzer CORPUS_DIR
143```
144To run on host
145```
146 $ $ANDROID_HOST_OUT/fuzz/x86_64/opus_enc_fuzzer/opus_enc_fuzzer CORPUS_DIR
147 $ $ANDROID_HOST_OUT/fuzz/x86_64/opus_multistream_enc_fuzzer/opus_multistream_enc_fuzzer CORPUS_DIR
148```
149
150## References:
151 * http://llvm.org/docs/LibFuzzer.html
152 * https://github.com/google/oss-fuzz
153