silk.crypto.sha2.

When to use#

Use Sha256 when you need a cryptographic hash and the protocol does not name another one. Use the type that a protocol names, for example Sha384 for some TLS cipher suites. Use silk.crypto.hmac for a keyed tag and silk.collections.hash for the keys of a hash map.

Details#

Each type has the same functions: hash returns the digest of one slice, and make, update, and finish hash a message that arrives in parts. Sha256.checkpoint and Sha384.checkpoint return the digest so far and keep the state. The states are fixed-size values and nothing allocates. Digests use the standard big-endian byte order.

Gotchas#

finish consumes the state. To hash two messages that share a prefix, use checkpoint, or copy the state before finish. Do not hash a secret key and a message together to make a tag. Use silk.crypto.hmac.

Examples#

Hash a message in one call and in parts#

import silk.crypto.sha2 { Sha256 }

pub fn main() -> i32 {
  let oneShot = Sha256.hash(b"abc")
  let mut state = Sha256.make()
  state.update(b"a")
  state.update(b"bc")
  let streamed = state.finish()

  // SHA-256("abc") is ba7816bf...15ad.
  if oneShot[0] != 0xba || oneShot[31] != 0xad || streamed[0] != oneShot[0] {
    return 1
  }
  return 0
}

Take a running digest with checkpoint#

import silk.crypto.sha2 { Sha256 }

pub fn main() -> i32 {
  let mut transcript = Sha256.make()
  transcript.update(b"abc")
  let early = transcript.checkpoint()
  transcript.update(b"def")
  let full = transcript.finish()
  if early[0] != Sha256.hash(b"abc")[0] || full[0] != Sha256.hash(b"abcdef")[0] {
    return 1
  }
  return 0
}

Import as Sha256 with import silk.crypto.sha2 { Sha256 }.

Public declarations: 6.

Sha224#

pub struct Sha224

A streaming SHA-224 state that returns a 28-byte digest.

Call Sha224.update for each part of the message, then Sha224.finish. Use Sha224.hash when the full message is in one slice. The state is a fixed-size value and does not allocate.

Implementation Sha224#

impl Sha224

Associated function make#

pub fn make() -> Sha224

Returns a SHA-224 state for an empty message.

Method update#

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

Adds bytes to the end of the message.

Any split of the message into parts gives the same digest. An empty slice changes nothing.

Gotchas#

The program traps if the full message is longer than 2^64 - 1 bits.

Method finish#

pub fn finish(self: Self) -> [u8; 28]

Returns the 28-byte SHA-224 digest of the message and consumes the state.

Associated function hash#

pub fn hash(bytes: &[u8]) -> [u8; 28]

Returns the 28-byte SHA-224 digest of bytes.

Gotchas#

The program traps if bytes is longer than 2^64 - 1 bits.

Sha256#

pub struct Sha256

A streaming SHA-256 state that returns a 32-byte digest.

Call Sha256.update for each part of the message, then Sha256.finish. Use Sha256.hash when the full message is in one slice. The state is a fixed-size value and does not allocate.

Implementation Sha256#

impl Sha256

Associated function make#

pub fn make() -> Sha256

Returns a SHA-256 state for an empty message.

Method update#

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

Adds bytes to the end of the message.

Any split of the message into parts gives the same digest. An empty slice changes nothing.

Gotchas#

The program traps if the full message is longer than 2^64 - 1 bits.

Method checkpoint#

pub fn checkpoint(self: &Self) -> [u8; 32]

Returns the SHA-256 digest of the bytes added so far, and keeps the state.

Later calls to update continue the same message. Use it for a running transcript hash, such as the TLS handshake hash.

Method finish#

pub fn finish(self: Self) -> [u8; 32]

Returns the 32-byte SHA-256 digest of the message and consumes the state.

Associated function hash#

pub fn hash(bytes: &[u8]) -> [u8; 32]

Returns the 32-byte SHA-256 digest of bytes.

Gotchas#

The program traps if bytes is longer than 2^64 - 1 bits.

Sha384#

pub struct Sha384

A streaming SHA-384 state that returns a 48-byte digest.

Call Sha384.update for each part of the message, then Sha384.finish. Use Sha384.hash when the full message is in one slice. The state is a fixed-size value and does not allocate.

Implementation Sha384#

impl Sha384

Associated function make#

pub fn make() -> Sha384

Returns a SHA-384 state for an empty message.

Method update#

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

Adds bytes to the end of the message.

Any split of the message into parts gives the same digest. An empty slice changes nothing.

Gotchas#

The program traps if the full message is longer than 2^128 - 1 bits.

Method checkpoint#

pub fn checkpoint(self: &Self) -> [u8; 48]

Returns the SHA-384 digest of the bytes added so far, and keeps the state.

Later calls to update continue the same message. Use it for a running transcript hash, such as the TLS handshake hash.

Method finish#

pub fn finish(self: Self) -> [u8; 48]

Returns the 48-byte SHA-384 digest of the message and consumes the state.

Associated function hash#

pub fn hash(bytes: &[u8]) -> [u8; 48]

Returns the 48-byte SHA-384 digest of bytes.

Gotchas#

The program traps if bytes is longer than 2^128 - 1 bits.

Sha512#

pub struct Sha512

A streaming SHA-512 state that returns a 64-byte digest.

Call Sha512.update for each part of the message, then Sha512.finish. Use Sha512.hash when the full message is in one slice. The state is a fixed-size value and does not allocate.

Implementation Sha512#

impl Sha512

Associated function make#

pub fn make() -> Sha512

Returns a SHA-512 state for an empty message.

Method update#

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

Adds bytes to the end of the message.

Any split of the message into parts gives the same digest. An empty slice changes nothing.

Gotchas#

The program traps if the full message is longer than 2^128 - 1 bits.

Method finish#

pub fn finish(self: Self) -> [u8; 64]

Returns the 64-byte SHA-512 digest of the message and consumes the state.

Associated function hash#

pub fn hash(bytes: &[u8]) -> [u8; 64]

Returns the 64-byte SHA-512 digest of bytes.

Gotchas#

The program traps if bytes is longer than 2^128 - 1 bits.

Sha512_224#

pub struct Sha512_224

A streaming SHA-512/224 state that returns a 28-byte digest.

Call Sha512_224.update for each part of the message, then Sha512_224.finish. Use Sha512_224.hash when the full message is in one slice. The state is a fixed-size value and does not allocate.

Implementation Sha512_224#

impl Sha512_224

Associated function make#

pub fn make() -> Sha512_224

Returns a SHA-512/224 state for an empty message.

Method update#

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

Adds bytes to the end of the message.

Any split of the message into parts gives the same digest. An empty slice changes nothing.

Gotchas#

The program traps if the full message is longer than 2^128 - 1 bits.

Method finish#

pub fn finish(self: Self) -> [u8; 28]

Returns the 28-byte SHA-512/224 digest of the message and consumes the state.

Associated function hash#

pub fn hash(bytes: &[u8]) -> [u8; 28]

Returns the 28-byte SHA-512/224 digest of bytes.

Gotchas#

The program traps if bytes is longer than 2^128 - 1 bits.

Sha512_256#

pub struct Sha512_256

A streaming SHA-512/256 state that returns a 32-byte digest.

Call Sha512_256.update for each part of the message, then Sha512_256.finish. Use Sha512_256.hash when the full message is in one slice. The state is a fixed-size value and does not allocate.

Implementation Sha512_256#

impl Sha512_256

Associated function make#

pub fn make() -> Sha512_256

Returns a SHA-512/256 state for an empty message.

Method update#

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

Adds bytes to the end of the message.

Any split of the message into parts gives the same digest. An empty slice changes nothing.

Gotchas#

The program traps if the full message is longer than 2^128 - 1 bits.

Method finish#

pub fn finish(self: Self) -> [u8; 32]

Returns the 32-byte SHA-512/256 digest of the message and consumes the state.

Associated function hash#

pub fn hash(bytes: &[u8]) -> [u8; 32]

Returns the 32-byte SHA-512/256 digest of bytes.

Gotchas#

The program traps if bytes is longer than 2^128 - 1 bits.

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.