silk.crypto.digest.

When to use#

Bound a type parameter with Digest to write code that works with any hash, such as Hmac<H> in silk.crypto.hmac or Pbkdf2.derive<H> in silk.crypto.pbkdf2. To hash data with a known algorithm, call that hash's own functions, which return a fixed-size array.

Details#

MD5, SHA-1, the six SHA-2 hashes, the four SHA-3 hashes, BLAKE2b-512, BLAKE2s-256, RIPEMD-160, SM3, and MD5-SHA1 conform. The SHAKE functions of silk.crypto.sha3 do not, because their output length is the caller's choice. Each state is a fixed-size value that does not allocate. No block is longer than 144 bytes and no digest is longer than 64 bytes, so generic code can keep them in arrays of those sizes.

Examples#

Hash with any digest#

import silk.crypto.digest { Digest }
import silk.crypto.sha2 { Sha256 }
import silk.crypto.sha1 { Sha1 }

fn firstByte<H: Digest>(message: &[u8]) -> u8 {
  let mut state: H = Digest.make()
  state.update(message)
  let mut digest: [u8; 64] = [0; 64]
  state.finishInto(&mut digest)
  return digest[0]
}

pub fn main() -> i32 {
  // SHA-256("abc") starts with ba, and SHA-1("abc") with a9.
  if firstByte<Sha256>(b"abc") != 0xba || firstByte<Sha1>(b"abc") != 0xa9 {
    return 1
  }
  return 0
}

Import as Digest with import silk.crypto.digest { Digest }.

Public declarations: 1.

Digest#

pub interface Digest

A streaming hash: a state that takes a message in parts and returns a fixed-length digest.

When to use#

Bound a type parameter with it to write code that works with any hash of silk.crypto, such as HMAC, PBKDF2, or a hash chosen by name at run time.

Details#

A provider is a fixed-size value that does not allocate. Digest.blockLength is at most 144 bytes and Digest.digestLength is at most 64 bytes for every provider in the standard library.

Operation make#

fn make() -> Self

Returns a state for an empty message.

Operation blockLength#

fn blockLength(self: &Self) -> usize

Returns the number of bytes the hash compresses at a time, such as 64 for SHA-256. HMAC pads its key to this length.

Operation digestLength#

fn digestLength(self: &Self) -> usize

Returns the number of bytes that Digest.finishInto writes, such as 32 for SHA-256.

Operation objectIdentifier#

fn objectIdentifier(self: &Self) -> &[u8]

Returns the content bytes of the DER object identifier that names the hash, without the tag and length. Signature formats such as PKCS #1 v1.5 and X.509 name the hash with it.

Operation update#

fn update(self: &mut Self, bytes: &[u8]) -> ()

Adds bytes to the end of the message. Any split of the message gives the same digest.

Operation copy#

fn copy(self: &Self) -> Self

Returns an independent copy of the state. Updates to either one do not change the other.

Operation finishInto#

fn finishInto(self: Self, output: &mut [u8]) -> ()

Writes the digest of the message to the first Digest.digestLength bytes of output and consumes the state. The bytes after them do not change. The program traps if output is shorter.

Category: Cryptography.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.