Skip to content

Latest commit

 

History

History
330 lines (207 loc) · 10.1 KB

ankh.md

File metadata and controls

330 lines (207 loc) · 10.1 KB
Raw
[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

NAME

ankh - Ankh - API

Table Of Contents

SYNOPSIS

package require Tcl 8.6 9
package require ankh ?1.0?

ak hash version
ak hash list
ak hash HASH channel channel ?options?
ak hash HASH path path ?options?
ak hash HASH string string ?options?
ak hash HASH size
ak hash HASH references

DESCRIPTION

Welcome to Ankh, Andreas Kupries' Hashes.

This document is the reference manpage for the publicly visible API, i.e. the API a user will see, and use.

Global operations

  • ak hash version

    This command returns a string containing the version number of the Ankh package.

  • ak hash list

    This command returns a list containing the names of all the hashes supported by the Ankh package. The names are returned in dictionary order.

Hash commands

Each supported hash provides an ensemble command with three methods for hashing data from an in-memory string, an open channel, or a file specified by its path in the filesystem.

The set of supported hashes is described in the following section.

  • ak hash HASH channel channel ?options?

  • ak hash HASH path path ?options?

  • ak hash HASH string string ?options?

    These three commands return the HASH-specific digest of the data specified by the command arguments.

    Attention: Note that this result is binary data, i.e. a Tcl ByteArray value. It is the callers responsibility to encode this digest into any other required form, like hex-digits, or base64, etc.

    The data to hash (the input) is provided either by a channel opened for reading, the path to a file in the filesystem, or an in-memory string (Again a Tcl ByteArray value).

    The options allow for finer control of the slice of the input to be hashed. For more details see section Slice Options.

    Notes about channel handling:

    • The input starts at the current location of the channel.

    • The channel location is moved forward as part of skipping the offset, and during hashing itself.

    • The channel location is left where it is when hashing ends. This may be after the end of the channel.

    • The channel is not closed by the command.

  • ak hash HASH size

    This command returns the size of digests generated by the HASH, in bytes.

  • ak hash HASH references

    This command returns a list of informational strings about the HASH.

Slice Options

The slice options allow for finer control of the part of the input to be hashed.

  • -offset wideint > 0

    Offset in bytes after the start of the input to start hashing from. If the offset indicates a location after the end of the input then the -length setting is ignored, and the hash returned is for the empty string.

  • -length wideint > 0

    Length in bytes of the part of the input to hash. If offset and length indicate a location after the end of the input the hashing terminates at the end of the input.

For string hashing these options are technically superfluous as their effect can be had by applying a string range to the input before handing it to the hash command.

Similarly for hashing a channel, seeking to the desired position makes option -start superfluous.

Only for hashing a file both are required if we do not wish to go through a channel or string at Tcl level.

They are implemented for all modes for the sake of consistency.

Supported Hashes

The package currently supports 18 different hash functions, some configured for multiple digest sizes, for 30 base commands. Times the 3 modes per such and the package publishes a total of 90 hash commands.

Note that many of the hash functions have descriptions at RHash @ SourceForge. Because of that the descriptions here are even shorter summaries.

Further note that all phrases like X supports digests of size A, B, ... should be read to mean that this are the digest sizes supported by the C code underlying Ankh. While this matches the allowed/specified digest sizes for many of the hashes here, it is not true for all.

  • aich

    The Advanced Intelligent Corruption Handler comes from the EDonkey p2p-network. It uses SHA-1 internally. Digests are 160 bits.

    See also ed2k below.

  • blake

    See Blake 2 @ Wikipedia for details. Supports digests of 256 and 512 bits.

    • blake2b

    • blake2s

  • btih

    The BitTorrent InfoHash originates, naturally, in the BitTorrent network. Digests are 160 bits.

  • ed2k

    Like aich above EDonkey 2000 comes from the EDonkey p2p-network. It uses MD-4 internally. Digests are 128 bits.

  • edonr

    Defined in 2006 in the article D. Gligoroski, S. Markovski, L. Kocarev "Edon-R, An Infinite Family of Cryptographic Hash Functions". Supports digests of 224, 256, 384, and 512 bits.

    • edonr/224

    • edonr/256

    • edonr/384

    • edonr/512

  • gost12

  • gost94

    These hash functions are from the Russian national standard GOST R 34.11-94. gost12 supports digests of 256 and 512 bits. gost94 digests are 256 bits.

    • gost12/256

    • gost12/512

    • gost94

  • has160

    Designed in and by Korea, for the Korean Certificate-based Digital Signature Algorithm (KCDSA). Digests have 160 bits.

  • md4

    Message digest 4 was developed by Ronald L. Rivest. See RFC 1320. Digests have 128 bits.

  • md5

    Message digest 5 is an improved success of MD-4, also developed by Ronald L. Rivest. See RFC 1321. Digests have 128 bits.

  • ripemd160

    The RACE Integrity Primitives Evaluation Message Digest. Digests have 160 bits.

  • sha1

    The Secure Hash Algorithm 1 was designed in 1993. See RFC 3174. Digests are 160 bits.

  • sha2

    Secure Hash Algorithm 2 is the successor of SHA-2. Supports digests of 224, 256, 384, and 512 bits.

    • sha2/224

    • sha2/256

    • sha2/384

    • sha2/512

  • sha3

    Secure Hash Algorithm 3 is the latest in the SHA series. Based on a completely new internal construction than the predecessors. See KECCACK. Supports digests of 224, 256, 384, and 512 bits.

    • sha3/224

    • sha3/256

    • sha3/384

    • sha3/512

  • snefru

    Made by Ralph Merkle in 1990. Considered broken. Also slow. Supports digests of 128 and 256 bits.

    • snefru/128

    • snefru/256

  • tiger

    Tiger was developed by Ross Anderson and Eli Biham, with speed on 64bit processors in mind. Digests are 192 bits.

  • tth

    The Tiger Tree Hash is based on the Tiger hash above. It is used by the p2p networks Direct Connect and Gnutella. Digests are 512 bits.

  • whirlpool

    Comes from NESSIE. Adopted by ISO/IEC 10118-3:2004. Digests are 512 bits.

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Ankh Tracker. Please also report any ideas for enhancements you may have for either package and/or documentation.

KEYWORDS

aich, bittorrent info hash, blake, btih, cryptographically secure hashes, ed2k, edonr, gost12, gost94, has160, hash digests, md4, md5, ripemd160, secure hashes, sha1, sha2, sha3, snefru, tiger, tth, whirlpool

CATEGORY

cryptographically secure hashes

COPYRIGHT

Copyright © 2021-2024 Andreas Kupries
Copyright © 2021-2024 Documentation, Andreas Kupries