v2.0.0
Data Structures | Typedefs | Functions
pico_sha256
High Level APIs

SHA-256 Hardware Accelerated implementation. More...

## Data Structures
struct | pico_sha256_state
| SHA-256 state used by the API. More...

## Typedefs
typedef struct pico_sha256_state | pico_sha256_state_t
| SHA-256 state used by the API.

## Functions
int | pico_sha256_try_start (pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma)
| Start a SHA-256 calculation returning immediately with an error if the SHA-256 hardware is not available. More...
int | pico_sha256_start_blocking_until (pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma, absolute_time_t until)
| Start a SHA-256 calculation waiting for a defined period for the SHA-256 hardware to be available. More...
static int | pico_sha256_start_blocking (pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma)
| Start a SHA-256 calculation, blocking forever waiting until the SHA-256 hardware is available. More...
void | pico_sha256_update (pico_sha256_state_t *state, const uint8_t *data, size_t data_size_bytes)
| Add byte data to be SHA-256 calculation. More...
void | pico_sha256_update_blocking (pico_sha256_state_t *state, const uint8_t *data, size_t data_size_bytes)
| Add byte data to be SHA-256 calculation. More...
void | pico_sha256_finish (pico_sha256_state_t *state, sha256_result_t *out)
| Finish the SHA-256 calculation and return the result. More...

## Detailed Description

SHA-256 Hardware Accelerated implementation.

RP2350 is equipped with a hardware accelerated implementation of the SHA-256 hash algorithm. This should be much quicker than performing a SHA-256 checksum in software.

pico_sha256_state_t state;
if (pico_sha256_try_start(&state, SHA256_BIG_ENDIAN, true) == PICO_OK) {
sha256_result_t result;
pico_sha256_update(&state, some_data, sizeof(some_data));
pico_sha256_update(&state, some_more_data, sizeof(some_more_data));
pico_sha256_finish(&state, &result);
for (int i = 0; i < SHA256_RESULT_BYTES; i++) {
printf("%02x", result.bytes[i]);
}
}
SHA256_RESULT_BYTES
#define SHA256_RESULT_BYTES
Size of a sha256 result in bytes.
Definition: sha256.h:44
SHA256_BIG_ENDIAN
@ SHA256_BIG_ENDIAN
Big Endian.
Definition: sha256.h:51
PICO_OK
@ PICO_OK
No error; the operation succeeded.
Definition: error.h:23
pico_sha256_update
void pico_sha256_update(pico_sha256_state_t *state, const uint8_t *data, size_t data_size_bytes)
Add byte data to be SHA-256 calculation.
Definition: sha256.c:137
pico_sha256_finish
void pico_sha256_finish(pico_sha256_state_t *state, sha256_result_t *out)
Finish the SHA-256 calculation and return the result.
Definition: sha256.c:167
pico_sha256_try_start
int pico_sha256_try_start(pico_sha256_state_t *state, enum sha256_endianness endianness, bool use_dma)
Start a SHA-256 calculation returning immediately with an error if the SHA-256 hardware is not availa...
Definition: sha256.c:33
pico_sha256_state
SHA-256 state used by the API.
Definition: sha256.h:48
sha256_result_t
SHA-256 result generated by the API.
Definition: sha256.h:57

## Example

## Function Documentation

## ◆ pico_sha256_finish()

void pico_sha256_finish | ( | pico_sha256_state_t * | state,
|  | sha256_result_t * | out
| ) |  |

Finish the SHA-256 calculation and return the result.

Ends the SHA-256 calculation freeing the hardware for use by another caller. You must have called pico_sha256_try_start already.

Parameters

  state | A pointer to a pico_sha256_state_t instance
  out | The SHA-256 checksum

## ◆ pico_sha256_start_blocking()

static int pico_sha256_start_blocking | ( | pico_sha256_state_t * | state,
|  | enum sha256_endianness | endianness,
|  | bool | use_dma
| ) |  |
| inlinestatic

Start a SHA-256 calculation, blocking forever waiting until the SHA-256 hardware is available.

Initialises the hardware and state ready to start a new SHA-256 calculation. Only one instance can be started at any time.

Parameters

  state | A pointer to a pico_sha256_state_t instance
  endianness | SHA256_BIG_ENDIAN or SHA256_LITTLE_ENDIAN for data in and data out
  use_dma | Set to true to use DMA internally to copy data to hardware. This is quicker at the expense of hardware DMA resources.

Returns
  Returns PICO_OK if the hardware was available for use and the sha256 calculation could be started, otherwise an error is returned

## ◆ pico_sha256_start_blocking_until()

int pico_sha256_start_blocking_until | ( | pico_sha256_state_t * | state,
|  | enum sha256_endianness | endianness,
|  | bool | use_dma,
|  | absolute_time_t | until
| ) |  |

Start a SHA-256 calculation waiting for a defined period for the SHA-256 hardware to be available.

Initialises the hardware and state ready to start a new SHA-256 calculation. Only one instance can be started at any time.

Parameters

  state | A pointer to a pico_sha256_state_t instance
  endianness | SHA256_BIG_ENDIAN or SHA256_LITTLE_ENDIAN for data in and data out
  use_dma | Set to true to use DMA internally to copy data to hardware. This is quicker at the expense of hardware DMA resources.
  until | How long to wait for the SHA hardware to be available

Returns
  Returns PICO_OK if the hardware was available for use and the sha256 calculation could be started in time, otherwise an error is returned

## ◆ pico_sha256_try_start()

int pico_sha256_try_start | ( | pico_sha256_state_t * | state,
|  | enum sha256_endianness | endianness,
|  | bool | use_dma
| ) |  |

Start a SHA-256 calculation returning immediately with an error if the SHA-256 hardware is not available.

Initialises the hardware and state ready to start a new SHA-256 calculation. Only one instance can be started at any time.

Parameters

  state | A pointer to a pico_sha256_state_t instance
  endianness | SHA256_BIG_ENDIAN or SHA256_LITTLE_ENDIAN for data in and data out
  use_dma | Set to true to use DMA internally to copy data to hardware. This is quicker at the expense of hardware DMA resources.

Returns
  Returns PICO_OK if the hardware was available for use and the sha256 calculation could be started, otherwise an error is returned

## ◆ pico_sha256_update()

void pico_sha256_update | ( | pico_sha256_state_t * | state,
|  | const uint8_t * | data,
|  | size_t | data_size_bytes
| ) |  |

Add byte data to be SHA-256 calculation.

Add byte data to be SHA-256 calculation You may call this as many times as required to add all the data needed. You must have called pico_sha256_try_start (or equivalent) already.

Parameters

  state | A pointer to a pico_sha256_state_t instance
  data | Pointer to the data to be added to the calculation
  data_size_bytes | Amount of data to add

Note
  This function may return before the copy has completed in which case the data passed to the function must remain valid and unchanged until a further call to pico_sha256_update or pico_sha256_finish. If this is not done, corrupt data may be used for the SHA-256 calculation giving an unexpected result.

## ◆ pico_sha256_update_blocking()

void pico_sha256_update_blocking | ( | pico_sha256_state_t * | state,
|  | const uint8_t * | data,
|  | size_t | data_size_bytes
| ) |  |

Add byte data to be SHA-256 calculation.

Add byte data to be SHA-256 calculation You may call this as many times as required to add all the data needed. You must have called pico_sha256_try_start already.

Parameters

  state | A pointer to a pico_sha256_state_t instance
  data | Pointer to the data to be added to the calculation
  data_size_bytes | Amount of data to add

Note
  This function will only return when the data passed in is no longer required, so it can be freed or changed on return.