2024-03-10 Update: Due to Samsung's increasing disdain for folks who like to tinker with custom firmware, I'm getting rid of all my Samsung Android devices. Thus, this project is no longer in development.

samfusdl

samfusdl is an unofficial tool for downloading firmware images from Samsung's FUS (firmware update service).

Features:

Downloads firmware chunks in parallel for faster downloads
Interrupted downloads can be resumed
Supports downloading both home and factory images
Supports both old and new-style firmware decryption (.enc2 and .enc4)
Supports downloading the latest firmware or a specific version
Supports AES-NI for fast firmware decryption on x86_64 (falls back to SIMD for other CPU architectures or if AES-NI is not available)

Encryption keys

Access to FUS requires two encryption keys: the fixed key and the flexible key suffix. These are the same for every user and are hard-coded into the official clients. samfusdl does not and will never include these encryption keys. You must acquire them yourself.

Please do not open any issues or contact the author about how to reverse-engineer any of the official clients. They will be ignored.

Once you have the keys, there are a few different ways to make them available to samfusdl:

Inside the config file:
- Windows: %APPDATA%\samfusdl.conf (eg. C:\Users\<user>\AppData\Roaming\samfusdl.conf)
- Linux (and other unix-like OS's): $XDG_CONFIG_HOME/samfusdl.conf or ~/.config/samfusdl.conf
- macOS: ~/Library/Application Support/samfusdl.conf
Contents:
```
{
    "fus_fixed_key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "fus_flexible_key_suffix": "XXXXXXXXXXXXXXXX"
}
```

As environment variables:

sh/bash/zsh:

export FUS_FIXED_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export FUS_FLEXIBLE_KEY_SUFFIX=XXXXXXXXXXXXXXXX

powershell:

$env:FUS_FIXED_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
$env:FUS_FLEXIBLE_KEY_SUFFIX = 'XXXXXXXXXXXXXXXX'

As command-line arguments:

When running samfusdl, add the --fus-fixed-key XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX and --fus-flexible-key-suffix XXXXXXXXXXXXXXXX arguments.

Usage

To download the latest firmware for a device, run:

samfusdl -m <model> -r <region> -i <IMEI/serial number>

FUS now requires the IMEI or serial number (for devices without a modem) to be specified. It is no longer possible to download arbitrary firmware for any device.

To download a specific firmware version, add the -v/--version argument. The version string is in the form: <PDA>/<CSC>/<Phone>/<Data>. For most devices, the shorthand <PDA>/<CSC> can be used because <Phone> and <Data> have the same value as <PDA>.

To change the output path, use the -o <filename> argument.

Firmware files are downloaded with 4 parallel connections. This can be changed using the -c/--chunks argument. To interrupt a download, simply use Ctrl-C as usual. Rerunning the same command will resume the download.

By default, the "home" firmware type (also known as "binary nature") is downloaded instead of the "factory" image. For newer devices, both firmware types are the same. To specify which type of firmware to download, use the -t/--firmware-type argument.

For more information about other command-line arguments, see --help.

Building from source

To build from source, first make sure that the Rust toolchain is installed. It can be installed from https://rustup.rs/ or the OS's package manager.

Build samfusdl using the following command:

cargo build --release

The resulting executable will be in target/release/samfusdl or target\release\samfusdl.exe.

Debugging

Debug logging can be enabled with the --loglevel debug argument. This will disable the fancy progress bar and print out significantly more information, such as how the parallel download chunks are split. Note that encryption keys are not logged unless the SAMFUSDL_LOG_KEYS environment variable is set to true.

If --loglevel trace is set, each file I/O operation during the download stage is logged. This is generally not useful for anything besides debugging the parallel download mechanism or pwrite/overlapped-I/O.

Instead of setting --loglevel, it is also possible to set the RUST_LOG environment variable, which allows log messages of samfusdl's dependencies to be printed out.

To debug the actual HTTP requests and responses, any HTTPS-compatible MITM software, like mitmproxy, can be used. samfusdl respects both the OS proxy settings and the http_proxy/https_proxy environment variables. Note that TLS certificate validation is enabled by default. The MITM software's CA certificate will either need to be added to the OS's trust store or the --ignore-tls-validation argument can be used.

Caveats

For Windows, only Windows 10 1607 and newer are supported. samfusdl uses atomic file rename/replace, which isn't supported on earlier versions of Windows.

License

samfusdl is licensed under the GPLv3 license. For details, please see LICENSE.

TODO

Stop using FOTA for querying the latest firmware as it does not work for ATT or VZW.

chenxiaolong/samfusdl