std.digest

This module describes the digest APIs used in Phobos. All digests follow these APIs. Additionally, this module contains useful helper methods which can be used with every digest type.

APIs: There are two APIs for digests: The template API and the OOP API. The template API uses structs and template helpers like isDigest. The OOP API implements digests as classes inheriting the Digest interface. All digests are named so that the template API struct is called "x" and the OOP API class is called "xDigest". For example we have MD5 <--> MD5Digest, CRC32 <--> CRC32Digest, etc.

The template API is slightly more efficient. It does not have to allocate memory dynamically, all memory is allocated on the stack. The OOP API has to allocate in the finish method if no buffer was provided. If you provide a buffer to the OOP APIs finish function, it doesn't allocate, but the Digest classes still have to be created using new which allocates them using the GC.

The OOP API is useful to change the digest function and/or digest backend at 'runtime'. The benefit here is that switching e.g. Phobos MD5Digest and an OpenSSLMD5Digest implementation is ABI compatible.

If just one specific digest type and backend is needed, the template API is usually a good fit. In this simplest case, the template API can even be used without templates: Just use the "x" structs directly.

Modules

crc
module std.digest.crc

Cyclic Redundancy Check (32-bit) implementation.

hmac
module std.digest.hmac

This package implements the hash-based message authentication code (HMAC) algorithm as defined in RFC2104. See also the corresponding Wikipedia article.

md
module std.digest.md

Computes MD5 hashes of arbitrary data. MD5 hashes are 16 byte quantities that are like a checksum or CRC, but are more robust.

murmurhash
module std.digest.murmurhash

Computes MurmurHash hashes of arbitrary data. MurmurHash is a non-cryptographic hash function suitable for general hash-based lookup. It is optimized for x86 but can be used on all architectures.

ripemd
module std.digest.ripemd

Computes RIPEMD-160 hashes of arbitrary data. RIPEMD-160 hashes are 20 byte quantities that are like a checksum or CRC, but are more robust.

sha
module std.digest.sha

Computes SHA1 and SHA2 hashes of arbitrary data. SHA hashes are 20 to 64 byte quantities (depending on the SHA algorithm) that are like a checksum or CRC, but are more robust.

Members

Classes

WrapperDigest
class WrapperDigest(T)

Wraps a template API hash struct into a Digest interface. Modules providing digest implementations will usually provide an alias for this template (e.g. MD5Digest, SHA1Digest, ...).

Enums

LetterCase (from std.ascii)
enum LetterCase via public import std.ascii : LetterCase;

Letter case specifier.

Order
enum Order

See toHexString

Functions

digest
DigestType!Hash digest(Range range)

This is a convenience function to calculate a hash using the template API. Every digest passing the isDigest test can be used with this function.

digest
DigestType!Hash digest(T data)

This overload of the digest function handles arrays.

hexDigest
char[digestLength!(Hash) * 2] hexDigest(Range range)

This is a convenience function similar to digest, but it returns the string representation of the hash. Every digest passing the isDigest test can be used with this function.

hexDigest
char[digestLength!(Hash) * 2] hexDigest(T data)

This overload of the hexDigest function handles arrays.

makeDigest
Hash makeDigest()

This is a convenience function which returns an initialized digest, so it's not necessary to call start manually.

secureEqual
bool secureEqual(R1 r1, R2 r2)

Securely compares two digest representations while protecting against timing attacks. Do not use == to compare digest representations.

toHexString
char[num * 2] toHexString(ubyte[num] digest)
string toHexString(ubyte[] digest)

Used to convert a hash value (a static or dynamic array of ubytes) to a string. Can be used with the OOP and with the template API.

Interfaces

Digest
interface Digest

This describes the OOP API. To understand when to use the template API and when to use the OOP API, see the module documentation at the top of this page.

Structs

ExampleDigest
struct ExampleDigest

This documents the general structure of a Digest in the template API. All digest implementations should implement the following members and therefore pass the isDigest test.

Templates

DigestType
template DigestType(T)

Use this template to get the type which is returned by a digest's finish method.

hasBlockSize
template hasBlockSize(T)

Checks whether the digest has a blockSize member, which contains the digest's internal block size in bits. It is primarily used by std.digest.hmac.HMAC.

hasPeek
template hasPeek(T)

Used to check if a digest supports the peek method. Peek has exactly the same function signatures as finish, but it doesn't reset the digest's internal state.

isDigest
template isDigest(T)

Use this to check if a type is a digest. See ExampleDigest to see what a type must provide to pass this check.

Meta

Source

See Source File
std/digest/package.d

CTFE: Digests do not work in CTFE

TODO: Digesting single bits (as opposed to bytes) is not implemented. This will be done as another template constraint helper (hasBitDigesting!T) and an additional interface (BitDigest)

Authors

Johannes Pfau