Module sha

Available on crate feature unstable only.

Secure Hash Algorithm (SHA) Accelerator

Overview

This SHA accelerator is a hardware device that speeds up the SHA algorithm significantly, compared to a SHA algorithm implemented solely in software

Configuration

This driver allows you to perform cryptographic hash operations using various hash algorithms supported by the SHA peripheral, such as:

• SHA-1
• SHA-224
• SHA-256
• SHA-384
• SHA-512

The driver supports two working modes:

• Typical SHA (CPU-driven)
• DMA-SHA (not supported yet)

It provides functions to update the hash calculation with input data, finish the hash calculation and retrieve the resulting hash value. The SHA peripheral on ESP chips can handle large data streams efficiently, making it suitable for cryptographic applications that require secure hashing.

To use the SHA Peripheral Driver, you need to initialize it with the desired SHA mode and the corresponding SHA peripheral. Once initialized, you can update the hash calculation by providing input data, finish the calculation to retrieve the hash value and repeat the process for a new hash calculation if needed.

Examples

Using the Sha driver

let mut source_data = "HELLO, ESPRESSIF!".as_bytes();
let mut sha = Sha::new(peripherals.SHA);
let mut hasher = sha.start::<Sha256>();
// Short hashes can be created by decreasing the output buffer to the
// desired length
let mut output = [0u8; 32];

while !source_data.is_empty() {
    // All the HW Sha functions are infallible so unwrap is fine to use if
    // you use block!
    source_data = block!(hasher.update(source_data))?;
}

// Finish can be called as many times as desired to get multiple copies of
// the output.
block!(hasher.finish(output.as_mut_slice()))?;

Using the ShaBackend driver

use esp_hal::sha::{Sha1Context, ShaBackend};
let mut sha = ShaBackend::new(peripherals.SHA);
// Start the backend, which allows processing SHA operations.
let _backend = sha.start();

// Create a new context to hash data with SHA-1.
let mut sha1_ctx = Sha1Context::new();

// SHA-1 outputs a 20-byte digest.
let mut digest: [u8; 20] = [0; 20];

// Process data. The `update` function returns a handle which can be used to wait
// for the operation to finish.
sha1_ctx.update(b"input data").wait_blocking();
sha1_ctx.update(b"input data").wait_blocking();
sha1_ctx.update(b"input data").wait_blocking();

// Extract the final hash. This resets the context.
sha1_ctx.finalize(&mut digest).wait_blocking();

// digest now contains the SHA-1 hash of the input.

Structs

Sha

The SHA Accelerator driver instance

Sha1

Hardware-accelerated SHA-1 implementation

Sha1Context

A SHA-1 context.

Sha256

Hardware-accelerated SHA-256 implementation

Sha384

Hardware-accelerated SHA-384 implementation

Sha512

Hardware-accelerated SHA-512 implementation

Sha256Context

A SHA-256 context.

Sha384Context

A SHA-384 context.

Sha512Context

A SHA-512 context.

ShaBackend

CPU-driven SHA processing backend.

ShaDigest

An active digest

ShaHandle

A handle for an in-progress operation, returned by update or finalize.

ShaWorkQueueDriver

An active work queue driver.

Enums

FinalizeError

Error type returned by finalize_into_slice.

ShaAlgorithmKind

Specifies particular SHA algorithm.

Traits

Digest

Re-export digest for convenience Convenience wrapper trait covering functionality of cryptographic hash functions with fixed output size.

ShaAlgorithm

This trait encapsulates the configuration for a specific SHA algorithm.