X-Git-Url: http://www.git.stargrave.org/?a=blobdiff_plain;f=HASHES;fp=HASHES;h=3198147b5f051f56488a22163c66cedd62acfd8b;hb=be69a4fc0c240c2772a0f0bf0955b39783e4c48a;hp=0000000000000000000000000000000000000000;hpb=ce902a58a32f42801603475c67dd75da86d4502a;p=meta4ra.git

diff --git a/HASHES b/HASHES
new file mode 100644
index 0000000..3198147
--- /dev/null
+++ b/HASHES
@@ -0,0 +1,62 @@
+There are plenty of possible hashing algorithms in use. Some are forced
+by standards, some are faster on hardware, some on 64-bit CPUs, some are
+relatively new. So there is no single algorithm that will satisfy you in
+every situation. That is why, Metalink4 files can contain many choices
+of the hashes.
+
+Various utilities, various versions, various OS distributions have
+different set of available/better options. That is why meta4ra-create
+and meta4ra-check utilities have -hashes option, where you specify set
+of supported algorithms and command line to run for their calculation.
+-hashes is comma-separated list of colon-separated "name:cmdline" pairs.
+    -hashes "skein-512:skein512,sha512:libressl dgst -sha512"
+option tells, that for calculation of Skein-512 you have to run skein512
+command, and for SHA2-512 "libressl ..." one. They are invoked under
+"/bin/sh -e -c" command, so pipelines are also allowable there. Data is
+fed to their stdout and they are expected to print hash value in
+hexadecimal form as a first (or single) column to stdout. First found
+common algorithm is used by default for file verification in
+meta4ra-check utility, so order in -hashes is important.
+
+meta4ra-hashes-detect utility conveniently checks various predefined
+known commands and outputs -hashes-compatible string for your system.
+
+If you use "builtin" word as a command, then builtin implementation of
+the hash will be used. By default, meta4ra does not require any
+non-standard library dependencies, so it includes only SHA2-256 and
+SHA2-512. Optionally you can run build-with-thirdparty script to enable
+building with third-party libraries, including much more other hashes.
+
+Only a few hashes are standardised:
+https://www.iana.org/assignments/hash-function-text-names/hash-function-text-names.xhtml
+But meta4ra uses more of advanced and performant ones. They are listed
+below in order of preference.
+
+* blake3-256
+  Ultimately fast hash, still considered cryptographically secure.
+  Out-of-box Merkle-tree gives ability to indefinitely parallelise for
+  >1KiB blocks. It runs faster than either MD5 or hardware-accelerated
+  SHA2-256. Runs several times faster with AVX512. It is reduced round
+  BLAKE2s.
+* blake2b-512, blake2b-256
+  Very fast hash, pretty widespread as a SHA2 replacement.
+  Both of its 512/256-bit variants are often met.
+  It is reduced round BLAKE, that was among SHA3 finalists.
+* skein-512
+  Skein is fastest software hash among all SHA3 finalists, with huge
+  security margin.
+* shake128, shake256
+  SHAKE is the officially recommended SHA3 mode of operation for general
+  usage. SHAKE256 as fast as software SHA2-512 with the comparable
+  security level. Can be very fast on specialised hardware.
+* sha-512, sha-256
+  SHA2 is rather slow, but has widespread availability. 512-bit version
+  version runs faster on 64-bit CPUs. However modern CPUs have hardware
+  accelerated SHA2-256, making it slower only than BLAKE3
+* streebog-512, streebog-256
+  Russian Federation's government standard for hashing. Both versions
+  have identical speed, so 512-bit is preferred.
+* xxh3-128
+  XXH3 is not a cryptographically secure hash (that is why it is at the
+  very end of the list), but 128-bit output with the speed of RAM makes
+  it also useful for integrity checking