NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

One of the following options must be used:

-c

Creates an archive

--create

Synonym for -c

-t

Lists the contents of an archive

--list

Synonym for -t

-x

Extracts an archive

--extract

Synonym for -x

--sign

Creates a placeholder signature and saves the data to sign to disk. Works with -c or just -f, requires --sig-size and one or more --cert-loc options to be set. Setting the --data-to-sign and/or --sig-offset option is optional.

--replace-sign

Rips out existing signature(s) and makes a new one. Same required options as --sign, but only works with -f.

--extract-data-to-sign

Extracts data to be signed from an existing archive. Requires --data-to-sign (and -f) options to be set. Setting the --sig-offset option is optional.

--extract-certs=<directory>

Extracts all certificates into DER (binary) format into the specified directory naming them "cert00", "cert01" etc. The specified directory must already exist. "cert00" is always the leaf certificate. "cert01", "cert02", etc. are only written if the xar file contains a certificate chain (i.e. more than the leaf signing certificate). Any pre-existing files in the specified directory of the same name as the certificates being written will be overwritten without warning.

--extract-CAfile=<filename>

Extracts all certificates into PEM format, concatenates them together and stores the result into the specified file.

--extract-sig=<filename>

Extracts the signature and stores it into the specified file. Setting the --sig-offset option is optional.

--inject-sig=<filename>

After extracting the data to be signed and doing the signing externally, injects the signature. No attempt is made to verify that the signature being injected is valid other than that it has the correct length as previously reserved with the --sig-size option.

NOTE: all of the above require the use of the -f option (filename) as this release of xar doesn't correctly handle pipes or sockets.

-f <file>

The filename to use for creation, listing, extraction or signing operations. With extraction, this can be a POSIX regular expression.

--file=<file>

Synonym for -f <file>

OPTIONS

--compression=<type>

Specifies the compression type to use. Valid values: none, gzip, bzip2, lzma, xz. Default value: gzip

-a

Synonym for --compression=lzma

-j

Synonym for --compression=bzip2

-z

Synonym for --compression=gzip (Default)

--compression-args=<arguments>

Specifies arguments to the compression engine selected. gzip, bzip2, and lzma all take a single integer argument between 0 and 9 specifying the compression level to use.

--rfc6713

Only affects --compression=gzip. Force gzip compression to use "application/zlib" as the encoding style name instead of "application/x-gzip". As of RFC 6713 this is the correct name to use for the actual compressed data format being stored in the archive. This option will automatically be forced on by the xar library if a --toc-cksum value other than "none", "md5" or "sha1" is in effect. Older xar versions will be unable to extract files using this encoding (and neither will they understand --toc-cksum values other than "none", "md5" or "sha1"). See http://tools.ietf.org/html/rfc6713 for details.

-C <path>

On archive or extract, xar will chdir to the specified path before processing archive members being archived or extracted.

--directory=<path>

Synonym for -C <path>

--dump-toc=<filename>

Has xar dump the XML header into the specified file. "-" can be specified to indicate stdout.

-d <filename>

Synonym for --dump-toc=<filename>

--dump-toc-raw=<filename>

Has xar dump the raw, compressed XML header data into the specified file.

--dump-header

Has xar print out the xar binary header information to stdout.

--extract-subdoc=<name>

Extracts the specified subdocument to a document in cwd named <name>.xml

--list-subdocs

List the subdocuments in the XML header

--toc-cksum

Specifies the hashing algorithm to use for XML header verification. Valid values: none, sha1, and md5. If the linked libcrypto library supports them sha224, sha256, sha384 and sha512 may also be used. Setting this option to a stronger hash than the default will also cause --file-cksum to be set to that hash unless it's been explicitly set to something else. Default value: sha1

--file-cksum

Specifies the hashing algorithm to use for file verification. Same values and defaults as --toc-cksum. Setting this option to a stronger hash than the default will also cause --toc-cksum to be set to that hash unless it's been explicitly set to something else.

-l

On archival, stay on the local device.

--one-file-system

Synonym for -l

-P

On extract, set ownership based on uid/gid. If the uid/gid can be set on the extracted file, setuid/setgid bits will also be preserved.

-p

On extract, set ownership based on symbolic names, if possible. If the uid/gid can be set on the extracted file, setuid/setgid bits will also be preserved.

-n <name>

On archival, specifies the subdocument name to use when adding the -s <filename> subdocument instead of the default name "subdoc".

-s <filename>

On extract, specifies the file to extract subdocuments to. On archival, specifies an XML file to add as a subdocument.

-v

Verbose output

--verbose

Synonym for -v

--exclude=<regexp>

Specifies a POSIX basic regular expression of files to exclude from adding to the archive during creation or from being extracted during extraction. This option can be specified multiple times.

--strip-components=<n>

When extracting, strip <n> path components from the front of the path before creating the destination file. If the item being extracted does not have enough path components to strip <n> off then it will be skipped and not extracted.

--to-stdout

Instead of creating files during extraction, write the file contents to standard output. Only the file data will be written to standard output. All extended attributes, resource forks and other file properties are ignored with this option.

-O

Synonym for --to-stdout

--rsize

Specifies a size (in bytes) for the internal libxar read buffer while performing I/O.

--coalesce-heap

When multiple files in the archive are identical, only store one copy of the data in the heap. This creates smaller archives, but the archives created are not streamable.

--link-same

When the data section of multiple files are identical, hardlink them within the archive.

--recompress

Normally archived files that are already compressed in a recogized format will be archived but not compressed (as though they matched a --no-compress expression). If this option is set then recompression of these files will be allowed (unless they match an explicit --no-compress expression).

--no-compress

Specifies a POSIX regular expression of files to archive, but not compress. The archived files will be copied raw into the archive. This can be used to exclude already gzipped files from being gzipped during the archival process when using --recompress or unrecognized-by-xar compressed formats. This option can be used multiple times.

--prop-include=<propname>

Specifies a file property to be included in the archive. When this option is specified, only the specified options will be included. Anything not specifically included with this option will be omitted. This option can be used multiple times.

--prop-exclude=<propname>

Specifies a file property to be excluded from the archive. When this option is specified, all file properties will be included except the specified properties. Note that excluding the "ea" property will exclude all extended attributes (including OS X's resource fork). This option can be used multiple times.

--distribution

Creates an archive to only contain file properties safe for file distribution. Currently, only name, type, mode, and data are preserved with this option.

--keep-existing

Does not overwrite existing files during extraction. Keeps any previously existing files while extracting.

-k

Synonym for --keep-existing.

--keep-setuid

When extracting without -p or -P options, xar will extract files as the uid/gid of the extracting process. In this situation, xar will strip setuid/setgid bits from the extracted files for security reasons. --keep-setuid will preserve the setuid/setgid bits even though the uid/gid of the extracted file is not the same as the archived file.

--sig-size=<n>

Specifies the size in bytes of the signature placeholder to generate when using the --sign or --replace-sign options.

--sig-len=<n>

Synonym for --sig-size=<n>.

--data-to-sign=<file>

Has xar dump the raw data to be signed to the specified file. This is simply the raw binary bytes of the --toc-cksum hash of the raw, compressed XML header data. Requires a --toc-cksum value other than "none". When generating a signature, this raw hash value must first have the proper DigestInfo prefix added to it (see RFC 3447 sections 9.2, A.2.4 and B.1). The --digestinfo-to-sign option automatically adds the appropriate prefix and should normally be used instead of this option.

--digestinfo-to-sign=<file>

Has xar dump the DigestInfo data to be signed to the specified file. This is simply the raw binary bytes of the --toc-cksum hash of the raw, compressed XML header data preceded by the appropriate DigestInfo prefix (see RFC 3447 sections 9.2, A.2.4 and B.1). Requires a --toc-cksum value of "md5", "sha1" (the default), "sha224", "sha256", "sha384" or "sha512".

--sig-offset=<file>

Has xar dump the signature's byte offset within the archive (as an ASCII decimal number) to the specified file. Always optional.

--cert-loc=<filename>

Specifies the location of a signing certificate in DER format to include in the archive. This option can be used multiple times to include a certificate chain. The first --cert-loc option should specify the leaf signing certificate, the next its issuer CA and so on so that the last --cert-loc= option specifies the root certificate authority for the chain. --leaf-cert-loc=<filename> and --intermediate-cert-loc=<filename> are accepted as synonyms for --cert-loc= for historical reasons.

--help

Show a help summary.

-h

Synonym for --help

-V

Synonym for --version

--version

Display the version number of xar. If --verbose is given before --version show additional version information.

TIPS

xar --replace-sign --sig-size=0 -f sample.xar

EXAMPLES

xar -cf sample.xar /home/uid

xar -tf sample.xar

xar -xf sample.xar

xar -cf sample.xar --toc-cksum=whirlpool! \
--file-cksum=whirlpool! /home/uid

SIGNING

The example here assumes the DER format certificates from leaf to root are available in the files

and the leaf.crt private key is available in PEM format in the file key.pem. Also the archive to be signed is archive.xar and the openssl and wc utility commands are available. The example commands are for an sh-compatible shell.

1. Determine the signature size

2. Extract the value to be signed and insert the certificates

3. Create the RSA signature

4. Inject the RSA signature

Step 1 simply places the size in bytes as an ASCII decimal number into the file siglen.txt. For any given specific RSA private key, this step only needs to be done once as the length is determined by key characteristics such as bit length, signing algorithm etc. that are independent of the data being signed.

Step 2, despite the name of the --sign option, only reserves space for the signature to be injected in step 4, inserts the certificates and extracts the DigestInfo to be signed. It does not create a valid signature.

Step 3 actually creates the signature using the openssl tool.

Step 4 inserts the real signature into the archive that previously had space reserved for it. This final step creates a signed archive.

Note that whenever the archive data changes steps 2-4 must be repeated. Repeating some or none of those steps will result in an invalid signature. Furthermore, xar makes no attempt to verify that the injected signature is compatible with the leaf signing certificate (the first --cert-loc option). For example, if the --toc-cksum type is "sha1" (the default) then the leaf signing certificate's signature algorithm must be "sha1WithRSAEncryption" in order for the resulting xar archive to have a valid signature.

More details on signing can be found at:

BUGS

Doesn't currently work with pipes or streams. Might be fixed in a future release.

Signature support is clumsy and requires multiple steps and use of external tools.

Should default to SHA-256 checksums if supported by the linked library but currently does not for backwards compatibility.

The formatting in this man page is suboptimal.

The option to use any available EVP_get_digestbyname hash for --toc-cksum and/or --file-cksum by simply appending an ! to its name remains mostly undocumented.

Probably one or two more in there somewhere. If you find one please report it to:

AUTHORS