git.seregonwar.com

README.md

ShadPKG / README.md

1	# shadPKG
2
3	[![Status](https://imrf.vercel.app/api/badge?label=Status&status=Active&color=10b981)]()
4	[![Platform](https://imrf.vercel.app/api/badge?label=Platform&status=Windows&color=0078d4)]()
5	[![License](https://imrf.vercel.app/api/badge?label=License&status=MIT&color=f59e0b)]()
6	<img src="https://img.shields.io/github/downloads/seregonwar/ShadPKG/total?style=flat-square&color=success" alt="Downloads"/><br/>
7
8
9	shadPKG is a C++ tool designed to derive encryption keys and extract content from PlayStation 4 PKG files.
10
11	---
12
13	## Overview
14
15	shadPKG is an advanced utility for analyzing, decrypting, and extracting PS4 PKG files, including games, updates, patches, DLCs, and homebrew packages.
16
17	It focuses on correctness, performance, and transparency, providing detailed logs and clear insight into the internal structure of PKG archives.
18
19	### Key capabilities:
20
21	* Full PKG structure analysis
22	* Automatic derivation and handling of encryption keys
23	* Decryption of protected data
24	* Complete file and directory extraction
25	* Support for retail, update, DLC, and homebrew PKGs
26	* Multi-threaded extraction with progress reporting
27
28	---
29
30	## ☕ Support Development
31
32	ShadPKG is actively maintained and improved over time.
33	If you find it useful and want to support continued development, you can contribute via Ko-fi.
34
35	[![Support me on Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/seregon)
36
37	---
38
39	## System Requirements
40
41	* OS: Windows 10 / 11 (x64)
42	* Compiler: Visual Studio 2022 (Build Tools or full IDE)
43	* Python: 3.10 or newer (required for `build.py`)
44	* Dependencies: Conan 2.x
45
46	* Used for managing libraries such as Zlib, Crypto++, and others
47
48	---
49
50	## Build Instructions
51
52	### 1. Clone the repository
53
54	```bash
55	git clone https://github.com/seregonwar/ShadPKG.git
56	cd ShadPKG
57	```
58
59	### 2. Install Conan (if missing)
60
61	```bash
62	pip install conan
63	```
64
65	### 3. Install dependencies
66
67	```bash
68	conan install . --build=missing
69	```
70
71	### 4. Build the project
72
73	Run the build script from the project root:
74
75	```bash
76	python build.py
77	```
78
79	The compiled binaries will be located in:
80
81	```
82	build/Release/
83	```
84
85	---
86
87	## Usage
88
89	From Command Prompt or PowerShell:
90
91	```text
92	shadPKG.exe <path_to_pkg> <output_directory>
93	```
94
95	### Example:
96
97	```text
98	shadPKG.exe "C:\GAMES\CUSA12345.pkg" C:\extracted\CUSA12345
99	```
100
101	### Behavior:
102
103	* All files and directories contained in the PKG are extracted to the target folder
104	* Progress is displayed in real time
105	* A detailed execution log is printed to the console and saved to `debug_log.txt`
106	* Unknown or unnamed entries are exported as:
107
108	```
109	entry_0x<ID>.bin
110	```
111
112	---
113
114	## Main Features
115
116	* Multi-threaded extraction for improved performance
117	* Automatic key handling and decryption
118	* Robust support for different PKG types
119	* Persistent logging for debugging and analysis
120	* Safe path handling and error resilience
121
122	---
123
124	## Notes & Limitations
125
126	* Some PKG types (especially patches or updates) may intentionally omit certain files
127	* If extraction issues occur, consult the generated `debug_log.txt` before reporting problems
128
129	---
130
131	## Technical Documentation
132
133	A detailed breakdown of the PKG and PFS formats, including cryptographic flow, data structures, and decryption logic, is available here:
134
135	📄 [Technical Analysis of the Decryption Process for PlayStation 4 PKG and PFS File Formats](docs/HOWWORKS.md)
136
137	---
138
139	## Credits & License
140
141	* Based on reverse engineering and community documentation.
142	* Licensed under MIT.
143

Seregon/ShadPKG