MySensors Library & Examples  2.3.2
SecurityPersonalizer.ino File Reference

Detailed Description

Security personalization sketch.

REVISION HISTORY

Definition in file SecurityPersonalizer.ino.

#include "sha204_library.h"
#include "sha204_lib_return_codes.h"
#include <MySensors.h>
+ Include dependency graph for SecurityPersonalizer.ino:

Go to the source code of this file.

#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 1864 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 1862 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 1854 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 1855 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 1866 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 1860 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 1856 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 1857 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 1858 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 1861 of file SecurityPersonalizer.ino.