Skip to content

API Reference

Complete reference for all EmbSec SDK functions, organized by module.

Core Functions

System Initialization

void embsec_init(void)
Initialize the EmbSec environment. Must be called before using any other SDK functions.

  • Configures system clock to 80MHz
  • Initializes UART0 for console I/O (115200 baud)
  • Sets up SysTick timer
  • Configures basic GPIO

bool embsec_is_initialized(void)
Check if EmbSec is initialized.

  • Returns: true if initialized, false otherwise

System Control

void embsec_system_reset(void)
Perform a software reset of the microcontroller.

void embsec_enable_interrupts(void)
Enable interrupts globally.

void embsec_disable_interrupts(void)
Disable interrupts globally.

static inline void embsec_memory_barrier(void)
Memory barrier to ensure all memory operations complete before continuing.

Timing

uint32_t embsec_get_tick_ms(void)
Get system tick count in milliseconds since boot.

void embsec_delay_ms(uint32_t ms)
Delay for specified milliseconds (blocking).

Version

const char *embsec_get_version(void)
Get SDK version string in format "major.minor.patch".

UART Functions

Basic I/O

void embsec_uart_init(void)
Initialize UART for console I/O (called by embsec_init()).

void embsec_putchar(int c)
Send a single character to UART.

int embsec_getchar(void)
Get a single character from UART (blocking).

bool embsec_kbhit(void)
Check if a character is available.

String I/O

void embsec_puts(const char *str)
Send a null-terminated string to UART.

char *embsec_gets(char *buffer, size_t size)
Get a line of input from UART.

  • Reads until newline or buffer full
  • Null-terminates the string
  • Newline not included in buffer
  • Returns: Pointer to buffer on success, NULL on error

Formatted I/O

int embsec_printf(const char *format, ...)
Printf-style formatted output.

  • Returns: Number of characters printed

int embsec_vprintf(const char *format, va_list args)
Vprintf-style formatted output.

  • Returns: Number of characters printed

Buffer Management

void embsec_uart_flush(void)
Flush UART transmit buffer (wait until all data transmitted).

void embsec_uart_clear(void)
Clear UART receive buffer (discard pending data).

GPIO Functions

Pin Configuration

void embsec_gpio_init(void)
Initialize GPIO for LEDs and switches (called by embsec_init()).

void embsec_gpio_config(char port, uint8_t pin, embsec_gpio_dir_t dir)
Configure a GPIO pin.

  • port: GPIO port ('A' through 'F')
  • pin: Pin mask (e.g., 0x01 for pin 0)
  • dir: Direction (EMBSEC_GPIO_INPUT or EMBSEC_GPIO_OUTPUT)

Pin Operations

void embsec_gpio_write(char port, uint8_t pin, bool value)
Write to a GPIO pin.

  • value: true for high, false for low

bool embsec_gpio_read(char port, uint8_t pin)
Read from a GPIO pin.

  • Returns: true if high, false if low

void embsec_gpio_toggle(char port, uint8_t pin)
Toggle a GPIO pin state.

LED Control

void embsec_led_set(uint8_t led, bool on)
Control onboard LEDs.

  • led: LED mask (EMBSEC_LED_RED, EMBSEC_LED_BLUE, EMBSEC_LED_GREEN)
  • on: true to turn on, false to turn off

void embsec_led_toggle(uint8_t led)
Toggle onboard LED state.

Switch Input

bool embsec_switch_read(uint8_t sw)
Read switch state.

  • sw: Switch mask (EMBSEC_SW1 or EMBSEC_SW2)
  • Returns: true if pressed, false if released

void embsec_switch_wait(uint8_t sw, uint32_t debounce_ms)
Wait for switch press with debouncing.

Timer Functions

Millisecond Timing

void embsec_timer_init(void)
Initialize timer subsystem (called by embsec_init()).

uint32_t embsec_millis(void)
Get milliseconds since system start (wraps after ~49 days).

bool embsec_timeout(uint32_t start_ms, uint32_t delay_ms)
Non-blocking delay check.

  • Returns: true if delay elapsed, false otherwise

uint32_t embsec_elapsed_ms(uint32_t start_ms)
Calculate elapsed time (handles wraparound).

Microsecond Timing

uint32_t embsec_micros(void)
Get microseconds since system start (wraps after ~71 minutes).

void embsec_delay_us(uint32_t us)
Delay for specified microseconds (blocking).

One-shot Timer

void embsec_timer_start(uint32_t ms, embsec_timer_callback_t callback)
Start a one-shot timer with callback.

void embsec_timer_stop(void)
Stop the one-shot timer.

bool embsec_timer_active(void)
Check if timer is active.

Performance Measurement

uint32_t embsec_perf_start(void)
Start performance counter.

  • Returns: Counter start value

uint32_t embsec_perf_end(uint32_t start)
End performance measurement.

  • Returns: Elapsed CPU cycles

uint32_t embsec_cycles_to_us(uint32_t cycles)
Convert CPU cycles to microseconds (assumes 80MHz).

Cryptographic Functions

SHA-256 Hashing

void embsec_sha256(const uint8_t *data, size_t len, uint8_t hash[32])
Calculate SHA-256 hash in one operation.

void embsec_sha256_init(embsec_sha256_ctx_t *ctx)
Initialize SHA-256 context for incremental hashing.

void embsec_sha256_update(embsec_sha256_ctx_t *ctx, const uint8_t *data, size_t len)
Update SHA-256 context with data.

void embsec_sha256_final(embsec_sha256_ctx_t *ctx, uint8_t hash[32])
Finalize SHA-256 hash.

HMAC

void embsec_hmac_sha256(const uint8_t *key, size_t key_len,
                        const uint8_t *data, size_t data_len,
                        uint8_t hmac[32])
Calculate HMAC-SHA256.

Utility Functions

void embsec_bytes_to_hex(const uint8_t *bytes, size_t len, char *hex)
Convert bytes to hexadecimal string.

  • Output buffer must be at least 2*len+1 bytes

int embsec_hex_to_bytes(const char *hex, size_t hex_len, uint8_t *bytes)
Convert hexadecimal string to bytes.

  • Returns: Number of bytes written, or -1 on error

void embsec_random_bytes(uint8_t *buffer, size_t len)
Generate cryptographically secure random bytes.

int embsec_crypto_memcmp(const void *a, const void *b, size_t len)
Constant-time memory comparison.

  • Returns: 0 if equal, non-zero if different

void embsec_secure_zero(void *ptr, size_t len)
Secure memory clearing (won't be optimized out).

Flag Functions

Flag Generation

void embsec_generate_flag(embsec_flag_t *flag, 
                          const uint8_t *lab_salt, 
                          size_t salt_len)
Generate cryptographically secure flag.

  • Uses hardware ID + timestamp + lab salt
  • Format: EMBSEC{hash_output}

void embsec_generate_flag_str(embsec_flag_t *flag, const char *salt_str)
Generate flag using string salt (convenience function).

Utility Functions

uint32_t embsec_get_hwid(void)
Get hardware ID (unique per device).

uint64_t embsec_get_timestamp(void)
Get timestamp in milliseconds since boot.

void embsec_print_flag(const embsec_flag_t *flag)
Print flag to console.

bool embsec_validate_flag_format(const char *flag_str)
Validate flag format (checks for EMBSEC{...}).

Constants and Macros

GPIO Pin Definitions

#define EMBSEC_LED_RED    0x02  // PF1
#define EMBSEC_LED_BLUE   0x04  // PF2  
#define EMBSEC_LED_GREEN  0x08  // PF3
#define EMBSEC_SW1        0x10  // PF4
#define EMBSEC_SW2        0x01  // PF0

Cryptographic Sizes

#define EMBSEC_SHA256_SIZE 32
#define EMBSEC_HMAC_SIZE   32
#define EMBSEC_FLAG_SIZE   32

Version Macros

#define EMBSEC_VERSION_MAJOR 1
#define EMBSEC_VERSION_MINOR 0
#define EMBSEC_VERSION_PATCH 0
#define EMBSEC_VERSION_STRING "1.0.0"

// Version checking
#define EMBSEC_VERSION_CHECK(major, minor, patch) ...

Type Definitions

GPIO Direction

typedef enum {
    EMBSEC_GPIO_INPUT = 0,
    EMBSEC_GPIO_OUTPUT = 1
} embsec_gpio_dir_t;

Timer Callback

typedef void (*embsec_timer_callback_t)(void);

Flag Structure

typedef struct {
    char value[EMBSEC_FLAG_SIZE + 1];
} embsec_flag_t;

SHA-256 Context

typedef struct embsec_sha256_ctx embsec_sha256_ctx_t;
(Opaque structure - implementation details hidden)