Detailed Description

Security personalization sketch.

REVISION HISTORY

See git log (git log libraries/MySensors/examples/SecurityPersonalizer/SecurityPersonalizer.ino)

Definition in file SecurityPersonalizer.ino.

#include "sha204_library.h"
#include "sha204_lib_return_codes.h"
#include <MySensors.h>

Include dependency graph for SecurityPersonalizer.ino:

#define	MY_CORE_ONLY
	Make use of the MySensors framework without invoking the entire system.

#define	MY_HMAC_KEY 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00
	The user-defined HMAC key to use unless GENERATE_HMAC_KEY is set.

#define	MY_AES_KEY 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00
	The user-defined AES key to store in EEPROM unless GENERATE_AES_KEY is set.

#define	MY_SOFT_SERIAL 0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF
	The user-defined soft serial to use for soft signing unless GENERATE_SOFT_SERIAL is set.

#define	NO_SETTINGS_DEFINED
	Set when there are no config flags defined.

#define	GENERATE_KEYS_ATSHA204A
	Default settings for generating keys using ATSHA204A. More...

#define	GENERATE_KEYS_SOFT
	Default settings for generating keys using software. More...

#define	PERSONALIZE_ATSHA204A
	Default settings for personalizing an ATSHA204A. More...

#define	PERSONALIZE_SOFT
	Default settings for personalizing EEPROM for software signing. More...

#define	PERSONALIZE_SOFT_RANDOM_SERIAL
	This is an alternative to PERSONALIZE_SOFT which will also store a randomly generated serial to EEPROM in addition to the actions performed by PERSONALIZE_SOFT. Take note of the generated soft serial as it will be needed if you plan to use whitelisting. It should be unique for each node. More...

#define	USE_SOFT_SIGNING
	Uncomment this to generate keys by software and store them to EEPROM instead of ATSHA204A.

#define	LOCK_ATSHA204A_CONFIGURATION
	Uncomment this to enable locking the ATSHA204A configuration zone. More...

#define	SKIP_UART_CONFIRMATION
	Uncomment this for boards that lack UART. More...

#define	GENERATE_HMAC_KEY
	Uncomment this to generate a random HMAC key using ATSHA204A or software depending on USE_SOFT_SIGNING. More...

#define	STORE_HMAC_KEY
	Uncomment this to store HMAC key to ATSHA204A or EEPROM depending on USE_SOFT_SIGNING.

#define	GENERATE_AES_KEY
	Uncomment this to generate a random AES key using ATSHA204A or software depending on USE_SOFT_SIGNING. More...

#define	STORE_AES_KEY
	Uncomment this to store AES key to EEPROM.

#define	GENERATE_SOFT_SERIAL
	Uncomment this to generate a random serial number for software signing. More...

#define	STORE_SOFT_SERIAL
	Uncomment this to store the serial number to EEPROM.

#define	PRINT_DETAILED_ATSHA204A_CONFIG
	Uncomment to print the detailed ATSHA204A configuration.

#define	RESET_EEPROM_PERSONALIZATION
	Uncomment to reset the personalization data in EEPROM to 0xFF:es.

const int	sha204Pin = MY_SIGNING_ATSHA204_PIN
	The IO pin to use for ATSHA204A.

atsha204Class	sha204 (sha204Pin)
	atsha204Class

void	setup ()
	Sketch setup code (all personalization is done here as it is a run-once sketch) More...

void	loop ()
	Sketch execution code (unused) More...

Macro Definition Documentation

◆ GENERATE_AES_KEY

#define GENERATE_AES_KEY

Uncomment this to generate a random AES key using ATSHA204A or software depending on USE_SOFT_SIGNING.

Note: If not enabled, key defined by MY_AES_KEY will be used instead.

Definition at line 1866 of file SecurityPersonalizer.ino.

◆ GENERATE_HMAC_KEY

#define GENERATE_HMAC_KEY

Uncomment this to generate a random HMAC key using ATSHA204A or software depending on USE_SOFT_SIGNING.

Note: If not enabled, key defined by MY_HMAC_KEY will be used instead.

Definition at line 1864 of file SecurityPersonalizer.ino.

◆ GENERATE_KEYS_ATSHA204A

#define GENERATE_KEYS_ATSHA204A

Default settings for generating keys using ATSHA204A.

Note: The generated keys displayed in the serial log with this setting needs to be written down and transferred to all nodes this gateway will communicate with. This is mandatory for ALL nodes for encryption (AES key). For signing (HMAC key) it is only required for nodes that use signing. Typically you set the values for MY_HMAC_KEY and MY_AES_KEY.

Definition at line 1856 of file SecurityPersonalizer.ino.

◆ GENERATE_KEYS_SOFT

#define GENERATE_KEYS_SOFT

Default settings for generating keys using software.

Important
You will need to ensure MY_SIGNING_SOFT_RANDOMSEED_PIN is set to an unconnected analog pin in order to provide entropy to the software RNG if your hardware has no HWRNG.

Note: The generated keys displayed in the serial log with this setting needs to be written down and transferred to all nodes this gateway will communicate with. This is mandatory for ALL nodes for encryption (AES key). For signing (HMAC key) it is only required for nodes that use signing. Typically you set the values for MY_HMAC_KEY and MY_AES_KEY.

Definition at line 1857 of file SecurityPersonalizer.ino.

◆ GENERATE_SOFT_SERIAL

#define GENERATE_SOFT_SERIAL

Uncomment this to generate a random serial number for software signing.

Note: If not enabled, serial defined by MY_SOFT_SERIAL will be used instead.

Definition at line 1868 of file SecurityPersonalizer.ino.

◆ LOCK_ATSHA204A_CONFIGURATION

#define LOCK_ATSHA204A_CONFIGURATION

Uncomment this to enable locking the ATSHA204A configuration zone.

It is still possible to change the key, and this also enable random key generation.

Warning: BE AWARE THAT THIS PREVENTS ANY FUTURE CONFIGURATION CHANGE TO THE CHIP

Definition at line 1862 of file SecurityPersonalizer.ino.

◆ PERSONALIZE_ATSHA204A

#define PERSONALIZE_ATSHA204A

Default settings for personalizing an ATSHA204A.

It is assumed that you have updated MY_HMAC_KEY and MY_AES_KEY with the keys displayed when executing this sketch with GENERATE_KEYS_ATSHA204A or GENERATE_KEYS_SOFT defined.

Definition at line 1858 of file SecurityPersonalizer.ino.

◆ PERSONALIZE_SOFT

#define PERSONALIZE_SOFT

Default settings for personalizing EEPROM for software signing.

It is assumed that you have updated MY_HMAC_KEY and MY_AES_KEY with the keys displayed when executing this sketch with GENERATE_KEYS_ATSHA204A or GENERATE_KEYS_SOFT defined.

Definition at line 1859 of file SecurityPersonalizer.ino.

◆ PERSONALIZE_SOFT_RANDOM_SERIAL

#define PERSONALIZE_SOFT_RANDOM_SERIAL

This is an alternative to PERSONALIZE_SOFT which will also store a randomly generated serial to EEPROM in addition to the actions performed by PERSONALIZE_SOFT. Take note of the generated soft serial as it will be needed if you plan to use whitelisting. It should be unique for each node.

Note: This is only needed for targets that lack unique device IDs. The sketch will inform you if there is a need for generating a random serial or not. Check the "Hardware security peripherals" listing. If a target has a unique device ID and a serial in EEPROM, the serial in EEPROM will be used. If erased (replaced with FF:es) the unique device ID will be used instead.

Definition at line 1860 of file SecurityPersonalizer.ino.

◆ SKIP_UART_CONFIRMATION

#define SKIP_UART_CONFIRMATION

Uncomment this for boards that lack UART.

This will disable additional confirmation for actions that are non-reversible.

Important
For ATSHA204A, no confirmation will be required for locking any zones with this configuration! Also, if you generate keys on a board without UART, you have no way of determining what the key is unless it is stored in EEPROM.

Definition at line 1863 of file SecurityPersonalizer.ino.