Skip to content

Commit abc5282

Browse files
racerxdlracerxdl
committed
Added WIP JPAK2 Specification
1 parent 8f63c5e commit abc5282

2 files changed

Lines changed: 132 additions & 0 deletions

File tree

‎doc/JPAK2/Extended Mode/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
TODO

‎doc/JPAK2/README.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
_ ____ _ _ __ ____ ___
2+
| | _ \ / \ | |/ / __ _|___ \ / _ \
3+
_ | | |_) / _ \ | ' / \ \ / / __) || | | |
4+
| |_| | __/ ___ \| . \ \ V / / __/ | |_| |
5+
\___/|_| /_/ \_\_|\_\ \_/ |_____(_)___/
6+
7+
Multiuse Javascript Package
8+
By: Lucas Teske
9+
https://github.com/racerxdl/jpak
10+
11+
#JPAK v2.0 Specification File
12+
13+
##### 1.0 Filesystem Specification
14+
The JPAK2.0 uses about the same structure than JPAK1.0 but now it supports table encryption and specify a nested encryption. The Filesystem Table uses is a JSON with the root node being a directory entry. The directory is as follow:
15+
16+
direntry = {
17+
"name" : DIRNAME, // Ndame of this folder
18+
"path" : DIRPATH, // Path for this folder
19+
"numfiles" : DIRNUMFILES, // Number of files in root of this folder
20+
"directories" : DIRSUBDIRECTORIES, // It's an array [] with directory objects like direntry
21+
"files" : DIRFILES // It's an array [] with file objects like fileentry
22+
"aeskey" : AESKEY // Folder key if != false
23+
};
24+
25+
And for the file entries:
26+
27+
fileentry = {
28+
"name" : FILENAME, // File Name
29+
"path" : FILEPATH, // File Path
30+
"offset" : FILEOFFSET, // Absolute offset in the jpak file
31+
"size" : FILESIZE // The file size
32+
"aeskey" : AESKEY // File key if != false
33+
"zlib" : FALSE/TRUE // If file is compressed
34+
"md5" : MD5SUM // Uncompresssed/unencrypted file MD5SUM
35+
}
36+
37+
The filesystem table can be either encrypted, compressed, both, or nothing. This is specified by **JPAK FLAGS** (see 2.X)
38+
Example of JPAK Filesystem Table:
39+
40+
{
41+
'name': 'packtest',
42+
'path': '/',
43+
'numfiles': 3,
44+
'size': 0,
45+
'files': {
46+
'whatisthis': {
47+
'path': '/whatisthis',
48+
'offset': 13,
49+
'name': 'whatisthis',
50+
'size': 55
51+
},
52+
'test.html': {
53+
'path': '/test.html',
54+
'offset': 81,
55+
'name': 'test.html',
56+
'size': 49
57+
},
58+
},
59+
'directories': {
60+
'3': {
61+
'path': '/3',
62+
'directories': { },
63+
'name': '3',
64+
'numfiles': 1
65+
'files': {
66+
't': {
67+
'path': '/3/t',
68+
'offset': 9104,
69+
'name': 't',
70+
'size': 0
71+
}
72+
},
73+
},
74+
}
75+
}
76+
##### 2.0 JPAK File
77+
78+
The JPAK has following structure:
79+
80+
| START | END | Description |
81+
| --------- | --------- | --------------------------------- |
82+
| 0x0 | 0x5 | JPAK2 Magic Number |
83+
| 0x5 | 0xC | Padding (0x00) |
84+
| 0xC | 0xY | Start of Files Data |
85+
| 0x**Y** | 0x**X** | JSON File Table |
86+
| 0x**X** | 0x**W** | `uint32_t` Producer ID (Look 2.1) |
87+
| 0x**X** | 0x**W** | `uint32_t` JPAK Flags (Look 2.1) |
88+
| 0x**W** | 0x**Z** | `uint32_t` User Flags (Look 2.1) |
89+
| 0x**Z** | `END` | `uint32_t` JSON FileTable Offset |
90+
91+
##### 2.1 JPAK / USER FLAGS and Producer ID
92+
93+
The JPAK Flags was implemented to support file table encryption, scrambling and compressing. We have two Flag types `JPAK` and `USER`. The `USER FLAGS` can be anything the user wants. This could be set for identifying a proprietary encryption for example. The `JPAK FLAGS` bitmask is organized in this way:
94+
95+
| D7 | D6 | D5 | D4 | D3 | D2 | D1 | D0 |
96+
| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
97+
| AES | ZLIB | XOR | F | Z | Z | Z | Z |
98+
99+
* `AES` - The Filetable is AES Encrypted
100+
* `ZLIB` - The Filetable is ZLib Compressed
101+
* `XOR` - The Filetable uses an **XORpad**
102+
* `F` - The filetable encryption key/xorpad is used on files
103+
* `Z` - Reserved for future use
104+
105+
The `Producer ID` is a (ideally) **unique** ID from who created the JPAK file. It's meant to be used together with `USER FLAGS`.
106+
107+
108+
##### 3.0 Encryption / Compressing
109+
110+
The AES Encryption used on JPAK2.0 is **AES-256-CTR**. The filetable can be both encrypted and compressed. For this case we will **first** compress then encrypt the data. We can also use xorpads for obfuscation of data. For `AES`, `ZLIB`, `XOR` flags enable the order of processing will follow:
111+
112+
DATA -> ZLIB -> AES -> XORPAD
113+
114+
We refer the filetable key as **masterkey**
115+
116+
For the file encryption we can have these cases:
117+
118+
* File Key, Directory Key, `F FLAG` unset : In this mode, the file is unencrypted
119+
* `F FLAG` set, File Key, Directory Key : In this mode, the file is encrypted using **master key**
120+
* Directory Key and `F FLAG` set, File Key unset : In this mode we use DIRKEY + MASTER_KEY in encryption
121+
* File Key, Directory Key, `F FLAG` set : In this mode we use FILEKEY + DIRKEY + MASTERKEY in encryption
122+
123+
#### 4.0 Data File and Filetable File in Extended Mode
124+
125+
In extended mode the owner of a jpak file is able to share its datafile with other user just by creating another filetable with only the keys owner want to share. Then on the cloud backend they can have a common datafile.
126+
So in `Extended Environment` we have following pieces:
127+
* `OWNER` - The Datafile Owner/Creator. It has all keys for all files
128+
* `JPAK DATA STORAGE (JDS)` - The data only file storage
129+
* `JPAK META STORAGE (JMS)` - The meta storage ( filetable )
130+
131+
For more specification of Extended Mode, see Extended Mode README.md

0 commit comments

Comments
 (0)