std.digest.sha

Category	Functions
Template API	SHA1
OOP API	SHA1Digest
Helpers	sha1Of

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.

SHA2 comes in several different versions, all supported by this module: SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224 and SHA-512/256.

This module conforms to the APIs defined in std.digest.digest. To understand the differences between the template and the OOP API, see std.digest.digest.

This module publicly imports std.digest.digest and can be used as a stand-alone module.

License:
Boost License 1.0

CTFE:
Digests do not work in CTFE

Authors:
The routines and algorithms are derived from the Secure Hash Signature Standard (SHS) (FIPS PUB 180-2).
Kai Nacke, Johannes Pfau, Nick Sabalausky

References:

• FIPS PUB180-2
• Fast implementation of SHA1
• Wikipedia article about SHA

Source:
std/digest/sha.d

struct SHA(int blockSize, int digestSize);

Template API SHA1/SHA2 implementation. Supports: SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224 and SHA-512/256.

The blockSize and digestSize are in bits. However, it's likely easier to simply use the convenience aliases: SHA1, SHA224, SHA256, SHA384, SHA512, SHA512_224 and SHA512_256.

See std.digest.digest for differences between template and OOP API.

pure nothrow @trusted void start();

SHA initialization. Begins an SHA1/SHA2 operation.

Note:
For this SHA Digest implementation calling start after default construction is not necessary. Calling start is only necessary to reset the Digest.

Generic code which deals with different Digest types should always call start though.

Examples:

SHA1 digest;
//digest.start(); //Not necessary
digest.put(0);

pure nothrow @trusted void put(scope const(ubyte)[] input...);

Use this to feed the digest with data. Also implements the std.range.OutputRange interface for ubyte and const(ubyte)[].

Examples:

typeof(this) dig;
dig.put(cast(ubyte)0); //single ubyte
dig.put(cast(ubyte)0, cast(ubyte)0); //variadic
ubyte[10] buf;
dig.put(buf); //buffer

pure nothrow @trusted ubyte[digestSize / 8] finish();

Returns the finished SHA hash. This also calls start to reset the internal state.

Examples:

//Simple example
SHA1 hash;
hash.start();
hash.put(cast(ubyte)0);
ubyte[20] result = hash.finish();

alias SHA1 = SHA!(512, 160).SHA;

SHA alias for SHA-1, hash is ubyte[20]

alias SHA224 = SHA!(512, 224).SHA;

SHA alias for SHA-224, hash is ubyte[28]

alias SHA256 = SHA!(512, 256).SHA;

SHA alias for SHA-256, hash is ubyte[32]

alias SHA384 = SHA!(1024, 384).SHA;

SHA alias for SHA-384, hash is ubyte[48]

alias SHA512 = SHA!(1024, 512).SHA;

SHA alias for SHA-512, hash is ubyte[64]

alias SHA512_224 = SHA!(1024, 224).SHA;

SHA alias for SHA-512/224, hash is ubyte[28]

alias SHA512_256 = SHA!(1024, 256).SHA;

SHA alias for SHA-512/256, hash is ubyte[32]

Examples:

//Simple example, hashing a string using sha1Of helper function
ubyte[20] hash = sha1Of("abc");
//Let's get a hash string
assert(toHexString(hash) == "A9993E364706816ABA3E25717850C26C9CD0D89D");

//The same, but using SHA-224
ubyte[28] hash224 = sha224Of("abc");
assert(toHexString(hash224) == "23097D223405D8228642A477BDA255B32AADBCE4BDA0B3F7E36C9DA7");

Examples:

//Using the basic API
SHA1 hash;
hash.start();
ubyte[1024] data;
//Initialize data here...
hash.put(data);
ubyte[20] result = hash.finish();

Examples:

//Let's use the template features:
//Note: When passing a SHA1 to a function, it must be passed by reference!
void doSomething(T)(ref T hash) if(isDigest!T)
{
  hash.put(cast(ubyte)0);
}
SHA1 sha;
sha.start();
doSomething(sha);
assert(toHexString(sha.finish()) == "5BA93C9DB0CFF93F52B521D7420E43F6EDA2784F");

auto sha1Of(T...)(T data);
auto sha224Of(T...)(T data);
auto sha256Of(T...)(T data);
auto sha384Of(T...)(T data);
auto sha512Of(T...)(T data);
auto sha512_224Of(T...)(T data);
auto sha512_256Of(T...)(T data);

These are convenience aliases for std.digest.digest.digest using the SHA implementation.

Examples:

ubyte[20] hash = sha1Of("abc");
assert(hash == digest!SHA1("abc"));

ubyte[28] hash224 = sha224Of("abc");
assert(hash224 == digest!SHA224("abc"));

ubyte[32] hash256 = sha256Of("abc");
assert(hash256 == digest!SHA256("abc"));

ubyte[48] hash384 = sha384Of("abc");
assert(hash384 == digest!SHA384("abc"));

ubyte[64] hash512 = sha512Of("abc");
assert(hash512 == digest!SHA512("abc"));

ubyte[28] hash512_224 = sha512_224Of("abc");
assert(hash512_224 == digest!SHA512_224("abc"));

ubyte[32] hash512_256 = sha512_256Of("abc");
assert(hash512_256 == digest!SHA512_256("abc"));

alias SHA1Digest = std.digest.digest.WrapperDigest!(SHA!(512, 160)).WrapperDigest;
alias SHA224Digest = std.digest.digest.WrapperDigest!(SHA!(512, 224)).WrapperDigest;
alias SHA256Digest = std.digest.digest.WrapperDigest!(SHA!(512, 256)).WrapperDigest;
alias SHA384Digest = std.digest.digest.WrapperDigest!(SHA!(1024, 384)).WrapperDigest;
alias SHA512Digest = std.digest.digest.WrapperDigest!(SHA!(1024, 512)).WrapperDigest;
alias SHA512_224Digest = std.digest.digest.WrapperDigest!(SHA!(1024, 224)).WrapperDigest;
alias SHA512_256Digest = std.digest.digest.WrapperDigest!(SHA!(1024, 256)).WrapperDigest;

OOP API SHA1 and SHA2 implementations. See std.digest.digest for differences between template and OOP API.

This is an alias for std.digest.digest.WrapperDigest!SHA1, see std.digest.digest.WrapperDigest for more information.

Examples:

//Simple example, hashing a string using Digest.digest helper function
auto sha = new SHA1Digest();
ubyte[] hash = sha.digest("abc");
//Let's get a hash string
assert(toHexString(hash) == "A9993E364706816ABA3E25717850C26C9CD0D89D");

//The same, but using SHA-224
auto sha224 = new SHA224Digest();
ubyte[] hash224 = sha224.digest("abc");
//Let's get a hash string
assert(toHexString(hash224) == "23097D223405D8228642A477BDA255B32AADBCE4BDA0B3F7E36C9DA7");

Examples:

//Let's use the OOP features:
void test(Digest dig)
{
  dig.put(cast(ubyte)0);
}
auto sha = new SHA1Digest();
test(sha);

//Let's use a custom buffer:
ubyte[20] buf;
ubyte[] result = sha.finish(buf[]);
assert(toHexString(result) == "5BA93C9DB0CFF93F52B521D7420E43F6EDA2784F");

Copyright © 1999-2017 by Digital Mars, All Rights Reserved | Page generated by Ddoc.