Software APIs
Data Structures | Typedefs | Enumerations | Functions
dif_hmac.h File Reference

(dcee03a)

HMAC Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"

Go to the source code of this file.

Data Structures

struct  dif_hmac_config
 Configuration for initializing the HMAC device. More...
 
struct  dif_hmac_transaction
 Configuration for a single HMAC Transaction. More...
 
struct  dif_hmac_digest
 A typed representation of the HMAC digest. More...
 
struct  dif_hmac
 State for a particular HMAC device. More...
 

Typedefs

typedef enum dif_hmac_interrupt dif_hmac_interrupt_t
 HMAC interrupt configuration. More...
 
typedef enum dif_hmac_enable dif_hmac_enable_t
 Generic enable/disable enumeration. More...
 
typedef enum dif_hmac_mode dif_hmac_mode_t
 Supported HMAC modes of operation.
 
typedef enum dif_hmac_endianness dif_hmac_endianness_t
 Supported byte endienness options.
 
typedef enum dif_hmac_result dif_hmac_result_t
 Error codes for HMAC functions that may exhibit generic failures.
 
typedef enum dif_hmac_fifo_result dif_hmac_fifo_result_t
 Error codes for HMAC FIFO operations that may fail.
 
typedef enum dif_hmac_digest_result dif_hmac_digest_result_t
 Error codes for reading the HMAC digest.
 
typedef struct dif_hmac_config dif_hmac_config_t
 Configuration for initializing the HMAC device.
 
typedef struct dif_hmac_transaction dif_hmac_transaction_t
 Configuration for a single HMAC Transaction.
 
typedef struct dif_hmac_digest dif_hmac_digest_t
 A typed representation of the HMAC digest.
 
typedef struct dif_hmac dif_hmac_t
 State for a particular HMAC device. More...
 

Enumerations

enum  dif_hmac_interrupt {
  kDifHmacInterruptHmacDone = 0,
  kDifHmacInterruptFifoEmpty,
  kDifHmacInterruptHmacErr
}
 HMAC interrupt configuration. More...
 
enum  dif_hmac_enable {
  kDifHmacEnable = 0,
  kDifHmacDisable
}
 Generic enable/disable enumeration. More...
 
enum  dif_hmac_mode {
  kDifHmacModeHmac = 0,
  kDifHmacModeSha256
}
 Supported HMAC modes of operation. More...
 
enum  dif_hmac_endianness {
  kDifHmacEndiannessBig = 0,
  kDifHmacEndiannessLittle
}
 Supported byte endienness options. More...
 
enum  dif_hmac_result {
  kDifHmacOk = 0,
  kDifHmacError = 1,
  kDifHmacBadArg = 2
}
 Error codes for HMAC functions that may exhibit generic failures. More...
 
enum  dif_hmac_fifo_result {
  kDifHmacFifoOk = 0,
  kDifHmacFifoError = kDifHmacError,
  kDifHmacFifoBadArg = kDifHmacBadArg,
  kDifHmacFifoFull
}
 Error codes for HMAC FIFO operations that may fail. More...
 
enum  dif_hmac_digest_result {
  kDifHmacDigestOk = 0,
  kDifHmacDigestError = kDifHmacError,
  kDifHmacDigestBadArg = kDifHmacBadArg,
  kDifHmacDigestProcessing
}
 Error codes for reading the HMAC digest. More...
 

Functions

dif_hmac_result_t dif_hmac_init (const dif_hmac_config_t *config, dif_hmac_t *hmac_out)
 Initializes the HMAC device described by config, writing internal state to hmac_out. More...
 
dif_hmac_result_t dif_hmac_irq_state_get (const dif_hmac_t *hmac, dif_hmac_interrupt_t irq_type, dif_hmac_enable_t *state)
 HMAC get requested IRQ state. More...
 
dif_hmac_result_t dif_hmac_irq_state_clear (const dif_hmac_t *hmac, dif_hmac_interrupt_t irq_type)
 HMAC clear requested IRQ state. More...
 
dif_hmac_result_t dif_hmac_irqs_disable (const dif_hmac_t *hmac, uint32_t *state)
 HMAC disable interrupts. More...
 
dif_hmac_result_t dif_hmac_irqs_restore (const dif_hmac_t *hmac, uint32_t state)
 HMAC restore IRQ state. More...
 
dif_hmac_result_t dif_hmac_irq_control (const dif_hmac_t *hmac, dif_hmac_interrupt_t irq_type, dif_hmac_enable_t enable)
 HMAC interrupt control. More...
 
dif_hmac_result_t dif_hmac_irq_force (const dif_hmac_t *hmac, dif_hmac_interrupt_t irq_type)
 HMAC interrupt force. More...
 
dif_hmac_result_t dif_hmac_mode_hmac_start (const dif_hmac_t *hmac, const uint8_t *key, const dif_hmac_transaction_t config)
 Resets the HMAC engine and readies it to receive a new message to process an HMAC digest. More...
 
dif_hmac_result_t dif_hmac_mode_sha256_start (const dif_hmac_t *hmac, const dif_hmac_transaction_t config)
 Resets the HMAC engine and readies it to receive a new message to process a SHA256 digest. More...
 
dif_hmac_fifo_result_t dif_hmac_fifo_push (const dif_hmac_t *hmac, const void *data, size_t len, size_t *bytes_sent)
 Attempts to send len bytes from the buffer pointed to by data to the device described by hmac. More...
 
dif_hmac_result_t dif_hmac_fifo_count_entries (const dif_hmac_t *hmac, uint32_t *num_entries)
 Retrieves the number of entries in the HMAC FIFO. More...
 
dif_hmac_result_t dif_hmac_get_message_length (const dif_hmac_t *hmac, uint64_t *msg_len)
 Retrieves the number of bits in the loaded HMAC device. More...
 
dif_hmac_result_t dif_hmac_process (const dif_hmac_t *hmac)
 Attempts to run HMAC or SHA256 depending on the mode hmac was initialized in. More...
 
dif_hmac_digest_result_t dif_hmac_finish (const dif_hmac_t *hmac, dif_hmac_digest_t *digest)
 Attempts to finish a transaction started with dif_hmac_mode_*_start, and reads the final digest in the buffer referenced by digest. More...
 
dif_hmac_result_t dif_hmac_wipe_secret (const dif_hmac_t *hmac, uint32_t entropy)
 Randomizes internal secret registers on the HMAC device. More...
 

Detailed Description

HMAC Device Interface Functions

Definition in file dif_hmac.h.


Data Structure Documentation

◆ dif_hmac_config

struct dif_hmac_config

Configuration for initializing the HMAC device.

Definition at line 143 of file dif_hmac.h.

Data Fields
mmio_region_t base_addr The base address for registers in the HMAC IP.

◆ dif_hmac_transaction

struct dif_hmac_transaction

Configuration for a single HMAC Transaction.

Definition at line 151 of file dif_hmac.h.

Data Fields
dif_hmac_endianness_t digest_endianness Byte endianness for reads from the digest.
dif_hmac_endianness_t message_endianness Byte endianness for writes to the FIFO.

◆ dif_hmac_digest

struct dif_hmac_digest

A typed representation of the HMAC digest.

Definition at line 161 of file dif_hmac.h.

Data Fields
uint32_t digest[8]

◆ dif_hmac

struct dif_hmac

State for a particular HMAC device.

Its member variables should be considered private, and are only provided so that callers can allocate it.

Definition at line 169 of file dif_hmac.h.

Data Fields
mmio_region_t base_addr

Typedef Documentation

◆ dif_hmac_enable_t

Generic enable/disable enumeration.

Enumeration used to enable/disable bits, flags, ...

◆ dif_hmac_interrupt_t

HMAC interrupt configuration.

Enumeration used to enable, disable, test and query the HMAC interrupts. Please see the comportability specification for more information: https://docs.opentitan.org/doc/rm/comportability_specification/

◆ dif_hmac_t

typedef struct dif_hmac dif_hmac_t

State for a particular HMAC device.

Its member variables should be considered private, and are only provided so that callers can allocate it.

Enumeration Type Documentation

◆ dif_hmac_digest_result

Error codes for reading the HMAC digest.

Enumerator
kDifHmacDigestOk 

No error occurred.

kDifHmacDigestError 

An unknown error occurred.

kDifHmacDigestBadArg 

An invalid argument was provided.

kDifHmacDigestProcessing 

The HMAC operation is still in progress.

Retryable. This error indicates HMAC is still processing and will finish in time. A function that returns this error may be retried at any time, or the caller may choose to do so when the kDifHmacInterruptHmacDone interrupt is raised, provided this interrupt has been enabled via the interrupt API.

Any function that returns this error is guaranteed to have not produced any side effects.

Definition at line 119 of file dif_hmac.h.

◆ dif_hmac_enable

Generic enable/disable enumeration.

Enumeration used to enable/disable bits, flags, ...

Enumerator
kDifHmacEnable 

Enable interrupt.

kDifHmacDisable 

Disable interrupt.

Definition at line 56 of file dif_hmac.h.

◆ dif_hmac_endianness

Supported byte endienness options.

Enumerator
kDifHmacEndiannessBig 

Big endian byte ordering.

kDifHmacEndiannessLittle 

Little endian byte ordering.

Definition at line 76 of file dif_hmac.h.

◆ dif_hmac_fifo_result

Error codes for HMAC FIFO operations that may fail.

Enumerator
kDifHmacFifoOk 

No error occurred.

kDifHmacFifoError 

An unknown error occurred.

kDifHmacFifoBadArg 

An invalid argument was provided.

kDifHmacFifoFull 

The FIFO filled up before the buffer was fully consumed.

Retryable. This error indicates that FIFO has filled up and will empty over time. A function that returns this error may be retried at any time, or the caller may choose to do so when the kDifHmacInterruptFifoEmpty interrupt is raised, provided this interrupt has been enabled via the interrupt API.

Definition at line 98 of file dif_hmac.h.

◆ dif_hmac_interrupt

HMAC interrupt configuration.

Enumeration used to enable, disable, test and query the HMAC interrupts. Please see the comportability specification for more information: https://docs.opentitan.org/doc/rm/comportability_specification/

Enumerator
kDifHmacInterruptHmacDone 

HMAC is done.

Associated with the hmac.INTR_STATE.hmac_done hardware interrupt.

kDifHmacInterruptFifoEmpty 

FIFO empty.

Associated with the hmac.INTR_STATE.fifo_empty hardware interrupt.

kDifHmacInterruptHmacErr 

HMAC error occurred.

Associated with the hmac.INTR_STATE.hmac_err hardware interrupt.

Definition at line 28 of file dif_hmac.h.

◆ dif_hmac_mode

Supported HMAC modes of operation.

Enumerator
kDifHmacModeHmac 

The HMAC mode.

kDifHmacModeSha256 

The SHA256-only mode.

Definition at line 66 of file dif_hmac.h.

◆ dif_hmac_result

Error codes for HMAC functions that may exhibit generic failures.

Enumerator
kDifHmacOk 

No error occurred.

kDifHmacError 

An unknown error occurred.

kDifHmacBadArg 

An invalid argument was provided.

Definition at line 86 of file dif_hmac.h.

Function Documentation

◆ dif_hmac_fifo_count_entries()

dif_hmac_result_t dif_hmac_fifo_count_entries ( const dif_hmac_t hmac,
uint32_t *  num_entries 
)

Retrieves the number of entries in the HMAC FIFO.

These entries may be semi-arbitrary in length; this function should not be used to calculate message length.

Parameters
hmacThe HMAC device to get the FIFO depth for.
[out]num_entriesThe number of entries in the FIFO.
Returns
kDifHmacBadArg if hmac or num_entries is null, kDifHmacOk otherwise.

Definition at line 364 of file dif_hmac.c.

◆ dif_hmac_fifo_push()

dif_hmac_fifo_result_t dif_hmac_fifo_push ( const dif_hmac_t hmac,
const void *  data,
size_t  len,
size_t *  bytes_sent 
)

Attempts to send len bytes from the buffer pointed to by data to the device described by hmac.

This function will send to the message FIFO until the FIFO fills up or len bytes have been sent.

In the event that the FIFO fills up before len bytes have been sent this function will return a kDifHmacFifoFull error. In this case it is valid to call this function again by advancing data by len - |*bytes_sent| bytes. It may be desirable to wait for space to free up on the FIFO before issuing subsequent calls to this function, but it is not strictly necessary. The number of entries in the FIFO can be queried with dif_hmac_fifo_count_entries().

data must point to an allocated buffer of at least length len.

Parameters
hmacThe HMAC device to send to.
dataA contiguous buffer to copy from.
lenThe length of the buffer to copy from.
[out]bytes_sentThe number of bytes sent to the FIFO (optional).
Returns
kDifHmacFifoFull if the FIFO fills up, kDifHmacFifoBadArg if hmac or data is null, and kDifHmacFifoOk otherwise.

Definition at line 323 of file dif_hmac.c.

◆ dif_hmac_finish()

dif_hmac_digest_result_t dif_hmac_finish ( const dif_hmac_t hmac,
dif_hmac_digest_t digest 
)

Attempts to finish a transaction started with dif_hmac_mode_*_start, and reads the final digest in the buffer referenced by digest.

This queries the INTR_STATE register to check if the HMAC is finished, and will acknowledge a hmac_done interrupt. If that register is not pending, then this function assumes HMAC is still processing and will return kDifHmacErrorDigestProcessing.

Once the digest has been read, the HMAC and SHA256 datapaths are disabled, clearing the digest registers.

digest must reference an allocated, contiguous, 32-byte buffer. This buffer shall also be 4-byte aligned. This is all consistent with the platform requirements for size and alignment requirements of dif_hmac_digest_t.

Parameters
hmacThe HMAC device to read the digest from.
[out]digestA contiguous 32-byte, 4-byte aligned buffer for the digest.
Returns
kDifHmacBadArg if hmac or digest is null, kDifHmacDigestProcessing if HMAC is still processing, and kDifHmacOk otherwise.

Definition at line 401 of file dif_hmac.c.

◆ dif_hmac_get_message_length()

dif_hmac_result_t dif_hmac_get_message_length ( const dif_hmac_t hmac,
uint64_t *  msg_len 
)

Retrieves the number of bits in the loaded HMAC device.

dif_hmac_fifo_count_entries() should be called before this function to ensure the FIFO is empty, as any bits in the FIFO are not counted in msg_len.

Parameters
hmacThe HMAC device to get the message length for.
[out]msg_lenThe number of bits in the HMAC message.
Returns
kDifHmacBadArg if hmac or msg_len is null, kDifHmacOk otherwise.

Definition at line 375 of file dif_hmac.c.

◆ dif_hmac_init()

dif_hmac_result_t dif_hmac_init ( const dif_hmac_config_t config,
dif_hmac_t hmac_out 
)

Initializes the HMAC device described by config, writing internal state to hmac_out.

This function must be called on a particular mmio_region_t before calling any other functions in this header with that mmio_region_t.

Parameters
configConfiguration supplied for initializing a particular device.
[out]hmac_outThe location at which to write HMAC state. This location must be valid to write to.
Returns
kDifHmacBadArg if config is null or contains illegal arguments or hmac_out is null, kDifHmacOk otherwise.

Definition at line 68 of file dif_hmac.c.

◆ dif_hmac_irq_control()

dif_hmac_result_t dif_hmac_irq_control ( const dif_hmac_t hmac,
dif_hmac_interrupt_t  irq_type,
dif_hmac_enable_t  enable 
)

HMAC interrupt control.

Enable/disable an HMAC interrupt specified in irq_type.

Parameters
hmacHMAC state data.
irq_typeHMAC interrupt type.
enableenable or disable the interrupt.
Returns
dif_hmac_result_t.

Definition at line 156 of file dif_hmac.c.

◆ dif_hmac_irq_force()

dif_hmac_result_t dif_hmac_irq_force ( const dif_hmac_t hmac,
dif_hmac_interrupt_t  irq_type 
)

HMAC interrupt force.

Force interrupt specified in irq_type.

Parameters
hmacHMAC state data.
irq_typeHMAC interrupt type to be forced.
Returns
dif_hmac_result_t.

Definition at line 180 of file dif_hmac.c.

◆ dif_hmac_irq_state_clear()

dif_hmac_result_t dif_hmac_irq_state_clear ( const dif_hmac_t hmac,
dif_hmac_interrupt_t  irq_type 
)

HMAC clear requested IRQ state.

Clear the state of the requested IRQ in irq_type. Primary use of this function is to de-assert the interrupt after it has been serviced.

Parameters
hmacHMAC state data.
irq_typeIRQ to be de-asserted.
Returns
dif_hmac_result_t.

Definition at line 109 of file dif_hmac.c.

◆ dif_hmac_irq_state_get()

dif_hmac_result_t dif_hmac_irq_state_get ( const dif_hmac_t hmac,
dif_hmac_interrupt_t  irq_type,
dif_hmac_enable_t state 
)

HMAC get requested IRQ state.

Get the state of the requested IRQ in irq_type.

Parameters
hmacHMAC state data.
irq_typeIRQ to get the state of.
[out]stateIRQ state passed back to the caller.
Returns
dif_hmac_result_t.

Definition at line 89 of file dif_hmac.c.

◆ dif_hmac_irqs_disable()

dif_hmac_result_t dif_hmac_irqs_disable ( const dif_hmac_t hmac,
uint32_t *  state 
)

HMAC disable interrupts.

Disable generation of all HMAC interrupts, and pass previous interrupt state in state back to the caller. Parameter state is ignored if NULL.

Parameters
hmacHMAC state data.
[out]stateIRQ state passed back to the caller.
Returns
'dif_hmac_result_t'.

Definition at line 127 of file dif_hmac.c.

◆ dif_hmac_irqs_restore()

dif_hmac_result_t dif_hmac_irqs_restore ( const dif_hmac_t hmac,
uint32_t  state 
)

HMAC restore IRQ state.

Restore previous HMAC IRQ state. This function is used to restore the HMAC interrupt state prior to dif_hmac_irqs_disable function call.

Parameters
hmacHMAC state data.
stateIRQ state to restore.
Returns
'dif_hmac_result_t'.

Definition at line 144 of file dif_hmac.c.

◆ dif_hmac_mode_hmac_start()

dif_hmac_result_t dif_hmac_mode_hmac_start ( const dif_hmac_t hmac,
const uint8_t *  key,
const dif_hmac_transaction_t  config 
)

Resets the HMAC engine and readies it to receive a new message to process an HMAC digest.

This function causes the HMAC engine to start its operation. After a successful call to this function, |dif_hmac_fifo_push()| can be called to write the message for HMAC processing.

This function must be called with a valid key that references a 32-byte, contiguous, readable region where the key may be copied from.

Parameters
hmacThe HMAC device to start HMAC operation for.
keyThe 256-bit HMAC key.
configThe per-transaction configuration.
Returns
kDifHmacBadArg if hmac or key is null, kDifHmacOk otherwise.

Definition at line 252 of file dif_hmac.c.

◆ dif_hmac_mode_sha256_start()

dif_hmac_result_t dif_hmac_mode_sha256_start ( const dif_hmac_t hmac,
const dif_hmac_transaction_t  config 
)

Resets the HMAC engine and readies it to receive a new message to process a SHA256 digest.

This function causes the HMAC engine to start its operation. After a successful call to this function, |dif_hmac_fifo_push()| can be called to write the message for SHA256 processing.

Parameters
hmacThe HMAC device to start SHA256 operation for.
configThe per-transaction configuration.
Returns
kDifHmacBadArg if hmac null, kDifHmacOk otherwise.

Definition at line 288 of file dif_hmac.c.

◆ dif_hmac_process()

dif_hmac_result_t dif_hmac_process ( const dif_hmac_t hmac)

Attempts to run HMAC or SHA256 depending on the mode hmac was initialized in.

Calls to this function always succeed and return without blocking. The caller can use dif_hmac_check_state() to check for errors and for the DIF_HMAC_DONE status before reading the digest with dif_hmac_digest_read().

Parameters
hmacThe HMAC device to initiate the run on.
Returns
kDifHmacBadArg if hmac is null kDifHmacOk otherwise.

Definition at line 391 of file dif_hmac.c.

◆ dif_hmac_wipe_secret()

dif_hmac_result_t dif_hmac_wipe_secret ( const dif_hmac_t hmac,
uint32_t  entropy 
)

Randomizes internal secret registers on the HMAC device.

This includes the key, hash value, and internal state machine. The value of entropy will be used to "randomize" the internal state of the HMAC device. See the HMAC IP documentation for more information: hw/ip/hmac/doc.

Parameters
hmacThe HMAC device to clobber state on.
entropyA source of randomness to write to the HMAC internal state.
Returns
kDifHmacBadArg if hmac is null kDifHmacOk otherwise.

Definition at line 438 of file dif_hmac.c.