ysfchn / SamFetch

A web API to download Samsung firmware easily without headers, authorization or anything that you don't want.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

SamFetch

A simple Web API to download Samsung Stock ROMs from Samsung's own Kies servers, without any restriction, rate-limit, authorization or passwords. Made in Python and built with Sanic.

Caution

Recent changes in Samsung backend causes all firmware downloads require a valid IMEI number, which must match with the model that is requested. Check this link for more information. SamFetch currently didn't adapted this change yet, which makes SamFetch unusable right now.

Warning

Due to a change in Samsung servers, you can only download the latest firmware even if you asked for an older firmware. See discussion here.

Deploy & Use

SamFetch doesn't have any rate-limits to keep it free (as in freedom) as much as I can. However, since this can allow malicious requests (such as spams) I recommend hosting your own instance, as you will have more control over it and you will have own private instance.

SamFetch is currently tested and ready to be hosted on Docker, Heroku (one-click deploy here) and fly.io. As it is just Python, it should run in any Python environment by default.

You can also run in your computer locally if you don't need to host publicly.

Features

  • It doesn't include any analytics, store cookies or have any rate-limits as it directly calls the Samsung servers without involving any 3rd party.

  • As Samsung server requests authorization before serving firmwares, it is done automatically by SamFetch itself, so you don't need any authorization or add any headers on your end.

  • The firmware file will directly stream to you, while decrypting the firmware on-the-fly, so no background-jobs, no queue, and no storing the firmware in disk.

  • SamFetch supports partial downloads with "Range" header which means it supports pausing and resuming the download. Note that partial downloads are not allowed when decrypting has enabled, due to some problems, see here.

  • You can configure your SamFetch instance with environment variables and edit allowed origin for CORS headers and chunk size.

Endpoints

Endpoint Description
/:region/:model/list List the available firmware versions of a specified model and region.
The first item in the list represents the latest firmware available.
/:region/:model/:firmware Returns the firmware details, such as Android version, changelog URL,
date and filename which is required for downloading firmware.
/file/:path/:filename Starts downloading the firmware with given path and filename
which can be obtained in firmware details endpoint.
For decrypting, add the given key as decrypt query parameter.
Also optionally, filename query parameter overwrites the
filename of the downloaded file.

Redirects

Endpoint Description
/:region/:model/latest Gets the latest firmware version for the device and
redirects to /:region/:model/:firmware.
/:region/:model/latest/download Gets the latest firmware version for the device and
redirects to /:region/:model/:firmware/download.
/:region/:model/:firmware/download Gets the firmware details for the device and
redirects to /file/:path/:filename with decrypt parameter.

Envrionment Variables

Variable Description
SAMFETCH_HIDE_TEXT Hides the text shown when visiting the root path.
SAMFETCH_ALLOW_ORIGIN Sets the "Access-Control-Allow-Origin" header value. Settings this to "*" (wildcard) allows all domains to access this SamFetch instance. Default is set to "*".
SAMFETCH_CHUNK_SIZE Specifies how many bytes must read in a single iteration when downloading the firmware. Default is set to 1485760 (1 megabytes), bigger chunk size means faster but uses more resources.

On-the-fly Decrypting

Samsung stores firmwares as encrypted. This means, in normally you are expected to download the encrypted firmware, and decrpyt it afterwards locally. However with SamFetch, the firmware file will directly stream to you, while decrypting the firmware on-the-fly, so no background-jobs, no queue, and no storing the firmware in disk.

This behavior is opt-in, so if you want SamFetch to decrypt the firmware on-the-fly, you need to insert the decryption key that you can also get it from SamFetch.

# Decrypt key can be found in firmware details.
$ curl http://127.0.0.1:8000/firmware/TUR/SM-N920C/latest -L | jq .decrypt_key
"22992da4a7f887d1c4f5bdc66d116367"

# Join path and filename. Add decryption key as "decrypt" query parameter
# The output is the URL path of the download.
$ curl http://127.0.0.1:8000/firmware/TUR/SM-N920C/latest -L | jq '.path + .filename + "?decrypt=" + .decrypt_key'
"/neofus/9/SM-N920C_1_20220819152351_1eub6wdeqb_fac.zip.enc4?decrypt=22992da4a7f887d1c4f5bdc66d116367"

# SamFetch also returns the full URLs in the response.
$ curl http://127.0.0.1:8000/firmware/TUR/SM-N920C/latest -L | jq '.download_path_decrypt'
"http://127.0.0.1:8000/file/neofus/9/SM-N920C_1_20220819152351_1eub6wdeqb_fac.zip.enc4?decrypt=22992da4a7f887d1c4f5bdc66d116367"

If you prefer to decrypt firmwares manually, sadly you can't do it with SamFetch (as it is an web application not a CLI), but you can use Samloader which has a decrypt command.

Partial downloads

When an encrypted file has decrypted, the file size becomes slightly different from the encrypted file. The thing is, SamFetch reports the firmware size, so you can see a progress bar and ETA in your browser. However, when the decrypted size is not equal with actual size, this will result in a failed download in 99%. To fix failed downloads, SamFetch won't report the firmware size when decrypting has enabled.

Running

Install dependencies with pip install -r requirements.txt and run with:

sanic main.app

Visit the URL you see in the console to get started with SamFetch.

$ curl http://127.0.0.1:8000/firmware/TUR/SM-N920C/latest -L
{
    "display_name": "Galaxy Note5",
    "size": 2530817088,
    "size_readable": "2.36 GB",
    "filename": "SM-N920C_1_20190117104840_n2lqmc6w6w_fac.zip.enc4",
    "path": "/neofus/9/",
    "version": "Nougat (Android 7.0)",
    "encrypt_version": 4,
    "last_modified": 20190117144207,
    "decrypt_key": "0727c304eea8a4d14835a4e6b02c0ce3",
...

$ curl http://127.0.0.1:8000/file/neofus/9/SM-N920C_1_20220819152351_1eub6wdeqb_fac.zip.enc4?decrypt=22992da4a7f887d1c4f5bdc66d116367 -O .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 27.0M    0 27.0M    0     0  1282k      0 --:--:--  0:00:21 --:--:-- 1499k

$ curl http://127.0.0.1:8000/file/neofus/9/SM-N920C_1_20220819152351_1eub6wdeqb_fac.zip.enc4 -O .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0 2413M    0 17.1M    0     0  2604k      0  0:15:48  0:00:06  0:15:42 3651k

Resources

If you want to do more with Samsung firmwares, or SamFetch is not enough for you, or just want to learn more stuff, you can check resources.

Credits

This is a Web API variant of Samloader project. I reimplemented the Samloader's functions as Web API routes and simplified the code for end-user to eliminate the authorization request, so SamFetch wouldn't be possible without Samloader.

License

This project is licensed with AGPLv3.

About

A web API to download Samsung firmware easily without headers, authorization or anything that you don't want.

License:GNU Affero General Public License v3.0


Languages

Language:Python 99.3%Language:Dockerfile 0.5%Language:Procfile 0.2%