From 1ac38b982de59ab383d1bc4bb13f171066222195 Mon Sep 17 00:00:00 2001 From: MatrixEditor <58256046+MatrixEditor@users.noreply.github.com> Date: Fri, 15 Dec 2023 10:05:12 +0100 Subject: [PATCH] Sphinx Documentation + Added License to source code files --- README.md | 7 ++- docs/Makefile | 20 +++++++++ docs/make.bat | 35 +++++++++++++++ docs/requirements.txt | 3 ++ docs/source/API/FUS.rst | 30 +++++++++++++ docs/source/API/crypto.rst | 25 +++++++++++ docs/source/API/firmware.rst | 20 +++++++++ docs/source/API/index.rst | 19 +++++++++ docs/{ => source}/cmd_list.png | Bin docs/source/conf.py | 75 +++++++++++++++++++++++++++++++++ docs/source/examples.rst | 65 ++++++++++++++++++++++++++++ docs/source/index.rst | 35 +++++++++++++++ samloader3/__init__.py | 18 +++++++- samloader3/__main__.py | 15 +++++++ samloader3/_util.py | 15 +++++++ samloader3/cli.py | 15 +++++++ samloader3/crypto.py | 15 +++++++ samloader3/firmware.py | 15 +++++++ samloader3/fus.py | 18 +++++++- 19 files changed, 440 insertions(+), 5 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt create mode 100644 docs/source/API/FUS.rst create mode 100644 docs/source/API/crypto.rst create mode 100644 docs/source/API/firmware.rst create mode 100644 docs/source/API/index.rst rename docs/{ => source}/cmd_list.png (100%) create mode 100644 docs/source/conf.py create mode 100644 docs/source/examples.rst create mode 100644 docs/source/index.rst diff --git a/README.md b/README.md index e1a3dd2..ed8380c 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ versions:

-![cmd_list](/docs/cmd_list.png) +![cmd_list](/docs/source/cmd_list.png)

@@ -66,7 +66,7 @@ position. You can disable that behaviour using `--no-cache`. With a special vers To decrypt files directly after downloading them, use `--decrypt`. -## Decrypt Firmware +### Decrypt Firmware The decryption command (`decrypt`) is designd to operate on one file only. You just have to provide a version number and the file path: @@ -79,3 +79,6 @@ to provide a version number and the file path: > If you only want to generate the decryption key, use `--key-only`. Note that the actual > key is the MD5 value +## License + +Distributed under the GNU General Public License (V3). See LICENSE for more information. \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..dc1312a --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..17a9118 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +furo +sphinx_inline_tabs \ No newline at end of file diff --git a/docs/source/API/FUS.rst b/docs/source/API/FUS.rst new file mode 100644 index 0000000..d702011 --- /dev/null +++ b/docs/source/API/FUS.rst @@ -0,0 +1,30 @@ +.. _api_fus: + +================================ +FUS (Firmware Update Server) API +================================ + +.. note:: + Additional documentation on the whole FUS API is provided + here: `samsung-loki.github.io/samsung-docs/docs/FUS/ `_. + +.. autoclass:: samloader3.fus.AuthenticationError + :members: + +.. autoclass:: samloader3.fus.FUSAuthorization + :members: + +.. autoclass:: samloader3.fus.FUSClient + :members: + +.. autofunction:: samloader3.fus.FUSHdr + +.. autofunction:: samloader3.fus.FUSBody + +.. autofunction:: samloader3.fus.FUSMsg + +.. autofunction:: samloader3.fus.firmware_spec_url + +.. autofunction:: samloader3.fus.v4_key + +.. autofunction:: samloader3.fus.v2_key diff --git a/docs/source/API/crypto.rst b/docs/source/API/crypto.rst new file mode 100644 index 0000000..9138497 --- /dev/null +++ b/docs/source/API/crypto.rst @@ -0,0 +1,25 @@ +.. _api_crypto: + +===================== +Crypto Implementation +===================== + +.. autofunction:: samloader3.crypto.aes_decrypt + +.. autofunction:: samloader3.crypto.aes_encrypt + +.. autofunction:: samloader3.crypto.get_key + +.. autofunction:: samloader3.crypto.get_nonce + +.. autofunction:: samloader3.crypto.get_logic_check + +.. autofunction:: samloader3.crypto.get_signature + +.. autofunction:: samloader3.crypto.get_file_decryptor + +.. autofunction:: samloader3.crypto.unpad + +.. autofunction:: samloader3.crypto.pad + +.. autofunction:: samloader3.crypto.file_decrypt diff --git a/docs/source/API/firmware.rst b/docs/source/API/firmware.rst new file mode 100644 index 0000000..1c7ed57 --- /dev/null +++ b/docs/source/API/firmware.rst @@ -0,0 +1,20 @@ +.. _api_firmware: + +============== +Firmware Model +============== + +.. autoclass:: samloader3.firmware.FirmwareInfo + :members: + +.. autoclass:: samloader3.firmware.FirmwareSpec + :members: + +.. autoclass:: samloader3.firmware.VersionInfo + :members: + +.. autoclass:: samloader3.firmware.BinaryNature + :members: + +.. autoclass:: samloader3.firmware.EncryptionType + :members: \ No newline at end of file diff --git a/docs/source/API/index.rst b/docs/source/API/index.rst new file mode 100644 index 0000000..f8dd745 --- /dev/null +++ b/docs/source/API/index.rst @@ -0,0 +1,19 @@ +.. _api_index: + +================= +API Documentation +================= + +The following sections describe how the internal classes and functions of this small +library are structured. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + firmware + crypto + FUS + + diff --git a/docs/cmd_list.png b/docs/source/cmd_list.png similarity index 100% rename from docs/cmd_list.png rename to docs/source/cmd_list.png diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..bdcd472 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,75 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information +import sys +import os + +sys.path.insert(0, os.path.abspath("../..")) + +import samloader3 + + +project = "samloader3" +author = samloader3.__author__ +copyright = f"2023, {author}" + + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +# The short X.Y version. +release = samloader3.__version__ +# The full version, including alpha/beta/rc tags. +version = samloader3.__version__ + + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.doctest", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx_inline_tabs", +] + +templates_path = ["_templates"] +exclude_patterns = [] + + +# The master toctree document. +master_doc = "index" + +# The suffix of source filenames. +source_suffix = ".rst" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +html_theme = "furo" +html_static_path = ["_static"] +html_theme_options = { + # Toc options +} diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000..d758670 --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,65 @@ +.. _examples: + +======== +Examples +======== + + +List firmware information +------------------------- + +Utilizing the ``list`` command you can list all available firmwares for a specific model within +the selected region. + +.. note:: + Make sure to always set the device's model name and region code, otherwise you won't get any + valid results. For simplicity, we don't write the model and region code explicitly. + +Using this command without any arguments will result in a table view that displays all available +versions: + +.. image:: cmd_list.png + :align: center + :name: Example output + + +.. note:: + If you just want to list the latest firmware use `-l` and if you want to print out the version + strings only, use `-q`. Using `-v VERSION` you can also view details on one specific version. + + +Download Firmware +----------------- + +With this updated version of `samloader`, you can download multiple firmware files at one (though, most likely not a real use case) and accelerate to the maximum download speed. Using one version +string from the output before, simply run the following command: + +.. code-block:: console + + (sl3)> download -o "/path/to/destination/" "$version1" "$version2" ... + + +As these files can be huge, once canceled, the donwload will resume at the current download +position. You can disable that behaviour using `--no-cache`. With a special version identifier (`*`) you can download all firmware binaries at once. + +.. warning:: + Because of some issues with python.rich, parallel download is disabled by default. It can be + enabled using `--parallel`. + +To decrypt files directly after downloading them, use `--decrypt`. + + +Decrypt Firmware +---------------- + +The decryption command (`decrypt`) is designd to operate on one file only. You just have +to provide a version number and the file path: + +.. code-block:: console + + (sl3)> decrypt -v "$version" "/path/to/firmware.zip.enc4" + + +.. note:: + If you only want to generate the decryption key, use `--key-only`. Note that the actual + key is the MD5 value \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..42e16b5 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,35 @@ +Welcome to samloader3's documentation! +====================================== + +Cross plattform Firmware downloader and decryptor for Samsung devices with maximum download speed. +A list of API examples are given in the documentation available at `Github-Pages `_. + +.. note:: + This project was formerly hosted at ``nlscc/samloader``, and has moved from ``samloader/samloader`` to an refactored + and updated version with enhanced CLI support and an API documentation. + + +Installation +------------ + +You can easily install ``samloader3`` by using the pip package manager. + +.. code-block:: console + + pip install git+https://github.com/MatrixEditor/samloader3.git + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + examples + API/index + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/samloader3/__init__.py b/samloader3/__init__.py index 8513dde..a358486 100644 --- a/samloader3/__init__.py +++ b/samloader3/__init__.py @@ -1,4 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + __version__ = "1.0.0" -__authors__ = ("MatrixEditor", ) +__authors__ = ("MatrixEditor",) __author__ = ", ".join(__authors__) - diff --git a/samloader3/__main__.py b/samloader3/__main__.py index a8ef4f9..8c1269f 100644 --- a/samloader3/__main__.py +++ b/samloader3/__main__.py @@ -1,3 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + from samloader3.cli import run_with_args if __name__ == "__main__": diff --git a/samloader3/_util.py b/samloader3/_util.py index 8860f98..739ded7 100644 --- a/samloader3/_util.py +++ b/samloader3/_util.py @@ -1,3 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + from xml.etree import ElementTree from typing import Union diff --git a/samloader3/cli.py b/samloader3/cli.py index 63afcd7..2673517 100644 --- a/samloader3/cli.py +++ b/samloader3/cli.py @@ -1,3 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + from __future__ import annotations import os diff --git a/samloader3/crypto.py b/samloader3/crypto.py index cbe3cd1..1aacf69 100644 --- a/samloader3/crypto.py +++ b/samloader3/crypto.py @@ -1,3 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + from __future__ import annotations import os diff --git a/samloader3/firmware.py b/samloader3/firmware.py index 1a706c1..bbb1df3 100644 --- a/samloader3/firmware.py +++ b/samloader3/firmware.py @@ -1,3 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + from __future__ import annotations import dataclasses as dc diff --git a/samloader3/fus.py b/samloader3/fus.py index 545613e..28275ed 100644 --- a/samloader3/fus.py +++ b/samloader3/fus.py @@ -1,3 +1,18 @@ +# Copyright (C) 2023 MatrixEditor +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see . + from __future__ import annotations import typing as t @@ -13,6 +28,7 @@ from ._util import xml_find +# General constants FUS_CLOUD_DOMAIN = "cloud-neofussvr.samsungmobile.com" FUS_DOMAIN = "neofussvr.sslcs.cdngc.net" @@ -304,7 +320,7 @@ def fw_info( { "ACCESS_MODE": 2, "BINARY_NATURE": str(nature.value), - "CLIENT_PRODUCT": client_product or "Smart Switch", + "CLIENT_PRODUCT": client_product or "Bogus", "DEVICE_FW_VERSION": version, "DEVICE_LOCAL_CODE": local_code, "DEVICE_MODEL_NAME": model_name,