[ 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
-
This command returns a string containing the version number of the Ankh package.
-
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 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.
-
This command returns the size of digests generated by the HASH, in bytes.
-
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