File Format of Styles - jonelo/jacksum GitHub Wiki
This article documents the style file format for Jacksum. Styles are files and some are bundled with Jacksum to specify the compatibility behavior of Jacksum for both input format and output format. Styles can be created by the user as well.
A style is basically a plain text property file with many pairs of keys and values. Each key and its corresponding value in the property list is a string.
A style must be stored using the UTF-8 character encoding. The fileformat of styles is subject to change.
Any line that begins with a pound sign (#) is considered a comment and ignored.
Empty lines are ignored.
Those properties allow you to describe the style.
Specifies the syntax version of the file. Value must be an integer. This value identifies the version of the file format being used, not necessarily the version of the Jacksum program. The current version of the syntax is 3.
The version of the style itself. It should be an integer, expressed as YYYYMMDD.
A short name of the style.
A short description of the style.
A list of authors of the style.
Properties that has to do with the algorithm.
A string that must be a valid algorithm id supported by Jacksum. The default algorithm used if no algorithm has been specified by the user.
Values can be true or false.
If the value is set to true, the user can specify the algorithm. If the value is set to false, the user is not allowed to specify the algorithm. Only the default algorithm is possible.
Those properties describe the values for the input format. In other words it describes the parser which is used if you want to read check files using Jacksum.
A string. Any lines starting with that string are ignored.
Values can be true or false. If the value is set to true, empty lines are ignored.
A regular expression that describe each data line of the style. The token called #NIBBLES is being replaced before the regexp is evaluated.
Example: ^([\\\\]?)([^ ]+) \\((.+)\\) = ([a-z0-9]{#NIBBLES})$
An optional value, an integer. Describes the position of the GNU escaping character in the regular expresion.
An optional value, an integer. Describes the position of the algorithm name in the regular expression.
An integer. Describes the position of the file path/name in the regular expression.
An optional value, an intgeger. Describes the position of the hash value in the regular expression.
An optional value, an integer. Sets the number of nibbles. That value is replaced in the parser.regexp value.
Those properties describe the values for the output format.
The format of each data line. See option -F.
The encoding for the hash values. See option -E.
The line separator to be used for the check file, usually \n if compatibility is required for Linux styles.
Values can be true or false.
Values can be true or false.
Specifies whether the user can enable or disable GNU escaping.
if #ALGONAME is part of the value specified at the key formatter.format, we can adjust the replacement behavior.
Example: #ALGONAME{uppercase}
$ skein512 foobar
# on BSD the algorithm name is being returned as Skein with an uppercase S
Skein512 (foobar) = 5c9ab7...
# but
$ md5 foobar
# returns the algorithm name entirely in uppercase
MD5 (foobar) = 3749...
# so we need to define some exceptions ...
A string containing keys and values, delimited by a =, and separated by a ; to specify a mapping between the primary ID of the algorithm and the actual name of the original program.
The following style describes the format of hash tools on BSD.
compat.syntaxVersion=3
compat.version=20220403
compat.name=BSD (Berkeley Software Distribution), default (tagged) format
compat.description=Parser and formatter for compatibility with hash tools on macOS and BSD systems (e.g. md5, sha1)
compat.authors=Johann N. Löfflmann <https://johann.loefflmann.net>
algorithm.default=sha3-256
algorithm.userSelectable=true
parser.ignoreLinesStartingWithString=#
parser.ignoreEmptyLines=false
parser.regexp=^([\\\\]?)([^ ]+) \\((.+)\\) = ([a-z0-9]{#NIBBLES})$
parser.regexp.gnuEscapingPos=1
parser.regexp.algonamePos=2
parser.regexp.filenamePos=3
parser.regexp.hashPos=4
parser.regexp.nibbles=64
formatter.format=#ESCAPETAG#ALGONAME (#FILENAME) = #CHECKSUM{hex}
formatter.hash.encoding=hex
formatter.lineSeparator=\n
formatter.gnuescaping.enabled=true
formatter.gnuescaping.userSelectable=true
# > skein512 foobar
# returns on BSDs the algorithm name Skein with an uppercase S
# Skein512 (foobar) = 5c9ab7...
# but
# > md5 foobar
# returns the algorithm name entirely in uppercase
# MD5 (foobar) = 3749...
# so we have to define some exceptions here
formatter.ALGONAME.defaultReplacement=#ALGONAME{uppercase}
formatter.ALGONAME.exceptionMappings=\
sha-512/224=SHA512t224;\
sha-512/256=SHA512t256;\
skein-256-256=Skein256;\
skein-512-512=Skein512;\
skein-1024-1024=Skein1024
> jacksum --style bsd g*.txt
SHA3-256 (gpl-3.0.txt) = edb0016d9f8bafb54540da34f05a8d510de8114488f23916276bdead05509a53
> jacksum --style bsd g*.txt > hashes.sha3
> jacksum --style bsd -c hashes.sha3 *.txt
Jacksum: Info: Option --compat/--style has been set, setting implicitly -a sha3-256 -E hex, stdin-name=<stdin>
OK gpl-3.0.txt
Jacksum: total lines in check file: 1
Jacksum: improperly formatted lines in check file: 0
Jacksum: properly formatted lines in check file: 1
Jacksum: ignored lines (empty lines and comments): 0
Jacksum: correctness of check file: 100.00 %
Jacksum: matches (OK): 1
Jacksum: mismatches (FAILED): 0
Jacksum: new files (NEW): 0
Jacksum: missing files (MISSING): 0
Jacksum: strict check: PASSED
Jacksum: total files read successfully: 1
Jacksum: total bytes read: 35149
Jacksum: total bytes read (human readable): 34 KiB, 333 bytes
Jacksum: total file read errors: 0
Jacksum: elapsed time: 207 ms
>