├── README.md
├── chunk_ordering_rules
└── index.md
├── chunk_specifications
└── index.md
├── cipher_algorithms
└── index.md
├── cipher_modes
└── index.md
├── compression_algorithms
└── index.md
├── data_representation
└── index.md
├── file_structure
└── index.md
├── glossary
└── index.md
├── index.md
├── introduction
└── index.md
├── key_derivation_algorithms
└── index.md
├── miscellaneous_topics
└── index.md
├── recommendations_for_decoders
└── index.md
├── recommendations_for_encoders
└── index.md
└── references
└── index.md
/README.md:
--------------------------------------------------------------------------------
1 | # PNA (Portable Network Archive) Specification
2 |
3 | [](https://uithub.com/Portable-Network-Archive/Portable-Network-Archive-Specification?accept=text%2Fhtml&maxTokens=50000&ext=md)
4 |
5 | PNA (Portable Network Archive) is a highly scalable archive format that can be compressed, encrypted, and split.
6 | Also, its data structure is based on the PNG data structure.
7 |
8 | Specification is hosted on GitHub Pages.
9 |
10 | See [Specification](https://portable-network-archive.github.io/Portable-Network-Archive-Specification/)
11 |
--------------------------------------------------------------------------------
/chunk_ordering_rules/index.md:
--------------------------------------------------------------------------------
1 | ## 9. Chunk Ordering Rules
2 |
3 | To allow new chunk types to be added to PNA, it is necessary to establish rules about the ordering requirements for all chunk types. Otherwise, a PNA editing program cannot know what to do when it encounters an unknown chunk.
4 |
5 | We define a "PNA editor" as a program that modifies a PNA file and wishes to preserve as much as possible of the ancillary information in the file. Two examples of PNA editors are a program that adds or modifies text chunks, and a program that adds or modifies an entry to a PNA file. (Note: we strongly encourage programs handling PNA files to preserve ancillary information whenever possible.)
6 |
7 | As an example of possible problems, consider a hypothetical new ancillary chunk type that is safe-to-copy and is required to appear after PHSF if PHSF is present. If our program to add a suggested PHSF does not recognize this new chunk, it may insert PHSF in the wrong place, namely after the new chunk. We could prevent such problems by requiring PNA editors to discard all unknown chunks, but that is a very unattractive solution. Instead, PNA requires ancillary chunks not to have ordering restrictions like this.
8 |
9 | To prevent this type of problem while allowing for future extension, we put some constraints on both the behavior of PNA editors and the allowed ordering requirements for chunks.
10 |
11 | ### 9.1. Behavior of PNA editors
12 |
13 | The rules for PNA editors are:
14 |
15 | - When copying an unknown unsafe-to-copy ancillary chunk, a PNA editor must not move the chunk relative to any critical chunk. It can relocate the chunk freely relative to other ancillary chunks that occur between the same pair of critical chunks. (This is well defined since the editor must not add, delete, modify, or reorder critical chunks if it is preserving unknown unsafe-to-copy chunks.)
16 | - When copying an unknown safe-to-copy ancillary chunk, a PNA editor must not move the chunk from before FDAT to after FDAT or vice versa. (This is well defined because FDAT is always present.) This is the same goes for SDAT. Any other reordering is permitted.
17 | - When copying a known ancillary chunk type, an editor need only honor the specific chunk ordering rules that exist for that chunk type. However, it can always choose to apply the above general rules instead.
18 | - PNA editors must give up on encountering an unknown critical chunk type, because there is no way to be certain that a valid file will result from modifying a file containing such a chunk. (Note that simply discarding the chunk is not good enough, because it might have unknown implications for the interpretation of other chunks.)
19 | - These rules are expressed in terms of copying chunks from an input file to an output file, but they apply in the obvious way if a PNA file is modified in place.
20 |
21 | See also [Chunk naming conventions](../file_structure/index.md#36-chunk-naming-conventions).
22 |
23 | ### 9.2. Ordering of ancillary chunks
24 |
25 | The ordering rules for an ancillary chunk type cannot be any stricter than this:
26 |
27 | - Unsafe-to-copy chunks can have ordering requirements relative to critical chunks.
28 | - Safe-to-copy chunks can have ordering requirements relative to FDAT or SDAT.
29 |
30 | The actual ordering rules for any particular ancillary chunk type may be weaker. See for example the ordering rules for the standard ancillary chunk types ([Summary of standard chunks](../chunk_specifications/index.md#43-summary-of-standard-chunks)).
31 |
32 | **Decoders must not assume more about the positioning of any ancillary chunk than is specified by the chunk ordering rules.** In particular, it is never valid to assume that a specific ancillary chunk type occurs with any particular positioning relative to other ancillary chunks. (For example, it is unsafe to assume that your private ancillary chunk occurs immediately before AEND, FEND or SEND. Even if your application always writes it there, a PNA editor might have inserted some other ancillary chunk after it. But you can safely assume that your chunk will remain somewhere between AHED and AEND or FDAT and FEND or SDAT and SEND.)
33 |
34 | ### 9.3. Ordering of critical chunks
35 |
36 | Critical chunks can have arbitrary ordering requirements, because PNA editors are required to give up if they encounter unknown critical chunks. For example, AHED has the special ordering rule that it must always appear first. A PNA editor, or indeed any PNA-writing program, must know and follow the ordering rules for any critical chunk type that it can emit.
37 |
--------------------------------------------------------------------------------
/chunk_specifications/index.md:
--------------------------------------------------------------------------------
1 | ## 4. Chunk Specifications
2 |
3 | ### 4.1. Critical chunks
4 |
5 | #### 4.1.1. AHED Archive header
6 |
7 | The AHED chunk must appear FIRST. It contains:
8 |
9 | | Significance | Size | Description |
10 | |:-------------------------|:------:|:---------------------|
11 | | Major version | 1-byte | Major version of PNA |
12 | | Minor version | 1-byte | Minor version of PNA |
13 | | General purpose bit flag | 2-byte | Bit flags |
14 | | Archive number | 4-byte | Archive number |
15 |
16 | ##### Major version
17 |
18 | Currently, only 0 is defined.
19 | It may be changed if there is a change in the structure of each chunk that makes up PNA.
20 |
21 | ##### Minor version
22 |
23 | Currently, only 0 is defined.
24 | It may be changed when there is a change in the type of chunks that make up PNA.
25 |
26 | ##### General purpose bit flag
27 |
28 | __Bit0__ ~ __Bit15__ currently does not used. reserve for the future.
29 |
30 | ##### Archive number
31 |
32 | Contains the number of the archive when the archive is split.
33 | Archive number is start with 0.
34 |
35 | ### 4.1.2. AEND Archive tailer
36 |
37 | This chunk must appear last.
38 | This signals the end of PNA data stream.
39 | The chunk data area is empty.
40 | Decoders should not load more than this chunk.
41 |
42 | ### 4.1.3. ANXT Archive continues marker
43 |
44 | Indicates that the archive is split and the following file exists.
45 | The Archive number field of the `AHED` chunk of the next file will be the value of the Archive number field of the `AHED` chunk of the current file incremented by 1.
46 | The chunk data area is empty.
47 |
48 | ### 4.1.4. FHED File header
49 |
50 | Basic information about each entry is stored.
51 |
52 | | Significance | Size | Description |
53 | |:-------------------|:------:|:-------------------|
54 | | Major version | 1-byte | Major version |
55 | | Minor version | 1-byte | Minor version |
56 | | Entry kind | 1-byte | Entry kind |
57 | | Compression method | 1-byte | Compression method |
58 | | Encryption method | 1-byte | Encryption method |
59 | | Cipher mode | 1-byte | Cipher mode |
60 | | Path | n-byte | File path |
61 |
62 | ##### Entry kind
63 |
64 | The entry kind is recorded.
65 | 0 is regular file
66 | 1 is directory
67 | 2 is symbolic link
68 | 3 is hard link
69 | 4 is a file that has previously appeared in the archive
70 |
71 | ##### Compression method
72 |
73 | The compression method is recorded.
74 | 0 is not compression
75 | 1 is deflate
76 | 2 is zstandard
77 | 4 is lzma
78 |
79 | ##### Encryption method
80 |
81 | The encryption method is recorded.
82 | 0 is not encryption
83 | 1 is AES (Rijndael)
84 | 2 is Camellia
85 |
86 | When this field value is 0, `PHSF` chunk is not required.
87 |
88 | ##### Cipher mode
89 |
90 | Cipher mode of encryption.
91 | 0 is cbc mode
92 | 1 is ctr mode
93 |
94 | Not interested in the value of this field, if Encryption method filed value is 0.
95 |
96 | ##### File path
97 |
98 | The path of entry is encoded by UTF-8.
99 | The / is used as a path separator.
100 | Paths should not contain / at the leading or trailing.
101 | Decoders should ignore them even if they contain a leading or trailing /.
102 |
103 | #### FHED field values (PNA method code)
104 |
105 | The `Compression method`, `Encryption method`, and `Cipher mode` fields in the FHED chunk must be set to the following PNA method codes (integer values):
106 |
107 | | Field | Value | Algorithm/Mode | Note |
108 | |:--------------------|------:|:----------------------|:---------------------------|
109 | | Compression method | 0 | No compression | |
110 | | | 1 | Deflate | zlib compatible |
111 | | | 2 | Zstandard | |
112 | | | 4 | LZMA | xz |
113 | | Encryption method | 0 | No encryption | |
114 | | | 1 | AES (Rijndael) | 256-bit key |
115 | | | 2 | Camellia | 256-bit key |
116 | | Cipher mode | 0 | CBC | Cipher Block Chaining |
117 | | | 1 | CTR | Counter Mode |
118 |
119 | **Note:**
120 | - Do not use algorithm-internal method codes (such as zlib's method/flags code) in these fields. Only the PNA method code (integer value) must be stored in the FHED chunk fields.
121 | - For extensions or private algorithms, use values 64 or greater as recommended in the encoder guidelines.
122 |
123 | #### 4.1.5. PHSF Password hash
124 |
125 | The information about the key derivation function when encrypting a file.
126 | This chunk appeared after `FHED` chunk and before `FDAT` chunk.
127 | If the value of the Encryption method field of `FHED` chunk is not 0, this chunk is required.
128 |
129 | | size | description |
130 | |:-------:|:------------------|
131 | | n-byte | PHC string format |
132 |
133 | About [PHC string format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md)
134 |
135 | ### 4.1.6. FDAT File data
136 |
137 | The actual data of the file is recorded.
138 | Multiple of these chunks are permitted for a single entry.
139 |
140 | ### 4.1.7. FEND File tailer
141 |
142 | This signals the end of the entry data stream.
143 | The chunk data area is empty.
144 |
145 | ### 4.1.8. SHED Solid mode header
146 |
147 | Basic information of Solid mode archive is stored.
148 |
149 | | significance | size | description |
150 | |:-------------------|:-------:|:-------------------|
151 | | Major version | 1-byte | Major version |
152 | | Minor version | 1-byte | Minor version |
153 | | Compression method | 1-byte | Compression method |
154 | | Encryption method | 1-byte | Encryption method |
155 | | Cipher mode | 1-byte | Cipher mode |
156 |
157 |
158 | ### 4.1.9. SDAT Solid mode data
159 |
160 | Solid mode archive data.
161 | Contains chunks representing entries.
162 |
163 | #### 4.1.9.1 Structure of Entries in SDAT
164 |
165 | In solid mode archives, the `SDAT` chunk contains a continuous stream of data representing multiple entries.
166 | Unlike per-entry mode where each entry is composed of discrete `FHED` through `FEND` chunks within the archive, the `SDAT` chunk serializes these chunks together within its own data stream.
167 |
168 | The following structural rules apply to the contents of an `SDAT` chunk:
169 |
170 | - The `SDAT` chunk MUST contain a sequence of standard entry structures, each beginning with a `FHED` chunk and ending with a corresponding `FEND` chunk.
171 | - All chunks appearing within an `SDAT` chunk must conform to the same structure, layout, and constraints as defined for individual entries in per-entry mode.
172 | - Ancillary chunks (e.g., `cTIM`, `fPRM`, `xATR`) may appear between `FHED` and `FEND`, following the same rules as in regular entry mode.
173 | - Encryption and compression, if applied to the solid stream, are performed **after** the entire SDAT datastream has been composed.
174 |
175 | Each entry in solid mode is not stored as an independent top-level chunk sequence in the file but is instead **embedded** within the data field of the `SDAT` chunk.
176 | Decoders must parse the contents of `SDAT` as a logical concatenation of standard entry structures.
177 |
178 | The use of solid mode is intended to improve compression efficiency by processing similar files together as a single compression/encryption unit.
179 |
180 | **Example structure of SDAT content (conceptual):**
181 |
182 | ```
183 | [ FHED | Ancillary* | FDAT* | FEND ]
184 | [ FHED | Ancillary* | FDAT* | FEND ]
185 | ...
186 | ```
187 |
188 | The outer `SDAT` chunk may be followed by additional `SDAT` chunks if the solid data stream is split. These must be interpreted as a single contiguous logical stream, terminated by the `SEND` chunk.
189 |
190 | ### 4.1.10. SEND Solid mode tailer
191 |
192 | This signals the end of the solid data stream.
193 | The chunk data area is empty.
194 |
195 | ### 4.2. Ancillary chunks
196 |
197 | All Auxiliary Chunks must appear before the `AEND` chunk.
198 |
199 | #### 4.2.1 Timestamp information
200 |
201 | ##### 4.2.1.1 cTIM Created timestamp
202 |
203 | The creation datetime is recorded in Unix time.
204 | When this chunk appears after the `FHED` chunk and before the `FEND` chunk, it indicates the creation datetime of the entry.
205 |
206 | | size | description |
207 | |:------:|:---------------|
208 | | 8byte | Unix timestamp |
209 |
210 | ##### 4.2.1.2 mTIM Modified timestamp
211 |
212 | The last modified datetime is recorded in Unix time.
213 | When this chunk appears after the `FHED` chunk and before the `FEND` chunk, it indicates the last modified datetime of the entry.
214 |
215 | | size | description |
216 | |:------:|:---------------|
217 | | 8byte | Unix timestamp |
218 |
219 | ##### 4.2.1.3 aTIM Accessed timestamp
220 |
221 | The last accessed datetime is recorded in Unix time.
222 | When this chunk appears after the `FHED` chunk and before the `FEND` chunk, it indicates the last accessed datetime of the entry.
223 |
224 | | size | description |
225 | |:------:|:---------------|
226 | | 8byte | Unix timestamp |
227 |
228 | ##### 4.2.1.4 cTNS Created timestamp (Nanoseconds)
229 |
230 | Provides the nanosecond portion of the file creation time, to be used in conjunction with the `cTIM` chunk.
231 |
232 | - **Context**: Must appear after the `FHED` chunk and before the `FEND` chunk.
233 | - **Dependency**: Ignored unless `cTIM` is also present.
234 | - **Interpretation**: `cTIM` seconds + (`cTNS` / 1_000_000_000.0)
235 |
236 | | Size | Description |
237 | |--------|------------------------------------------|
238 | | 4-byte | Unsigned integer (`u32`), nanoseconds |
239 |
240 | Valid values are in the range `0 <= value < 1,000,000,000`.
241 |
242 | ##### 4.2.1.5 mTNS Modified timestamp (Nanoseconds)
243 |
244 | Provides the nanosecond portion of the last modified time, to be used in conjunction with the `mTIM` chunk.
245 |
246 | - **Context**: Must appear after the `FHED` chunk and before the `FEND` chunk.
247 | - **Dependency**: Ignored unless `mTIM` is also present.
248 | - **Interpretation**: `mTIM` seconds + (`mTNS` / 1_000_000_000.0)
249 |
250 | | Size | Description |
251 | |--------|------------------------------------------|
252 | | 4-byte | Unsigned integer (`u32`), nanoseconds |
253 |
254 | Valid values are in the range `0 <= value < 1,000,000,000`.
255 |
256 | ##### 4.2.1.6 aTNS Accessed timestamp (Nanoseconds)
257 |
258 | Provides the nanosecond portion of the last accessed time, to be used in conjunction with the `aTIM` chunk.
259 |
260 | - **Context**: Must appear after the `FHED` chunk and before the `FEND` chunk.
261 | - **Dependency**: Ignored unless `aTIM` is also present.
262 | - **Interpretation**: `aTIM` seconds + (`aTNS` / 1_000_000_000.0)
263 |
264 | | Size | Description |
265 | |--------|------------------------------------------|
266 | | 4-byte | Unsigned integer (`u32`), nanoseconds |
267 |
268 | Valid values are in the range `0 <= value < 1,000,000,000`.
269 |
270 | **Decoder Notes**:
271 | - If any `*TNS` chunk is present without its corresponding `*TIM` chunk, it must be ignored.
272 | - Values outside the range `[0, 999_999_999]` are invalid and must cause a decoder error.
273 | - Encoders should omit `*TNS` chunks unless sub-second precision is explicitly needed.
274 |
275 | #### 4.2.2 permission information
276 |
277 | ##### 4.2.2.1 fPRM File permission
278 |
279 | File permissions are recorded.
280 | This chunk appeared after `FHED` chunk and before `FEND` chunk.
281 |
282 | | significance | size | description |
283 | |:-------------|:------:|:----------------------|
284 | | uid | 8-byte | user ID |
285 | | uname length | 1-byte | length of uname |
286 | | uname | n-byte | Unix user name |
287 | | gid | 8-byte | group ID |
288 | | gname length | 1-byte | length of gname |
289 | | gname | n-byte | Unix group name |
290 | | permissions | 2-byte | file permission bytes |
291 |
292 | #### 4.2.3 Extended attribute
293 |
294 | ##### 4.2.3.1 xATR Extended attribute
295 |
296 | An extended attribute are recorded.
297 | this chunk appeared after `FHED` chunk and before `FEND` chunk. this chunk can appear many times.
298 |
299 | | significance | size | description |
300 | |:-------------|:------:|:----------------------|
301 | | name length | 4-byte | length of name |
302 | | name | n-byte | attribute name |
303 | | body length | 4-byte | length of body |
304 | | body | n-byte | attribute value |
305 |
306 | ### 4.3. Summary of standard chunks
307 |
308 | This table summarizes some properties of the standard chunk types.
309 |
310 | Critical chunks
311 |
312 | | Name | Multiple in Archive | Multiple in Entry | Optional | Ordering constraints |
313 | |:----:|:-------------------:|:-----------------:|:--------:|:-----------------------------------|
314 | | AHED | No | N/A | No | Must be first |
315 | | FHED | Yes | No | Yes | Must start an entry |
316 | | PHSF | Yes | No | Yes | Before FDAT or SDAT if used |
317 | | FDAT | Yes | Yes | Yes | Multiple FDATs must be consecutive |
318 | | FEND | Yes | No | Yes | Must end an entry |
319 | | SHED | Yes | No | Yes | Must start an Solid mode data |
320 | | SDAT | Yes | Yes | Yes | Multiple SDATs must be consecutive |
321 | | SEND | Yes | No | Yes | Must end an Solid mode data |
322 | | ANXT | No | N/A | Yes | |
323 | | AEND | No | N/A | No | Must be last |
324 |
325 | Ancillary chunks
326 |
327 | | Name | Multiple in Archive | Multiple in Entry | Optional | Ordering constraints |
328 | |:-----:|:-------------------:|:-----------------:|:--------:|:----------------------------------------------|
329 | | cTIM | Yes | No | Yes | Between `FHED` and `FEND` |
330 | | mTIM | Yes | No | Yes | Between `FHED` and `FEND` |
331 | | aTIM | Yes | No | Yes | Between `FHED` and `FEND` |
332 | | cTNS | Yes | No | Yes | Must accompany `cTIM`, between `FHED`–`FEND` |
333 | | mTNS | Yes | No | Yes | Must accompany `mTIM`, between `FHED`–`FEND` |
334 | | aTNS | Yes | No | Yes | Must accompany `aTIM`, between `FHED`–`FEND` |
335 | | fPRM | Yes | No | Yes | Between `FHED` and `FEND` |
336 | | xATR | Yes | Yes | Yes | Between `FHED` and `FEND` |
337 |
338 | ### 4.4. Additional chunk types
339 |
340 | Additional public PNA chunk types are defined in the document "Extensions to the PNA 0.0 Specification, Version 0.0.0" [PNA-EXTENSIONS]. Chunks described there are expected to be less widely supported than those defined in this specification. However, application authors are encouraged to use those chunk types whenever appropriate for their applications. Additional chunk types can be proposed for inclusion in that list by contacting the PNA specification maintainers at @Portable-Network-Archive on GitHub.
341 |
342 | New public chunks will be registered only if they are of use to others and do not violate the design philosophy of PNA. Chunk registration is not automatic, although it is the intent of the authors that it be straightforward when a new chunk of potentially wide application is needed. Note that the creation of new critical chunk types is discouraged unless absolutely necessary.
343 |
344 | Applications can also use private chunk types to carry data that is not of interest to other applications. See Recommendations for Encoders: Use of private chunks.
345 |
346 | Decoders must be prepared to encounter unrecognized public or private chunk-type codes. Unrecognized chunk types must be handled as described in Chunk naming conventions.
347 |
--------------------------------------------------------------------------------
/cipher_algorithms/index.md:
--------------------------------------------------------------------------------
1 | ## 6. Cipher algorithms
2 |
3 | PNA employs multiple cipher algorithms. This specification is designed to ensure the secure use of PNA by enabling the selection of alternative cipher algorithms in the event of a critical flaw discovered in a specific algorithm. In this chapter, we will define the cipher algorithms available for use in PNA. For information on cipher mode, please refer to the following chapter.
4 |
5 | ### 6.1 Rijndael
6 |
7 | PNA cipher method 0 specifies Rijndael encryption with a key length of 256 bits and a block length of 128 bits. Rijndael, generally known as AES(Advanced Encryption Standard), is a widely accepted symmetric encryption algorithm renowned for its security and efficiency. It operates on blocks of data and supports key sizes of 128, 192, and 256 bits. In PNA, Rijndael with a key length of 256 bits is utilized. This provides a high level of encryption strength, ensuring that the archived data remains secure against unauthorized access.
8 |
9 | Rijndael-encrypted datastreams within PNA are stored in a format depending on the cipher mode.
10 |
11 | For PNA cipher method 0, the Rijndael encryption method/flags code must specify method code 1 ("Rijndael" encryption). Note that the Rijndael encryption method number is not the same as PNA cipher method number. A PNA decoder must be able to decrypt any valid Rijndael-encrypted datastream that satisfies these additional constraints.
12 |
13 | In an entry of PNA file, the concatenation of the contents of all the FDAT chunks between FHED and FEND makes up a Rijndael-encrypted datastream as specified above. This datastream decrypts to file data as described elsewhere in this document.
14 |
15 | It is important to emphasize that the boundaries between FDAT chunks are arbitrary and can fall anywhere in the Rijndael-encrypted datastream. There is not necessarily any correlation between FDAT chunk boundaries and block boundaries or any other feature of the Rijndael-encrypted data.
16 |
17 | In the same vein, there is no required correlation between the structure of the file data and deflate block boundaries or FDAT chunk boundaries. The complete entry data is represented by a single Rijndael-encrypted datastream that is stored in some number of FDAT chunks; a decoder that assumes any more than this is incorrect. (Of course, some encoder implementations may emit files in which some of these structures are indeed related. But decoders cannot rely on this.)
18 |
19 | Treat all SDAT chunks between SHAD and SEND in the same way.
20 |
21 | Additional documentation is available from the Cryptographic Standards and Guidelines archives at [http://www.nist.gov/aes](http://www.nist.gov/aes) and the FIPS Publication 197 [FIPS-197](https://csrc.nist.gov/publications/detail/fips/197/final).
22 |
23 | ### 6.2 Camellia
24 |
25 | PNA cipher method 1 specifies Camellia encryption with a key length of 256 bits and a block length of 128 bits. Camellia is a symmetric encryption algorithm developed jointly by Nippon Telegraph and Telephone Corporation (NTT) and Mitsubishi Electric Corporation. It is designed to offer high security and performance comparable to AES. Camellia supports key sizes of 128, 192, and 256 bits. In PNA, Camellia with a key length of 256 bits is employed, enhancing the overall security of the archived data.
26 |
27 | Camellia-encrypted datastream within PNA is stored in a format depending on the cipher use mode.
28 |
29 | For PNA cipher method 1, the Camellia encryption method/flags code must specify method code 2 ("Camellia" encryption). Note that the Camellia encryption method number is not the same as PNA cipher method number. A PNA decoder must be able to decrypt any valid Camellia-encrypted datastream that satisfies these additional constraints.
30 |
31 | In an entry of PNA file, the concatenation of the contents of all the FDAT chunks between FHED and FEND makes up a Camellia-encrypted datastream as specified above. This datastream decrypts to file data as described elsewhere in this document.
32 |
33 | It is important to emphasize that the boundaries between FDAT chunks are arbitrary and can fall anywhere in the Camellia-encrypted datastream. There is not necessarily any correlation between FDAT chunk boundaries and block boundaries or any other feature of the Camellia-encrypted data.
34 |
35 | In the same vein, there is no required correlation between the structure of the file data and deflate block boundaries or FDAT chunk boundaries. The complete entry data is represented by a single Camellia-encrypted datastream that is stored in some number of FDAT chunks; a decoder that assumes any more than this is incorrect. (Of course, some encoder implementations may emit files in which some of these structures are indeed related. But decoders cannot rely on this.)
36 |
37 | Treat all SDAT chunks between SHAD and SEND in the same way.
38 |
39 | Additional documentation is available from the Camellia Specification at [RFC-3713](https://datatracker.ietf.org/doc/html/rfc3713).
40 |
--------------------------------------------------------------------------------
/cipher_modes/index.md:
--------------------------------------------------------------------------------
1 | ## 7. Cipher modes
2 |
3 | PNA employs multiple cipher modes of operation. This specification is designed to ensure the secure use of PNA by enabling the selection of alternative cipher modes of operation in the event of a critical flaw discovered in a specific cipher mode of operation.
4 |
5 | ### 7.1. Cipher Block Chaining Mode (CBC)
6 | PNA cipher mode of operation method 0 specifies CBC with a block length of 128 bits.
7 |
8 | CBC mode is a block cipher mode of operation that provides confidentiality and integrity through chaining encrypted blocks. In CBC mode, each plaintext block is XORed with the previous ciphertext block before encryption. It introduces a dependency between blocks, making it suitable for scenarios where each block's integrity relies on the preceding block.
9 |
10 | This document specifies the use of the Rijndael or Camellia cipher in CBC mode within PNA.
11 |
12 | This mode requires an Initialization Vector (IV) that is the same size as the block size. Use of a randomly generated IV prevents generation of identical ciphertext from packets which have identical data that spans the first block of the cipher algorithm's block size.
13 |
14 | The IV is XOR'd with the first plaintext block before it is encrypted. Then for successive blocks, the previous ciphertext block is XOR'd with the current plaintext, before it is encrypted.
15 |
16 | More information on CBC mode can be obtained in [MODES](../references/index.md#modes), [CRYPTO-S](../references/index.md#crypto-s)
17 |
18 | ### 7.2. Counter Mode (CTR)
19 | PNA cipher mode of operation method 1 specifies CTR with a block length of 128 bits.
20 |
21 | CTR mode is a stream cipher mode of operation, where each plaintext block is encrypted by XORing it with the corresponding block of a keystream. CTR offers excellent parallelizability and allows random access to individual blocks, making it suitable for scenarios where seeking and parallel processing are required.
22 |
23 | This document specifies the use of the Rijndael or Camellia cipher in CTR mode within PNA.
24 |
25 | CTR requires the encryptor to generate a unique per-packet value and communicate this value to the decryptor. This specification calls this per-packet value an initialization vector (IV). The same IV and key combination MUST NOT be used more than once. The encryptor can generate the IV in any manner that ensures uniqueness. Common approaches to IV generation include incrementing a counter for each packet.
26 |
27 | More information on CTR mode can be obtained in [MODES](../references/index.md#modes)
28 |
29 |
30 | ### 7.3. Initialization Vector (IV) Placement in Encrypted Streams
31 |
32 | When using an encryption mode that requires an Initialization Vector (IV), such as CBC (Cipher Block Chaining) or CTR (Counter Mode), PNA requires that the IV be prepended to the beginning of the encrypted datastream.
33 |
34 | #### 7.3.1 Placement
35 |
36 | For both per-entry (`FDAT`) and solid mode (`SDAT`) encrypted datastreams, the IV appears at the start of the stream. The IV is always 16 bytes in length, corresponding to the 128-bit block size used by both Rijndael (AES) and Camellia.
37 |
38 | The structure of an encrypted stream is:
39 |
40 | ```
41 | [16-byte IV] + [ciphertext data...]
42 | ```
43 |
44 | #### 7.3.2 Decoder Behavior
45 |
46 | A decoder must extract the first 16 bytes of the encrypted datastream as the Initialization Vector. The remainder of the datastream represents the ciphertext, which must be decrypted using the specified cipher algorithm and mode.
47 |
48 | #### 7.3.3 Encoder Behavior
49 |
50 | An encoder must generate a new, cryptographically secure random IV for each encrypted stream. The IV must be prepended to the encrypted datastream.
51 |
52 | Reuse of an IV with the same encryption key is prohibited and renders the archive cryptographically insecure.
53 |
--------------------------------------------------------------------------------
/compression_algorithms/index.md:
--------------------------------------------------------------------------------
1 | ## 5. Compression algorithms
2 |
3 | PNA allows the use of multiple compression algorithms. This is designed to achieve high performance by switching compression algorithms depending on the intended use and environment.
4 |
5 | ### 5.1. Deflate
6 |
7 | PNA compression method 0 specifies deflate/inflate compression with a sliding window of at most 32768 bytes. Deflate compression is an LZ77 derivative used in zip, gzip, pkzip, and related programs. Extensive research has been done supporting its patent-free status. Portable C implementations are freely available.
8 |
9 | Deflate-compressed datastreams within PNA are stored in the "zlib" format, which has the structure:
10 |
11 | Compression method/flags code: 1 byte
12 | Additional flags/check bits: 1 byte
13 | Compressed data blocks: n bytes
14 | Check value: 4 bytes
15 | Further details on this format are given in the zlib specification [RFC-1950](../references/index.md#rfc-1950).
16 |
17 | For PNA compression method 0, the zlib compression method/flags code must specify method code 1 ("deflate" compression) and an LZ77 window size of not more than 32768 bytes. Note that the zlib compression method number is not the same as PNA compression method number. The additional flags must not specify a preset dictionary. A PNA decoder must be able to decompress any valid zlib datastream that satisfies these additional constraints.
18 |
19 | If the data to be compressed contains 16384 bytes or fewer, the encoder can set the window size by rounding up to a power of 2 (256 minimum). This decreases the memory required not only for encoding but also for decoding, without adversely affecting the compression ratio.
20 |
21 | The compressed data within the zlib datastream is stored as a series of blocks, each of which can represent raw (uncompressed) data, LZ77-compressed data encoded with fixed Huffman codes, or LZ77-compressed data encoded with custom Huffman codes. A marker bit in the final block identifies it as the last block, allowing the decoder to recognize the end of the compressed datastream. Further details on the compression algorithm and the encoding are given in the deflate specification [RFC-1951](../references/index.md#rfc-1951).
22 |
23 | The check value stored at the end of the zlib datastream is calculated on the uncompressed data represented by the datastream. Note that the algorithm used is not the same as the CRC calculation used for PNA chunk check values. The zlib check value is useful mainly as a cross-check that the deflate and inflate algorithms are implemented correctly. Verifying the chunk CRCs provides adequate confidence that PNA file has been transmitted undamaged.
24 |
25 | In an entry of PNA file, the concatenation of the contents of all the FDAT chunks between FHED and FEND makes up a zlib datastream as specified above. This datastream decompresses to file data as described elsewhere in this document.
26 |
27 | It is important to emphasize that the boundaries between FDAT chunks are arbitrary and can fall anywhere in the zlib datastream. There is not necessarily any correlation between FDAT chunk boundaries and deflate block boundaries or any other feature of the zlib data. For example, it is entirely possible for the terminating zlib check value to be split across FDAT chunks.
28 |
29 | In the same vein, there is no required correlation between the structure of the file data and deflate block boundaries or FDAT chunk boundaries. The complete entry data is represented by a single zlib datastream that is stored in some number of FDAT chunks; a decoder that assumes any more than this is incorrect. (Of course, some encoder implementations may emit files in which some of these structures are indeed related. But decoders cannot rely on this.)
30 |
31 | Treat all SDAT chunks between SHAD and SEND in the same way.
32 |
33 | Additional documentation and portable C code for deflate and inflate are available from the Info-ZIP archives at [ftp://ftp.info-zip.org/pub/infozip/](ftp://ftp.info-zip.org/pub/infozip/).
34 |
35 | ### 5.2. ZStandard
36 |
37 | PNA compression method 1 specifies ZStandard compression with a [RFC-8878](../references/index.md#rfc-8878). ZStandard compression is an LZ77 derivative used in linux kernel, btrfs, squashfs, and related programs. Reference implementations are BSD license and freely available.
38 |
39 | For PNA compression method 1, the ZStandard compression method/flags code must specify method code 2 ("ZStandard" compression). Note that the ZStandard compression method number is not the same as PNA compression method number. The additional flags must not specify a preset dictionary. A PNA decoder must be able to decompress any valid ZStandard datastream that satisfies these additional constraints.
40 |
41 | In an entry of PNA file, the concatenation of the contents of all the FDAT chunks between FHED and FEND makes up a ZStandard datastream as specified above. This datastream decompresses to file data as described elsewhere in this document.
42 |
43 | It is important to emphasize that the boundaries between FDAT chunks are arbitrary and can fall anywhere in the ZStandard datastream. There is not necessarily any correlation between FDAT chunk boundaries or any other feature of the ZStandard data. For example, it is entirely possible for the terminating ZStandard check value to be split across FDAT chunks.
44 |
45 | In the same vein, there is no required correlation between the structure of the file data or FDAT chunk boundaries. The complete entry data is represented by a single ZStandard datastream that is stored in some number of FDAT chunks; a decoder that assumes any more than this is incorrect. (Of course, some encoder implementations may emit files in which some of these structures are indeed related. But decoders cannot rely on this.)
46 |
47 | Treat all SDAT chunks between SHAD and SEND in the same way.
48 |
49 | Additional documentation and Reference implementations of ZStandard are available from GitHub at [https://facebook.github.io/zstd/](https://facebook.github.io/zstd/) and [https://github.com/facebook/zstd](https://github.com/facebook/zstd)
50 |
51 | ### 5.3. LZMA
52 |
53 | PNA compression method 2 specifies LZMA compression with a [](). LZMA compression is an LZ77 derivative used in linux kernel, 7-zip, xz-utils, and related programs. Reference implementations are BSD license and freely available.
54 |
55 | LZMA-compressed datastreams within PNA are stored in the "xz" format.
56 | Further details on this format are given in the xz specification [https://tukaani.org/xz/xz-file-format.txt](https://tukaani.org/xz/xz-file-format.txt).
57 |
58 | For PNA compression method 2, the LZMA compression method/flags code must specify method code 4 ("LZMA" compression). Note that the LZMA compression method number is not the same as PNA compression method number. The additional flags must not specify a preset dictionary. A PNA decoder must be able to decompress any valid LZMA datastream that satisfies these additional constraints.
59 |
60 | In an entry of PNA file, the concatenation of the contents of all the FDAT chunks between FHED and FEND makes up a LZMA datastream as specified above. This datastream decompresses to file data as described elsewhere in this document.
61 |
62 | It is important to emphasize that the boundaries between FDAT chunks are arbitrary and can fall anywhere in the LZMA datastream. There is not necessarily any correlation between FDAT chunk boundaries or any other feature of the LZMA data. For example, it is entirely possible for the terminating LZMA check value to be split across FDAT chunks.
63 |
64 | In the same vein, there is no required correlation between the structure of the file data or FDAT chunk boundaries. The complete entry data is represented by a single LZMA datastream that is stored in some number of FDAT chunks; a decoder that assumes any more than this is incorrect. (Of course, some encoder implementations may emit files in which some of these structures are indeed related. But decoders cannot rely on this.)
65 |
66 | Treat all SDAT chunks between SHAD and SEND in the same way.
67 |
68 | Additional documentation and Reference implementations of LZMA are available from GitHub at [https://github.com/tukaani-project/xz](https://github.com/tukaani-project/xz).
69 |
--------------------------------------------------------------------------------
/data_representation/index.md:
--------------------------------------------------------------------------------
1 | ## 2. Data Representation
2 |
3 | This chapter discusses basic data representations used in PNA files, as well as the expected representation of the archive data.
4 |
5 | ### 2.1 Archive layout
6 |
7 | Conceptually, PNA archive is represented by a series of multiple entries between the start and end headers.
8 | There are multiple types of entries, including files and directories.
9 |
10 | Three types of archives are supported:
11 | - An archive in which one entry consists of one file or directory and corresponding entries
12 | - An archive consisting of an entry that is a collection of multiple entries
13 | - Archives that combine the above two types, allowing for a mix of individual entries and collections within the same archive
14 |
15 | Optionally, PNA archive can be split.
16 | Splitting is allowed across entries.
17 |
18 | ### 2.2. Integers and byte order
19 |
20 | All integers that require more than one byte must be in network byte order: the most significant byte comes first, then the less significant bytes in descending order of significance (MSB LSB for two-byte integers, B3 B2 B1 B0 for four-byte integers). The highest bit (value 128) of a byte is numbered bit 7; the lowest bit (value 1) is numbered bit 0. Values are unsigned unless otherwise noted. Values explicitly noted as signed are represented in two's complement notation.
21 |
22 | ### 2.3 Text encodings
23 |
24 | All character information must be encoded in UTF-8: this also includes the path for each entry.
25 |
--------------------------------------------------------------------------------
/file_structure/index.md:
--------------------------------------------------------------------------------
1 | ## 3. File Structure
2 |
3 | A PNA file consists of a PNA signature followed by a series of chunks.
4 | This chapter defines the signature and the basic properties of chunks. Individual chunk types are discussed in the next chapter.
5 |
6 | ### 3.1. PNA file signature
7 | The first eight bytes of a PNA file always contain the following values:
8 |
9 | | hex | ASCII |
10 | |:-----:|:-----------:|
11 | | 0x89 | ¥x89 |
12 | | 0x50 | P |
13 | | 0x4E | N |
14 | | 0x41 | A |
15 | | 0x0D | CR(Ctrl-M) |
16 | | 0x0A | LF(Ctrl-J) |
17 | | 0x1A | Ctrl-Z |
18 | | 0x0A | LF(Ctrl-J) |
19 |
20 | This signature indicates that the remainder of the file contains a single PNA archive, consisting of a series of chunks beginning with an AHED chunk and ending with an AEND chunk.
21 |
22 | ### 3.2. Entry layout
23 |
24 | Each entry consists of three parts:
25 |
26 | **Header:**
27 |
28 | The basic information of the entry, the type of entry, the compression algorithm, the encryption algorithm and the encryption use mode are recorded.
29 | Decoders are required to select the appropriate algorithm based on this information and extract the file.
30 |
31 | **Ancillary:**
32 |
33 | Ancillary information such as the creation and update datetime, ownership, permissions, and others.
34 | These are not required for entry.
35 |
36 | **Data:**
37 |
38 | Actual data of the entry.
39 | The data is allowed to be split into multiple chunks.
40 | By splitting the data into smaller chunks can help to detect file corruption more quickly.
41 | Depending on the type of entry, this data is also allowed to be empty.
42 | About the types of entries are in the next chapter.
43 |
44 | **Tailer:**
45 |
46 | End of entry marker.
47 | The point where this chunk appears is the end point of a single entry.
48 | It is permitted to start the next entry following this entry or to continue with a chunk indicating the end of the archive.
49 |
50 | ### 3.3 Entry kind
51 |
52 | The following types of entry are currently supported.
53 |
54 | **Regular file**
55 |
56 | **Directory**
57 |
58 | **Symbolic link**
59 |
60 | **Hard link**
61 |
62 | ### 3.4 Special entry
63 |
64 | A special entry is supported, a solid-mode-only entry that holds data that concatenated the above entries.
65 | This entry is similar to a normal entries, but the data part records the data of concatenated the normal entry instead of the actual data of the entry.
66 | The chunks that make up this special entry have chunks dedicated to solid mode.
67 |
68 | The data part of this special entry is contained in one or more `SDAT` chunks and is conceptually a concatenated stream of multiple standard entries.
69 | Each of these embedded entries MUST follow the same structure as regular entries, consisting of `FHED`, optional ancillary chunks, `FDAT`, and `FEND`.
70 |
71 | Decoders must parse the content of `SDAT` as an ordered sequence of standard entries.
72 |
73 | Encryption or compression applied to the `SDAT` stream is applied as a whole after entry composition.
74 |
75 | In solid mode, multiple entries are represented as a concatenated stream within `SDAT`, each following the same layout structure (Header, Ancillary, Data, Tailer).
76 | The decoder must scan and identify each logical entry within the `SDAT` stream by parsing `FHED` to `FEND` boundaries.
77 |
78 | ### 3.5 Chunk layout
79 |
80 | Each chunk consists of four parts:
81 |
82 | **Length**
83 |
84 | A 4-byte unsigned integer giving the number of bytes in the chunk's data field. The length counts only the data field, not itself, the chunk type code, or the CRC. Zero is a valid length.
85 |
86 | **Chunk Type**
87 |
88 | A 4-byte chunk type code. For convenience in description and in examining PNA files, type codes are restricted to consist of uppercase and lowercase ASCII letters (A-Z and a-z, or 65-90 and 97-122 decimal). However, encoders and decoders must treat the codes as fixed binary values, not character strings. Additional naming conventions for chunk types are discussed in the next section.
89 |
90 | **Chunk Data**
91 |
92 | The data bytes appropriate to the chunk type, if any. This field can be of zero length.
93 |
94 | **CRC**
95 |
96 | A 4-byte CRC (Cyclic Redundancy Check) calculated on the preceding bytes in the chunk, including the chunk type code and chunk data fields, but not including the length field. The CRC is always present, even for chunks containing no data. See [CRC algorithm](#37-crc-algorithm).
97 |
98 | The chunk data length can be any number of bytes up to the maximum; therefore, implementors cannot assume that chunks are aligned on any boundaries larger than bytes.
99 |
100 | Chunks can appear in any order, subject to the restrictions placed on each chunk type. (One notable restriction is that FHED must appear first and FEND must appear last; thus the FEND chunk serves as an end-of-file marker.) Multiple chunks of the same type can appear, but only if specifically permitted for that type.
101 |
102 | ### 3.6. Chunk naming conventions
103 |
104 | Chunk type codes are assigned so that a decoder can determine some properties of a chunk even when it does not recognize the type code. These rules are intended to allow safe, flexible extension of PNA format, by allowing a decoder to decide what to do when it encounters an unknown chunk. The naming rules are not normally of interest when the decoder does recognize the chunk's type.
105 |
106 | Four bits of the type code, namely bit 5 (value 32) of each byte, are used to convey chunk properties. This choice means that a human can read off the assigned properties according to whether each letter of the type code is uppercase (bit 5 is 0) or lowercase (bit 5 is 1). However, decoders should test the properties of an unknown chunk by numerically testing the specified bits; testing whether a character is uppercase or lowercase is inefficient, and even incorrect if a locale-specific case definition is used.
107 |
108 | It is worth noting that the property bits are an inherent part of the chunk name, and hence are fixed for any chunk type. Thus, BLOB and bLOb would be unrelated chunk type codes, not the same chunk with different properties. Decoders must recognize type codes by a simple four-byte literal comparison; it is incorrect to perform case conversion on type codes.
109 |
110 | The semantics of the property bits are:
111 |
112 | **Ancillary bit: bit 5 of first byte**
113 |
114 | 0 (uppercase) = critical, 1 (lowercase) = ancillary.
115 | Chunks that are not strictly necessary in order to meaningfully extract the contents of the file are known as "ancillary" chunks. A decoder encountering an unknown chunk in which the ancillary bit is 1 can safely ignore the chunk and proceed to extract the file. The created time chunk (cTIM) is an example of an ancillary chunk.
116 |
117 | Chunks that are necessary for successful extract of the file's contents are called "critical" chunks. A decoder encountering an unknown chunk in which the ancillary bit is 0 must indicate to the user that the file contains information it cannot safely interpret. The file header chunk (FHED) is an example of a critical chunk.
118 |
119 | **Private bit: bit 5 of second byte**
120 |
121 | 0 (uppercase) = public, 1 (lowercase) = private.
122 | A public chunk is one that is part of PNA specification or is registered in the list of PNA special-purpose public chunk types. Applications can also define private (unregistered) chunks for their own purposes. The names of private chunks must have a lowercase second letter, while public chunks will always be assigned names with uppercase second letters. Note that decoders do not need to test the private-chunk property bit, since it has no functional significance; it is simply an administrative convenience to ensure that public and private chunk names will not conflict. See [Additional chunk types](../chunk_specifications/index.md#44-additional-chunk-types), and Recommendations for Encoders: [Use of private chunks](TODO: link to ../recommendations_for_encoders/index.md).
123 |
124 | **Reserved bit: bit 5 of third byte**
125 |
126 | Must be 0 (uppercase) in files conforming to this version of PNA.
127 | The significance of the case of the third letter of the chunk name is reserved for possible future expansion. At the present time all chunk names must have uppercase third letters. (Decoders should not complain about a lowercase third letter, however, as some future version of PNA specification could define a meaning for this bit. It is sufficient to treat a chunk with a lowercase third letter in the same way as any other unknown chunk type.)
128 |
129 | **Safe-to-copy bit: bit 5 of fourth byte**
130 |
131 | 0 (uppercase) = unsafe to copy, 1 (lowercase) = safe to copy.
132 | This property bit is not of interest to pure decoders, but it is needed by PNA editors (programs that modify PNA files). This bit defines the proper handling of unrecognized chunks in a file that is being modified.
133 |
134 | If a chunk's safe-to-copy bit is 1, the chunk may be copied to a modified PNA file whether or not the software recognizes the chunk type, and regardless of the extent of the file modifications.
135 |
136 | If a chunk's safe-to-copy bit is 0, it indicates that the chunk depends on the file data. If the program has made any changes to critical chunks, including addition, modification, deletion, or reordering of critical chunks, then unrecognized unsafe chunks must not be copied to the output PNA file. (Of course, if the program does recognize the chunk, it can choose to output an appropriately modified version.)
137 |
138 | A PNA editor is always allowed to copy all unrecognized chunks if it has only added, deleted, modified, or reordered ancillary chunks. This implies that it is not permissible for ancillary chunks to depend on other ancillary chunks.
139 |
140 | PNA editors that do not recognize a critical chunk must report an error and refuse to process that PNA file at all. The safe/unsafe mechanism is intended for use with ancillary chunks. The safe-to-copy bit will always be 0 for critical chunks.
141 |
142 | Rules for PNA editors are discussed further in Chunk Ordering Rules.
143 |
144 | For example, the hypothetical chunk type name bLOb has the property bits:
145 |
146 | bLOb <-- 32-bit chunk type code represented in text form
147 | ||||
148 | |||+- Safe-to-copy bit is 1 (lowercase letter; bit 5 is 1)
149 | ||+-- Reserved bit is 0 (uppercase letter; bit 5 is 0)
150 | |+--- Private bit is 0 (uppercase letter; bit 5 is 0)
151 | +---- Ancillary bit is 1 (lowercase letter; bit 5 is 1)
152 | Therefore, this name represents an ancillary, public, safe-to-copy chunk.
153 |
154 | ### 3.7. CRC algorithm
155 |
156 | Chunk CRCs are calculated using standard CRC methods with pre and post conditioning, as defined by ISO 3309 [ISO-3309](../references/index.md#iso-3309) or ITU-T V.42 [ITU-T-V42](../references/index.md#itu-t-v42). The CRC polynomial employed is
157 |
158 | x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x+1
159 |
160 | The 32-bit CRC register is initialized to all 1's, and then the data from each byte is processed from the least significant bit (1) to the most significant bit (128). After all the data bytes are processed, the CRC register is inverted (its ones complement is taken). This value is transmitted (stored in the file) MSB first. For the purpose of separating into bytes and ordering, the least significant bit of the 32-bit CRC is defined to be the coefficient of the x31 term.
161 |
162 | Practical calculation of the CRC always employs a precalculated table to greatly accelerate the computation.
163 |
--------------------------------------------------------------------------------
/glossary/index.md:
--------------------------------------------------------------------------------
1 | ## 13. Glossary
2 |
3 | **AES (Rijndael)**
4 | A symmetric-key block cipher algorithm standardized as Advanced Encryption Standard (AES). Rijndael was selected as the AES algorithm and supports key sizes of 128, 192, and 256 bits. In PNA, AES with a 256-bit key and 128-bit block size is used for encryption.
5 |
6 | **Ancillary chunk**
7 | A chunk that provides additional information. A decoder can still produce a meaningful archive, though not necessarily the best possible archive, without processing the chunk.
8 |
9 | **Archive number**
10 | A 4-byte field in the AHED chunk indicating the sequence number of a split archive part. The first part is numbered 0, and subsequent parts increment by 1.
11 |
12 | **Argon2**
13 | A modern memory-hard key derivation function and password hashing algorithm, designed to resist GPU and side-channel attacks. Argon2 is the winner of the Password Hashing Competition (PHC) and is recommended for secure password storage and key derivation.
14 |
15 | **Byte**
16 | Eight bits; also called an octet.
17 |
18 | **Camellia**
19 | A symmetric-key block cipher algorithm developed by NTT and Mitsubishi Electric. Camellia is designed to offer high security and performance comparable to AES, and supports key sizes of 128, 192, and 256 bits. In PNA, Camellia with a 256-bit key and 128-bit block size is used for encryption.
20 |
21 | **Cipher mode**
22 | A method of using a block cipher to encrypt data, defining how blocks of plaintext are transformed into ciphertext. Common modes include CBC (Cipher Block Chaining) and CTR (Counter mode), each providing different security properties and operational characteristics.
23 |
24 | **Chunk**
25 | A section of a PNA file. Each chunk has a type indicated by its chunk type name. Most types of chunks also include some data. The format and meaning of the data within the chunk are determined by the type name.
26 |
27 | **CRC (Cyclic Redundancy Check)**
28 | A CRC is a type of check value designed to catch most transmission errors. A decoder calculates the CRC for the received data and compares it to the CRC that the encoder calculated, which is appended to the data. A mismatch indicates that the data was corrupted in transit.
29 |
30 | **Critical chunk**
31 | A chunk that must be understood and processed by the decoder in order to produce a meaningful archive from a PNA file.
32 |
33 | **Datastream**
34 | A sequence of bytes. This term is used rather than "file" to describe a byte sequence that is only a portion of a file. We also use it to emphasize that a PNA archive might be generated and consumed "on-the-fly", never appearing in a stored file at all.
35 |
36 | **Deflate**
37 | The name of the compression algorithm used in standard PNG files, as well as in zip, gzip, pkzip, and other compression programs. Deflate is a member of the LZ77 family of compression methods.
38 |
39 | **Entry**
40 | A logical unit within a PNA archive, representing a file, directory, symbolic link, hard link, or a reference to a previously stored file. Each entry is described by a header, optional ancillary information, data, and a tailer.
41 |
42 | **File signature**
43 | A fixed 8-byte sequence at the beginning of every PNA file, used to identify the file as a PNA archive and detect file corruption or misidentification.
44 |
45 | **Initialization Vector (IV)**
46 | A random or unique value used as the initial input for certain encryption modes (such as CBC and CTR) to ensure that identical plaintexts encrypt to different ciphertexts. The IV must never be reused with the same key.
47 |
48 | **Key derivation function (KDF)**
49 | A cryptographic algorithm that derives one or more secret keys from a password or passphrase, often using a salt and multiple iterations to increase security against brute-force attacks.
50 |
51 | **Lossless compression**
52 | Any method of data compression that guarantees the original data can be reconstructed exactly, bit-for-bit.
53 |
54 | **Lossy compression**
55 | Any method of data compression that reconstructs the original data approximately, rather than exactly.
56 |
57 | **LSB (Least Significant Byte)**
58 | Least Significant Byte of a multi-byte value.
59 |
60 | **LZMA (Lempel-Ziv-Markov chain algorithm)**
61 | A lossless data compression algorithm that uses a dictionary compression scheme and range encoding. LZMA is known for its high compression ratio and is used in formats such as xz and 7z.
62 |
63 | **MSB (Most Significant Byte)**
64 | Most Significant Byte of a multi-byte value.
65 |
66 | **Password hash**
67 | A cryptographic hash of a password, typically generated using a key derivation function (such as PBKDF2 or Argon2) and a salt, to securely store or verify passwords without saving the original password.
68 |
69 | **PBKDF2 (Password-Based Key Derivation Function 2)**
70 | A widely used key derivation function that applies a pseudorandom function (such as HMAC) to the input password along with a salt and repeats the process many times to produce a derived key. PBKDF2 is specified in RFC 2898.
71 |
72 | **PHC string format**
73 | A standardized string format for encoding password hash parameters and results, as defined by the Password Hashing Competition (PHC). It encodes the algorithm, parameters, salt, and hash in a single string.
74 |
75 | **PNA editor**
76 | A program that modifies a PNA file and preserves ancillary information, including chunks that it does not recognize. Such a program must obey the rules given in Chunk Ordering Rules.
77 |
78 | **Salt**
79 | A random value added to a password before hashing, to ensure that identical passwords result in different hashes and to protect against precomputed attacks such as rainbow tables.
80 |
81 | **Solid mode**
82 | A storage mode in which multiple entries' data are concatenated and compressed/encrypted as a single continuous stream, improving compression ratio for similar files. Solid mode entries use dedicated chunk types (SHED, SDAT, SEND).
83 |
84 | **Split archive**
85 | A PNA archive that is divided into multiple files for easier storage or transfer. Each part contains a portion of the archive, and the order is managed by the Archive number and file naming conventions (e.g., .part1.pna, .part2.pna).
86 |
87 | **UTF-8**
88 | A variable-width character encoding used for electronic communication, capable of encoding all possible Unicode code points. UTF-8 is the required encoding for all textual data in PNA files, including file paths.
89 |
90 | **xz**
91 | A file format and software for lossless data compression, utilizing the LZMA2 algorithm. The xz format is commonly used for compressing software packages and archives in Unix-like systems.
92 |
93 | **Zstandard (Zstd)**
94 | A fast lossless compression algorithm developed by Facebook, providing high compression ratios and very fast decompression. Zstandard is widely used in modern systems and supports adjustable compression levels.
95 |
96 | **zlib**
97 | A particular format for data that has been compressed using deflate-style compression. Also the name of a library implementing this method. PNA implementations need not use the zlib library, but they must conform to its format for compressed data.
98 |
--------------------------------------------------------------------------------
/index.md:
--------------------------------------------------------------------------------
1 | # PNA (Portable Network Archive) Specification
2 |
3 | ## Status of this Document
4 |
5 | This is a PNA 0.0 specification and is subject to change without notice as it is still under development.
6 |
7 | ## Abstract
8 |
9 | This document describes PNA (Portable Network Archive), an extensible file format for the lossless, portable, well-compressed archive of files. PNA can also replace many common uses of zip and tar. Multiple types of compression, including Zstanderd, multiple types of encryption, including AES, and their solid modes, plus optional archive splitting are supported.
10 |
11 | PNA is robust, providing both full file integrity checking and simple detection of common transmission errors.
12 |
13 | <!-- This specification defines the Internet Media Type "application/pna". -->
14 |
15 | ## Table of Contents
16 |
17 | - [1. Introduction](./introduction/index.md)
18 | - [2. Data Representation](./data_representation/index.md#2-data-representation)
19 | - [2.1 Archive layout](./data_representation/index.md#21-archive-layout)
20 | - [2.2. Integers and byte order](./data_representation/index.md#22-integers-and-byte-order)
21 | - [2.3 Text encodings](./data_representation/index.md#23-text-encodings)
22 | - [3. File Structure](./file_structure/index.md#3-file-structure)
23 | - [3.1. PNA file signature](./file_structure/index.md#31-pna-file-signature)
24 | - [3.2. Entry layout](./file_structure/index.md#32-entry-layout)
25 | - [3.3. Entry kind](./file_structure/index.md#33-entry-kind)
26 | - [3.4. Special entry](./file_structure/index.md#34-special-entry)
27 | - [3.5. Chunk layout](./file_structure/index.md#35-chunk-layout)
28 | - [3.6. Chunk naming conventions](./file_structure/index.md#36-chunk-naming-conventions)
29 | - [3.7. CRC algorithm](./file_structure/index.md#37-crc-algorithm)
30 | - [4. Chunk Specifications](./chunk_specifications/index.md)
31 | - [4.1. Critical chunks](./chunk_specifications/index.md#41-critical-chunks)
32 | - [4.1.1. AHED Archive header](./chunk_specifications/index.md#411-ahed-archive-header)
33 | - [4.1.2. AEND Archive tailer](./chunk_specifications/index.md#412-aend-archive-tailer)
34 | - [4.1.3. ANXT Archive continues marker](./chunk_specifications/index.md#413-anxt-archive-continues-marker)
35 | - [4.1.4. FHED File header](./chunk_specifications/index.md#414-fhed-file-header)
36 | - [4.1.5. PHSF Password hash](./chunk_specifications/index.md#415-phsf-password-hash)
37 | - [4.1.6. FDAT File data](./chunk_specifications/index.md#416-fdat-file-data)
38 | - [4.1.7. FEND File tailer](./chunk_specifications/index.md#417-fend-file-tailer)
39 | - [4.1.8. SHED Solid mode header](./chunk_specifications/index.md#418-shed-solid-mode-header)
40 | - [4.1.9. SDAT Solid mode data](./chunk_specifications/index.md#419-sdat-solid-mode-data)
41 | - [4.1.9.1 Structure of Entries in SDAT](./chunk_specifications/index.md#4191-structure-of-entries-in-sdat)
42 | - [4.1.10. SEND Solid mode tailer](./chunk_specifications/index.md#4110-send-solid-mode-tailer)
43 | - [4.2. Ancillary chunks](./chunk_specifications/index.md#42-ancillary-chunks)
44 | - [4.2.1 Timestamp information](./chunk_specifications/index.md#421-timestamp-information)
45 | - [4.2.1.1 cTIM Created timestamp](./chunk_specifications/index.md#4211-ctim-created-timestamp)
46 | - [4.2.1.2 mTIM Modified timestamp](./chunk_specifications/index.md#4212-mtim-modified-timestamp)
47 | - [4.2.1.3 aTIM Accessed timestamp](./chunk_specifications/index.md#4213-atim-accessed-timestamp)
48 | - [4.2.1.4 cTNS Created timestamp (Nanoseconds)](./chunk_specifications/index.md#4214-ctns-created-timestamp-nanoseconds)
49 | - [4.2.1.5 mTNS Modified timestamp (Nanoseconds)](./chunk_specifications/index.md#4215-mtns-modified-timestamp-nanoseconds)
50 | - [4.2.1.6 aTNS Accessed timestamp (Nanoseconds)](./chunk_specifications/index.md#4216-atns-accessed-timestamp-nanoseconds)
51 | - [4.2.2 permission information](./chunk_specifications/index.md#422-permission-information)
52 | - [4.2.2.1 fPRM File permission](./chunk_specifications/index.md#4221-fprm-file-permission)
53 | - [4.2.3 Extended attribute](./chunk_specifications/index.md#423-extended-attribute)
54 | - [4.2.3.1 xATR Extended attribute](./chunk_specifications/index.md#4231-xatr-extended-attribute)
55 | - [4.3. Summary of standard chunks](./chunk_specifications/index.md#43-summary-of-standard-chunks)
56 | - [4.4. Additional chunk types](./chunk_specifications/index.md#44-additional-chunk-types)
57 | - [5. Compression algorithms](./compression_algorithms/index.md)
58 | - [5.1. Deflate](./compression_algorithms/index.md#51-deflate)
59 | - [5.2. ZStandard](./compression_algorithms/index.md#52-zstandard)
60 | - [5.3. LZMA](./compression_algorithms/index.md#53-lzma)
61 | - [6. Cipher algorithms](./cipher_algorithms/index.md)
62 | - [6.1. Rijndael](./cipher_algorithms/index.md#61-rijndael)
63 | - [6.2. Camellia](./cipher_algorithms/index.md#62-camellia)
64 | - [7. Cipher modes](./cipher_modes/index.md)
65 | - [7.1. Cipher Block Chaining Mode (CBC)](./cipher_modes/index.md#71-cipher-block-chaining-mode-cbc)
66 | - [7.2. Counter Mode (CTR)](./cipher_modes/index.md#72-counter-mode-ctr)
67 | - [7.3. Initialization Vector (IV) Placement in Encrypted Streams](./cipher_modes/index.md#73-initialization-vector-iv-placement-in-encrypted-streams)
68 | - [7.3.1 Placement](./cipher_modes/index.md#731-placement)
69 | - [7.3.2 Decoder Behavior](./cipher_modes/index.md#732-decoder-behavior)
70 | - [7.3.3 Encoder Behavior](./cipher_modes/index.md#733-encoder-behavior)
71 | - [8. Key derivation algorithms](./key_derivation_algorithms/index.md)
72 | - [8.1. Password-Based Key Derivation Function 2(PBKDF2)](./key_derivation_algorithms/index.md#81-password-based-key-derivation-function-2pbkdf2)
73 | - [8.2. Argon2](./key_derivation_algorithms/index.md#82-argon2)
74 | - [9. Chunk Ordering Rules](./chunk_ordering_rules/index.md)
75 | - [9.1. Behavior of PNA editors](./chunk_ordering_rules/index.md#91-behavior-of-pna-editors)
76 | - [9.2. Ordering of ancillary chunks](./chunk_ordering_rules/index.md#92-ordering-of-ancillary-chunks)
77 | - [9.3. Ordering of critical chunks](./chunk_ordering_rules/index.md#93-ordering-of-critical-chunks)
78 | - [10. Miscellaneous Topics](./miscellaneous_topics/index.md)
79 | - [10.1. File name extension](./miscellaneous_topics/index.md#101-file-name-extension)
80 | - [10.2. Split file name extension](./miscellaneous_topics/index.md#102-split-file-name-extension)
81 | - [11. Recommendations for Encoders](./recommendations_for_encoders/index.md)
82 | - [11.1. Use of private chunks](./recommendations_for_encoders/index.md#111-use-of-private-chunks)
83 | - [11.2. Private type and method codes](./recommendations_for_encoders/index.md#112-private-type-and-method-codes)
84 | - [12. Recommendations for Decoders](./recommendations_for_decoders/index.md)
85 | - [12.1. Error checking](./recommendations_for_decoders/index.md#121-error-checking)
86 | - [12.2. Text processing](./recommendations_for_decoders/index.md#122-text-processing)
87 | - [13. Glossary](./glossary/index.md)
88 |
--------------------------------------------------------------------------------
/introduction/index.md:
--------------------------------------------------------------------------------
1 | ## 1. Introduction
2 |
3 | The Portable Network Archive (PNA) format provides a portable, compressible, encryptable, splittable, and well-specified standard for archive files.
4 |
5 | TAR features retained in PNA include:
6 |
7 | Streamability: files can be read and written serially, thus allowing the file format to be used as a communications protocol for on-the-fly generation.
8 | Ancillary information: textual comments and other data can be stored within the archive file.
9 | Complete hardware and platform independence.
10 |
11 | ZIP features retained in PNA include:
12 |
13 | Per-file basis: an archive can contain multiple files and each file is stored separately. As a result, each file in a PNA archive can be extracted individually.
14 |
15 | Important new features of PNA, not available in TAR or ZIP, include:
16 |
17 | Support for both per-file compression and archive-wide compression.
18 | In addition, both can be mixed within a single archive, allowing files to be added to the archive efficiently without having to decompress the entire archive.
19 |
20 | PNA is designed to be:
21 |
22 | Simple and portable: Developers should be able to implement PNA easily.
23 | Compressible: Provides flexible compression by supporting multiple compression algorithms. Of course, it also supports uncompressed.
24 | Encryptable: Supports 256-bit AES and 256-bit Camellia with the same encryption strength as 256-bit AES.
25 | Splittable: By using the same data unit as the PNG file, the archive can be easily split.
26 | Interchangeable: any standard-conforming PNA decoder must read all conforming PNA files.
27 | Flexible: The format allows for future extensions and private add-ons, without compromising the interchangeability of basic PNA.
28 | Robust: the design supports full file integrity checking as well as simple, quick detection of common transmission errors.
29 |
30 | The main part of this specification gives the definition of the file format and recommendations for encoder and decoder behavior. An appendix gives the rationale for many design decisions. Although the rationale is not part of the formal specification, reading it can help implementors understand the design. Cross-references in the main text point to relevant parts of the rationale.
31 |
32 | The words "must", "required", "should", "recommended", "may", and "optional" in this document are to be interpreted as described in [RFC-2119](../references/index.md#rfc-2119), which is consistent with their plain English meanings. The word "can" carries the same force as "may".
33 |
--------------------------------------------------------------------------------
/key_derivation_algorithms/index.md:
--------------------------------------------------------------------------------
1 | ## 8. Key derivation algorithms
2 |
3 | ### 8.1. Password-Based Key Derivation Function 2(PBKDF2)
4 |
5 | This section specifies the method for deriving a cryptographic key from a password using the Password-Based Key Derivation Function 2 (PBKDF2). The PBKDF2 algorithm is designed to produce keys that are computationally intensive to derive, thereby providing a defense against attacks such as dictionary attacks and brute force.
6 |
7 | #### 8.1.1 Algorithm Specification
8 |
9 | PBKDF2 applies a pseudorandom function (PRF) to the input password along with a salt value and iterates this process a specified number of times to produce a derived key. The iteration count is a critical security parameter and should be chosen with consideration to the desired level of security and the performance constraints of the system.
10 |
11 | #### 8.1.2 Parameters
12 |
13 | - Password: The secret input value.
14 | - Salt: A sequence of bits, known as a cryptographic salt.
15 | - Iteration Count: A positive integer specifying the number of iterations.
16 | - Derived Key Length: The desired length of the derived key.
17 | - Pseudorandom Function: Typically, a HMAC (Hash-Based Message Authentication Code) is used as the PRF, with a secure hash function such as SHA-256.
18 |
19 | #### 8.1.3 Process
20 |
21 | 1. Initialize a counter to one.
22 | 2. Concatenate the password and salt.
23 | 3. Apply the PRF to the combined password and salt.
24 | 4. Repeat the PRF process for the number of iterations specified.
25 | 5. Output the final block of data as the derived key.
26 |
27 | Further details on the key derivation algorithm are given in the PBKDF2 specification [RFC-2898](../references/index.md#rfc-2898) and PBKDF2 Test Vectors [RFC-6070](../references/index.md#rfc-6070)
28 |
29 | #### 8.1.4 Security Considerations
30 |
31 | The security of PBKDF2 is directly related to the number of iterations, the strength of the PRF, and the length and randomness of the salt. It is recommended to use a salt that is unique to each derivation process to prevent the use of precomputed tables for deriving keys.
32 |
33 | #### 8.1.5 Recommendations
34 |
35 | As per [NIST SP 800-132](../references/index.md#nist-sp-800-132), it is recommended to use at least 10,000 iterations for PBKDF2 when deriving keys for non-interactive applications. However, this value should be increased as computational power advances to ensure the security of the derived keys.
36 |
37 | ### 8.2. Argon2
38 |
39 | This section delineates the methodology for deriving cryptographic keys via the memory-hard key derivation function, Argon2. Recognized as the winner of the Password Hashing Competition in 2015, Argon2 is engineered to resist attacks from both specialized hardware and parallel computing, making it a robust choice for password hashing and key derivation.
40 |
41 | #### 8.2.1 Algorithm Specification
42 |
43 | Argon2 is a high-level key derivation function that operates with three distinct variants: Argon2d, Argon2i, and Argon2id, each tailored for different security applications. The function utilizes a large memory size, parallelism, and a variable number of iterations to thwart off-line brute-force attacks.
44 |
45 | #### 8.2.2 Parameters
46 |
47 | Memory Size: The amount of memory used by the algorithm.
48 | Iterations: The number of iterations the function is to perform.
49 | Parallelism: The number of threads and lanes that the algorithm utilizes.
50 | Salt: A unique sequence of bytes used as an input to the hash function.
51 | Tag Length: The desired length of the output key.
52 | Secret Value: An optional secret value that can be used as a key for HMAC when generating the hash.
53 |
54 | #### 8.2.3 Process
55 |
56 | Assign the memory to a matrix of blocks.
57 | Fill the matrix with hashes derived from the password, salt, and optional secret.
58 | Perform the specified number of iterations, mixing the blocks both within and between threads.
59 | Extract the tag of the requested length as the output of the function.
60 |
61 | Further details on the key derivation algorithm are given in the [argon2 specification](../references/index.md#argon2) and [RFC-9106](../references/index.md#rfc-9106)
62 |
63 | #### 8.2.4 Security Considerations
64 |
65 | The selection between Argon2d, Argon2i, and Argon2id should be made according to the threat model:
66 |
67 | Argon2d maximizes resistance to GPU cracking attacks and is suitable for cryptocurrencies and applications without a threat from side-channel attacks.
68 | Argon2i is optimized to resist side-channel attacks and is preferable for password hashing and key derivation where the input is not secret.
69 | Argon2id is a hybrid that combines the resistance to side-channel attacks of Argon2i with the GPU cracking resistance of Argon2d, suitable for applications that require a balance of both.
70 |
71 | #### 8.2.5 Recommendations
72 |
73 | As per current best practices, it is advised to allocate as much memory as is practical for the application and at least two iterations. The parallelism should be set according to the number of available processor cores. The salt should be a unique, cryptographically secure random value for each password.
74 |
--------------------------------------------------------------------------------
/miscellaneous_topics/index.md:
--------------------------------------------------------------------------------
1 | ## 10. Miscellaneous Topics
2 |
3 | ### 10.1. File name extension
4 |
5 | On systems where file names customarily include an extension signifying file type, the extension ".pna" is recommended for PNA files. Lowercase ".pna" is preferred if file names are case-sensitive.
6 |
7 | ### 10.2. Split file name extension
8 |
9 | If PNA archive is split, to facilitate determining the order, insert ".part[n]" before the extension is recommended. The "[n]" part starts from 1 and increases by 1 each time it is split. For example, when an archive is split into two, it will be ".part1.pna" and "part2.pna". On systems where file names customarily do not include an extension signifying file type, It is recommended to use this instead of the extension. Lowercase is preferred if file names are case-sensitive.
10 |
--------------------------------------------------------------------------------
/recommendations_for_decoders/index.md:
--------------------------------------------------------------------------------
1 | ## 12. Recommendations for Decoders
2 |
3 | This chapter gives some recommendations for decoder behavior. The only absolute requirement on a PNA decoder is that it successfully reads any file conforming to the format specified in the preceding chapters. However, best results will usually be achieved by following these recommendations.
4 |
5 | ### 12.1. Error checking
6 |
7 | To ensure early detection of common file-transfer problems, decoders should verify that all eight bytes of the PNA file signature are correct. (See Rationale: [PNA file signature](../file_structure/index.md#31-pna-file-signature).) A decoder can have additional confidence in the file's integrity if the next eight bytes are an IHDR chunk header with the correct chunk length.
8 |
9 | Unknown chunk types must be handled as described in [Chunk naming conventions](../file_structure/index.md#36-chunk-naming-conventions). An unknown chunk type is not to be treated as an error unless it is a critical chunk.
10 |
11 | It is strongly recommended that decoders should verify the CRC on each chunk.
12 |
13 | In some situations, it is desirable to check chunk headers (length and type code) before reading the chunk data and CRC. The chunk type can be checked for plausibility by seeing whether all four bytes are ASCII letters (codes 65-90 and 97-122); note that this needs to be done only for unrecognized type codes. If the total file size is known (from file system information, HTTP protocol, etc), the chunk length can be checked for plausibility as well.
14 |
15 | For known-length chunks such as AHED, decoders should treat an unexpected chunk length as an error. Future extensions to this specification will not add new fields to existing chunks; instead, new chunk types will be added to carry new information.
16 |
17 | Unexpected values in fields of known chunks (for example, an unexpected compression method in the FHED chunk) must be checked for and treated as errors. However, it is recommended that unexpected field values be treated as fatal errors only in critical chunks. An unexpected value in an ancillary chunk can be handled by ignoring the whole chunk as though it were an unknown chunk type. (This recommendation assumes that the chunk's CRC has been verified. In decoders that do not check CRCs, it is safer to treat any unexpected value as indicating a corrupted file.)
18 |
19 | ### 12.2. Text processing
20 |
21 | If practical, decoders should have a way to display to the user all text found in the file. Even if the decoder does not recognize a particular text keyword, the user might be able to understand it.
22 |
23 | If there are no specific instructions, text is assumed to be represented in UTF-8 without a BOM, but decoders should not rely on this. Decoders should always verify whether the text is UTF-8 encoded, considering the possibility that it might not be.
24 |
--------------------------------------------------------------------------------
/recommendations_for_encoders/index.md:
--------------------------------------------------------------------------------
1 | ## 11. Recommendations for Encoders
2 |
3 | This chapter gives some recommendations for encoder behavior. The only absolute requirement on a PNA encoder is that it produce files that conform to the format specified in the preceding chapters. However, best results will usually be achieved by following these recommendations.
4 |
5 | ### 11.1. Use of private chunks
6 |
7 | Applications can use PNA private chunks to carry information that need not be understood by other applications. Such chunks must be given names with lowercase second letters, to ensure that they can never conflict with any future public chunk definition. Note, however, that there is no guarantee that some other application will not use the same private chunk name. If you use a private chunk type, it is prudent to store additional identifying information at the beginning of the chunk data.
8 |
9 | Use an ancillary chunk type (lowercase first letter), not a critical chunk type, for all private chunks that store information that is not absolutely essential to read the archive. Creation of private critical chunks is discouraged because they render PNA files unportable. Such chunks should not be used in publicly available software or files. If private critical chunks are essential for your application, it is recommended that one appear near the start of the file, so that a standard decoder need not read very far before discovering that it cannot handle the file.
10 |
11 | If you want others outside your organization to understand a chunk type that you invent, contact the maintainers of the PNA specification to submit a proposed chunk name and definition for addition to the list of special-purpose public chunks (see [Additional chunk types](../chunk_specifications/index.md#44-additional-chunk-types)). Note that a proposed public chunk name (with uppercase second letter) must not be used in publicly available software or files until registration has been approved.
12 |
13 | If an ancillary chunk contains textual information that might be of interest to a human user, you should **not** create a special chunk type for it. Instead use a text chunk and define a suitable keyword. That way, the information will be available to users not using your software.
14 |
15 | Keywords in text chunks should be reasonably self-explanatory, since the idea is to let other users figure out what the chunk contains. If of general usefulness, new keywords can be registered with the maintainers of the PNA specification. But it is permissible to use keywords without registering them first.
16 |
17 | ### 11.2. Private type and method codes
18 |
19 | This specification defines the meaning of only some of the possible values of some fields. For example, only compression method 0 through 4, encryption method 0 through 3 and cipher mode 0 through 1 are defined. Numbers greater than 63 must be used when inventing experimental or private definitions of values for any of these fields. Numbers below 64 are reserved for possible future public extensions of this specification. Note that use of private type codes may render a file unreadable by standard decoders. Such codes are strongly discouraged except for experimental purposes, and should not appear in publicly available software or files.
20 |
--------------------------------------------------------------------------------
/references/index.md:
--------------------------------------------------------------------------------
1 | ## References
2 |
3 | ### **[RFC-1950]**
4 | Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format Specification version 3.3", RFC 1950, Aladdin Enterprises, May 1996.
5 | [ftp://ftp.isi.edu/in-notes/rfc1950.txt](ftp://ftp.isi.edu/in-notes/rfc1950.txt)
6 |
7 | ### **[RFC-1951]**
8 | Deutsch, P., "DEFLATE Compressed Data Format Specification version 1.3", RFC 1951, Aladdin Enterprises, May 1996.
9 | [ftp://ftp.isi.edu/in-notes/rfc1951.txt](ftp://ftp.isi.edu/in-notes/rfc1951.txt)
10 |
11 | ### **[RFC-8878]**
12 | Y. Collet and M. Kucherawy, Ed. "Zstandard Compression and the 'application/zstd' Media Type" RFC 8878, Facebook, February 2021.
13 | [https://tools.ietf.org/html/rfc8878](https://tools.ietf.org/html/rfc8878)
14 |
15 | ### **[RFC-2119]**
16 |
17 | Bradner, Scott, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997.
18 | [ftp://ftp.isi.edu/in-notes/rfc2119.txt](ftp://ftp.isi.edu/in-notes/rfc2119.txt)
19 |
20 | ### **[ISO-3309]**
21 |
22 | International Organization for Standardization, "Information Processing Systems--Data Communication High-Level Data Link Control Procedure--Frame Structure", IS 3309, October 1984, 3rd Edition.
23 |
24 | ### **[ITU-T-V42]**
25 |
26 | International Telecommunications Union, "Error-correcting Procedures for DCEs Using Asynchronous-to-Synchronous Conversion", ITU-T Recommendation V.42, 1994, Rev. 1.
27 |
28 | ### **[MODES]**
29 | Dworkin, M., "Recommendation for Block Cipher Modes of Operation: Methods and Techniques," NIST Special Publication 800-38A, December 2001.
30 | [http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf](http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf)
31 |
32 | ### **[CRYPTO-S]**
33 | B. Schneier, "Applied Cryptography Second Edition", John Wiley & Sons, New York, NY, 1995, ISBN 0-471-12845-7.
34 |
35 | ### **[NIST SP 800-132]**
36 | National Institute of Standards and Technology, "Recommendation for Password-Based Key Derivation - Part 1: Storage Applications", NIST SP 800-132, December 2010.
37 | [http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf](http://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-132.pdf)
38 |
39 | ## **[RFC-2898]**
40 | Kaliski, B., "PKCS #5: Password-Based Cryptography Specification Version 2.0", RFC 2898, RSA Laboratories, September 2000.
41 | [https://tools.ietf.org/html/rfc2898](https://tools.ietf.org/html/rfc2898)
42 |
43 | ## **[RFC-6070]**
44 | Hoffman, P., and J. Schaad, "PKCS #5: Password-Based Key Derivation Function 2 (PBKDF2) Test Vectors", RFC 6070, SJD AB, January 2011.
45 | [https://tools.ietf.org/html/rfc6070](https://tools.ietf.org/html/rfc6070)
46 |
47 | ## **[Argon2]**
48 | Alex Biryukov, Daniel Dinu, and Dmitry Khovratovich University of Luxembourg, Luxembourg, "Argon2: the memory-hard function for password hashing and other applications,", 2015.
49 | [https://www.cryptolux.org/images/0/0d/Argon2.pdf](https://www.cryptolux.org/images/0/0d/Argon2.pdf)
50 |
51 | ## **[RFC-9106]**
52 | A. Biryukov University of Luxembourg, D. Dinu University of Luxembourg, D. Khovratovich ABDK Consulting, S. Josefsson SJD AB, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, September 2021.
53 | [https://tools.ietf.org/html/rfc9106](https://tools.ietf.org/html/rfc9106)
54 |
--------------------------------------------------------------------------------