12 SHA* Secure Hash Algorithms

The library library(sha) provides Secure Hash Algorihms approved by FIPS (Federal Information Processing Standard). Quoting Wikipedia: ``The SHA (Secure Hash Algorithm) hash functions refer to five FIPS-approved algorithms for computing a condensed digital representation (known as a message digest) that is, to a high degree of probability, unique for a given input data sequence (the message). These algorithms are called `secure' because (in the words of the standard), ``for a given algorithm, it is computationally infeasible 1) to find a message that corresponds to a given message digest, or 2) to find two different messages that produce the same message digest. Any change to a message will, with a very high probability, result in a different message digest.''

The current library supports all 5 approved algorithms, both computing the hash-key from data and the hash Message Authentication Code (HMAC).

A general secure hash interface is provided by library(crypto), part of the ssl package.

Input is text, represented as an atom, packed string object or code-list. Note that these functions operate on byte-sequences and therefore are not meaningful on Unicode text. The result is returned as a list of byte-values. This is the most general format that is comfortable supported by standard Prolog and can easily be transformed in other formats. Commonly used text formats are ASCII created by encoding each byte as two hexadecimal digits and ASCII created using base64 encoding. Representation as a large integer can be desirable for computational processing.

sha_hash(+Data, -Hash, +Options)

Hash is the SHA hash of Data. Data is either an atom, packed string or list of character codes. Hash is unified with a list of bytes (integers in the range 0..255) representing the hash. See hash_atom/2 to convert this into the more commonly seen hexadecimal representation. The conversion is controlled by Options:

algorithm(+Algorithm)

One of sha1 (default), sha224, sha256, sha384 or sha512

encoding(+Encoding)

This option defines the mapping from Prolog (Unicode) text to bytes on which the SHA algorithm is performed. It has two values. The defualt is utf8, which implies that Unicode text is encoded as UTF-8 bytes. This option can deal with any atom. The alternative is octet, which implies that the text is considered as a sequence of bytes. This is suitable for e.g., atoms that represent binary data. An error is raised if the text contains code-points outside the range 0..255.

hmac_sha(+Key, +Data, -HMAC, +Options)

Quoting Wikipedia: ``A keyed-hash message authentication code, or HMAC, is a type of message authentication code (MAC) calculated using a cryptographic hash function in combination with a secret key. As with any MAC, it may be used to simultaneously verify both the data integrity and the authenticity of a message. Any iterative cryptographic hash function, such as MD5 or SHA-1, may be used in the calculation of an HMAC; the resulting MAC algorithm is termed HMAC-MD5 or HMAC-SHA-1 accordingly. The cryptographic strength of the HMAC depends upon the cryptographic strength of the underlying hash function, on the size and quality of the key and the size of the hash output length in bits.''

Key and Data are either an atom, packed string or list of character codes. HMAC is unified with a list of integers representing the authentication code. Options is the same as for sha_hash/3, but currently only sha1 and sha256 are supported.

hash_atom(+Hash, -HexAtom)

True when HexAtom is the commonly used hexadecimal encoding of the hash code. E.g.,

?- sha_hash('SWI-Prolog', Hash, []),
   hash_atom(Hash, Hex).
Hash = [61, 128, 252, 38, 121, 69, 229, 85, 199|...],
Hex = '3d80fc267945e555c730403bd0ab0716e2a68c68'.

12.1 License terms

The underlying SHA-2 library is an unmodified copy created by Dr Brian Gladman, Worcester, UK. It is distributed under the license conditions below.

The free distribution and use of this software in both source and binary form is allowed (with or without changes) provided that:

1. distributions of this source code include the above copyright notice, this list of conditions and the following disclaimer;

2. distributions in binary form include the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other associated materials;

3. the copyright holder's name is not used to endorse products built using this software without specific written permission.

ALTERNATIVELY, provided that this notice is retained in full, this product may be distributed under the terms of the GNU General Public License (GPL), in which case the provisions of the GPL apply INSTEAD OF those given above.