add XAR header format (#473)

* add XAR format

* xar: document variations, add support for versions with
checksum_algorithm field 3 created with the XAR archiver referenced in
the doc-ref

* xar: differentiate between the regular header and the apple header
(probably misnomers)

* xar: use correct variable

* xar: rename from `xar_header`

* xar: add `/meta/xref/justsolve`

* xar: restructure (`header` to substream), provide cksum alg name

* xar: change `/meta/title`

* xar: improve sentence in `/doc`

* xar: update Apple Open Source GitHub mirror link

* xar: remove sentence from `/doc`, add link to Wikipedia

* xar: move "xar" file extension above "pkg"

See #473 (comment)

* xar: change "read" to "access" to avoid confusion

Co-authored-by: Petr Pucil <[email protected]>

archive/xar.ksy

@@ -0,0 +1,120 @@
+meta:
+  id: xar
+  title: XAR (eXtensible ARchive)
+  file-extension:
+    - xar
+    - pkg
+    - xip
+  xref:
+    justsolve: Xar_(Extensible_Archive)
+    mime: application/x-xar
+    pronom: fmt/600
+    wikidata: Q1093556
+  license: CC0-1.0
+  ks-version: 0.9
+  encoding: UTF-8
+  endian: be
+doc: |
+  From [Wikipedia](https://en.wikipedia.org/wiki/Xar_(archiver)):
+
+  "XAR (short for eXtensible ARchive format) is an open source file archiver
+  and the archiver’s file format. It was created within the OpenDarwin project
+  and is used in macOS X 10.5 and up for software installation routines, as
+  well as browser extensions in Safari 5.0 and up."
+doc-ref: https://github.com/mackyle/xar/wiki/xarformat
+seq:
+  - id: header_prefix
+    type: file_header_prefix
+    doc: internal; access `_root.header` instead
+  - id: header
+    size: header_prefix.len_header - header_prefix._sizeof
+    type: file_header
+  - id: toc
+    size: header.len_toc_compressed
+    type: toc_type
+    process: zlib
+    doc: zlib compressed XML further describing the content of the archive
+instances:
+  checksum_algorithm_other:
+    -orig-id: XAR_CKSUM_OTHER
+    value: 3
+    doc-ref: https://github.com/mackyle/xar/blob/66d451d/xar/include/xar.h.in#L85
+types:
+  file_header_prefix:
+    seq:
+      - id: magic
+        contents: 'xar!'
+      - id: len_header
+        type: u2
+        doc: internal; access `_root.header.len_header` instead
+  file_header:
+    seq:
+      - id: version
+        type: u2
+        valid: 1
+      - id: len_toc_compressed
+        -orig-id: toc_length_compressed
+        type: u8
+      - id: toc_length_uncompressed
+        type: u8
+      - id: checksum_algorithm_int
+        type: u4
+        doc: internal; access `checksum_algorithm_name` instead
+      - id: checksum_alg_name
+        size-eos: true
+        type: strz
+        valid:
+          expr: _ != "" and _ != "none"
+        if: has_checksum_alg_name
+        doc: internal; access `checksum_algorithm_name` instead
+    instances:
+      checksum_algorithm_name:
+        value: |
+          has_checksum_alg_name ? checksum_alg_name
+          : checksum_algorithm_int == checksum_algorithms_apple::none.to_i ? "none"
+          : checksum_algorithm_int == checksum_algorithms_apple::sha1.to_i ? "sha1"
+          : checksum_algorithm_int == checksum_algorithms_apple::md5.to_i ? "md5"
+          : checksum_algorithm_int == checksum_algorithms_apple::sha256.to_i ? "sha256"
+          : checksum_algorithm_int == checksum_algorithms_apple::sha512.to_i ? "sha512"
+          : ""
+        doc: |
+          If it is not
+
+          * `""` (empty string), indicating an unknown integer value (access
+            `checksum_algorithm_int` for debugging purposes to find out
+            what that value is), or
+          * `"none"`, indicating that the TOC checksum is not provided (in that
+            case, the `<checksum>` property or its `style` attribute should be
+            missing, or the `style` attribute must be set to `"none"`),
+
+          it must exactly match the `style` attribute value of the
+          `<checksum>` property in the root node `<toc>`. See
+          <https://github.com/mackyle/xar/blob/66d451d/xar/lib/archive.c#L345-L371>
+          for reference.
+
+          The `xar` (eXtensible ARchiver) program [uses OpenSSL's function
+          `EVP_get_digestbyname`](
+            https://github.com/mackyle/xar/blob/66d451d/xar/lib/archive.c#L328
+          ) to verify this value (if it's not `""` or `"none"`, of course).
+          So it's reasonable to assume that this can only have one of the values
+          that OpenSSL recognizes.
+      has_checksum_alg_name:
+        value: |
+          checksum_algorithm_int == _root.checksum_algorithm_other
+          and len_header >= 32
+          and len_header % 4 == 0
+      len_header:
+        value: _root.header_prefix.len_header
+  toc_type:
+    seq:
+      - id: xml_string
+        type: str
+        size-eos: true
+enums:
+  # https://github.com/apple-opensource/xar/blob/03d10ac/xar/include/xar.h.in#L67-L73
+  checksum_algorithms_apple:
+    0: none
+    1: sha1
+    2: md5
+    3: sha256
+    4: sha512